kaizen-agentic/workplans/kaizen-agentic-WP-0002-agency-framework.md

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:

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

Memory file structure:

---
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-start protocol (all agents):

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 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 <agent>      # Print agent memory for current project
kaizen-agentic memory init <agent>      # Scaffold empty memory file
kaizen-agentic memory brief <agent>     # Run coach, print orientation for agent
kaizen-agentic memory clear <agent>     # 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 <agent> 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/<name>/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/<agent-name>/<slug>.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:

## 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 -->

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 <agent> <slug> 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