@hustle-together/api-dev-tools 3.10.1 → 3.12.1

package/commands/hustle-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.)
 
@@ -374,9 +385,39 @@ Both conditions must be true for the flag to be set.
 └───────────────────────────────────────────────────────────┘
         │
         ▼
-┌─ PHASE 11: TDD REFACTOR ──────────────────────────────────┐
+┌─ PHASE 11: CODE REVIEW (Greptile) ────────────────────────┐
+│                                                           │
+│ Run Greptile AI code review BEFORE refactoring:           │
+│   • Bug detection with full codebase context              │
+│   • Security vulnerability scanning (OWASP top 10)        │
+│   • Performance issue identification                      │
+│                                                           │
+│ Review returns actionable issues with file:line refs.     │
+│ Requires: GREPTILE_API_KEY + GITHUB_TOKEN                 │
+│                                                           │
+│ ⚠️ REQUIRED: Use AskUserQuestion tool:                    │
+│                                                           │
+│   AskUserQuestion({                                       │
+│     questions: [{                                         │
+│       question: "Code review found [N] issue(s): [list].  │
+│                  How should I proceed?",                  │
+│       header: "Review",                                   │
+│       options: [                                          │
+│         "Fix all issues in refactor phase",               │
+│         "Fix critical only, defer others",                │
+│         "Skip - no issues to fix"                         │
+│       ]                                                   │
+│     }]                                                    │
+│   })                                                      │
+│                                                           │
+│ WAIT for user response. Do NOT auto-proceed.              │
+└───────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌─ PHASE 12: TDD REFACTOR ──────────────────────────────────┐
 │                                                           │
-│ Clean up code while tests stay green:                     │
+│ Fix code review issues + clean up while tests stay green: │
+│   • Address Greptile issues (bugs, security, performance) │
 │   • Extract reusable patterns                             │
 │   • Improve error messages                                │
 │   • Add JSDoc comments                                    │
@@ -386,7 +427,7 @@ Both conditions must be true for the flag to be set.
 └───────────────────────────────────────────────────────────┘
         │
         ▼
-┌─ PHASE 12: DOCUMENTATION ─────────────────────────────────┐
+┌─ PHASE 13: DOCUMENTATION ─────────────────────────────────┐
 │                                                           │
 │ Update documentation files, then:                         │
 │                                                           │
@@ -411,7 +452,7 @@ Both conditions must be true for the flag to be set.
 └───────────────────────────────────────────────────────────┘
         │
         ▼
-┌─ PHASE 13: COMPLETION ────────────────────────────────────┐
+┌─ PHASE 14: COMPLETION ────────────────────────────────────┐
 │                                                           │
 │ Final verification:                                       │
 │   • All tests passing                                     │
@@ -484,16 +525,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
@@ -504,7 +545,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
@@ -516,4 +557,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/commands/hustle-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/commands/hustle-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/commands/hustle-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
 /hustle-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/commands/hustle-api-sessions.md

@@ -3,19 +3,20 @@
 Browse and export saved session logs from previous API development workflows.
 
 ## Usage
+
 ```
 /hustle-api-sessions [options]
 ```
 
 ## Options
 
-| Option | Description |
-|--------|-------------|
-| `--list` | List all saved sessions |
-| `--view [endpoint]` | View a specific session |
-| `--export [endpoint] [format]` | Export session to PDF/HTML/MD |
-| `--search [term]` | Search across all sessions |
-| `--cleanup` | Remove old sessions (>30 days) |
+| Option                         | Description                    |
+| ------------------------------ | ------------------------------ |
+| `--list`                       | List all saved sessions        |
+| `--view [endpoint]`            | View a specific session        |
+| `--export [endpoint] [format]` | Export session to PDF/HTML/MD  |
+| `--search [term]`              | Search across all sessions     |
+| `--cleanup`                    | Remove old sessions (>30 days) |
 
 ## Examples