kaizen-agentic/docs/agency-framework.md

# Agency Framework

kaizen-agentic is not just a library of agent instruction sets — it is an **agency**: a system where agents are deployed into projects with their own persistent memory, learn from experience, and are guided by a coaching meta-agent that distils patterns across the entire fleet.

## Overview

When you deploy a kaizen-agentic agent into a project, it can accumulate **project-scoped memory** — a structured file written at session close and read at session start. A **Coach** meta-agent reads across all agent memories and produces orientation briefs for newly deployed agents: what has been tried, what worked, what to watch out for.

Agents arrive in a project informed, not blank.

---

## Project Memory

### Location Convention

```
<project-root>/.kaizen/agents/<agent-name>/memory.md
```

The `.kaizen/` directory is analogous to `.claude/` — a project-level configuration and state directory owned by the kaizen-agentic ecosystem.

### Memory File Structure

```markdown
---
agent: <name>
project: <project-root or slug>
last_updated: <ISO date>
session_count: <n>
---

## Project Context
<!-- What this agent knows about the project it is working in -->

## Accumulated Findings
<!-- Patterns, recurring issues, key decisions the agent has encountered -->

## What Worked
<!-- Approaches that produced good results in this project -->

## Watch Points
<!-- Recurring risks, traps, or areas requiring extra care -->

## Open Threads
<!-- Things noticed but not yet acted on -->

## Session Log
<!-- One-line entry per session: date · summary · outcome -->
```

### Session Protocols

**Session-start (all agents with `memory: enabled`):**

1. Check for `.kaizen/agents/<name>/memory.md` in the project root.
2. If present, read it before beginning work.
3. Acknowledge the memory in the opening brief.

**Session-close (all agents with `memory: enabled`):**

1. Update `## Accumulated Findings`, `## What Worked`, `## Watch Points` as appropriate.
2. Append one line to `## Session Log`: `YYYY-MM-DD · <summary> · <outcome>`.
3. Bump `last_updated` and `session_count`.

---

## Agent YAML Frontmatter

Each agent definition (`agents/agent-<name>.md`) includes a YAML frontmatter block:

```yaml
---
name: <name>
description: <one-line description>
category: <category>
memory: enabled   # or: disabled
---
```

The `memory` field defaults to `enabled`. Set `memory: disabled` for agents that are stateless by design (e.g. `wisdom-encouragement`).

The file name must follow `agent-<name>.md` where `<name>` equals the frontmatter
`name`. `kaizen-agentic validate` enforces the frontmatter schema (required
fields, known `category`, valid `memory`/`model`).

### Authoring and doc sync (WP-0007)

```bash
kaizen-agentic create-agent <name> -c <category> -d "<description>"
kaizen-agentic validate                 # schema + dependency checks
kaizen-agentic docs generate            # refresh CLAUDE.md Installed Agents
make agents-sync-package                # keep packaged data/agents/ in parity
```

`create-agent` writes a schema-valid skeleton; `docs generate` rewrites the
project `## Installed Agents` section **idempotently** (use `--check` as a CI
gate). The section is grouped by the declared frontmatter `category`.

---

## The Coach Meta-Agent

`agents/agent-coach.md` is a **meta-agent** — it performs no domain work (coding, testing, infrastructure). Its sole purpose is synthesis and advice.

### What the Coach Does

- **Cross-agent synthesis**: reads all `.kaizen/agents/*/memory.md` files, identifies shared patterns, cross-domain risks, and contradictions
- **New-agent orientation**: when briefing a specific agent, filters all existing memories for what is relevant and produces a targeted brief
- **Fleet health overview**: summarises which agents are active, stale, or missing; flags high-session-count agents with open threads

### Invoking the Coach

**Via CLI (assembles raw memory context):**

```bash
kaizen-agentic memory brief <agent-name>
```

This prints a structured orientation brief. Pass the output to a Claude session with `agents/agent-coach.md` loaded for full LLM synthesis.

**Directly in a Claude session:**

```
Coach, brief the sys-medic agent on this project.
Coach, what patterns have you observed across all agents?
```

The Coach maintains its own memory at `.kaizen/agents/coach/memory.md` covering fleet-level observations over time.

---

## CLI Reference

The `memory` command group manages project-scoped agent memory:

```
kaizen-agentic memory show <agent>      # Print agent memory for the current project
kaizen-agentic memory init <agent>      # Scaffold an empty memory file
kaizen-agentic memory brief <agent>     # Assemble orientation context for the coach
kaizen-agentic memory clear <agent>     # Wipe memory (with confirmation prompt)
```

### Options

`memory brief` accepts:
- `--target / -t` — project root (default: current directory)
- `--raw` — dump raw memory file contents without the structured header

### Example Workflow

```bash
# First deployment of sys-medic into a project
kaizen-agentic memory init sys-medic

# After a few sessions, brief an incoming tdd-workflow agent
kaizen-agentic memory brief tdd-workflow
# → paste output into Claude with agent-coach.md loaded

# Review accumulated memory for a specific agent
kaizen-agentic memory show project-assistant
```

---

## Protocol Runbooks

Agents can reference **protocol runbooks** — structured, human-readable procedural checklists for structured assessments or remediation work. Protocols are distinct from agent prompts:

- **Agent prompts** (`agents/agent-*.md`) shape AI behaviour
- **Protocols** (`agents/protocols/<agent>/<slug>.md`) are procedural documents for humans and agents to execute

### Location Convention

```
agents/protocols/
  <agent-name>/
    <slug>.md    ← one file per protocol
```

### Protocol Frontmatter

Each protocol file has a YAML frontmatter block:

```yaml
---
agent: <agent-name>
slug: <slug>
title: <human-readable title>
version: 1.0.0
last_updated: "<ISO date>"
---
```

### Referencing Protocols from Agents

Agents with `memory: enabled` check for relevant protocols at session start and reference them in their session-start protocol block. For example, sys-medic's session-start protocol instructs:

> *"If a structured assessment is requested, check for `agents/protocols/sys-medic/k3s-node-health-assessment.md` and use it as your procedure."*

### CLI Reference

```bash
kaizen-agentic protocols list                        # List all protocols
kaizen-agentic protocols list sys-medic              # Filter by agent
kaizen-agentic protocols show sys-medic k3s-node-health-assessment
```

### sys-medic Memory and Protocols Integration

sys-medic extends the base memory template with three additional sections for operational continuity across sessions:

```markdown
## Node Profiles
<!-- Per-node operational baseline established over sessions -->
<!-- hostname | typical load | known quirks | last assessment date -->

## Recurring Findings
<!-- Issues seen more than once: pattern · first seen · frequency -->

## Cleared Issues
<!-- Issues that were resolved: what was done · when · outcome -->
```

These sections are maintained automatically by the sys-medic session-close protocol.

The **k3s Node Health Assessment** (`agents/protocols/sys-medic/k3s-node-health-assessment.md`) is the first protocol runbook — a step-by-step procedure covering OS baseline, process hygiene, memory, CPU, disk, network, Kubernetes node state, and k3s runtime health.

### Available Protocols

| Agent | Protocol | Description |
|-------|----------|-------------|
| sys-medic | [k3s-node-health-assessment](../agents/protocols/sys-medic/k3s-node-health-assessment.md) | Structured k3s node health check |

See [ADR-003: Protocols Artifact Convention](adr/ADR-003-protocols-artifact-convention.md) for the full specification.

---

## Agents with Memory Enabled

All agents that do session-bound project work have `memory: enabled` in their frontmatter and include session-start/session-close protocol blocks:

| Agent | Category | Notes |
|-------|----------|-------|
| project-assistant | process | Reference implementation of the session protocol pattern |
| tdd-workflow | testing | |
| requirements-engineering | process | |
| scope-analyst | process | |
| sys-medic | infrastructure | Extended memory template (node profiles, recurring findings) |
| coach | meta | Fleet-level memory |

---

## Project Metrics

Project-scoped **quantitative** metrics complement qualitative memory (ADR-002).
Per-execution records live under `.kaizen/metrics/<agent>/` and feed the
kaizen optimizer loop.

### Location

```
<project-root>/.kaizen/metrics/<agent-name>/
  executions.jsonl
  summary.json

<project-root>/.kaizen/metrics/optimizer/
  analysis.json
  recommendations.jsonl
```

### CLI (WP-0003)

```
kaizen-agentic metrics record <agent>   # Append execution record at session close
kaizen-agentic metrics show <agent>     # Summary + recent executions
kaizen-agentic metrics list             # Agents with metrics in project
kaizen-agentic metrics export <agent>   # Dump executions.jsonl
kaizen-agentic metrics optimize [agent] # Run optimizer on project metrics (≥10 records)
kaizen-agentic metrics correlate <uid>  # Helix Forge digest lookup (read-only)
kaizen-agentic metrics publish          # Register optimizer output in artifact-store
```

`memory brief` includes a `## Performance Summary` when metrics exist (success
rate, avg quality, execution time, trend arrows).

`memory init` scaffolds `.kaizen/metrics/<agent>/` by default (`--no-metrics` to
skip). Record outcomes at session close per
[session-close protocol template](templates/session-close-protocol.md).

### Fleet correlation

Project metrics correlate with **Helix Forge** fleet session metrics in
`agentic-resources` via optional `helix_session_uid` (ADR-004).

- `HELIX_SESSION_UID` (and related env vars) auto-merge on `metrics record`
- `metrics correlate <uid>` looks up fleet digest when `HELIX_STORE_DB` is set

See [integrations/helix-forge-correlation.md](integrations/helix-forge-correlation.md)
and [wiki/EcosystemIntegration.md](../wiki/EcosystemIntegration.md).

### Evidence retention

After `metrics optimize`, optionally publish optimizer outputs to **artifact-store**:

```bash
export ARTIFACTSTORE_API_URL=http://127.0.0.1:8000
export ARTIFACTSTORE_API_TOKEN=<write-token>
kaizen-agentic metrics publish --target .
```

Package uses `retention_class: raw-evidence` (180d). Local
`.kaizen/metrics/optimizer/` remains authoritative when publish is skipped.

Manifest: [integrations/optimizer-artifact-manifest.md](integrations/optimizer-artifact-manifest.md).

---

## Scheduled Agent Execution

Agents can run on a **regular cadence** against **preselected repos**, fired by
**activity-core** and prepared by kaizen-agentic (ADR-005). A repo opts in by
committing `.kaizen/schedule.yml`:

```bash
kaizen-agentic schedule init       # scaffold (coach + optimization weekly)
kaizen-agentic schedule validate   # check schema + agent names
kaizen-agentic schedule list       # show enabled entries
kaizen-agentic schedule prepare coach   # orientation bundle for a scheduled run
```

`schedule prepare <agent>` bundles the agent prompt, project memory, metrics
summary, and repo pointers — offline, no State Hub required. kaizen-agentic does
**not** run cron, own durable work, or invoke an LLM. activity-core fires the
schedule and creates `ops_run` work. Task intake remains rein-local where
implemented. The blueprint/instance supplies a versioned
`harness_profile_ref`; Glas resolves the concrete rein, model route, sandbox,
tool policy, and limits and returns normalized evidence. Manual sessions remain
a supported fallback.

Schema: [integrations/schedule-schema.md](integrations/schedule-schema.md).

---

## Related Documents

- [ADR-001: Workplan Convention](adr/ADR-001-workplan-convention.md)
- [ADR-002: Project Memory Convention](adr/ADR-002-project-memory-convention.md)
- [ADR-003: Protocols Artifact Convention](adr/ADR-003-protocols-artifact-convention.md)
- [ADR-004: Project Metrics Convention](adr/ADR-004-project-metrics-convention.md)
- [ADR-005: Scheduled Agent Execution](adr/ADR-005-scheduled-agent-execution.md)
- [ADR-006: Customer Engagement Convention](adr/ADR-006-customer-engagement-convention.md)
- [ADR-007: Forward-Deployed Engagement Convention](adr/ADR-007-forward-deployed-engagement-convention.md)
- [Forward-Deployed Engagement Architecture](forward-deployed-engagement-architecture.md) — client-requestable Roles, ramp-up/down, client vaults
- [Forward-Deployed Engagement Playbook](integrations/forward-deployed-engagement-playbook.md)
- [DEC-FDA-001 working defaults](decisions/DEC-FDA-001-working-defaults.md)
- [roles/host-operator](../roles/host-operator/) — first Role package (pilot)
- [engagements/pilots/eng-coulomb-railiance01-ho-001](../engagements/pilots/eng-coulomb-railiance01-ho-001/) — Phase 1 pilot tree
- [wiki/ForwardDeployedAgencyBusinessModel.md](../wiki/ForwardDeployedAgencyBusinessModel.md) — Kai trial currency, seats/duties, confidentiality
- [wiki/EcosystemIntegration.md](../wiki/EcosystemIntegration.md) — two-layer measurement model
- [WP-0002: Agency Framework](../workplans/KAIZEN-WP-0002-agency-framework.md)
- [WP-0003: Measurement Loop](../workplans/KAIZEN-WP-0003-measurement-loop.md)
- [WP-0004: Ecosystem Integration](../workplans/KAIZEN-WP-0004-ecosystem-integration.md)