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

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

@@ -0,0 +1,370 @@
+---
+name: api-research
+description: Adaptive propose-approve research workflow for API documentation discovery. Use when researching external APIs, SDKs, or libraries. Caches research with 7-day freshness tracking. Keywords: research, documentation, api, discovery, cache, adaptive
+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: "research"
+  tags: ['api', 'research', 'documentation', 'discovery', 'cache']
+  author: "Hustle Together"
+allowed-tools: WebSearch WebFetch mcp__context7 mcp__github AskUserQuestion Read Write Edit Bash TodoWrite
+---
+
+# 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>

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

@@ -0,0 +1,292 @@
+---
+name: api-status
+description: Track implementation progress through 13 phases. Shows completed, in-progress, and pending phases. Displays interview decisions and research cache info. Keywords: status, progress, tracking, phases, workflow
+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: "workflow"
+  tags: ['status', 'progress', 'tracking', 'workflow']
+  author: "Hustle Together"
+allowed-tools: WebSearch WebFetch mcp__context7 mcp__github AskUserQuestion Read Write Edit Bash TodoWrite
+---
+
+# API Status - Track Implementation Progress
+
+**Usage:** `/api-status [endpoint-name]` or `/api-status --all`
+
+**Purpose:** View and update API implementation status, track progress, and manage V2 migration.
+
+## State File Integration
+
+This command reads from `.claude/api-dev-state.json` which is automatically updated by the enforcement hooks.
+
+### Reading Current State
+
+**FIRST: Read the state file to understand current progress:**
+
+```
+Tool: Read
+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
+- Timestamps for each phase
+- Verification status
+
+### Example State Display
+
+```
+📊 API Development Progress
+
+Endpoint: stream-text
+Library: vercel-ai-sdk
+Started: 2025-12-06T20:00:00Z
+
+PHASES:
+  ✅ Scope defined (20:00:30)
+  ✅ Initial research - 4 sources consulted (20:02:00)
+  🔄 Interview - in progress
+  ⬜ Deep research
+  ⬜ Schema creation
+  ⬜ Environment check
+  ⬜ TDD Red
+  ⬜ TDD Green
+  ⬜ TDD Refactor
+  ⬜ Documentation
+
+RESEARCH SOURCES:
+  • context7: @ai-sdk/core (20:01:00)
+  • websearch: "Vercel AI SDK streamText 2025" (20:01:30)
+  • webfetch: https://sdk.vercel.ai/docs (20:01:45)
+
+VERIFICATION:
+  ❌ All sources fetched: false
+  ❌ Schema matches docs: false
+  ❌ Tests cover params: false
+  ❌ All tests passing: false
+```
+
+## What This Shows
+
+### For Specific Endpoint
+
+```
+📊 Status: /api/v2/generate-css
+
+Phase: ✅ Complete
+Tests: 33/33 passing (100% coverage)
+Documentation: ✅ Complete
+
+Timeline:
+✅ Interview completed (2025-12-06)
+✅ Research completed (2025-12-06)
+✅ Environment verified (2025-12-06)
+✅ Tests written (Red phase)
+✅ Implementation complete (Green phase)
+✅ Refactored (Refactor phase)
+✅ Documentation updated
+✅ Committed to git
+
+Files:
+- Route: src/app/api/v2/generate-css/route.ts
+- Tests: src/app/api/v2/generate-css/__tests__/generate-css.api.test.ts
+- Docs: src/v2/docs/endpoints/generate-css.md
+- Research: src/v2/docs/research/gemini-flash.md
+
+Next Steps: None - endpoint complete
+```
+
+### For All Endpoints
+
+```
+📊 V2 API Implementation Status
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ COMPLETE (2)
+  • /api/v2/health (15 tests)
+  • /api/v2/monitor (23 tests)
+
+🚧 IN PROGRESS (1)
+  • /api/v2/generate-css (interview complete, implementing)
+
+📋 PLANNED (3)
+  • /api/v2/generate-html
+  • /api/v2/chat
+  • /api/v2/scrape
+
+❌ NOT STARTED (0)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Summary:
+  Total endpoints: 6
+  Complete: 2 (33%)
+  In progress: 1 (17%)
+  Planned: 3 (50%)
+  Total tests: 38
+  Coverage: 100%
+
+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
+```
+
+## Status Tracking File
+
+Updates: `/src/v2/docs/v2-api-implementation-status.md`
+
+**Format:**
+
+```markdown
+# V2 API Implementation Status
+
+**Last Updated:** 2025-12-06
+**Total Endpoints:** 6
+**Completed:** 2 (33%)
+
+## Endpoints
+
+### ✅ /api/v2/health
+
+- **Status:** Complete
+- **Tests:** 15/15 passing
+- **Coverage:** 100%
+- **Interview:** [Link to docs]
+- **Implemented:** 2025-12-06
+- **Purpose:** System health check with dependency validation
+
+### 🚧 /api/v2/generate-css
+
+- **Status:** In Progress (Testing)
+- **Tests:** 20/33 passing
+- **Coverage:** 85%
+- **Interview:** [Link to docs]
+- **Started:** 2025-12-06
+- **Blocked by:** None
+- **Next:** Complete remaining tests
+
+### 📋 /api/v2/generate-html
+
+- **Status:** Planned
+- **Priority:** High
+- **Dependencies:** None
+- **Interview:** Not started
+- **Estimated effort:** Medium
+```
+
+## 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
+/commit
+```
+
+## Automatic Updates
+
+The `/api-create` command automatically updates status:
+
+- Interview phase → "Interview Complete"
+- Red phase → "Tests Written"
+- Green phase → "Implementation Complete"
+- Refactor phase → "Refactored"
+- Documentation → "Documentation Updated"
+- Commit → "Complete"
+
+## Status Phases
+
+1. **Not Started** - No work begun
+2. **Interview Complete** - Understanding documented
+3. **Research Complete** - External docs reviewed
+4. **Environment Ready** - API keys verified
+5. **Tests Written** - Red phase complete
+6. **Implementation Complete** - Green phase complete
+7. **Refactored** - Code cleaned up
+8. **Documentation Updated** - Manifests updated
+9. **Complete** - All tests passing, committed
+
+## 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>
+## Status Management
+
+- Update status after each phase completion
+- Keep v2-api-implementation-status.md current
+- Use status to plan next work
+- Reference in standup/progress reports
+- Track blockers and dependencies
+
+## Integration Points
+
+- Used by /api-create to track progress
+- Used by /commit to verify readiness
+- Used by team to see what's done
+- Used for planning future work
+  </claude-commands-template>