@hustle-together/api-dev-tools 3.0.0 → 3.1.0

package/README.md

@@ -26,6 +26,22 @@ npx @hustle-together/api-dev-tools --scope=project
 
 ## What This Installs
 
+```
+.claude/
+├── commands/          # Slash commands (*.md)
+├── hooks/             # Enforcement hooks (*.py)
+├── settings.json      # Hook configuration
+├── api-dev-state.json # Workflow state tracking
+└── research/          # Cached research with freshness
+
+scripts/
+└── api-dev-tools/     # Manifest generation scripts (*.ts)
+
+src/app/
+├── api-test/          # Test UI page (if Next.js)
+└── api/test-structure/# Parser API route (if Next.js)
+```
+
 ### Slash Commands
 
 Six powerful slash commands for Claude Code:
@@ -59,6 +75,20 @@ Python hooks that provide **real programmatic guarantees**:
 - **`.claude/research/`** - Cached research with freshness tracking
 - **`.claude/research/index.json`** - Research catalog with 7-day validity
 
+### Manifest Generation Scripts (Programmatic, NO LLM)
+
+Scripts that automatically generate documentation from test files:
+
+| Script | Output | Purpose |
+|--------|--------|---------|
+| `generate-test-manifest.ts` | `api-tests-manifest.json` | Parses Vitest tests → full API manifest |
+| `extract-parameters.ts` | `parameter-matrix.json` | Extracts Zod params → coverage matrix |
+| `collect-test-results.ts` | `test-results.json` | Runs tests → results with pass/fail |
+
+**Key principle:** Tests are the SOURCE OF TRUTH. Scripts parse source files programmatically. **NO LLM involvement** in manifest generation.
+
+Scripts are triggered automatically after tests pass (Phase 8 → Phase 9) via `verify-after-green.py` hook.
+
 ## Complete Phase Flow (12 Phases)
 
 ```
@@ -115,6 +145,16 @@ Python hooks that provide **real programmatic guarantees**:
         ▼
 ┌─ PHASE 8: TDD GREEN ──────────────────────────┐
 │ Minimal implementation to pass tests          │
+└───────────────────────────────────────────────┘
+        │
+        ▼
+┌─ MANIFEST GENERATION (Automatic) ─────────────┐
+│ verify-after-green.py hook triggers:          │
+│ • generate-test-manifest.ts                   │
+│ • extract-parameters.ts                       │
+│ • collect-test-results.ts                     │
+│                                               │
+│ Output: api-tests-manifest.json (NO LLM)      │
 └───────────────────────────────────────────────┘
         │
         ▼
@@ -302,6 +342,17 @@ Progress tracking. See [commands/api-status.md](commands/api-status.md).
     "tdd_refactor": { "status": "complete" },
     "documentation": { "status": "complete" }
   },
+  "manifest_generation": {
+    "last_run": "2025-12-09T10:30:00.000Z",
+    "manifest_generated": true,
+    "parameters_extracted": true,
+    "test_results_collected": true,
+    "output_files": {
+      "manifest": "src/app/api-test/api-tests-manifest.json",
+      "parameters": "src/app/api-test/parameter-matrix.json",
+      "results": "src/app/api-test/test-results.json"
+    }
+  },
   "reground_history": [
     { "turn": 7, "phase": "interview" },
     { "turn": 14, "phase": "tdd_red" }
@@ -351,6 +402,26 @@ Progress tracking. See [commands/api-status.md](commands/api-status.md).
 └──────────────────────────────────────────────────────────┘
 ```
 
+## Manual Script Usage
+
+While scripts run automatically after tests pass, you can also run them manually:
+
+```bash
+# Generate manifest from test files
+npx tsx scripts/api-dev-tools/generate-test-manifest.ts
+
+# Extract parameters and calculate coverage
+npx tsx scripts/api-dev-tools/extract-parameters.ts
+
+# Collect test results (runs Vitest)
+npx tsx scripts/api-dev-tools/collect-test-results.ts
+```
+
+Output files are written to `src/app/api-test/`:
+- `api-tests-manifest.json` - Complete API documentation
+- `parameter-matrix.json` - Parameter coverage analysis
+- `test-results.json` - Latest test run results
+
 ## Requirements
 
 - **Node.js** 14.0.0 or higher

package/bin/cli.js

@@ -69,15 +69,29 @@ function verifyInstallation(claudeDir, hooksDir) {
     { path: path.join(claudeDir, 'research', 'index.json'), name: 'Research index' },
   ];
 
-  // Add hook checks if hooks directory exists (v3.0 has 9 hooks)
+  // Add hook checks if hooks directory exists (v3.0 has 18 hooks for 100% phase enforcement with user checkpoints)
   if (fs.existsSync(hooksDir)) {
     checks.push(
-      { path: path.join(hooksDir, 'enforce-research.py'), name: 'enforce-research.py' },
-      { path: path.join(hooksDir, 'track-tool-use.py'), name: 'track-tool-use.py' },
-      { path: path.join(hooksDir, 'api-workflow-check.py'), name: 'api-workflow-check.py' },
+      // Core utility hooks (5)
       { path: path.join(hooksDir, 'session-startup.py'), name: 'session-startup.py' },
+      { path: path.join(hooksDir, 'enforce-external-research.py'), name: 'enforce-external-research.py' },
+      { path: path.join(hooksDir, 'track-tool-use.py'), name: 'track-tool-use.py' },
       { path: path.join(hooksDir, 'periodic-reground.py'), name: 'periodic-reground.py' },
-      { path: path.join(hooksDir, 'verify-after-green.py'), name: 'verify-after-green.py' }
+      { path: path.join(hooksDir, 'api-workflow-check.py'), name: 'api-workflow-check.py' },
+      // Phase enforcement hooks with user checkpoints (12 - one per phase)
+      { path: path.join(hooksDir, 'enforce-disambiguation.py'), name: 'enforce-disambiguation.py' },
+      { path: path.join(hooksDir, 'enforce-scope.py'), name: 'enforce-scope.py' },
+      { path: path.join(hooksDir, 'enforce-research.py'), name: 'enforce-research.py' },
+      { path: path.join(hooksDir, 'enforce-interview.py'), name: 'enforce-interview.py' },
+      { path: path.join(hooksDir, 'enforce-deep-research.py'), name: 'enforce-deep-research.py' },
+      { path: path.join(hooksDir, 'enforce-schema.py'), name: 'enforce-schema.py' },
+      { path: path.join(hooksDir, 'enforce-environment.py'), name: 'enforce-environment.py' },
+      { path: path.join(hooksDir, 'enforce-tdd-red.py'), name: 'enforce-tdd-red.py' },
+      { path: path.join(hooksDir, 'verify-implementation.py'), name: 'verify-implementation.py' },
+      { path: path.join(hooksDir, 'verify-after-green.py'), name: 'verify-after-green.py' },
+      { path: path.join(hooksDir, 'enforce-verify.py'), name: 'enforce-verify.py' },
+      { path: path.join(hooksDir, 'enforce-refactor.py'), name: 'enforce-refactor.py' },
+      { path: path.join(hooksDir, 'enforce-documentation.py'), name: 'enforce-documentation.py' }
     );
   }
 
@@ -267,6 +281,118 @@ function main() {
     log('   ℹ️  Research index already exists (preserved)', 'blue');
   }
 
+  // ========================================
+  // 4c. Install Test UI (Parser API + Page)
+  // ========================================
+  log('\n🧪 Setting up Test UI:', 'cyan');
+
+  const testUiSourceDir = path.join(sourceTemplatesDir, 'api-test');
+  const hasNextJs = fs.existsSync(path.join(targetDir, 'next.config.js')) ||
+                    fs.existsSync(path.join(targetDir, 'next.config.mjs')) ||
+                    fs.existsSync(path.join(targetDir, 'next.config.ts'));
+
+  if (!hasNextJs) {
+    log('   ⚠️  Next.js not detected - skipping Test UI installation', 'yellow');
+    log('   💡 Test UI requires Next.js App Router', 'yellow');
+  } else if (fs.existsSync(testUiSourceDir)) {
+    // Detect App Router structure
+    const appDir = fs.existsSync(path.join(targetDir, 'src', 'app'))
+      ? path.join(targetDir, 'src', 'app')
+      : fs.existsSync(path.join(targetDir, 'app'))
+        ? path.join(targetDir, 'app')
+        : null;
+
+    if (!appDir) {
+      log('   ⚠️  App Router not detected - skipping Test UI installation', 'yellow');
+      log('   💡 Test UI requires Next.js App Router (app/ or src/app/)', 'yellow');
+    } else {
+      // Install test-structure API route
+      const apiTestStructureDir = path.join(appDir, 'api', 'test-structure');
+      const apiTestStructureSource = path.join(testUiSourceDir, 'test-structure', 'route.ts');
+      const apiTestStructureDest = path.join(apiTestStructureDir, 'route.ts');
+
+      if (!fs.existsSync(apiTestStructureDir)) {
+        fs.mkdirSync(apiTestStructureDir, { recursive: true });
+      }
+
+      if (!fs.existsSync(apiTestStructureDest)) {
+        try {
+          fs.copyFileSync(apiTestStructureSource, apiTestStructureDest);
+          log('   ✅ Created /api/test-structure route (parses Vitest files)', 'green');
+        } catch (error) {
+          log(`   ❌ Failed to create test-structure API: ${error.message}`, 'red');
+        }
+      } else {
+        log('   ℹ️  /api/test-structure already exists (preserved)', 'blue');
+      }
+
+      // Install test UI page
+      const apiTestPageDir = path.join(appDir, 'api-test');
+      const apiTestPageSource = path.join(testUiSourceDir, 'page.tsx');
+      const apiTestPageDest = path.join(apiTestPageDir, 'page.tsx');
+
+      if (!fs.existsSync(apiTestPageDir)) {
+        fs.mkdirSync(apiTestPageDir, { recursive: true });
+      }
+
+      if (!fs.existsSync(apiTestPageDest)) {
+        try {
+          fs.copyFileSync(apiTestPageSource, apiTestPageDest);
+          log('   ✅ Created /api-test page (displays test structure)', 'green');
+        } catch (error) {
+          log(`   ❌ Failed to create test UI page: ${error.message}`, 'red');
+        }
+      } else {
+        log('   ℹ️  /api-test page already exists (preserved)', 'blue');
+      }
+
+      log('   💡 Test UI available at http://localhost:3000/api-test', 'yellow');
+    }
+  } else {
+    log('   ⚠️  Test UI templates not found in package', 'yellow');
+  }
+
+  // ========================================
+  // 4d. Install Manifest Generation Scripts
+  // ========================================
+  log('\n📊 Setting up manifest generation scripts:', 'cyan');
+
+  const sourceScriptsDir = path.join(packageDir, 'scripts');
+  const targetScriptsDir = path.join(targetDir, 'scripts', 'api-dev-tools');
+
+  if (fs.existsSync(sourceScriptsDir)) {
+    if (!fs.existsSync(targetScriptsDir)) {
+      fs.mkdirSync(targetScriptsDir, { recursive: true });
+    }
+
+    const scriptFiles = fs.readdirSync(sourceScriptsDir).filter(file =>
+      file.endsWith('.ts')
+    );
+
+    if (scriptFiles.length > 0) {
+      scriptFiles.forEach(file => {
+        const source = path.join(sourceScriptsDir, file);
+        const dest = path.join(targetScriptsDir, file);
+
+        try {
+          fs.copyFileSync(source, dest);
+          log(`   ✅ ${file}`, 'green');
+        } catch (error) {
+          log(`   ❌ Failed to copy ${file}: ${error.message}`, 'red');
+        }
+      });
+
+      log('\n   Script purposes:', 'blue');
+      log('   • generate-test-manifest.ts - Parses tests → manifest (NO LLM)', 'blue');
+      log('   • extract-parameters.ts     - Extracts Zod params → matrix', 'blue');
+      log('   • collect-test-results.ts   - Runs Vitest → results JSON', 'blue');
+      log('\n   💡 Scripts run automatically after tests pass (Phase 8 → 9)', 'yellow');
+      log('   💡 Manual: npx tsx scripts/api-dev-tools/generate-test-manifest.ts', 'yellow');
+    }
+  } else {
+    log('   ⚠️  Scripts directory not found in package', 'yellow');
+  }
+
   // ========================================
   // 5. Install MCP Servers via CLI (Context7, GitHub)
   // ========================================
@@ -302,6 +428,42 @@ function main() {
   log('\n   ⚠️  GitHub MCP requires GITHUB_PERSONAL_ACCESS_TOKEN in env', 'yellow');
   log('   💡 Restart Claude Code for MCP tools to be available', 'yellow');
 
+  // ========================================
+  // 6. Update CLAUDE.md with workflow documentation
+  // ========================================
+  const claudeMdSection = path.join(sourceTemplatesDir, 'CLAUDE-SECTION.md');
+  const projectClaudeMd = path.join(targetDir, 'CLAUDE.md');
+
+  if (fs.existsSync(claudeMdSection)) {
+    log('\n📝 CLAUDE.md workflow documentation:', 'cyan');
+
+    const sectionContent = fs.readFileSync(claudeMdSection, 'utf8');
+    const sectionMarker = '## API Development Workflow (v3.0)';
+
+    if (fs.existsSync(projectClaudeMd)) {
+      const existingContent = fs.readFileSync(projectClaudeMd, 'utf8');
+
+      if (existingContent.includes(sectionMarker)) {
+        // Update existing section
+        const beforeSection = existingContent.split(sectionMarker)[0];
+        // Find the next ## heading or end of file
+        const afterMatch = existingContent.match(/## API Development Workflow[\s\S]*?((?=\n## )|$)/);
+        const afterSection = afterMatch ? existingContent.substring(existingContent.indexOf(afterMatch[0]) + afterMatch[0].length) : '';
+
+        fs.writeFileSync(projectClaudeMd, beforeSection + sectionContent + afterSection);
+        log('   ✅ Updated API Development Workflow section in CLAUDE.md', 'green');
+      } else {
+        // Append section
+        fs.appendFileSync(projectClaudeMd, '\n\n' + sectionContent);
+        log('   ✅ Added API Development Workflow section to CLAUDE.md', 'green');
+      }
+    } else {
+      // Create new CLAUDE.md with section
+      fs.writeFileSync(projectClaudeMd, '# Project Instructions\n\n' + sectionContent);
+      log('   ✅ Created CLAUDE.md with API Development Workflow section', 'green');
+    }
+  }
+
   // ========================================
   // Success Summary
   // ========================================
@@ -311,25 +473,33 @@ function main() {
 
   log('📋 What was installed:', 'bright');
   log('   Commands:  .claude/commands/*.md', 'blue');
-  log('   Hooks:     .claude/hooks/*.py (9 hooks)', 'blue');
+  log('   Hooks:     .claude/hooks/*.py (18 hooks for 100% enforcement + user checkpoints)', 'blue');
   log('   Settings:  .claude/settings.json', 'blue');
   log('   State:     .claude/api-dev-state.json', 'blue');
   log('   Research:  .claude/research/ (with freshness tracking)', 'blue');
+  log('   Scripts:   scripts/api-dev-tools/*.ts (manifest generation)', 'blue');
   log('   MCP:       context7, github (via claude mcp add)', 'blue');
+  log('   Test UI:   /api-test page + /api/test-structure API (if Next.js)', 'blue');
 
   log('\n🆕 New in v3.0:', 'bright');
-  log('   • Phase 0: Pre-research disambiguation', 'cyan');
-  log('   • Phase 9: Verify (re-research after tests pass)', 'cyan');
+  log('   • 12 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');
-  log('   • Questions generated FROM research findings', 'cyan');
   log('   • 7-turn re-grounding (prevents context dilution)', 'cyan');
   log('   • Research freshness (7-day cache validity)', 'cyan');
 
-  log('\n🔒 Enforcement Features:', 'bright');
-  log('   • Research MUST happen before code writing', 'cyan');
-  log('   • All research activity logged with turn counting', 'cyan');
-  log('   • Verification triggered after tests pass', 'cyan');
-  log('   • Periodic re-grounding every 7 turns', '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('\n📚 Available Commands:', 'bright');
   log('  /api-create [endpoint]    - Complete 12-phase workflow', 'blue');

package/demo/audio/generate-all-narrations.js

@@ -54,27 +54,25 @@ const VOICES = [
 ];
 
 // The narration script with section markers and highlight triggers
+// Format: [SECTION:id] marks a new section, [HIGHLIGHT:element-selector] marks what to highlight
 const NARRATION_SCRIPT = `
 [SECTION:intro]
-Welcome to Hustle API Dev Tools.
+Welcome to Hustle API Dev Tools, version three point oh.
 
 [HIGHLIGHT:#hustleBrand]
-This package enforces a structured workflow for AI-assisted API development.
+This package enforces a structured, twelve-phase workflow for AI-assisted API development.
 
 [HIGHLIGHT:[data-phase="research"]]
-First, you research. No assumptions. No training data. Real documentation.
+Research first. No assumptions. No training data. Real documentation from Context7 and web search.
 
 [HIGHLIGHT:[data-phase="interview"]]
-Then you interview. The AI asks YOU questions with structured options based on what it learned.
+Interview second. The AI asks YOU questions with structured options based on what it actually found.
 
 [HIGHLIGHT:[data-phase="test"]]
-Next, you write tests first. Red, green, refactor. No implementation without a failing test.
-
-[HIGHLIGHT:[data-phase="code"]]
-Only then do you write code. Minimal. Just enough to pass the tests.
+Test before code. Red, green, refactor. No implementation without a failing test.
 
 [HIGHLIGHT:[data-phase="docs"]]
-Finally, documentation. Every endpoint documented with real examples and schemas.
+Document everything. Every endpoint documented with real examples and schemas.
 
 The philosophy is simple: Hustle together. Share resources. Build stronger.
 
@@ -83,72 +81,136 @@ The philosophy is simple: Hustle together. Share resources. Build stronger.
 Let's talk about the problem. What goes wrong when AI builds APIs without structure?
 
 [HIGHLIGHT:.gap-item:nth-child(1)]
-Gap one: AI doesn't use your exact words. You say Vercel AI Gateway but it searches for Vercel AI SDK. Wrong library. Wrong documentation. Wrong code.
+Gap one: AI doesn't use your exact words. You say Brandfetch API but it searches for something else. Wrong library. Wrong documentation.
 
 [HIGHLIGHT:.gap-item:nth-child(2)]
-Gap two: AI claims files are updated without proof. It says I've updated the file but there's no git diff. No verification. You're trusting on faith.
+Gap two: Generic questions. Without research first, the AI asks template questions instead of specific ones based on actual API capabilities.
 
 [HIGHLIGHT:.gap-item:nth-child(3)]
-Gap three: Skipped tests are accepted. The AI runs tests, some fail, and it moves on. We can fix those later. Those later fixes never come.
+Gap three: Memory-based implementation. After research, the AI forgets what it learned and implements from training data instead.
 
 [HIGHLIGHT:.gap-item:nth-child(4)]
-Gap four: Tasks marked complete without verification. The AI says Done but the feature doesn't work. No one actually checked.
+Gap four: No verification after tests pass. The AI writes code that passes tests but doesn't match the actual documentation.
 
 [HIGHLIGHT:.gap-item:nth-child(5)]
-Gap five: Environment variable mismatch. Tests pass locally but fail in production. The AI used different values than what's actually deployed.
+Gap five: Context dilution. After many turns, the AI forgets project structure, documentation locations, and workflow requirements.
 
-These gaps compound. One wrong assumption leads to another. By the time you notice, you've built on a broken foundation.
+These gaps compound. Version three solves all of them with loop-back architecture and continuous re-grounding.
 
 [SECTION:solution]
 [HIGHLIGHT:#solution h2]
 The solution is enforcement. Python hooks that intercept every tool call.
 
-[HIGHLIGHT:.solution-grid .solution-card:nth-child(1)]
-PreToolUse hooks run before Claude can write or edit any file. They check: Did you research first? Did you interview the user? Did you write a failing test?
+[HIGHLIGHT:.hook-box:nth-child(1)]
+PreToolUse hooks run before Claude writes any file. They inject interview decisions as reminders and block writes without research.
+
+[HIGHLIGHT:.hook-box:nth-child(2)]
+PostToolUse hooks track tool usage and trigger verification. After tests pass, they force Phase nine: re-read the documentation.
 
-[HIGHLIGHT:.solution-grid .solution-card:nth-child(2)]
-PostToolUse hooks run after research and interviews. They track what was learned. They log every query. They build a paper trail.
+[HIGHLIGHT:.hook-box:nth-child(3)]
+The Stop hook blocks completion if any phase is incomplete. No more premature "done" declarations.
 
-[HIGHLIGHT:.solution-grid .solution-card:nth-child(3)]
-The Stop hook runs when Claude tries to mark a task complete. It checks: Are all phases done? Did tests pass? Is documentation updated? If not, blocked.
+[HIGHLIGHT:.hook-box:nth-child(4)]
+SessionStart and periodic hooks re-inject context every seven turns to prevent dilution in long sessions.
 
 This isn't about limiting AI. It's about holding it to the same standards we hold ourselves.
 
-[SECTION:workflow]
-[HIGHLIGHT:#workflow h2]
-The workflow has ten phases. Let's walk through each one.
+[SECTION:phases]
+[HIGHLIGHT:#phases h2]
+The workflow now has twelve phases. Two new ones in version three.
+
+[HIGHLIGHT:[data-phase="0"]]
+Phase zero: Disambiguation. When you say Vercel AI, do you mean the SDK or the Gateway? We clarify before researching.
+
+[HIGHLIGHT:[data-phase="1"]]
+Phase one: Scope. Confirm we understand what you want to build.
+
+[HIGHLIGHT:[data-phase="2"]]
+Phase two: Initial research. Context7 and web search. Find the real documentation.
+
+[HIGHLIGHT:[data-phase="3"]]
+Phase three: Interview. Questions generated FROM research findings. Not generic templates.
+
+[HIGHLIGHT:[data-phase="4"]]
+Phase four: Deep research. Based on your interview answers, we propose targeted follow-up searches. Adaptive, not shotgun.
+
+[HIGHLIGHT:[data-phase="5"]]
+Phase five: Schema. Define Zod schemas based on research plus interview decisions.
+
+[HIGHLIGHT:[data-phase="6"]]
+Phase six: Environment. Verify API keys exist before writing code.
+
+[HIGHLIGHT:[data-phase="7"]]
+Phase seven: TDD Red. Write failing tests. Define success before implementation.
+
+[HIGHLIGHT:[data-phase="8"]]
+Phase eight: TDD Green. Minimal code to pass tests. Interview decisions injected by hooks.
+
+[HIGHLIGHT:[data-phase="9"]]
+Phase nine: Verify. This is new. Re-read the original documentation and compare to implementation. Find gaps. Loop back if needed.
+
+[HIGHLIGHT:[data-phase="10"]]
+Phase ten: Refactor. Clean up code while tests stay green.
 
-[HIGHLIGHT:.phase-box[data-phase='1']]
-Phase one: Scope. Define what you're building. What's the endpoint? What does it do?
+[HIGHLIGHT:[data-phase="11"]]
+Phase eleven: Documentation. Update OpenAPI spec and test manifest.
 
-[HIGHLIGHT:.phase-box[data-phase='2']]
-Phase two: Initial research. Use Context7 or web search. Find the real documentation. No guessing.
+[HIGHLIGHT:[data-phase="12"]]
+Phase twelve: Complete. Final verification by the Stop hook.
 
-[HIGHLIGHT:.phase-box[data-phase='3']]
-Phase three: Interview. Ask the user questions with multiple choice options. What provider? What format? What error handling?
+Every phase can loop back. If verification finds gaps, we return to Red and write tests for missing features.
 
-[HIGHLIGHT:.phase-box[data-phase='4']]
-Phase four: Deep research. Based on interview answers, research specific APIs and SDKs.
+[SECTION:demo]
+[HIGHLIGHT:#demo h2]
+Let's watch a real example. Creating a Brandfetch API endpoint.
 
-[HIGHLIGHT:.phase-box[data-phase='5']]
-Phase five: Schema design. Define request and response schemas with Zod. Types before code.
+[HIGHLIGHT:[data-step="0"]]
+The user types /api-create brandfetch. The twelve-phase workflow begins.
 
-[HIGHLIGHT:.phase-box[data-phase='6']]
-Phase six: Environment setup. Check API keys. Verify environment variables. Test connectivity.
+[HIGHLIGHT:[data-step="1"]]
+Claude confirms scope. We're building an endpoint to fetch brand assets by domain.
 
-[HIGHLIGHT:.phase-box[data-phase='7']]
-Phase seven: Red. Write a failing test. Define what success looks like before writing any implementation.
+[HIGHLIGHT:[data-step="2"]]
+Initial research. Claude uses Context7 to find the SDK documentation. WebSearch finds rate limits and response formats.
 
-[HIGHLIGHT:.phase-box[data-phase='8']]
-Phase eight: Green. Write minimal code to pass the test. No extra features. No premature optimization.
+[HIGHLIGHT:[data-step="3"]]
+Interview begins. But notice: the questions are specific to what Claude actually found. What's the primary purpose? Options come from the documentation.
 
-[HIGHLIGHT:.phase-box[data-phase='9']]
-Phase nine: Refactor. Clean up the code. Extract utilities. Improve readability. Tests stay green.
+[HIGHLIGHT:[data-step="4"]]
+User selects: Full brand kit with logos, colors, and fonts.
 
-[HIGHLIGHT:.phase-box[data-phase='10']]
-Phase ten: Documentation. Update OpenAPI spec. Add to test manifest. Include real examples.
+[HIGHLIGHT:[data-step="5"]]
+More questions. How should API keys be handled? User selects server environment variables only.
 
-Only when all ten phases are complete can the workflow finish.
+[HIGHLIGHT:[data-step="7"]]
+Deep research. Based on your selections, Claude proposes specific searches for the full brand response format.
+
+[HIGHLIGHT:[data-step="8"]]
+Schema created. Zod types based on research plus interview decisions.
+
+[HIGHLIGHT:[data-step="9"]]
+Environment check. The hook verifies BRANDFETCH_API_KEY exists.
+
+[HIGHLIGHT:[data-step="10"]]
+TDD Red. Claude writes twelve failing test cases.
+
+[HIGHLIGHT:[data-step="11"]]
+TDD Green. Implementation begins. Watch the hook inject interview decisions.
+
+[HIGHLIGHT:[data-step="12"]]
+The hook reminds Claude: Remember user decisions. Purpose: full brand kit. API key handling: server only.
+
+[HIGHLIGHT:[data-step="13"]]
+Phase nine: Verify. Claude re-reads the Brandfetch documentation and compares to implementation. All features accounted for.
+
+[HIGHLIGHT:[data-step="14"]]
+Refactor. Code cleaned up. Tests still pass.
+
+[HIGHLIGHT:[data-step="15"]]
+Documentation updated. API test manifest and OpenAPI spec.
+
+[HIGHLIGHT:[data-step="16"]]
+Complete. All twelve phases verified. Four files created. Twelve tests passing.
 
 [SECTION:installation]
 [HIGHLIGHT:#installation h2]
@@ -157,33 +219,29 @@ Installation takes one command.
 [HIGHLIGHT:.install-command]
 Run npx @hustle-together/api-dev-tools. That's it.
 
-The CLI copies slash commands to your .claude/commands folder. Red, green, refactor, cycle, and the API development commands.
+The CLI copies slash commands, Python hooks, and settings. It creates the research cache folder and updates your CLAUDE.md with workflow documentation.
 
-It copies Python hooks to .claude/hooks. These are the enforcers. The gatekeepers.
+Version three adds automatic CLAUDE.md updates so Claude understands the workflow in your project.
 
-It merges settings into your settings.json. Hooks are registered. Permissions are configured.
-
-And it offers to add the Context7 MCP server for live documentation lookup.
-
-Your project is now enforced. Every API you build follows the workflow.
+Your project is now enforced. Every API follows the twelve-phase workflow.
 
 [SECTION:credits]
 [HIGHLIGHT:#credits h2]
 This project builds on the work of others.
 
-The TDD workflow commands are based on @wbern/claude-instructions by William Bernmalm. The red, green, refactor pattern that makes AI development rigorous.
+The TDD workflow is based on @wbern/claude-instructions by William Bernmalm.
 
-The interview methodology is inspired by Anthropic's Interviewer approach. Structured discovery before implementation.
+Context7 provides live documentation lookup. Current docs, not stale training data.
 
-And Context7 provides live documentation lookup. Current docs, not stale training data.
+And the interview methodology ensures questions come from research, not templates.
 
 Thank you to the Claude Code community. Together, we're making AI development better.
 
 [SECTION:outro]
 [HIGHLIGHT:#intro]
-Hustle API Dev Tools. Research first. Interview second. Test before code. Document everything.
+Hustle API Dev Tools version three. Twelve phases. Loop-back architecture. Continuous verification.
 
-Build together. Share resources. Grow stronger.
+Research first. Questions FROM findings. Verify after green. Document always.
 
 Install it now with npx @hustle-together/api-dev-tools.
 `.trim();
@@ -221,11 +279,18 @@ function parseMarkers(script) {
     }
 
     // Check for highlight marker
-    const highlightMatch = line.match(/\[HIGHLIGHT:([^\]]+)\]/);
+    // Use a more robust regex that handles nested brackets like [data-phase="0"]
+    const highlightMatch = line.match(/\[HIGHLIGHT:(.+?)\]$/);
     if (highlightMatch) {
+      // Extract the selector - handle double brackets for attribute selectors
+      let selector = highlightMatch[1];
+      // If selector starts with [ but doesn't end with ], add the closing bracket
+      if (selector.startsWith('[') && !selector.endsWith(']')) {
+        selector = selector + ']';
+      }
       markers.push({
         type: 'highlight',
-        selector: highlightMatch[1],
+        selector: selector,
         section: currentSection,
         charPosition
       });