gm-cc 2.0.187 → 2.0.189

package/.claude-plugin/marketplace.json

@@ -4,7 +4,7 @@
     "name": "AnEntrypoint"
   },
   "description": "State machine agent with hooks, skills, and automated git enforcement",
-  "version": "2.0.187",
+  "version": "2.0.189",
   "metadata": {
     "description": "State machine agent with hooks, skills, and automated git enforcement"
   },

package/agents/gm.md

@@ -15,3 +15,5 @@ All work coordination, planning, execution, and verification happens through the
 All code execution uses `exec:<lang>` via the Bash tool — never direct `Bash(node ...)` or `Bash(npm ...)`.
 
 Do not use `EnterPlanMode`. Do not run code directly via Bash. Invoke `gm` skill first.
+
+Skills are invoked via the **Skill tool** (`skill: "name"`). Never use the Agent tool to load a skill — skills are not agents. The `gm` skill, `planning` skill, `gm-execute` skill, `gm-emit` skill, and `gm-complete` skill are all invoked with the Skill tool only.

package/hooks/prompt-submit-hook.js

@@ -74,7 +74,7 @@ try {
   ensureGitignore();
 
   const parts = [];
-  parts.push('Invoke the `gm` skill to begin. DO NOT use EnterPlanMode. DO NOT use gm subagent directly — use the `gm` skill via the Skill tool.');
+  parts.push('Use the Skill tool with skill: "gm" to begin — do NOT use the Agent tool to load skills. Skills are invoked via the Skill tool only, never as agents. DO NOT use EnterPlanMode.');
 
   const search = runCodeSearch(prompt);
   if (search) parts.push(search);

package/hooks/session-start-hook.js

@@ -29,7 +29,7 @@ ensureGitignore();
 try {
   let outputs = [];
 
-  outputs.push('Invoke the `gm` skill to begin. All code execution uses exec:<lang> via the Bash tool — never direct Bash(node ...) or Bash(npm ...) or Bash(npx ...).');
+  outputs.push('Use the Skill tool with skill: "gm" to begin — do NOT use the Agent tool to load skills. Skills are invoked via the Skill tool only, never as agents. All code execution uses exec:<lang> via the Bash tool — never direct Bash(node ...) or Bash(npm ...) or Bash(npx ...).');
 
   if (projectDir && fs.existsSync(projectDir)) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-cc",
-  "version": "2.0.187",
+  "version": "2.0.189",
   "description": "State machine agent with hooks, skills, and automated git enforcement",
   "author": "AnEntrypoint",
   "license": "MIT",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gm",
-  "version": "2.0.187",
+  "version": "2.0.189",
   "description": "State machine agent with hooks, skills, and automated git enforcement",
   "author": {
     "name": "AnEntrypoint",

package/skills/gm/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: gm
-description: Immutable programming state machine. Root orchestrator. Invoke for all work coordination.
-agent: true
+description: Immutable programming state machine. Root orchestrator. Invoke for all work coordination via the Skill tool.
 enforce: critical
 ---
 
@@ -9,74 +8,105 @@ enforce: critical
 
 You think in state, not prose. You are the root orchestrator of all work in this system.
 
-**GRAPH POSITION**: `[ROOT ORCHESTRATOR] → coordinates PLAN → EXECUTE → EMIT → VERIFY → COMPLETE`
-- **Invoke**: The prompt-submit hook directs you here first. Always the first skill invoked.
-- **Your job**: Set up the state machine, then immediately invoke `planning` skill.
-- **Previous skill context does not carry forward** — each invoked skill is self-contained. Shared state = .prd file + witnessed execution output only.
+**GRAPH POSITION**: `[ROOT ORCHESTRATOR]`
+- **Entry**: The prompt-submit hook always invokes `gm` skill first.
+- **Shared state**: .prd file on disk + witnessed execution output only. Nothing persists between skills.
+- **First action**: Invoke `planning` skill immediately.
 
-## STATE MACHINE — SNAKES AND LADDERS
+## THE STATE MACHINE
 
+`PLAN → EXECUTE → EMIT → VERIFY → COMPLETE`
+
+**FORWARD (ladders)**:
+- PLAN complete → invoke `gm-execute` skill
+- EXECUTE complete → invoke `gm-emit` skill
+- EMIT complete → invoke `gm-complete` skill
+- COMPLETE with .prd items remaining → invoke `gm-execute` skill (next wave)
+
+**BACKWARD (snakes) — any new unknown at any phase restarts from PLAN**:
+- New unknown discovered → invoke `planning` skill, restart chain
+- EXECUTE mutable unresolvable after 2 passes → invoke `planning` skill
+- EMIT logic wrong → invoke `gm-execute` skill
+- EMIT new unknown → invoke `planning` skill
+- VERIFY file broken → invoke `gm-emit` skill
+- VERIFY logic wrong → invoke `gm-execute` skill
+- VERIFY new unknown or wrong requirements → invoke `planning` skill
+
+**Runs until**: .prd empty AND git clean AND all pushes confirmed.
+
+## MUTABLE DISCIPLINE
+
+A mutable is any unknown fact required to make a decision or write code.
+- Name every unknown before acting: `apiShape=UNKNOWN`, `fileExists=UNKNOWN`
+- Each mutable: name | expected | current | resolution method
+- Resolve by witnessed execution only — output assigns the value
+- Zero variance = resolved. Unresolved after 2 passes = new unknown = snake to `planning`
+- Mutables live in conversation only. Never written to files.
+
+## CODE EXECUTION
+
+**exec:<lang> is the only way to run code.** Bash tool body: `exec:<lang>\n<code>`
+
+Languages: `exec:nodejs` (default) | `exec:bash` | `exec:python` | `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')`
+- Only `git` runs directly in Bash. `Bash(node/npm/npx/bun)` = violations.
+
+**Background tasks** (auto-backgrounded after 15s):
+```
+exec:sleep
+<task_id> [seconds]
 ```
-                    ┌─────────────────────────────────────────┐
-                    ↓  snake: requirements changed            │
-START → [PLAN] → [EXECUTE] → [EMIT] → [VERIFY] → [COMPLETE]  │
-           ↑         ↑          │         │                   │
-           │         │          │ snake:  │ snake:            │
-           │         └──────────┘ pre-    │ verify            │
-           │           snake:    emit     │ reveals           │
-           │           mutable   fails    │ file issues       │
-           │           unresolvable       └──→ [EMIT]         │
-           │                                                   │
-           └───────────────────────────────────────────────────┘
-                        snake: .prd incomplete
+```
+exec:status
+<task_id>
+```
+```
+exec:close
+<task_id>
 ```
 
-**FORWARD TRANSITIONS (ladders)**:
-- START → invoke `planning` skill
-- PLAN → EXECUTE: .prd written → invoke `gm-execute` skill
-- EXECUTE → EMIT: all mutables resolved → invoke `gm-emit` skill
-- EMIT → VERIFY: all gates pass → invoke `gm-complete` skill
-- VERIFY → COMPLETE: .prd empty + git clean → DONE
-- COMPLETE → EXECUTE: .prd items remain → invoke `gm-execute` skill (next wave)
-
-**BACKWARD TRANSITIONS (snakes)**:
-- EXECUTE → PLAN: unknowns discovered that require .prd restructure → invoke `planning` skill
-- EMIT → EXECUTE: pre-emit tests fail, need more hypothesis testing → invoke `gm-execute` skill
-- EMIT → PLAN: scope changed, .prd items need rework → invoke `planning` skill
-- VERIFY → EMIT: end-to-end reveals broken files → invoke `gm-emit` skill to fix + re-validate
-- VERIFY → EXECUTE: end-to-end reveals logic errors, not file errors → invoke `gm-execute` skill
-- VERIFY → PLAN: requirements fundamentally changed → invoke `planning` skill
+**Runner management** (the runner itself is a PM2 process named `gm-exec-runner`):
+```
+exec:runner
+start|stop|status
+```
 
-## MUTABLE DISCIPLINE
+`exec:runner start` launches a single PM2 process (`gm-exec-runner`) that hosts all execution as worker threads inside it. Individual `exec:<lang>` calls are worker threads — they do NOT appear as separate entries in `pm2 list`. Only the runner process is visible. Use `exec:runner status` to check it.
 
-- Task start: 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. Trigger snake back to EXECUTE or PLAN. Never narrate.
-- State-tracking mutables live in conversation only. Never written to files.
+## CODEBASE EXPLORATION
 
-## SKILL REGISTRY
+```
+exec:codesearch
+<natural language description>
+```
 
-**`planning`** — PRD construction. Invoke at START and on any snake back to PLAN.
-**`gm-execute`** — EXECUTE phase. Invoke entering EXECUTE or on snake back from EMIT/VERIFY.
-**`gm-emit`** — EMIT phase. Invoke when all EXECUTE mutables resolved, or on snake back from VERIFY.
-**`gm-complete`** — VERIFY/COMPLETE. Invoke after EMIT gates pass.
-**`code-search`** — Semantic code discovery. Invoke inside EXECUTE for all exploration.
-**`agent-browser`** — Browser automation. Invoke inside EXECUTE for all browser work.
-**`process-management`** — PM2 lifecycle. Invoke inside EXECUTE for all servers/workers/daemons.
-**`exec:<lang>`** — Bash tool: `exec:nodejs` | `exec:bash` | `exec:python` | `exec:typescript` | `exec:go` | `exec:rust` | `exec:java` | `exec:deno` | `exec:cmd`. Only git directly in bash. All else via exec interception.
+Alias: `exec:search`. Glob, Grep, Read-for-discovery, Explore, WebSearch = blocked.
 
-## PRD RULES
+## BROWSER AUTOMATION
+
+Invoke `agent-browser` skill. Escalation — exhaust each before advancing:
+1. `exec:agent-browser\n<js>` — query DOM/state via JS
+2. `agent-browser` skill + `__gm` globals — instrument and capture
+3. navigate/click/type — only when real events required
+4. screenshot — last resort only
+
+## SKILL REGISTRY
 
-.prd created before any work. Dependency graph. Waves of ≤3 independent items. Empty = all work complete. Path: exactly `./.prd`. Valid JSON. Snake back to `planning` if items need restructuring.
+**`planning`** — Mutable discovery and .prd construction. Invoke at start and on any new unknown.
+**`gm-execute`** — Resolve all mutables via witnessed execution.
+**`gm-emit`** — Write files to disk when all mutables resolved.
+**`gm-complete`** — End-to-end verification and git enforcement.
+**`agent-browser`** — Browser automation. Invoke inside EXECUTE for all browser/UI work.
 
 ## CONSTRAINTS
 
-**Tier 0**: immortality, no_crash, no_exit, ground_truth_only, real_execution
+**Tier 0**: no_crash, no_exit, ground_truth_only, real_execution
 **Tier 1**: max_file_lines=200, hot_reloadable, checkpoint_state
 **Tier 2**: no_duplication, no_hardcoded_values, modularity
 **Tier 3**: no_comments, convention_over_code
 
-**Never**: `Bash(node/npm/npx/bun)` — use exec:<lang> | skip planning | orphaned PM2 | independent items sequentially | screenshot before JS
+**Never**: `Bash(node/npm/npx/bun)` | skip planning | sequential independent items | screenshot before JS exhausted | narrate past unresolved mutables
 
-**Always**: invoke phase skill at every transition | snake back when blocked | ground truth | witnessed verification | keep going until .prd empty and git clean
+**Always**: invoke named skill at every transition | snake to planning on any new unknown | witnessed execution only | keep going until .prd empty and git clean

package/skills/gm-complete/SKILL.md

@@ -1,85 +1,97 @@
 ---
 name: gm-complete
-description: VERIFY and COMPLETE phase. End-to-end system verification, git enforcement, completion gate. Invoke after EMIT gates pass. Snake back to EMIT or EXECUTE if verification reveals failures.
+description: VERIFY and COMPLETE phase. End-to-end system verification and git enforcement. Any new unknown triggers immediate snake back to planning — restart chain.
 ---
 
 # GM COMPLETE — Verification and Completion
 
-You are in the **VERIFY → COMPLETE** phase. Files are written. Now prove the whole system works and enforce git discipline.
+You are in the **VERIFY → COMPLETE** phase. Files are written. Prove the whole system works end-to-end. Any new unknown = snake to `planning`, restart chain.
 
 **GRAPH POSITION**: `PLAN → EXECUTE → EMIT → [VERIFY → COMPLETE]`
-- **Entry chain**: prompt-submit hook → `gm` skill → `planning` → `gm-execute` → `gm-emit` → `gm-complete` (here).
+- **Entry**: All EMIT gates passed. Entered from `gm-emit`.
 
 ## TRANSITIONS
 
-**FORWARD (ladders)**:
-- .prd items remain → invoke `gm-execute` skill for next wave (new items unblocked)
+**FORWARD**:
+- .prd items remain → invoke `gm-execute` skill (next wave)
 - .prd empty + git clean + all pushed → COMPLETE
 
-**BACKWARD (snakes) — when to leave this phase**:
-- End-to-end reveals broken file (wrong output, crash, bad structure) → snake back: invoke `gm-emit` skill, fix and re-verify the file, return here
-- End-to-end reveals logic error not a file issue (wrong algorithm, missing step) → snake back: invoke `gm-execute` skill, re-resolve mutables, re-emit, return here
-- End-to-end reveals requirements were wrong → snake back: invoke `planning` skill, revise .prd, restart cycle
+**BACKWARD**:
+- Verification reveals broken file output → invoke `gm-emit` skill, fix, re-verify, return
+- Verification reveals logic error → invoke `gm-execute` skill, re-resolve, re-emit, return
+- Verification reveals new unknown → invoke `planning` skill, restart chain
+- Verification reveals requirements wrong → invoke `planning` skill, restart chain
 
-**WHEN TO SNAKE TO EMIT**: output is wrong but the logic was right — file needs rewriting
-**WHEN TO SNAKE TO EXECUTE**: algorithm is wrong — needs re-debugging before re-writing
-**WHEN TO SNAKE TO PLAN**: requirements changed or were misunderstood
+**TRIAGE on failure**: broken file output → snake to `gm-emit` | wrong logic → snake to `gm-execute` | new unknown or wrong requirements → snake to `planning`
+
+**RULE**: Any surprise = new unknown = snake to `planning`. Never patch around surprises.
 
 ## MUTABLE DISCIPLINE
 
-- `witnessed_execution=UNKNOWN` until real end-to-end run produces witnessed output
-- `git_clean=UNKNOWN` until `git status --porcelain` returns empty
-- `git_pushed=UNKNOWN` until `git rev-list --count @{u}..HEAD` returns 0
+- `witnessed_e2e=UNKNOWN` until real end-to-end run produces witnessed output
+- `git_clean=UNKNOWN` until `exec:bash\ngit status --porcelain` returns empty
+- `git_pushed=UNKNOWN` until `exec:bash\ngit rev-list --count @{u}..HEAD` returns 0
 - `prd_empty=UNKNOWN` until .prd has zero items
 
-All four must resolve to KNOWN before COMPLETE. Any UNKNOWN = absolute barrier. Trigger a snake if stuck.
+All four must resolve to KNOWN before COMPLETE. Any UNKNOWN = absolute barrier.
 
 ## END-TO-END VERIFICATION
 
-Run the real system. Witness it working with real data and real interactions.
+Run the real system with real data. Witness actual output.
 
-Verification = witnessed system output. NOT verification: marker files, docs updates, status text, saying done, screenshots alone.
+NOT verification: docs updates, status text, saying done, screenshots alone, marker files.
 
-- `exec:nodejs` with real imports and real data — witness success paths and failure paths
-- For browser/UI: `agent-browser` skill with real workflows
-- Dual-side: server + client features require both `exec:nodejs` AND `agent-browser`
+```
+exec:nodejs
+const { fn } = await import('/abs/path/to/module.js');
+console.log(await fn(realInput));
+```
 
-If verification fails: identify whether it's a file issue (→ snake to EMIT) or logic issue (→ snake to EXECUTE).
+For browser/UI: invoke `agent-browser` skill with real workflows. Server + client features require both exec:nodejs AND agent-browser. After every success: enumerate what remains — never stop at first green.
 
-## TOOL REFERENCE
+## CODE EXECUTION
 
-**`exec:<lang>`** — Bash tool: `exec:<lang>\n<code>`. `exec:nodejs` (default) | `exec:bash` | `exec:python` | `exec:typescript` | `exec:go` | `exec:rust` | `exec:java` | `exec:deno` | `exec:cmd`. Only git directly in bash.
+**exec:<lang> is the only way to run code.** Bash tool body: `exec:<lang>\n<code>`
 
-**`agent-browser`** — Invoke `agent-browser` skill. Escalation: (1) `exec:agent-browser\n<js>` → (2) skill + `__gm` globals → (3) navigate/click → (4) screenshot last resort.
+`exec:nodejs` (default) | `exec:bash` | `exec:python` | `exec:typescript` | `exec:go` | `exec:rust` | `exec:java` | `exec:deno` | `exec:cmd`
 
-**`process-management`** — Invoke `process-management` skill. Clean up all processes before COMPLETE. Orphaned PM2 = gate violation.
+Only git in bash directly. Background tasks: `exec:sleep\n<id>`, `exec:status\n<id>`, `exec:close\n<id>`. Runner: `exec:runner\nstart|stop|status`. All activity visible in `pm2 list` and `pm2 monit` in user terminal.
 
-## GIT ENFORCEMENT
+## CODEBASE EXPLORATION
 
-All changes committed AND pushed before COMPLETE.
+```
+exec:codesearch
+<natural language description>
+```
 
-1. `exec:bash\ngit status --porcelain` → must be empty
-2. `exec:bash\ngit rev-list --count @{u}..HEAD` → must be 0
-3. If not: `git add -A` → `git commit -m "..."` → `git push` → re-verify both
+## GIT ENFORCEMENT
 
-Local commit without push ≠ complete.
+```
+exec:bash
+git status --porcelain
+```
+Must return empty.
 
-## COMPLETION DEFINITION
+```
+exec:bash
+git rev-list --count @{u}..HEAD
+```
+Must return 0. If not: stage → commit → push → re-verify. Local commit without push ≠ complete.
 
-All of: witnessed end-to-end execution | every failure path debugged | `user_steps_remaining=0` | .prd empty | git clean and pushed | all processes cleaned up
+## COMPLETION DEFINITION
 
-Do not stop when it first works. Enumerate what remains after every success. Execute all remaining items.
+All of: witnessed end-to-end output | all failure paths exercised | .prd empty | git clean and pushed | `user_steps_remaining=0`
 
 ## CONSTRAINTS
 
-**Never**: claim done without witnessed execution | uncommitted changes | unpushed commits | .prd items remaining | orphaned processes | handoffs to user | stop at first green
+**Never**: claim done without witnessed output | uncommitted changes | unpushed commits | .prd items remaining | stop at first green | absorb surprises silently
 
-**Always**: witness end-to-end | git commit + push + verify | empty .prd before done | clean processes | enumerate remaining after every success | snake back on failure
+**Always**: triage failure before snaking | witness end-to-end | snake to planning on any new unknown | enumerate remaining after every success
 
 ---
 
-**→ FORWARD**: .prd items remain → invoke `gm-execute` skill for next wave.
+**→ FORWARD**: .prd items remain → invoke `gm-execute` skill.
 **→ DONE**: .prd empty + git clean → COMPLETE.
-**↩ SNAKE to EMIT**: file broken → invoke `gm-emit` skill.
+**↩ SNAKE to EMIT**: file output wrong → invoke `gm-emit` skill.
 **↩ SNAKE to EXECUTE**: logic wrong → invoke `gm-execute` skill.
-**↩ SNAKE to PLAN**: requirements wrong → invoke `planning` skill.
+**↩ SNAKE to PLAN**: new unknown or wrong requirements → invoke `planning` skill, restart chain.

package/skills/gm-emit/SKILL.md

@@ -1,88 +1,101 @@
 ---
 name: gm-emit
-description: EMIT phase. Pre-emit debugging, file writing, post-emit verification. Invoke when all EXECUTE mutables resolved. Snake back from VERIFY if files need fixes.
+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 — Writing and Verifying Files
 
-You are in the **EMIT** phase. Every mutable was resolved in EXECUTE. Now prove the write is correct, write, then confirm from disk.
+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`
-- **Entry chain**: prompt-submit hook → `gm` skill → `planning` → `gm-execute` → `gm-emit` (here). Also entered via snake from VERIFY.
+- **Entry**: All .prd mutables resolved. Entered from `gm-execute` or via snake from VERIFY.
 
 ## TRANSITIONS
 
-**FORWARD (ladders)**:
-- All gates pass simultaneously → invoke `gm-complete` skill
+**FORWARD**: All gate conditions true simultaneously → invoke `gm-complete` skill
 
-**BACKWARD (snakes) — when to leave this phase**:
-- Pre-emit debugging reveals logic error not caught in EXECUTE → snake back: invoke `gm-execute` skill, re-resolve the broken mutable, return here
-- Post-emit verification shows disk output differs from expected → fix in this phase immediately, do not advance, re-run verification
-- Scope changed mid-emit, .prd items no longer accurate → snake back: invoke `planning` skill to revise .prd
-- From VERIFY: end-to-end reveals broken file → snake back here, fix file, re-verify post-emit, then re-advance to VERIFY
+**SELF-LOOP**: Post-emit variance with known cause → fix immediately, re-verify, do not advance until zero variance
 
-**WHEN TO SNAKE TO EXECUTE**: logic is wrong, needs re-debugging before re-writing
-**WHEN TO SNAKE TO PLAN**: requirements changed, .prd items need restructure
-**WHEN TO STAY HERE**: file written but post-emit verification fails → fix immediately, re-verify
+**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. Pre-emit run = expected value. Post-emit run = current value. Zero variance required. Any unresolved gate = absolute barrier. State-tracking mutables 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`.
+
+## CODE EXECUTION
+
+**exec:<lang> is the only way to run code.** Bash tool body: `exec:<lang>\n<code>`
+
+`exec:nodejs` (default) | `exec:bash` | `exec:python` | `exec:typescript` | `exec:go` | `exec:rust` | `exec:java` | `exec:deno` | `exec:cmd`
+
+Only git in bash directly. `Bash(node/npm/npx/bun)` = violations. File writes via exec:nodejs + require('fs').
 
 ## PRE-EMIT DEBUGGING (before writing any file)
 
 1. Import actual module from disk via `exec:nodejs` — witness current on-disk behavior
-2. Run proposed logic in isolation WITHOUT writing any file — witness output with real inputs
-3. Debug failure paths with real error inputs
-4. For browser code: inject `__gm` globals, run interactions, dump captures, verify
+2. Run proposed logic in isolation WITHOUT writing — witness output with real inputs
+3. Debug failure paths with real error inputs — record expected values
 
-`exec:nodejs\nconst { fn } = await import('/abs/path')` — never rewrite logic inline.
+```
+exec:nodejs
+const { fn } = await import('/abs/path/to/module.js');
+console.log(await fn(realInput));
+```
 
-Pre-emit run failing → snake back to `gm-execute` skill, do not write.
+Pre-emit revealing unexpected behavior → new unknown → snake to `planning`.
 
 ## WRITING FILES
 
-Use `exec:nodejs` with `require('fs')`. Write only when every gate mutable is `resolved=true` simultaneously.
+`exec:nodejs` with `require('fs')`. Write only when every gate mutable is `resolved=true` simultaneously.
 
 ## POST-EMIT VERIFICATION (immediately after writing)
 
-1. Load actual modified file from disk via real import — not in-memory version
-2. Output must match pre-emit run exactly — any variance = regression
+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. Variance → fix immediately, re-verify. Never advance with variance.
+4. Known variance → fix and re-verify | Unknown variance → snake to `planning`
 
-## GATE CONDITIONS (all must be true simultaneously)
+## GATE CONDITIONS (all true simultaneously before advancing)
 
-- Pre-emit run passed with real inputs and real error inputs
-- Post-emit verification matches pre-emit run exactly
+- 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
-- Docs-code sync: CLAUDE.md reflects actual behavior
+- Files ≤200 lines, no duplicate code, no comments, no hardcoded values
+- CLAUDE.md reflects actual behavior
+
+## CODEBASE EXPLORATION
 
-## TOOL REFERENCE
+```
+exec:codesearch
+<natural language description>
+```
 
-**`exec:<lang>`** — Bash tool: `exec:<lang>\n<code>`. `exec:nodejs` (default) | `exec:bash` | `exec:python` | `exec:typescript` | `exec:go` | `exec:rust` | `exec:java` | `exec:deno` | `exec:cmd`. Only git directly in bash.
+Alias: `exec:search`. Glob, Grep, Explore = blocked.
 
-**`agent-browser`** — Invoke `agent-browser` skill. Escalation: (1) `exec:agent-browser\n<js>` → (2) skill + `__gm` globals → (3) navigate/click → (4) screenshot last resort.
+## BROWSER DEBUGGING
 
-**`code-search`** — Invoke `code-search` skill. Glob/Grep/Explore blocked.
+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)
 
-File ≤200 lines | No duplication | Pre-emit run passed | No mocks | No comments | Docs match | All spotted issues fixed immediately
+File ≤200 lines | No duplication | Pre-emit passed | No mocks | No comments | Docs match | All spotted issues fixed
 
 ## CONSTRAINTS
 
-**Never**: write before pre-emit run passes | advance with post-emit variance | skip doc sync | defer spotted issues | 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 debug before writing | post-emit verify after writing | dual-side for full-stack | fix immediately | snake back when blocked
+**Always**: pre-emit debug before writing | post-emit verify from disk | snake to planning on any new unknown | fix immediately
 
 ---
 
 **→ FORWARD**: All gates pass → invoke `gm-complete` skill.
-**↩ SNAKE to EXECUTE**: logic wrong → invoke `gm-execute` skill.
-**↩ SNAKE to PLAN**: scope changed → invoke `planning` skill.
-**↩ SNAKE from VERIFY**: file broken → fix here, re-verify, re-advance.
+**↺ 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,57 +1,70 @@
 ---
 name: gm-execute
-description: EXECUTE phase. Hypothesis proving, chain decomposition, import-based debugging, browser protocols, ground truth enforcement. Invoke when entering EXECUTE or snaking back from EMIT/VERIFY.
+description: EXECUTE phase. Resolve all mutables via witnessed execution. Any new unknown triggers immediate snake back to planning — restart chain from PLAN.
 ---
 
 # GM EXECUTE — Resolving Every Unknown
 
-You are in the **EXECUTE** phase. Every mutable must resolve to KNOWN via witnessed execution before advancing.
+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`
-- **Entry chain**: prompt-submit hook → `gm` skill → `planning` → `gm-execute` (here). Also entered via snake from EMIT or VERIFY.
+- **Entry**: .prd exists with all unknowns named. Entered from `planning` or via snake from EMIT/VERIFY.
 
 ## TRANSITIONS
 
-**FORWARD (ladders)**:
-- All mutables resolved to KNOWN → invoke `gm-emit` skill
+**FORWARD**: All mutables KNOWN → invoke `gm-emit` skill
 
-**BACKWARD (snakes) — when to re-enter here**:
-- From EMIT: pre-emit debugging reveals logic error, hypothesis was wrong → snake back, re-run execution with corrected approach
-- From VERIFY: end-to-end debugging reveals runtime failure not caught in execution → snake back, re-execute with real system state
-- Self-loop: mutables still UNKNOWN after a pass → re-invoke `gm-execute` with broader debug scope. Never add stages.
+**SELF-LOOP**: Mutable still UNKNOWN after one pass → re-run with different angle (max 2 passes then snake)
 
-**WHEN TO SNAKE BACK TO PLAN instead**: discovered hidden dependencies that require .prd restructure → invoke `planning` skill
-
-**Sub-skills** (invoke from within EXECUTE):
-- Code exploration → invoke `code-search` skill
-- Browser/UI debugging → invoke `agent-browser` skill
-- Servers/workers/daemons → invoke `process-management` skill
+**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 every unknown as a named mutable. Each: name, expected value, current value, resolution method. Execute → witness → assign → compare → zero variance = resolved. Unresolved = absolute barrier. Never narrate past an unresolved mutable. Trigger a snake if stuck.
+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.
 
-## EXECUTION DENSITY
+## CODE EXECUTION
 
-Each run ≤15s, packed with every related hypothesis. Group all related unknowns into one run. Never one idea per run. Witnessed output = ground truth. Narrated assumption = nothing.
+**exec:<lang> is the only way to run code.** Bash tool body: `exec:<lang>\n<code>`
 
-**Parallel waves**: Launch ≤3 `gm:gm` subagents per wave via Task tool. Independent items simultaneously. Sequential execution of independent items = violation.
+`exec:nodejs` (default) | `exec:bash` | `exec:python` | `exec:typescript` | `exec:go` | `exec:rust` | `exec:c` | `exec:cpp` | `exec:java` | `exec:deno` | `exec:cmd`
 
-## CHAIN DECOMPOSITION
+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.
 
-Break every multi-step operation before running end-to-end:
-1. Number every distinct step (parse → validate → transform → write → confirm)
-2. Per step: input shape, output shape, success condition, failure condition
-3. Run step 1 in isolation → witness → assign mutable → proceed only when KNOWN
-4. Run step 2 with step 1's witnessed output. Repeat for each step.
-5. Debug adjacent pairs (1+2, 2+3...) for handoff correctness
-6. Only after all pairs pass: run full chain
+**Background tasks** (auto-backgrounded when execution exceeds 15s):
+```
+exec:sleep
+<task_id> [seconds]
+```
+```
+exec:status
+<task_id>
+```
+```
+exec:close
+<task_id>
+```
 
-Step failure → debug that step only, re-run from there. Never skip forward.
+**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>
+```
+
+Alias: `exec:search`. Glob, Grep, Read-for-discovery, Explore, WebSearch = blocked.
 
 ## IMPORT-BASED DEBUGGING
 
-Always import actual codebase modules. Never rewrite logic inline — that debugs your reimplementation, not the real code.
+Always import actual codebase modules. Never rewrite logic inline.
 
 ```
 exec:nodejs
@@ -61,41 +74,48 @@ console.log(await fn(realInput));
 
 Witnessed import output = resolved mutable. Reimplemented output = UNKNOWN.
 
-## TOOL REFERENCE
+## EXECUTION DENSITY
 
-**`exec:<lang>`** — THE ONLY WAY TO RUN CODE. Bash tool body: `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`. `cwd` sets directory. File I/O via exec:nodejs with require('fs'). Only git directly in bash.
+Pack every related hypothesis into one run. Each run ≤15s. Witnessed output = ground truth. Narrated assumption = nothing.
 
-`Bash(node ...)` `Bash(npm ...)` `Bash(npx ...)` `Bash(bun ...)` = violations. Use `exec:<lang>`.
+Parallel waves: ≤3 `gm:gm` subagents via Task tool — independent items simultaneously, never sequentially.
 
-**`code-search`** — Invoke `code-search` skill. MANDATORY for all exploration. Glob/Grep/Read/Explore/WebSearch blocked. Fallback: `bun x codebasesearch <query>`.
+## 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
 
-**`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.
+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.
+## BROWSER DEBUGGING
 
-## BROWSER DEBUGGING 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 DEBUGGING
-
-Backend via `exec:nodejs`, frontend via `agent-browser` + `__gm`. Neither substitutes the other. Single-side = UNKNOWN mutable = blocked gate.
-
 ## GROUND TRUTH
 
-Real services, real API responses, real timing. On discovering mocks/fakes/stubs: delete immediately, implement real paths. No .test.js/.spec.js files. No mock files. Delete on discovery.
+Real services, real data, real timing. Mocks/fakes/stubs = delete immediately. No .test.js/.spec.js. Delete on discovery.
 
 ## CONSTRAINTS
 
-**Never**: `Bash(node/npm/npx/bun/python)` | fake data | mock files | Glob/Grep/Explore for discovery | puppeteer/playwright | screenshot before JS exhausted | 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 | witness every hypothesis | delete mocks on discovery | fix immediately | snake back when blocked
+**Always**: witness every hypothesis | import real modules | snake to planning on any new unknown | fix immediately on discovery
 
 ---
 
 **→ FORWARD**: All mutables KNOWN → invoke `gm-emit` skill.
-**↩ SNAKE to EXECUTE**: hypothesis wrong → re-invoke `gm-execute` with corrected approach.
-**↩ SNAKE to PLAN**: .prd needs restructure → invoke `planning` 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,82 +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).
+- **Entry chain**: prompt-submit hook → `gm` skill → `planning` skill (here).
+- **Also entered**: any time a new unknown surfaces in EXECUTE, EMIT, or VERIFY.
 
 ## TRANSITIONS
 
-**FORWARD (ladders)**:
-- .prd written → invoke `gm-execute` skill to begin EXECUTE
+**FORWARD**:
+- No new mutables discovered in latest pass → .prd is complete → invoke `gm-execute` skill
 
-**BACKWARD (snakes) — when to return here**:
-- From EXECUTE: discovered unknowns require .prd restructure → re-invoke `planning` skill, revise .prd, re-enter EXECUTE
-- From EMIT: scope changed, current .prd items no longer match what needs to be done → re-invoke `planning` skill
-- From VERIFY: end-to-end reveals requirements were wrong → re-invoke `planning` skill, rewrite affected items
+**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
 
-**When to snake back to PLAN**: requirements changed | discovered hidden dependencies | .prd items are wrong/missing | scope expanded beyond current .prd
+**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
 
-## Purpose
+## WHAT PLANNING MEANS
 
-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, error conditions, boundary conditions, configuration variants, environment differences, backwards compatibility, rollback paths, verification steps.
+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
 
-Longer is better. Missing items means missing work.
+**Iterate until**: a full reasoning pass adds zero new items to .prd.
 
-## File Rules
+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
 
-Path: exactly `./.prd` in current working directory. No variants. Valid JSON.
+## .PRD SCHEMA
 
-## Item 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. **Status**: `pending` → `in_progress` → `completed`. **Effort**: `small` (<15min) | `medium` (<45min) | `large` (1h+). **Blocking/blockedBy**: bidirectional, every dependency explicit.
+**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.
 
-## Construction
+## EXECUTION WAVES
 
-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.
+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.
 
-## Execution
+## COMPLETION CRITERION
 
-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.
+.prd is ready when: one full reasoning pass produces zero new items AND all items have explicit acceptance criteria AND all dependencies are mapped.
 
-Never execute independent items sequentially. Never launch more than 3 at once.
-
-## Completion
-
-`.prd` must be empty at COMPLETE. Skip this skill if 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.
 
 ---
 
-**→ FORWARD**: .prd written → invoke `gm-execute` skill.
-**↩ SNAKE**: re-invoke `planning` if requirements change at any later 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/skills/code-search/SKILL.md

@@ -1,376 +0,0 @@
----
-name: code-search
-description: Semantic code search across the codebase. Returns structured results with file paths, line numbers, and relevance scores. Use for all code exploration, finding implementations, locating files, and answering codebase questions.
-category: exploration
-allowed-tools: Bash(bun x codebasesearch*)
-input-schema:
-  type: object
-  required: [prompt]
-  properties:
-    prompt:
-      type: string
-      minLength: 3
-      maxLength: 200
-      description: Natural language search query describing what you're looking for
-    context:
-      type: object
-      description: Optional context about search scope and restrictions
-      properties:
-        path:
-          type: string
-          description: Restrict search to this directory path (relative or absolute)
-        file-types:
-          type: array
-          items: { type: string }
-          description: Filter results by file extensions (e.g., ["js", "ts", "py"])
-        exclude-patterns:
-          type: array
-          items: { type: string }
-          description: Exclude paths matching glob patterns (e.g., ["node_modules", "*.test.js"])
-    filter:
-      type: object
-      description: Output filtering and formatting options
-      properties:
-        max-results:
-          type: integer
-          minimum: 1
-          maximum: 500
-          default: 50
-          description: Maximum number of results to return
-        min-score:
-          type: number
-          minimum: 0
-          maximum: 1
-          default: 0.5
-          description: Minimum relevance score (0-1) to include in results
-        sort-by:
-          type: string
-          enum: [relevance, path, line-number]
-          default: relevance
-          description: Result sort order
-    timeout:
-      type: integer
-      minimum: 1000
-      maximum: 30000
-      default: 10000
-      description: Search timeout in milliseconds (query returns partial results if exceeded)
-output-schema:
-  type: object
-  required: [status, results, meta]
-  properties:
-    status:
-      type: string
-      enum: [success, partial, empty, timeout, error]
-      description: Overall operation status
-    results:
-      type: array
-      description: Array of matching code locations
-      items:
-        type: object
-        required: [file, line, content, score]
-        properties:
-          file:
-            type: string
-            description: Absolute or relative file path to matched file
-          line:
-            type: integer
-            description: Line number where match occurs (1-indexed)
-          content:
-            type: string
-            description: The matched line or context snippet
-          score:
-            type: number
-            minimum: 0
-            maximum: 1
-            description: Relevance score where 1.0 is perfect match
-          context:
-            type: object
-            description: Surrounding context lines (optional)
-            properties:
-              before:
-                type: array
-                items: { type: string }
-                description: Lines before the match
-              after:
-                type: array
-                items: { type: string }
-                description: Lines after the match
-          metadata:
-            type: object
-            description: File and match metadata (optional)
-            properties:
-              language:
-                type: string
-                description: Programming language detected (js, ts, py, rs, go, etc.)
-              size:
-                type: integer
-                description: File size in bytes
-              modified:
-                type: string
-                format: date-time
-                description: Last modification timestamp
-    meta:
-      type: object
-      required: [query, count, duration_ms]
-      description: Query execution metadata
-      properties:
-        query:
-          type: string
-          description: Normalized query that was executed
-        count:
-          type: integer
-          description: Total matches found (before filtering)
-        filtered:
-          type: integer
-          description: Results returned (after filtering and limiting)
-        duration_ms:
-          type: integer
-          description: Execution time in milliseconds
-        scanned_files:
-          type: integer
-          description: Total files examined during search
-        timestamp:
-          type: string
-          format: date-time
-          description: When execution completed
-    errors:
-      type: array
-      description: Non-fatal errors that occurred (may appear alongside partial results)
-      items:
-        type: object
-        properties:
-          code:
-            type: string
-            enum: [TIMEOUT, INVALID_PATH, SCHEMA_VIOLATION, EXECUTION_FAILED]
-            description: Error classification
-          message:
-            type: string
-            description: Human-readable error description
-output-format: json
-error-handling:
-  timeout:
-    behavior: return-partial
-    description: Returns results collected before timeout with status=partial
-  invalid-input:
-    behavior: reject
-    description: Returns status=error with validation errors in errors array
-  empty-results:
-    behavior: return-empty
-    description: Returns status=empty with count=0, filtered=0, results=[]
-  execution-error:
-    behavior: return-error
-    description: Returns status=error with error details in errors array
----
-
-# Semantic Code Search
-
-Only use bun x codebasesearch for searching code, or execute some custom code if you need more than that, never use other cli tools to search the codebase. Search the codebase using natural language. Do multiple searches when looking for files, starting with fewer words and adding more if you need to refine the search. 102 file types are covered, returns results with file paths and line numbers.
-
-## Usage
-
-```bash
-bun x codebasesearch "your natural language query"
-```
-
-## Invocation Examples
-
-### Via Skill Tool (Recommended - Structured JSON Input)
-
-**Basic search**:
-```json
-{
-  "prompt": "where is authentication handled"
-}
-```
-
-**With filtering and limits**:
-```json
-{
-  "prompt": "database connection setup",
-  "filter": {
-    "max-results": 20,
-    "min-score": 0.7,
-    "sort-by": "path"
-  }
-}
-```
-
-**Scoped to directory with file type filter**:
-```json
-{
-  "prompt": "error logging middleware",
-  "context": {
-    "path": "src/middleware/",
-    "file-types": ["js", "ts"]
-  },
-  "timeout": 5000
-}
-```
-
-**Exclude patterns and narrow results**:
-```json
-{
-  "prompt": "rate limiter implementation",
-  "context": {
-    "exclude-patterns": ["*.test.js", "node_modules/*"]
-  },
-  "filter": {
-    "max-results": 10,
-    "min-score": 0.8
-  }
-}
-```
-
-### Legacy CLI Invocation (Still Supported)
-
-```bash
-bun x codebasesearch "where is authentication handled"
-bun x codebasesearch "database connection setup"
-bun x codebasesearch "how are errors logged"
-bun x codebasesearch "function that parses config files"
-bun x codebasesearch "where is the rate limiter"
-```
-
-## Output Examples
-
-### Success Response (Multiple Results)
-
-```json
-{
-  "status": "success",
-  "results": [
-    {
-      "file": "src/auth/handler.js",
-      "line": 42,
-      "content": "async function authenticateUser(credentials) {",
-      "score": 0.95,
-      "context": {
-        "before": [
-          "// Main authentication entry point",
-          ""
-        ],
-        "after": [
-          "  const { username, password } = credentials;",
-          "  const user = await db.users.findOne({ username });"
-        ]
-      },
-      "metadata": {
-        "language": "javascript",
-        "size": 2048,
-        "modified": "2025-03-10T14:23:00Z"
-      }
-    },
-    {
-      "file": "src/middleware/auth-middleware.js",
-      "line": 18,
-      "content": "export const requireAuth = (req, res, next) => {",
-      "score": 0.78,
-      "metadata": {
-        "language": "javascript",
-        "size": 1024,
-        "modified": "2025-03-10T14:20:00Z"
-      }
-    }
-  ],
-  "meta": {
-    "query": "authentication handled",
-    "count": 2,
-    "filtered": 2,
-    "duration_ms": 245,
-    "scanned_files": 87,
-    "timestamp": "2025-03-15T10:30:00Z"
-  }
-}
-```
-
-### Empty Results Response
-
-```json
-{
-  "status": "empty",
-  "results": [],
-  "meta": {
-    "query": "nonexistent pattern xyz123",
-    "count": 0,
-    "filtered": 0,
-    "duration_ms": 123,
-    "scanned_files": 87,
-    "timestamp": "2025-03-15T10:30:00Z"
-  }
-}
-```
-
-### Timeout Response (Partial Results)
-
-```json
-{
-  "status": "partial",
-  "results": [
-    {
-      "file": "src/a.js",
-      "line": 5,
-      "content": "function init() {",
-      "score": 0.92,
-      "metadata": { "language": "javascript", "size": 512 }
-    },
-    {
-      "file": "src/b.js",
-      "line": 12,
-      "content": "const setup = () => {",
-      "score": 0.85,
-      "metadata": { "language": "javascript", "size": 768 }
-    }
-  ],
-  "meta": {
-    "query": "expensive search pattern",
-    "count": 1847,
-    "filtered": 2,
-    "duration_ms": 10000,
-    "scanned_files": 45,
-    "timestamp": "2025-03-15T10:30:00Z"
-  },
-  "errors": [
-    {
-      "code": "TIMEOUT",
-      "message": "Search exceeded 10000ms limit. Returning partial results (2 of 1847 matches)."
-    }
-  ]
-}
-```
-
-### Error Response (Invalid Input)
-
-```json
-{
-  "status": "error",
-  "results": [],
-  "meta": {
-    "query": null,
-    "count": 0,
-    "filtered": 0,
-    "duration_ms": 50,
-    "scanned_files": 0,
-    "timestamp": "2025-03-15T10:30:00Z"
-  },
-  "errors": [
-    {
-      "code": "INVALID_PATH",
-      "message": "context.path='/nonexistent' does not exist"
-    },
-    {
-      "code": "SCHEMA_VIOLATION",
-      "message": "filter.max-results must be between 1 and 500, got 1000"
-    }
-  ]
-}
-```
-
-## Rules
-
-- Always use this first before reading files — it returns file paths and line numbers
-- Natural language queries work best; be descriptive about what you're looking for
-- Structured JSON output includes relevance scores and file paths for immediate navigation
-- Use returned file paths and line numbers to read full file context via Read tool
-- Results are pre-sorted by relevance (highest scores first) unless sort-by specifies otherwise
-- Timeout queries return partial results with status=partial — use if time-critical
-- Schema validation ensures valid input before execution — invalid args return error with details

package/skills/process-management/SKILL.md

@@ -1,83 +0,0 @@
----
-name: process-management
-description: PM2 process lifecycle. MANDATORY for all servers, workers, daemons. Invoke from gm-execute when any long-running process is needed. Return to gm-execute when done.
----
-
-# Process Management — PM2 Lifecycle
-
-You are managing long-running processes. Invoked from EXECUTE phase.
-
-**GRAPH POSITION**: Sub-skill of `gm-execute`. Invoked and returns.
-- **Entry**: `gm-execute` encounters server/worker/daemon requirement → invoke `process-management` skill
-- **Return**: Lifecycle task complete → return to `gm-execute` to continue EXECUTE phase
-- **Snake**: Process fails to start or behaves incorrectly → debug here, then return to `gm-execute` with witnessed status
-
-## TRANSITIONS
-
-**RETURN (normal)**:
-- Process started and confirmed running → return to `gm-execute`
-- Process stopped/cleaned up → return to `gm-execute`
-
-**SNAKE (failure)**:
-- Process crashes on start → debug logs here, surface error to `gm-execute`, let EXECUTE phase decide whether to snake to PLAN
-- Port conflict detected → resolve here, then return to `gm-execute`
-- Orphans found → clean up here, then return to `gm-execute`
-
-## PRE-CHECK (mandatory before any start)
-
-```
-exec:nodejs
-const { execSync } = require('child_process');
-console.log(execSync('npx pm2 list', { encoding: 'utf8' }));
-```
-
-If process already running with same name → stop and delete first.
-If different process using same port → stop it first.
-Never start a duplicate. Never stack processes.
-
-## START
-
-```
-exec:nodejs
-const { execSync } = require('child_process');
-execSync('npx pm2 start <file> --name <name> --watch --no-autorestart', { stdio: 'inherit' });
-```
-
-- `--watch`: hot reload on file changes
-- `--no-autorestart`: prevents infinite crash loops
-- Always name every process explicitly
-
-## STATUS AND LOGS
-
-```
-exec:nodejs
-const { execSync } = require('child_process');
-console.log(execSync('npx pm2 list', { encoding: 'utf8' }));
-console.log(execSync('npx pm2 logs <name> --lines 50 --nostream', { encoding: 'utf8' }));
-```
-
-## STOP AND CLEANUP
-
-Always clean up when work is done. Orphaned processes = gate violation in COMPLETE.
-
-```
-exec:nodejs
-const { execSync } = require('child_process');
-execSync('npx pm2 stop <name>', { stdio: 'inherit' });
-execSync('npx pm2 delete <name>', { stdio: 'inherit' });
-```
-
-## ORPHAN DETECTION
-
-Run `npx pm2 list` — any process not started in the current session = orphan. Delete immediately.
-
-## CONSTRAINTS
-
-**Never**: start without pre-check | direct node/bun/python for servers (use PM2) | leave orphans | skip cleanup before COMPLETE | `Bash(pm2 ...)` — use exec:nodejs with execSync
-
-**Always**: pre-check before start | name every process | watch enabled | autorestart disabled | delete on session end
-
----
-
-**→ RETURN**: Lifecycle task complete → return to `gm-execute` skill.
-**↩ SNAKE**: Process failure → debug logs, surface to `gm-execute`, let EXECUTE decide next step.