Skip to content

munna-chauhan/HeadMaster

Repository files navigation

HeadMaster - AI-Driven Software Delivery Pipeline

Built on Claude Code Python 3.9+ Node.js 18+ Apache 2.0 13 Agents 19 Skills

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.

WebsiteQuick StartPipelineCommandsWalkthroughConfigHelp

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


What It Does

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.


Quick Start

1. Clone & Configure

git clone <headmaster-repo> HeadMaster && cd HeadMaster
cp config.yml.example config.yml

Edit config.yml — set projects.active and add your project entry with a real root path.

2. Resolve project paths

sh scripts/setup_projects.py

Creates 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.

3. Install MCP Servers

npx -y @xuandev/atlassian-mcp    # Jira + Confluence
npx @drawio/mcp                  # Diagrams

4. Launch

claude

5. Build Something

/init-feature "Add PDF invoice export with GDPR compliance"
/plan invoice-pdf-export
/design invoice-pdf-export
/breakdown invoice-pdf-export
/execute invoice-pdf-export

Verify 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-token

Set these in your shell profile. HeadMaster never stores credentials.


Pipeline at a Glance

Routes

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

Tiers

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

State Machine

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.

Human Gates

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.


Skills — All Commands

Primary Pipeline

/init-feature

Start here. Detects route, classifies tier, scaffolds directories, creates loop_state.json.

/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 /plan {slug} to begin the interactive review.

/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

Per-Story Execution Phases

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.

Supporting Skills

Click to expand all supporting commands

/implement <slug> <story-key>

Phase A only. Implements a single story inline.

/security-scan <slug> <story-key>

Standalone. Runs diff_scanner.py against a branch diff. Embedded in Phase A.

/review-code <slug> <story-key>

Standalone code review skill. Reviews a branch diff — TDD compliance, OWASP, logic.

/qa-integration <slug> <story-key>

Standalone. Writes + runs integration tests. Used as subagent in Phase C.

/review-system <slug>

Standalone. Process audit subagent — TDD design vs actual execution. Used in Phase C.

/jira-ops <action> <target> [payload]

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-102

/reopen <slug> [stage] [message]

Reopen 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-confluence <slug> <artifact>

Publish PRD or TDD to Confluence.

/archive-feature <project> <slug>

Move a completed feature to archive.

/retrospect <slug>

Analyze completed run. Auto-applies agent memory patches and pipeline learnings. Config proposals require human approval.

/compress <filepath>

Compress a working .md file to concise style. Saves input tokens.

/draw "description" [--format png|svg|pdf] [-o path]

Generate architecture or flow diagrams as native .drawio files.

Setup

/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.


Standalone Reviews

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

Full Pipeline Walkthrough

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.


Tier Workflows

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 C
S — Standard Feature (PRD + TDD, reviews optional)
/init-feature "Add user profile avatar upload"
/plan my-feature
/design my-feature
/breakdown my-feature
/execute my-feature
M — 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) -> PR
L — 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-feature
Spike — 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.

Agents

13 specialized agents, each with defined input/output contracts and memory.

Planning

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

Design

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

Execution

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).


Configuration Reference

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.yml

Validate your config at any time:

sh scripts/config_utils.py validate config.yml

gates.{phase}.interactivetrue 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.


Working on Multiple Projects

Add a Project

projects:
  active: beta
  beta:
    name: Beta
    root: ../beta-app
    project_key: BETA
    jira_push: false
    coverage_threshold: 75

Switch Active Project

Change 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

Check All Feature States

sh scripts/state_manager.py --status
sh scripts/state_manager.py --status --project acme

Resuming an Interrupted Feature

Every 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 story

Handling Failures & Rollback

Phase 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-201
Phase 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-state

Scripts

All 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).


Project Structure

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/

Troubleshooting

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
  1. Check env vars: echo $ATLASSIAN_DOMAIN && echo $JIRA_USER_EMAIL
  2. Set jira_push: false in config.yml to 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
  1. Read docs/features/{project}/{slug}/planning/PRD_REVIEW.md
  2. Fix BLOCKER items; HIGH should be fixed; MEDIUM is your call
  3. 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-state
Context window approaching limit
/handoff    # saves session state and clears context

Who Can Use This

Target 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.yml is per-machine (gitignored) — no coordination needed
  • memory/ is per-machine (gitignored) — agent memory is personal
  • Jira creds are personal env vars
  • setup-env writes a personal repo-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.


Best Practices

# 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

About

HeadMaster — open-source ADLC (AI-Driven Delivery Lifecycle) built on Claude Code. Turns a single conversation into PRD, TDD, Jira stories, code, tests, and a reviewed PR.

Topics

Resources

License

Contributing

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors