@hustle-together/api-dev-tools 3.11.1 → 3.12.2

package/.claude/commands/api-create.md

@@ -9,6 +9,7 @@
 **YOU MUST USE THE `AskUserQuestion` TOOL AT EVERY CHECKPOINT.**
 
 This workflow requires REAL user input at each phase. You are **FORBIDDEN** from:
+
 - Self-answering questions
 - Assuming user responses
 - Proceeding without explicit user confirmation
@@ -26,9 +27,9 @@ At every `[Y/n]` or multiple-choice prompt in this workflow, you MUST call the `
       "header": "Phase",
       "multiSelect": false,
       "options": [
-        {"label": "Option A", "description": "What this option means"},
-        {"label": "Option B", "description": "What this option means"},
-        {"label": "Other", "description": "I'll type my own answer"}
+        { "label": "Option A", "description": "What this option means" },
+        { "label": "Option B", "description": "What this option means" },
+        { "label": "Other", "description": "I'll type my own answer" }
       ]
     }
   ]
@@ -36,6 +37,7 @@ At every `[Y/n]` or multiple-choice prompt in this workflow, you MUST call the `
 ```
 
 **CRITICAL REQUIREMENTS:**
+
 - `header`: Max 12 characters (e.g., "Scope", "Research", "Format")
 - `options`: 2-4 options, each with `label` (1-5 words) and `description`
 - `multiSelect`: Required boolean (true for checkboxes, false for radio)
@@ -47,6 +49,7 @@ At every `[Y/n]` or multiple-choice prompt in this workflow, you MUST call the `
 ### Violation Detection
 
 The enforcement hooks will BLOCK your progress if:
+
 - `user_question_asked` is false for any phase
 - `user_confirmed`/`user_approved`/`user_completed` is false
 - `phase_exit_confirmed` is false (user must explicitly approve proceeding to next phase)
@@ -59,27 +62,35 @@ If you see "BLOCKED" messages, it means you skipped user interaction.
 **Every phase requires an EXIT CONFIRMATION question** before proceeding to the next phase. This prevents Claude from self-answering and moving on without explicit user approval.
 
 The exit confirmation question MUST:
+
 1. Summarize what was accomplished in the current phase
 2. Ask if user is ready to proceed to the next phase
 3. Include options like "Yes, proceed", "No, I have changes", "Add more"
 
 Example exit confirmation:
+
 ```json
 {
-  "questions": [{
-    "question": "Phase complete. Research found 5 sources. Ready to proceed to Interview phase?",
-    "header": "Proceed",
-    "multiSelect": false,
-    "options": [
-      {"label": "Yes, proceed", "description": "Move to next phase"},
-      {"label": "No, more research", "description": "I need additional research on [topic]"},
-      {"label": "Review sources", "description": "Show me what was found"}
-    ]
-  }]
+  "questions": [
+    {
+      "question": "Phase complete. Research found 5 sources. Ready to proceed to Interview phase?",
+      "header": "Proceed",
+      "multiSelect": false,
+      "options": [
+        { "label": "Yes, proceed", "description": "Move to next phase" },
+        {
+          "label": "No, more research",
+          "description": "I need additional research on [topic]"
+        },
+        { "label": "Review sources", "description": "Show me what was found" }
+      ]
+    }
+  ]
 }
 ```
 
 The `phase_exit_confirmed` flag is automatically set when:
+
 1. An `AskUserQuestion` is called with a question containing words like "proceed", "continue", "ready", "confirm", "approve"
 2. The user responds with an affirmative answer (yes, proceed, confirm, approve, etc.)
 
@@ -464,16 +475,16 @@ This command creates:
 
 ## Hooks That Enforce This Workflow
 
-| Phase | Hook | Purpose |
-|-------|------|---------|
-| 0 | `enforce-external-research.py` | Detects API terms, requires disambiguation |
-| 2-4 | `track-tool-use.py` | Logs all research, tracks turns |
-| 7-8 | `enforce-research.py` | Blocks Write if no research done |
-| 7-8 | `enforce-interview.py` | Injects interview decisions |
-| 8 | `verify-implementation.py` | Blocks route if no test file |
-| 9 | `verify-after-green.py` | Triggers verification after tests pass |
-| All | `periodic-reground.py` | Re-grounds every 7 turns |
-| 11 | `api-workflow-check.py` | Blocks completion if docs incomplete |
+| Phase | Hook                           | Purpose                                    |
+| ----- | ------------------------------ | ------------------------------------------ |
+| 0     | `enforce-external-research.py` | Detects API terms, requires disambiguation |
+| 2-4   | `track-tool-use.py`            | Logs all research, tracks turns            |
+| 7-8   | `enforce-research.py`          | Blocks Write if no research done           |
+| 7-8   | `enforce-interview.py`         | Injects interview decisions                |
+| 8     | `verify-implementation.py`     | Blocks route if no test file               |
+| 9     | `verify-after-green.py`        | Triggers verification after tests pass     |
+| All   | `periodic-reground.py`         | Re-grounds every 7 turns                   |
+| 11    | `api-workflow-check.py`        | Blocks completion if docs incomplete       |
 
 <claude-commands-template>
 ## Project-Specific Rules
@@ -484,7 +495,7 @@ This command creates:
 4. **AI SDK**: Use Vercel AI SDK 5.0.11 patterns from `/src/v2/docs/ai-sdk-catalog.json`
 5. **Package Manager**: Use `pnpm` for all operations
 6. **Documentation**: Follow patterns in `/src/v2/docs/Main Doc – V2 Development Patterns.md`
-7. **API Keys**: Support three methods (env, NEXT_PUBLIC_, custom headers)
+7. **API Keys**: Support three methods (env, NEXT*PUBLIC*, custom headers)
 8. **Test Command**: `pnpm test:run` before commits
 
 ## Never Skip
@@ -496,4 +507,4 @@ This command creates:
 - Phase 10 (Verify) - Re-research after Green
 - Phase 12 (Documentation) - Keep docs in sync
 - Coverage verification - 100% required
-</claude-commands-template>
+  </claude-commands-template>

package/.claude/commands/api-env.md

@@ -42,6 +42,7 @@ Status: BLOCKED - Cannot proceed without FIRECRAWL_API_KEY
 ## API Key Support
 
 The project supports three methods:
+
 1. Server env: `OPENAI_API_KEY=sk-...`
 2. Client env: `NEXT_PUBLIC_OPENAI_API_KEY=sk-...`
 3. Custom headers: `X-OpenAI-Key: sk-...`

package/.claude/commands/api-interview.md

@@ -7,6 +7,7 @@
 ## Key Principle: Questions FROM Research
 
 **OLD WAY (Generic Templates):**
+
 ```
 "Which AI provider should this endpoint support?"
 - OpenAI
@@ -15,6 +16,7 @@
 ```
 
 **NEW WAY (From Research):**
+
 ```
 Based on research, Brandfetch API has 7 parameters:
 
@@ -40,6 +42,7 @@ Based on research, Brandfetch API has 7 parameters:
 **Interview is BLOCKED until research is done.**
 
 The interview READS from the research findings:
+
 ```
 State file shows:
   research_initial.status = "complete"
@@ -57,6 +60,7 @@ Discovered parameters:
 For each discovered parameter, generate an appropriate question:
 
 #### Required Parameters (Confirmation Only)
+
 ```
 ┌────────────────────────────────────────────────────────────┐
 │ REQUIRED PARAMETERS                                        │
@@ -71,6 +75,7 @@ For each discovered parameter, generate an appropriate question:
 ```
 
 #### Enum Parameters (Multi-Select)
+
 ```
 ┌────────────────────────────────────────────────────────────┐
 │ FORMAT PARAMETER                                           │
@@ -87,6 +92,7 @@ For each discovered parameter, generate an appropriate question:
 ```
 
 #### Continuous Parameters (Test Strategy)
+
 ```
 ┌────────────────────────────────────────────────────────────┐
 │ QUALITY PARAMETER                                          │
@@ -105,6 +111,7 @@ For each discovered parameter, generate an appropriate question:
 ```
 
 #### Boolean Parameters (Enable/Disable)
+
 ```
 ┌────────────────────────────────────────────────────────────┐
 │ INCLUDE_COLORS PARAMETER                                   │
@@ -189,14 +196,14 @@ After interview, propose additional research:
 
 ## Question Types Summary
 
-| Discovered Type | Question Type | Example |
-|----------------|---------------|---------|
-| Required param | Confirmation | "Confirm these are understood?" |
-| Enum param | Multi-select | "Which formats to support?" |
-| Continuous range | Test strategy | "How to test 1-100 range?" |
-| Boolean param | Enable/disable | "Expose this parameter?" |
-| Optional feature | Priority | "Include this feature?" |
-| Error case | Handling strategy | "How to handle rate limits?" |
+| Discovered Type  | Question Type     | Example                         |
+| ---------------- | ----------------- | ------------------------------- |
+| Required param   | Confirmation      | "Confirm these are understood?" |
+| Enum param       | Multi-select      | "Which formats to support?"     |
+| Continuous range | Test strategy     | "How to test 1-100 range?"      |
+| Boolean param    | Enable/disable    | "Expose this parameter?"        |
+| Optional feature | Priority          | "Include this feature?"         |
+| Error case       | Handling strategy | "How to handle rate limits?"    |
 
 ## State Tracking
 
@@ -239,7 +246,7 @@ All decisions are saved to `.claude/api-dev-state.json`:
 
 Creates: `.claude/research/[api-name]/interview.md`
 
-```markdown
+````markdown
 # Interview: [API Name]
 
 **Date:** [current-date]
@@ -248,19 +255,19 @@ Creates: `.claude/research/[api-name]/interview.md`
 
 ## Discovered Parameters
 
-| Parameter | Type | Required | Decision |
-|-----------|------|----------|----------|
-| domain | string | Yes | Always required |
-| format | enum | No | json, svg, png |
-| quality | 1-100 | No | Boundary testing: 1, 50, 100 |
+| Parameter | Type   | Required | Decision                     |
+| --------- | ------ | -------- | ---------------------------- |
+| domain    | string | Yes      | Always required              |
+| format    | enum   | No       | json, svg, png               |
+| quality   | 1-100  | No       | Boundary testing: 1, 50, 100 |
 
 ## Feature Scope
 
-| Feature | Included | Reason |
-|---------|----------|--------|
-| Basic fetch | Yes | Core functionality |
-| Multiple formats | Yes | User selected |
-| Webhooks | No | Deferred to v2 |
+| Feature          | Included | Reason             |
+| ---------------- | -------- | ------------------ |
+| Basic fetch      | Yes      | Core functionality |
+| Multiple formats | Yes      | User selected      |
+| Webhooks         | No       | Deferred to v2     |
 
 ## Test Strategy
 
@@ -277,6 +284,7 @@ Creates: `.claude/research/[api-name]/interview.md`
   "rate_limit_handling": "exponential_backoff"
 }
 ```
+````
 
 ## Deep Research Approved
 
@@ -286,6 +294,7 @@ Creates: `.claude/research/[api-name]/interview.md`
 ## Open Questions
 
 [Any remaining ambiguities]
+
 ```
 
 ## Integration with Hooks
@@ -293,14 +302,17 @@ Creates: `.claude/research/[api-name]/interview.md`
 The `enforce-interview.py` hook injects these decisions when Claude tries to write implementation:
 
 ```
+
 INTERVIEW CONTEXT REMINDER
 
 When implementing, remember user decisions:
+
 - format: ["json", "svg", "png"] (raw excluded)
 - quality: boundary testing (1, 50, 100)
 - rate limits: exponential backoff
 
 Source: .claude/api-dev-state.json
+
 ```
 
 <claude-commands-template>
@@ -329,3 +341,4 @@ Source: .claude/api-dev-state.json
 - Decisions injected during implementation via hook
 - Consistency between interview answers and code enforced
 </claude-commands-template>
+```

package/.claude/commands/api-research.md

@@ -9,6 +9,7 @@
 **NOT shotgun research** - We don't blindly run 20 searches.
 
 **Adaptive flow:**
+
 1. Run 2-3 initial searches
 2. Summarize findings
 3. PROPOSE additional searches based on context
@@ -21,6 +22,7 @@
 ### Initial Discovery (Automatic)
 
 Run 2-3 targeted searches:
+
 ```
 - Context7: "[library-name]" (if SDK/library)
 - WebSearch: "[name] official documentation"
@@ -28,6 +30,7 @@ Run 2-3 targeted searches:
 ```
 
 Present initial summary:
+
 ```
 ┌────────────────────────────────────────────────────────────┐
 │ INITIAL RESEARCH: [library-name]                           │
@@ -81,6 +84,7 @@ After interview, PROPOSE targeted searches based on user's selections:
 ### Execute Approved Searches
 
 Only run searches that were explicitly approved:
+
 - Track which searches were proposed vs approved vs skipped
 - Log everything to state file for transparency
 
@@ -100,9 +104,7 @@ Only run searches that were explicitly approved:
       "SVG optimization options",
       "batch processing"
     ],
-    "skipped_searches": [
-      "webhook support"
-    ]
+    "skipped_searches": ["webhook support"]
   }
 }
 ```
@@ -141,6 +143,7 @@ Research is cached in `.claude/research/[api-name]/`:
 ```
 
 **Freshness Rule:** If research is >7 days old when referenced:
+
 ```
 ⚠️ Research for "brandfetch" is 15 days old.
 Re-research before using? [Y/n]
@@ -150,7 +153,7 @@ Re-research before using? [Y/n]
 
 Creates: `.claude/research/[library-name]/CURRENT.md`
 
-```markdown
+````markdown
 # Research: [Library/Service Name]
 
 **Date:** [current-date]
@@ -159,6 +162,7 @@ Creates: `.claude/research/[library-name]/CURRENT.md`
 **Freshness:** 0 days (valid for 7 days)
 
 ## 1. Official Documentation Links
+
 - Main docs: [URL]
 - API reference: [URL]
 - GitHub repo: [URL]
@@ -166,72 +170,93 @@ Creates: `.claude/research/[library-name]/CURRENT.md`
 - TypeScript types: [URL]
 
 ## 2. Installation & Setup
+
 ### Installation
+
 ```bash
 [installation command]
 ```
+````
 
 ### Environment Variables
+
 ```env
 [required env vars]
 ```
 
 ### API Key Setup
+
 [How to obtain and configure]
 
 ## 3. Complete Request Schema
+
 ### Required Parameters
-| Parameter | Type | Description | Validation |
-|-----------|------|-------------|------------|
-| [name] | [type] | [desc] | [rules] |
+
+| Parameter | Type   | Description | Validation |
+| --------- | ------ | ----------- | ---------- |
+| [name]    | [type] | [desc]      | [rules]    |
 
 ### Optional Parameters
-| Parameter | Type | Default | Description | Notes |
-|-----------|------|---------|-------------|-------|
-| [name] | [type] | [default] | [desc] | [notes] |
+
+| Parameter | Type   | Default   | Description | Notes   |
+| --------- | ------ | --------- | ----------- | ------- |
+| [name]    | [type] | [default] | [desc]      | [notes] |
 
 ### Continuous Parameters (for test strategy)
-| Parameter | Type | Range | Suggested Test Values |
-|-----------|------|-------|----------------------|
-| quality | number | 1-100 | 1, 50, 100 (boundary) |
-| timeout | number | 1000-30000 | 1000, 15000, 30000 |
+
+| Parameter | Type   | Range      | Suggested Test Values |
+| --------- | ------ | ---------- | --------------------- |
+| quality   | number | 1-100      | 1, 50, 100 (boundary) |
+| timeout   | number | 1000-30000 | 1000, 15000, 30000    |
 
 ## 4. Complete Response Schema
+
 ### Success Response
+
 [TypeScript interface]
 
 ### Error Response
+
 [TypeScript interface with error codes]
 
 ## 5. Features & Capabilities
+
 ### Core Features (Discovered)
+
 - [x] [Feature 1]: [description]
 - [x] [Feature 2]: [description]
 
 ### Features NOT Implemented (Intentional)
+
 - [ ] [Feature]: [reason for exclusion]
 
 ## 6. Limitations & Constraints
+
 - Rate limits: [details]
 - Size limits: [details]
 - Timeout: [details]
 
 ## 7. Testing Considerations
+
 - [ ] Test boundary values for continuous params
 - [ ] Test all enum values
 - [ ] Test error responses
 - [ ] Test rate limiting behavior
 
 ## 8. Research Trail
+
 ### Searches Performed
-| Search | Tool | Found |
-|--------|------|-------|
-| "[name] documentation" | WebSearch | ✓ |
-| "[name]" | Context7 | ✓ |
+
+| Search                 | Tool      | Found |
+| ---------------------- | --------- | ----- |
+| "[name] documentation" | WebSearch | ✓     |
+| "[name]"               | Context7  | ✓     |
 
 ### Proposed but Skipped
+
 - "webhook support" - User declined, not needed
-```
+
+````
 
 ## Research-First Schema Design (MANDATORY)
 
@@ -296,11 +321,12 @@ All research is tracked in `.claude/api-dev-state.json`:
     }
   }
 }
-```
+````
 
 ## Usage Examples
 
 ### Research with full flow
+
 ```bash
 /api-research brandfetch
 # → Initial search (2-3 queries)
@@ -328,4 +354,4 @@ All research is tracked in `.claude/api-dev-state.json`:
 - Phase 5 uses adaptive proposal flow
 - Phase 10 (Verify) triggers re-research
 - Freshness check prevents stale data
-</claude-commands-template>
+  </claude-commands-template>

package/.claude/commands/api-status.md

@@ -18,6 +18,7 @@ Path: .claude/api-dev-state.json
 ```
 
 Parse the JSON and display a formatted status report showing:
+
 - Current endpoint being worked on
 - Phase completion status (scope, research, interview, TDD, docs)
 - Sources consulted during research
@@ -60,6 +61,7 @@ VERIFICATION:
 ## What This Shows
 
 ### For Specific Endpoint
+
 ```
 📊 Status: /api/v2/generate-css
 
@@ -87,6 +89,7 @@ Next Steps: None - endpoint complete
 ```
 
 ### For All Endpoints
+
 ```
 📊 V2 API Implementation Status
 
@@ -122,12 +125,14 @@ Last updated: 2025-12-06
 ## Commands
 
 ### View Status
+
 ```bash
 /api-status generate-css    # Specific endpoint
 /api-status --all           # All endpoints
 ```
 
 ### Update Status
+
 ```bash
 /api-status generate-css --phase=testing
 /api-status generate-css --complete
@@ -138,6 +143,7 @@ Last updated: 2025-12-06
 Updates: `/src/v2/docs/v2-api-implementation-status.md`
 
 **Format:**
+
 ```markdown
 # V2 API Implementation Status
 
@@ -148,6 +154,7 @@ Updates: `/src/v2/docs/v2-api-implementation-status.md`
 ## Endpoints
 
 ### ✅ /api/v2/health
+
 - **Status:** Complete
 - **Tests:** 15/15 passing
 - **Coverage:** 100%
@@ -156,6 +163,7 @@ Updates: `/src/v2/docs/v2-api-implementation-status.md`
 - **Purpose:** System health check with dependency validation
 
 ### 🚧 /api/v2/generate-css
+
 - **Status:** In Progress (Testing)
 - **Tests:** 20/33 passing
 - **Coverage:** 85%
@@ -165,6 +173,7 @@ Updates: `/src/v2/docs/v2-api-implementation-status.md`
 - **Next:** Complete remaining tests
 
 ### 📋 /api/v2/generate-html
+
 - **Status:** Planned
 - **Priority:** High
 - **Dependencies:** None
@@ -175,24 +184,28 @@ Updates: `/src/v2/docs/v2-api-implementation-status.md`
 ## Integration with Workflow
 
 ### After Interview
+
 ```bash
 /api-interview generate-css
 /api-status generate-css --phase=interview-complete
 ```
 
 ### After Research
+
 ```bash
 /api-research gemini-flash
 /api-status generate-css --phase=research-complete
 ```
 
 ### After TDD Cycle
+
 ```bash
 /cycle generate CSS with Gemini
 /api-status generate-css --complete
 ```
 
 ### Before Commit
+
 ```bash
 pnpm test:run
 /api-status --all  # Verify all green
@@ -202,6 +215,7 @@ pnpm test:run
 ## Automatic Updates
 
 The `/api-create` command automatically updates status:
+
 - Interview phase → "Interview Complete"
 - Red phase → "Tests Written"
 - Green phase → "Implementation Complete"
@@ -224,21 +238,27 @@ The `/api-create` command automatically updates status:
 ## Reports
 
 ### Coverage Report
+
 ```bash
 /api-status --coverage
 ```
+
 Shows test coverage for all V2 endpoints.
 
 ### Migration Report
+
 ```bash
 /api-status --migration
 ```
+
 Shows progress from legacy to V2.
 
 ### Blockers Report
+
 ```bash
 /api-status --blocked
 ```
+
 Shows endpoints blocked by missing keys, dependencies, etc.
 
 <claude-commands-template>
@@ -256,4 +276,4 @@ Shows endpoints blocked by missing keys, dependencies, etc.
 - Used by /commit to verify readiness
 - Used by team to see what's done
 - Used for planning future work
-</claude-commands-template>
+  </claude-commands-template>

package/.claude/commands/api-verify.md

@@ -138,24 +138,24 @@ Creates: `.claude/research/[api-name]/verification.md`
 
 **Date:** [current-date]
 **Implementation File:** src/app/api/v2/[endpoint]/route.ts
-**Test File:** src/app/api/v2/[endpoint]/__tests__/[endpoint].api.test.ts
+**Test File:** src/app/api/v2/[endpoint]/**tests**/[endpoint].api.test.ts
 
 ## Documentation Sources Re-Checked
 
-| Source | URL | Checked |
-|--------|-----|---------|
-| Official docs | [URL] | ✓ |
-| Context7 | [library] | ✓ |
-| Cached research | .claude/research/[api]/CURRENT.md | ✓ |
+| Source          | URL                               | Checked |
+| --------------- | --------------------------------- | ------- |
+| Official docs   | [URL]                             | ✓       |
+| Context7        | [library]                         | ✓       |
+| Cached research | .claude/research/[api]/CURRENT.md | ✓       |
 
 ## Feature Comparison
 
-| Feature | In Docs | Implemented | Status |
-|---------|---------|-------------|--------|
-| domain param | ✓ | ✓ | ✅ Match |
-| format param | 4 options | 3 options | ⚠️ Fixed |
-| size param | ✓ | ✓ | ⚠️ Fixed |
-| webhook | ✓ | ✗ | ℹ️ Intentional |
+| Feature      | In Docs   | Implemented | Status         |
+| ------------ | --------- | ----------- | -------------- |
+| domain param | ✓         | ✓           | ✅ Match       |
+| format param | 4 options | 3 options   | ⚠️ Fixed       |
+| size param   | ✓         | ✓           | ⚠️ Fixed       |
+| webhook      | ✓         | ✗           | ℹ️ Intentional |
 
 ## Gaps Fixed
 
@@ -190,6 +190,7 @@ Creates: `.claude/research/[api-name]/verification.md`
 This command is normally triggered automatically by `verify-after-green.py` hook after tests pass.
 
 Manual invocation is useful when:
+
 - Hook was skipped or didn't trigger
 - Want to re-verify after changes
 - Research is stale and needs refresh
@@ -228,4 +229,4 @@ Phase 10: VERIFY ← /api-verify triggers this
 - Error codes handled?
 - Optional features accounted for?
 - Default values match docs?
-</claude-commands-template>
+  </claude-commands-template>