@hustle-together/api-dev-tools 3.12.16 → 4.5.3

package/.skills/adr-deep-research/SKILL.md

@@ -0,0 +1,351 @@
+---
+name: adr-deep-research
+description: Research technology options for Architecture Decision Records. Spawns parallel agents to fetch official docs, extract pros/cons, pricing, and best-use cases. Creates substantive ADRs before interview phase.
+license: MIT
+compatibility: Requires Claude Code with MCP servers (Context7, GitHub), Python 3.9+ for hooks
+metadata:
+  version: "1.0.0"
+  category: "research"
+  tags: ['adr', 'research', 'architecture', 'decisions']
+  author: "Hustle Together"
+allowed-tools: WebSearch WebFetch mcp__context7 Task Read Write Edit TodoWrite
+---
+
+# ADR Deep Research - Technology Option Investigation
+
+**Usage:** `/adr-deep-research [category]`
+
+**Purpose:** Research each option for an Architecture Decision Record with real documentation, creating substantive pros/cons before the interview phase.
+
+## When This Skill Runs
+
+This skill is triggered when:
+
+1. `generate-adr-options.py` hook detects a significant decision during research
+2. A pending request exists in `.claude/adr-requests/pending-{category}.json`
+3. User needs informed choices before the interview phase
+
+## What It Does
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    ADR DEEP RESEARCH FLOW                       │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Read pending request:                                       │
+│     .claude/adr-requests/pending-database.json                  │
+│     {                                                           │
+│       "category": "database",                                   │
+│       "options": ["supabase", "firebase", "postgres"],          │
+│       "context": "User building todo app with React"            │
+│     }                                                           │
+│                                                                 │
+│  2. Spawn parallel adr-researcher agents (one per option):      │
+│     ┌──────────────┐ ┌──────────────┐ ┌──────────────┐         │
+│     │ Agent #1     │ │ Agent #2     │ │ Agent #3     │         │
+│     │ supabase     │ │ firebase     │ │ postgres     │         │
+│     │ → docs       │ │ → docs       │ │ → docs       │         │
+│     │ → pros/cons  │ │ → pros/cons  │ │ → pros/cons  │         │
+│     └──────────────┘ └──────────────┘ └──────────────┘         │
+│                                                                 │
+│  3. Merge results into ADR document:                            │
+│     .claude/adrs/ADR-NNNN-database-choice.md                    │
+│     - Real pros/cons from official docs                         │
+│     - Pricing information                                       │
+│     - Best-for recommendations                                  │
+│     - Source URLs for verification                              │
+│                                                                 │
+│  4. Update state and registry:                                  │
+│     - Mark request as processed                                 │
+│     - Add ADR to registry                                       │
+│     - Inject context for interview                              │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Process Steps
+
+### Step 1: Read Pending Request
+
+```bash
+# Check for pending request
+cat .claude/adr-requests/pending-{category}.json
+```
+
+Expected format:
+
+```json
+{
+  "category": "database",
+  "options": ["supabase", "firebase", "postgres"],
+  "context": "User building todo app with React frontend",
+  "endpoint": "todo-api",
+  "status": "pending",
+  "created_at": "2025-12-30T10:00:00Z"
+}
+```
+
+### Step 2: Spawn Parallel Research Agents
+
+For each option in the request, spawn an `adr-researcher` agent in parallel:
+
+```
+Use Task tool with subagent_type="adr-researcher" for each option.
+
+Spawn ALL agents in a SINGLE message (parallel execution).
+```
+
+**Agent prompt template:**
+
+```
+Research the following technology option for an ADR decision:
+
+Option: {option}
+Category: {category}
+Context: {context}
+Comparison Options: {other_options}
+
+Return structured JSON with:
+- pros (3-5 specific, factual)
+- cons (3-5 specific, factual)
+- best_for (1-2 ideal use cases)
+- pricing (free tier, paid tiers)
+- limitations (technical constraints)
+- sources (documentation URLs)
+```
+
+### Step 3: Collect and Merge Results
+
+Wait for all agents to complete, then merge results into a unified ADR:
+
+```markdown
+# ADR-{NNNN}: {Category} Choice
+
+**Status:** PROPOSED
+**Date:** {date}
+**Category:** {category}
+**Context:** {context}
+**Endpoint:** {endpoint}
+
+## Options Considered
+
+### Option 1: {Option A} (Recommended)
+
+**Pros:**
+- {Real pro from research}
+- {Real pro from research}
+- {Real pro from research}
+
+**Cons:**
+- {Real con from research}
+- {Real con from research}
+
+**Best For:** {Use cases from research}
+
+**Pricing:** {Pricing from research}
+
+**Source:** {URL from research}
+
+### Option 2: {Option B}
+
+... (same structure)
+
+## Decision
+
+_Awaiting user selection in interview phase_
+
+## Consequences
+
+_Will be filled after decision is made_
+```
+
+### Step 4: Determine Recommendation
+
+Based on research, mark ONE option as `(Recommended)` using these criteria:
+
+1. **Match to context** - Which fits user's stated project best?
+2. **Developer experience** - Which has better docs, easier setup?
+3. **Cost effectiveness** - Which has best free tier for MVPs?
+4. **Community/support** - Which has more active community?
+
+### Step 5: Update State and Registry
+
+Mark request as processed:
+
+```json
+{
+  "status": "completed",
+  "completed_at": "2025-12-30T10:15:00Z",
+  "adr_file": ".claude/adrs/ADR-0001-database-choice.md"
+}
+```
+
+Add to registry:
+
+```json
+{
+  "adrs": {
+    "0001-database-choice": {
+      "number": 1,
+      "title": "Database Choice",
+      "status": "proposed",
+      "date": "2025-12-30",
+      "category": "database",
+      "options_considered": ["supabase", "firebase", "postgres"],
+      "recommended": "supabase",
+      "file": ".claude/adrs/ADR-0001-database-choice.md",
+      "endpoint": "todo-api"
+    }
+  }
+}
+```
+
+### Step 6: Output Summary
+
+```
+═══════════════════════════════════════════════════════════════════
+                    ADR RESEARCH COMPLETE
+═══════════════════════════════════════════════════════════════════
+
+Category: database
+Options Researched: 3
+  • Supabase (Recommended)
+  • Firebase
+  • PostgreSQL + Prisma
+
+ADR Created: .claude/adrs/ADR-0001-database-choice.md
+
+Key Findings:
+───────────────────────────────────────
+  Supabase:   Real-time + Auth built-in, free tier generous
+  Firebase:   Google ecosystem, NoSQL only
+  PostgreSQL: Full control, more setup required
+───────────────────────────────────────
+
+This ADR will be referenced during the interview phase.
+The user can review options and select their preference.
+
+═══════════════════════════════════════════════════════════════════
+```
+
+## ADR Output Template
+
+Use this template for the generated ADR:
+
+```markdown
+# ADR-{NUMBER}: {Title}
+
+**Status:** PROPOSED | ACCEPTED | DEPRECATED | SUPERSEDED
+**Date:** YYYY-MM-DD
+**Category:** {category}
+**Context:** {user's project context}
+**Endpoint:** {related endpoint if any}
+
+## Context
+
+{Why this decision needs to be made}
+
+## Options Considered
+
+### Option 1: {Name} (Recommended)
+
+**Pros:**
+- {Specific, factual pro with detail}
+- {Specific, factual pro with detail}
+- {Specific, factual pro with detail}
+
+**Cons:**
+- {Specific, factual con with detail}
+- {Specific, factual con with detail}
+
+**Best For:** {Ideal use cases}
+
+**Pricing:**
+- Free: {limits}
+- Paid: {tiers}
+
+**Source:** {URL}
+
+### Option 2: {Name}
+
+{Same structure}
+
+### Option 3: {Name}
+
+{Same structure}
+
+## Decision
+
+_Awaiting user selection in interview phase_
+
+## Consequences
+
+_Will be filled after decision is made_
+
+## Research Metadata
+
+| Aspect | Details |
+|--------|---------|
+| Researched | {timestamp} |
+| Sources | {count} official docs |
+| Agents | {count} parallel researchers |
+| Duration | {time} |
+```
+
+## Configuration
+
+ADR categories and keywords are configured in `.claude/hustle-build-defaults.json`:
+
+```json
+{
+  "adr": {
+    "enabled": true,
+    "significant_decisions": {
+      "database": ["supabase", "firebase", "postgres", "mysql", "mongodb"],
+      "auth": ["api key", "oauth", "jwt", "session", "cookie"],
+      "cache": ["redis", "memcached", "in-memory", "cdn"],
+      "hosting": ["vercel", "netlify", "aws", "cloudflare"],
+      "state": ["redux", "zustand", "jotai", "context"],
+      "styling": ["tailwind", "css modules", "styled-components"]
+    },
+    "min_options_for_adr": 2
+  }
+}
+```
+
+## Directory Structure
+
+```
+.claude/
+├── adr-requests/
+│   ├── pending-database.json      # Awaiting research
+│   ├── pending-auth.json          # Awaiting research
+│   └── completed-database.json    # Research done
+├── adrs/
+│   ├── ADR-0001-database-choice.md
+│   ├── ADR-0002-auth-method.md
+│   └── index.json                 # ADR catalog
+└── registry.json                  # Includes adrs section
+```
+
+## Integration Points
+
+- **Triggered by:** `hooks/generate-adr-options.py` (PostToolUse)
+- **Uses agent:** `.claude/agents/adr-researcher.md`
+- **Updates:** `.claude/registry.json` with ADR entries
+- **Referenced by:** `/api-interview` for informed user choices
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| No pending request | Log warning, exit gracefully |
+| Agent fails | Use fallback research (WebSearch directly) |
+| Partial results | Create ADR with available data, mark incomplete |
+| Rate limited | Retry with backoff, continue with other options |
+
+## See Also
+
+- `/api-research` - General API documentation research
+- `/api-interview` - Interview phase that uses ADR context
+- `docs/ARCHITECTURE_DECISION_RECORDS.md` - Full ADR documentation

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

@@ -40,12 +40,18 @@ When `--auto` flag is used:
    - Always generates ALL documentation
    - Prefers "Yes" over "No" for optional features
 
-3. **Error Handling:**
-   - Test failures: Retry 3x, then log and continue
-   - Verification gaps: Log gap, continue (will review later)
-   - Missing API keys: Log warning, continue if possible
-
-4. **Logging:**
+3. **Phase Execution:**
+   - ALL phases MUST execute - no skipping in auto mode
+   - Phase 10 (Verify): MUST re-research and compare to implementation
+   - Phase 11 (Code Review): Run if GREPTILE_API_KEY exists, else mark "no API key" but still complete
+   - Phase 12 (Refactor): MUST run basic refactoring even if no review issues
+
+4. **Error Handling:**
+   - Test failures: Retry 3x, then fix issues
+   - Verification gaps: Add tests to cover gaps, then fix
+   - Missing API keys: Log warning but complete the phase
+
+5. **Logging:**
    - All decisions logged to `.claude/workflow-logs/api-create/[workflow-id].json`
    - Review with `/api-create-review [workflow-id]`
 
@@ -245,7 +251,7 @@ TodoWrite([
 │       "header": "Disambig",                               │
 │       "multiSelect": false,                               │
 │       "options": [                                        │
-│         {"label": "REST API", "description": "Official API"},│
+│         {"label": "REST API (Recommended)", "description": "Official API"},│
 │         {"label": "SDK/Package", "description": "NPM wrapper"},│
 │         {"label": "Both", "description": "API + SDK"}     │
 │       ]                                                   │
@@ -270,7 +276,7 @@ TodoWrite([
 │                  Is this correct?",                       │
 │       header: "Scope",                                    │
 │       options: [                                          │
-│         "Yes, proceed",                                   │
+│         "Yes, proceed (Recommended)",                     │
 │         "I have modifications to add",                    │
 │         "No, let me clarify the purpose"                  │
 │       ]                                                   │
@@ -325,7 +331,7 @@ TodoWrite([
 │                  for more?",                              │
 │       header: "Research",                                 │
 │       options: [                                          │
-│         "Proceed to interview",                           │
+│         "Proceed to interview (Recommended)",             │
 │         "Search more - I need [specific topic]",          │
 │         "Search for something specific (I'll describe)"   │
 │       ]                                                   │
@@ -377,7 +383,7 @@ TodoWrite([
 │                  [summary]. All correct?",                │
 │       header: "Confirm",                                  │
 │       options: [                                          │
-│         "Yes, proceed to schema",                         │
+│         "Yes, proceed to schema (Recommended)",           │
 │         "Change an answer",                               │
 │         "Add another question"                            │
 │       ]                                                   │
@@ -401,7 +407,7 @@ TodoWrite([
 │                  want to research: [list]. Approve?",     │
 │       header: "Deep Research",                            │
 │       options: [                                          │
-│         "Yes, run these searches",                        │
+│         "Yes, run these searches (Recommended)",          │
 │         "Add more - I also need [topic]",                 │
 │         "Skip deep research, proceed to schema"           │
 │       ]                                                   │
@@ -427,7 +433,7 @@ TodoWrite([
 │                  requirements?",                          │
 │       header: "Schema",                                   │
 │       options: [                                          │
-│         "Yes, schema looks correct",                      │
+│         "Yes, schema looks correct (Recommended)",        │
 │         "No, I need changes (I'll describe)",             │
 │         "Let's redo the interview"                        │
 │       ]                                                   │
@@ -451,7 +457,7 @@ TodoWrite([
 │                  [M] missing. Ready to start TDD?",       │
 │       header: "Environment",                              │
 │       options: [                                          │
-│         "Yes, ready to write tests",                      │
+│         "Yes, ready to write tests (Recommended)",        │
 │         "No, need to set up API keys first",              │
 │         "No, need to fix something else"                  │
 │       ]                                                   │
@@ -476,7 +482,7 @@ TodoWrite([
 │                  Approve this test plan?",                │
 │       header: "Tests",                                    │
 │       options: [                                          │
-│         "Yes, write these tests",                         │
+│         "Yes, write these tests (Recommended)",           │
 │         "Add more scenarios (I'll describe)",             │
 │         "Change a scenario (I'll describe)"               │
 │       ]                                                   │
@@ -515,7 +521,7 @@ TodoWrite([
 │                  How should I proceed?",                  │
 │       header: "Verify",                                   │
 │       options: [                                          │
-│         "Fix gaps - loop back to Red phase",              │
+│         "Fix gaps - loop back to Red phase (Recommended)",│
 │         "Skip - these are intentional omissions",         │
 │         "Fix some, skip others (I'll specify)"            │
 │       ]                                                   │
@@ -551,7 +557,7 @@ TodoWrite([
 │       header: "Review",                                   │
 │       multiSelect: false,                                 │
 │       options: [                                          │
-│         {"label": "Fix all issues", "description": "Address each issue in Phase 12"},│
+│         {"label": "Fix all issues (Recommended)", "description": "Address each issue in Phase 12"},│
 │         {"label": "Fix critical only", "description": "Skip medium/low priority"},│
 │         {"label": "Skip review", "description": "Proceed without fixes (not recommended)"}│
 │       ]                                                   │
@@ -590,7 +596,7 @@ TodoWrite([
 │       header: "Docs",                                     │
 │       multiSelect: false,                                 │
 │       options: [                                          │
-│         {"label": "Yes, complete", "description": "All docs updated"},│
+│         {"label": "Yes, complete (Recommended)", "description": "All docs updated"},│
 │         {"label": "Need to add more", "description": "I'll describe what's missing"},│
 │         {"label": "Skip for now", "description": "Not recommended"}│
 │       ]                                                   │
@@ -696,13 +702,21 @@ This command creates:
 7. **API Keys**: Support three methods (env, NEXT*PUBLIC*, custom headers)
 8. **Test Command**: `pnpm test:run` before commits
 
-## Never Skip
+## Never Skip (Even in --auto mode)
+
+**CRITICAL: ALL phases must execute - auto mode only auto-answers questions, it does NOT skip phases.**
 
 - Phase 1 (Disambiguation) - Clarify before research
 - Phase 3 (Initial Research) - Find ALL parameters
 - Phase 4 (Interview) - Questions FROM research, not templates
+- Phase 5 (Deep Research) - Only skip if truly comprehensive initial research
 - Phase 8 (TDD Red) - Failing tests FIRST
-- Phase 10 (Verify) - Re-research after Green
-- Phase 12 (Documentation) - Keep docs in sync
+- Phase 10 (Verify) - MUST re-research after Green - this catches memory errors
+- Phase 11 (Code Review) - Run if API key exists, else document "no key" but complete phase
+- Phase 12 (Refactor) - MUST run even if no review issues - always optimize
+- Phase 13 (Documentation) - Keep docs in sync
+- Phase 14 (Completion) - Always run final verification
 - Coverage verification - 100% required
+
+**If a phase can't fully complete (e.g., missing API key), mark it as "partial" not "skipped".**
   </claude-commands-template>

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

@@ -42,6 +42,103 @@ Run 2-3 targeted searches:
 - WebSearch: "site:[domain] api reference" (if known domain)
 ```
 
+### Table of Contents Scraping (CRITICAL)
+
+**Always fetch and parse the documentation Table of Contents first!**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    TOC DISCOVERY FLOW                           │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Step 1: Find Docs Root                                        │
+│  ├─ WebSearch: "[name] documentation"                          │
+│  └─ Extract: docs.example.com or example.com/docs              │
+│                                                                 │
+│  Step 2: Fetch TOC Page                                        │
+│  ├─ WebFetch: docs.example.com + look for sidebar/nav          │
+│  ├─ WebFetch: docs.example.com/api-reference                   │
+│  └─ WebFetch: docs.example.com/sitemap.xml (if available)      │
+│                                                                 │
+│  Step 3: Extract All Sections                                  │
+│  ├─ Getting Started                                            │
+│  ├─ Authentication                                             │
+│  ├─ API Reference                                              │
+│  │   ├─ Endpoints                                              │
+│  │   ├─ Parameters                                             │
+│  │   ├─ Response Codes                                         │
+│  │   └─ Webhooks                                               │
+│  ├─ SDKs & Libraries                                           │
+│  ├─ Rate Limits                                                │
+│  ├─ Errors                                                     │
+│  └─ Changelog                                                  │
+│                                                                 │
+│  Step 4: Prioritize for Interview                              │
+│  ├─ Which sections have parameters we need to ask about?       │
+│  ├─ Which sections have optional features?                     │
+│  └─ Which sections have configuration options?                 │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Comprehensive Discovery Checklist
+
+Before proceeding to interview, ensure we've discovered:
+
+```markdown
+## Pre-Interview Discovery Checklist
+
+### Authentication & Authorization
+- [ ] Auth method (API key, OAuth, Bearer token, Basic)
+- [ ] Where to get credentials (dashboard URL)
+- [ ] Token refresh mechanism
+- [ ] Scopes/permissions available
+
+### Endpoints
+- [ ] All available endpoints listed
+- [ ] HTTP methods for each
+- [ ] Path parameters identified
+- [ ] Query parameters with types
+- [ ] Request body schemas
+
+### Parameters (CRITICAL for Interview)
+- [ ] Required vs optional distinction
+- [ ] Parameter types (string, number, enum, array)
+- [ ] Enum values listed
+- [ ] Default values documented
+- [ ] Validation rules/constraints
+- [ ] Continuous parameters (ranges for testing)
+
+### Response Schemas
+- [ ] Success response structure
+- [ ] Error response format
+- [ ] HTTP status codes used
+- [ ] Pagination format
+
+### Rate Limits & Quotas
+- [ ] Requests per minute/hour/day
+- [ ] Rate limit headers
+- [ ] Retry behavior
+- [ ] Quota types (per key, per user)
+
+### Webhooks (if applicable)
+- [ ] Available webhook events
+- [ ] Payload structure
+- [ ] Signature verification
+- [ ] Retry behavior
+
+### SDKs & Libraries
+- [ ] Official SDK availability
+- [ ] npm/pip/cargo package names
+- [ ] TypeScript types available?
+- [ ] Version compatibility
+
+### Errors
+- [ ] Error code catalog
+- [ ] Error message format
+- [ ] Troubleshooting steps
+```
+
 Present initial summary:
 
 ```
@@ -367,4 +464,37 @@ 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
+
+## ADR Integration (Automatic)
+
+When research discovers **multiple options for a significant decision**, the
+`generate-adr-options.py` hook automatically:
+
+1. Detects significant decisions (database, auth, cache, hosting, etc.)
+2. Creates a research request in `.claude/adr-requests/pending-{category}.json`
+3. Injects context telling you to run `/adr-deep-research {category}`
+
+**You should then run the deep research skill to:**
+
+- Spawn parallel agents to research each option
+- Fetch official documentation for each technology
+- Extract real pros, cons, pricing, and best-use cases
+- Create a substantive ADR before the interview phase
+
+```
+Example Flow:
+1. /api-research supabase
+   → Hook detects: database options (supabase, firebase, postgres)
+   → Creates: .claude/adr-requests/pending-database.json
+   → Injects: "Run /adr-deep-research database"
+
+2. /adr-deep-research database
+   → Spawns 3 parallel agents (one per option)
+   → Each agent fetches docs, extracts pros/cons
+   → Creates: .claude/adrs/ADR-0001-database-choice.md (with real content)
+
+3. Interview phase references ADR for informed decision
+```
+
+See `/adr-deep-research` skill and `docs/ARCHITECTURE_DECISION_RECORDS.md`.
   </claude-commands-template>