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

package/.skills/api-env/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: api-env
+description: Check required API keys and environment variables. Supports server env vars, NEXT_PUBLIC_ vars, and custom headers. Use before starting implementation. Keywords: environment, api-keys, configuration, setup, validation
+license: MIT
+compatibility: Requires Claude Code with MCP servers (Context7, GitHub), Python 3.9+ for hooks, pnpm 10.11.0+
+metadata:
+  version: "3.0.0"
+  category: "development"
+  tags: ['environment', 'api-keys', 'configuration', 'setup']
+  author: "Hustle Together"
+allowed-tools: WebSearch WebFetch mcp__context7 mcp__github AskUserQuestion Read Write Edit Bash TodoWrite
+---
+
+# API Environment - Check API Keys & Configuration
+
+**Usage:** `/api-env [endpoint-name]`
+
+**Purpose:** Quick check for required API keys and environment setup before implementation.
+
+## What This Checks
+
+1. **Reads endpoint documentation** to identify required services
+2. **Checks .env.local** for API keys
+3. **Verifies .env.example** has templates
+4. **Reports missing keys** with setup instructions
+
+## Output
+
+```
+🔑 Environment Check: [endpoint-name]
+
+Required API Keys:
+✅ OPENAI_API_KEY (found)
+❌ FIRECRAWL_API_KEY (missing)
+
+Action Required:
+1. Get key from https://firecrawl.dev
+2. Add to .env.local: FIRECRAWL_API_KEY=fc-...
+3. Add to .env.example template
+
+Status: BLOCKED - Cannot proceed without FIRECRAWL_API_KEY
+```
+
+## Usage in Workflow
+
+```bash
+# Before starting implementation
+/api-interview generate-css
+/api-research firecrawl
+/api-env generate-css  ← Check keys
+/red                   ← Start TDD if ready
+```
+
+<claude-commands-template>
+## 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-...`
+
+Check src/lib/api-keys.ts for implementation.
+</claude-commands-template>

package/.skills/api-interview/SKILL.md

@@ -0,0 +1,357 @@
+---
+name: api-interview
+description: Structured interview for API requirements gathering. Questions generated FROM research findings, not templates. Use when you need to understand API parameter preferences, error handling, formats, and user decisions. Keywords: interview, requirements, api, questions, research, decisions
+license: MIT
+compatibility: Requires Claude Code with MCP servers (Context7, GitHub), Python 3.9+ for hooks, pnpm 10.11.0+
+metadata:
+  version: "3.0.0"
+  category: "development"
+  tags: ['api', 'interview', 'requirements', 'research']
+  author: "Hustle Together"
+allowed-tools: WebSearch WebFetch mcp__context7 mcp__github AskUserQuestion Read Write Edit Bash TodoWrite
+---
+
+# 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>
+```