diff --git a/workplans/kaizen-agentic-WP-0002-agency-framework.md b/workplans/kaizen-agentic-WP-0002-agency-framework.md new file mode 100644 index 0000000..eeac04a --- /dev/null +++ b/workplans/kaizen-agentic-WP-0002-agency-framework.md @@ -0,0 +1,259 @@ +# KAIZEN-WP-0002 — Agency Framework: Project Memory, Coaching, and sys-medic Integration + +**Status:** active +**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 + +- [ ] T01 — Copy `agent-sys-medic.md` into `agents/` with correct naming convention +- [ ] T02 — Add YAML frontmatter (`name`, `description`, `category: infrastructure`) +- [ ] 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) +- [ ] T04 — Add a source attribution comment referencing the sys-medic repo +- [ ] T05 — Validate agent loads correctly via `kaizen-agentic list` and `validate` +- [ ] 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** +- [ ] T07 — Write ADR: project memory convention (file location, structure, lifecycle) +- [ ] T08 — Implement `memory` CLI command group (show, init, brief, clear) +- [ ] T09 — Add session-start and session-close protocol sections to agent template / + contributor guide + +**Agent definition updates** +- [ ] 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) +- [ ] T11 — Update agent YAML frontmatter schema to include optional + `memory: enabled|disabled` field (default: enabled) + +**Coaching meta-agent** +- [ ] T12 — Write `agents/agent-coach.md` definition +- [ ] T13 — Wire `kaizen-agentic memory brief ` to invoke coach logic +- [ ] T14 — Add coach to agent registry and validate + +**Documentation** +- [ ] T15 — Write `docs/agency-framework.md` explaining the memory model, coach + agent, and deployment lifecycle +- [ ] 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** +- [ ] T17 — Write ADR: protocols artifact convention (location, structure, lifecycle) +- [ ] T18 — Create `agents/protocols/` directory with `README.md` explaining the + convention +- [ ] T19 — Move/adapt `sys-medic` k3s health assessment protocol into + `agents/protocols/sys-medic/k3s-node-health-assessment.md` + +**sys-medic memory integration** +- [ ] 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) +- [ ] T21 — Add `## Node Profiles`, `## Recurring Findings`, `## Cleared Issues` + extensions to sys-medic memory template +- [ ] T22 — Update sys-medic prompt to reference its protocol runbook when performing + structured assessments ("use the k3s protocol if available") + +**CLI integration** +- [ ] T23 — Add `kaizen-agentic protocols list [agent]` and + `kaizen-agentic protocols show ` commands +- [ ] T24 — Add protocol scaffolding to `kaizen-agentic memory init sys-medic` + +**Validation and documentation** +- [ ] 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 +- [ ] T26 — Update `docs/agency-framework.md` with protocols section +- [ ] 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. + +--- + +## 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