kaizen-docs

Self-improving documentation for AI-assisted development teams.

Stop making the same mistakes twice. kaizen-docs installs a set of living markdown templates into your project that get smarter after every sprint. Your retros feed back into your docs, which feed back into your planning — creating a compounding improvement loop.

Works with Claude Code, Cursor, Windsurf, or any AI coding agent.

Sprint starts
    │
    ▼
┌─────────────────────────────┐
│  Read LESSONS.md            │ ◄── What went wrong before?
│  Read WAYS-OF-WORKING.md    │ ◄── How do we work?
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│  Build                      │
│  (follow QUALITY-GATES.md)  │ ◄── Checklists before "done"
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│  Retro                      │
│  (use RETRO-TEMPLATE.md)    │ ◄── What happened this sprint?
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│  Extract learnings          │
│  ├─ Append to LESSONS.md    │ ◄── Never delete, only append
│  ├─ Update WAYS-OF-WORKING  │ ◄── Always current best practice
│  ├─ Update QUALITY-GATES    │ ◄── New checks from new bugs
│  └─ Update AI-AGENT-PLAYBOOK│ ◄── Better AI instructions
└─────────────┬───────────────┘
              │
              ▼
        Next sprint starts
        with better docs ♻️

Quick Install

Option 1: npx (recommended)

npx kaizen-docs init

Option 2: Manual copy

git clone https://github.com/jrbrugger/kaizen-docs.git
cp kaizen-docs/templates/*.md your-project/docs/

Option 3: Claude Code skill

claude install-skill https://github.com/jrbrugger/kaizen-docs

Then use /kaizen in Claude Code to activate the self-improvement loop.

What's Inside

| File | Purpose | Update Rule | |---|---|---| | WAYS-OF-WORKING.md | How the team plans, builds, reviews, deploys | Edit in place — always reflects current practice | | LESSONS.md | Append-only log of mistakes and fixes | Append only — never delete a lesson | | QUALITY-GATES.md | Checklists before marking a phase done | Add gates when bugs slip through | | AI-AGENT-PLAYBOOK.md | Instructions for AI agents on the project | Update when AI patterns succeed or fail | | RETRO-TEMPLATE.md | Sprint retrospective template | Use as-is — creates sprint retro records | | SPRINT-PLAN-TEMPLATE.md | Sprint planning template | Use as-is — creates sprint plan records |

How the Self-Improvement Loop Works

1. Sprint planning — Read LESSONS.md to avoid past mistakes. Create a plan from SPRINT-PLAN-TEMPLATE.md.
2. During the sprint — Follow QUALITY-GATES.md before marking phases done. AI agents follow AI-AGENT-PLAYBOOK.md.
3. Sprint retro — Fill out RETRO-TEMPLATE.md with the team. Cluster what went well, what didn't, and why.
4. Extract learnings — The retro template has explicit instructions for updating each living doc:
   • Append new lessons to LESSONS.md (never delete)
   • Update WAYS-OF-WORKING.md with improved processes
   • Add new quality gates that would have caught this sprint's bugs
   • Update AI-AGENT-PLAYBOOK.md with better agent instructions

The key insight: LESSONS.md is append-only (you never lose history), while WAYS-OF-WORKING.md is edit-in-place (it always reflects current best practice). The retro is the trigger that updates both.

CLI Commands

# Install templates into your project
npx kaizen-docs init

# Create a new sprint retro file
npx kaizen-docs retro 3    # → docs/sprints/SPRINT-3-RETRO.md

# Create a new sprint plan file
npx kaizen-docs plan 4     # → docs/sprints/SPRINT-4-PLAN.md

Example: A Real Lesson Entry

### L003 — Deployed with stale environment variables
`#deploy` `#config`

- **What happened:** Production app connected to the staging database
  for 2 hours after deploy.
- **Why:** Environment variables were cached from a previous deploy.
  The deploy script didn't force a refresh.
- **Fix:** Redeployed with --force-env flag. Verified connection string
  in production logs.
- **Prevention rule:** Added to deploy quality gate: "Verify environment
  variables match target environment before deploy." Added automated
  env-var diff check to CI pipeline.

This entry lives forever in LESSONS.md. The prevention rule gets added to QUALITY-GATES.md. Next sprint, anyone deploying will see that gate — and the AI agent will too.

Philosophy

Kaizen (改善) — Japanese for "continuous improvement." Small, incremental changes that compound over time.

Most teams have retros. Most retros produce action items. Most action items are forgotten by Monday. kaizen-docs closes the loop by encoding retro outputs directly into the documents that developers and AI agents read every day.

Your docs get smarter. Your team gets faster. Your AI agents make fewer mistakes.

Who This Is For

• Solo builders who ship fast and want to stop repeating mistakes
• Small teams using AI coding agents who need shared context
• Anyone who believes documentation should be a living system, not a write-once artifact

Built by a solo builder who shipped an MVP in 2 days and wanted to never make the same mistake twice.

License

MIT