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

package/.skills/parallel-spawn/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: parallel-spawn
+description: Spawn multiple Task agents in parallel for concurrent workflow execution across git worktrees
+license: MIT
+compatibility: Requires Claude Code with Task tool, git worktrees support
+metadata:
+  version: "4.5.0"
+  category: "workflow"
+  tags: ['parallel', 'concurrent', 'worktree', 'agents', 'orchestration']
+  author: "Hustle Together"
+allowed-tools: Task Read Write Bash TodoWrite
+model: sonnet
+---
+
+# Parallel Spawn
+
+Coordinate parallel agent execution across git worktrees for concurrent workflow processing.
+
+## Usage
+
+```
+/parallel-spawn api:users api:products api:analytics
+/parallel-spawn component:chart component:table page:dashboard
+```
+
+Format: `type:name` where type is `api`, `component`, or `page`
+
+## How It Works
+
+1. **Interview Once** - Shared decisions are collected upfront
+2. **Create Worktrees** - Each workflow gets its own git worktree
+3. **Spawn Agents** - Background Task agents run in parallel
+4. **Monitor Progress** - Track completion with /parallel-status
+5. **Merge Results** - Combine all changes back to main branch
+
+## Example Session
+
+```
+User: /parallel-spawn api:users api:products api:orders
+
+AI: Setting up 3 parallel workflows...
+
+┌─────────────────────────────────────────────────────────────────┐
+│               PARALLEL EXECUTION SETUP                          │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Workflows to spawn:                                            │
+│  └─ api:users                                                   │
+│  └─ api:products                                                │
+│  └─ api:orders                                                  │
+│                                                                 │
+│  Shared interview required first!                               │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+
+Before spawning, I need to collect shared decisions that will apply
+to ALL workflows:
+
+1. Authentication method?
+   [1] API Key
+   [2] Bearer Token
+   [3] OAuth 2.0
+
+2. Error handling strategy?
+   [1] Fail-fast
+   [2] Partial success
+   [3] Retry with backoff
+
+... (shared interview)
+
+AI: Creating worktrees and spawning agents...
+
+[Spawns 3 Task agents in parallel with run_in_background: true]
+
+Parallel execution started! Monitor with /parallel-status
+```
+
+## Implementation
+
+<claude-commands-template>
+When /parallel-spawn is invoked:
+
+### 1. Parse Workflows
+
+Extract workflow definitions from the command:
+```python
+workflows = []
+for match in re.findall(r'(api|component|page):(\w+)', args):
+    workflows.append({"type": match[0], "name": match[1]})
+```
+
+### 2. Collect Shared Decisions
+
+Before spawning, conduct ONE shared interview:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                  SHARED INTERVIEW                               │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  These decisions apply to ALL {len(workflows)} workflows:       │
+│                                                                 │
+│  [Questions based on workflow types]                            │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+Use AskUserQuestion with options based on hustle-build-defaults.json.
+
+### 3. Create Worktrees
+
+For each workflow, create an isolated git worktree:
+
+```bash
+# Create worktree with new branch
+git worktree add ../parallel-users-0 -b parallel-users-0
+
+# Copy shared decisions
+cp .claude/shared-decisions.json ../parallel-users-0/.claude/
+```
+
+### 4. Update State
+
+Save parallel execution state:
+```json
+{
+  "parallel_execution": {
+    "enabled": true,
+    "worktrees": [
+      {"name": "parallel-users-0", "path": "../parallel-users-0", "status": "pending"},
+      {"name": "parallel-products-1", "path": "../parallel-products-1", "status": "pending"},
+      {"name": "parallel-orders-2", "path": "../parallel-orders-2", "status": "pending"}
+    ],
+    "shared_decisions": {
+      "auth_required": true,
+      "error_handling": "partial-success"
+    }
+  }
+}
+```
+
+### 5. Spawn Task Agents
+
+**CRITICAL: Spawn all agents in a SINGLE message with multiple Task tool calls!**
+
+```
+Call Task tool 3 times in ONE message:
+
+Task 1:
+  subagent_type: "general-purpose"
+  prompt: "Execute api-create users in worktree parallel-users-0..."
+  run_in_background: true
+
+Task 2:
+  subagent_type: "general-purpose"
+  prompt: "Execute api-create products in worktree parallel-products-1..."
+  run_in_background: true
+
+Task 3:
+  subagent_type: "general-purpose"
+  prompt: "Execute api-create orders in worktree parallel-orders-2..."
+  run_in_background: true
+```
+
+### 6. Monitor Completion
+
+Use TaskOutput with block=false to check status:
+
+```
+For each background agent ID:
+  TaskOutput(task_id=agent_id, block=false)
+
+Update worktree status based on results.
+```
+
+### 7. Merge When Complete
+
+When all agents complete:
+
+```bash
+# Merge each worktree branch
+git merge parallel-users-0 --no-ff -m "Merge parallel: users API"
+git merge parallel-products-1 --no-ff -m "Merge parallel: products API"
+git merge parallel-orders-2 --no-ff -m "Merge parallel: orders API"
+
+# Clean up worktrees
+git worktree remove ../parallel-users-0
+git worktree remove ../parallel-products-1
+git worktree remove ../parallel-orders-2
+```
+</claude-commands-template>
+
+## Related Commands
+
+- `/parallel-status` - Check parallel execution progress
+- `/parallel-merge` - Merge all completed worktrees
+- `/parallel-abort` - Cancel parallel execution and clean up
+- `/ralph-status` - Check individual agent loop status
+
+## Configuration
+
+In `hustle-build-defaults.json`:
+
+```json
+{
+  "parallel": {
+    "max_worktrees": 5,
+    "auto_merge": false,
+    "cleanup_on_error": true
+  }
+}
+```

package/.skills/ralph-continue/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: ralph-continue
+description: Continue or resume a paused Ralph Wiggum autonomous loop from its last state
+license: MIT
+compatibility: Requires Claude Code with hook_utils.py
+metadata:
+  version: "4.5.0"
+  category: "workflow"
+  tags: ['ralph', 'autonomous', 'loop', 'resume', 'continue']
+  author: "Hustle Together"
+allowed-tools: Read Write Task
+model: sonnet
+---
+
+# Ralph Continue
+
+Resume a paused or interrupted Ralph Wiggum autonomous loop.
+
+## Usage
+
+```
+/ralph-continue                    # Continue current workflow
+/ralph-continue [workflow-id]      # Resume specific workflow by ID
+/ralph-continue --list             # List resumable workflows
+```
+
+## What It Does
+
+1. **Clear Active Promise** - Removes any pending completion promise so the loop continues
+2. **Reset Iteration Counter** - Optionally reset phase iterations if stuck
+3. **Resume From Last State** - Pick up where the workflow left off
+4. **Restore Archived Workflows** - Can restore from workflow-logs if session ended
+
+## Examples
+
+### Continue After Promise Detection
+
+When a `<promise>DONE</promise>` was detected but you want to keep going:
+
+```
+/ralph-continue
+```
+
+This clears the active promise and lets the autonomous loop continue.
+
+### Resume Interrupted Session
+
+If your session ended mid-workflow:
+
+```
+/ralph-continue session-20251230-143022
+```
+
+This restores the workflow state from the archived log.
+
+### List Available Workflows
+
+```
+/ralph-continue --list
+```
+
+Output:
+```
+┌─────────────────────────────────────────────────────────────────┐
+│               RESUMABLE WORKFLOWS                               │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Active:                                                        │
+│  └─ session-20251230-150000 (user-api) - tdd_green phase       │
+│                                                                 │
+│  Archived:                                                      │
+│  └─ session-20251230-143022 - last activity: 14:45:00          │
+│  └─ session-20251229-091500 - last activity: 09:30:00 (stale)  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Implementation
+
+<claude-commands-template>
+When /ralph-continue is invoked:
+
+### Without Arguments (Continue Current)
+
+1. Load completion-promises.json:
+   ```python
+   promise_state = load_promise_state()
+   ```
+
+2. Clear active promise:
+   ```python
+   promise_state['active_promise'] = None
+   save_promise_state(promise_state)
+   ```
+
+3. Load api-dev-state.json and find current phase
+
+4. Output continuation message:
+   ```
+   ✓ Cleared active promise
+   ✓ Continuing from phase: {current_phase}
+   ✓ Iteration {current} / {max}
+
+   The autonomous loop will now continue.
+   Output <promise>DONE</promise> when complete.
+   ```
+
+5. If in autonomous mode, re-invoke the current phase skill
+
+### With Workflow ID (Resume Specific)
+
+1. Use hook_utils.handle_resume(workflow_id):
+   ```python
+   from hook_utils import handle_resume
+   state, message = handle_resume(workflow_id)
+   ```
+
+2. If state found:
+   - Display what phase will resume
+   - Ask user to confirm
+   - If confirmed, re-invoke the workflow
+
+3. If not found:
+   - Show error and list available workflows
+
+### With --list Flag
+
+1. Use hook_utils.list_resumable_workflows():
+   ```python
+   from hook_utils import list_resumable_workflows
+   workflows = list_resumable_workflows()
+   ```
+
+2. Display formatted list as shown above
+
+### Reset Iterations (Optional Flag)
+
+If `--reset-iterations` is passed:
+```python
+from hook_utils import reset_phase_iterations
+reset_phase_iterations()
+```
+
+This clears all iteration counters, useful if max-iterations was hit.
+</claude-commands-template>
+
+## Related Commands
+
+- `/ralph-status` - Check current loop status
+- `/api-create --resume [id]` - Resume with full workflow context
+- `/hustle-build --resume [id]` - Resume build workflow

package/.skills/ralph-loop/SKILL.md

@@ -0,0 +1,341 @@
+---
+name: ralph-loop
+description: Start an autonomous loop with completion promise detection (Ralph Wiggum pattern)
+license: MIT
+compatibility: Requires Claude Code with completion-promise-detector hook
+metadata:
+  version: "1.0.0"
+  category: "autonomous"
+  tags: ["ralph-wiggum", "autonomous", "loop", "continuous"]
+  author: "Hustle Together"
+  references:
+    - https://ghuntley.com/ralph/
+    - docs/CLAUDE_CODE_BEST_PRACTICES.md
+allowed-tools: Bash Read Write Edit Grep Glob Task TodoWrite AskUserQuestion
+---
+
+# Ralph Wiggum Autonomous Loop
+
+Start a self-terminating autonomous loop. The agent works continuously until it outputs a completion promise signal, then gracefully stops.
+
+## Usage
+
+```
+/ralph-loop [task description]
+/ralph-loop --promise [CUSTOM] [task description]
+/ralph-loop --max [N] [task description]
+/ralph-continue
+/ralph-status
+```
+
+## Arguments
+
+- `$ARGUMENTS` - The task to complete autonomously
+- `--promise [WORD]` - Custom completion word (default: DONE)
+- `--max [N]` - Maximum iterations before forced stop (safety net)
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                   RALPH WIGGUM PATTERN                          │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │                    AUTONOMOUS LOOP                        │  │
+│  │                                                           │  │
+│  │   1. Agent works on task                                  │  │
+│  │   2. Agent self-evaluates progress                        │  │
+│  │   3. If done → Output <promise>DONE</promise>            │  │
+│  │   4. If not done → Continue working                       │  │
+│  │   5. Hook detects promise → Graceful termination          │  │
+│  │                                                           │  │
+│  └──────────────────────────────────────────────────────────┘  │
+│                          │                                      │
+│                          ▼                                      │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │              COMPLETION PROMISE DETECTOR                  │  │
+│  │                                                           │  │
+│  │   Monitors all tool outputs for:                          │  │
+│  │   - <promise>DONE</promise>                              │  │
+│  │   - <promise>FIXED</promise>                             │  │
+│  │   - <promise>COMPLETE</promise>                          │  │
+│  │   - Custom promises via --promise flag                    │  │
+│  │                                                           │  │
+│  └──────────────────────────────────────────────────────────┘  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Built-in Completion Promises
+
+| Promise | Use Case |
+|---------|----------|
+| `DONE` / `COMPLETE` / `FINISHED` | General task completion |
+| `FIXED` / `RESOLVED` / `SOLVED` | Bug fixing |
+| `REFACTORED` / `CLEANED` / `IMPROVED` | Code improvement |
+| `TESTED` / `VERIFIED` / `VALIDATED` | Testing tasks |
+| `DEPLOYED` / `SHIPPED` / `RELEASED` | Deployment tasks |
+
+## Phase 1: Parse Arguments
+
+Extract from `$ARGUMENTS`:
+
+1. **Task Description** - What to accomplish
+2. **Custom Promise** - If `--promise` specified
+3. **Max Iterations** - If `--max` specified
+
+## Phase 2: Initialize Loop
+
+1. **Create Todo List:**
+   - Main task objective
+   - Sub-tasks as identified
+
+2. **Set Loop Parameters:**
+   ```json
+   {
+     "task": "[description]",
+     "completion_promise": "DONE",
+     "max_iterations": null,
+     "started_at": "[timestamp]",
+     "iteration": 0
+   }
+   ```
+
+3. **Output Initialization:**
+   ```
+   ═══════════════════════════════════════════════════════════════
+                    RALPH WIGGUM LOOP STARTED
+   ═══════════════════════════════════════════════════════════════
+
+   Task: [description]
+   Completion Signal: <promise>DONE</promise>
+   Max Iterations: [N or unlimited]
+
+   The loop will continue until you output the completion signal.
+   Use /ralph-status to check progress.
+   Use /ralph-continue to override a detected promise.
+   ═══════════════════════════════════════════════════════════════
+   ```
+
+## Phase 3: Execute Loop
+
+Work on the task using this pattern:
+
+```markdown
+## Iteration [N]
+
+### Current State
+- What has been done
+- What remains
+
+### This Iteration
+1. [Action 1]
+2. [Action 2]
+3. [Action 3]
+
+### Self-Evaluation
+- [ ] Task requirement 1 met?
+- [ ] Task requirement 2 met?
+- [ ] All tests passing?
+- [ ] Code review clean?
+
+### Decision
+If ALL requirements met:
+  → Output: <promise>DONE</promise>
+Else:
+  → Continue to next iteration
+```
+
+## Phase 4: Completion
+
+When outputting a completion promise:
+
+```markdown
+## Task Complete
+
+### Summary
+- What was accomplished
+- Files changed
+- Tests status
+
+### Verification
+- [x] Requirement 1
+- [x] Requirement 2
+- [x] All tests pass
+
+<promise>DONE</promise>
+```
+
+The hook will detect this and allow graceful termination.
+
+---
+
+## Example Prompts
+
+### Feature Development
+```
+/ralph-loop "Implement user authentication with JWT tokens
+
+Requirements:
+- Login endpoint at /api/auth/login
+- Register endpoint at /api/auth/register
+- JWT token generation and validation
+- Password hashing with bcrypt
+- All tests passing
+
+Output <promise>DONE</promise> when all requirements met and tests pass."
+```
+
+### Bug Fixing
+```
+/ralph-loop --promise FIXED "Fix the memory leak in the WebSocket handler
+
+Steps:
+1. Identify the leak source
+2. Implement fix
+3. Add regression test
+4. Verify with memory profiler
+
+Output <promise>FIXED</promise> when the leak is resolved."
+```
+
+### Refactoring
+```
+/ralph-loop --max 25 "Refactor the payment module to use the new API client
+
+Checklist:
+- [ ] Update all API calls
+- [ ] Maintain backward compatibility
+- [ ] Update tests
+- [ ] Update documentation
+
+Output <promise>REFACTORED</promise> when complete."
+```
+
+---
+
+## Commands
+
+### /ralph-continue
+
+Override a detected promise and continue the loop:
+
+```
+/ralph-continue
+```
+
+Use when:
+- Promise was output prematurely
+- More work needed despite signal
+- Testing the loop behavior
+
+### /ralph-status
+
+Check current loop status:
+
+```
+/ralph-status
+```
+
+Shows:
+- Active promise (if any)
+- Recent promise history
+- Current iteration count
+
+---
+
+## Best Practices
+
+### 1. Clear Requirements
+
+Always specify clear, verifiable requirements:
+
+```markdown
+Requirements:
+- [ ] Feature X implemented
+- [ ] Unit tests with >80% coverage
+- [ ] E2E test for happy path
+- [ ] No TypeScript errors
+- [ ] ESLint passing
+```
+
+### 2. Self-Evaluation Checkpoints
+
+Include explicit checkpoints in your prompt:
+
+```markdown
+Before outputting DONE, verify:
+1. All requirements in the list above are checked
+2. `pnpm test` passes
+3. `pnpm lint` passes
+4. `pnpm build` succeeds
+```
+
+### 3. Use Max Iterations as Safety Net
+
+Always set a reasonable max for complex tasks:
+
+```
+/ralph-loop --max 50 "Complex refactoring task..."
+```
+
+### 4. Combine with Test Skills
+
+```
+/ralph-loop "Implement feature X
+
+After implementation, run:
+- /test-unit
+- /test-e2e
+
+Only output <promise>DONE</promise> when ALL tests pass."
+```
+
+---
+
+## Integration with Hustle Build
+
+The `/hustle-build --auto` mode uses Ralph Wiggum internally:
+
+```
+/hustle-build --auto --max-iterations 10 "Build a photo gallery"
+```
+
+This:
+1. Starts autonomous build loop
+2. Uses completion promise detection
+3. Falls back to max-iterations if needed
+
+---
+
+## Troubleshooting
+
+### Promise Not Detected
+
+Ensure exact format: `<promise>DONE</promise>`
+- Must have angle brackets
+- Must be uppercase
+- No extra whitespace inside tags
+
+### Loop Won't Stop
+
+Check:
+1. `/ralph-status` - Is promise active?
+2. Hook enabled in settings?
+3. Try `/ralph-continue` then manually stop
+
+### Infinite Loop
+
+Safety measures:
+1. Use `--max [N]` flag
+2. Context window will eventually fill
+3. Manual Ctrl+C always works
+
+---
+
+## See Also
+
+- [Completion Promise Detector Hook](../../hooks/completion-promise-detector.py)
+- [CLAUDE_CODE_BEST_PRACTICES.md](../../docs/CLAUDE_CODE_BEST_PRACTICES.md) - Ralph Wiggum section
+- [/hustle-build skill](../hustle-build/SKILL.md) - Uses this pattern internally