gm-copilot-cli 2.0.185 → 2.0.188

package/skills/gm-emit/SKILL.md

@@ -1,84 +1,101 @@
 ---
 name: gm-emit
-description: EMIT phase gate validation, pre/post-emit testing, code quality enforcement. Invoke when all EXECUTE mutables resolved and ready to write files.
+description: EMIT phase. Pre-emit debug, write files, post-emit verify from disk. Any new unknown triggers immediate snake back to planning — restart chain.
 ---
 
-# GM EMIT — Gate Validation and File Writing
+# GM EMIT — Writing and Verifying Files
 
-You are in the **EMIT** phase. All mutables were resolved in EXECUTE. Now validate, write, and verify files.
+You are in the **EMIT** phase. Every mutable is KNOWN. Prove the write is correct, write, confirm from disk. Any new unknown = snake to `planning`, restart chain.
 
 **GRAPH POSITION**: `PLAN → EXECUTE → [EMIT] → VERIFY → COMPLETE`
-- **Session entry chain**: prompt-submit hook → `gm` skill → `planning` → `gm-execute` → `gm-emit` skill (here). The `gm` skill contract is active: state machine, mutable discipline, ground truth only, all transitions invoke named skills.
-- **Entry**: All EXECUTE mutables resolved to KNOWN via witnessed execution. .prd items are scoped and proven.
-- **Exit**: Files written, post-emit validation passes, all gate conditions true simultaneously → invoke `gm-complete` skill.
-- **Rollback**: If post-emit validation fails → fix immediately in this phase, do not advance.
+- **Entry**: All .prd mutables resolved. Entered from `gm-execute` or via snake from VERIFY.
+
+## TRANSITIONS
+
+**FORWARD**: All gate conditions true simultaneously → invoke `gm-complete` skill
+
+**SELF-LOOP**: Post-emit variance with known cause → fix immediately, re-verify, do not advance until zero variance
+
+**BACKWARD**:
+- Pre-emit reveals logic error (known mutable) → invoke `gm-execute` skill, re-resolve, return here
+- Pre-emit reveals new unknown → invoke `planning` skill, restart chain
+- Post-emit variance with unknown cause → invoke `planning` skill, restart chain
+- Scope changed → invoke `planning` skill, restart chain
+- From VERIFY: end-to-end reveals broken file → re-enter here, fix, re-verify, re-advance
 
 ## MUTABLE DISCIPLINE
 
-Each gate condition is a mutable that must resolve to `true` before files are written. Pre-emit test results = expected values. Post-emit test results = current values. Zero variance required. Unresolved gate mutable = absolute barrier to VERIFY phase. State-tracking mutables live in conversation only. Never written to files.
+Each gate condition is a mutable. Pre-emit run witnesses expected value. Post-emit run witnesses current value. Zero variance = resolved. Variance with unknown cause = new unknown = snake to `planning`.
 
-## PRE-EMIT-TEST (before writing any file)
+## CODE EXECUTION
 
-1. Import the actual module from disk via `exec:nodejs`, witness current on-disk behavior
-2. Execute proposed logic in isolation — WITHOUT writing to any file
-3. Witness correct output with real inputs. Test failure paths with real error inputs.
-4. For browser code: inject `__gm` globals, run interactions, dump captures, verify
+**exec:<lang> is the only way to run code.** Bash tool body: `exec:<lang>\n<code>`
 
-Always: `exec:nodejs\nconst { fn } = await import('/abs/path')` — never rewrite logic inline.
+`exec:nodejs` (default) | `exec:bash` | `exec:python` | `exec:typescript` | `exec:go` | `exec:rust` | `exec:java` | `exec:deno` | `exec:cmd`
 
-## WRITING FILES
+Only git in bash directly. `Bash(node/npm/npx/bun)` = violations. File writes via exec:nodejs + require('fs').
 
-Use `exec:nodejs` with `require('fs')` for all file operations. Write all files only when every gate mutable is `resolved=true` simultaneously.
+## PRE-EMIT DEBUGGING (before writing any file)
 
-## POST-EMIT-VALIDATION (immediately after writing)
+1. Import actual module from disk via `exec:nodejs` — witness current on-disk behavior
+2. Run proposed logic in isolation WITHOUT writing — witness output with real inputs
+3. Debug failure paths with real error inputs — record expected values
 
-1. Load actual modified file from disk via real import — not in-memory version
-2. Output must match PRE-EMIT-TEST witnessed output exactly
-3. For browser: reload from disk, re-inject `__gm` globals, re-run interactions, compare captures
-4. Any variance = regression, fix immediately before proceeding
+```
+exec:nodejs
+const { fn } = await import('/abs/path/to/module.js');
+console.log(await fn(realInput));
+```
 
-## GATE CONDITIONS (all must be true simultaneously)
+Pre-emit revealing unexpected behavior → new unknown → snake to `planning`.
 
-- Executed via `exec:<lang>` or `agent-browser` — witnessed real output
-- Every scenario tested: success, failure, edge, corner, error, recovery
-- Real witnessed output proves goal achieved
-- Hot reloadable: state outside reloadable modules, handlers swap atomically
-- Crash-proof: catch at every boundary, recovery hierarchy, every component supervised
-- No mocks/fakes/stubs anywhere in codebase
-- Files ≤200 lines each
-- No duplicate code
-- No comments in code
-- No hardcoded values
-- Docs-code sync: CLAUDE.md reflects actual code behavior
+## WRITING FILES
 
-## TOOL REFERENCE
+`exec:nodejs` with `require('fs')`. Write only when every gate mutable is `resolved=true` simultaneously.
 
-**`exec:<lang>`** — Bash tool: `exec:<lang>\n<code>`. Languages: `exec:nodejs` (default) | `exec:python` | `exec:bash` | `exec:typescript` | `exec:go` | `exec:rust` | `exec:java` | `exec:deno` | `exec:cmd`. Lang auto-detected. `cwd` sets directory. File I/O via exec:nodejs with require('fs'). Bash: only git directly.
+## POST-EMIT VERIFICATION (immediately after writing)
 
-**`agent-browser`** — Invoke `agent-browser` skill. Escalation: (1) `exec:agent-browser\n<js>` first → (2) skill + `__gm` globals → (3) navigate/click → (4) screenshot last resort.
+1. Re-import the actual file from disk — not in-memory version
+2. Run same inputs as pre-emit — output must match exactly
+3. For browser: reload from disk, re-inject `__gm` globals, re-run, compare captures
+4. Known variance → fix and re-verify | Unknown variance → snake to `planning`
 
-**`code-search`** — Invoke `code-search` skill. MANDATORY for all exploration. Glob/Grep/Explore blocked.
+## GATE CONDITIONS (all true simultaneously before advancing)
 
-## DUAL-SIDE VALIDATION
+- Pre-emit debug passed with real inputs and error inputs
+- Post-emit verification matches pre-emit exactly
+- Hot reloadable: state outside reloadable modules, handlers swap atomically
+- Crash-proof: catch at every boundary, recovery hierarchy
+- No mocks/fakes/stubs anywhere
+- Files ≤200 lines, no duplicate code, no comments, no hardcoded values
+- CLAUDE.md reflects actual behavior
 
-Backend proven with `exec:nodejs`, frontend with `agent-browser` + `__gm`. Neither substitutes. Single-side = UNKNOWN mutable = blocked gate.
+## CODEBASE EXPLORATION
 
-## SELF-CHECK (before and after each file)
+```
+exec:codesearch
+<natural language description>
+```
 
-1. File ≤200 lines | 2. No duplicate code | 3. Pre-emit test passed | 4. No mocks | 5. No comments | 6. Docs match code | 7. All spotted issues fixed
+Alias: `exec:search`. Glob, Grep, Explore = blocked.
 
-Score = 100 - (T0_violations×50) - (T1_violations×20) - (T2_violations×5). Target ≥95.
+## BROWSER DEBUGGING
 
-## GROUND TRUTH
+Invoke `agent-browser` skill. Escalation: (1) `exec:agent-browser\n<js>` → (2) skill + `__gm` globals → (3) navigate/click → (4) screenshot last resort.
+
+## SELF-CHECK (before and after each file)
 
-Real services only. On discovering mocks/fakes/stubs: delete immediately, implement real paths.
+File ≤200 lines | No duplication | Pre-emit passed | No mocks | No comments | Docs match | All spotted issues fixed
 
-## CONSTRAINTS (EMIT-PHASE)
+## CONSTRAINTS
 
-**Never**: skip pre-emit testing | skip post-emit validation | leave docs-code desync | defer spotted issues | advance with failing gate | comments in code | hardcoded values
+**Never**: write before pre-emit passes | advance with post-emit variance | absorb surprises silently | comments | hardcoded values | defer spotted issues
 
-**Always**: pre-emit test before writing | post-emit validate after writing | dual-side for full-stack | self-check every file | reconcile docs | fix immediately
+**Always**: pre-emit debug before writing | post-emit verify from disk | snake to planning on any new unknown | fix immediately
 
 ---
 
-**→ NEXT**: When all gate conditions pass → invoke `gm-complete` skill for end-to-end verification and git enforcement.
+**→ FORWARD**: All gates pass → invoke `gm-complete` skill.
+**↺ SELF-LOOP**: Known post-emit variance → fix, re-verify.
+**↩ SNAKE to EXECUTE**: Known logic error → invoke `gm-execute` skill.
+**↩ SNAKE to PLAN**: Any new unknown → invoke `planning` skill, restart chain.

package/skills/gm-execute/SKILL.md

@@ -1,42 +1,68 @@
 ---
 name: gm-execute
-description: EXECUTE phase methodology. Hypothesis testing, chain decomposition, import-based verification, browser protocols, ground truth enforcement.
+description: EXECUTE phase. Resolve all mutables via witnessed execution. Any new unknown triggers immediate snake back to planning — restart chain from PLAN.
 ---
 
-# GM EXECUTE — Proving Every Hypothesis
+# GM EXECUTE — Resolving Every Unknown
 
-You are in the **EXECUTE** phase. All mutables must resolve to KNOWN via witnessed execution before transitioning to EMIT.
+You are in the **EXECUTE** phase. Resolve every named mutable via witnessed execution. Any new unknown = stop, snake to `planning`, restart chain.
 
 **GRAPH POSITION**: `PLAN → [EXECUTE] → EMIT → VERIFY → COMPLETE`
-- **Session entry chain**: prompt-submit hook → `gm` skill → `planning` skill → `gm-execute` skill (here). The `gm` skill contract is active: state machine, mutable discipline, ground truth only, all transitions invoke named skills.
-- **Entry**: .prd exists with all unknowns named. This skill owns the EXECUTE phase entirely.
-- **Exit**: Zero unresolved mutables → invoke `gm-emit` skill for gate validation and file writing.
-- **Sub-skills**: code discovery → invoke `code-search` skill | browser work → invoke `agent-browser` skill | servers/workers/daemons → invoke `process-management` skill
-- **Re-entry**: If mutables remain unresolved, re-invoke `gm-execute` skill with broader scope. Never add stages.
+- **Entry**: .prd exists with all unknowns named. Entered from `planning` or via snake from EMIT/VERIFY.
+
+## TRANSITIONS
+
+**FORWARD**: All mutables KNOWN → invoke `gm-emit` skill
+
+**SELF-LOOP**: Mutable still UNKNOWN after one pass → re-run with different angle (max 2 passes then snake)
+
+**BACKWARD**:
+- New unknown discovered → invoke `planning` skill immediately, restart chain
+- From EMIT: logic error → re-enter here, re-resolve mutable
+- From VERIFY: runtime failure → re-enter here, re-resolve with real system state
 
 ## MUTABLE DISCIPLINE
 
-Enumerate all unknowns as named mutables. Each mutable: name, expected value, current value, resolution method. Execute → witness → assign → compare → zero variance = resolved. Unresolved = absolute barrier. Never narrate. Assign, execute, resolve, transition. State-tracking mutables live in conversation only. Never written to files.
+Each mutable: name | expected | current | resolution method. Execute → witness → assign → compare. Zero variance = resolved. Unresolved after 2 passes = new unknown = snake to `planning`. Never narrate past an unresolved mutable.
 
-## HYPOTHESIS TESTING
+## CODE EXECUTION
 
-Every hypothesis proven by execution before changing files. Know nothing until execution proves it.
+**exec:<lang> is the only way to run code.** Bash tool body: `exec:<lang>\n<code>`
 
-**DENSITY**: Each execution ≤15s, packed with every related hypothesis. Group every related unknown into one run. Never one idea per run.
+`exec:nodejs` (default) | `exec:bash` | `exec:python` | `exec:typescript` | `exec:go` | `exec:rust` | `exec:c` | `exec:cpp` | `exec:java` | `exec:deno` | `exec:cmd`
 
-**PARALLEL WAVES**: Launch ≤3 gm:gm subagents per wave via Task tool. Independent items run simultaneously. Sequential execution = violation. Waves of ≤3; batches >3 split.
+Lang auto-detected if omitted. `cwd` sets directory. File I/O via exec:nodejs + require('fs'). Only git in bash directly. `Bash(node/npm/npx/bun)` = violations.
 
-## CHAIN DECOMPOSITION
+**Background tasks** (auto-backgrounded when execution exceeds 15s):
+```
+exec:sleep
+<task_id> [seconds]
+```
+```
+exec:status
+<task_id>
+```
+```
+exec:close
+<task_id>
+```
+
+**Runner** (PM2-backed — all activity visible in `pm2 list` and `pm2 monit` in user terminal):
+```
+exec:runner
+start|stop|status
+```
+
+## CODEBASE EXPLORATION
+
+```
+exec:codesearch
+<natural language description of what you need>
+```
 
-Every multi-step chain broken into individually-verified steps BEFORE any end-to-end run:
-1. List every distinct operation as numbered steps
-2. Per step: define input shape, output shape, success condition, failure condition
-3. Execute step 1 in isolation → witness → assign mutable → proceed only when KNOWN
-4. Execute step 2 with step 1's witnessed output as input. Repeat for every step.
-5. After all steps pass individually, test adjacent pairs for handoff correctness
-6. Only after all pairs pass: run full chain end-to-end
+Alias: `exec:search`. Glob, Grep, Read-for-discovery, Explore, WebSearch = blocked.
 
-## IMPORT-BASED EXECUTION
+## IMPORT-BASED DEBUGGING
 
 Always import actual codebase modules. Never rewrite logic inline.
 
@@ -48,44 +74,48 @@ console.log(await fn(realInput));
 
 Witnessed import output = resolved mutable. Reimplemented output = UNKNOWN.
 
-## TOOL REFERENCE
+## EXECUTION DENSITY
 
-**`exec:<lang>`** — Bash tool: `exec:<lang>\n<code>`. Languages: `exec:nodejs` (default) | `exec:python` | `exec:bash` | `exec:typescript` | `exec:go` | `exec:rust` | `exec:c` | `exec:cpp` | `exec:java` | `exec:deno` | `exec:cmd`. Lang auto-detected if omitted. `cwd` field sets working directory. File I/O: exec:nodejs with require('fs'). Bash scope: only git directly. All else via exec interception.
+Pack every related hypothesis into one run. Each run ≤15s. Witnessed output = ground truth. Narrated assumption = nothing.
 
-**`code-search`** — Semantic code discovery. Invoke `code-search` skill. MANDATORY for all exploration. Glob/Grep/Read-for-discovery/Explore/WebSearch blocked. Fallback: `bun x codebasesearch <query>`. Try 5+ queries before alternatives.
+Parallel waves: ≤3 `gm:gm` subagents via Task tool — independent items simultaneously, never sequentially.
 
-**`agent-browser`** — Invoke `agent-browser` skill. Replaces puppeteer/playwright entirely. Escalation order:
-1. `exec:agent-browser\n<js>` — query DOM/state via JS. Always first.
-2. `agent-browser` skill + `__gm` globals + evaluate — instrument, intercept, capture.
-3. navigate/click/type — only when state requires real events.
-4. screenshot — LAST RESORT. Screenshot before exhausting 1–3 = blocked gate.
+## CHAIN DECOMPOSITION
+
+Break every multi-step operation before running end-to-end:
+1. Number every distinct step
+2. Per step: input shape, output shape, success condition, failure mode
+3. Run each step in isolation — witness — assign mutable — KNOWN before next
+4. Debug adjacent pairs for handoff correctness
+5. Only when all pairs pass: run full chain end-to-end
+
+Step failure revealing new unknown → snake to `planning`.
 
-**`process-management`** — Invoke `process-management` skill. MANDATORY for all servers/workers/daemons. Pre-check before start. Delete on completion. Orphaned processes = gate violation. Direct node/bun/python for servers = violation.
+## BROWSER DEBUGGING
 
-## BROWSER GLOBALS SCAFFOLD
+Invoke `agent-browser` skill. Escalation — exhaust each before advancing:
+1. `exec:agent-browser\n<js>` — query DOM/state. Always first.
+2. `agent-browser` skill + `__gm` globals — instrument and capture
+3. navigate/click/type — only when real events required
+4. screenshot — last resort
 
-Inject before any browser state assertion:
+`__gm` scaffold:
 ```js
 window.__gm = { captures: [], log: (...a) => window.__gm.captures.push({t:Date.now(),a}), assert: (l,c) => { window.__gm.captures.push({l,pass:!!c,val:c}); return !!c; }, dump: () => JSON.stringify(window.__gm.captures,null,2) };
 ```
 
-## DUAL-SIDE VALIDATION
-
-Backend via `exec:nodejs`, frontend via `agent-browser` + `__gm`. Neither substitutes. Single-side = UNKNOWN mutable = blocked gate.
-
 ## GROUND TRUTH
 
-Real services, real API responses, real timing only. On discovering mocks/fakes/stubs: delete immediately, implement real paths. Unit testing forbidden: no .test.js/.spec.js, no mock files. Delete on discovery.
-
-## CONSTRAINTS (EXECUTE-PHASE)
+Real services, real data, real timing. Mocks/fakes/stubs = delete immediately. No .test.js/.spec.js. Delete on discovery.
 
-**Tier 0 (ABSOLUTE)**: immortality, no_crash, no_exit, ground_truth_only, real_execution
-**Tier 1 (CRITICAL)**: max_file_lines=200, hot_reloadable, checkpoint_state
+## CONSTRAINTS
 
-**Never**: fake data | write test files | use Glob/Grep/Explore for discovery | direct bash non-git | puppeteer/playwright | screenshot before JS | independent items sequentially
+**Never**: `Bash(node/npm/npx/bun)` | fake data | mock files | Glob/Grep/Explore | sequential independent items | absorb surprises silently
 
-**Always**: import real modules | delete mocks on discovery | witness every hypothesis | fix issues immediately
+**Always**: witness every hypothesis | import real modules | snake to planning on any new unknown | fix immediately on discovery
 
 ---
 
-**→ NEXT**: When all mutables resolved → invoke `gm-emit` skill for gate validation and file writing.
+**→ FORWARD**: All mutables KNOWN → invoke `gm-emit` skill.
+**↺ SELF-LOOP**: Still UNKNOWN → re-run (max 2 passes).
+**↩ SNAKE to PLAN**: Any new unknown → invoke `planning` skill, restart chain.

package/skills/planning/SKILL.md

@@ -1,78 +1,84 @@
 ---
 name: planning
-description: PRD construction for work planning. Compulsory in PLAN phase. Builds .prd file as frozen dependency graph of every possible work item before execution begins. Triggers on any new task, multi-step work, or when gm enters PLAN state.
+description: Mutable discovery and PRD construction. Invoke at session start and any time new unknowns surface during execution. Loop until no new mutables are discovered.
 allowed-tools: Write
 ---
 
-# PRD Construction
+# PRD Construction — Mutable Discovery Loop
 
-You are in the **PLAN** phase. Build the .prd before any execution begins.
+You are in the **PLAN** phase. Your job is to discover every unknown before execution begins.
 
 **GRAPH POSITION**: `[PLAN] → EXECUTE → EMIT → VERIFY → COMPLETE`
-- **Session entry chain**: prompt-submit hook → `gm` skill → `planning` skill (here). The `gm` skill contract is active: state machine, mutable discipline, all transitions invoke named skills, no fake data.
-- **Entry**: No work begins until .prd exists on disk. This is the first tool-calling phase.
-- **Exit**: .prd written to disk → invoke `gm-execute` skill to begin EXECUTE phase.
+- **Entry chain**: prompt-submit hook → `gm` skill → `planning` skill (here).
+- **Also entered**: any time a new unknown surfaces in EXECUTE, EMIT, or VERIFY.
 
-## Purpose
+## TRANSITIONS
 
-The `.prd` is the single source of truth for remaining work. A frozen dependency graph capturing every possible item — steps, substeps, edge cases, corner cases, dependencies, transitive dependencies, unknowns, assumptions, decisions, trade-offs, acceptance criteria, scenarios, failure paths, recovery paths, integration points, state transitions, race conditions, concurrency concerns, error conditions, boundary conditions, configuration variants, environment differences, platform concerns, backwards compatibility, rollback paths, verification steps.
+**FORWARD**:
+- No new mutables discovered in latest pass → .prd is complete → invoke `gm-execute` skill
 
-Longer is better. Missing items means missing work.
+**SELF-LOOP (stay in PLAN)**:
+- Each planning pass may surface new unknowns → add them to .prd → plan again
+- Loop until a full pass produces zero new items
+- Do not advance to EXECUTE while unknowns remain discoverable through reasoning alone
 
-## File Rules
+**BACKWARD (snakes back here from later phases)**:
+- From EXECUTE: execution reveals an unknown not in .prd → snake here, add it, re-plan
+- From EMIT: scope shifted mid-write → snake here, revise affected items, re-plan
+- From VERIFY: end-to-end reveals requirement was wrong → snake here, rewrite items, re-plan
 
-Path: exactly `./.prd` in current working directory. No variants. Valid JSON.
+## WHAT PLANNING MEANS
 
-## Item Schema
+Planning = exhaustive mutable discovery. For every aspect of the task ask:
+- What do I not know? → name it as a mutable
+- What could go wrong? → name it as an edge case item
+- What depends on what? → map blocking/blockedBy
+- What assumptions am I making? → validate each as a mutable
+
+**Iterate until**: a full reasoning pass adds zero new items to .prd.
+
+Categories of unknowns to enumerate: file existence | API shape | data format | dependency versions | runtime behavior | environment differences | error conditions | concurrency | integration points | backwards compatibility | rollback paths | deployment steps | verification criteria
+
+## .PRD SCHEMA
+
+Path: exactly `./.prd` in current working directory. Valid JSON array.
 
 ```json
 {
   "id": "descriptive-kebab-id",
-  "subject": "Imperative verb describing outcome",
+  "subject": "Imperative verb phrase — what must be true when done",
   "status": "pending",
-  "description": "What must be true when this is done",
-  "blocking": ["ids-this-prevents"],
-  "blockedBy": ["ids-that-must-finish-first"],
+  "description": "Precise completion criterion",
+  "blocking": ["ids this prevents from starting"],
+  "blockedBy": ["ids that must complete first"],
   "effort": "small|medium|large",
-  "category": "feature|bug|refactor|docs|infra",
-  "acceptance": ["measurable criteria"],
-  "edge_cases": ["known complications"]
+  "category": "feature|bug|refactor|infra",
+  "acceptance": ["measurable, binary criteria"],
+  "edge_cases": ["known failure modes and boundary conditions"]
 }
 ```
 
-**Subject**: imperative form — "Fix auth bug", "Add webhook support". Never "Bug: auth".
-**Status**: `pending` → `in_progress` → `completed`. No other values.
-**Effort**: `small` (<15min) | `medium` (<45min) | `large` (1h+).
-**Blocking/blockedBy**: bidirectional. Every dependency explicit.
-
-## Construction
-
-1. Enumerate every possible unknown as a work item.
-2. Map every possible dependency (blocking/blockedBy).
-3. Group independent items into parallel waves (max 3 per wave).
-4. Capture every edge case as either a separate item or edge_case field.
-5. Write `./.prd` to disk.
-6. **FREEZE** — no additions after creation. Only mutation: removing finished items.
-
-## Execution
-
-1. Find all `pending` items with empty `blockedBy`.
-2. Launch ≤3 parallel subagents (`subagent_type: gm:gm`) per wave.
-3. Each subagent completes one item, verifies via witnessed execution.
-4. On completion: remove item from `.prd`, write updated file.
-5. Check for newly unblocked items. Launch next wave.
-6. Continue until `.prd` is empty.
+**Status flow**: `pending` → `in_progress` → `completed` (completed items are removed from file).
+**Effort**: `small` = single execution, under 15min | `medium` = 2-3 rounds, under 45min | `large` = multiple rounds, over 1h.
+**blocking/blockedBy**: always bidirectional. Every dependency must be explicit in both directions.
 
-Never execute independent items sequentially. Never launch more than 3 at once.
+## EXECUTION WAVES
 
-## Completion
+Independent items (empty `blockedBy`) run in parallel waves of ≤3 subagents.
+- Find all pending items with empty `blockedBy`
+- Launch ≤3 parallel `gm:gm` subagents via Task tool
+- Each subagent handles one item: resolves it, witnesses output, removes from .prd
+- After each wave: check newly unblocked items, launch next wave
+- Never run independent items sequentially. Never launch more than 3 at once.
 
-`.prd` must be empty at COMPLETE. The stop hook blocks session end when items remain.
+## COMPLETION CRITERION
 
-## Do Not Use
+.prd is ready when: one full reasoning pass produces zero new items AND all items have explicit acceptance criteria AND all dependencies are mapped.
 
-Skip this skill if the task is trivially single-step (under 5 minutes, no dependencies, no unknowns).
+**Skip planning entirely** if: task is single-step, trivially bounded, zero unknowns, under 5 minutes.
 
 ---
 
-**→ NEXT**: .prd written → invoke `gm-execute` skill to begin EXECUTE phase.
+**→ FORWARD**: No new mutables → invoke `gm-execute` skill.
+**↺ SELF-LOOP**: New items discovered → add to .prd → plan again.
+**↩ SNAKE here**: New unknown surfaces in any later phase → add it, re-plan, re-advance.

package/tools.json

@@ -1,6 +1,6 @@
 {
   "name": "gm",
-  "version": "2.0.185",
+  "version": "2.0.188",
   "description": "State machine agent with hooks, skills, and automated git enforcement",
   "tools": [
     {