Claude Code Workflow

A nine-agent development team. PM proposes, QA challenges, five technical agents build. You invoke and validate.

April 2026 context

Anthropic shipped a lot this quarter — managed agents, remote operations from your phone, dynamic scheduled tasks for monitoring without leaving your session. This repo assembles those pieces into a working multi-agent development team you can clone today, inspect end-to-end, and adapt to your project.

Why this exists

The human only does two things: invoke and validate. Everything else is encoded in skills.

Without structure, three things happen when you build with Claude Code:

1. Claude drifts. Long conversations get compacted, instructions disappear, code stops respecting standards.
2. There's no traceability. Every session is an island. You lose track of what was decided, why, and where you are.
3. Quality is not systematic. The temptation is build → ship without review or tests.

Engineers solved how to structure work decades ago — sprints, planning, review, retrospectives, the discipline that DevOps culture put in place. We didn't invent a new method for AI. We taught the AI how to follow ours. The repository below is the result of two months of running structured AI-assisted development on a real production project. If you find yourself copy-pasting prompts or manually dictating steps to Claude, that's a workflow bug. It should be in a skill.

Proof

The full version history with verifiable commit SHAs is in CHANGELOG.md. Every claim is backed by git history you can audit.

Hotfix v3.5.1 — two bugs surfaced when the strategic-pm ran an autonomous sprint: an ambiguous session semantic and a silent plan mode failure. Both were discovered during the workflow's own usage on 2026-04-11 and fixed before public release. The workflow caught its own bugs in production. That's the point.

v4.0.0 — May 2026 — five months of dogfooding surfaced four incident patterns that v3.x didn't prevent: agents overwriting uncommitted work, PMs auto-merging without manual smoke checks, sparse wrap-ups hiding blockers, auto-routing CI failures over pre-existing debt. v4.0 closes these gaps with two new PreToolUse hooks (block_wiki_write.py, protect-uncommitted-hook.py), a strategic-pm V2 that stops at the merge gate and persists state across sessions, and an archive convention for sprints/backlog. See CHANGELOG.md and docs/MIGRATION-v4.md.

The team

Three strategic agents run the cycle. Five technical agents do the building.

Strategic layer (activate after 3+ manual sprints):

The rule: no agent reviews its own output. PM and QA are in adversarial relationship by design. Three rounds of disagreement, then it escalates to you.

Technical layer (available from sprint 1):

All agents have memory: project enabled — they accumulate knowledge about the codebase, past decisions, and recurring patterns across sessions.

How it works

Each phase runs in its own isolated claude -p session — not a human approval gate, a technical boundary. Build context biases review; separate sessions give a fresh perspective. A full sprint in one session saturates context past ~60% and degrades quality.

Three sprint types:

• Hotfix — /build → deploy. Production bug, urgency, fewer than 3 files.
• Normal — /sprint-plan → /build → /review → /fix → /capture-lessons.
• Security — Full cycle with /red-team. Auth changes, payments, pre-release.

Manual mode: you invoke each skill, validate the result, invoke the next.

Autonomous mode: claude --agent=strategic-pm — the PM chains all phases without your intervention. The QA reviews every sprint independently. You validate the final PR.

The whole picture

Three diagrams above showed the parts: the agent team, the sprint cycle, the anti-sycophancy guard. This one shows them stacked together — the human at the top driving direction, the strategic agents orchestrating, the security layers underneath, and the wiki feeding context. Useful when you've already met each piece individually and want to see how they compose.

Quick start

Prerequisites: Claude Code installed and authenticated.

git clone https://github.com/rbah31/claude-code-workflow.git my-project
cd my-project
rm -rf .git && git init

# Personalize
# 1. Edit .claude/CLAUDE.md — your project's vision, stack, conventions
# 2. Edit .claude/rules/general.md — your code conventions
# 3. Add items to tasks/backlog.md

claude
> /doctor
> /context

First sprint:

> /sprint-plan

Validate the plan, then invoke /build, /review, /fix, and /capture-lessons in sequence.

Autonomous mode (after 3+ manual sprints):

claude --agent=strategic-pm

The PM reads briefs/direction.md, proposes a sprint, and orchestrates the full cycle without intervention between phases.

What's in the repo

claude-code-workflow/
├── .claude/
│   ├── CLAUDE.md              # Project source of truth (~100 lines)
│   ├── settings.json          # Hooks, permissions, deny-list (31 patterns)
│   ├── agents/                # 9 specialized agents with persistent memory
│   ├── skills/                # 19 skills (sprint cycle + extensions)
│   └── rules/                 # Path-scoped conventions
├── briefs/                    # Strategic agent shared memory
├── docs/
│   ├── WORKFLOW.md            # Complete workflow documentation
│   ├── SECURITY.md            # 6-layer defense architecture
│   └── REFERENCES.md          # External resources
├── tasks/
│   ├── backlog.md             # Your product backlog
│   └── sprints/sprint-XX/     # Per-sprint artifacts (handoff files)
├── CHANGELOG.md               # Version history with verifiable SHAs
├── LICENSE                    # Apache 2.0
├── NOTICE                     # Attribution and origin
└── README.md

The 19 skills

Sprint cycle: sprint-plan, build, review, fix, red-team, capture-lessons

Autonomous orchestration: full-sprint, update-briefs

Wiki curation: wiki-review

Operations: runbook, monitoring-briefing, smoke-test, product-verification, remote-fix

Marketing & content: marketing-sync, changelog, frontend-slides

Project setup: scaffolding, data-analysis

Philosophy

Eight principles that shape every decision in this repo:

1. Plan first. Never code without a plan. If it derails, stop and re-plan.
2. Subagents for everything specialized. Isolate concerns, keep the main context clean.
3. Capitalize on every mistake. Update lessons.md after every correction. Agent memory complements this organically.
4. Prove before declaring "done". Tests, logs, demo. Hooks enforce this.
5. Balanced elegance. Neither hack nor over-engineering.
6. Claude is autonomous within a phase. Don't micro-manage. Give scope and context, Claude does the rest.
7. Simplicity first. The simplest change that works. Always.
8. Revisit regularly. Skills and agents must evolve with model capabilities. If the model naturally does what a skill tells it, simplify the skill. Gotchas and business context are more durable than rigid steps.

Documentation

• docs/WORKFLOW.md — Complete workflow documentation
• docs/SECURITY.md — 6-layer defense architecture
• docs/REFERENCES.md — External resources and inspiration
• CHANGELOG.md — Version history with verifiable commit SHAs
• CONTRIBUTING.md — How to propose changes
• NOTICE — Attribution and origin

License

Licensed under the Apache License 2.0.

In short: you can use, modify, distribute, and use this work commercially. You must keep the LICENSE and NOTICE files in your distribution. You don't need to ask permission.

See NOTICE for attribution requirements.

Author

Rayan Aly Bah — DevSecOps engineer who built this workflow to ship a production SaaS without losing his mind to AI-assisted development drift. Connect on GitHub.

Issues, ideas, war stories: open an issue or start a discussion.

Acknowledgments

Built on top of Claude Code by Anthropic. Inspired by the Claude Code community's experimentation with hooks, subagents, and skills throughout 2025–2026.

The framing of wiki/ as the project-specific extension of the model's base knowledge takes after Andrej Karpathy's LLM Knowledge Bases thread — see his work at karpathy.ai. The generic model knows the public internet; the wiki adds what is yours. Together they form a model that actually knows your project.

This workflow is not affiliated with or endorsed by Anthropic.