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

package/commands/README.md

@@ -1,275 +1,168 @@
-# API Development Slash Commands
+# API Development Slash Commands v3.0
 
-**Comprehensive API development workflow with programmatic enforcement**
+**Interview-driven, research-first API development workflow with continuous verification loops**
 
-## Overview
+## What's New in v3.0
 
-These slash commands implement an interview-driven, test-first methodology for API development. They automate the workflow described in the V2 Development Patterns and ensure consistent, high-quality API implementations.
+- **Phase 0: Disambiguation** - Search variations before research
+- **Phase 9: 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
+- **Research Freshness** - 7-day cache with staleness warnings
 
-## Programmatic Enforcement (Hooks)
+## Hook Architecture (9 Hooks)
 
-This package includes **Python hooks** that provide real programmatic guarantees:
-
-| Hook | Trigger | Purpose |
-|------|---------|---------|
-| `enforce-research.py` | PreToolUse (Write/Edit) | Blocks API code writing until research is complete |
-| `track-tool-use.py` | PostToolUse (WebSearch/Context7) | Logs all research activity to state file |
-| `api-workflow-check.py` | Stop | Prevents stopping until required phases complete |
-
-### What Gets Enforced
-
-- **Research MUST happen first** - Cannot write API route code without completing research
-- **All research is logged** - WebSearch, WebFetch, Context7 calls tracked in state file
-- **Progress is visible** - Check `.claude/api-dev-state.json` anytime
-- **Workflow completion verified** - Cannot stop until TDD phases complete
-
-### Check Progress
-
-```bash
-# View current state
-cat .claude/api-dev-state.json | jq '.phases'
-
-# Or use the status command
-/api-status
-```
+| Hook | Event | Purpose |
+|------|-------|---------|
+| `session-startup.py` | SessionStart | Inject state at session start |
+| `enforce-external-research.py` | UserPromptSubmit | Detect API terms, require research |
+| `enforce-research.py` | PreToolUse | Block writes until research done |
+| `enforce-interview.py` | PreToolUse | Inject interview decisions |
+| `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 |
+| `api-workflow-check.py` | Stop | Block if phases incomplete |
 
 ## Available Commands
 
-### 🎯 Complete Workflow
+### Complete Workflow
 
 **`/api-create [endpoint-name]`**
-- Orchestrates the entire API development process
-- Runs all phases automatically: Interview → Research → Environment Check → TDD → Documentation
-- Use this for new endpoints to ensure nothing is missed
+- Runs all 12 phases automatically
+- Loop-back architecture at every checkpoint
+- See [api-create.md](api-create.md) for full flow
 
-### 📋 Individual Phases
+### Individual Phases
 
 **`/api-interview [endpoint-name]`**
-- Conducts structured 20-question interview (Anthropic Interviewer methodology)
-- Documents purpose, usage, requirements, edge cases
-- Creates endpoint documentation file
-- **Output:** `/src/v2/docs/endpoints/[endpoint-name].md`
+- Questions GENERATED from research findings
+- Different question types: enum, continuous, boolean
+- See [api-interview.md](api-interview.md)
 
 **`/api-research [library-or-service]`**
-- Researches external APIs, SDKs, and libraries
-- Discovers ALL parameters (documented + undocumented)
-- Extracts complete schemas from source code
-- Documents integration requirements
-- **Output:** `/src/v2/docs/research/[library-name].md`
+- Adaptive propose-approve flow (not shotgun)
+- Research cached with 7-day freshness
+- See [api-research.md](api-research.md)
+
+**`/api-verify [endpoint-name]`** (NEW)
+- Manual Phase 9 verification
+- Re-read docs, compare to implementation
+- Report gaps, loop back or document omissions
+- See [api-verify.md](api-verify.md)
 
 **`/api-env [endpoint-name]`**
-- Checks for required API keys
-- Verifies .env.local and .env.example
-- Provides setup instructions for missing keys
-- **Output:** Terminal report + action items
+- Check API keys and environment
+- See [api-env.md](api-env.md)
 
-**`/api-status [endpoint-name]`** or **`/api-status --all`**
-- Shows implementation progress
-- Tracks phases (Interview → Research → Red → Green → Refactor → Complete)
-- Updates V2 implementation status document
-- **Output:** Progress report
+**`/api-status [endpoint-name]`**
+- Track progress through 12 phases
+- See [api-status.md](api-status.md)
 
-### 🔴🟢🔵 TDD Cycle
+### TDD Commands
 
-Use the existing TDD commands from AI_WORKFLOW.md:
+From [@wbern/claude-instructions](https://github.com/wbern/claude-instructions):
 - `/red` - Write ONE failing test
 - `/green` - Minimal implementation to pass
-- `/refactor` - Clean up code while tests pass
-- `/cycle [description]` - Full Red → Green → Refactor loop
+- `/refactor` - Clean up while tests pass
+- `/cycle [description]` - Full Red → Green → Refactor
 
-## Complete Workflow Example
+## 12-Phase Flow
 
-### Option 1: Fully Automated
-```bash
-/api-create generate-css
 ```
-This will:
-1. Interview you about the endpoint
-2. Research required libraries (Gemini SDK, etc.)
-3. Check environment/API keys
-4. Write failing tests (Red)
-5. Implement minimal solution (Green)
-6. Refactor for quality (Refactor)
-7. Update all documentation
-8. Verify tests and coverage
-9. Create commit
-
-### Option 2: Manual Step-by-Step
-```bash
-# Phase 1: Understanding
-/api-interview generate-css
-# (Answer 20 questions about purpose, usage, requirements)
-
-# Phase 2: Research
-/api-research google-generative-ai
-# (Discovers all Gemini SDK parameters)
-
-# Phase 3: Environment
-/api-env generate-css
-# (Verifies GOOGLE_GENERATIVE_AI_API_KEY exists)
-
-# Phase 4: TDD Implementation
-/red
-# (Write failing tests based on interview + research)
-
-/green
-# (Implement route handler with Zod schemas)
+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
+```
 
-/refactor
-# (Clean up, extract patterns, improve code)
+## State File
 
-# Phase 5: Documentation
-# (Update api-tests-manifest.json, OpenAPI spec, status doc)
+All progress tracked in `.claude/api-dev-state.json`:
 
-# Phase 6: Commit
-pnpm test:run
-/commit
+```json
+{
+  "version": "3.0.0",
+  "endpoint": "brandfetch",
+  "turn_count": 23,
+  "phases": {
+    "disambiguation": { "status": "complete" },
+    "scope": { "status": "complete" },
+    "research_initial": { "status": "complete" },
+    "interview": { "status": "complete", "decisions": {...} },
+    "research_deep": {
+      "proposed_searches": [...],
+      "approved_searches": [...],
+      "skipped_searches": [...]
+    },
+    "verify": {
+      "gaps_found": 2,
+      "gaps_fixed": 2,
+      "intentional_omissions": [...]
+    }
+  },
+  "reground_history": [...]
+}
 ```
 
-## Command Cheat Sheet
-
-| Command | When to Use | Output |
-|---------|-------------|--------|
-| `/api-create [endpoint]` | Starting new endpoint | Complete implementation |
-| `/api-interview [endpoint]` | Need to understand requirements | Documentation file |
-| `/api-research [library]` | Integrating external API/SDK | Research document |
-| `/api-env [endpoint]` | Before implementation | Environment check report |
-| `/api-status [endpoint]` | Check progress | Status report |
-| `/red` | Write test first | Failing test |
-| `/green` | Make test pass | Working implementation |
-| `/refactor` | Clean up code | Improved code |
-| `/cycle [desc]` | Implement feature | Full TDD cycle |
+## Research Cache
 
-## File Structure Created
+Research cached in `.claude/research/`:
 
-Each endpoint creates this structure:
 ```
-src/app/api/v2/[endpoint-name]/
-├── route.ts                               # API handler with Zod schemas
-├── __tests__/
-│   └── [endpoint-name].api.test.ts       # Comprehensive tests
-└── README.md                              # Endpoint documentation
-
-src/v2/docs/
-├── endpoints/
-│   └── [endpoint-name].md                # Interview results
-└── research/
-    └── [library-name].md                 # External API research
-
-src/app/api-test/
-└── api-tests-manifest.json               # Updated with new tests
-
-src/lib/openapi/endpoints/
-└── [endpoint-name].ts                    # OpenAPI spec
+.claude/research/
+├── brandfetch/
+│   ├── 2025-12-08_initial.md
+│   ├── 2025-12-08_deep.md
+│   └── CURRENT.md
+└── index.json  ← Freshness tracking (7-day validity)
 ```
 
-## Workflow Principles
-
-### 1. Context First
-**Never write code without understanding WHY it exists.**
-- Interview before implementation
-- Document real-world usage
-- Understand edge cases
-
-### 2. Research Thoroughly
-**Find ALL parameters, not just the documented ones.**
-- Read official docs
-- Check source code
-- Review TypeScript definitions
-- Test assumptions
-
-### 3. Test First (TDD)
-**No implementation without a failing test.**
-- Red: Write test that fails
-- Green: Minimal code to pass
-- Refactor: Improve while tests pass
-
-### 4. Document Everything
-**Future you needs to understand this.**
-- Interview results
-- Research findings
-- API schemas
-- Code examples
-- Testing notes
-
-### 5. Verify Environment
-**Check API keys before starting.**
-- Identify required services
-- Verify keys exist
-- Document setup
-- Test connections
-
-## Integration with Existing Tools
-
-These commands work alongside:
-- **`/plan`** - Create implementation checklist
-- **`/gap`** - Find missing pieces
-- **`/issue [url]`** - Start from GitHub issue
-- **`/commit`** - AI-generated semantic commits
-- **`/pr`** - Create pull request
-
-## Why This Approach Works
-
-### Problems with Previous Approach
-❌ Tests written without understanding purpose
-❌ Missing parameters from incomplete research
-❌ Failed tests due to missing API keys
-❌ No documentation of real-world usage
-❌ Mechanical testing without context
-
-### Benefits of New Approach
-✅ Deep understanding before coding
-✅ Complete parameter coverage
-✅ Environment verified upfront
-✅ Documentation drives implementation
-✅ Tests reflect actual usage patterns
-✅ Consistent, repeatable process
-✅ Nothing gets forgotten
-
-## Getting Started
-
-### First Time Setup
-1. Review this README
-2. Read `/src/v2/docs/AI_WORKFLOW.md`
-3. Read `/src/v2/docs/Main Doc – V2 Development Patterns.md`
-4. Try `/api-create` with a simple endpoint
-
-### For Each New Endpoint
+## Quick Start
+
+### Automated
 ```bash
-# Quick automated approach
-/api-create [endpoint-name]
-
-# Or manual for learning
-/api-interview [endpoint-name]
-/api-research [library]
-/api-env [endpoint-name]
-/cycle [description]
-/commit
+/api-create my-endpoint
 ```
 
-### Checking Progress
+### Manual Step-by-Step
 ```bash
-/api-status --all           # See all endpoints
-/api-status [endpoint]      # Specific endpoint
-pnpm test:run               # Verify tests pass
+/api-research [library]      # Initial research
+/api-interview [endpoint]    # Questions from research
+/api-env [endpoint]          # Verify environment
+/red                         # Failing tests
+/green                       # Make tests pass
+/api-verify [endpoint]       # Compare to docs
+/refactor                    # Clean up
+/commit                      # Semantic commit
 ```
 
 ## Installation
 
-Install via NPX command:
 ```bash
 npx @hustle-together/api-dev-tools --scope=project
 ```
 
-This installs:
-- **Commands** in `.claude/commands/` (slash commands)
-- **Hooks** in `.claude/hooks/` (Python enforcement scripts)
-- **Settings** in `.claude/settings.json` (hook registration)
-- **State template** in `.claude/api-dev-state.json` (progress tracking)
+Installs:
+- Commands in `.claude/commands/`
+- Hooks in `.claude/hooks/`
+- Settings in `.claude/settings.json`
+- State template in `.claude/api-dev-state.json`
+- Research index in `.claude/research/index.json`
 
-### Team-Wide Installation
+### Team-Wide
 
-Add to your project's `package.json`:
+Add to `package.json`:
 ```json
 {
   "scripts": {
@@ -278,35 +171,15 @@ Add to your project's `package.json`:
 }
 ```
 
-Now `npm install` or `pnpm install` automatically installs the tools for all team members.
-
-## References
-
-- **AI Workflow:** `/src/v2/docs/AI_WORKFLOW.md`
-- **V2 Patterns:** `/src/v2/docs/Main Doc – V2 Development Patterns.md`
-- **AI SDK Catalog:** `/src/v2/docs/ai-sdk-catalog.json`
-- **API Testing Plan:** `/src/v2/docs/API_TESTING_PLAN.md`
-- **Implementation Status:** `/src/v2/docs/v2-api-implementation-status.md`
-
-## Support
-
-If commands aren't working:
-1. Check that files exist in `.claude/commands/`
-2. Verify command syntax matches usage examples
-3. Review error messages for missing dependencies
-4. Check that required docs exist in `/src/v2/docs/`
-
-## Contributing
+## Key Principles
 
-To improve these commands:
-1. Edit markdown files in `.claude/commands/`
-2. Update this README
-3. Test with real endpoint implementation
-4. Document learnings
-5. Commit improvements
+1. **Loop Until Green** - Every verification loops back if not successful
+2. **Continuous Interviews** - Checkpoints at EVERY phase transition
+3. **Adaptive Research** - Propose based on context, not shotgun
+4. **Self-Documenting** - State file captures everything
+5. **Verify After Green** - Re-research to catch memory errors
 
 ---
 
-**Last Updated:** 2025-12-06
-**Version:** 1.0.0
-**Status:** Ready for use
+**Version:** 3.0.0
+**Last Updated:** 2025-12-08