coulomb/kaizen-agentic
2
0
Fork 0
Code Issues 4 Pull Requests Actions Projects Releases Wiki Activity

Added project documentation in wiki and established INTENT.md

Browse Source
This commit is contained in:
Bernd Worsch
2026-06-16 00:58:43 +02:00
parent 95b729cc53
commit 71ef5f4734
21 changed files with 1442 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

113
SCOPE.md
View File

@@ -8,87 +8,138 @@
## One-liner
AI agent development framework providing specialized agent personas (markdown instruction sets) and CLI scaffolding tools for embedding domain expertise into Claude Code sessions.
AI agency framework: specialized agent personas (markdown instruction sets), project-scoped memory, and CLI tooling for deploying informed agents into Claude Code sessions.
---
## Core Idea
Kaizen-agentic makes recurring development workflows (TDD, refactoring, project management, documentation) first-class by packaging them as named agent personas. You invoke an agent by name, load its instruction set, and follow it — the agent defines the workflow, Claude Code executes it. The "kaizen" (continuous improvement) philosophy means agents are refined based on performance over time.
Kaizen-agentic packages recurring development workflows (TDD, refactoring, project management, infrastructure health) as named agent personas you invoke in Claude Code. The agency layer adds **project-scoped memory** (`.kaizen/agents/<name>/memory.md`) so agents accumulate knowledge across sessions, plus a **Coach** meta-agent that synthesises cross-agent context for new deployments. The kaizen loop — measure, analyse, refine — is embodied in agent definitions and an `OptimizationLoop` Python pattern, even though runtime execution remains Claude's responsibility.
---
## In Scope
- 17+ agent definition files (`agents/agent-*.md`) — markdown persona instruction sets
- Agent categories: testing, quality, process, infrastructure, release, documentation
- CLI tooling: `kaizen-agentic init/install/status` for project scaffolding
- Project templates (python-basic, python-web, python-cli, python-data, comprehensive)
- Python framework: `Agent` base class, `AgentConfig` dataclass, `OptimizationLoop` for performance tracking
- Custodian MCP integration: `list_kaizen_agents()` and `get_kaizen_agent()` tools
- **21 agent definitions** (`agents/agent-*.md`) — markdown persona instruction sets with YAML frontmatter
- **Agent categories**: project-management, development-process, code-quality, infrastructure, testing, documentation, meta
- **Agency framework**: project memory convention, session-start/close protocols, Coach meta-agent (`agent-coach.md`)
- **Protocol runbooks** (`agents/protocols/<agent>/<slug>.md`) — procedural checklists distinct from agent prompts (sys-medic k3s assessment is the first example)
- **CLI tooling** (`kaizen-agentic`): `init`, `install`, `update`, `remove`, `list`, `status`, `validate`, `templates`, `detect`, `migrate`, `extensions`, `memory` (show/init/brief/clear), `protocols` (list/show)
- **Project templates** (python-basic, python-web, python-cli, python-data, comprehensive) — agent bundles defined in registry code, not separate template directories
- **Python framework** (`src/kaizen_agentic/`): `Agent`/`AgentConfig`, `AgentRegistry`, `AgentInstaller`, `OptimizationLoop`/`PerformanceMetrics`, detection/migration/extensions
- **Packaged agent data** (`src/kaizen_agentic/data/agents/`) — 17 agents bundled for pip installs (lags `agents/` by 4 agents; see Notes)
- **Custodian MCP integration** (owned by `the-custodian`): `list_kaizen_agents()` and `get_kaizen_agent()` resolve this repo via `host_paths`
- **ADRs and workplans** documenting memory, protocols, and workplan conventions
---
## Out of Scope
- Agent runtime / execution engine (agents are persona definitions; execution is Claude Code's responsibility)
- LLM orchestration or multi-agent debate systems
- Project-specific implementation (agents guide; they do not build the software)
- Commercial features or PyPI distribution (pre-v1.0)
- Agent runtime / execution engine (agents are persona definitions; Claude Code executes them)
- LLM orchestration, scheduling, or multi-agent debate systems
- Project-specific implementation (agents guide work; they do not build the target software)
- Custodian State Hub, MCP server code, or cross-domain governance (consumed, not owned)
- PyPI publication pipeline (v1.0.2 released locally; public PyPI distribution still pending)
---
## Relevant When
- Starting a guided development workflow (TDD, refactoring, testing, requirements)
- Scaffolding a new project with consistent structure and best-practice tooling
- Looking up what specialized agent personas are available for a domain session
- Contributing a new agent persona to the ecosystem
- Starting a guided development workflow (TDD, refactoring, testing, requirements, scope analysis)
- Deploying agents into a project with persistent cross-session memory
- Briefing a newly deployed agent using accumulated project knowledge (Coach / `memory brief`)
- Scaffolding a new project with consistent structure and agent bundles
- Looking up available agent personas (CLI, MCP, or `agents/` directory)
- Contributing or refining an agent persona or protocol runbook
---
## Not Relevant When
- Ad-hoc, one-off scripting with no need for structured guidance
- Ad-hoc scripting with no need for structured agent guidance
- Non-Claude-Code development environments
- Need for runtime orchestration or scheduling (not a scheduler)
- Need for runtime orchestration, task scheduling, or autonomous agent execution
- Repository capability profiling or SCOPE.md generation at scale (see `repo-scoping`)
---
## Current State
- Status: experimental → stabilizing (v1.0.2 released)
- Implementation: ~85% — 17 agents defined, CLI functional, templates working; optimization loop pattern established but not exercised at scale
- Stability: stable CLI and agent loading
- Usage: installed in dev projects; agents callable via Custodian MCP hub-wide
- Status: experimental → stabilizing (v1.0.2; agency framework shipped in WP-0002)
- Implementation: substantial — 21 agents, full CLI, agency memory + protocols tested e2e; optimization loop exists but is not exercised in production workflows
- Stability: CLI stable (Click workaround in place); agency framework validated by e2e tests
- Usage: internal dev projects and Custodian MCP hub-wide; packaged wheel missing 4 newest agents
- Active work: WP-0001 (community engagement / v1.1.0) — CI, telemetry, cross-platform fixes not started
---
## How It Fits
- Upstream dependencies: Claude Code (agent invocation), kaizen philosophy
- Downstream consumers: Custodian State Hub (loads agents via MCP); all six domains (teams use agents for guided workflows)
- Often used with: the-custodian (MCP integration), markitect_project (project-management agent), activity-core (scaffolding)
- Upstream dependencies: Claude Code (agent invocation), kaizen continuous-improvement philosophy
- Downstream consumers: Custodian State Hub (MCP agent discovery); domain repos that install agents and maintain `.kaizen/` memory
- Often used with: `the-custodian` (MCP integration), `markitect_project` (project-management patterns), `activity-core` (scaffolding references)
---
## Terminology
- Preferred terms: agent, agent persona, AgentConfig, project template
- Preferred terms: agent, agent persona, agency, project memory, protocol runbook, Coach
- Also known as: "kaizen agents", "the agent library"
- Potentially confusing terms: "Agent" here is a persona/instruction set, not a running process
- Potentially confusing terms: "Agent" here is a persona/instruction set, not a running process; "agency" means memory + coaching, not autonomous orchestration
---
## Related / Overlapping Repositories
- `the-custodian` — hosts MCP tools that load agents; custodian agent copies live in `the-custodian/agents/`
- `the-custodian` — hosts MCP tools that load agents; integration code lives there, not here
- `repo-scoping` — generates/refreshes SCOPE.md from approved characteristics; owns scope analysis at scale
- `markitect_project` — references kaizen-agentic as a capability submodule
- `sys-medic` (source repo) — origin of sys-medic agent; canonical copy now lives in `agents/agent-sys-medic.md`
---
## Getting Oriented
- Start with: `README.md` (quick start, agent list, installation)
- Key files / directories: `agents/` (all persona definitions), `src/kaizen_agentic/` (Python framework), `templates/` (project scaffolds)
- Entry points: `kaizen-agentic --help`; or via MCP: `get_kaizen_agent("scope-analyst")`
- Start with: `README.md` (quick start, agency overview), `docs/agency-framework.md` (memory + coach + protocols)
- Key files / directories: `agents/` (persona definitions), `agents/protocols/` (runbooks), `src/kaizen_agentic/` (Python framework), `workplans/` (active roadmap)
- Entry points: `kaizen-agentic --help`; via MCP: `get_kaizen_agent("scope-analyst")`; docs: `docs/GETTING_STARTED.md`, `docs/AGENT_DISTRIBUTION.md`
---
## Provided Capabilities
```capability
type: process
title: Guided development agent personas
description: Named markdown instruction sets for TDD, refactoring, documentation standards, requirements engineering, and project management workflows in Claude Code sessions.
keywords: [agents, personas, tdd, refactoring, claude-code, workflows]
```
```capability
type: infrastructure
title: Agent deployment and project scaffolding CLI
description: Install, update, validate, and bundle agents into new or existing projects via the kaizen-agentic CLI and registry-backed templates.
keywords: [cli, install, templates, scaffolding, registry]
```
```capability
type: process
title: Project-scoped agent memory and coaching
description: Convention and CLI for .kaizen/agents memory files, session protocols, and Coach-mediated orientation briefs across a deployed agent fleet.
keywords: [memory, coach, agency, kaizen, cross-session]
```
```capability
type: infrastructure
title: Kaizen agent discovery via Custodian MCP
description: Single source of truth for agent definitions consumed by the Custodian State Hub list_kaizen_agents and get_kaizen_agent tools.
keywords: [mcp, custodian, discovery, agent-library]
```
---
## Notes
- `agents/` (21 files) is the development source of truth; `src/kaizen_agentic/data/agents/` (17 files) is what pip installs ship — coach, sys-medic, scope-analyst, and optimization are not yet bundled
- `INTENT.md` is not present in this repo (see gap analysis against derived intent)
- `agent-optimization.md` and `agent-agent-optimization.md` both exist; naming overlap may confuse discovery