A spec-driven development system for building products with AI. Combines the PM rigor of structured specs with the execution engine of phase-based AI coding.
Three territories, one flow:
PM writes specs/ → Designer fills design/ → Engineer builds with .planning/
↓
AGENTS.md (auto-generated map)
↓
discuss → plan → execute → verify
↓
Shipped product
Most AI coding tools skip the hard part. You describe an idea, AI generates code, and you get inconsistent results that fall apart at scale. The problem isn't the AI — it's the inputs.
This system enforces a simple rule: spec before code. Every feature needs a JTBD spec. Every domain rule needs documentation. Every phase gets explicit implementation decisions before planning starts. The AI reads these specs and builds exactly what was specified.
The result: product decisions live in specs (where PMs can review them), not buried in prompts or code comments.
cd your-project
# Copy this template into your project
cp -r ai-sdlc/* .
cp -r ai-sdlc/.claude .
# Launch Claude Code
claude
# Bootstrap
/ai-sdlc:init# Copy template files
cp -r ai-sdlc/.claude .
cp -r ai-sdlc/specs .
cp -r ai-sdlc/design .
cp -r ai-sdlc/.planning .
cp ai-sdlc/CLAUDE.md .
# Launch Claude Code
claude
# Map your codebase first
/ai-sdlc:map-codebase
# Then bootstrap
/ai-sdlc:init| Command | Phase | What It Does |
|---|---|---|
/ai-sdlc:init |
Setup | Bootstrap project: questions → specs → roadmap |
/ai-sdlc:spec-draft |
PM | Coach through JTBD spec creation |
/ai-sdlc:domain-capture |
PM | Extract business rules from conversation |
/ai-sdlc:spec-review |
PM | Multi-agent review (engineer, designer, skeptic) |
/ai-sdlc:design-phase N |
Design | Generate components, flows, prototype specs |
/ai-sdlc:prototype |
Design | Create interactive HTML/React prototype |
/ai-sdlc:discuss-phase N |
Build | Shape implementation decisions |
/ai-sdlc:plan-phase N |
Build | Research + task plans + Ralph prompts |
/ai-sdlc:execute-phase N |
Build | Run tasks (interactive or Ralph loop) |
/ai-sdlc:verify-work N |
Build | UAT + route fixes |
/ai-sdlc:quick |
Build | Ad-hoc task with SDLC guarantees |
/ai-sdlc:progress |
Nav | Where am I? What's next? |
/ai-sdlc:map-codebase |
Nav | Analyze existing codebase |
/ai-sdlc:generate-agents |
Nav | Rebuild AGENTS.md |
project/
├── CLAUDE.md # System prompt (read by Claude Code)
├── AGENTS.md # Auto-generated project map
├── PROJECT.md # Vision, problem, hypothesis
├── REQUIREMENTS.md # v1 / v2 / out-of-scope
├── ROADMAP.md # Phases + progress
│
├── specs/ # [PM TERRITORY]
│ ├── jobs/ # JTBD specs (product decisions)
│ └── domain/ # Business rules (timeless truth)
│
├── design/ # [DESIGNER TERRITORY]
│ ├── components.md # Component catalog
│ ├── flows.md # User flows
│ └── prototype/ # Per-feature UI specs
│
├── STACK.md # [ENGINEER TERRITORY]
├── ARCHITECTURE.md # System design
├── CONVENTIONS.md # Code patterns
│
├── .planning/ # Execution state
│ ├── STATE.md # Living memory
│ └── phases/ # Per-phase work
│ └── 01-phase-name/
│ ├── CONTEXT.md # Implementation decisions (from discuss-phase)
│ ├── RESEARCH.md # Technical research (from plan-phase)
│ ├── PLAN.md # Task checklist (from plan-phase)
│ ├── PROMPT_build.md # Ralph build prompt (from plan-phase)
│ ├── PROMPT_plan.md # Ralph planning prompt
│ ├── PROMPT_fix.md # Ralph fix prompt
│ ├── IMPLEMENTATION.md # What was built (generated by Ralph)
│ ├── SUMMARY.md # Phase completion report (generated by Ralph)
│ └── UAT.md # User acceptance test results
│
├── .claude/
│ ├── commands/ai-sdlc/ # Slash commands
│ └── agents/ # Sub-agent definitions
│
├── scripts/
│ └── loop.sh # Ralph Wiggum loop (run outside Claude Code)
│
└── docs/ # Methodology docs
| File | Owner | When |
|---|---|---|
| PROJECT.md | PM | Project kickoff |
| REQUIREMENTS.md | PM | After discovery |
| specs/jobs/*.md | PM (or PMCoach) | Before each feature |
| specs/domain/*.md | PM (or PMCoach) | When domain rules surface |
| design/*.md | Designer (AI-assisted) | After specs, via /ai-sdlc:design-phase |
| STACK.md | Engineer | Project kickoff |
| ARCHITECTURE.md | Engineer | After specs review |
| CONVENTIONS.md | Engineer | Project kickoff |
| .planning/* | System (AI) | During execution |
| AGENTS.md | System (auto) | Regenerated on changes |
AGENTS.md is compressed passive context loaded into every Claude Code session. It's not a status dashboard — status tracking belongs in .planning/STATE.md.
What it contains (~60 lines, <10KB):
- Stack summary (3-5 lines from STACK.md)
- Architecture summary (3-5 lines from ARCHITECTURE.md)
- Conventions summary (3-5 lines from CONVENTIONS.md)
- Commands (dev/build/test/lint from package.json)
- Domain index (one-line summary per spec — the core of AGENTS.md)
- Operational notes (user-added, preserved across regeneration)
Regenerate with: /ai-sdlc:generate-agents
The domain index gives Claude quick orientation without reading every spec file:
| Spec | Covers |
|------|--------|
| specs/jobs/01-user-submits-form.md | Mobile form submission with offline support |
| specs/domain/validation-rules.md | Field validation, required fields, error messages |Planning always happens inside Claude Code with human guidance:
/ai-sdlc:plan-phase N
↓
researcher agent → planner agent → plan-checker agent
↓
PLAN.md (task checklist)
Building has two paths from the same PLAN.md:
PLAN.md
│
┌──────────────┴──────────────┐
│ │
▼ ▼
PATH A PATH B
Interactive Ralph Loop
(inside Claude Code) (outside Claude Code)
│ │
▼ ▼
/ai-sdlc:execute-phase N ./scripts/loop.sh build
executor agent fresh context per task
human reviews each task fully autonomous
│ │
└──────────────┬──────────────┘
│
▼
PLAN.md updated
- [ ] → - [x]
│
▼
/ai-sdlc:verify-work N
claude
/ai-sdlc:execute-phase 1- Executor agent works through tasks one by one
- You review, provide feedback, adjust
- Good for: complex work, learning codebase, nuanced decisions
exit # leave Claude Code
./scripts/loop.sh build 01-core-feature- Fresh Claude context per task (no context rot)
- Fully autonomous, auto-approves tool calls
- Good for: well-specified phases, overnight runs, batch execution
Both paths use markdown checklists in PLAN.md:
- [ ] **Create user profile component**
- Files: `src/components/UserProfile.tsx`
- Spec: `specs/jobs/01-user-views-profile.md`
- Action: Create Card with avatar, name, email using shadcn components
- Verify: `pnpm build` passes, component renders correctly
- Done: Profile displays user info with proper styling
- [x] **Set up database schema**
- Files: `prisma/schema.prisma`
- ...| Status | Meaning |
|---|---|
- [ ] |
Pending |
- [x] |
Completed |
- [!] |
Blocked |
This repo is the output target for PMCoach. PMCoach coaches PMs through spec creation and writes directly to specs/. You don't need PMCoach to use this repo — specs can be created manually or via /ai-sdlc:spec-draft. PMCoach just makes it faster and higher quality.
See examples/ for complete worked examples of the framework in action:
- jha-safety-forms/ — Mobile safety compliance forms for construction (shows specs, domain rules, planning, and implementation)
| Command | Agents Used | Reads | Output |
|---|---|---|---|
/ai-sdlc:init |
— (interactive) | — | PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STACK.md |
/ai-sdlc:spec-draft |
— (interactive) | PROJECT.md, REQUIREMENTS.md, specs/domain/ | specs/jobs/*.md |
/ai-sdlc:domain-capture |
— (interactive) | PROJECT.md | specs/domain/*.md |
/ai-sdlc:spec-review |
designer-reviewer + engineer-reviewer + skeptic | specs/jobs/, specs/domain/ | Review feedback |
/ai-sdlc:design-phase |
— (interactive) | PROJECT.md, ROADMAP.md, STACK.md, specs/ | design/*.md |
/ai-sdlc:discuss-phase |
— (interactive) | ROADMAP.md, specs/jobs/, specs/domain/ | CONTEXT.md |
/ai-sdlc:plan-phase |
researcher → planner → plan-checker | STACK.md, CONVENTIONS.md, CONTEXT.md, specs/ | PLAN.md, PROMPT_*.md |
/ai-sdlc:execute-phase |
executor (Path A) or — (Path B) | PLAN.md, STACK.md, CONVENTIONS.md | Code, PLAN.md updated |
/ai-sdlc:verify-work |
verifier | PLAN.md, specs/jobs/, CONTEXT.md | UAT.md |
/ai-sdlc:quick |
— (inline) | STACK.md, CONVENTIONS.md | Code + commit |
/ai-sdlc:progress |
— (reads state) | ROADMAP.md, STATE.md, AGENTS.md | Status report |
/ai-sdlc:map-codebase |
researcher | (existing codebase) | STACK.md, ARCHITECTURE.md, CONVENTIONS.md |
/ai-sdlc:generate-agents |
— | PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STACK.md, specs/ | AGENTS.md |
| Agent | Called By | Reads | Purpose |
|---|---|---|---|
| researcher | plan-phase, map-codebase | STACK.md, specs/, codebase | Explore codebase, gather technical context |
| planner | plan-phase | CONTEXT.md, RESEARCH.md, specs/, CONVENTIONS.md | Generate PLAN.md as markdown checklist |
| plan-checker | plan-phase | PLAN.md, specs/, CONTEXT.md, ROADMAP.md | Validate PLAN.md completeness and ordering |
| executor | execute-phase (Path A) | PLAN.md, STACK.md, CONVENTIONS.md, specs/ | Work through tasks inside Claude Code |
| designer-reviewer | spec-review | specs/jobs/, design/ | Review specs for UX/design gaps |
| engineer-reviewer | spec-review | specs/jobs/, STACK.md | Review specs for technical feasibility |
| skeptic | spec-review | specs/jobs/, specs/domain/ | Challenge assumptions, find edge cases |
| verifier | verify-work | PLAN.md, specs/, code output | UAT, check work against specs |
Built on patterns from:
- Ralph Wiggum — Autonomous loop execution with fresh context per iteration
- GSD (TÂCHES) — Phase execution, multi-agent orchestration
- PM-OS — Skills architecture, sub-agent reviewers, context management
- AI-SDLC Framework — Role separation, AGENTS.md, domain persistence