feat(workplan): KAIZEN-WP-0002 — agency framework and sys-medic integration
Three-part workplan (27 tasks) covering: - Part 1: sys-medic integration as standard kaizen-agentic agent (T01-T06) - Part 2: agency framework — project memory model, coaching meta-agent, and CLI memory command group (T07-T16) - Part 3: sys-medic extended with protocols runbook and node-profile memory, built on the Part 2 framework (T17-T27) Workstream registered in state-hub as kaizen-wp-0002-agency-framework. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
259
workplans/kaizen-agentic-WP-0002-agency-framework.md
Normal file
259
workplans/kaizen-agentic-WP-0002-agency-framework.md
Normal file
@@ -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:**
|
||||
```
|
||||
<project-root>/.kaizen/agents/<agent-name>/memory.md
|
||||
```
|
||||
|
||||
**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-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:
|
||||
|
||||
```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 -->
|
||||
```
|
||||
|
||||
### 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
|
||||
Reference in New Issue
Block a user