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

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

@@ -0,0 +1,344 @@
+# API Interview - Research-Driven Dynamic Discovery v3.0
+
+**Usage:** `/api-interview [endpoint-name]`
+
+**Purpose:** Conduct structured interview where questions are GENERATED FROM research findings, not generic templates. Every question is specific to the discovered API capabilities.
+
+## Key Principle: Questions FROM Research
+
+**OLD WAY (Generic Templates):**
+
+```
+"Which AI provider should this endpoint support?"
+- OpenAI
+- Anthropic
+- Google
+```
+
+**NEW WAY (From Research):**
+
+```
+Based on research, Brandfetch API has 7 parameters:
+
+1. DOMAIN (required) - string
+   → No question needed (always required)
+
+2. FORMAT: ["json", "svg", "png", "raw"]
+   Q: Which formats do you need?
+   [x] json  [x] svg  [x] png  [ ] raw
+
+3. QUALITY: 1-100 (continuous range)
+   Q: How should we TEST this continuous parameter?
+   [ ] All values (100 tests)
+   [x] Boundary (1, 50, 100)
+   [ ] Sample (1, 25, 50, 75, 100)
+   [ ] Custom: ____
+```
+
+## Interview Flow
+
+### PREREQUISITE - Research Must Be Complete (Phase 3)
+
+**Interview is BLOCKED until research is done.**
+
+The interview READS from the research findings:
+
+```
+State file shows:
+  research_initial.status = "complete"
+  research_initial.sources = [...]
+
+Discovered parameters:
+  - 5 required parameters
+  - 12 optional parameters
+  - 3 enum types
+  - 2 continuous ranges
+```
+
+### Parameter-Based Questions
+
+For each discovered parameter, generate an appropriate question:
+
+#### Required Parameters (Confirmation Only)
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ REQUIRED PARAMETERS                                        │
+│                                                            │
+│ These parameters are required by the API:                  │
+│                                                            │
+│ 1. domain (string) - The domain to fetch brand data for   │
+│ 2. apiKey (string) - Your Brandfetch API key              │
+│                                                            │
+│ Confirm these are understood? [Y/n]                        │
+└────────────────────────────────────────────────────────────┘
+```
+
+#### Enum Parameters (Multi-Select)
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ FORMAT PARAMETER                                           │
+│                                                            │
+│ Research found these format options:                       │
+│                                                            │
+│ [x] json   - Structured JSON response                      │
+│ [x] svg    - Vector logo format                            │
+│ [x] png    - Raster logo format                            │
+│ [ ] raw    - Raw API response (advanced)                   │
+│                                                            │
+│ Which formats should we support?                           │
+└────────────────────────────────────────────────────────────┘
+```
+
+#### Continuous Parameters (Test Strategy)
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ QUALITY PARAMETER                                          │
+│                                                            │
+│ Research found: quality is a continuous range 1-100        │
+│                                                            │
+│ How should we TEST this parameter?                         │
+│                                                            │
+│ [ ] All values (100 tests - comprehensive but slow)        │
+│ [x] Boundary (1, 50, 100 - 3 tests)                        │
+│ [ ] Sample (1, 25, 50, 75, 100 - 5 tests)                  │
+│ [ ] Custom values: ____                                    │
+│                                                            │
+│ Your testing strategy affects test count.                  │
+└────────────────────────────────────────────────────────────┘
+```
+
+#### Boolean Parameters (Enable/Disable)
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ INCLUDE_COLORS PARAMETER                                   │
+│                                                            │
+│ Research found: includeColors (boolean, default: true)     │
+│                                                            │
+│ Should we expose this parameter?                           │
+│                                                            │
+│ [x] Yes - Let users toggle it                              │
+│ [ ] No - Use default (true) always                         │
+│ [ ] Hardcode to: ____                                      │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Feature Questions
+
+Based on discovered features, ask about priorities:
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ DISCOVERED FEATURES                                        │
+│                                                            │
+│ Research found these features. Mark priorities:            │
+│                                                            │
+│ [x] Basic brand fetch - Get logo, colors, fonts            │
+│ [x] Multiple formats - Support json, svg, png              │
+│ [ ] Webhook callbacks - Async notification (skip for now)  │
+│ [ ] Batch processing - Multiple domains at once            │
+│ [x] Error handling - Graceful degradation                  │
+│                                                            │
+│ Confirm feature scope?                                     │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Error Handling Questions
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ ERROR HANDLING                                             │
+│                                                            │
+│ Research found these error cases in the API:               │
+│                                                            │
+│ - 400: Invalid domain format                               │
+│ - 401: Invalid API key                                     │
+│ - 404: Brand not found                                     │
+│ - 429: Rate limit exceeded                                 │
+│ - 500: Server error                                        │
+│                                                            │
+│ How should we handle rate limits (429)?                    │
+│                                                            │
+│ [x] Retry with exponential backoff                         │
+│ [ ] Return error immediately                               │
+│ [ ] Queue and retry later                                  │
+│ [ ] Custom: ____                                           │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Deep Research Proposal (Phase 5)
+
+After interview, propose additional research:
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ PROPOSED DEEP RESEARCH                                     │
+│                                                            │
+│ Based on your selections, I recommend researching:         │
+│                                                            │
+│ [x] Rate limiting behavior                                 │
+│     Reason: You selected "retry with backoff"              │
+│                                                            │
+│ [x] SVG optimization                                       │
+│     Reason: You selected SVG format                        │
+│                                                            │
+│ [ ] Webhook format                                         │
+│     Reason: You skipped webhook feature                    │
+│                                                            │
+│ Approve these searches? [Y]                                │
+│ Add more: ____                                             │
+│ Skip and proceed: [n]                                      │
+└────────────────────────────────────────────────────────────┘
+```
+
+## 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?"    |
+
+## State Tracking
+
+All decisions are saved to `.claude/api-dev-state.json`:
+
+```json
+{
+  "phases": {
+    "interview": {
+      "status": "complete",
+      "questions": [
+        {
+          "parameter": "format",
+          "type": "enum",
+          "options": ["json", "svg", "png", "raw"],
+          "selected": ["json", "svg", "png"],
+          "timestamp": "..."
+        },
+        {
+          "parameter": "quality",
+          "type": "continuous",
+          "range": [1, 100],
+          "test_strategy": "boundary",
+          "test_values": [1, 50, 100],
+          "timestamp": "..."
+        }
+      ],
+      "decisions": {
+        "format": ["json", "svg", "png"],
+        "quality_testing": "boundary",
+        "quality_values": [1, 50, 100],
+        "rate_limit_handling": "exponential_backoff"
+      }
+    }
+  }
+}
+```
+
+## Output
+
+Creates: `.claude/research/[api-name]/interview.md`
+
+````markdown
+# Interview: [API Name]
+
+**Date:** [current-date]
+**Research Sources:** [list from research phase]
+**Status:** Interview Complete
+
+## 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 |
+
+## Feature Scope
+
+| Feature          | Included | Reason             |
+| ---------------- | -------- | ------------------ |
+| Basic fetch      | Yes      | Core functionality |
+| Multiple formats | Yes      | User selected      |
+| Webhooks         | No       | Deferred to v2     |
+
+## Test Strategy
+
+- Enum parameters: Test all selected values
+- Continuous parameters: Boundary testing (3 values)
+- Error cases: 400, 401, 404, 429, 500
+
+## Decisions Summary
+
+```json
+{
+  "format": ["json", "svg", "png"],
+  "quality_testing": "boundary",
+  "rate_limit_handling": "exponential_backoff"
+}
+```
+````
+
+## Deep Research Approved
+
+- Rate limiting behavior (for retry logic)
+- SVG optimization (for SVG format)
+
+## Open Questions
+
+[Any remaining ambiguities]
+
+```
+
+## Integration with Hooks
+
+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>
+## Interview Guidelines v3.0
+
+1. **Questions FROM Research** - Never use generic templates
+2. **Parameter-Specific** - Each discovered param gets appropriate question
+3. **Test Strategy for Continuous** - Ask how to test ranges
+4. **Track Decisions** - Save everything to state file
+5. **Propose Deep Research** - Based on selections
+6. **No Skipped Parameters** - Every discovered param must have a decision
+
+## Question Generation Rules
+
+| If research finds... | Then ask... |
+|---------------------|-------------|
+| Enum with 3+ options | Multi-select: which to support |
+| Continuous range | Test strategy: all/boundary/sample |
+| Boolean param | Enable/disable/hardcode |
+| Optional feature | Include/exclude/defer |
+| Error case | Handling strategy |
+
+## After Interview
+
+- Decisions saved to state file
+- Decisions injected during implementation via hook
+- Consistency between interview answers and code enforced
+</claude-commands-template>
+```

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

@@ -0,0 +1,357 @@
+# API Research - Adaptive Documentation Discovery v3.0
+
+**Usage:** `/api-research [library-or-service-name]`
+
+**Purpose:** Research external APIs and SDKs using an adaptive, propose-approve flow (not shotgun searches).
+
+## Key Principle: Adaptive Research
+
+**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
+4. User approves/modifies proposals
+5. Execute approved searches
+6. Repeat until complete
+
+## Research Phases
+
+### Initial Discovery (Automatic)
+
+Run 2-3 targeted searches:
+
+```
+- Context7: "[library-name]" (if SDK/library)
+- WebSearch: "[name] official documentation"
+- WebSearch: "site:[domain] api reference" (if known domain)
+```
+
+Present initial summary:
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ INITIAL RESEARCH: [library-name]                           │
+│                                                            │
+│ │ Source              │ Status                             │
+│ ├─────────────────────┼────────────────────────────────────│
+│ │ Official docs       │ ✓ Found: [URL]                     │
+│ │ API Reference       │ ✓ REST v2 documented               │
+│ │ Auth method         │ ✓ Bearer token / API key           │
+│ │ TypeScript types    │ ? Not confirmed                    │
+│ │ npm package         │ ? Not searched                     │
+│                                                            │
+│ Discovered parameters: 5 required, 12 optional             │
+│                                                            │
+│ Proceed to interview? [Y]                                  │
+│ Search more first? [n] → What? ____                        │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Deep Research (Proposed)
+
+After interview, PROPOSE targeted searches based on user's selections:
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ PROPOSED DEEP RESEARCH                                     │
+│                                                            │
+│ Based on interview answers, I recommend researching:       │
+│                                                            │
+│ [x] Error response format                                  │
+│     Reason: You selected "comprehensive error handling"    │
+│                                                            │
+│ [x] Rate limiting behavior                                 │
+│     Reason: You selected "short cache" / high frequency    │
+│                                                            │
+│ [ ] Webhook support                                        │
+│     Reason: You didn't select async/webhook features       │
+│                                                            │
+│ [x] SVG optimization options                               │
+│     Reason: You selected SVG output format                 │
+│                                                            │
+│ [x] Batch processing                                       │
+│     Reason: You mentioned "multiple domains at once"       │
+│                                                            │
+│ Approve these searches? [Y]                                │
+│ Add more: ____                                             │
+│ Skip and proceed: [n]                                      │
+└────────────────────────────────────────────────────────────┘
+```
+
+### 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
+
+```json
+{
+  "research_deep": {
+    "proposed_searches": [
+      "error response format",
+      "rate limiting behavior",
+      "webhook support",
+      "SVG optimization options",
+      "batch processing"
+    ],
+    "approved_searches": [
+      "error response format",
+      "rate limiting behavior",
+      "SVG optimization options",
+      "batch processing"
+    ],
+    "skipped_searches": ["webhook support"]
+  }
+}
+```
+
+## Research Caching & Freshness
+
+Research is cached in `.claude/research/[api-name]/`:
+
+```
+.claude/research/
+├── brandfetch/
+│   ├── 2025-12-08_initial.md    # Timestamped snapshot
+│   ├── 2025-12-08_deep.md       # Deep research after interview
+│   └── CURRENT.md               # Latest (copy or symlink)
+├── vercel-ai-sdk/
+│   ├── providers/               # Complex APIs get subfolders
+│   │   ├── openai.md
+│   │   ├── anthropic.md
+│   │   └── groq.md
+│   └── CURRENT.md
+└── index.json                   # Catalog with freshness
+```
+
+### Freshness Tracking
+
+```json
+{
+  "brandfetch": {
+    "last_updated": "2025-12-08",
+    "current_file": "brandfetch/CURRENT.md",
+    "days_old": 0,
+    "parameters_discovered": 7,
+    "source_urls": ["https://docs.brandfetch.com"]
+  }
+}
+```
+
+**Freshness Rule:** If research is >7 days old when referenced:
+
+```
+⚠️ Research for "brandfetch" is 15 days old.
+Re-research before using? [Y/n]
+```
+
+## Output Format
+
+Creates: `.claude/research/[library-name]/CURRENT.md`
+
+````markdown
+# Research: [Library/Service Name]
+
+**Date:** [current-date]
+**Version:** [version-number]
+**Status:** Research Complete
+**Freshness:** 0 days (valid for 7 days)
+
+## 1. Official Documentation Links
+
+- Main docs: [URL]
+- API reference: [URL]
+- GitHub repo: [URL]
+- npm package: [URL]
+- 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]    |
+
+### Optional Parameters
+
+| 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    |
+
+## 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  | ✓     |
+
+### Proposed but Skipped
+
+- "webhook support" - User declined, not needed
+
+````
+
+## Research-First Schema Design (MANDATORY)
+
+### The Anti-Pattern: Schema-First Development
+
+**NEVER DO THIS:**
+- ❌ Define interfaces based on assumptions before researching
+- ❌ Rely on training data for API capabilities
+- ❌ Say "I think it supports..." without verification
+- ❌ Build schemas from memory instead of documentation
+
+### The Correct Pattern: Research-First
+
+**ALWAYS DO THIS:**
+
+1. **Research the Source of Truth**
+   - Use Context7 for SDK docs
+   - Use WebSearch for official docs
+   - Check GitHub for current implementation
+
+2. **Build Schema FROM Research**
+   - Interface fields emerge from discovered capabilities
+   - Every field has a source (docs, SDK types, API response)
+   - Don't guess - verify each capability
+
+3. **Verify with Phase 10**
+   - After implementation, re-research
+   - Compare docs to implementation
+   - Fix gaps or document intentional omissions
+
+## Research Query Tracking
+
+All research is tracked in `.claude/api-dev-state.json`:
+
+```json
+{
+  "research_queries": [
+    {
+      "timestamp": "2025-12-08T...",
+      "tool": "WebSearch",
+      "query": "Brandfetch API documentation",
+      "terms": ["brandfetch", "api", "documentation"]
+    },
+    {
+      "timestamp": "2025-12-08T...",
+      "tool": "mcp__context7__get-library-docs",
+      "library": "brandfetch",
+      "terms": ["brandfetch"]
+    }
+  ],
+  "phases": {
+    "research_initial": {
+      "status": "complete",
+      "sources": [...],
+      "summary_approved": true
+    },
+    "research_deep": {
+      "status": "complete",
+      "proposed_searches": [...],
+      "approved_searches": [...],
+      "skipped_searches": [...]
+    }
+  }
+}
+````
+
+## Usage Examples
+
+### Research with full flow
+
+```bash
+/api-research brandfetch
+# → Initial search (2-3 queries)
+# → Present summary, ask to proceed
+# → Interview happens (separate phase)
+# → Propose deep research based on interview
+# → User approves/modifies
+# → Execute approved searches
+# → Cache results with freshness tracking
+```
+
+<claude-commands-template>
+## Research Guidelines
+
+1. **Start minimal** - 2-3 searches, not 20
+2. **Propose before executing** - User controls depth
+3. **Track everything** - State file logs all searches
+4. **Cache with freshness** - 7-day validity
+5. **Cite sources** - Every claim has a URL
+6. **Distinguish proposed vs approved** - Transparency
+
+## Integration with API Development
+
+- Phase 3 of `/api-create` uses this for initial research
+- Phase 5 uses adaptive proposal flow
+- Phase 10 (Verify) triggers re-research
+- Freshness check prevents stale data
+  </claude-commands-template>