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

package/.skills/hustle-build/SKILL.md

@@ -4,7 +4,7 @@ description: Build complete features from natural language. Orchestrates API, co
 license: MIT
 compatibility: Requires Claude Code with hooks and MCP servers configured
 metadata:
-  version: "4.0.0"
+  version: "4.6.0"
   category: "orchestration"
   tags: ["build", "workflow", "orchestrator", "autonomous"]
   author: "Hustle Together"
@@ -20,23 +20,257 @@ Build complete features from natural language descriptions. This skill orchestra
 ```
 /hustle-build [description]
 /hustle-build --auto [description]
+/hustle-build --parallel [description]
 /hustle-build --resume [build-id]
 /hustle-build --dry-run [description]
+/hustle-build --max-iterations [N] [description]
 ```
 
 ## Arguments
 
 - `$ARGUMENTS` - Natural language description of what to build
 - `--auto` - Fully autonomous mode, auto-answers questions
+- `--parallel` - Run up to 5 Opus agents in parallel (requires worktrees)
 - `--resume [id]` - Resume an interrupted build
 - `--dry-run` - Show what would be created without executing
+- `--max-iterations [N]` - Max retry iterations per phase (default: 5)
+- `--skip-document` - Skip the project document prompt
+- `--from-document [path]` - Use specified file as project document (PRD, spec)
+
+## Parallel Execution (Recommended for Large Builds)
+
+When `--parallel` is used, the orchestrator:
+
+1. **Creates git worktrees** for each independent workflow
+2. **Spawns up to 5 Opus agents** simultaneously
+3. **Injects shared decisions** into each agent
+4. **Merges results** when all complete
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    PARALLEL ORCHESTRATOR                        │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Shared Context (from Interview)                               │
+│  ┌───────────────────────────────────────────────────────┐     │
+│  │ Auth: JWT | Errors: partial-success | Brand: yes      │     │
+│  └───────────────────────────────────────────────────────┘     │
+│                          │                                      │
+│          ┌───────────────┼───────────────┐                     │
+│          ▼               ▼               ▼                     │
+│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐           │
+│  │ Agent #1     │ │ Agent #2     │ │ Agent #3     │           │
+│  │ /api-create  │ │ /api-create  │ │ /hustle-ui   │           │
+│  │ user-stats   │ │ chart-data   │ │ StatCard     │           │
+│  └──────────────┘ └──────────────┘ └──────────────┘           │
+│          │               │               │                     │
+│          └───────────────┼───────────────┘                     │
+│                          ▼                                      │
+│  ┌───────────────────────────────────────────────────────┐     │
+│  │              MERGE COORDINATOR                         │     │
+│  │  • Combines registry entries                          │     │
+│  │  • Resolves conflicts                                 │     │
+│  │  • Creates unified PR                                 │     │
+│  └───────────────────────────────────────────────────────┘     │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+See [PARALLEL_AUTONOMOUS_WORKFLOW.md](../../docs/PARALLEL_AUTONOMOUS_WORKFLOW.md) for details.
+
+## Max Iterations
+
+Each phase has a maximum iteration count to prevent infinite loops:
+
+```json
+{
+  "max_iterations": {
+    "default": 5,
+    "phases": {
+      "disambiguation": 2,
+      "research": 3,
+      "interview": 1,
+      "schema": 3,
+      "tdd_red": 5,
+      "tdd_green": 10,
+      "verify": 3,
+      "code_review": 3,
+      "refactor": 5
+    }
+  }
+}
+```
+
+Override with `--max-iterations`:
+```bash
+# Allow more retries for complex builds
+/hustle-build --max-iterations 10 --auto complex e-commerce system
+```
+
+When max iterations reached:
+1. Log issue to `session_archives.interrupted`
+2. Create partial PR with work completed
+3. Notify via NTFY
+4. Continue with other workflows
 
 ---
 
-## Phase 1: Parse Request
+## Phase 1: Document Intake & Parsing (Optional)
+
+At the start of `/hustle-build`, the `project-document-prompt.py` hook asks if you have a comprehensive project document.
+
+**Supported Document Types:**
+- PRD (Product Requirements Document)
+- Technical specifications
+- Deep research outputs (from `/plan` or `/spike`)
+- API definitions (OpenAPI, JSON specs)
+
+**How to provide:**
+```
+# When prompted, you can:
+1. Provide a file path: ./docs/my-prd.md
+2. Paste content directly
+3. Provide a URL to fetch
+4. Say "no document" to skip
+
+# Or skip the prompt entirely:
+/hustle-build --skip-document [description]
+
+# Or provide a document directly:
+/hustle-build --from-document ./docs/spec.md [description]
+```
+
+The document is stored in `state.project_spec.raw_content` for parsing.
+
+### Document Parsing (When project_spec exists)
+
+If a project document was provided, analyze it to extract structured elements.
+
+**Extraction Targets:**
+
+| Element Type | Keywords to Find | What to Extract |
+|-------------|------------------|-----------------|
+| Pages | "page", "screen", "route", "/path", "view" | name, route, description, features |
+| Components | "component", "widget", "card", "form", "button" | name, type (display/input/composite), props, variants |
+| APIs | "API", "endpoint", "/api/", "fetch", "GET", "POST" | name, method, path, request/response schemas |
+| Data Models | "model", "schema", "type", "interface", "entity" | name, fields, relationships |
+| Integrations | service names (Stripe, Supabase, Auth0) | service, features used, env vars |
+
+**Dependency Graph Construction:**
+- APIs = Tier 1 (no dependencies)
+- Components = Tier 2 (depend on APIs for types)
+- Pages = Tier 3 (depend on components)
+
+**Store extracted data in state:**
+
+```json
+{
+  "project_spec": {
+    "source": "file|paste|url",
+    "file_path": "./docs/my-prd.md",
+    "raw_content": "[original document]",
+    "format": "markdown|json|text",
+    "parsed_at": "[timestamp]",
+    "word_count": 2500,
+    "extracted": {
+      "summary": "E-commerce dashboard with user stats and order tracking",
+      "pages": [
+        {
+          "name": "Dashboard",
+          "route": "/dashboard",
+          "description": "Main user dashboard",
+          "features": ["stats display", "order list", "notifications"],
+          "uses_components": ["StatCard", "OrderTable"],
+          "uses_apis": ["user-stats", "orders"]
+        }
+      ],
+      "components": [
+        {
+          "name": "StatCard",
+          "type": "display",
+          "description": "Display individual statistic with trend",
+          "props": ["title", "value", "trend", "icon"],
+          "variants": ["primary", "secondary", "success", "warning"]
+        }
+      ],
+      "apis": [
+        {
+          "name": "user-stats",
+          "method": "GET",
+          "path": "/api/v2/user-stats",
+          "description": "User statistics endpoint",
+          "response_fields": ["totalOrders", "revenue", "growth"]
+        }
+      ],
+      "data_models": [
+        {
+          "name": "UserStats",
+          "fields": ["totalOrders: number", "revenue: number", "growth: number"]
+        }
+      ],
+      "integrations": [
+        {
+          "service": "supabase",
+          "features": ["auth", "database"],
+          "env_vars": ["SUPABASE_URL", "SUPABASE_ANON_KEY"]
+        }
+      ]
+    },
+    "user_modifications": {
+      "added": [],
+      "removed": [],
+      "modified": []
+    }
+  }
+}
+```
+
+**Present decomposition for approval:**
+
+Use AskUserQuestion:
+
+```
+Based on your project document, I've identified:
+
+**Pages (2):**
+  - Dashboard (/dashboard) - Main user dashboard
+  - Orders (/orders) - Order management
+
+**Components (4):**
+  - StatCard (display) - Display statistic with trend
+  - OrderTable (composite) - Order listing
+  - OrderRow (display) - Single order row
+  - StatusBadge (display) - Order status indicator
+
+**APIs (3):**
+  - user-stats (GET /api/v2/user-stats)
+  - orders (GET /api/v2/orders)
+  - order-detail (GET /api/v2/orders/[id])
+
+**Data Models (2):**
+  - UserStats, Order
+
+**Integrations (1):**
+  - Supabase (auth, database)
+
+Is this decomposition correct?
+```
+
+Options:
+- "Yes, proceed with this plan (Recommended)"
+- "Add missing elements"
+- "Remove elements"
+- "Re-parse document"
+- "Skip document, use description instead"
+
+---
+
+## Phase 2: Parse Request
 
 Parse the user's natural language request to identify required elements.
 
+**Note:** If `project_spec.extracted` exists from Phase 1, use it as the primary decomposition source and skip manual parsing.
+
 **Input:** $ARGUMENTS
 
 **Look for:**
@@ -49,7 +283,7 @@ Parse the user's natural language request to identify required elements.
 
 ---
 
-## Phase 2: Decompose Into Workflows
+## Phase 3: Decompose Into Workflows
 
 For each identified element, determine:
 
@@ -90,14 +324,14 @@ Does this look correct?
 ```
 
 Use AskUserQuestion with options:
-- "Yes, proceed with this plan"
+- "Yes, proceed with this plan (Recommended)"
 - "Add more elements"
 - "Remove elements"
 - "Let me describe differently"
 
 ---
 
-## Phase 3: Orchestrator Interview
+## Phase 4: Orchestrator Interview
 
 Ask HIGH-LEVEL questions that apply to ALL sub-workflows.
 
@@ -105,25 +339,25 @@ Ask HIGH-LEVEL questions that apply to ALL sub-workflows.
 
 ### Q1: Authentication
 "What's the authentication requirement for this feature?"
-- Protected (requires login) - DEFAULT
+- Protected (requires login) (Recommended)
 - Public (no auth)
 - Mixed (specify per element)
 
 ### Q2: Error Handling
 "How should errors be handled across APIs?"
-- Partial success (show what works) - DEFAULT
+- Partial success (show what works) (Recommended)
 - Fail-fast (one fails = all fail)
 - Retry with fallback
 
 ### Q3: Brand Guide
 "Use project brand guide for styling?"
-- Yes, use .claude/BRAND_GUIDE.md - DEFAULT
+- Yes, use .claude/BRAND_GUIDE.md (Recommended)
 - No, custom theme
 - Match existing page
 
 ### Q4: Testing Level
 "What level of testing?"
-- Full TDD (all 14 phases per element) - DEFAULT
+- Full TDD (all 14 phases per element) (Recommended)
 - Essential tests only
 - Smoke tests only
 
@@ -131,13 +365,13 @@ Store all answers in `shared_decisions` - these will be injected into sub-workfl
 
 ---
 
-## Phase 4: Create Orchestration State
+## Phase 5: Create Orchestration State
 
 Create `.claude/hustle-build-state.json`:
 
 ```json
 {
-  "version": "4.0.0",
+  "version": "4.6.0",
   "build_id": "build-[timestamp]-[name]",
   "status": "in_progress",
   "mode": "interactive|auto",
@@ -148,6 +382,22 @@ Create `.claude/hustle-build-state.json`:
     "parsed_at": "[timestamp]"
   },
 
+  "project_spec": {
+    "source": "file|paste|url|none",
+    "file_path": "[optional - path to document]",
+    "raw_content": "[document content if provided]",
+    "format": "markdown|json|text",
+    "parsed_at": "[timestamp]",
+    "extracted": {
+      "summary": "[AI-generated summary]",
+      "pages": [],
+      "components": [],
+      "apis": [],
+      "data_models": [],
+      "integrations": []
+    }
+  },
+
   "orchestrator_interview": {
     "status": "complete",
     "decisions": {
@@ -160,14 +410,14 @@ Create `.claude/hustle-build-state.json`:
 
   "decomposition": {
     "apis": [
-      {"name": "user-stats", "status": "pending", "depends_on": []}
+      {"name": "user-stats", "status": "pending", "depends_on": [], "from_project_spec": true}
     ],
     "components": [
-      {"name": "StatCard", "status": "pending", "depends_on": ["user-stats"]}
+      {"name": "StatCard", "status": "pending", "depends_on": ["user-stats"], "from_project_spec": true}
     ],
     "combined_apis": [],
     "pages": [
-      {"name": "Dashboard", "status": "pending", "depends_on": ["StatCard"]}
+      {"name": "Dashboard", "status": "pending", "depends_on": ["StatCard"], "from_project_spec": true}
     ]
   },
 
@@ -183,13 +433,15 @@ Create `.claude/hustle-build-state.json`:
 }
 ```
 
+**Note:** Elements with `from_project_spec: true` were extracted from the project document. This helps track provenance and allows referencing the original spec during implementation.
+
 ---
 
-## Phase 5: Execute Workflows
+## Phase 6: Execute Workflows
 
 For each workflow in execution order:
 
-### 5.1 Set Active Workflow
+### 6.1 Set Active Workflow
 
 Update state:
 ```json
@@ -201,7 +453,7 @@ Update state:
 }
 ```
 
-### 5.2 Invoke Sub-Workflow
+### 6.2 Invoke Sub-Workflow
 
 The orchestrator hooks will automatically:
 1. Inject `shared_decisions` into `api-dev-state.json`
@@ -217,27 +469,51 @@ Run the appropriate skill:
 | combined_api | `/hustle-combine api` |
 | page | `/hustle-ui-create-page [name]` |
 
-### 5.3 Sub-Workflow Behavior
+### 6.3 Sub-Workflow Behavior
 
 When `orchestrated: true`:
 - Skip questions answered in `shared_decisions`
 - Only ask element-specific questions
 - Report completion back to orchestrator
 
-### 5.4 On Completion
+### 6.4 On Completion
+
+When a sub-workflow completes:
+
+1. **Mark Complete:** Update state with `"status": "complete"`
+2. **Find Next:** Identify next pending workflow in decomposition
 
-The `orchestrator-completion.py` hook will:
-1. Mark workflow as complete in state
-2. Find next pending workflow
-3. Inject context for next workflow
+3. **⚠️ CRITICAL: Use AskUserQuestion for Transitions**
+
+   You MUST use `AskUserQuestion` tool (not plain text) to ask about continuing:
+
+   ```json
+   {
+     "questions": [{
+       "question": "✅ Completed [workflow-name]. Next: [next-name]. Continue?",
+       "header": "Continue",
+       "multiSelect": false,
+       "options": [
+         {"label": "Yes, proceed (Recommended)", "description": "Continue to next workflow"},
+         {"label": "Review first", "description": "Show me what was created"},
+         {"label": "Stop here", "description": "Pause build for review"}
+       ]
+     }]
+   }
+   ```
+
+   **Why:** The `auto-answer.py` hook only intercepts `AskUserQuestion` tool calls.
+   If you use plain text like "Should I continue?", auto-mode will halt.
+
+4. **Inject Context:** Pass shared_decisions and completed element info to next workflow
 
 ---
 
-## Phase 6: Cross-Workflow Wiring
+## Phase 7: Cross-Workflow Wiring
 
 After all workflows complete, wire them together:
 
-### 6.1 Import Generation
+### 7.1 Import Generation
 
 For pages that use components and APIs:
 
@@ -248,7 +524,7 @@ import { StatCard } from '@/components/StatCard';
 import { ChartWidget } from '@/components/ChartWidget';
 ```
 
-### 6.2 Prop Wiring
+### 7.2 Prop Wiring
 
 Wire component props to API response types:
 
@@ -259,13 +535,13 @@ interface DashboardProps {
 }
 ```
 
-### 6.3 Registry Updates
+### 7.3 Registry Updates
 
 Update `.claude/registry.json` with all created elements and their relationships.
 
 ---
 
-## Phase 7: Final Verification
+## Phase 8: Final Verification
 
 Run comprehensive test suite:
 
@@ -290,7 +566,7 @@ Report results:
 
 ---
 
-## Phase 8: Documentation Rollup
+## Phase 9: Documentation Rollup
 
 Generate unified documentation:
 
@@ -311,7 +587,7 @@ Generate unified documentation:
 
 ---
 
-## Phase 9: Completion
+## Phase 10: Completion
 
 Mark build as complete:
 
@@ -352,27 +628,78 @@ Next Steps:
 
 ---
 
-## Auto Mode Behavior
+## Auto Mode Behavior (Test Mode)
 
-When `--auto` flag is used:
+When `--auto` flag is used, the workflow runs end-to-end without prompts:
+
+```bash
+# Full autonomous build - perfect for testing
+/hustle-build --auto "photo gallery with search and favorites"
+
+# Autonomous with parallel execution
+/hustle-build --auto --parallel "e-commerce checkout flow"
+```
+
+### How It Works
 
 1. **No Interactive Questions:**
    - All questions auto-answered with comprehensive defaults
    - Uses `.claude/hustle-build-defaults.json` for overrides
+   - Selects "recommended" option for every choice
+   - Uses `AskUserQuestion` tool for all prompts (auto-answer.py intercepts)
+
+2. **ALL Phases Execute:**
+   - Auto mode ONLY auto-answers questions, it does NOT skip phases
+   - Every sub-workflow runs all 14 phases
+   - If a phase can't fully complete (missing API key), mark as "partial" not "skipped"
 
-2. **Error Handling:**
-   - Test failures: Retry 3x, then log and continue
-   - Verification gaps: Log, continue
-   - Missing API keys: Skip element, log warning
+3. **Error Handling:**
+   - Test failures: Retry 3x, then fix issues
+   - Verification gaps: Add tests for gaps, then fix
+   - Missing API keys: Mark phase "partial", continue
 
-3. **Notifications:**
+4. **Notifications:**
    - Single NTFY notification at completion
    - Includes summary and review link
 
-4. **Logging:**
+5. **Logging:**
    - All decisions logged to `.claude/workflow-logs/[build-id].json`
    - Review with `/hustle-build-review [build-id]`
 
+### Customizing Defaults
+
+Copy the template and customize for your project:
+
+```bash
+cp templates/hustle-build-defaults.json .claude/hustle-build-defaults.json
+```
+
+Then edit `.claude/hustle-build-defaults.json`:
+
+```json
+{
+  "orchestrator": {
+    "auth_required": true,        // Change to false for public APIs
+    "error_handling": "partial-success",
+    "brand_guide": true,
+    "testing_level": "essential"  // Change from "full" for faster runs
+  },
+  "testing": {
+    "coverage_threshold": 80,
+    "e2e_tests": false           // Skip E2E for faster testing
+  }
+}
+```
+
+### Use Cases
+
+| Scenario | Command |
+|----------|---------|
+| Full end-to-end test | `/hustle-build --auto "feature"` |
+| Quick test (skip E2E) | Edit defaults, then `--auto` |
+| CI/CD integration | `/hustle-build --auto --dry-run` first |
+| Demo mode | `/hustle-build --auto --parallel` |
+
 ---
 
 ## Resume Behavior