Orc

Create .orc/sessions/${CLAUDE_SESSION_ID}/prd.json:

{
  "task": "[user's original request]",
  "mode": "[solo|solo+ralph|team|team+ralph|solver]",
  "stories": [
    { "id": "story-1", "title": "[clear deliverable]", "passes": false },
    { "id": "story-2", "title": "[clear deliverable]", "passes": false }
  ],
  "iteration": 0,
  "errors": [],
  "started_at": "[ISO timestamp]"
}

Create .orc/sessions/${CLAUDE_SESSION_ID}/session.json:

{
  "active": true,
  "mode": "[chosen mode]",
  "sessionId": "${CLAUDE_SESSION_ID}",
  "started_at": "[ISO timestamp]"
}

Rules for stories:

• Each story must be independently verifiable (build + test)
• 1-7 stories. Fewer is better. Each must be concrete.
• For solo mode with 1 story, ralph is unnecessary — use plain solo.
• For algorithm problems, 1 story is fine (the solution itself).

Phase 3: Execute

solo

Spawn coder agent with the task. It implements, tests, and marks passes:true in prd.json.

solo+ralph

Spawn coder for the first story. When it completes (or you try to stop), the Stop hook reads prd.json and injects the next incomplete story. This continues automatically until all stories pass.

For each story:

1. Implement the story
2. Verify: run build and tests. Show evidence.
3. Update prd.json: set passes: true for the completed story
4. The Stop hook handles continuation.

team

1. Use TeamCreate to create a team
2. Choose agents based on the task:
   • Frontend + Backend + DB → spawn frontend, backend, tester
   • Code review → spawn reviewer, security, analyst
   • Research → spawn scout, researcher, gemini-worker
   • Algorithm → spawn solver (×2), consensus
3. Use TaskCreate for each story, with dependencies if needed
4. Monitor progress via TaskList / TaskGet
5. When all tasks complete, verify and merge

team+ralph

Same as team, but the Stop hook keeps the lead running until all prd.json stories pass.

solver

Spawn solver agent directly with the problem. It runs in a worktree with opus-level reasoning. For extra confidence, also spawn consensus to cross-validate.

Phase 4: Completion

When all stories in prd.json have passes: true:

1. Update session.json: active: false
2. The Stop hook will allow exit
3. Report results to the user

Agent Selection Guide

External Model Usage

When a task benefits from a second opinion or specialized capability:

• Use codex-worker for tasks where Codex excels (code generation, sandbox execution)
• Use gemini-worker for vision tasks or extremely large context
• Use consensus when a critical decision needs validation from multiple models

Circuit Breaker

If the Stop hook detects 3 consecutive identical errors, it automatically halts. The session ends with an error report. This prevents infinite loops.

Important

• ALWAYS create prd.json and session.json BEFORE spawning agents
• ALWAYS verify each story with concrete evidence (build output, test results)
• NEVER mark a story as passes:true without evidence
• NEVER ask the user to choose a mode — decide automatically
• After 3 failed attempts on a story: STOP, document what failed, try a different approach or escalate