@hustle-together/api-dev-tools 3.12.3 → 4.5.1

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

@@ -4,19 +4,98 @@ description: Complete API development workflow using interview-driven, research-
 license: MIT
 compatibility: Requires Claude Code with MCP servers (Context7 for docs, GitHub for PRs), Python 3.9+ for enforcement hooks, pnpm 10.11.0+ for package management, Vitest for testing
 metadata:
-  version: "3.0.0"
+  version: "4.0.0"
   category: "development"
   tags: ["api", "tdd", "workflow", "research", "interview", "verification", "testing"]
   author: "Hustle Together"
 allowed-tools: WebSearch WebFetch mcp__context7 mcp__github AskUserQuestion Read Write Edit Bash TodoWrite
 ---
 
-# API Create - Comprehensive API Development Workflow v3.0
+# API Create - Comprehensive API Development Workflow v4.0
 
-**Usage:** `/api-create [endpoint-name]`
+**Usage:** `/api-create [endpoint-name] [--auto] [--resume [workflow-id]]`
 
 **Purpose:** Orchestrates the complete API development workflow using interview-driven, research-first, test-first methodology with continuous verification loops.
 
+## Arguments
+
+- `[endpoint-name]` - Name of the API endpoint to create
+- `--auto` - Fully autonomous mode, auto-answers all questions with comprehensive defaults
+- `--resume [workflow-id]` - Resume an interrupted workflow from its last phase
+
+---
+
+## Auto Mode (`--auto`)
+
+When `--auto` flag is used:
+
+1. **No Interactive Questions:**
+   - All questions auto-answered with comprehensive defaults
+   - Uses `.claude/hustle-build-defaults.json` for configured answers
+   - Falls back to "most comprehensive" option when no default exists
+
+2. **Comprehensive Selection Logic:**
+   - Always selects options that include ALL available features
+   - Always enables ALL testing levels
+   - Always generates ALL documentation
+   - Prefers "Yes" over "No" for optional features
+
+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]`
+
+**Example:**
+```bash
+/api-create brandfetch --auto
+```
+
+---
+
+## Resume Mode (`--resume`)
+
+When `--resume [workflow-id]` is used:
+
+1. Load state from `.claude/api-dev-state.json`
+2. Find the last incomplete phase
+3. Continue from that point
+4. Preserve all previous decisions
+
+**Example:**
+```bash
+/api-create --resume wf-brandfetch-2025-12-28
+```
+
+---
+
+## Orchestrated Mode
+
+When running as part of `/hustle-build`:
+
+1. `orchestrated: true` flag is set in state
+2. `shared_decisions` are pre-filled from orchestrator interview
+3. Questions covered by shared_decisions are SKIPPED
+4. Only workflow-specific questions are asked
+
+Check for orchestration at startup:
+```python
+if state.get("orchestrated"):
+    # Skip questions in shared_decisions_applied
+    skip_questions = state.get("shared_decisions_applied", [])
+```
+
+---
+
 ## ⚠️ CRITICAL: MANDATORY USER INTERACTION
 
 **YOU MUST USE THE `AskUserQuestion` TOOL AT EVERY CHECKPOINT.**
@@ -172,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"}     │
 │       ]                                                   │
@@ -197,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"                  │
 │       ]                                                   │
@@ -252,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)"   │
 │       ]                                                   │
@@ -304,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"                            │
 │       ]                                                   │
@@ -328,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"           │
 │       ]                                                   │
@@ -354,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"                        │
 │       ]                                                   │
@@ -378,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"                  │
 │       ]                                                   │
@@ -403,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)"               │
 │       ]                                                   │
@@ -442,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)"            │
 │       ]                                                   │
@@ -478,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)"}│
 │       ]                                                   │
@@ -517,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"}│
 │       ]                                                   │
@@ -542,6 +621,18 @@ TodoWrite([
 │                                                           │
 │ Run /commit to create semantic commit.                    │
 │ Run /pr to create pull request.                           │
+│                                                           │
+│ ═══════════════════════════════════════════════════════  │
+│ ✅ API CREATED: [endpoint-name]                           │
+│                                                           │
+│ 📍 Quick Links:                                           │
+│   • Test it:     /api-showcase                            │
+│   • API Docs:    /docs/api/[endpoint-name]                │
+│   • Run tests:   pnpm test:api [endpoint-name]            │
+│   • TypeDoc:     pnpm typedoc                             │
+│                                                           │
+│ 📊 Dashboard:    /hustle-dev-dashboard                    │
+│ ═══════════════════════════════════════════════════════  │
 └───────────────────────────────────────────────────────────┘
 ```
 
@@ -611,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>