kaizen-agentic/SCOPE.md

# 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.
> For strategic purpose and boundaries, see `INTENT.md`.

---

## One-liner

KaizenAgentic: a digital talent agency framework — agent personas, project memory, measurable improvement loops, and CLI tooling for deploying continuously refining AI coding agents into Claude Code sessions.

---

## Core Idea

This repo is the canonical home for the **KaizenAgentic** operating model (`INTENT.md`, `wiki/`). It packages recurring development workflows as named agent personas invoked in Claude Code. The **agency layer** adds project-scoped memory (`.kaizen/agents/<name>/memory.md`) and a **Coach** meta-agent for cross-agent orientation. The **kaizen loop** — measure, analyse, refine — is defined in `wiki/` and partially implemented: `OptimizationLoop` exists in Python, but per-execution metrics collection and optimizer integration are in progress (WP-0003). Runtime execution remains Claude Code's responsibility.

---

## In Scope

- **Strategic framing**: `INTENT.md` (purpose, boundaries, design principles) and `wiki/` (mission, agent template, guidance model, brand/pricing)
- **20 agent definitions** (`agents/agent-*.md`) — markdown persona instruction sets with YAML frontmatter (reference fleet; see `INTENT.md` boundaries)
- **Agent categories**: project-management, development-process, code-quality, infrastructure, testing, documentation, meta
- **Agency framework**: project memory convention (ADR-002), session-start/close protocols, Coach meta-agent (`agent-coach.md`)
- **Protocol runbooks** (`agents/protocols/<agent>/<slug>.md`) — procedural checklists distinct from agent prompts
- **CLI tooling** (`kaizen-agentic`): `init`, `install`, `update`, `remove`, `list`, `status`, `validate`, `templates`, `detect`, `migrate`, `extensions`, `memory` (show/init/brief/clear), `protocols` (list/show); `metrics` commands planned in WP-0003
- **Project templates** (python-basic, python-web, python-cli, python-data, comprehensive) — agent bundles in registry code
- **Python framework** (`src/kaizen_agentic/`): `Agent`/`AgentConfig`, `AgentRegistry`, `AgentInstaller`, `OptimizationLoop`/`PerformanceMetrics`, detection/migration/extensions
- **Packaged agent data** (`src/kaizen_agentic/data/agents/`) — agents bundled for pip installs (sync with `agents/` via `make agents-update`)
- **Gitea PyPI publication** — `make publish-gitea`, tag-triggered `.gitea/workflows/publish-python-package.yml` (v1.1.0+)
- **Custodian MCP integration** (owned by `the-custodian`): `list_kaizen_agents()` and `get_kaizen_agent()`
- **ADRs and workplans** for memory, protocols, workplan, and metrics 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)
- Full KaizenGuidance codemod pipeline (vision in `wiki/KaizenGuidance.md`; not yet implemented)
- Public pypi.org distribution (optional; Coulomb Gitea registry is primary)

---

## Relevant When

- Understanding **why** KaizenAgentic exists and what it must not become (`INTENT.md`)
- Exploring the conceptual model: agent template, optimizer, guidance, composable capabilities (`wiki/`)
- Starting a guided development workflow (TDD, refactoring, testing, requirements, scope analysis)
- Deploying agents with persistent cross-session memory or Coach-mediated orientation
- Scaffolding projects with agent bundles; looking up personas via CLI or Custodian MCP
- Contributing agent personas, protocol runbooks, or improvement-loop conventions

---

## Not Relevant When

- Ad-hoc scripting with no need for structured agent guidance
- Non-Claude-Code development environments (primary target; patterns may transfer)
- 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: stabilizing (v1.1.0 published on Gitea PyPI; WP-0001–0004 completed)
- Strategic layer: `INTENT.md` and `wiki/` established; ecosystem integration docs in `wiki/EcosystemIntegration.md`
- Implementation: 20 agents, full CLI (`metrics`, `memory`, `feedback`), agency memory + ADR-004 metrics + optimizer wiring
- Stability: CLI stable (Click workaround in place); Gitea CI on main; publish workflow on `v*` tags
- Usage: internal dev projects and Custodian MCP hub-wide; pip install via Gitea extra index
- Active work: **WP-0005** (adoption polish, fleet parity, publish verification → v1.2.0)

---

## 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/` state
- Often used with: `the-custodian` (MCP integration), `markitect_project` (project-management patterns), `activity-core` (scaffolding references), `repo-scoping` (SCOPE.md generation)

---

## Terminology

- Preferred terms: KaizenAgentic (product), agent, agent persona, agency, project memory, protocol runbook, Coach, kaizen loop
- Also known as: "kaizen agents", "kaizen-agentic" (repo/package slug), "the agent library"
- Potentially confusing terms: "Agent" is a persona/instruction set, not a running process; "agency" means memory + coaching, not autonomous orchestration; repo slug `kaizen-agentic` vs product name `KaizenAgentic`

---

## Related / Overlapping Repositories

- `the-custodian` — hosts MCP tools that load agents; integration code lives there, not here
- `repo-scoping` — generates/refreshes SCOPE.md from approved characteristics
- `markitect_project` — references kaizen-agentic as a capability submodule
- `sys-medic` (source repo) — origin of sys-medic agent; canonical copy in `agents/agent-sys-medic.md`

---

## Getting Oriented

Read in this order for full context:

1. `INTENT.md` — stable purpose, boundaries, design principles
2. `wiki/KaizenAgenticMission.md` — product narrative and key components
3. `wiki/EcosystemIntegration.md` — how KaizenAgentic composes with adjacent repos
4. `wiki/KaizenAgentTemplate.md` — intended agent specification format
5. `README.md` — quick start and agency overview
6. `docs/agency-framework.md` — memory, coach, protocols, metrics (ADR-004)
7. `history/` — persisted assessments and gap analyses
8. `workplans/` — active implementation roadmap

Key directories: `wiki/` (conceptual model), `agents/` (personas), `agents/protocols/` (runbooks), `src/kaizen_agentic/` (Python framework), `docs/adr/` (conventions)

Entry points: `kaizen-agentic --help`; 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]
```

```capability
type: process
title: KaizenAgentic conceptual model and agent specification standards
description: Strategic framing, design principles, agent template, optimizer spec, and improvement philosophy via INTENT.md and wiki/.
keywords: [kaizen, intent, template, optimization, digital-talent-agency]
```

---

## Notes

- `agents/` (20 files) is the development source of truth; `src/kaizen_agentic/data/agents/` must stay in sync (enforced in WP-0005 T09–T10)
- Agent definitions use minimal frontmatter today; full `wiki/KaizenAgentTemplate.md` conformance is a maturity target, not current reality