HeadMaster — an open-source ADLC (AI-Driven Delivery Lifecycle) built on Claude Code.
Turns a single conversation into a PRD, a TDD, Jira stories, code, tests, and a reviewed PR. Plan. Design. Build. Review. Ship.
Website • Quick Start • Pipeline • Commands • Walkthrough • Config • Help
Keywords: ADLC, AI-Driven Development Lifecycle, Claude Code, Anthropic Claude, agentic pipeline, AI software delivery, autonomous coding agent, PRD generator, TDD generator, Jira automation, MCP, model context protocol, agent orchestration, code review automation, multi-agent workflow
HeadMaster is an orchestration layer that sits alongside your feature repositories. You open Claude Code from the HeadMaster directory, point it at a project, and run slash commands to move features through the pipeline.
/init-feature --> /plan --> /design --> /breakdown --> /execute --> PR
| | | | | |
Route & Tier PRD.md TDD.md Jira Stories Code + Tests Merge
Each stage produces structured, human-reviewable artifacts. Nothing merges automatically. Every gate requires explicit approval.
What it automates: requirements elicitation, PRD authoring, architecture decisions, TDD blueprints, Jira story decomposition, test-first implementation, security scanning, code review, QA testing, and cross-story system review.
What it does not do: deploy, auto-merge, or skip human approval gates.
git clone <headmaster-repo> HeadMaster && cd HeadMaster
cp config.yml.example config.ymlEdit config.yml — set projects.active and add your project entry with a real root path.
sh scripts/setup_projects.pyCreates docs/features/{project}/, memory/features/{project}/, and writes .claude/settings.local.json (gitignored) with the resolved project root for additionalDirectories and per-project Write rules. Re-run after editing config.yml.
npx -y @xuandev/atlassian-mcp # Jira + Confluence
npx @drawio/mcp # Diagramsclaude/init-feature "Add PDF invoice export with GDPR compliance"
/plan invoice-pdf-export
/design invoice-pdf-export
/breakdown invoice-pdf-export
/execute invoice-pdf-exportVerify state at any time: sh scripts/state_manager.py --status.
Prerequisites
| Requirement | Version | Notes |
|---|---|---|
| Claude Code | Latest | CLI or desktop app |
| Python | 3.9+ | For orchestration scripts. HeadMaster auto-resolves python3/py3/python/py plus common Windows install dirs. |
| Node.js | 18+ | Only for MCP servers (Atlassian, drawio) — not for HeadMaster itself. |
| Git | Any | For story branches and commits |
| Jira access | Optional | Required only if jira_push: true |
Environment variables (required for Jira integration):
ATLASSIAN_DOMAIN=your-org.atlassian.net
JIRA_USER_EMAIL=you@yourcompany.com
JIRA_API_TOKEN=your-api-tokenSet these in your shell profile. HeadMaster never stores credentials.
| Route | When to use | Pipeline |
|---|---|---|
feature |
New functionality | Full: plan → design → breakdown → execute |
hotfix |
Targeted bug fix | Compressed: optional design skip |
epic |
Multi-phase initiative | Plan-only or full |
spike |
Research / feasibility | Plan only → RESEARCH_REPORT.md |
Auto-detected during /init-feature. Controls artifact depth and which reviews are required.
| Tier | Stories | Points | PRD | Design | Reviews |
|---|---|---|---|---|---|
| XS | 1-2 | 1-5 | Skip | IMPLEMENTATION_BRIEF.md |
Optional |
| S | 3-5 | 6-15 | Required | TDD.md |
Optional |
| M | 5-8 | 13-21 | Required | SYSTEM_DESIGN_NOTES + TDD.md |
Required |
| L | 9+ | 22+ | Required | Full design + TDD_MASTER |
Required |
Every feature has a loop_state.json in memory/features/{project}/{slug}/ — the single source of truth. Tracks current phase, per-stage status (planning_stages, design_stages), artifact statuses, story progress, gate timestamps, and retry counts. Never edit manually; use gate_transition.py for transitions.
Unconditional (never auto-approve): PRD approval, TDD approval, Jira story approval, Merge Gate.
Configurable: PRD review mode, TDD review mode, breakdown auto-approve. See config.yml gates section.
/init-feature |
Start here. Detects route, classifies tier, scaffolds directories, creates /init-feature "Add PDF invoice export with GDPR compliance"
/init-feature spike "Is ElasticSearch viable for replacing Lucene?"
/init-feature hotfix "Fix null pointer in payment processor"
/init-feature path/to/FEATURE_INPUT.md |
/plan <slug> |
Drives planning to an approved PRD. Auto-resumes from saved stage state. /plan invoice-pdf-export
/plan invoice-pdf-export "the async path needs more detail"Stages: Context (codebase scan) → Discover (gap Q&A, inline) → Draft (PRD authoring, inline) → stop → Review (new session, interactive) Draft and Review run in separate sessions. After Draft completes, start a new session and re-run |
/design <slug> |
Drives design to an approved TDD. Reads PRD. Auto-resumes. /design invoice-pdf-export
/design invoice-pdf-export "focus on caching strategy"Stages: Architect (ADRs + design notes) → Engineer (TDD blueprint) → stop → Review (new session, inline) |
/breakdown <slug> |
Decomposes TDD into Jira stories with ACs and sizing. /breakdown invoice-pdf-export
/breakdown invoice-pdf-export merge-gate # standalone pre-merge check |
/execute <slug> |
Drives all stories through implementation, scan, review, QA, and creates PR. /execute invoice-pdf-export
/execute invoice-pdf-export --story ACME-101 # one story only |
| Phase | Scope | Agent | What | Isolated |
|---|---|---|---|---|
| A | Per story | developer (inline) |
Implement per TDD + security scan | |
| B | Per story | Parent (inline) | Verify diff covers all ACs | |
| C | Feature (once) | review-agent + qa-engineer (parallel subagents) |
System review + integration QA | Yes |
Phase C runs once after all stories complete. Any blocking findings → escalate before PR.
Click to expand all supporting commands
Phase A only. Implements a single story inline.
Standalone. Runs diff_scanner.py against a branch diff. Embedded in Phase A.
Standalone code review skill. Reviews a branch diff — TDD compliance, OWASP, logic.
Standalone. Writes + runs integration tests. Used as subagent in Phase C.
Standalone. Process audit subagent — TDD design vs actual execution. Used in Phase C.
All Jira communication. MCP-first, manual fallback.
/jira-ops create-epic invoice-pdf-export
/jira-ops create-story ACME-100 "Add PDF generation endpoint"
/jira-ops transition ACME-101 "In Progress"
/jira-ops comment ACME-101 "Phase A complete, branch: story/ACME-101"
/jira-ops link ACME-101 blocks ACME-102Reopen a completed stage for revision. Cascades downstream.
/reopen invoice-pdf-export planning "PRD section 3 is missing auth flow"
/reopen invoice-pdf-export design "TDD missing error handling for timeout"Cascade: planning reopened → design, breakdown, execute marked revision.
Publish PRD or TDD to Confluence.
Move a completed feature to archive.
Analyze completed run. Auto-applies agent memory patches and pipeline learnings. Config proposals require human approval.
Compress a working .md file to concise style. Saves input tokens.
Generate architecture or flow diagrams as native .drawio files.
/setup-env [--project <name>] [--reset]Scan project repos, detect tech stack per module, write memory/projects/{project}/repo-registry.yml. Run once per project before /init-feature — enables repo/module selection without live scanning on every feature. Re-run with --reset after repo structure changes.
Three skills run independently — no active feature or loop state required.
| Command | What it does |
|---|---|
/review-pr <number-or-url> |
Review an open GitHub PR (quality + OWASP + logic) |
/review-branch [branch] [--base main] |
Review full branch diff against base |
/review-tdd <path> [--prd <path>] |
Review TDD for completeness + optional PRD traceability |
A complete s-tier feature from start to PR.
Step 1 — Initialize
/init-feature "Add full-text search to the product catalog"
HeadMaster asks clarifying questions (codebase, effort, complexity, dependencies), then outputs:
Feature initialized: product-catalog-search
Route: feature
Tier: s
Next: /plan product-catalog-search
Step 2 — Plan (two sessions)
Session 1 — Authoring
/plan product-catalog-search
- Context — codebase-analyst scans for existing search patterns, indexing code, data models.
- Discover — requirements-analyst (inline) surfaces gaps one question at a time: fuzzy matching required? searchable fields? response time SLA?
- Draft — prd-author (inline) writes
PRD.md.
Stops automatically. Prints: PRD written. Start a new session: /plan product-catalog-search to review.
Session 2 — Review
/plan product-catalog-search
- Step 1 — "Any feedback on the PRD?" → apply or skip
- Step 2 — targeted Q&A on scope, requirements, AC testability (3 questions for s-tier)
- Step 3 — open floor: "Any other questions or concerns?"
- Step 4 — optional sections gate: "Add security requirements? Observability targets? Performance SLOs?" — user decides, none added by default
- Step 5 — prd-reviewer (inline, m/l only) mechanical checklist pass
PRD approved → advance to /design.
Step 3 — Design
/design product-catalog-search
Architect — reads PRD + codebase. Decides: use existing ES client, add FullTextSearchService, index on product write, query via GET /catalog/search?q=. Writes SYSTEM_DESIGN_NOTES.md with ADRs.
Engineer — reads locked design. Writes TDD.md: interfaces, data models, component design, error handling, testing strategy, vertical slices, ADR references.
Engineer stops. Start a new session and re-run /design product-catalog-search to begin Review.
Review — tdd-reviewer reads TDD cold. Verifies interface-to-AC traceability, ADR alignment, error path enumeration. Returns APPROVED.
Step 4 — Breakdown
/breakdown product-catalog-search
release-agent decomposes TDD into stories. You approve. If jira_push: true, it creates the epic + stories in Jira.
Step 5 — Execute
/execute product-catalog-search
For each story: Phase A (implement + scan) → Phase B (AC check). Phase C (system review + integration QA) runs once after all stories complete.
Step 6 — PR
/execute finishes with automatic PR creation. Human reviewer merges. Feature complete.
XS — Trivial Fix (skips PRD, design notes, all reviews)
/init-feature hotfix "Fix null pointer in PaymentService"
# -> tier: xs
/design my-fix # writes IMPLEMENTATION_BRIEF.md only
/execute my-fix # A -> B per story, no Phase CS — Standard Feature (PRD + TDD, reviews optional)
/init-feature "Add user profile avatar upload"
/plan my-feature
/design my-feature
/breakdown my-feature
/execute my-featureM — Multi-Story (all artifacts + reviews required)
/init-feature "Add real-time notifications"
/plan my-feature
/design my-feature # SYSTEM_DESIGN_NOTES + TDD + required review
/breakdown my-feature
/execute my-feature # A -> B (per story) + Phase C (system review + QA) -> PRL — Large / Multi-Repo (full depth, TDD splits by repo)
/init-feature "Migrate from MySQL to PostgreSQL"
/plan my-feature
/design my-feature # 13-section design + TDD_MASTER + TDD_{REPO} per repo
/breakdown my-feature # JIRA_BREAKDOWN_{REPO} per repo
/execute my-featureSpike — Research Only
/init-feature spike "Evaluate GraphQL vs REST for the API gateway"
/plan my-spike # FEATURE_DRAFT -> DISCOVERY -> RESEARCH_REPORT.md
# Pipeline ends here.13 specialized agents, each with defined input/output contracts and memory.
| Agent | Model | Role | Pattern |
|---|---|---|---|
requirements-analyst |
haiku | Requirements elicitation, gap surfacing | Inline always |
prd-author |
haiku | PRD authoring from discovery | Inline always |
prd-reviewer |
haiku | PRD mechanical checklist (m/l tiers) | Inline in review session |
| Agent | Model | Role | Pattern |
|---|---|---|---|
solutions-architect |
opus | Architecture decisions, ADRs, design notes | Inline |
codebase-analyst |
haiku | Codebase scanning | Subagent (read-only) |
tdd-author |
haiku | TDD blueprints from design notes | Inline |
tdd-reviewer |
haiku | TDD stress-test | Inline in review session |
web-researcher |
sonnet | External library / API research | Subagent |
| Agent | Model | Role | Pattern |
|---|---|---|---|
developer |
sonnet | Test-first implementation, atomic commits | Inline |
review-agent |
haiku | Code review + OWASP security (diff only) | Subagent (isolated) |
qa-engineer |
sonnet | Integration tests per AC, test fixes | Subagent (isolated) |
release-agent |
haiku | Story decomposition + merge gate | Inline |
retrospective-analyst |
haiku | Post-feature pattern extraction, memory + learning proposals | Subagent |
Isolation: review-agent, qa-engineer, tdd-reviewer receive no implementation context — diff + ACs + TDD sections only. Enforced by pre_spawn_validation.py hook. prd-reviewer isolation is structural (new session).
The canonical reference is config.yml.example. Copy it to config.yml (gitignored) and customize. Every key in the example file has a consumer — no dead keys.
cp config.yml.example config.ymlValidate your config at any time:
sh scripts/config_utils.py validate config.ymlgates.{phase}.interactive — true asks at decision points, false lets the agent decide and document reasoning. Per-phase only — there is no global pipeline.interactive.
gates.{phase}.review.mode
| Mode | Behavior |
|---|---|
skip |
Mark artifact APPROVED immediately |
auto |
Run reviewer inline, auto-approve PASS/CONDITIONAL |
human_in_loop |
Interactive Q&A + reviewer (m/l tiers) |
.mcp.json — MCP server config
{
"mcpServers": {
"atlassian": {
"command": "npx",
"args": ["-y", "@xuandev/atlassian-mcp"],
"env": {
"ATLASSIAN_DOMAIN": "${ATLASSIAN_DOMAIN}",
"ATLASSIAN_EMAIL": "${JIRA_USER_EMAIL}",
"ATLASSIAN_API_TOKEN": "${JIRA_API_TOKEN}"
}
},
"drawio": {
"command": "npx",
"args": ["@drawio/mcp"]
}
}
}Environment variables are resolved at runtime. Never put actual values in this file.
projects:
active: beta
beta:
name: Beta
root: ../beta-app
project_key: BETA
jira_push: false
coverage_threshold: 75Change projects.active in config.yml, re-run sh scripts/setup_projects.py (refreshes .claude/settings.local.json), then restart your Claude Code session.
All feature directories are isolated by project:
docs/features/acme/{slug}/ <- Acme features
docs/features/beta/{slug}/ <- Beta features
memory/features/acme/{slug}/ <- Acme state
memory/features/beta/{slug}/ <- Beta state
sh scripts/state_manager.py --status
sh scripts/state_manager.py --status --project acmeEvery skill auto-detects where it left off. Just re-run the command:
/plan product-catalog-search # resumes at the interrupted stage
/design product-catalog-search
/execute product-catalog-search # resumes from the incomplete storyPhase A — Implementation Failures
Max 3 attempts before human escalation. failure_ledger.py prevents retrying the same broken approach.
sh scripts/failure_ledger.py load acme product-catalog-search ACME-201Phase C — System Review + QA Failures
| Agent | Verdict | Action |
|---|---|---|
review-agent |
FINDINGS (CRITICAL/HIGH) |
Fix in-place on feature branch or re-dispatch story |
qa-engineer |
REJECTED-BUG |
Fix code (never the test), Phase C re-runs once |
qa-engineer |
APPROVED_PARTIAL |
Some ACs NOT_VERIFIABLE — acceptable, proceed |
Reopening a Completed Stage
/reopen product-catalog-search planning "NFR for response time is wrong, should be p99 not p95"Cascades downstream: PRD → revision, design/breakdown/execute → revision.
Emergency Reset
sh scripts/cleanup_failed_run.py acme product-catalog-search
sh scripts/cleanup_failed_run.py acme product-catalog-search --reset-stateAll orchestration scripts live in scripts/. Browse the directory for the full list — each script has a docstring at the top describing its purpose and usage. Key entry points are referenced inline throughout this README (state, recovery, failure ledger, setup).
Full directory tree
HeadMaster/
|
+-- config.yml # Active project + pipeline settings
+-- .mcp.json # MCP servers (Atlassian, Draw.io)
|
+-- .claude/
| +-- CLAUDE.md # Core operating rules
| +-- settings.json # Permissions + hooks
| |
| +-- agents/ # 13 agent definitions
| | +-- requirements-analyst.md
| | +-- prd-author.md
| | +-- prd-reviewer.md
| | +-- solutions-architect.md
| | +-- codebase-analyst.md
| | +-- tdd-author.md
| | +-- tdd-reviewer.md
| | +-- developer.md
| | +-- review-agent.md
| | +-- qa-engineer.md
| | +-- release-agent.md
| | +-- web-researcher.md
| | +-- retrospective-analyst.md
| | +-- references/ # Output protocols
| |
| +-- skills/ # 19 skill definitions
| | +-- init-feature/ | plan/ | design/ | breakdown/ | execute/
| | +-- implement/ | security-scan/ | review-code/ | qa-integration/
| | +-- review-system/ | jira-ops/ | reopen/ | retrospect/
| | +-- publish-confluence/ | archive-feature/ | compress/ | draw/
| |
| +-- workflows/ # Tier algorithms (xs/s/m/l)
| +-- hooks/ # Auto-run on session events
| +-- pre_spawn_validation.py # Subagent isolation enforcement
| +-- write_guard.py # Secret detection on writes
| +-- subagent_stop.py # Subagent output validation
| +-- activate.py # Session startup
| +-- feature_context.py # Active feature context loader
|
+-- scripts/ # Python orchestration
+-- docs/features/{project}/{slug}/ # Artifacts (PRD, TDD, reviews)
+-- memory/features/{project}/{slug}/ # State (loop_state.json, failure ledger)
+-- tests/
Hooks not running / python: command not found
Hooks and scripts are invoked as sh path/to/file.py. Each .py file starts with a polyglot shebang that probes python3 → py3 → python → py on PATH, then common Windows install dirs (/c/Program Files/Python/Python*, $LOCALAPPDATA/Programs/Python/Python*). Install Python 3.9+ anywhere standard and HeadMaster finds it — no shim, no PATH setup.
loop_state.json not found
Run /init-feature first. It scaffolds all directories and creates loop_state.json.
config.yml not found
Run Claude Code from the HeadMaster root directory, not from a feature repo. If config.yml does not exist, copy it from the example: cp config.yml.example config.yml.
Read/Write blocked for files in the feature repo
.claude/settings.local.json controls additionalDirectories and per-project Write rules. It is generated from config.yml by scripts/setup_projects.py — re-run it after editing config.yml.projects.{slug}.root or adding a new project.
Jira MCP unavailable
- Check env vars:
echo $ATLASSIAN_DOMAIN && echo $JIRA_USER_EMAIL - Set
jira_push: falseinconfig.ymlto work locally without Jira.
PRD gate not triggering
The gate string must appear verbatim in the PRD header table: PRD Status: APPROVED (case-sensitive).
Review returned REJECTED
- Read
docs/features/{project}/{slug}/planning/PRD_REVIEW.md - Fix
BLOCKERitems;HIGHshould be fixed;MEDIUMis your call - Run
/plan {slug} "corrections: [describe what changed]"in the review session
Story stuck at 3 retries
sh scripts/failure_ledger.py load acme {slug} {STORY-KEY}Review excluded_approaches. Use /reopen {slug} breakdown to revise scope or /reopen {slug} design if the TDD interface is unimplementable.
Stale file lock on loop_state.json
sh scripts/gate_transition.py acme {slug} rollback
# If backup is also corrupted:
sh scripts/cleanup_failed_run.py acme {slug} --reset-stateContext window approaching limit
/handoff # saves session state and clears contextTarget users:
| User | How they use HeadMaster |
|---|---|
| Solo senior / staff engineer | Full pipeline across one or more existing repos |
| Tech lead running design reviews | /plan, /design, /review-tdd standalone — no execution required |
| Security engineer | /scan, /review-code, /review-branch standalone |
Why it works for a single developer today:
config.ymlis per-machine (gitignored) — no coordination neededmemory/is per-machine (gitignored) — agent memory is personal- Jira creds are personal env vars
setup-envwrites a personalrepo-registry.yml
Known limitations at Phase 1:
- Agent memory does not cross machines
- Two developers cannot share progress on the same feature slug without manually moving
memory/features/{project}/{slug}/loop_state.json
Team rollout (architect owns plan/design; developers pick up breakdown/execute) is captured in FUTURE.md and not implemented yet.
| # | Practice |
|---|---|
| 1 | Always start with /init-feature — sets tier, route, and pipeline mode correctly |
| 2 | Read every artifact before continuing — catching issues in PRD/TDD is far cheaper than in execution |
| 3 | Keep jira_push: false until Jira is configured — push manually with /jira-ops when ready |
| 4 | Review runs in a new session — both /plan and /design stop after authoring; re-run in a fresh session for structural isolation |
| 5 | Use --story for spot-fixes — /execute {slug} --story ACME-101 then resume the full run |
| 6 | Never edit loop_state.json manually — use gate_transition.py for transitions |
| 7 | /reopen instead of editing artifacts — tracks cascade and triggers revision mode |
| 8 | One active project per session — change projects.active and restart |
| 9 | Security/observability/metrics are opt-in — offered during PRD review, never auto-added |
| 10 | Phase C is mandatory for m/l tiers — the only audit comparing intent (TDD) to outcome (commits) |
Built with Claude Code • Orchestrated by HeadMaster