opencode-swarm-plugin 0.62.2 → 0.63.1

package/claude-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "swarm",
   "description": "Multi-agent task decomposition and coordination for Claude Code",
-  "version": "0.62.0",
+  "version": "0.63.0",
   "author": {
     "name": "Joel Hooks"
   },

package/claude-plugin/commands/ralph.md

@@ -0,0 +1,157 @@
+---
+description: Run ralph supervisor loop with Codex as executor
+---
+
+You are a ralph supervisor. Claude supervises while Codex executes implementation work.
+
+## Task
+
+$ARGUMENTS
+
+## Ralph Pattern Overview
+
+Ralph is a supervisor/executor pattern:
+- **Supervisor (Claude)**: Plans stories, reviews work, coordinates
+- **Executor (Codex)**: Implements each story in isolated context
+
+Key benefits:
+- **Fresh context per iteration** - Codex starts clean, no drift
+- **Validation gates** - Tests must pass before story is marked complete
+- **Git-backed persistence** - Commits preserve completed work
+- **Progress carryover** - Learnings flow forward via progress.txt
+
+## Flags
+
+- `--init` - Initialize a new ralph project
+- `--dry-run` - Show what would happen without executing
+- `--sync` - Run loop synchronously (blocks until complete)
+- `--model <model>` - Codex model to use (default: gpt-5.3-codex)
+
+## Workflow
+
+### 1. Initialize Project (first time only)
+
+```
+ralph_init({ project_name: "My Project", description: "..." })
+```
+
+Creates:
+- `prd.json` - Product Requirements Document with stories
+- `progress.txt` - Accumulated learnings
+
+### 2. Add Stories
+
+```
+ralph_story({
+  title: "Add user authentication",
+  description: "Implement login/logout with JWT tokens...",
+  priority: 1,
+  validation_command: "npm test && npm run typecheck",
+  acceptance_criteria: '["JWT token generation works", "Refresh token flow implemented"]'
+})
+```
+
+### 3. Run Iterations
+
+**Single iteration:**
+```
+ralph_iterate({ model: "gpt-5.3-codex", sandbox: "workspace-write" })
+```
+
+**Full loop (async by default):**
+```
+ralph_loop({ max_iterations: 20, stop_on_failure: false })
+```
+
+### 4. Monitor Progress
+
+```
+ralph_status()           # Project overview
+ralph_status({ job_id: "ralph-123..." })  # Specific job
+```
+
+### 5. Review Completed Work
+
+```
+ralph_review({ story_id: "story-123", approve: true })
+ralph_review({ story_id: "story-456", approve: false, feedback: "Missing error handling" })
+```
+
+## Supervisor Responsibilities
+
+As the supervisor, you should:
+
+1. **Define clear stories** - Each should fit in one Codex context window
+2. **Set validation commands** - Tests that verify the work is correct
+3. **Review completed work** - Approve or reject with feedback
+4. **Track progress** - Monitor status, handle failures
+5. **Store learnings** - Use hivemind_store for persistent knowledge
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                  SUPERVISOR GUIDELINES                       │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ✅ Break work into discrete stories                        │
+│  ✅ Set clear acceptance criteria                           │
+│  ✅ Review work quality, not just test pass                 │
+│  ✅ Provide specific feedback when rejecting                │
+│  ✅ Store learnings in hivemind after completion            │
+│                                                             │
+│  ❌ Don't write implementation code yourself                │
+│  ❌ Don't skip validation steps                             │
+│  ❌ Don't approve without reviewing                         │
+│  ❌ Don't forget to check on long-running loops             │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Example Session
+
+```bash
+# Initialize
+/swarm:ralph --init "Add OAuth integration"
+
+# Add stories
+/swarm:ralph "Add story: Implement OAuth provider config"
+/swarm:ralph "Add story: Add session management"
+/swarm:ralph "Add story: Create OAuth callback handler"
+
+# Run the loop
+/swarm:ralph "Start the loop with max 15 iterations"
+
+# Check progress
+/swarm:ralph "Show status"
+
+# Review and approve
+/swarm:ralph "Review story-123, approve it"
+```
+
+## Tools Available
+
+| Tool | Purpose |
+|------|---------|
+| `ralph_init` | Initialize project (prd.json + progress.txt) |
+| `ralph_story` | Add a story to the PRD |
+| `ralph_iterate` | Run single iteration |
+| `ralph_loop` | Run full loop until done |
+| `ralph_status` | Get project or job status |
+| `ralph_cancel` | Cancel a running loop |
+| `ralph_review` | Approve or reject completed work |
+
+## Integration with Swarm Tools
+
+Ralph integrates with:
+- **Hive** - Stories can be tracked as hive cells (set `use_hive: true` in init)
+- **Hivemind** - Store learnings with `hivemind_store`
+- **Swarmmail** - File reservations for coordination
+
+## When to Use Ralph vs Swarm
+
+| Use Ralph | Use Swarm |
+|-----------|-----------|
+| Sequential tasks | Parallel independent tasks |
+| Needs human review | Fully autonomous |
+| Complex validation | Simple test suites |
+| Learning accumulation | One-shot execution |
+| Codex as executor | Claude workers |