ql-execute
npx machina-cli add skill andyzengmath/quantum-loop/ql-execute --openclawQuantum-Loop: Execute
Run the autonomous execution loop to implement all stories in quantum.json.
Prerequisites
Before starting:
quantum.jsonmust exist (created by/quantum-loop:plan)- The project must be a git repository
- Project build tools must be available (npm, pip, cargo, etc.)
If prerequisites are not met, inform the user and stop.
Execution
Read and follow the orchestrator agent instructions in agents/orchestrator.md.
The orchestrator will:
- Read quantum.json state and validate the dependency DAG
- Query for eligible stories (pending/retriable with all dependencies passed)
- If 1 story eligible: execute it sequentially (implement, quality checks, review, commit)
- If 2+ stories eligible: spawn parallel implementer subagents in isolated worktrees
- Handle retries, cascade blocking, and error recovery
- Loop until all stories pass (COMPLETE) or no stories are executable (BLOCKED)
Autonomous CLI Alternative
For unattended execution outside Claude Code (Linux/Mac):
./quantum-loop.sh --max-iterations 20
./quantum-loop.sh --parallel --max-parallel 4
On Windows, use /ql-execute instead of the shell script for reliable execution.
Signals
| Signal | Meaning |
|---|---|
<quantum>COMPLETE</quantum> | All stories passed |
<quantum>BLOCKED</quantum> | No executable stories remain |
<quantum>STORY_PASSED</quantum> | One story completed (more remain) |
<quantum>STORY_FAILED</quantum> | One story failed (will retry if attempts remain) |
Source
git clone https://github.com/andyzengmath/quantum-loop/blob/master/skills/ql-execute/SKILL.mdView on GitHub Overview
ql-execute runs the autonomous execution loop to implement stories listed in quantum.json. It reads quantum.json, validates the dependency DAG, and applies TDD with two-stage review gates. It supports parallel execution via native worktree isolation and loops until all stories pass or are BLOCKED.
How This Skill Works
It orchestrates by reading quantum.json and validating the dependency DAG, then querying for eligible stories. If one story is eligible, it runs a serial implement+quality+review+commit flow; if two or more are eligible, it forks parallel implementer subagents in isolated worktrees. It manages retries, cascading blocks, and error recovery, looping until COMPLETE or BLOCKED.
When to Use It
- After /quantum-loop:plan has created quantum.json and you are ready to execute
- When there is a single eligible story with all dependencies satisfied
- When you want to accelerate progress by executing multiple stories in parallel
- When handling transient failures that require automatic retries or cascading blocking
- When you want to drive the full cycle to COMPLETE or BLOCKED status
Quick Start
- Step 1: Ensure quantum.json exists (created by /quantum-loop:plan)
- Step 2: Run the CLI: Linux/macOS: ./quantum-loop.sh --max-iterations 20; Windows: /ql-execute
- Step 3: Monitor for COMPLETE, STORY_PASSED, or BLOCKED signals and loop
Best Practices
- Ensure quantum.json exists and the project is a Git repository before running
- Verify required build tools (npm, pip, cargo, etc.) are available
- Prefer parallel execution only if native worktime isolation is supported
- Monitor signals: COMPLETE, STORY_PASSED, STORY_FAILED, BLOCKED for flow control
- Keep dependency DAG up to date and review gates aligned with TDD
Example Use Cases
- After planning, run ql-execute to implement all stories in quantum.json
- Run two eligible stories in parallel to reduce iteration time
- Retry a STORY_FAILED story automatically until attempts are exhausted
- Use unattended CLI in CI to continuously drive the execution loop
- Observe BLOCKED status when a dependency is not yet satisfied
