coulomb/kaizen-agentic
2
0
Fork 0
Code Issues 4 Pull Requests Actions Projects Releases Wiki Activity
Files
d7a8357dbfb7168bd523deb4ecf1772c630a5841
kaizen-agentic/SCOPE.md
tegwick d7a8357dbf
Some checks failed
ci / test (3.12) (push) Has been cancelled
Details
ci / test (3.10) (push) Has been cancelled
Details
docs: refresh SCOPE.md for v1.1.0 and completed workplans 
Move Gitea PyPI to in-scope, mark WP-0001–0004 done, and note WP-0005
as the next planning target.
2026-06-16 02:19:48 +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)
  • 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: none — propose WP-0005 for v1.2.0 (doc sync, packaged fleet parity, adoption polish)

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/ (20 files) is the development source of truth; src/kaizen_agentic/data/agents/ (16 files) is what pip installs ship — coach, sys-medic, scope-analyst, and optimization are not yet bundled
  • 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