Document measurement loop plan and ecosystem integration strategy.
Persist INTENT and ecosystem assessments in history/, add ADR-004 for project metrics with Helix Forge correlation, and register WP-0003 and WP-0004 workplans with State Hub. Update SCOPE, README, and agency-framework docs to reflect the two-layer measurement model.
This commit is contained in:
82
SCOPE.md
82
SCOPE.md
@@ -3,33 +3,35 @@
|
||||
> 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
|
||||
|
||||
AI agency framework: specialized agent personas (markdown instruction sets), project-scoped memory, and CLI tooling for deploying informed agents into Claude Code sessions.
|
||||
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
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
- **21 agent definitions** (`agents/agent-*.md`) — markdown persona instruction sets with YAML frontmatter
|
||||
- **Strategic framing**: `INTENT.md` (purpose, boundaries, design principles) and `wiki/` (mission, agent template, guidance model, brand/pricing)
|
||||
- **21 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, 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
|
||||
- **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/`) — 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
|
||||
- **Packaged agent data** (`src/kaizen_agentic/data/agents/`) — 17 agents bundled for pip installs (lags `agents/` by 4; see Notes)
|
||||
- **Custodian MCP integration** (owned by `the-custodian`): `list_kaizen_agents()` and `get_kaizen_agent()`
|
||||
- **ADRs and workplans** for memory, protocols, workplan, and metrics conventions
|
||||
|
||||
---
|
||||
|
||||
@@ -39,25 +41,26 @@ Kaizen-agentic packages recurring development workflows (TDD, refactoring, proje
|
||||
- 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)
|
||||
- PyPI publication pipeline (v1.0.2 released locally; public PyPI distribution still pending)
|
||||
|
||||
---
|
||||
|
||||
## 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 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
|
||||
- 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
|
||||
- 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`)
|
||||
|
||||
@@ -66,43 +69,55 @@ Kaizen-agentic packages recurring development workflows (TDD, refactoring, proje
|
||||
## 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
|
||||
- Strategic layer: `INTENT.md` and `wiki/` established; orientation docs not yet fully linked
|
||||
- Implementation: substantial — 21 agents, full CLI, agency memory + protocols tested e2e; **measurement loop not closed** (no `.kaizen/metrics/`, optimizer unwired)
|
||||
- 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
|
||||
- Active work: **WP-0003** (measurement loop); **WP-0004** (ecosystem integration); WP-0001 (community engagement / v1.1.0) pending
|
||||
|
||||
---
|
||||
|
||||
## 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)
|
||||
- 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: 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
|
||||
- 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; owns scope analysis at scale
|
||||
- `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 now lives in `agents/agent-sys-medic.md`
|
||||
- `sys-medic` (source repo) — origin of sys-medic agent; canonical copy 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`
|
||||
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`
|
||||
|
||||
---
|
||||
|
||||
@@ -136,10 +151,17 @@ description: Single source of truth for agent definitions consumed by the Custod
|
||||
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/` (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
|
||||
- `agent-optimization.md` and `agent-agent-optimization.md` both exist; consolidation planned in WP-0003
|
||||
- Agent definitions use minimal frontmatter today; full `wiki/KaizenAgentTemplate.md` conformance is a maturity target, not current reality
|
||||
Reference in New Issue
Block a user