From 15f4cce23859921ad6ce09c12df42852da8d77ff Mon Sep 17 00:00:00 2001 From: Bernd Worsch Date: Wed, 18 Mar 2026 23:44:05 +0000 Subject: [PATCH] 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 --- README.md | 33 +++++-- docs/agency-framework.md | 182 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 210 insertions(+), 5 deletions(-) create mode 100644 docs/agency-framework.md diff --git a/README.md b/README.md index 57e19a9..0e3622b 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ # Kaizen Agentic -AI agent development framework embracing continuous improvement through specialized agents and comprehensive development workflows. +AI **agency** framework: 18 specialized agents that arrive in your project informed, learn from experience, and improve over time. -This project embraces the Japanese concept of "kaizen" (continuous improvement) applied to AI agent development. Every coding subagent becomes part of an optimization loop where performance is measured, patterns are analyzed, and specifications are refined over time. +kaizen-agentic provides two things: a library of agent instruction sets you deploy into projects, and an **agency framework** that gives those agents persistent memory and coordination. Agents accumulate project-scoped knowledge across sessions. A Coach meta-agent synthesises patterns across the entire fleet and briefs incoming agents on what to know first. + +This project embraces the Japanese concept of "kaizen" (continuous improvement) applied to AI agent development. Every agent becomes part of an optimization loop where performance is measured, patterns are analyzed, and knowledge is carried forward. ## Quick Start @@ -70,14 +72,31 @@ kaizen-agentic install keepaTodofile keepaChangelog tdd-workflow kaizen-agentic status ``` +## Agency Framework + +Agents deployed into a project 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 targeted orientation briefs for incoming agents. + +```bash +# Scaffold memory for an agent +kaizen-agentic memory init sys-medic + +# Brief an incoming agent using all existing project memories +kaizen-agentic memory brief tdd-workflow + +# Review an agent's accumulated knowledge +kaizen-agentic memory show project-management +``` + +See [docs/agency-framework.md](docs/agency-framework.md) for the full model. + ## Features -- **16+ Specialized Agents**: Project management, testing, code quality, documentation -- **CLI Tool**: Easy agent installation and management (`kaizen-agentic`) +- **18 Specialized Agents**: Project management, testing, code quality, infrastructure, meta +- **Agency Framework**: Project-scoped agent memory + Coach meta-agent for cross-agent synthesis +- **CLI Tool**: Easy agent installation, management, and memory commands (`kaizen-agentic`) - **Project Templates**: Pre-configured setups for different project types - **Claude Code Integration**: Seamless integration with Claude Code workflows - **Comprehensive Testing**: Full test coverage with multiple testing strategies -- **Standards Compliance**: Follows PythonVibes and industry best practices ## Available Agents @@ -101,6 +120,10 @@ kaizen-agentic status - **setupRepository**: Repository initialization and standards compliance - **claude-documentation**: Claude Code configuration and documentation - **tooling-optimization**: Repository tooling usage optimization +- **sys-medic**: Infrastructure health monitoring and diagnostics + +### Meta +- **coach**: Coaching meta-agent — reads all project agent memories, synthesises cross-agent briefs, and orients incoming agents [View complete agent list](docs/AGENT_DISTRIBUTION.md#agent-categories) diff --git a/docs/agency-framework.md b/docs/agency-framework.md new file mode 100644 index 0000000..0185706 --- /dev/null +++ b/docs/agency-framework.md @@ -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 + +``` +/.kaizen/agents//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: +project: +last_updated: +session_count: +--- + +## Project Context + + +## Accumulated Findings + + +## What Worked + + +## Watch Points + + +## Open Threads + + +## Session Log + +``` + +### Session Protocols + +**Session-start (all agents with `memory: enabled`):** + +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 (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 · · `. +3. Bump `last_updated` and `session_count`. + +--- + +## Agent YAML Frontmatter + +Each agent definition (`agents/agent-.md`) includes a YAML frontmatter block: + +```yaml +--- +name: +description: +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 +``` + +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 # Print agent memory for the current project +kaizen-agentic memory init # Scaffold an empty memory file +kaizen-agentic memory brief # Assemble orientation context for the coach +kaizen-agentic memory clear # 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//.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