ql-execute

Name: ql-execute
Author: andyzengmath

23stars0forks

How to install ql-execute?

andyzengmath/quantum-loop/ql-execute

$npx -y skills add andyzengmath/quantum-loop --skill ql-execute

Installs into the current project.

Summary

Part of the quantum-loop autonomous development pipeline (brainstorm \u2192 spec \u2192 plan \u2192 execute \u2192 review \u2192 verify). Run the autonomous execution loop. Reads quantum.json, queries the dependency DAG, implements stories with TDD and two-stage review gates. Sup

Files · 1

View on GitHub

SKILL.md

1	# Quantum-Loop: Execute
2
3	Run the autonomous execution loop to implement all stories in quantum.json.
4
5	## Prerequisites
6
7	Before starting:
8	1. `quantum.json` must exist (created by `/quantum-loop:plan`)
9	2. The project must be a git repository
10	3. Project build tools must be available (npm, pip, cargo, etc.)
11
12	If prerequisites are not met, inform the user and stop.
13
14	## Execution
15
16	Read and follow the orchestrator agent instructions in `agents/orchestrator.md`.
17
18	The orchestrator will:
19	1. Read quantum.json state and validate the dependency DAG
20	2. Query for eligible stories (pending/retriable with all dependencies passed)
21	3. If 1 story eligible: execute it sequentially (implement, quality checks, review, commit)
22	4. If 2+ stories eligible: spawn parallel implementer subagents in isolated worktrees
23	5. Handle retries, cascade blocking, and error recovery
24	6. Loop until all stories pass (COMPLETE) or no stories are executable (BLOCKED)
25
26	## Orchestrator liveness gate (N14 / US-002 — v0.7.0)
27
28	Default-on for unattended `/ql-execute` runs. v0.6.7 + v0.6.8 + v0.6.9 all saw the orchestrator subagent abandon its cycle mid-execution (LLM context-drift). v0.6.8 N6 shipped a prose-only Self-monitoring guard. v0.6.9 N6-followup shipped `lib/orchestrator-liveness.sh::poll_orchestrator_commits` as a callable runtime helper. This v0.7.0 N14 SKILL-level wrapping is the third and final layer — auto-invoke the helper after dispatching the orchestrator, hand off to the parent on STALE.
29
30	```bash
31	# After dispatching the orchestrator subagent (Step 3 of Execution above):
32	source lib/orchestrator-liveness.sh
33	wrap_orchestrator_dispatch 600 60 \|\| exit 1
34	```
35
36	The `wrap_orchestrator_dispatch` function (v0.7.1 N20 extraction; see
37	`lib/orchestrator-liveness.sh`) handles the `QL_LIVENESS_ENABLE` env-var
38	check, the `poll_orchestrator_commits` invocation, and the structured
39	handoff message internally. The SKILL just calls it and exits 1 on
40	STALE so CI / wrapper scripts can distinguish stale-signal exits from
41	clean COMPLETE / BLOCKED exits.
42
43	Env var contract:
44
45	\| `QL_LIVENESS_ENABLE=` \| Effect \|
46	\|---\|---\|
47	\| (unset) or `true` \| default — wrap orchestrator dispatch with `poll_orchestrator_commits` (timeout 600s, interval 60s) \|
48	\| `false` \| skip the wrapping; preserve v0.6.9 dispatch semantics exactly (backwards compat for operators with their own wrappers) \|
49	\| any other value \| treated as `true` (default-true semantics; warn to stderr) \|
50
51	Handoff message structure (printed to stdout when STALE fires):
52	- One-line `[QL-EXECUTE] orchestrator-stale signal.` header.
53	- Pointer to `references/orchestrator-takeover.md` (the v0.6.9 N13 SOP).
54	- Numbered recovery steps the parent agent runs (drift verification + manual takeover).
55
56	The parent agent reads the handoff and either re-spawns `/ql-execute` (after confirming whether drift was a transient LLM hiccup) or takes over manually per the SOP. SKILL exits with rc=1 (`orchestrator-stale`) so CI / wrapper scripts can distinguish stale-signal exits from clean COMPLETE / BLOCKED exits.
57
58	Testability note (presence-only AC): the wrapping prose above is consumed by an LLM that runs `/ql-execute`. There is no runtime test that EXERCISES the env-var conditional or the handoff message structure inside the SKILL itself — those would require running the SKILL in a controlled fixture. Instead, `tests/test_ql_execute_liveness_wrapping.sh` verifies the prose contains the expected idioms (header, env var, default-true, cross-link, handoff structure). Matches v0.6.8 N6 prose-guard pattern.
59
60	## Autonomous CLI Alternative
61
62	For unattended execution outside Claude Code (Linux/Mac):
63	```bash
64	./quantum-loop.sh --max-iterations 20
65	./quantum-loop.sh --parallel --max-parallel 4
66	```
67
68	On Windows, use `/ql-execute` instead of the shell script for reliable execution.
69
70	## Signals
71
72	\| Signal \| Meaning \|
73	\|--------\|---------\|
74	\| `<quantum>COMPLETE</quantum>` \| All stories passed \|
75	\| `<quantum>BLOCKED</quantum>` \| No executable stories remain \|
76	\| `<quantum>STORY_PASSED</quantum>` \| One story completed (more remain) \|
77	\| `<quantum>STORY_FAILED</quantum>` \| One story failed (will retry if attempts remain) \|
78	\| `<quantum>WAVE_PASSED</quantum>` \| All stories in a coordinator wave passed (v0.8.0+ coordinator pattern; see `agents/coordinator.md`) \|
79	\| `<quantum>WAVE_FAILED</quantum>` \| One or more wave stories failed (parent decides retry/abort) \|
80
81	## Post-review slop-cleanup hook (Phase 9 / P1.6)
82
83	After each story's two-stage review gate PASSES but BEFORE t

People who liked this also viewed

6 picks

Type

ql-execute

23stars0forks

View on GitHub

How to install ql-execute?

andyzengmath/quantum-loop/ql-execute

$npx -y skills add andyzengmath/quantum-loop --skill ql-execute

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Quantum-Loop: Execute
2
3	Run the autonomous execution loop to implement all stories in quantum.json.
4
5	## Prerequisites
6
7	Before starting:
8	1. `quantum.json` must exist (created by `/quantum-loop:plan`)
9	2. The project must be a git repository
10	3. Project build tools must be available (npm, pip, cargo, etc.)
11
12	If prerequisites are not met, inform the user and stop.
13
14	## Execution
15
16	Read and follow the orchestrator agent instructions in `agents/orchestrator.md`.
17
18	The orchestrator will:
19	1. Read quantum.json state and validate the dependency DAG
20	2. Query for eligible stories (pending/retriable with all dependencies passed)
21	3. If 1 story eligible: execute it sequentially (implement, quality checks, review, commit)
22	4. If 2+ stories eligible: spawn parallel implementer subagents in isolated worktrees
23	5. Handle retries, cascade blocking, and error recovery
24	6. Loop until all stories pass (COMPLETE) or no stories are executable (BLOCKED)
25
26	## Orchestrator liveness gate (N14 / US-002 — v0.7.0)
27
28	Default-on for unattended `/ql-execute` runs. v0.6.7 + v0.6.8 + v0.6.9 all saw the orchestrator subagent abandon its cycle mid-execution (LLM context-drift). v0.6.8 N6 shipped a prose-only Self-monitoring guard. v0.6.9 N6-followup shipped `lib/orchestrator-liveness.sh::poll_orchestrator_commits` as a callable runtime helper. This v0.7.0 N14 SKILL-level wrapping is the third and final layer — auto-invoke the helper after dispatching the orchestrator, hand off to the parent on STALE.
29
30	```bash
31	# After dispatching the orchestrator subagent (Step 3 of Execution above):
32	source lib/orchestrator-liveness.sh
33	wrap_orchestrator_dispatch 600 60 \|\| exit 1
34	```
35
36	The `wrap_orchestrator_dispatch` function (v0.7.1 N20 extraction; see
37	`lib/orchestrator-liveness.sh`) handles the `QL_LIVENESS_ENABLE` env-var
38	check, the `poll_orchestrator_commits` invocation, and the structured
39	handoff message internally. The SKILL just calls it and exits 1 on
40	STALE so CI / wrapper scripts can distinguish stale-signal exits from
41	clean COMPLETE / BLOCKED exits.
42
43	Env var contract:
44
45	\| `QL_LIVENESS_ENABLE=` \| Effect \|
46	\|---\|---\|
47	\| (unset) or `true` \| default — wrap orchestrator dispatch with `poll_orchestrator_commits` (timeout 600s, interval 60s) \|
48	\| `false` \| skip the wrapping; preserve v0.6.9 dispatch semantics exactly (backwards compat for operators with their own wrappers) \|
49	\| any other value \| treated as `true` (default-true semantics; warn to stderr) \|
50
51	Handoff message structure (printed to stdout when STALE fires):
52	- One-line `[QL-EXECUTE] orchestrator-stale signal.` header.
53	- Pointer to `references/orchestrator-takeover.md` (the v0.6.9 N13 SOP).
54	- Numbered recovery steps the parent agent runs (drift verification + manual takeover).
55
56	The parent agent reads the handoff and either re-spawns `/ql-execute` (after confirming whether drift was a transient LLM hiccup) or takes over manually per the SOP. SKILL exits with rc=1 (`orchestrator-stale`) so CI / wrapper scripts can distinguish stale-signal exits from clean COMPLETE / BLOCKED exits.
57
58	Testability note (presence-only AC): the wrapping prose above is consumed by an LLM that runs `/ql-execute`. There is no runtime test that EXERCISES the env-var conditional or the handoff message structure inside the SKILL itself — those would require running the SKILL in a controlled fixture. Instead, `tests/test_ql_execute_liveness_wrapping.sh` verifies the prose contains the expected idioms (header, env var, default-true, cross-link, handoff structure). Matches v0.6.8 N6 prose-guard pattern.
59
60	## Autonomous CLI Alternative
61
62	For unattended execution outside Claude Code (Linux/Mac):
63	```bash
64	./quantum-loop.sh --max-iterations 20
65	./quantum-loop.sh --parallel --max-parallel 4
66	```
67
68	On Windows, use `/ql-execute` instead of the shell script for reliable execution.
69
70	## Signals
71
72	\| Signal \| Meaning \|
73	\|--------\|---------\|
74	\| `<quantum>COMPLETE</quantum>` \| All stories passed \|
75	\| `<quantum>BLOCKED</quantum>` \| No executable stories remain \|
76	\| `<quantum>STORY_PASSED</quantum>` \| One story completed (more remain) \|
77	\| `<quantum>STORY_FAILED</quantum>` \| One story failed (will retry if attempts remain) \|
78	\| `<quantum>WAVE_PASSED</quantum>` \| All stories in a coordinator wave passed (v0.8.0+ coordinator pattern; see `agents/coordinator.md`) \|
79	\| `<quantum>WAVE_FAILED</quantum>` \| One or more wave stories failed (parent decides retry/abort) \|
80
81	## Post-review slop-cleanup hook (Phase 9 / P1.6)
82
83	After each story's two-stage review gate PASSES but BEFORE t

People who liked this also viewed

6 picks

Type