coulomb/kaizen-agentic
2
0
Fork 0
Code Issues 4 Pull Requests Actions Projects Releases Wiki Activity
Files
5cd3da3166c6474a4e5ea4c9840314134a2ab1b5
kaizen-agentic/SCOPE.md
tegwick bd74d7d122 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.
2026-06-16 01:34:13 +02:00

8.8 KiB
Raw Blame History

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)
  • 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 (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; 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

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)
  • 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 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: experimental → stabilizing (v1.0.2; agency framework shipped in WP-0002)
  • 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-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/ 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

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]

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
  • 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 View Git Blame Copy Permalink