@hustle-together/api-dev-tools 3.6.1 → 3.6.4

package/README.md

@@ -1,4 +1,4 @@
-# API Development Tools for Claude Code v3.6.1
+# API Development Tools for Claude Code v3.6.4
 
 **Interview-driven, research-first API development with 100% phase enforcement**
 
@@ -7,7 +7,7 @@
 │ ❯ npx @hustle-together/api-dev-tools         │
 │         --scope=project                      │
 │                                              │
-│ 🚀 Installing v3.6.1...                      │
+│ 🚀 Installing v3.6.4...                      │
 │                                              │
 │ ✅ Python 3.12.0                             │
 │ 📦 24 slash commands                         │
@@ -17,9 +17,9 @@
 │ 📚 research cache ready                      │
 │ 🔌 MCP: context7, github                     │
 │                                              │
-│ ═════════════════════════════════════        │
+│ ════════════════════════════════════════════ │
 │ 🎉 Installation complete!                    │
-│ ═════════════════════════════════════        │
+│ ════════════════════════════════════════════ │
 │                                              │
 │ Quick Start: /api-create my-endpoint         │
 └──────────────────────────────────────────────┘
@@ -39,17 +39,17 @@ When developers use Claude (or any LLM) to build APIs, five predictable failure
 
 1. **Outdated Documentation** - LLMs use training data from months or years ago. APIs change constantly - endpoints get deprecated, parameters are renamed, authentication methods evolve. Building from stale knowledge means broken code.
 
-2. **Memory-Based Implementation** - Even after doing research, Claude often implements from memory by the time it gets to Phase 8 (writing code). It forgets the specific parameter names, error codes, and edge cases it discovered 20 messages ago.
+2. **Memory-Based Implementation** - Even after doing research, Claude often implements from memory by the time it gets to Phase 9 (writing code). It forgets the specific parameter names, error codes, and edge cases it discovered 20 messages ago.
 
 3. **Self-Answering Questions** - Claude asks "Which format do you want?" then immediately answers "I'll use JSON" without waiting for your response. You lose control of the decision-making process.
 
-4. **Context Dilution** - In a 50-message session, the context from Phase 3 (research) is diluted by Phase 9 (implementation). Critical details get lost. Claude starts guessing instead of referencing research.
+4. **Context Dilution** - In a 50-message session, the context from Phase 4 (research) is diluted by Phase 10 (implementation). Critical details get lost. Claude starts guessing instead of referencing research.
 
 5. **Skipped Steps** - Without enforcement, Claude jumps directly to implementation. No tests. No verification. No documentation. You get code that "works" but fails in production because edge cases weren't tested.
 
 ### Our Solution
 
-**A 12-phase workflow enforced by Python hooks that BLOCK progress** until each phase is complete with explicit user approval. Not suggestions. Not guidelines. **Hard stops using Exit Code 2.**
+**A 13-phase workflow enforced by Python hooks that BLOCK progress** until each phase is complete with explicit user approval. Not suggestions. Not guidelines. **Hard stops using Exit Code 2.**
 
 This means:
 - Claude cannot skip research
@@ -62,9 +62,9 @@ Every decision is tracked. Every phase is verified. Every step is enforced.
 
 ---
 
-## The 12-Phase Workflow
+## The 13-Phase Workflow
 
-When you run `/api-create brandfetch`, Claude is guided through 12 enforced phases. Each phase has three components:
+When you run `/api-create brandfetch`, Claude is guided through 13 enforced phases. Each phase has three components:
 
 1. **The Problem** - What goes wrong without enforcement
 2. **The Solution** - How the phase prevents the problem
@@ -72,7 +72,7 @@ When you run `/api-create brandfetch`, Claude is guided through 12 enforced phas
 
 ---
 
-### Phase 0: Disambiguation
+### Phase 1: Disambiguation
 
 **The Problem We're Solving:**
 Ambiguous terms waste hours of work. When you say "brandfetch," do you mean:
@@ -121,7 +121,7 @@ Five seconds of clarification saves an hour of wasted research. Everyone starts
 ---
 
 <details>
-<summary><strong>Phase 1: Scope Confirmation</strong></summary>
+<summary><strong>Phase 2: Scope Confirmation</strong></summary>
 
 **The Problem We're Solving:**
 Misunderstood requirements lead to wrong implementations. You say "fetch brand assets" but Claude thinks you want a full-featured CMS with caching, authentication, rate limiting, and database persistence. Or worse - Claude thinks you want something simpler and omits features you need.
@@ -174,7 +174,7 @@ Requirements locked in before research begins. No backtracking. No "wait, that's
 ---
 
 <details>
-<summary><strong>Phase 2: Initial Research</strong></summary>
+<summary><strong>Phase 3: Initial Research</strong></summary>
 
 **The Problem We're Solving:**
 Training data is stale. Claude's knowledge cutoff might be January 2024, but the Brandfetch API was updated in March 2024 with new rate limit headers. Building from outdated knowledge means broken integrations.
@@ -258,7 +258,7 @@ Current, accurate documentation prevents integration failures. Cross-referencing
 ---
 
 <details>
-<summary><strong>Phase 3: Structured Interview</strong></summary>
+<summary><strong>Phase 4: Structured Interview</strong></summary>
 
 **The Problem We're Solving:**
 Generic template questions don't reflect actual API capabilities. Without research, Claude asks:
@@ -337,7 +337,7 @@ The hook monitors tool calls:
 ```
 
 **Critical Insight:**
-These decisions are saved and automatically injected during implementation phases. When Claude writes tests (Phase 7), it references `decisions.error_handling = "return_objects"` to know what to test. When implementing (Phase 8), it uses `decisions.caching = "24h"` to set cache headers.
+These decisions are saved and automatically injected during implementation phases. When Claude writes tests (Phase 8), it references `decisions.error_handling = "return_objects"` to know what to test. When implementing (Phase 9), it uses `decisions.caching = "24h"` to set cache headers.
 
 Your choices drive the entire implementation. No guessing. No forgetting.
 
@@ -349,7 +349,7 @@ Questions based on research prevent impossible requirements. Interview answers b
 ---
 
 <details>
-<summary><strong>Phase 4: Deep Research</strong></summary>
+<summary><strong>Phase 5: Deep Research</strong></summary>
 
 **The Problem We're Solving:**
 Initial research provides the overview, but your specific choices need deeper investigation. You chose "Expose rate limit headers" - but which headers does Brandfetch actually return? You chose "Return error objects" - but what's the exact structure?
@@ -442,7 +442,7 @@ Targeted research prevents assumption-based implementation. You get exact header
 ---
 
 <details>
-<summary><strong>Phase 5: Schema Creation</strong></summary>
+<summary><strong>Phase 6: Schema Creation</strong></summary>
 
 **The Problem We're Solving:**
 Without a contract between tests and implementation, they drift apart. Tests check for `logoUrl` but implementation returns `logo_url`. Tests expect 400 errors but implementation returns 500. The API "works" but doesn't match the spec.
@@ -538,7 +538,7 @@ Type safety from research to production. Tests verify the schema. Implementation
 ---
 
 <details>
-<summary><strong>Phase 6: Environment Check</strong></summary>
+<summary><strong>Phase 7: Environment Check</strong></summary>
 
 **The Problem We're Solving:**
 Tests pass locally but fail in CI. Why? Missing `BRANDFETCH_API_KEY` environment variable. You waste 30 minutes debugging, checking logs, re-running tests, before realizing the environment isn't set up.
@@ -618,7 +618,7 @@ No surprises in CI. No mock/real API drift. Tests run with real API calls from d
 ---
 
 <details>
-<summary><strong>Phase 7: TDD Red (Write Failing Tests)</strong></summary>
+<summary><strong>Phase 8: TDD Red (Write Failing Tests)</strong></summary>
 
 **The Problem We're Solving:**
 Without tests, you don't know if your code works. You ship bugs. You break things in production. You discover edge cases after users report them.
@@ -726,7 +726,7 @@ Tests first means bugs are caught before code is written. Requirements are encod
 ---
 
 <details>
-<summary><strong>Phase 8: TDD Green (Make Tests Pass)</strong></summary>
+<summary><strong>Phase 9: TDD Green (Make Tests Pass)</strong></summary>
 
 **The Problem We're Solving:**
 Over-engineering wastes time. Developers often write more code than needed:
@@ -866,10 +866,10 @@ Minimal code = minimal bugs. Tests define "done." If tests pass, you're done. No
 ---
 
 <details>
-<summary><strong>Phase 9: Verification (Re-Research After Green)</strong></summary>
+<summary><strong>Phase 10: Verification (Re-Research After Green)</strong></summary>
 
 **The Problem We're Solving:**
-Even after researching in Phase 2, Claude implements from memory in Phase 8. Twenty messages have passed. Context has diluted. Claude forgets specific details:
+Even after researching in Phase 3, Claude implements from memory in Phase 9. Twenty messages have passed. Context has diluted. Claude forgets specific details:
 - Used `format` parameter but docs say `imageFormat`
 - Returned `logo_url` but API returns `logoUrl`
 - Forgot that API supports `include_fonts` parameter
@@ -963,7 +963,7 @@ Verification loop ensures implementation matches current docs. Memory errors cau
 ---
 
 <details>
-<summary><strong>Phase 10: TDD Refactor</strong></summary>
+<summary><strong>Phase 11: TDD Refactor</strong></summary>
 
 **The Problem We're Solving:**
 First implementations are messy. Variable names are unclear. Logic is duplicated. Comments are missing. But cleaning up code might break things - you change a condition, forget a case, introduce a regression.
@@ -1077,7 +1077,7 @@ Refactor confidently. Tests prove nothing broke. Code gets cleaner without risk.
 ---
 
 <details>
-<summary><strong>Phase 11: Documentation</strong></summary>
+<summary><strong>Phase 12: Documentation</strong></summary>
 
 **The Problem We're Solving:**
 Knowledge gets lost. The next developer (or the next Claude session) starts from scratch:
@@ -1231,13 +1231,13 @@ Knowledge compounds instead of resetting.
 ---
 
 <details>
-<summary><strong>Phase 12: Completion</strong></summary>
+<summary><strong>Phase 13: Completion</strong></summary>
 
 **The Problem We're Solving:**
 How do you know everything is actually done? Claude might claim "finished" but skip phases:
-- Skipped verification (Phase 9)
-- Forgot documentation (Phase 11)
-- Never wrote tests (Phase 7)
+- Skipped verification (Phase 10)
+- Forgot documentation (Phase 12)
+- Never wrote tests (Phase 8)
 
 Without verification, "done" means "Claude stopped talking" not "workflow complete."
 
@@ -1247,19 +1247,19 @@ The `api-workflow-check.py` hook runs on Stop event (when you try to close Claud
 ```
 Checking workflow completion...
 
-Phase 0: Disambiguation       ✅ Complete
-Phase 1: Scope                ✅ Complete
-Phase 2: Research             ✅ Complete (2 sources)
-Phase 3: Interview            ✅ Complete (5 questions)
-Phase 4: Deep Research        ✅ Complete (3 searches)
-Phase 5: Schema               ✅ Complete
-Phase 6: Environment          ✅ Complete (1 key)
-Phase 7: TDD Red              ✅ Complete (10 tests)
-Phase 8: TDD Green            ✅ Complete (10/10 passing)
-Phase 9: Verification         ✅ Complete (1 omission)
-Phase 10: Refactor            ✅ Complete
-Phase 11: Documentation       ✅ Complete
-Phase 12: Completion          ✅ In progress
+Phase 1: Disambiguation       ✅ Complete
+Phase 2: Scope                ✅ Complete
+Phase 3: Research             ✅ Complete (2 sources)
+Phase 4: Interview            ✅ Complete (5 questions)
+Phase 5: Deep Research        ✅ Complete (3 searches)
+Phase 6: Schema               ✅ Complete
+Phase 7: Environment          ✅ Complete (1 key)
+Phase 8: TDD Red              ✅ Complete (10 tests)
+Phase 9: TDD Green            ✅ Complete (10/10 passing)
+Phase 10: Verification        ✅ Complete (1 omission)
+Phase 11: Refactor            ✅ Complete
+Phase 12: Documentation       ✅ Complete
+Phase 13: Completion          ✅ In progress
 
 All phases verified. Workflow complete.
 
@@ -1532,7 +1532,7 @@ Automatically installed by `npx @hustle-together/api-dev-tools`:
 ### Automatic Re-grounding
 
 **The Problem:**
-Long sessions lose context. Phase 3 (interview) happens at turn 15. Phase 9 (verification) happens at turn 47. By turn 47, Claude has forgotten your interview decisions from turn 15.
+Long sessions lose context. Phase 4 (interview) happens at turn 15. Phase 10 (verification) happens at turn 47. By turn 47, Claude has forgotten your interview decisions from turn 15.
 
 **The Solution:**
 `periodic-reground.py` re-injects state summary every 7 turns.
@@ -1582,13 +1582,13 @@ Research shows context dilution accelerates after 7-10 messages. Re-grounding ev
 ## File Structure
 
 ```
-@hustle-together/api-dev-tools v3.6.1
+@hustle-together/api-dev-tools v3.6.4
 │
 ├── bin/
 │   └── cli.js                         # NPX installer
 │
 ├── commands/                          # 24 slash commands
-│   ├── api-create.md                  # Main 12-phase workflow
+│   ├── api-create.md                  # Main 13-phase workflow
 │   ├── api-interview.md               # Structured interview
 │   ├── api-research.md                # Adaptive research
 │   ├── api-verify.md                  # Manual verification
@@ -1622,29 +1622,29 @@ Research shows context dilution accelerates after 7-10 messages. Re-grounding ev
 │   ├── enforce-external-research.py   # Detect API terms, require research
 │   │
 │   │ # PreToolUse (Write/Edit) - BLOCKING
-│   ├── enforce-disambiguation.py      # Phase 0
-│   ├── enforce-scope.py               # Phase 1
-│   ├── enforce-research.py            # Phase 2
-│   ├── enforce-interview.py           # Phase 3
-│   ├── enforce-deep-research.py       # Phase 4
-│   ├── enforce-schema.py              # Phase 5
-│   ├── enforce-environment.py         # Phase 6
-│   ├── enforce-tdd-red.py             # Phase 7
-│   ├── verify-implementation.py       # Phase 8 helper
-│   ├── enforce-verify.py              # Phase 9
-│   ├── enforce-refactor.py            # Phase 10
-│   ├── enforce-documentation.py       # Phase 11
+│   ├── enforce-disambiguation.py      # Phase 1
+│   ├── enforce-scope.py               # Phase 2
+│   ├── enforce-research.py            # Phase 3
+│   ├── enforce-interview.py           # Phase 4
+│   ├── enforce-deep-research.py       # Phase 5
+│   ├── enforce-schema.py              # Phase 6
+│   ├── enforce-environment.py         # Phase 7
+│   ├── enforce-tdd-red.py             # Phase 8
+│   ├── verify-implementation.py       # Phase 9 helper
+│   ├── enforce-verify.py              # Phase 10
+│   ├── enforce-refactor.py            # Phase 11
+│   ├── enforce-documentation.py       # Phase 12
 │   │
 │   │ # PostToolUse - TRACKING
 │   ├── track-tool-use.py              # Log all tool usage
 │   ├── periodic-reground.py           # Re-inject context every 7 turns
-│   ├── verify-after-green.py          # Auto-trigger Phase 9
+│   ├── verify-after-green.py          # Auto-trigger Phase 10
 │   │
 │   │ # Stop - BLOCKING
-│   └── api-workflow-check.py          # Phase 12 (block if incomplete)
+│   └── api-workflow-check.py          # Phase 13 (block if incomplete)
 │
 ├── templates/
-│   ├── api-dev-state.json             # 12 phases + phase_exit_confirmed
+│   ├── api-dev-state.json             # 13 phases + phase_exit_confirmed
 │   ├── settings.json                  # Hook registrations
 │   ├── research-index.json            # 7-day freshness tracking
 │   └── CLAUDE-SECTION.md              # CLAUDE.md injection
@@ -1804,11 +1804,18 @@ npx @hustle-together/api-dev-tools --scope=project
 
 ---
 
+## What's New in v3.6.4
+
+### 1-Indexed Phase Numbering
+- Changed from 0-indexed (Phase 0-12) to 1-indexed (Phase 1-13)
+- More human-readable: Phase 1 starts the workflow, Phase 13 completes it
+- All documentation, hooks, and demo updated consistently
+
 ## What's New in v3.6.1
 
 ### README Improvements
 - Removed verbose ASCII workflow simulations (was 798 lines)
-- Added comprehensive explanations for all 12 phases
+- Added comprehensive explanations for all 13 phases
 - Detailed sections on Exit Code 2, Context7, phase_exit_confirmed
 - Better mobile/narrow display formatting (50-char width ASCII)
 - Collapsible sections for easier scanning

package/bin/cli.js

@@ -482,7 +482,7 @@ function main() {
   log('   Test UI:   /api-test page + /api/test-structure API (if Next.js)', 'blue');
 
   log('\n🆕 New in v3.0:', 'bright');
-  log('   • 12 phases, each with mandatory user checkpoint', 'cyan');
+  log('   • 13 phases, each with mandatory user checkpoint', 'cyan');
   log('   • AskUserQuestion required at EVERY phase transition', 'cyan');
   log('   • Loop-back support when user wants changes', 'cyan');
   log('   • Adaptive research (propose-approve, not shotgun)', 'cyan');
@@ -490,24 +490,24 @@ function main() {
   log('   • Research freshness (7-day cache validity)', 'cyan');
 
   log('\n🔒 User Checkpoint Enforcement:', 'bright');
-  log('   • Phase 0: "Which interpretation?" (disambiguation)', 'cyan');
-  log('   • Phase 1: "Scope correct?" (scope confirmation)', 'cyan');
-  log('   • Phase 2: "Proceed to interview?" (research summary)', 'cyan');
-  log('   • Phase 3: "Interview complete?" (all questions answered)', 'cyan');
-  log('   • Phase 4: "Approve searches?" (deep research proposal)', 'cyan');
-  log('   • Phase 5: "Schema matches interview?" (schema review)', 'cyan');
-  log('   • Phase 6: "Ready for testing?" (environment check)', 'cyan');
-  log('   • Phase 7: "Test plan looks good?" (test matrix)', 'cyan');
-  log('   • Phase 9: "Fix gaps?" (verification decision)', 'cyan');
-  log('   • Phase 11: "Documentation complete?" (final checklist)', 'cyan');
+  log('   • Phase 1: "Which interpretation?" (disambiguation)', 'cyan');
+  log('   • Phase 2: "Scope correct?" (scope confirmation)', 'cyan');
+  log('   • Phase 3: "Proceed to interview?" (research summary)', 'cyan');
+  log('   • Phase 4: "Interview complete?" (all questions answered)', 'cyan');
+  log('   • Phase 5: "Approve searches?" (deep research proposal)', 'cyan');
+  log('   • Phase 6: "Schema matches interview?" (schema review)', 'cyan');
+  log('   • Phase 7: "Ready for testing?" (environment check)', 'cyan');
+  log('   • Phase 8: "Test plan looks good?" (test matrix)', 'cyan');
+  log('   • Phase 10: "Fix gaps?" (verification decision)', 'cyan');
+  log('   • Phase 12: "Documentation complete?" (final checklist)', 'cyan');
 
   log('\n📚 Available Commands:', 'bright');
-  log('  /api-create [endpoint]    - Complete 12-phase workflow', 'blue');
+  log('  /api-create [endpoint]    - Complete 13-phase workflow', 'blue');
   log('  /api-interview [endpoint] - Questions FROM research', 'blue');
   log('  /api-research [library]   - Adaptive propose-approve research', 'blue');
-  log('  /api-verify [endpoint]    - Manual Phase 9 verification', 'blue');
+  log('  /api-verify [endpoint]    - Manual Phase 10 verification', 'blue');
   log('  /api-env [endpoint]       - Check API keys and environment', 'blue');
-  log('  /api-status [endpoint]    - Track 12-phase progress', 'blue');
+  log('  /api-status [endpoint]    - Track 13-phase progress', 'blue');
 
   log('\n🚀 Quick Start:', 'bright');
   log('   /api-create my-endpoint', 'blue');

package/commands/README.md

@@ -4,8 +4,8 @@
 
 ## What's New in v3.0
 
-- **Phase 0: Disambiguation** - Search variations before research
-- **Phase 9: Verify** - Re-research after tests pass to catch memory errors
+- **Phase 1: Disambiguation** - Search variations before research
+- **Phase 10: Verify** - Re-research after tests pass to catch memory errors
 - **Adaptive Research** - Propose searches based on context, not shotgun
 - **Questions FROM Research** - Interview generates questions from discovered params
 - **7-Turn Re-grounding** - Periodic context injection prevents dilution
@@ -22,7 +22,7 @@
 | `verify-implementation.py` | PreToolUse | Require test file before route |
 | `track-tool-use.py` | PostToolUse | Log research, count turns |
 | `periodic-reground.py` | PostToolUse | Re-ground every 7 turns |
-| `verify-after-green.py` | PostToolUse | Trigger Phase 9 after test pass |
+| `verify-after-green.py` | PostToolUse | Trigger Phase 10 after test pass |
 | `api-workflow-check.py` | Stop | Block if phases incomplete |
 
 ## Available Commands
@@ -30,7 +30,7 @@
 ### Complete Workflow
 
 **`/api-create [endpoint-name]`**
-- Runs all 12 phases automatically
+- Runs all 13 phases automatically
 - Loop-back architecture at every checkpoint
 - See [api-create.md](api-create.md) for full flow
 
@@ -47,7 +47,7 @@
 - See [api-research.md](api-research.md)
 
 **`/api-verify [endpoint-name]`** (NEW)
-- Manual Phase 9 verification
+- Manual Phase 10 verification
 - Re-read docs, compare to implementation
 - Report gaps, loop back or document omissions
 - See [api-verify.md](api-verify.md)
@@ -57,7 +57,7 @@
 - See [api-env.md](api-env.md)
 
 **`/api-status [endpoint-name]`**
-- Track progress through 12 phases
+- Track progress through 13 phases
 - See [api-status.md](api-status.md)
 
 ### TDD Commands
@@ -68,22 +68,22 @@ From [@wbern/claude-instructions](https://github.com/wbern/claude-instructions):
 - `/refactor` - Clean up while tests pass
 - `/cycle [description]` - Full Red → Green → Refactor
 
-## 12-Phase Flow
+## 13-Phase Flow
 
 ```
-Phase 0:  DISAMBIGUATION     - Clarify ambiguous terms
-Phase 1:  SCOPE              - Confirm understanding
-Phase 2:  INITIAL RESEARCH   - 2-3 targeted searches
-Phase 3:  INTERVIEW          - Questions FROM research
-Phase 4:  DEEP RESEARCH      - Adaptive propose-approve
-Phase 5:  SCHEMA             - Zod from research + interview
-Phase 6:  ENVIRONMENT        - Verify API keys
-Phase 7:  TDD RED            - Write failing tests
-Phase 8:  TDD GREEN          - Minimal implementation
-Phase 9:  VERIFY             - Re-research, find gaps
-Phase 10: TDD REFACTOR       - Clean up code
-Phase 11: DOCUMENTATION      - Update manifests
-Phase 12: COMPLETION         - Final verification
+Phase 1:  DISAMBIGUATION     - Clarify ambiguous terms
+Phase 2:  SCOPE              - Confirm understanding
+Phase 3:  INITIAL RESEARCH   - 2-3 targeted searches
+Phase 4:  INTERVIEW          - Questions FROM research
+Phase 5:  DEEP RESEARCH      - Adaptive propose-approve
+Phase 6:  SCHEMA             - Zod from research + interview
+Phase 7:  ENVIRONMENT        - Verify API keys
+Phase 8:  TDD RED            - Write failing tests
+Phase 9:  TDD GREEN          - Minimal implementation
+Phase 10: VERIFY             - Re-research, find gaps
+Phase 11: TDD REFACTOR       - Clean up code
+Phase 12: DOCUMENTATION      - Update manifests
+Phase 13: COMPLETION         - Final verification
 ```
 
 ## State File

package/commands/api-create.md

@@ -370,7 +370,7 @@ Both conditions must be true for the flag to be set.
 │                                                           │
 │ WAIT for user response. Do NOT auto-decide.               │
 │ HOOK: PostToolUse triggers after test pass                │
-│ ──── Loop back to Phase 7 if user wants fixes ────        │
+│ ──── Loop back to Phase 8 if user wants fixes ────        │
 └───────────────────────────────────────────────────────────┘
         │
         ▼
@@ -489,11 +489,11 @@ This command creates:
 
 ## Never Skip
 
-- Phase 0 (Disambiguation) - Clarify before research
-- Phase 2 (Initial Research) - Find ALL parameters
-- Phase 3 (Interview) - Questions FROM research, not templates
-- Phase 7 (TDD Red) - Failing tests FIRST
-- Phase 9 (Verify) - Re-research after Green
-- Phase 11 (Documentation) - Keep docs in sync
+- Phase 1 (Disambiguation) - Clarify before research
+- Phase 3 (Initial Research) - Find ALL parameters
+- Phase 4 (Interview) - Questions FROM research, not templates
+- Phase 8 (TDD Red) - Failing tests FIRST
+- Phase 10 (Verify) - Re-research after Green
+- Phase 12 (Documentation) - Keep docs in sync
 - Coverage verification - 100% required
 </claude-commands-template>

package/commands/api-interview.md

@@ -35,7 +35,7 @@ Based on research, Brandfetch API has 7 parameters:
 
 ## Interview Flow
 
-### Phase 0: PREREQUISITE - Research Must Be Complete
+### PREREQUISITE - Research Must Be Complete (Phase 3)
 
 **Interview is BLOCKED until research is done.**
 
@@ -52,7 +52,7 @@ Discovered parameters:
   - 2 continuous ranges
 ```
 
-### Phase 1: Parameter-Based Questions
+### Parameter-Based Questions
 
 For each discovered parameter, generate an appropriate question:
 
@@ -119,7 +119,7 @@ For each discovered parameter, generate an appropriate question:
 └────────────────────────────────────────────────────────────┘
 ```
 
-### Phase 2: Feature Questions
+### Feature Questions
 
 Based on discovered features, ask about priorities:
 
@@ -139,7 +139,7 @@ Based on discovered features, ask about priorities:
 └────────────────────────────────────────────────────────────┘
 ```
 
-### Phase 3: Error Handling Questions
+### Error Handling Questions
 
 ```
 ┌────────────────────────────────────────────────────────────┐
@@ -162,7 +162,7 @@ Based on discovered features, ask about priorities:
 └────────────────────────────────────────────────────────────┘
 ```
 
-### Phase 4: Deep Research Proposal
+### Deep Research Proposal (Phase 5)
 
 After interview, propose additional research:
 

package/commands/api-research.md

@@ -18,7 +18,7 @@
 
 ## Research Phases
 
-### Phase 1: Initial Discovery (Automatic)
+### Initial Discovery (Automatic)
 
 Run 2-3 targeted searches:
 ```
@@ -47,7 +47,7 @@ Present initial summary:
 └────────────────────────────────────────────────────────────┘
 ```
 
-### Phase 2: Deep Research (Proposed)
+### Deep Research (Proposed)
 
 After interview, PROPOSE targeted searches based on user's selections:
 
@@ -78,7 +78,7 @@ After interview, PROPOSE targeted searches based on user's selections:
 └────────────────────────────────────────────────────────────┘
 ```
 
-### Phase 3: Execute Approved Searches
+### Execute Approved Searches
 
 Only run searches that were explicitly approved:
 - Track which searches were proposed vs approved vs skipped
@@ -257,7 +257,7 @@ Creates: `.claude/research/[library-name]/CURRENT.md`
    - Every field has a source (docs, SDK types, API response)
    - Don't guess - verify each capability
 
-3. **Verify with Phase 9**
+3. **Verify with Phase 10**
    - After implementation, re-research
    - Compare docs to implementation
    - Fix gaps or document intentional omissions
@@ -324,8 +324,8 @@ All research is tracked in `.claude/api-dev-state.json`:
 
 ## Integration with API Development
 
-- Phase 2 of `/api-create` uses this for initial research
-- Phase 4 uses adaptive proposal flow
-- Phase 9 (Verify) triggers re-research
+- Phase 3 of `/api-create` uses this for initial research
+- Phase 5 uses adaptive proposal flow
+- Phase 10 (Verify) triggers re-research
 - Freshness check prevents stale data
 </claude-commands-template>

package/commands/api-verify.md

@@ -1,8 +1,8 @@
-# API Verify - Implementation Verification (Phase 9) v3.0
+# API Verify - Implementation Verification (Phase 10) v3.0
 
 **Usage:** `/api-verify [endpoint-name]`
 
-**Purpose:** Manually trigger Phase 9 verification - re-research documentation and compare to implementation to catch memory-based errors.
+**Purpose:** Manually trigger Phase 10 verification - re-research documentation and compare to implementation to catch memory-based errors.
 
 ## When to Use
 
@@ -170,7 +170,7 @@ Creates: `.claude/research/[api-name]/verification.md`
 ## Intentional Omissions
 
 1. **webhook support**
-   - Reason: User declined in interview (Phase 3)
+   - Reason: User declined in interview (Phase 4)
    - Decision recorded: api-dev-state.json
    - May add in v2
 
@@ -197,17 +197,17 @@ Manual invocation is useful when:
 ## Workflow Position
 
 ```
-Phase 7: TDD Red (write tests)
+Phase 8: TDD Red (write tests)
     │
     ▼
-Phase 8: TDD Green (implementation)
+Phase 9: TDD Green (implementation)
     │
     ▼
-Phase 9: VERIFY ← /api-verify triggers this
+Phase 10: VERIFY ← /api-verify triggers this
     │
-    ├─► Gaps found? → Loop back to Phase 7
+    ├─► Gaps found? → Loop back to Phase 8
     │
-    └─► All verified → Proceed to Phase 10 (Refactor)
+    └─► All verified → Proceed to Phase 11 (Refactor)
 ```
 
 <claude-commands-template>