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

package/README.md

@@ -1,10 +1,20 @@
-# API Development Tools for Claude Code
+# API Development Tools for Claude Code v3.0
 
-**Interview-driven, research-first API development workflow**
+**Interview-driven, research-first API development workflow with continuous verification loops**
 
-Automates the complete API development lifecycle from understanding requirements to deployment through structured interviews, deep research, test-driven development, and comprehensive documentation.
+Automates the complete API development lifecycle from understanding requirements to deployment through structured interviews, adaptive research, test-driven development, and comprehensive documentation with automatic re-grounding.
 
-## 🚀 Quick Start
+## What's New in v3.0
+
+- **Phase 0: Pre-Research Disambiguation** - Search variations to clarify ambiguous terms
+- **Phase 9: Verify** - Re-research after tests pass to catch memory-based errors
+- **Adaptive Research** - Propose searches based on interview answers, not shotgun approach
+- **Questions FROM Research** - Interview questions generated from discovered parameters
+- **7-Turn Re-grounding** - Periodic context injection prevents memory dilution
+- **Research Freshness** - 7-day cache with automatic staleness warnings
+- **Loop-Back Architecture** - Every verification loops back if not successful
+
+## Quick Start
 
 ```bash
 # Install in your project
@@ -14,574 +24,440 @@ npx @hustle-together/api-dev-tools --scope=project
 /api-create my-endpoint
 ```
 
-## 📦 What This Installs
+## 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
-Five powerful slash commands for Claude Code:
 
-- **`/api-create [endpoint]`** - Complete automated workflow (Interview → Research → TDD → Docs)
-- **`/api-interview [endpoint]`** - Structured 20-question interview about purpose and usage
-- **`/api-research [library]`** - Deep research of external APIs/SDKs (finds ALL parameters)
+Six powerful slash commands for Claude Code:
+
+- **`/api-create [endpoint]`** - Complete workflow (Disambiguate → Research → Interview → TDD → Verify → Docs)
+- **`/api-interview [endpoint]`** - Dynamic questions GENERATED from research findings
+- **`/api-research [library]`** - Adaptive propose-approve research flow
+- **`/api-verify [endpoint]`** - Re-research and compare implementation to docs
 - **`/api-env [endpoint]`** - Check required API keys and environment setup
 - **`/api-status [endpoint]`** - Track implementation progress and phase completion
 
-### Enforcement Hooks
-Six Python hooks that provide **real programmatic guarantees**:
+### Enforcement Hooks (8 total)
+
+Python hooks that provide **real programmatic guarantees**:
 
-- **`enforce-external-research.py`** - (v1.7.0) Detects external API questions and requires research before answering
-- **`enforce-research.py`** - Blocks API code writing until research is complete
-- **`enforce-interview.py`** - (v1.8.0+) Verifies structured questions with options were asked; (v1.9.0+) Injects decision reminders on writes
-- **`verify-implementation.py`** - Checks implementation matches interview requirements
-- **`track-tool-use.py`** - (v1.9.0+) Captures user decisions from AskUserQuestion; logs all research activity
-- **`api-workflow-check.py`** - Prevents stopping until required phases are complete + git diff verification
+| Hook | Event | Purpose |
+|------|-------|---------|
+| `session-startup.py` | SessionStart | Inject current state at session start |
+| `enforce-external-research.py` | UserPromptSubmit | Detect API terms, require research |
+| `enforce-research.py` | PreToolUse | Block writes until research complete |
+| `enforce-interview.py` | PreToolUse | Inject interview decisions on writes |
+| `verify-implementation.py` | PreToolUse | Check test file exists before route |
+| `track-tool-use.py` | PostToolUse | Log research, count turns |
+| `periodic-reground.py` | PostToolUse | Re-inject context every 7 turns |
+| `verify-after-green.py` | PostToolUse | Trigger Phase 9 after tests pass |
+| `api-workflow-check.py` | Stop | Block completion if phases incomplete |
 
 ### State Tracking
-- **`.claude/api-dev-state.json`** - Persistent state file tracking all workflow progress
 
-### MCP Servers (Auto-installed via `claude mcp add`)
-- **Context7** - Fetches LIVE documentation from library source code (not training data)
-- **GitHub** - Read/create issues, pull requests, and access repository data (requires `GITHUB_PERSONAL_ACCESS_TOKEN`)
+- **`.claude/api-dev-state.json`** - Persistent workflow state with turn counting
+- **`.claude/research/`** - Cached research with freshness tracking
+- **`.claude/research/index.json`** - Research catalog with 7-day validity
 
-## 🎯 Why Use This?
+### Manifest Generation Scripts (Programmatic, NO LLM)
 
-### Problems This Solves
+Scripts that automatically generate documentation from test files:
 
-- ❌ **Writing tests without understanding purpose** → Mechanical tests that miss real use cases
-- ❌ **Incomplete API research** → Missing optional parameters and edge cases
-- ❌ **Runtime errors from missing API keys** → Tests fail due to configuration issues
-- ❌ **No documentation of real usage** → Future developers don't understand context
-- ❌ **Inconsistent implementation patterns** → Every endpoint looks different
+| 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 |
 
-### What You Get
+**Key principle:** Tests are the SOURCE OF TRUTH. Scripts parse source files programmatically. **NO LLM involvement** in manifest generation.
 
-- ✅ **Interview-first development** → Deep understanding before any code
-- ✅ **Comprehensive research** → Discover ALL parameters, not just documented ones
-- ✅ **Environment validation** → Verify API keys before starting
-- ✅ **TDD enforced** → Red → Green → Refactor cycle mandatory
-- ✅ **Auto-documentation** → Updates manifests, OpenAPI specs, status tracking
-- ✅ **Consistent workflow** → Repeatable, testable, maintainable
+Scripts are triggered automatically after tests pass (Phase 8 → Phase 9) via `verify-after-green.py` hook.
 
-## 💡 How It Works
+## Complete Phase Flow (12 Phases)
 
-### Fully Automated
-```bash
-/api-create generate-pdf
 ```
-
-This single command:
-1. **Interviews you** about the endpoint (20 structured questions)
-2. **Researches** required libraries and external APIs
-3. **Checks environment** for API keys and configuration
-4. **Writes failing tests** first (TDD Red phase)
-5. **Implements** minimal solution (TDD Green phase)
-6. **Refactors** for quality (TDD Refactor phase)
-7. **Updates documentation** (manifests, OpenAPI, examples)
-8. **Creates commit** with semantic message
-
-### Manual Step-by-Step
-```bash
-/api-interview generate-pdf    # Understand purpose & requirements
-/api-research pdf-lib          # Research PDF library thoroughly
-/api-env generate-pdf          # Verify environment & API keys
-/red                           # Write ONE failing test
-/green                         # Implement to make it pass
-/refactor                      # Clean up the code
-/api-status generate-pdf       # Update progress tracking
-/commit                        # Create semantic commit
+┌─ PHASE 0: DISAMBIGUATION ─────────────────────┐
+│ Search 3-5 variations, clarify ambiguity      │
+│ Loop back if still unclear                    │
+└───────────────────────────────────────────────┘
+        │
+        ▼
+┌─ PHASE 1: SCOPE CONFIRMATION ─────────────────┐
+│ Confirm understanding of endpoint purpose     │
+└───────────────────────────────────────────────┘
+        │
+        ▼
+┌─ PHASE 2: INITIAL RESEARCH ───────────────────┐
+│ 2-3 targeted searches (Context7, WebSearch)   │
+│ Present summary, ask to proceed or search more│
+│ Loop back if user wants more                  │
+└───────────────────────────────────────────────┘
+        │
+        ▼
+┌─ PHASE 3: INTERVIEW ──────────────────────────┐
+│ Questions GENERATED from research findings    │
+│ - Enum params → multi-select                  │
+│ - Continuous ranges → test strategy           │
+│ - Boolean params → enable/disable             │
+└───────────────────────────────────────────────┘
+        │
+        ▼
+┌─ PHASE 4: DEEP RESEARCH (Adaptive) ───────────┐
+│ PROPOSE searches based on interview answers   │
+│ User approves/modifies/skips                  │
+│ Not shotgun - targeted to selections          │
+└───────────────────────────────────────────────┘
+        │
+        ▼
+┌─ PHASE 5: SCHEMA DESIGN ──────────────────────┐
+│ Create Zod schema from research + interview   │
+│ Loop back if schema wrong                     │
+└───────────────────────────────────────────────┘
+        │
+        ▼
+┌─ PHASE 6: ENVIRONMENT CHECK ──────────────────┐
+│ Verify API keys exist                         │
+│ Loop back if keys missing                     │
+└───────────────────────────────────────────────┘
+        │
+        ▼
+┌─ PHASE 7: TDD RED ────────────────────────────┐
+│ Write failing tests from schema + decisions   │
+│ Test matrix derived from interview            │
+└───────────────────────────────────────────────┘
+        │
+        ▼
+┌─ 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)      │
+└───────────────────────────────────────────────┘
+        │
+        ▼
+┌─ PHASE 9: VERIFY (NEW) ───────────────────────┐
+│ Re-read original documentation                │
+│ Compare implementation to docs feature-by-    │
+│ feature. Find gaps.                           │
+│                                               │
+│ Fix gaps? → Loop back to Phase 7              │
+│ Skip (intentional)? → Document as omissions   │
+└───────────────────────────────────────────────┘
+        │
+        ▼
+┌─ PHASE 10: TDD REFACTOR ──────────────────────┐
+│ Clean up code, tests still pass               │
+└───────────────────────────────────────────────┘
+        │
+        ▼
+┌─ PHASE 11: DOCUMENTATION ─────────────────────┐
+│ Update manifests, OpenAPI, cache research     │
+└───────────────────────────────────────────────┘
+        │
+        ▼
+┌─ PHASE 12: COMPLETION ────────────────────────┐
+│ All phases verified, commit                   │
+└───────────────────────────────────────────────┘
 ```
 
-## 📋 Installation
+## Key Features
 
-### One-Time Installation
-```bash
-cd your-project
-npx @hustle-together/api-dev-tools --scope=project
-```
+### Adaptive Research (Not Shotgun)
 
-### Team-Wide Auto-Installation
+**OLD:** Run 20 searches blindly
 
-Add to your project's `package.json`:
-```json
-{
-  "scripts": {
-    "postinstall": "npx @hustle-together/api-dev-tools --scope=project"
-  }
-}
-```
-
-Now anyone who runs `npm install` or `pnpm install` gets the commands automatically.
+**NEW:**
+1. Run 2-3 initial searches
+2. Present summary
+3. PROPOSE additional searches based on context
+4. User approves/modifies
+5. Execute only approved searches
 
-## 📚 Command Reference
+### Questions FROM Research
 
-### `/api-create [endpoint-name]`
-
-**The orchestrator.** Runs the complete workflow automatically.
-
-**Example:**
-```bash
-/api-create user-preferences
+**OLD:** Generic template questions
 ```
-
-**What it does:**
-- Interviews you about requirements
-- Researches dependencies (Next.js API routes, Zod, etc.)
-- Checks environment (Supabase keys, etc.)
-- Writes comprehensive tests
-- Implements with Zod validation
-- Updates all documentation
-- Creates commit
-
----
-
-### `/api-interview [endpoint-name]`
-
-**Structured discovery.** 20-question interview based on Anthropic Interviewer methodology.
-
-**Example:**
-```bash
-/api-interview send-email
+"Which AI provider should this endpoint support?"
 ```
 
-**Questions cover:**
-- Purpose & context
-- Real-world usage scenarios
-- Required vs. optional parameters
-- Dependencies & API keys
-- Error handling & edge cases
-- Documentation sources
-
-**Output:** `/src/v2/docs/endpoints/[endpoint-name].md`
-
----
-
-### `/api-research [library-or-service]`
-
-**Deep dive.** Discovers ALL parameters by reading source code and documentation.
-
-**Example:**
-```bash
-/api-research resend-api
-```
-
-**Finds:**
-- Official documentation links
-- Complete request/response schemas
-- Undocumented parameters (from source code)
-- TypeScript type definitions
-- Rate limits, quotas, costs
-- Integration patterns
-- Code examples
-
-**Output:** `/src/v2/docs/research/[library-name].md`
-
----
-
-### `/api-env [endpoint-name]`
-
-**Environment check.** Verifies API keys and configuration before implementation.
-
-**Example:**
-```bash
-/api-env send-email
+**NEW:** Questions generated from discovered parameters
 ```
+Based on research, Brandfetch API has 7 parameters:
 
-**Checks:**
-- Required API keys exist in `.env.local`
-- Templates in `.env.example`
-- `.gitignore` protects secrets
-- Service connectivity (optional)
+1. DOMAIN (required) - string
+   → No question needed
 
-**Output:** Terminal report + action items
+2. FORMAT: ["json", "svg", "png", "raw"]
+   Q: Which formats do you need?
 
----
-
-### `/api-status [endpoint-name]`
-
-**Progress tracking.** Shows implementation status and phase completion.
-
-**Examples:**
-```bash
-/api-status send-email         # Specific endpoint
-/api-status --all              # All endpoints
+3. QUALITY: 1-100 (continuous range)
+   Q: How should we TEST this?
+   [ ] All values (100 tests)
+   [x] Boundary (1, 50, 100)
 ```
 
-**Tracks:**
-- Interview completion
-- Research completion
-- Environment readiness
-- TDD phases (Red → Green → Refactor)
-- Documentation updates
-- Test coverage
-
-**Output:** Progress report + status document updates
-
-## 🔄 Workflow Integration
-
-Works seamlessly with existing Claude Code commands:
-
-```bash
-/plan          # Create implementation checklist
-/gap           # Find missing pieces
-/issue [url]   # Start from GitHub issue
-
-/api-create    # ← Run complete API workflow
-
-/commit        # Semantic commit message
-/pr            # Create pull request
-```
-
-## 🎓 Methodology
-
-Based on proven approaches:
-
-- **[Anthropic Interviewer](https://www.anthropic.com/news/anthropic-interviewer)** - Structured interview methodology
-- **TDD (Test-Driven Development)** - Red → Green → Refactor cycle
-- **[@wbern/claude-instructions](https://github.com/wbern/claude-instructions)** - Slash command pattern
-- **V2 Development Patterns** - Zod schemas, consistent structure
+### Phase 9: Verify (Catches Memory Errors)
 
-## 📁 Output Artifacts
-
-Each endpoint creates:
+After tests pass, automatically:
+1. Re-read original documentation
+2. Compare feature-by-feature
+3. Report discrepancies:
 
 ```
-src/app/api/v2/[endpoint]/
-├── route.ts                          # Handler with Zod schemas
-├── __tests__/
-│   └── [endpoint].api.test.ts        # Comprehensive tests (100% coverage)
-└── README.md                          # Endpoint documentation
-
-src/v2/docs/
-├── endpoints/
-│   └── [endpoint].md                 # Interview results & requirements
-└── research/
-    └── [library].md                  # External API research findings
-
-Updated files:
-- src/app/api-test/api-tests-manifest.json    # Test documentation
-- src/lib/openapi/endpoints/[endpoint].ts     # OpenAPI spec
-- src/v2/docs/v2-api-implementation-status.md # Progress tracking
+│ Feature       │ In Docs │ Implemented │ Status      │
+├───────────────┼─────────┼─────────────┼─────────────│
+│ domain param  │ ✓       │ ✓           │ ✅ Match    │
+│ format opts   │ 4       │ 3           │ ⚠️ Missing  │
+│ webhook       │ ✓       │ ✗           │ ℹ️ Optional │
+
+Fix gaps? [Y] → Return to Phase 7
+Skip? [n] → Document as omissions
 ```
 
-## 🏗 Project Structure Required
-
-This tool expects:
-- **Next.js** API routes (`src/app/api/`)
-- **Vitest** for testing
-- **Zod** for validation
-- **TypeScript** strict mode
-
-Not tied to specific AI providers - works with any API architecture.
+### 7-Turn Re-grounding
 
-## 🔑 Key Principles
+Prevents context dilution in long sessions:
+- Every 7 turns, hook injects state summary
+- Current phase, decisions, research cache location
+- Ensures Claude stays aware of workflow
 
-1. **Context First** - Understand WHY before HOW
-2. **Research Thoroughly** - Find ALL parameters, not just documented
-3. **Test First** - No implementation without failing test
-4. **Document Everything** - Future you needs to understand this
-5. **Verify Environment** - Check API keys before starting
-6. **Consistent Process** - Same workflow every time
+### Research Freshness
 
-## 🆚 Comparison
-
-### Without API Dev Tools
+Research is cached with 7-day validity:
 ```
-1. Start coding immediately
-2. Guess at parameters
-3. Discover missing API keys mid-development
-4. Write tests after implementation (if at all)
-5. Forget to update documentation
-6. Inconsistent patterns across endpoints
-7. No progress tracking
-
-Result: Brittle APIs, poor docs, hard to maintain
+.claude/research/
+├── brandfetch/
+│   ├── 2025-12-08_initial.md
+│   └── CURRENT.md
+└── index.json  ← Tracks freshness
 ```
 
-### With API Dev Tools
-```
-1. Interview to understand requirements
-2. Research to find ALL parameters
-3. Verify environment before coding
-4. Write failing tests first (TDD)
-5. Implement with minimal code
-6. Auto-update all documentation
-7. Track progress throughout
-
-Result: Robust APIs, comprehensive docs, easy to maintain
-```
-
-## 🔒 Programmatic Enforcement (Hooks)
-
-Unlike pure markdown instructions that rely on Claude following directions, this package includes **real Python hooks** that enforce workflow compliance.
-
-### How Hooks Work
-
+If research is >7 days old:
 ```
-┌─────────────────────────────────────────────────────────────┐
-│  USER: "Add Vercel AI SDK"                                  │
-│                    ↓                                        │
-│  CLAUDE: Calls WebSearch for docs                           │
-│                    ↓                                        │
-│  HOOK: PostToolUse (track-tool-use.py)                      │
-│  → Logs search to api-dev-state.json                        │
-│                    ↓                                        │
-│  CLAUDE: Tries to Write route.ts                            │
-│                    ↓                                        │
-│  HOOK: PreToolUse (enforce-research.py)                     │
-│  → Checks: Has research been completed?                     │
-│  → If NO: BLOCKED with error message                        │
-│  → If YES: Allowed to proceed                               │
-│                    ↓                                        │
-│  CLAUDE: Tries to stop conversation                         │
-│                    ↓                                        │
-│  HOOK: Stop (api-workflow-check.py)                         │
-│  → Checks: Are all required phases complete?                │
-│  → If NO: BLOCKED with list of incomplete phases            │
-│  → If YES: Allowed to stop                                  │
-└─────────────────────────────────────────────────────────────┘
+⚠️ Research for "brandfetch" is 15 days old.
+Re-research before using? [Y/n]
 ```
 
-### What Gets Enforced
-
-| Action | Hook | Enforcement |
-|--------|------|-------------|
-| Claude calls WebSearch/WebFetch/Context7 | `track-tool-use.py` | Logged to state file |
-| Claude tries to write API code | `enforce-research.py` | **BLOCKED** if no research logged |
-| Claude tries to stop | `api-workflow-check.py` | **BLOCKED** if phases incomplete |
-
-### Check Progress Anytime
+## Installation
 
 ```bash
-# View current state
-cat .claude/api-dev-state.json | jq '.phases'
-
-# Or use the status command
-/api-status
+cd your-project
+npx @hustle-together/api-dev-tools --scope=project
 ```
 
-### State File Structure
-
-The `.claude/api-dev-state.json` file tracks:
+### Team-Wide Auto-Installation
 
+Add to `package.json`:
 ```json
 {
-  "endpoint": "stream-text",
-  "library": "vercel-ai-sdk",
-  "phases": {
-    "scope": { "status": "complete" },
-    "research_initial": {
-      "status": "complete",
-      "sources": [
-        { "type": "context7", "tool": "resolve_library_id" },
-        { "type": "websearch", "query": "Vercel AI SDK docs" },
-        { "type": "webfetch", "url": "https://sdk.vercel.ai" }
-      ]
-    },
-    "interview": { "status": "complete" },
-    "research_deep": { "status": "complete" },
-    "schema_creation": { "status": "in_progress" },
-    "tdd_red": { "status": "pending" },
-    "tdd_green": { "status": "pending" },
-    "tdd_refactor": { "status": "pending" },
-    "documentation": { "status": "pending" }
-  },
-  "verification": {
-    "all_sources_fetched": true,
-    "schema_matches_docs": false,
-    "tests_cover_params": false,
-    "all_tests_passing": false
+  "scripts": {
+    "postinstall": "npx @hustle-together/api-dev-tools --scope=project"
   }
 }
 ```
 
-### Why This Matters
-
-**Without hooks (pure markdown instructions):**
-- Claude *might* skip research if confident
-- Claude *might* use outdated training data
-- No way to verify steps were actually completed
-
-**With hooks (programmatic enforcement):**
-- Research is **required** - can't write code without it
-- All research activity is **logged** - auditable trail
-- Workflow completion is **verified** - can't stop early
-
-## 🔍 Gap Detection & Verification (v1.6.0+)
+## Command Reference
 
-The workflow now includes automatic detection of common implementation gaps:
-
-### Gap 1: Exact Term Matching
-**Problem:** AI paraphrases user terminology instead of using exact terms for research.
+### `/api-create [endpoint-name]`
 
-**Example:**
-- User says: "Use Vercel AI Gateway"
-- AI searches for: "Vercel AI SDK" (wrong!)
+Complete 12-phase workflow. See [commands/api-create.md](commands/api-create.md).
 
-**Fix:** `verify-implementation.py` extracts key terms from interview answers and warns if those exact terms weren't used in research queries.
+### `/api-interview [endpoint-name]`
 
-### Gap 2: File Change Tracking
-**Problem:** AI claims "all files updated" but doesn't verify which files actually changed.
+Dynamic interview with questions FROM research. See [commands/api-interview.md](commands/api-interview.md).
 
-**Fix:** `api-workflow-check.py` runs `git diff --name-only` and compares against tracked `files_created`/`files_modified` in state. Warns about untracked changes.
+### `/api-research [library-name]`
 
-### Gap 3: Skipped Test Investigation
-**Problem:** AI accepts "9 tests skipped" without investigating why.
+Adaptive propose-approve research. See [commands/api-research.md](commands/api-research.md).
 
-**Fix:** `verification_warnings` in state file tracks issues that need review. Stop hook shows unaddressed warnings.
+### `/api-verify [endpoint-name]`
 
-### Gap 4: Implementation Verification
-**Problem:** AI marks task complete without verifying implementation matches interview.
+Manual Phase 9 verification. See [commands/api-verify.md](commands/api-verify.md).
 
-**Fix:** Stop hook checks that:
-- Route files exist if endpoints mentioned
-- Test files are tracked
-- Key terms from interview appear in implementation
+### `/api-env [endpoint-name]`
 
-### Gap 5: Test/Production Alignment
-**Problem:** Test files check different environment variables than production code.
+Environment and API key check. See [commands/api-env.md](commands/api-env.md).
 
-**Example:**
-- Interview: "single gateway key"
-- Production: uses `AI_GATEWAY_API_KEY`
-- Test: still checks `OPENAI_API_KEY` (wrong!)
+### `/api-status [endpoint-name]`
 
-**Fix:** `verify-implementation.py` warns when test files check env vars that don't match interview requirements.
+Progress tracking. See [commands/api-status.md](commands/api-status.md).
 
-### Gap 6: Training Data Reliance (v1.7.0+)
-**Problem:** AI answers questions about external APIs from potentially outdated training data instead of researching first.
+## State File Structure (v3.0)
 
-**Example:**
-- User asks: "What providers does Vercel AI Gateway support?"
-- AI answers from memory: "Groq not in gateway" (WRONG!)
-- Reality: Groq has 4 models in the gateway (Llama variants)
+```json
+{
+  "version": "3.0.0",
+  "endpoint": "brandfetch",
+  "turn_count": 23,
+  "phases": {
+    "disambiguation": { "status": "complete" },
+    "scope": { "status": "complete" },
+    "research_initial": { "status": "complete", "sources": [...] },
+    "interview": {
+      "status": "complete",
+      "decisions": {
+        "format": ["json", "svg", "png"],
+        "quality_testing": "boundary"
+      }
+    },
+    "research_deep": {
+      "status": "complete",
+      "proposed_searches": [...],
+      "approved_searches": [...],
+      "skipped_searches": [...]
+    },
+    "schema_creation": { "status": "complete" },
+    "environment_check": { "status": "complete" },
+    "tdd_red": { "status": "complete", "test_count": 23 },
+    "tdd_green": { "status": "complete" },
+    "verify": {
+      "status": "complete",
+      "gaps_found": 2,
+      "gaps_fixed": 2,
+      "intentional_omissions": ["webhook support"]
+    },
+    "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" }
+  ]
+}
+```
 
-**Fix:** New `UserPromptSubmit` hook (`enforce-external-research.py`) that:
-1. Detects questions about external APIs/SDKs using pattern matching
-2. Injects context requiring research before answering
-3. Works for ANY API (Brandfetch, Stripe, Twilio, etc.) - not just specific ones
-4. Auto-allows WebSearch and Context7 without permission prompts
+## Hook Architecture
 
 ```
-USER: "What providers does Brandfetch API support?"
-        ↓
-HOOK: Detects "Brandfetch", "API", "providers"
-        ↓
-INJECTS: "RESEARCH REQUIRED: Use Context7/WebSearch before answering"
-        ↓
-CLAUDE: Researches first → Gives accurate answer
+┌──────────────────────────────────────────────────────────┐
+│  SESSION START                                            │
+│  → session-startup.py injects current state              │
+└──────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌──────────────────────────────────────────────────────────┐
+│  USER PROMPT                                              │
+│  → enforce-external-research.py detects API terms        │
+└──────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌──────────────────────────────────────────────────────────┐
+│  RESEARCH TOOLS (WebSearch, Context7)                     │
+│  → track-tool-use.py logs activity, counts turns         │
+│  → periodic-reground.py injects summary every 7 turns    │
+└──────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌──────────────────────────────────────────────────────────┐
+│  WRITE/EDIT TOOLS                                         │
+│  → enforce-research.py blocks if no research             │
+│  → enforce-interview.py injects decisions                │
+│  → verify-implementation.py checks test file exists      │
+└──────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌──────────────────────────────────────────────────────────┐
+│  TEST COMMANDS (pnpm test)                                │
+│  → verify-after-green.py triggers Phase 9 after pass     │
+└──────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌──────────────────────────────────────────────────────────┐
+│  STOP                                                     │
+│  → api-workflow-check.py blocks if phases incomplete     │
+└──────────────────────────────────────────────────────────┘
 ```
 
-### Gap 7: Interview Decisions Not Used During Implementation (v1.9.0+)
-**Problem:** AI asks good interview questions but then ignores the answers when writing code.
-
-**Example:**
-- Interview: User selected "server environment variables only" for API key handling
-- Implementation: AI writes code with custom header overrides (not what user wanted!)
-
-**Fix:** Two-part solution in `track-tool-use.py` and `enforce-interview.py`:
+## Manual Script Usage
 
-1. **track-tool-use.py** now captures:
-   - The user's actual response from AskUserQuestion
-   - Matches responses to option values
-   - Stores decisions in categorized `decisions` dict (purpose, api_key_handling, etc.)
+While scripts run automatically after tests pass, you can also run them manually:
 
-2. **enforce-interview.py** now injects a decision summary on EVERY write:
-```
-✅ Interview complete. REMEMBER THE USER'S DECISIONS:
+```bash
+# Generate manifest from test files
+npx tsx scripts/api-dev-tools/generate-test-manifest.ts
 
-• Primary Purpose: full_brand_kit
-• API Key Handling: server_only
-• Response Format: JSON with asset URLs
-• Error Handling: detailed (error, code, details)
+# Extract parameters and calculate coverage
+npx tsx scripts/api-dev-tools/extract-parameters.ts
 
-Your implementation MUST align with these choices.
+# Collect test results (runs Vitest)
+npx tsx scripts/api-dev-tools/collect-test-results.ts
 ```
 
-This ensures the AI is constantly reminded of what the user actually wanted throughout the entire implementation phase.
+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
+## Requirements
 
 - **Node.js** 14.0.0 or higher
 - **Python 3** (for enforcement hooks)
 - **Claude Code** (CLI tool for Claude)
 - **Project structure** with `.claude/commands/` support
 
-## 🔌 MCP Servers
-
-This package auto-configures two MCP servers:
+## MCP Servers (Auto-installed)
 
 ### Context7
-- **Live documentation lookup** from library source code
-- **Current API parameters** (not outdated training data)
-- **TypeScript type definitions** directly from packages
-
-When you research a library like `@ai-sdk/core`, Context7 fetches the actual current documentation rather than relying on Claude's training data which may be outdated.
+- Live documentation from library source code
+- Current API parameters (not training data)
 
 ### GitHub
-- **Issue management** - Read and create GitHub issues
-- **Pull requests** - Create PRs with proper formatting
-- **Repository access** - Browse repo contents and metadata
+- Issue management
+- Pull request creation
 
-Required for `/pr` and `/issue` commands to work with GitHub MCP tools.
+Set `GITHUB_PERSONAL_ACCESS_TOKEN` for GitHub MCP.
 
-**Setup:** Set `GITHUB_PERSONAL_ACCESS_TOKEN` in your environment:
-```bash
-export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
-```
-
-The installer runs `claude mcp add` commands directly, which registers the servers in your Claude Code config (`~/.claude.json`). Restart Claude Code after installation for MCP tools to be available.
-
-## 📖 Documentation
-
-After installation, see:
-- `.claude/commands/README.md` - Complete command reference
-- `.claude/commands/api-create.md` - Full workflow details
-- `.claude/commands/api-interview.md` - Interview questions
-- `.claude/commands/api-research.md` - Research methodology
+## Acknowledgments
 
-## 🤝 Contributing
+- **[@wbern/claude-instructions](https://github.com/wbern/claude-instructions)** - TDD commands
+- **[Anthropic Interviewer](https://www.anthropic.com/news/anthropic-interviewer)** - Interview methodology
+- **[Context7](https://context7.com)** - Live documentation lookup
 
-This is the initial release. Feedback welcome!
+## License
 
-**Ideas for improvement:**
-- Additional interview questions
-- More research sources
-- Integration with other tools
-- Custom templates
-- Multi-language support
+MIT License
 
-## 🙏 Acknowledgments
-
-### @wbern/claude-instructions
-The TDD workflow commands (`/red`, `/green`, `/refactor`, `/cycle`) are based on the excellent [@wbern/claude-instructions](https://github.com/wbern/claude-instructions) package by **William Bernmalm**. This project extends those patterns with interview-driven API development, research enforcement hooks, and comprehensive state tracking.
-
-### Anthropic
-The interview methodology is inspired by [Anthropic's Interviewer approach](https://www.anthropic.com/news/anthropic-interviewer) for structured discovery.
-
-### Context7
-Special thanks to the [Context7](https://context7.com) team for providing live documentation lookup that makes research-first development possible.
-
----
-
-Thank you to the Claude Code community for making AI-assisted development more rigorous!
-
-## 📄 License
-
-MIT License - Use freely in your projects
-
-## 🔗 Links
+## Links
 
 - **Repository:** https://github.com/hustle-together/api-dev-tools
-- **Issues:** https://github.com/hustle-together/api-dev-tools/issues
 - **NPM:** https://www.npmjs.com/package/@hustle-together/api-dev-tools
 
-## 💬 Support
-
-- Open an issue on GitHub
-- Check command documentation in `.claude/commands/README.md`
-- Review example workflows in the repository
-
 ---
 
-**Made with ❤️ for API developers using Claude Code**
+**Made with care for API developers using Claude Code**
 
-*"Interview first, test first, document always"*
+*"Disambiguate, research, interview, verify, repeat"*