tdd-claude-code 0.4.1 → 0.5.0

package/README.md

@@ -1,114 +1,168 @@
-# TDD Workflow for Claude Code
+# TDD
 
-Test-Led Development powered by [GSD](https://github.com/glittercowboy/get-shit-done).
+**Tests before code. Automatically.**
 
-**One interface. Tests happen automatically. You don't think about methodology.**
+```bash
+npx tdd-claude-code
+```
 
 <p align="center">
-  <img src="assets/terminal.svg" alt="TDD Installer" width="700">
+  <img src="assets/terminal.svg" alt="TDD" width="700">
 </p>
 
-## Install
+---
 
-```bash
-npx tdd-claude-code
+## The Problem
+
+You tell Claude to build something. It builds it. You test it manually. It's broken. You debug. Repeat.
+
+**That's backwards.**
+
+## The Solution
+
+TDD writes tests *before* code exists. Every feature has a spec. Every spec is executable. When the code works, you know — because the tests pass.
+
+```
+You describe → Tests are written → Code is implemented → Tests pass → Done
 ```
 
-GSD is installed automatically if missing.
+No manual testing. No "does this work?" No vibes.
+
+---
+
+## Quick Start
 
-Options:
 ```bash
-npx tdd-claude-code --global   # available in all projects
-npx tdd-claude-code --local    # this project only
+npx tdd-claude-code        # Install
 ```
 
-## Usage
-
-You use `/tdd:*` commands for everything. Never touch `/gsd:*` directly.
+Then in Claude Code:
 
 ```
-/tdd:new-project          New project from scratch
-       OR
-/tdd:init                 Add TDD to existing codebase
-/tdd:coverage             Analyze gaps, write retro tests (optional)
-    ↓
-/tdd:discuss 1            Shape how phase 1 gets built
-/tdd:plan 1               Create task plans
-/tdd:build 1              Write tests → implement → tests pass  ← TDD happens here
-/tdd:verify 1             Human acceptance testing
-    ↓
-...repeat for each phase...
-    ↓
-/tdd:complete             Tag release
+/tdd
 ```
 
-## What `/tdd:build` Does
-
-This is where the magic happens:
+That's it. One command. It knows what to do next.
 
-1. **Red** — Spawns agents to write failing tests for each task
-2. **Verify** — Runs tests, confirms they fail (code doesn't exist yet)
-3. **Green** — Calls GSD to implement (you walk away)
-4. **Verify** — Runs tests, confirms they pass
+Starting fresh? It asks what you're building.
+Have existing code? It finds untested files.
+Mid-project? It picks up where you left off.
 
-You run one command. Tests get written before code. Automatically.
+---
 
 ## Commands
 
-| Command | What It Does |
-|---------|--------------|
-| `/tdd:new-project` | Start project with test infrastructure |
-| `/tdd:init` | Add TDD to existing codebase |
-| `/tdd:coverage` | Analyze gaps, write tests for existing code |
-| `/tdd:discuss [N]` | Capture implementation preferences |
-| `/tdd:plan [N]` | Create task plans |
-| `/tdd:build <N>` | **Write tests → implement → verify** |
-| `/tdd:verify [N]` | Human acceptance testing |
-| `/tdd:status [N]` | Check test pass/fail |
-| `/tdd:progress` | Where am I? |
-| `/tdd:quick` | Ad-hoc task with tests |
-| `/tdd:complete` | Tag release |
-| `/tdd:new-milestone` | Start next version |
-| `/tdd:help` | Show all commands |
-
-## For Vibe Coders
-
-No existing codebase? No problem.
-
-`/tdd:new-project` detects your stack and sets up the test framework:
-
-| Stack | Framework |
-|-------|-----------|
-| Next.js / React | Vitest |
-| Node.js | Vitest |
-| Python | pytest |
-| Go | go test |
-| Ruby | RSpec |
-
-You describe what you want. Tests and code get written. You verify it works.
-
-## Why TDD?
-
-**Without TDD:**
+| Command | What |
+|---------|------|
+| `/tdd` | **Smart entry point. Knows what's next.** |
+| `/tdd:new-project` | Start fresh. Discuss stack, scaffold. |
+| `/tdd:init` | Add TDD to existing code. |
+| `/tdd:coverage` | Find untested → write tests |
+| `/tdd:quick` | One-off task with tests |
+| `/tdd:status` | Pass/fail counts |
+
+---
+
+## What Makes This Different
+
+### 1. Tests First, Always
+
+Other workflows: plan → build → "hope it works"
+
+TDD: plan → **write failing tests** → build until tests pass
+
+The tests *are* the spec. No ambiguity.
+
+### 2. Smart Stack Selection
+
+Don't pick tech in a vacuum. TDD asks what you're building, who uses it, what scale — then suggests the right stack.
+
 ```
-Plan → Implement → "Does it work?" → Debug → Repeat
+Building: Internal dashboard
+Scale: Small team
+Data: Simple CRUD
+
+→ Suggested: Next.js + SQLite + Vercel
+→ Why: Fast to build, cheap to host, fits your needs
 ```
 
-**With TDD:**
+### 3. Parallel Agents
+
+Up to 3 Claude instances working simultaneously. GitHub issues as task queue. Watch them go.
+
 ```
-Plan → Write tests (spec) → Implement (pass tests) → Verify
+┌──────────────────────────────────────────────────────┐
+│ Agents                                               │
+│ [1] ● Working on #42: Auth flow                      │
+│ [2] ● Working on #43: User CRUD                      │
+│ [3] ○ Idle                                           │
+└──────────────────────────────────────────────────────┘
 ```
 
-Tests define expected behavior BEFORE code exists. Implementation has concrete pass/fail targets. Bugs surface immediately, not during manual testing.
+### 4. GitHub Integration
+
+Plans approved → issues created automatically. Tasks complete → issues closed. Full audit trail.
+
+### 5. Live Preview
+
+Docker container spins up. See your app as it's built. Not after.
+
+---
+
+## Dashboard (Coming Soon)
+
+```
+┌─────────────────────────────────┬──────────────────────┐
+│ Chat                            │ GitHub Issues        │
+│                                 │ #42 Auth flow    WIP │
+│ Building login endpoint...      │ #43 User CRUD        │
+│ ✓ Created tests/auth.test.ts    │ #44 Dashboard        │
+│ ✓ Tests failing (expected)      ├──────────────────────┤
+│ Implementing...                 │ Agents (2/3)         │
+│                                 │ [1] ● #42            │
+│                                 │ [2] ● #43            │
+│                                 │ [3] ○ Idle           │
+├─────────────────────────────────┼──────────────────────┤
+│ > add password reset flow       │ Tests: 23/23 ✓       │
+└─────────────────────────────────┴──────────────────────┘
+```
+
+TUI dashboard. Multiple panes. Real-time updates.
+
+---
 
-Human verification still happens — tests catch logic errors, you catch "not what I meant" issues.
+## Philosophy
 
-## Safe from GSD Updates
+**Tests define behavior. Code makes tests pass.**
 
-TDD lives in `.claude/commands/tdd/`
-GSD lives in `.claude/commands/gsd/`
+- Tests written BEFORE code
+- Tests are the spec, not an afterthought
+- If it's not tested, it doesn't exist
+- Human verification still happens — tests catch logic errors, you catch "not what I meant"
+
+---
+
+## vs Other Approaches
+
+| Approach | Process | Result |
+|----------|---------|--------|
+| Vibe coding | Build → hope | Works until it doesn't |
+| Manual TDD | Write tests yourself | Slow, easy to skip |
+| **TDD Workflow** | Tests auto-generated first | Fast, guaranteed coverage |
+
+---
+
+## Install
+
+```bash
+npx tdd-claude-code
+```
+
+Options:
+- `--global` — Available everywhere
+- `--local` — This project only
 
-Running `npx get-shit-done-cc@latest` only touches GSD. Your TDD commands are untouched.
+---
 
 ## License
 

package/bin/install.js

@@ -26,9 +26,10 @@ ${c.cyan}  ████████╗██████╗ ██████
      ╚═╝   ╚═════╝ ╚═════╝${c.reset}
 `;
 
-const VERSION = '0.4.1';
+const VERSION = '0.5.0';
 
 const COMMANDS = [
+  'tdd.md',
   'new-project.md',
   'init.md',
   'coverage.md',
@@ -126,14 +127,15 @@ function install(targetDir, installType) {
   log('');
   log(`${c.green}Done!${c.reset} Restart Claude Code to load commands.`);
   log('');
-  log(`${c.bold}Workflow:${c.reset}`);
-  log(`  ${c.cyan}/tdd:new-project${c.reset}  Start project with test infrastructure`);
-  log(`  ${c.cyan}/tdd:discuss${c.reset}      Shape implementation preferences`);
-  log(`  ${c.cyan}/tdd:plan${c.reset}         Create task plans`);
-  log(`  ${c.cyan}/tdd:build${c.reset}        Write tests → implement → verify`);
-  log(`  ${c.cyan}/tdd:verify${c.reset}       Human acceptance testing`);
+  log(`${c.bold}Quick Start:${c.reset}`);
+  log(`  ${c.cyan}/tdd${c.reset}              Smart entry point - knows what to do next`);
   log('');
-  log(`Run ${c.cyan}/tdd:help${c.reset} for full command list.`);
+  log(`${c.dim}Or use specific commands:${c.reset}`);
+  log(`  ${c.cyan}/tdd:new-project${c.reset}  Start new project`);
+  log(`  ${c.cyan}/tdd:init${c.reset}         Add TDD to existing code`);
+  log(`  ${c.cyan}/tdd:coverage${c.reset}     Find and fix test gaps`);
+  log('');
+  log(`Run ${c.cyan}/tdd:help${c.reset} for all commands.`);
   log('');
 }
 

package/help.md

@@ -1,107 +1,115 @@
 # /tdd:help - Test-Led Development Commands
 
-TDD-first workflow powered by GSD. You use `/tdd:*` for everything — tests happen automatically.
+## Quick Start
 
-## Commands
+```
+/tdd
+```
 
-### Getting Started
+That's it. Detects where you are, tells you what's next.
 
-| Command | What It Does |
-|---------|--------------|
-| `/tdd:new-project` | Start new project with test infrastructure |
-| `/tdd:init` | Add TDD to existing codebase |
-| `/tdd:coverage` | Analyze gaps, write tests for existing code |
+---
+
+## All Commands
 
-### Core Workflow
+### The Smart One
 
 | Command | What It Does |
 |---------|--------------|
-| `/tdd:discuss [N]` | Capture implementation preferences for phase N |
-| `/tdd:plan [N]` | Research and create task plans for phase N |
-| `/tdd:build <N>` | **Write tests → implement → verify tests pass** |
-| `/tdd:verify [N]` | Human acceptance testing |
+| `/tdd` | **Context-aware entry point. Knows what to do next.** |
 
-### Navigation
+### Setup
 
 | Command | What It Does |
 |---------|--------------|
-| `/tdd:progress` | Where am I? What's next? |
-| `/tdd:status [N]` | Check test pass/fail counts |
-| `/tdd:help` | Show this help |
+| `/tdd:new-project` | Start new project (discusses stack, creates roadmap) |
+| `/tdd:init` | Add TDD to existing code |
+| `/tdd:coverage` | Find untested code, write tests |
 
-### Milestones
+### Build (rarely needed directly)
 
 | Command | What It Does |
 |---------|--------------|
-| `/tdd:complete` | Archive milestone, tag release |
-| `/tdd:new-milestone [name]` | Start next version |
+| `/tdd:discuss` | Shape implementation approach |
+| `/tdd:plan` | Create task plan |
+| `/tdd:build` | Write tests → implement → verify |
+| `/tdd:verify` | Human acceptance testing |
 
-### Quick Tasks
+### Utility
 
 | Command | What It Does |
 |---------|--------------|
-| `/tdd:quick` | Ad-hoc task with test-first flow |
+| `/tdd:status` | Test pass/fail counts |
+| `/tdd:quick` | One-off task with tests |
+| `/tdd:complete` | Tag release |
+| `/tdd:new-milestone` | Start next version |
+
+---
 
 ## Workflow
 
+**Simple version:**
 ```
-/tdd:new-project          New project from scratch
-       OR
-/tdd:init                 Existing codebase
-/tdd:coverage             Analyze gaps, write retro tests (optional)
-    ↓
-/tdd:discuss 1            Shape how phase 1 gets built
-/tdd:plan 1               Create task plans
-/tdd:build 1              Write tests → implement → tests pass
-/tdd:verify 1             Human acceptance testing
+/tdd                    <- just keep running this
+```
+
+**Detailed version:**
+```
+/tdd:new-project        New project
     ↓
-/tdd:discuss 2            Repeat for each phase...
-/tdd:plan 2
-/tdd:build 2
-/tdd:verify 2
+/tdd                    Guides you through each phase:
+                        → discuss → plan → build → verify
     ↓
-/tdd:complete             Tag release
-/tdd:new-milestone        Start v2
+/tdd:complete           Tag release
+```
+
+---
+
+## What `/tdd` Does
+
+Checks project state and presents ONE action:
+
 ```
+> /tdd
 
-## What Happens in `/tdd:build`
+Phase 2: User Dashboard
+Status: Planned, not built
 
-This is where TDD happens:
+4 tasks ready. Tests will be written first.
 
-1. **Red** — Write failing tests for each task in the plan
-2. **Verify** — Run tests, confirm they fail
-3. **Green** — Implement code (via GSD execute-phase)
-4. **Verify** — Run tests, confirm they pass
+→ Build phase 2? (Y/n)
+```
 
-You don't think about it. Just run `/tdd:build` and tests happen before code.
+Or if you have untested code:
 
-## Philosophy
+```
+> /tdd
 
-**Tests define behavior. Implementation makes tests pass.**
+Found 3 files without tests:
+  - src/utils/format.ts
+  - src/api/health.ts
+  - src/middleware/auth.ts
 
-- Tests are written BEFORE code exists
-- Tests are the spec, not an afterthought
-- Human verification still happens at the end
-- You never invoke GSD directly — TDD wraps it
+Add tests? (Y/n)
+```
 
-## GSD Under the Hood
+---
 
-TDD commands call GSD internally:
+## Philosophy
 
-| TDD Command | Calls |
-|-------------|-------|
-| `/tdd:new-project` | `/gsd:new-project` + test setup |
-| `/tdd:init` | scan + test setup (no GSD call) |
-| `/tdd:coverage` | scan + write tests (no GSD call) |
-| `/tdd:discuss` | `/gsd:discuss-phase` |
-| `/tdd:plan` | `/gsd:plan-phase` |
-| `/tdd:build` | write tests + `/gsd:execute-phase` |
-| `/tdd:verify` | test check + `/gsd:verify-work` |
+**Tests define behavior. Code makes tests pass.**
 
-GSD does the planning and execution. TDD ensures tests come first.
+- Tests written BEFORE code
+- Tests are the spec, not afterthought
+- Human verification still happens
+- No phase numbers to remember
+
+---
 
 ## Installation
 
-Lives in `.claude/commands/tdd/` — separate from GSD.
+```bash
+npx tdd-claude-code
+```
 
-GSD updates only touch `.claude/commands/gsd/`. Your TDD commands survive updates.
+Lives in `.claude/commands/tdd/`

package/new-project.md

@@ -4,14 +4,163 @@ Initialize a new project with test-led development.
 
 ## What This Does
 
-Calls `/gsd:new-project` with TDD conventions automatically added to PROJECT.md.
+1. Gather requirements and context
+2. Suggest tech stack based on your needs
+3. Create roadmap
+4. Set up test infrastructure
 
 ## Process
 
-1. **Run GSD new-project flow**
-   - Questions → Research → Requirements → Roadmap
-   
-2. **After PROJECT.md is created, append TDD conventions:**
+### Step 1: Understand What You're Building
+
+Start by understanding the project:
+
+**Core purpose:**
+```
+What are you building? (1-2 sentences)
+```
+
+**Target users:**
+```
+Who uses this?
+
+1) Just me / internal tool
+2) Small team (<10 users)
+3) Startup scale (100-10K users)
+4) Growth stage (10K-100K users)
+5) Enterprise / high scale (100K+ users)
+```
+
+**Data characteristics:**
+```
+What kind of data?
+
+1) Simple CRUD - users, posts, etc.
+2) Relational - complex relationships, joins
+3) Document-oriented - flexible schemas
+4) Time-series - logs, metrics, events
+5) Graph - relationships are the data
+6) Minimal / stateless
+```
+
+**Real-time requirements:**
+```
+Do you need real-time features?
+
+1) No - standard request/response
+2) Some - notifications, live updates
+3) Heavy - chat, collaboration, streaming
+```
+
+**Existing constraints:**
+```
+Any constraints I should know?
+
+- Team experience (what languages/tools do you know?)
+- Existing infrastructure (AWS, GCP, on-prem?)
+- Budget considerations
+- Compliance requirements (HIPAA, SOC2, etc.)
+- Timeline pressure
+```
+
+### Step 2: Suggest Tech Stack
+
+Based on answers, suggest appropriate stack:
+
+**Example: Internal tool, small team, simple CRUD**
+```
+Suggested Stack:
+
+| Component | Recommendation | Why |
+|-----------|----------------|-----|
+| Language | TypeScript | Type safety, good tooling |
+| Framework | Next.js | Full-stack, fast to build |
+| Database | SQLite or Postgres | Simple, reliable |
+| Architecture | Monolith | No need for complexity |
+| Hosting | Vercel or Railway | Easy deploy, free tier |
+
+Alternatives to consider:
+- Python + FastAPI if more comfortable with Python
+- Supabase if you want auth + DB bundled
+```
+
+**Example: Growth stage SaaS, real-time, complex data**
+```
+Suggested Stack:
+
+| Component | Recommendation | Why |
+|-----------|----------------|-----|
+| Language | TypeScript | Type safety at scale |
+| Framework | Next.js + tRPC | Type-safe API layer |
+| Database | PostgreSQL | Reliable, scalable |
+| Cache | Redis | Sessions, real-time |
+| Architecture | Modular monolith | Scale when needed |
+| Hosting | Docker + K8s ready | Portable, scalable |
+
+Alternatives to consider:
+- Go if performance is critical
+- Microservices if team is large enough
+```
+
+**Example: High-performance API, minimal latency**
+```
+Suggested Stack:
+
+| Component | Recommendation | Why |
+|-----------|----------------|-----|
+| Language | Go or Rust | Performance, efficiency |
+| Framework | stdlib or Axum | Minimal overhead |
+| Database | PostgreSQL + Redis | Speed + reliability |
+| Architecture | Microservices | Scale independently |
+| Hosting | Kubernetes | Production-grade |
+```
+
+### Step 3: Confirm or Adjust
+
+```
+Does this stack work for you?
+
+1) Yes, proceed with this
+2) I'd prefer [language] instead
+3) Let's discuss alternatives
+```
+
+Allow user to override any decision with rationale captured.
+
+### Step 4: Record Decisions
+
+Create PROJECT.md with tech decisions:
+
+```markdown
+# Project Name
+
+## Overview
+[From step 1 discussion]
+
+## Tech Stack
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Language | TypeScript | Team familiarity |
+| Framework | Next.js | Full-stack, good DX |
+| Database | PostgreSQL | Relational data needs |
+| Architecture | Modular monolith | Start simple |
+| Hosting | Docker + Railway | Easy CI/CD |
+
+## Constraints
+- Timeline: MVP in 4 weeks
+- Team: Solo developer
+- Budget: Minimal hosting costs
+```
+
+### Step 5: Run GSD for Roadmap
+
+Call `/gsd:new-project` internals to:
+- Generate requirements from discussion
+- Create phase-based roadmap
+- Define milestones
+
+### Step 6: Append TDD Conventions
 
 ```markdown
 ## Development Methodology: Test-Led Development
@@ -19,33 +168,31 @@ Calls `/gsd:new-project` with TDD conventions automatically added to PROJECT.md.
 This project uses TDD. All implementation follows Red → Green → Refactor:
 
 1. **Red**: Write failing tests that define expected behavior
-2. **Green**: Write minimum code to make tests pass  
+2. **Green**: Write minimum code to make tests pass
 3. **Refactor**: Clean up while keeping tests green
 
 Tests are written BEFORE implementation, not after.
-```
 
-3. **Detect or set up test framework** based on stack chosen during setup:
+## Test Framework
+- [Framework based on stack]
+- Run: `npm test` / `pytest` / `go test`
+```
 
-| Stack | Framework | Config |
-|-------|-----------|--------|
-| Next.js / React | Vitest | `vitest.config.ts` |
-| Node.js | Vitest or Jest | `vitest.config.ts` |
-| Python | pytest | `pytest.ini` or `pyproject.toml` |
-| Go | go test | (built-in) |
-| Ruby | RSpec | `.rspec`, `spec/spec_helper.rb` |
+### Step 7: Set Up Project Structure
 
-4. **Create test directory structure** if it doesn't exist:
-   - `tests/` or `__tests__/` or `spec/` depending on convention
-   - Example test file showing project patterns
+Scaffold based on chosen stack:
 
-5. **Add test script** to package.json / pyproject.toml / Makefile:
-   ```json
-   "scripts": {
-     "test": "vitest run",
-     "test:watch": "vitest"
-   }
-   ```
+```
+project/
+├── src/
+├── tests/
+├── .env.example
+├── docker-compose.yml
+├── Dockerfile
+├── [package.json | pyproject.toml | go.mod]
+├── [vitest.config.ts | pytest.ini]
+└── PROJECT.md
+```
 
 ## Usage
 
@@ -53,4 +200,9 @@ Tests are written BEFORE implementation, not after.
 /tdd:new-project
 ```
 
-Same interactive flow as GSD, but you end up with test infrastructure ready to go.
+Interactive flow that:
+1. Understands what you're building
+2. Suggests appropriate tech
+3. Lets you adjust
+4. Creates roadmap
+5. Sets up tests

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tdd-claude-code",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "TDD workflow for Claude Code - wraps GSD",
   "bin": {
     "tdd-claude-code": "./bin/install.js"

package/tdd.md

@@ -0,0 +1,215 @@
+# /tdd - Smart Entry Point
+
+One command. Context-aware. Tells you what to do next.
+
+## What This Does
+
+Detects project state and suggests the right action. No memorizing commands.
+
+## Process
+
+### Step 1: Detect Project State
+
+Check what exists:
+
+```
+□ PROJECT.md exists?
+□ .planning/ directory exists?
+□ .planning/ROADMAP.md exists?
+□ Test framework configured? (vitest.config.*, pytest.ini, etc.)
+□ Test files exist?
+□ Source files exist?
+```
+
+### Step 2: Route Based on State
+
+**No PROJECT.md → New or Init**
+```
+No project detected.
+
+1) Start new project (/tdd:new-project)
+2) Add TDD to existing code (/tdd:init)
+```
+
+**PROJECT.md exists, no roadmap → Need Planning**
+```
+Project exists but no roadmap.
+
+Creating phases for your project...
+[Run /gsd:new-project internals to create ROADMAP.md]
+```
+
+**Roadmap exists → Check Phase Status**
+
+Parse ROADMAP.md to find:
+- Completed phases: `[x]` or `[completed]`
+- Current phase: `[>]` or `[in progress]` or `[current]`
+- Next pending phase: first without marker
+
+### Step 3: Determine Current Phase Action
+
+For the current/next phase, check what exists:
+
+```
+Phase {N}: {Name}
+□ DISCUSSION.md exists? (.planning/phases/{N}-DISCUSSION.md)
+□ PLAN.md exists? (.planning/phases/{N}-*-PLAN.md)
+□ Tests written? (.planning/phases/{N}-TESTS.md or test files)
+□ Implementation done? (check if tests pass)
+□ Verified? (.planning/phases/{N}-VERIFIED.md)
+```
+
+### Step 4: Present Contextual Action
+
+Based on phase state, show ONE clear action:
+
+**Phase not discussed:**
+```
+Phase 2: User Dashboard
+
+Ready to discuss implementation approach.
+
+→ Continue? (Y/n)
+```
+Then run discuss flow.
+
+**Discussed but not planned:**
+```
+Phase 2: User Dashboard
+
+Discussion complete. Ready to create task plan.
+
+→ Continue? (Y/n)
+```
+Then run plan flow.
+
+**Planned but no tests:**
+```
+Phase 2: User Dashboard
+
+Plan ready. 4 tasks to implement.
+
+Next: Write tests, then build.
+
+→ Continue? (Y/n)
+```
+Then run build flow (tests first).
+
+**Tests written, not implemented:**
+```
+Phase 2: User Dashboard
+
+Tests ready (12 tests, all failing - expected).
+
+Next: Implement to make tests pass.
+
+→ Continue? (Y/n)
+```
+Then run implementation.
+
+**Implemented, not verified:**
+```
+Phase 2: User Dashboard
+
+Tests passing (12/12 ✓)
+
+Next: Human verification.
+
+→ Continue? (Y/n)
+```
+Then run verify flow.
+
+**Phase complete:**
+```
+Phase 2: User Dashboard ✓ Complete
+
+Moving to Phase 3: Reports
+
+→ Continue? (Y/n)
+```
+
+### Step 5: Check for Untested Code
+
+If project has source files without tests:
+
+```
+Found 5 files without tests:
+  - src/utils/helpers.ts
+  - src/api/users.ts
+  - src/services/email.ts
+  ...
+
+Add tests for existing code? (Y/n)
+```
+
+If yes, run `/tdd:coverage` flow.
+
+### Step 6: All Phases Complete
+
+```
+All phases complete! 🎉
+
+Milestone ready for release.
+
+1) Tag release (/tdd:complete)
+2) Start next milestone (/tdd:new-milestone)
+3) Check test coverage (/tdd:coverage)
+```
+
+## Examples
+
+**Fresh directory:**
+```
+> /tdd
+
+No project detected.
+
+What would you like to do?
+1) Start new project
+2) Add TDD to existing code
+```
+
+**Mid-project:**
+```
+> /tdd
+
+Phase 2: User Dashboard
+Status: Planned, not built
+
+4 tasks ready. Tests will be written first.
+
+→ Build phase 2? (Y/n)
+```
+
+**Has untested code:**
+```
+> /tdd
+
+Phase 3: Reports [current]
+
+Also found: 3 files without test coverage
+  - src/utils/format.ts
+  - src/api/health.ts
+  - src/middleware/auth.ts
+
+1) Continue with Phase 3
+2) Add tests to existing code first
+```
+
+## Usage
+
+```
+/tdd
+```
+
+No arguments. Auto-detects everything.
+
+## Why This Exists
+
+Instead of remembering:
+- `/tdd:discuss 2`
+- `/tdd:plan 2`
+- `/tdd:build 2`
+- `/tdd:verify 2`
+
+Just run `/tdd`. It knows where you are.