SCOPE

This file helps you quickly understand what this repository is about, when it is relevant, and when it is not. It is intentionally lightweight and may be incomplete.

One-liner

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

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; 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, 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 scripting with no need for structured agent guidance
Non-Claude-Code development environments
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; 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 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, 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; "agency" means memory + coaching, not autonomous orchestration

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

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]

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]

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]

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

7.3 KiB Raw Blame History