kaizen
A Claude Code plugin that runs a full software delivery lifecycle — planning, design, implementation, code review, verification, acceptance, and knowledge maintenance — as one in-session orchestrator dispatching named specialist personas, with evidence checked at every gate instead of self-reported.
---
id: GUIDE-README
title: "[GUIDE] Kaizen"
type: GUIDE
status: Approved
owner: FlockFlow
priority: Medium
tags:
- documentation
- governance
depends_on:
- AGENTS.md
related:
- CHANGELOG.md
last_updated: 2026-07-24
---
Kaizen
A Claude Code plugin that runs a full software delivery lifecycle — planning, design, implementation, code review, verification, acceptance, and knowledge maintenance — as one in-session orchestrator dispatching named specialist personas, with evidence checked at every gate instead of self-reported.
Overview
Kaizen turns Claude Code into a structured software factory. Instead of one agent doing everything from memory, a run breaks the work into individually dispatched actions — requirements gathering, technical design, backend implementation, security review, test verification, and so on — each one going to a subagent wearing a specific persona (Business Analyst, Solution Architect, Backend Developer, Security Reviewer, QA Engineer...). The orchestrating session itself never writes the code or the design; it dispatches, then checks the evidence each dispatch produced against the actual acceptance criteria before moving on.
Kaizen is product-agnostic: it ships with no knowledge of any specific product's domain, folder names, or business rules. Point it at any git repository and it runs the same disciplined process.
Philosophy
A self-reported "done" is not evidence. Every checkpoint in a Kaizen run does two things, in order: confirm the required outputs actually exist as real files or content (mechanical, no judgment), then read that evidence against the accepted acceptance criteria (a factual call, not a quality re-score — the reviewer personas already provide that independence, since the code reviewer didn't write the code, the security reviewer didn't implement anything, and QA judges evidence it didn't produce). A claim with no evidence behind it never counts as passing, regardless of what result field is attached to it.
Commands
| Command | Runs | Ends with |
| --- | --- | --- |
| /develop <target> | One feature target through the full SDLC: planning → design → implementation (parallel tracks when genuinely independent) → code review → verification → acceptance → knowledge maintenance | A recorded outcome, then a process retrospective |
| /fix-bug <target> | One defect: reproduce → isolate the demonstrated root cause (in-session, one tested hypothesis at a time) → minimal fix → verify → review → accept → knowledge maintenance | A recorded outcome, then a process retrospective |
| /discover <target> | Requirements, and optionally a technical design, with no implementation | Recorded findings and an offer to continue into /develop |
Usage:
``
/develop Add CSV export to the invoices list
`
/fix-bug Login redirects to a blank page after password reset
`
/discover Whether we should support multi-currency invoicing
Each command resolves exactly one target first — if the request could mean more than one thing, or names nothing concrete, it stops and asks rather than guessing.
How a run works
One in-session delivery-lead persona orchestrates the whole run — it never gets dispatched itself, it is the orchestrating session. Each action in the sequence goes out as one Agent-tool call to a named specialist persona (subagent_type), carrying only the context that action needs and the required inputs/outputs quoted verbatim from the process definition. Every dispatch reports back a structured result — pass, pass_with_risks, blocked, or failure — with real evidence locations, never just a claim.
At each checkpoint, the delivery-lead loads the evidence-verification skill and judges the stretch in-session: no separate gate reviewer is dispatched. A live-appended journal records every dispatch, checkpoint decision, and human escalation as the run proceeds. When a decision would materially change scope, ownership, a security boundary, or the acceptance outcome, the run stops and asks — a blocking question is always relayed to the human verbatim, never answered on the requester's behalf.
A /develop or /fix-bug run closes with debrief, a propose-only persona that reads the run's own journal and proposes process improvements — never applying one without an explicit human decision.
Capabilities, not vendors
Kaizen never tells an agent to run a specific tool. It names the capability — Semantic Search, Structural Search, Text Search, Repository Discovery, Knowledge Retrieval, Execution, Context Optimization, Validation — and each capability resolves to whatever provider your environment actually has, with a fallback that is always available. A language server, an AST-pattern tool, or a token-filtering command proxy makes a run faster and cheaper when present; nothing breaks when it is absent.
The same principle applies to other plugins. Where an installed plugin already owns a rule, kaizen composes it instead of restating it — a dedicated over-engineering review pass, a compressed finding format, a deferred-shortcut ledger. Every one of those is optional, and a persona's own rules stand alone without it. Two limits are absolute: a composed skill shapes how work is expressed and never decides whether it passes, and no compression is ever applied to evidence — journals, run state, verification output, and security findings are recorded verbatim.
One file owns all of this: [skills/agent-conduct/agent-conduct.md](skills/agent-conduct/agent-conduct.md). It is the only place in the plugin where an outside tool or plugin is named, so adding support for a new provider is a one-file change.
Installation
Kaizen is a standard Claude Code plugin (commands/, agents/, skills/, hooks/, bin/) and this repository is also its own marketplace (.claude-plugin/marketplace.json). From inside Claude Code:
`
/plugin marketplace add BhangeeF16/kaizen
/plugin install kaizen@kaizen
See the [Claude Code plugin documentation](https://docs.claude.com/en/docs/claude-code/plugins) for the mechanics of plugin marketplaces, or add this repository's entry to another marketplace's own marketplace.json.
Requirements
- Claude Code installed.PATH
- A git repository for whatever project you point a command at (branches, worktrees, and commits are part of the delivery model — parallel implementation tracks use isolated worktrees, and the push-approval hooks operate on git state).
- Python 3 available on for the bundled bin/*.py scripts the hooks and skills invoke (no PowerShell, no other runtime dependency).
When to use / when not to
Use for: a real feature, a real defect, or a real requirements/design question where a disciplined, evidence-checked process is worth the overhead of dispatching specialist personas instead of one agent working from memory.
Don't use for: a single, well-scoped action you already know how to name (invoke that action's own skill directly, e.g. kaizen:review-diff, instead of a full command run); a trivial one-line change; a question that doesn't touch delivery at all.
Learn more
[AGENTS.md](AGENTS.md) is the full operating contract — the directory index, the orchestration model in detail, lifecycle statuses, retired-concept history, and every standing rule a session works under while inside this plugin. Read it before making any change to this plugin itself.
Author
FlockFlow
Version
See [.claude-plugin/plugin.json`](.claude-plugin/plugin.json).
Kaizen is a standard Claude Code plugin (commands/, agents/, skills/, hooks/, bin/) and this repository is also its own marketplace (.claude-plugin/marketplace.json). From inside Claude Code:
``
/plugin marketplace add BhangeeF16/kaizen
/plugin install kaizen@kaizen
See the [Claude Code plugin documentation](https://docs.claude.com/en/docs/claude-code/plugins) for the mechanics of plugin marketplaces, or add this repository's entry to another marketplace's own marketplace.json`.
- Claude Code installed.
- A git repository for whatever project you point a command at (branches, worktrees, and commits are part of the delivery model — parallel implementation tracks use isolated worktrees, and the push-approval hooks operate on git state).
- Python 3 available on PATH for the bundled bin/*.py scripts the hooks and skills invoke (no PowerShell, no other runtime dependency).