| name | orchestrate |
| description | Poll beans for ready epics, create worktrees, and delegate to sub-agents that implement each epic following docs/workflow.md. Use when asked to "run orchestration", "process epics", or "start the agent loop".
|
Orchestrate — Epic Dispatch Loop
Monitor beans for ready epics and delegate each to a sub-agent in an
isolated worktree.
Prerequisites
gh CLI authenticatedbeans CLI availablegit worktree support- Scripts:
scripts/worktree-create.sh, scripts/worktree-remove.sh
Loop
1. Intake (optional)
Run the intake skill first if GitHub Issues should be imported:
→ skills/intake/SKILL.md
2. Find ready epics
beans ready --type epic
This returns epics with no unresolved blockers. Skip epics that are
already claimed by another agent.
3. For each ready epic
3a. Derive branch slug
From the epic title: lowercase, spaces to hyphens, drop punctuation,
truncate to ~50 chars.
Example: "Add bulk edit command" → add-bulk-edit-command
3b. Create worktree
./scripts/worktree-create.sh <epic-id> <branch-slug>
This creates ../jira-genie-worktrees/<epic-id>-<slug>/ with a fresh
branch from origin/main, runs uv sync, and verifies tests pass.
3c. Claim the epic
beans claim <epic-id> --actor orchestrator
3d. Delegate to sub-agent
Spawn a sub-agent in the worktree directory with this task:
Follow docs/workflow.md to implement epic <epic-id>.
The sub-agent operates autonomously inside the worktree using the
full docs/workflow.md operating script: plan → TDD loop → push → PR.
4. Monitor outcomes
After a sub-agent finishes:
- Success (PR created): the epic should be closed by the sub-agent.
Verify with
beans show <epic-id>.
- Failure/crash: check
beans ready --parent <epic-id> for remaining
work. The worktree and branch are preserved for retry. A new sub-agent
can resume from the current state.
- Blocked: sub-agent should have stopped and reported the blocker.
Check the GitHub Issue (if one exists) for a blocker comment.
5. Cleanup (after merge)
Once the PR is merged:
./scripts/worktree-remove.sh <epic-id> <branch-slug>
Concurrency
- One sub-agent per epic.
- Multiple epics can run in parallel in separate worktrees.
- The orchestrator should not dispatch the same epic twice (check
beans show <epic-id> — if status is in_progress, skip it).
State recovery
All state lives in beans + git:
- Which epics are in flight?
beans list --type epic --status in_progress
- Which leaves remain?
beans ready --parent <epic-id>
- What code exists?
git worktree list + branch state
- No external DB needed. Restart the orchestrator and it resumes
from beans state.
