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

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

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

@@ -0,0 +1,87 @@
+---
+name: ralph-status
+description: Show current Ralph Wiggum loop status - phase, iteration count, elapsed time, and promises emitted
+license: MIT
+compatibility: Requires Claude Code with hook_utils.py
+metadata:
+  version: "4.5.0"
+  category: "workflow"
+  tags: ['ralph', 'autonomous', 'loop', 'status']
+  author: "Hustle Together"
+allowed-tools: Read
+model: haiku
+---
+
+# Ralph Status
+
+Show the current status of autonomous Ralph Wiggum loops.
+
+## Usage
+
+```
+/ralph-status
+```
+
+## What It Shows
+
+1. **Current Phase** - Which workflow phase is active
+2. **Iteration Count** - How many iterations in current phase
+3. **Max Iterations** - The limit before safety cutoff
+4. **Active Promise** - Any completion promise waiting to be fulfilled
+5. **Recent History** - Last 5 promise detections
+6. **Elapsed Time** - How long the current session has been running
+
+## Output Format
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    RALPH WIGGUM STATUS                          │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Workflow ID: session-20251230-143022                           │
+│  Current Phase: tdd_green                                       │
+│  Iteration: 7 / 25 (max)                                        │
+│  Active Promise: None                                           │
+│  Elapsed: 12m 34s                                               │
+│                                                                 │
+│  Recent Promises:                                               │
+│  └─ DONE via Write at 14:28:15                                  │
+│  └─ TESTED via Bash at 14:25:42                                 │
+│                                                                 │
+│  Phase Iterations:                                              │
+│  └─ tdd_red: 3                                                  │
+│  └─ tdd_green: 7                                                │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Implementation
+
+<claude-commands-template>
+When /ralph-status is invoked:
+
+1. Read the workflow state files:
+   - `.claude/api-dev-state.json` - Main workflow state
+   - `.claude/completion-promises.json` - Ralph loop state
+
+2. Extract and display:
+   - workflow_id from state
+   - Current phase from state.phases (find "in_progress")
+   - phase_iterations from state
+   - active_promise from completion-promises.json
+   - history from completion-promises.json (last 5)
+
+3. Calculate elapsed time:
+   - Read workflow log from `.claude/workflow-logs/{workflow_id}.json`
+   - Get started_at timestamp
+   - Calculate difference from now
+
+4. Format output as shown above
+
+5. If no active workflow:
+```
+No active workflow. Start one with:
+- /api-create [endpoint]
+- /hustle-build [prompt]
+```
+</claude-commands-template>

package/.skills/refactor/SKILL.md

@@ -150,3 +150,62 @@ This phase is **not part of the regular TDD workflow** and must only be applied
      - Testing notes
    - Document expected behavior and edge cases
    - Include real-world output examples
+
+## Autonomous Loop Completion (Ralph Wiggum Pattern)
+
+When running in autonomous mode (`--auto` flag or `/ralph-loop`), this skill supports
+self-terminating loops for iterative refactoring cycles.
+
+### Promise Signal
+
+After completing refactoring and verifying tests still pass, output:
+
+```
+<promise>REFACTORED</promise>
+```
+
+This signal is detected by the `completion-promise-detector.py` hook, which:
+1. Records the promise in `.claude/completion-promises.json`
+2. Allows graceful workflow termination
+3. Prevents infinite refactoring loops
+
+### When to Output the Promise
+
+Output `<promise>REFACTORED</promise>` when:
+- All identified refactoring opportunities have been addressed
+- Tests are still passing (verify with `pnpm test`)
+- No additional cleanup is needed
+- Code meets project quality standards
+
+### Iterative Refactor Loop
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                   REFACTOR LOOP (Ralph Wiggum)                  │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Identify refactoring opportunities                          │
+│     └─ Code smells, duplication, complexity                     │
+│                                                                 │
+│  2. Apply refactoring                                           │
+│     └─ Run tests → Failing? → Fix before continuing             │
+│                                                                 │
+│  3. Review result                                               │
+│     └─ More opportunities? → Loop back to step 1                │
+│                                                                 │
+│  4. All clean?                                                  │
+│     └─ Output: <promise>REFACTORED</promise>                    │
+│     └─ Hook detects → Workflow terminates gracefully            │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Credit:** Ralph Wiggum pattern by [Geoffrey Huntley](https://ghuntley.com/ralph/)
+
+## See Also
+
+- `/red` - Write failing tests
+- `/green` - Minimal implementation
+- `/cycle` - Full TDD cycle
+- `/ralph-loop` - Autonomous loop execution
+- [docs/AUTONOMOUS_LOOPS.md](../../docs/AUTONOMOUS_LOOPS.md) - Pattern documentation