Claude Code SDLC

Turn Claude Code into a full software development team.

13 specialized AI agents. Documentation-first. TDD. Quality gates. Hardened against Claude Code's known limitations.

---

Why

Claude Code out of the box:

• Writes code before understanding requirements
• Skips tests or writes them as an afterthought
• Reports success when the code doesn't compile — "bytes hit disk" is its success metric
• Silently loses context at ~167K tokens, then edits against stale memory
• Misses references during renames — grep is text matching, not an AST
• Truncates file reads at 2,000 lines and search results at ~50K chars without warning

What This Fixes

• Documentation-first — PRD, use cases, test cases documented before any code
• TDD enforcement — tests written before implementation, every slice verified
• Goal-backward verification — checks features are actually wired together, not just that code compiles (file existence, stub detection, wiring, data flow)
• Graduated error recovery — auto-fix typos (free), auto-add validation (free), auto-resolve dependencies (costs retry), escalate architecture decisions (stop)
• Executable plans — each slice has Files:, Changes:, Verify:, Done when: fields — no interpretation drift
• Scope reduction detection — Plan Critic flags hedging language ("v1", "placeholder", "for now") against PRD requirements
• Context integrity — mandatory re-read before edit, scratchpad persistence, chunked reads for large files
• Rename safety — 7-step protocol covering barrel files, dynamic imports, re-exports, typecheck verification
• Mid-slice typecheck — runs after every 3 file edits when a slice touches 4+ files
• Parallel execution waves — independent slices execute simultaneously via wave-based parallelism, cutting wall-clock implementation time
• 9 quality gates — git hygiene, docs completeness, code review, security audit, build, E2E, goal-backward verification, doc accuracy, UI/UX

---

Install

curl -fsSL https://raw.githubusercontent.com/Koroqe/claude-code-sdlc/main/install.sh | bash

Or locally:

git clone https://github.com/Koroqe/claude-code-sdlc.git
cd claude-code-sdlc
bash install.sh --yes

Scaffold a new project:

cd your-project && bash install.sh --init-project

---

How It Works

Feature Request
     |
     v
PLAN MODE -----> Explore codebase, design approach, Plan Critic review
     |
     v
/bootstrap-feature
  - PRD Writer ........... documents requirements
  - Business Analyst ..... writes use cases
  - Architect ............ reviews design
  - QA Lead .............. documents test cases
  - Tech Lead ............ creates executable plan (5-9 slices)
     |
     v
/develop-feature Phase 2 (wave-aware)
  - Single-slice wave: TDD as before
  - Multi-slice wave: spawn parallel subagents (one per slice)
  - Wait for wave completion -> next wave
  - Each slice: re-read files, TDD, verify, commit
     |
     v
/merge-ready
  - Code Review + Security Audit + Build
  - E2E Tests + Goal-Backward Verification + Doc Check
     |
     v
MERGE READY

---

The 13 Agents

Agent	Role
prd-writer	Feature requirements in docs/PRD.md
ba-analyst	Use cases and scenarios in docs/use-cases/
architect	Architecture review, module boundaries, [STRUCTURAL] fix authorizations
qa-planner	Test cases in docs/qa/ before any code
planner	Breaks features into 5-9 executable slices with verification commands
security-auditor	Vulnerability audit, auth boundaries
test-writer	TDD — tests before implementation
e2e-runner	End-to-end tests from use-case scenarios
code-reviewer	Quality, security, architecture compliance
build-runner	Typecheck, tests, build verification
verifier	Goal-backward checks: file existence, stubs, wiring, data flow
doc-updater	Keeps documentation accurate after changes
refactor-cleaner	Post-implementation cleanup with rename safety

---

Commands

Command	What It Does
/develop-feature	Full autonomous pipeline — request to merge-ready
/bootstrap-feature	Documentation phases only — PRD, use cases, architecture, QA, plan
/implement-slice	Next TDD slice — tests first, implement, verify, commit
/merge-ready	All 9 quality gates
/context-refresh	Rebuild session context from scratchpad

> Add user authentication with Google OAuth

Claude automatically:
1. Plans -> explores codebase -> critic review
2. Bootstraps -> PRD, use cases, architecture, QA, executable plan
3. Implements -> TDD slices in parallel waves (independent slices run simultaneously)
4. Verifies -> 9 quality gates including goal-backward verification

---

Hardening Against Claude Code Internals

Failure Mode	Our Fix
False success reports (bytes hit disk != working code)	Mandatory typecheck after edits; mid-slice typecheck every 3 files
Context death spiral (~167K token compaction)	Re-read-before-edit rule; scratchpad persistence; auto-archiving at 100+ lines
Silent file truncation (2,000-line read cap)	Chunked reads with offset/limit for files >500 LOC
Search truncation (50K char cap, silent)	Re-run with narrower scope when results look small
Grep misses references (text matching, not AST)	7-step rename protocol: whole-word, barrel files, dynamic imports, tests, config, typecheck
Simplicity bias blocks structural fixes	Architect [STRUCTURAL] action items authorize fixes beyond minimal-diff
No pre-refactor cleanup	Step 0: remove dead code first, commit separately, then refactor
Flat "retry 3x" error recovery	4-tier deviation rules: auto-fix, auto-add, auto-resolve, escalate
Vague plans cause implementation drift	Executable format: Files:, Changes:, Verify:, Done when: per slice
Code compiles but feature is disconnected	4-level goal-backward verification: existence, stubs, wiring, data flow
Agents silently downgrade scope	Plan Critic scans for hedging language against PRD requirements
Sequential execution wastes time on independent slices	Wave-based parallelism: planner groups slices by file overlap, develop-feature spawns parallel subagents per wave

---

Project Setup

cd your-project && bash install.sh --init-project

Creates:

• .claude/CLAUDE.md — your tech stack, structure, commands (fill in TODOs)
• .claude/scratchpad.md — session state persistence
• .claude/settings.json — permissions config
• .claude/rules/ — architecture, security, testing constraints
• docs/PRD.md — product requirements
• docs/qa/ and docs/use-cases/ — test case and use case directories

---

Customization

• Edit agents — each is a standalone .md file in ~/.claude/agents/
• Add agents — create a new .md with YAML frontmatter (name, description, tools, model)
• Change models — set model: opus, sonnet, or haiku per agent in frontmatter
• Fork and reinstall — edit in src/agents/, run bash install.sh --local --yes

---

Contributing

See CONTRIBUTING.md.

License

MIT