docs(agency): add agency-framework.md and update README (WP-0002 T15-T16)
- Add docs/agency-framework.md: full explanation of the project memory model, session protocols, memory frontmatter field, CLI reference, coach meta-agent usage, and protocols preview (Part 3) - Update README: reposition as agency framework (not just agent library), add Agency Framework section with memory CLI examples, update feature list to 18 agents, add sys-medic and coach to agent listing Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
182
docs/agency-framework.md
Normal file
182
docs/agency-framework.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# 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 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-management
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Protocols (Part 3 — coming in WP-0002 Part 3)
|
||||
|
||||
A future extension adds **protocol runbooks** — structured, human-readable procedural checklists that agents can reference during structured assessments:
|
||||
|
||||
```
|
||||
agents/protocols/<agent-name>/<slug>.md
|
||||
```
|
||||
|
||||
The sys-medic k3s health assessment protocol is the first planned example. CLI commands `kaizen-agentic protocols list` and `protocols show` will expose them.
|
||||
|
||||
See [WP-0002](../workplans/kaizen-agentic-WP-0002-agency-framework.md) Part 3 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-management | 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 |
|
||||
|
||||
---
|
||||
|
||||
## Related Documents
|
||||
|
||||
- [ADR-001: Workplan Convention](../workplans/kaizen-agentic-WP-0001-community-engagement.md) — how work items are structured
|
||||
- [ADR-002: Project Memory Convention](../workplans/kaizen-agentic-WP-0002-agency-framework.md) — memory file location, structure, and lifecycle
|
||||
- [WP-0002: Agency Framework](../workplans/kaizen-agentic-WP-0002-agency-framework.md) — full implementation workplan
|
||||
Reference in New Issue
Block a user