opencode-swarm-plugin 0.62.1 → 0.63.0

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.59.5",
+  "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 |

package/claude-plugin/dist/index.js

@@ -152667,7 +152667,7 @@ WD9f
 
 // ../../node_modules/.bun/ioredis@5.9.2/node_modules/ioredis/built/utils/index.js
 var require_utils9 = __commonJS((exports) => {
-  var __dirname = "/home/runner/work/swarm-tools/swarm-tools/node_modules/.bun/ioredis@5.9.2/node_modules/ioredis/built/utils";
+  var __dirname = "/Users/joel/Code/joelhooks/opencode-swarm-plugin/node_modules/.bun/ioredis@5.9.2/node_modules/ioredis/built/utils";
   Object.defineProperty(exports, "__esModule", { value: true });
   exports.noop = exports.defaults = exports.Debug = exports.getPackageMeta = exports.zipMap = exports.CONNECTION_CLOSED_ERROR_MSG = exports.shuffle = exports.sample = exports.resolveTLSProfile = exports.parseURL = exports.optimizeErrorStack = exports.toArg = exports.convertMapToArray = exports.convertObjectToArray = exports.timeout = exports.packObject = exports.isInt = exports.wrapMultiResult = exports.convertBufferToString = undefined;
   var fs_1 = __require("fs");
@@ -152953,7 +152953,7 @@ var require_argumentParsers = __commonJS((exports) => {
 
 // ../../node_modules/.bun/ioredis@5.9.2/node_modules/ioredis/built/Command.js
 var require_Command = __commonJS((exports) => {
-  var __dirname = "/home/runner/work/swarm-tools/swarm-tools/node_modules/.bun/ioredis@5.9.2/node_modules/ioredis/built";
+  var __dirname = "/Users/joel/Code/joelhooks/opencode-swarm-plugin/node_modules/.bun/ioredis@5.9.2/node_modules/ioredis/built";
   Object.defineProperty(exports, "__esModule", { value: true });
   var commands_1 = require_built();
   var calculateSlot = require_lib();
@@ -194204,7 +194204,7 @@ var require_node_gyp_build_optional_packages = __commonJS((exports, module) => {
 
 // ../../node_modules/.bun/msgpackr-extract@3.0.3/node_modules/msgpackr-extract/index.js
 var require_msgpackr_extract = __commonJS((exports, module) => {
-  var __dirname = "/home/runner/work/swarm-tools/swarm-tools/node_modules/.bun/msgpackr-extract@3.0.3/node_modules/msgpackr-extract";
+  var __dirname = "/Users/joel/Code/joelhooks/opencode-swarm-plugin/node_modules/.bun/msgpackr-extract@3.0.3/node_modules/msgpackr-extract";
   module.exports = require_node_gyp_build_optional_packages()(__dirname);
 });
 
@@ -218507,7 +218507,7 @@ var require_indexes2 = __commonJS((exports, module) => {
 
 // ../../node_modules/.bun/thread-stream@3.1.0/node_modules/thread-stream/index.js
 var require_thread_stream = __commonJS((exports, module) => {
-  var __dirname = "/home/runner/work/swarm-tools/swarm-tools/node_modules/.bun/thread-stream@3.1.0/node_modules/thread-stream";
+  var __dirname = "/Users/joel/Code/joelhooks/opencode-swarm-plugin/node_modules/.bun/thread-stream@3.1.0/node_modules/thread-stream";
   var { version: version5 } = require_package();
   var { EventEmitter: EventEmitter4 } = __require("events");
   var { Worker: Worker3 } = __require("worker_threads");
@@ -218928,7 +218928,7 @@ var require_thread_stream = __commonJS((exports, module) => {
 
 // ../../node_modules/.bun/pino@9.14.0/node_modules/pino/lib/transport.js
 var require_transport = __commonJS((exports, module) => {
-  var __dirname = "/home/runner/work/swarm-tools/swarm-tools/node_modules/.bun/pino@9.14.0/node_modules/pino/lib";
+  var __dirname = "/Users/joel/Code/joelhooks/opencode-swarm-plugin/node_modules/.bun/pino@9.14.0/node_modules/pino/lib";
   var { createRequire: createRequire3 } = __require("module");
   var getCallers = require_caller();
   var { join: join18, isAbsolute: isAbsolute3, sep: sep4 } = __require("node:path");