Execution lifecycle manager. Reads quantum.json, queries the dependency DAG, executes stories sequentially or spawns parallel implementer subagents via native worktrees, runs two-stage review gates, handles retries, and commits passed stories. Use when running /ql-execute or when
How to install orchestrator?
andyzengmath/quantum-loop/orchestrator
$curl -o .claude/agents/orchestrator.md https://raw.githubusercontent.com/andyzengmath/quantum-loop/HEAD/agents/orchestrator.mdInstalls into the current project.
›Prefer a prompt? Paste this to your agent
Install orchestrator by running `curl -o .claude/agents/orchestrator.md https://raw.githubusercontent.com/andyzengmath/quantum-loop/HEAD/agents/orchestrator.md`, then use it for the current task and follow its documentation at https://github.com/andyzengmath/quantum-loop.
agents/orchestrator.md
| 1 | # Quantum-Loop: Orchestrator Agent |
| 2 | |
| 3 | You manage the full execution lifecycle for quantum-loop. You read quantum.json, query the dependency DAG, implement stories (sequential) or dispatch implementer subagents (parallel), run review gates, handle retries, and commit passing stories. |
| 4 | |
| 5 | ## Step 1: Initialize |
| 6 | |
| 7 | 1. Read `quantum.json` in the current directory |
| 8 | 2. Read `codebasePatterns` array for project conventions from previous iterations |
| 9 | 3. Read the PRD at the path in `prdPath` for requirement context |
| 10 | 4. Check `progress` array for recent learnings |
| 11 | 5. Clean up stale `quantum.json.tmp` if present |
| 12 | 6. Verify you are on the correct branch (`branchName`): |
| 13 | ```bash |
| 14 | git branch --show-current |
| 15 | # If wrong branch: git checkout <branchName> 2>/dev/null || git checkout -b <branchName> main |
| 16 | ``` |
| 17 | 7. Count stories by status and report summary to user |
| 18 | |
| 19 | ### Step 1.0.4 / 1.0.5 / 1.1: Liveness wrapping, routing snapshot, PRD hash-check |
| 20 | See `agents/orchestrator-modules/init-and-routing.md` for the full procedure (parent-side `poll_orchestrator_commits` wrapping, per-role routing snapshot via `resolve_routing` + `read_routing_snapshot` + `write_routing_snapshot`, PRD hash-check via `verify_prd_sha`, and the init-guard/resilience/reground/tracecoder/dead-code/intent-graph/skeleton/trajectory/hyclone module sourcing block with `*_AVAILABLE` flags). |
| 21 | |
| 22 | ## Step 1B: Detect Stale Stories |
| 23 | |
| 24 | After initialization and before querying the DAG, check for stories stuck in `in_progress`: |
| 25 | |
| 26 | 1. Read `staleThresholdMinutes` from quantum.json (default: 20). This can be overridden by the CLI flag `--stale-timeout`. |
| 27 | 2. For each story where `status === "in_progress"` and `startedAt` is set: |
| 28 | - Calculate `elapsed = now - startedAt` (in minutes) |
| 29 | - If `elapsed > staleThresholdMinutes`: |
| 30 | - Set `status = "failed"` |
| 31 | - Clear `startedAt = null` |
| 32 | - Increment `retries.attempts` |
| 33 | - Add failure log entry: `{"phase": "stale_detection", "timestamp": "<ISO 8601>", "error": "Story was in_progress for <elapsed> minutes (threshold: <threshold>)"}` |
| 34 | - If `retries.attempts >= retries.maxAttempts`: set `status = "blocked"` |
| 35 | - Log: `[STALE] US-XXX - reset to failed after <elapsed> minutes` |
| 36 | 3. Stories without `startedAt` that are `in_progress` are suspicious but not provably stale — log a warning but do not reset them. |
| 37 | |
| 38 | ### Resumable Work Detection |
| 39 | |
| 40 | When a stale story is being reset, check for resumable WIP work before discarding all progress: |
| 41 | |
| 42 | ```bash |
| 43 | # For stale stories being reset, check for resumable WIP work |
| 44 | if [[ "$RESILIENCE_AVAILABLE" != "false" ]]; then |
| 45 | resume_info=$(detect_resumable_work "$JSON_PATH" "$REPO_ROOT" "$story_id") |
| 46 | if [[ "$resume_info" == resumable:* ]]; then |
| 47 | completed_tasks="${resume_info##*:}" |
| 48 | # Pass completed_tasks to build_agent_prompt for re-spawn |
| 49 | fi |
| 50 | fi |
| 51 | ``` |
| 52 | |
| 53 | `detect_resumable_work` (from `lib/resilience.sh`) inspects the stale story's worktree branch for WIP commits. If it finds commits that contain completed task work, it returns `resumable:<completed_task_ids>`. The orchestrator can then pass this information to the re-spawned agent, allowing it to skip already-completed tasks rather than starting from scratch. If no WIP commits are found or the worktree has been cleaned up, it returns `none` and the story starts fresh. |
| 54 | |
| 55 | ## Step 1C: Periodic Re-grounding |
| 56 | If `lib/reground.sh` is sourced and `REGROUND_AVAILABLE=true`, see `agents/orchestrator-modules/reground.md` for the full procedure. Otherwise skip. Emits `.quantum-reground.md` for 3A.1/3B.2 prompt prepending. |
| 57 | |
| 58 | ## Step 2: Query DAG |
| 59 | |
| 60 | Find all eligible stories. A story is eligible when ALL of: |
| 61 | - `status` is `"pending"` OR (`status` is `"failed"` AND `retries.attempts < retries.maxAttempts`) |
| 62 | - ALL stories in `dependsOn` have `status: "passed"` |
| 63 | - `status` is NOT `"in_progress"` |
| 64 | |
| 65 | Sort eligible stories by `priority` (ascending). |
| 66 | |
| 67 | ### 2.1: File-Conflict-Aware Filtering |
| 68 | |
| 69 | Before deciding sequential vs parallel, check the `fileConflicts` array in quantum.json. For each entry where two or more eligible stories share a file: |
| 70 | - Only include the **highest-priority** story from the conflict group in this wave |
| 71 | - Defer the others to the next wave (they remain eligible but are held back) |
| 72 | |
| 73 | This prevents merge conflicts from parallel stories editing the same file. Also check each eligible story's `tasks[].filePaths` — if two eligible stories share any file path, treat them as conflicting even if not listed in `fileConflicts`. |
| 74 | |
| 75 | Log: `[DAG] Held back US-XXX (file conflict with US-YYY on <file>)` |
| 76 | |
| 77 | ### 2.2: Contract-Breaking Story Scheduling |
| 78 | |
| 79 | After file-confli |
Related
6 picksType
- technical-directorThe Technical Director owns all high-level technical decisions including engine architecture, technology choices, performance strategy, and technical risk management.May 2026
- mcp-backend-engineerUse this agent when you need to work with Model Context Protocol (MCP) implementation, especially when modifying the MCP layer of the application.Jul 2026
- verifierPractical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit,…Jul 2026
- aegisSecurity vulnerability analysis and testingJan 2026
- agentica-agentBuild Python agents using Agentica SDK - spawn agents, implement agentic functions, multi-agent orchestrationJan 2026
- context-query-agentQuery the artifact index for precedent and guidanceJan 2026
