orchestrator

Name: orchestrator
Author: andyzengmath

23stars0forks

How to install orchestrator?

andyzengmath/quantum-loop/orchestrator

$curl -o .claude/agents/orchestrator.md https://raw.githubusercontent.com/andyzengmath/quantum-loop/HEAD/agents/orchestrator.md

Installs into the current project.

Summary

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

Files · 1

View on GitHub

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

People who liked this also viewed

6 picks

Type

orchestrator

23stars0forks

View on GitHub

How to install orchestrator?

andyzengmath/quantum-loop/orchestrator

$curl -o .claude/agents/orchestrator.md https://raw.githubusercontent.com/andyzengmath/quantum-loop/HEAD/agents/orchestrator.md

Installs into the current project.

Summary

Files · 1

View on GitHub

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

People who liked this also viewed

6 picks

Type