ql-plan

Name: ql-plan
Author: andyzengmath

23stars0forks

How to install ql-plan?

andyzengmath/quantum-loop/ql-plan

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

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). Convert a PRD into machine-readable quantum.json with dependency DAG, granular 2-5 minute tasks, and execution metadata. Use after creating a

Files · 1

View on GitHub

SKILL.md

1	# Quantum-Loop: Plan
2
3	You are converting a Product Requirements Document (PRD) into a machine-readable `quantum.json` file that will drive autonomous execution. Every decision you make here determines whether the execution loop succeeds or fails.
4
5	## Phase 0: Phase-skip check (Phase 18 / P2.4)
6
7	Before reading the PRD, check whether a prior `/ql-plan` run already converted the same PRD + spec handoff into quantum.json:
8
9	```bash
10	PRD=$(ls -t tasks/prd-*.md 2>/dev/null \| head -1)
11	SPEC_HANDOFF=".handoffs/spec.md"
12	ARGS=()
13	[[ -n "$PRD" ]] && ARGS+=("$PRD")
14	[[ -f "$SPEC_HANDOFF" ]] && ARGS+=("$SPEC_HANDOFF")
15
16	if bash lib/phase-skip.sh skip plan . "${ARGS[@]}"; then
17	echo "[SKIP] plan is up-to-date — PRD + spec handoff unchanged."
18	bash lib/handoff.sh read plan \| jq '.'
19	exit 0
20	fi
21	```
22
23	After writing quantum.json and `.handoffs/plan.md`, record the fingerprint:
24
25	```bash
26	PRD_H=$(bash lib/phase-skip.sh hash "$PRD")
27	SPEC_H=$(bash lib/phase-skip.sh hash "$SPEC_HANDOFF")
28	FP=$(jq -cn --arg pp "$PRD" --arg ph "$PRD_H" --arg sp "$SPEC_HANDOFF" --arg sh "$SPEC_H" \
29	'{artifacts: [{path: $pp, sha256: $ph}, {path: $sp, sha256: $sh}]}')
30	bash lib/phase-skip.sh record plan "$FP" . >/dev/null
31	```
32
33	## Prerequisite: read prior-stage handoffs (Phase 15 / P2.3)
34
35	Before reading the PRD, ingest every prior-stage handoff so decisions, rejected alternatives, and risks carry forward across context compaction:
36
37	```bash
38	bash lib/handoff.sh all \| jq '.'
39	bash lib/handoff.sh read brainstorm \| jq '.'
40	bash lib/handoff.sh read spec \| jq '.'
41	```
42
43	Treat `spec.decided` as binding (these are the ACs you MUST plan for), `spec.rejected` as closed (don't re-introduce), `spec.remaining` as explicit gaps you should surface to the user before finalizing the DAG, and the union of `brainstorm.risks ∪ spec.risks` as mandatory inputs to every story's risk consideration.
44
45	At the end of `/ql-plan`, write `.handoffs/plan.md`:
46
47	```bash
48	bash lib/handoff.sh write plan "$(cat <<'JSON'
49	{
50	"decided": ["<each DAG + wave decision>", "<contract materialization picks>"],
51	"rejected": ["<each alternative story split / ordering considered>"],
52	"risks": ["<carried from upstream + any new planning risks>"],
53	"files": ["quantum.json"],
54	"remaining": ["<any AC you could not resolve into a concrete story>"],
55	"notes": "<notes on parallelism, file-conflict sets, contract choices>"
56	}
57	JSON
58	)"
59	```
60
61	## Step 1: Read the PRD
62
63	1. Look for the most recent PRD in `tasks/prd-*.md`
64	2. If multiple PRDs exist, ask the user which one to convert
65	3. Read the entire PRD, extracting:
66	- User stories (US-NNN) with acceptance criteria
67	- Functional requirements (FR-N)
68	- Technical considerations and constraints
69	- Non-goals (to prevent scope creep during execution)
70
71	Also read:
72	- Project files (package.json, pyproject.toml, etc.) for project name and tech stack
73	- Existing code structure to determine correct file paths for tasks
74
75	## Step 2: Analyze Dependencies
76
77	Build a dependency graph between stories. Dependencies follow natural layering:
78
79	```
80	1. Schema / Database changes (foundation)
81	2. Type definitions / Models (depends on schema)
82	3. Backend logic / API endpoints (depends on types)
83	4. UI components (depends on API)
84	5. Integration / Aggregate views (depends on components)
85	```
86
87	### Dependency Rules
88	- A story that reads from a table DEPENDS ON the story that creates that table
89	- A story that renders data DEPENDS ON the story that provides the API
90	- A story that tests integration DEPENDS ON all component stories
91	- If two stories touch unrelated parts of the codebase, they are INDEPENDENT (no dependency)
92
93	### Cycle Detection
94	After building the dependency graph, verify there are no cycles. If you detect a cycle:
95	1. STOP and inform the user
96	2. Explain which stories form the cycle
97	3. Ask how to break the cycle (usually by splitting a story)
98
99	### Contracts Generation (after dependency DAG)
100
101	After building the dependency graph, scan for values that appear in 2+ stories' acceptance criteria or task descriptions. These are contract candidates — shared constants that parallel agents must agree on.
102
103	1. Identify candidates: Look for repeated references to the same entity across stories — secret key names, environment variable names, type/class names, API route paths, event names, CSS class names
104	2. Group by category: Organize candidates into logical categories:
105	- `secret_keys` — shared secret/config key names
106	- `env_vars` — environment variable names
107	- `shared_types` — type names, class names, enum values
108	- `api_route

People who liked this also viewed

6 picks

Type

ql-plan

23stars0forks

View on GitHub

How to install ql-plan?

andyzengmath/quantum-loop/ql-plan

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Quantum-Loop: Plan
2
3	You are converting a Product Requirements Document (PRD) into a machine-readable `quantum.json` file that will drive autonomous execution. Every decision you make here determines whether the execution loop succeeds or fails.
4
5	## Phase 0: Phase-skip check (Phase 18 / P2.4)
6
7	Before reading the PRD, check whether a prior `/ql-plan` run already converted the same PRD + spec handoff into quantum.json:
8
9	```bash
10	PRD=$(ls -t tasks/prd-*.md 2>/dev/null \| head -1)
11	SPEC_HANDOFF=".handoffs/spec.md"
12	ARGS=()
13	[[ -n "$PRD" ]] && ARGS+=("$PRD")
14	[[ -f "$SPEC_HANDOFF" ]] && ARGS+=("$SPEC_HANDOFF")
15
16	if bash lib/phase-skip.sh skip plan . "${ARGS[@]}"; then
17	echo "[SKIP] plan is up-to-date — PRD + spec handoff unchanged."
18	bash lib/handoff.sh read plan \| jq '.'
19	exit 0
20	fi
21	```
22
23	After writing quantum.json and `.handoffs/plan.md`, record the fingerprint:
24
25	```bash
26	PRD_H=$(bash lib/phase-skip.sh hash "$PRD")
27	SPEC_H=$(bash lib/phase-skip.sh hash "$SPEC_HANDOFF")
28	FP=$(jq -cn --arg pp "$PRD" --arg ph "$PRD_H" --arg sp "$SPEC_HANDOFF" --arg sh "$SPEC_H" \
29	'{artifacts: [{path: $pp, sha256: $ph}, {path: $sp, sha256: $sh}]}')
30	bash lib/phase-skip.sh record plan "$FP" . >/dev/null
31	```
32
33	## Prerequisite: read prior-stage handoffs (Phase 15 / P2.3)
34
35	Before reading the PRD, ingest every prior-stage handoff so decisions, rejected alternatives, and risks carry forward across context compaction:
36
37	```bash
38	bash lib/handoff.sh all \| jq '.'
39	bash lib/handoff.sh read brainstorm \| jq '.'
40	bash lib/handoff.sh read spec \| jq '.'
41	```
42
43	Treat `spec.decided` as binding (these are the ACs you MUST plan for), `spec.rejected` as closed (don't re-introduce), `spec.remaining` as explicit gaps you should surface to the user before finalizing the DAG, and the union of `brainstorm.risks ∪ spec.risks` as mandatory inputs to every story's risk consideration.
44
45	At the end of `/ql-plan`, write `.handoffs/plan.md`:
46
47	```bash
48	bash lib/handoff.sh write plan "$(cat <<'JSON'
49	{
50	"decided": ["<each DAG + wave decision>", "<contract materialization picks>"],
51	"rejected": ["<each alternative story split / ordering considered>"],
52	"risks": ["<carried from upstream + any new planning risks>"],
53	"files": ["quantum.json"],
54	"remaining": ["<any AC you could not resolve into a concrete story>"],
55	"notes": "<notes on parallelism, file-conflict sets, contract choices>"
56	}
57	JSON
58	)"
59	```
60
61	## Step 1: Read the PRD
62
63	1. Look for the most recent PRD in `tasks/prd-*.md`
64	2. If multiple PRDs exist, ask the user which one to convert
65	3. Read the entire PRD, extracting:
66	- User stories (US-NNN) with acceptance criteria
67	- Functional requirements (FR-N)
68	- Technical considerations and constraints
69	- Non-goals (to prevent scope creep during execution)
70
71	Also read:
72	- Project files (package.json, pyproject.toml, etc.) for project name and tech stack
73	- Existing code structure to determine correct file paths for tasks
74
75	## Step 2: Analyze Dependencies
76
77	Build a dependency graph between stories. Dependencies follow natural layering:
78
79	```
80	1. Schema / Database changes (foundation)
81	2. Type definitions / Models (depends on schema)
82	3. Backend logic / API endpoints (depends on types)
83	4. UI components (depends on API)
84	5. Integration / Aggregate views (depends on components)
85	```
86
87	### Dependency Rules
88	- A story that reads from a table DEPENDS ON the story that creates that table
89	- A story that renders data DEPENDS ON the story that provides the API
90	- A story that tests integration DEPENDS ON all component stories
91	- If two stories touch unrelated parts of the codebase, they are INDEPENDENT (no dependency)
92
93	### Cycle Detection
94	After building the dependency graph, verify there are no cycles. If you detect a cycle:
95	1. STOP and inform the user
96	2. Explain which stories form the cycle
97	3. Ask how to break the cycle (usually by splitting a story)
98
99	### Contracts Generation (after dependency DAG)
100
101	After building the dependency graph, scan for values that appear in 2+ stories' acceptance criteria or task descriptions. These are contract candidates — shared constants that parallel agents must agree on.
102
103	1. Identify candidates: Look for repeated references to the same entity across stories — secret key names, environment variable names, type/class names, API route paths, event names, CSS class names
104	2. Group by category: Organize candidates into logical categories:
105	- `secret_keys` — shared secret/config key names
106	- `env_vars` — environment variable names
107	- `shared_types` — type names, class names, enum values
108	- `api_route

People who liked this also viewed

6 picks

Type