--- id: KAIZEN-WP-0002 type: workplan title: "Agency Framework: Project Memory, Coaching, and sys-medic Integration" domain: custodian repo: kaizen-agentic status: done owner: kaizen-agentic topic_slug: custodian state_hub_workstream_id: d82b5ec9-ee3c-4b3b-9a27-2e30ab3a8158 created: "2026-03-18" updated: "2026-03-19" --- # KAIZEN-WP-0002 — Agency Framework: Project Memory, Coaching, and sys-medic Integration **Status:** done **Owner:** kaizen-agentic **Repo:** kaizen-agentic ## Goal Evolve kaizen-agentic from a library of standalone agent instruction sets into a coherent **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 whole agent fleet. sys-medic is the first concrete integration that drives and validates the framework. --- ## Part 1 — Integrate sys-medic as a Standard kaizen-agentic Agent Minimal, no new conventions required. Get sys-medic into the library in the existing format. ### Tasks - [x] T01 — Copy `agent-sys-medic.md` into `agents/` with correct naming convention - [x] T02 — Add YAML frontmatter (`name`, `description`, `category: infrastructure`) - [x] T03 — Collapse to single prompt (remove the "Shorter version" section; the lean version can live as an inline note at the top of the full prompt) - [x] T04 — Add a source attribution comment referencing the sys-medic repo - [x] T05 — Validate agent loads correctly via `kaizen-agentic list` and `validate` - [x] T06 — Update CHANGELOG.md for the new agent addition ### Definition of done `kaizen-agentic list` shows `sys-medic` under `infrastructure`. Agent passes `kaizen-agentic validate`. No other conventions changed. --- ## Part 2 — Agency Framework: Project Memory and Coaching Meta-Agent ### Vision Each agent deployed into a project accumulates a **project-scoped memory** — a structured file written at session close and read at session start. A new **coaching meta-agent** reads across all agent memories in a project and produces an orientation brief for any newly deployed agent: what has been tried, what worked, what to watch out for. kaizen-agentic becomes an agency whose agents arrive in a project informed, not blank. ### Memory Model **Location convention:** ``` /.kaizen/agents//memory.md ``` **Memory file structure:** ```markdown --- agent: project: last_updated: session_count: --- ## Project Context ## Accumulated Findings ## What Worked ## Watch Points ## Open Threads ## Session Log ``` **Session-start protocol (all agents):** 1. Check for `.kaizen/agents//memory.md` in the project root 2. If present, read it before beginning work 3. Acknowledge the memory in the opening brief **Session-close protocol (all agents):** 1. Update `## Accumulated Findings`, `## What Worked`, `## Watch Points` as needed 2. Append one line to `## Session Log` 3. Bump `last_updated` and `session_count` ### Coaching Meta-Agent A new agent `agent-coach.md` (category: `meta`) that: - Reads all `.kaizen/agents/*/memory.md` files in a project - Synthesises a **cross-agent brief**: patterns common across agents, cross-domain risks, resource or architectural signals that multiple agents have flagged - Produces a **new-agent orientation**: targeted summary for a specific agent about to be deployed for the first time in this project - Can be invoked explicitly: *"Coach, brief the sys-medic agent on this project"* - Does not perform domain work itself — observes, synthesises, and advises The coaching agent also maintains its own memory file covering meta-level observations about how the agent fleet is functioning in the project. ### CLI Integration `kaizen-agentic` CLI gains a `memory` command group: ``` kaizen-agentic memory show # Print agent memory for current project kaizen-agentic memory init # Scaffold empty memory file kaizen-agentic memory brief # Run coach, print orientation for agent kaizen-agentic memory clear # Wipe memory (with confirmation) ``` ### Tasks **Memory convention and tooling** - [x] T07 — Write ADR: project memory convention (file location, structure, lifecycle) - [x] T08 — Implement `memory` CLI command group (show, init, brief, clear) - [x] T09 — Add session-start and session-close protocol sections to agent template / contributor guide **Agent definition updates** - [x] T10 — Add session-start and session-close protocol blocks to all existing agents that do session-bound work (project-management, tdd-workflow, requirements-engineering, scope-analyst, sys-medic) - [x] T11 — Update agent YAML frontmatter schema to include optional `memory: enabled|disabled` field (default: enabled) **Coaching meta-agent** - [x] T12 — Write `agents/agent-coach.md` definition - [x] T13 — Wire `kaizen-agentic memory brief ` to invoke coach logic - [x] T14 — Add coach to agent registry and validate **Documentation** - [x] T15 — Write `docs/agency-framework.md` explaining the memory model, coach agent, and deployment lifecycle - [x] T16 — Update README to reflect the agency positioning ### Definition of done - `.kaizen/agents//memory.md` convention documented in ADR - `memory` CLI commands implemented and tested - `agent-coach.md` loads, validates, and produces a coherent brief when invoked against a project with at least one populated agent memory file - At least one existing agent (project-management or tdd-workflow) updated with session protocols and tested end-to-end --- ## Part 3 — sys-medic with Protocols, Extended via Agency Framework With the memory framework in place (Part 2), extend sys-medic so it: - Accumulates project/node-specific operational knowledge across sessions - Integrates its companion protocols runbook as a managed artifact ### Protocols Runbook Convention A new optional artifact type alongside agent definitions: ``` agents/protocols//.md ``` Protocols are structured runbooks — reusable, parameterised inspection or remediation checklists that an agent can reference or hand off to the operator. They are NOT prompts. They are human-readable procedural documents produced or refined through agent sessions. The sys-medic k3s health assessment protocol is the first example. ### sys-medic Memory Extensions sys-medic's memory file gains an additional section beyond the base template: ```markdown ## Node Profiles ## Recurring Findings ## Cleared Issues ``` ### Tasks **Protocols convention** - [x] T17 — Write ADR: protocols artifact convention (location, structure, lifecycle) - [x] T18 — Create `agents/protocols/` directory with `README.md` explaining the convention - [x] T19 — Move/adapt `sys-medic` k3s health assessment protocol into `agents/protocols/sys-medic/k3s-node-health-assessment.md` **sys-medic memory integration** - [x] T20 — Add session-start and session-close protocol blocks to `agent-sys-medic.md` (extending the base protocol from Part 2 with the node-profile extensions) - [x] T21 — Add `## Node Profiles`, `## Recurring Findings`, `## Cleared Issues` extensions to sys-medic memory template - [x] T22 — Update sys-medic prompt to reference its protocol runbook when performing structured assessments ("use the k3s protocol if available") **CLI integration** - [x] T23 — Add `kaizen-agentic protocols list [agent]` and `kaizen-agentic protocols show ` commands - [x] T24 — Add protocol scaffolding to `kaizen-agentic memory init sys-medic` **Validation and documentation** - [x] T25 — End-to-end test: deploy sys-medic into a test project, run two simulated sessions, verify memory accumulates and coach produces a useful brief - [x] T26 — Update `docs/agency-framework.md` with protocols section - [x] T27 — Update sys-medic agent doc with memory and protocol references ### Definition of done - Protocol runbook lives in `agents/protocols/sys-medic/` - sys-medic memory template includes node-profile extensions - sys-medic session-start reads memory + references relevant protocol - sys-medic session-close updates node profiles and findings - Coach agent produces a brief for sys-medic that includes node-level context from memory - CLI exposes protocol listing and viewing --- ## Sequencing ``` Part 1 (T01–T06) ──→ Part 2 (T07–T16) ──→ Part 3 (T17–T27) ~1 session ~3–4 sessions ~2–3 sessions ``` Part 1 is independent and can ship immediately. Part 3 depends on Part 2's memory framework being in place. Parts 2 and 3 together define the agency model that can then be generalised to bring future agents (from other repos like sys-medic) into the framework at lower incremental cost. --- ## State Hub Task IDs | Code | UUID | |------|------| | T01 | 41c9380b-1337-4e6d-aa74-98cc527a7975 | | T02 | 4badb7bb-9a1f-49bf-b75c-bce98f3d5490 | | T03 | d94b305a-e542-4e0e-a29e-e07339baf000 | | T04 | 15f5521e-c111-4078-b781-54bc3e208d9a | | T05 | bfc1f741-ce12-42a1-832a-588549446692 | | T06 | 7c2f87b4-023d-455f-9874-ad920d7e15ab | | T07 | 822c5aae-482e-4eae-9abc-c36bec6b3316 | | T08 | 49b164e0-3620-431b-89a5-cc5c12b42825 | | T09 | 104181da-2c3b-4482-a472-5316ec1dba9e | | T10 | 3ff44d3b-507b-4ece-98b9-e06a808405f3 | | T11 | 763ff109-02e4-4817-9aef-b91539a8a010 | | T12 | 9455c6c2-67df-49cc-b6ae-e7b813799824 | | T13 | 7175a344-35ca-4d13-bfa5-3fb0888cb6d2 | | T14 | c040e902-a0d2-48ad-89e9-2890cdf6d9a6 | | T15 | 88380f99-4b3e-4369-ab19-9ac0730343f9 | | T16 | c5770067-08ee-4944-ba0f-366a19f0d581 | | T17 | 4814e450-0d74-4fe9-9f80-940eabde8339 | | T18 | a0e8ee82-4f10-4f0f-baa3-8a656e9b8539 | | T19 | 814dc6f9-8652-4d0e-8c83-c99881b752f1 | | T20 | d2255c79-c211-4cf7-aa3c-2750637b7dee | | T21 | 1f249dd4-a74c-4063-b0d2-fb67ec0902d5 | | T22 | 1ddd546a-7868-4d18-81b4-f5c1fd364afe | | T23 | e533358e-15c3-4273-98e0-0365ead78d6a | | T24 | 787b5d6a-9c51-4043-910e-02f085894dc5 | | T25 | 81c57475-a0c1-4636-9baf-b3c9675e218e | | T26 | d1bdff1e-4c06-4677-85d0-8e109c3fa1a2 | | T27 | b10462d3-eb79-4336-adea-e2df758eb91f | --- ## Notes - The `.kaizen/` directory in target projects is analogous to `.claude/` — a project-level configuration and state directory owned by the kaizen-agentic ecosystem - The coaching meta-agent draws conceptual inspiration from how the `project-management` agent already maintains session start/close protocols — that pattern is being generalised and made consistent across the fleet - Protocol runbooks (Part 3) are distinct from agent prompts: they are operational checklists for humans and agents to execute, not instruction sets for shaping AI behaviour