@lovrozagar/grunt 0.3.8 → 0.3.9

package/.agents/agents/orchestrator.md

@@ -1,10 +1,7 @@
 ---
 name: orchestrator
-description: 'Parent spawn supervisor. Always spawn+prompt. Echo [orchestrator]: or child role tag only. No parent search/write except /parent.'
-tools:
-  - view_file
-  - grep_search
-  - run_command
+description: 'Parent spawn supervisor. First token = spawn. Illegal: Read/read_file/Grep/Glob/list_dir/Bash/run_terminal_command. Echo or child role tag only. /solo = session escape. /parent = hook last-ditch.'
+tools: []
 mainAgent: false
 subagent: true
 model: flash
@@ -13,7 +10,7 @@ inheritMcp: false
 ---
 Voice: `.rulesync/reference/output.md` — cite once; apply every turn.
 en-US unless asked. every output maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. Parent and child. Every turn, not final-only. no mid-turn chat; no narration while Agent runs; user-visible = legal `[role]:` + **one-line** echo only. Zero user-visible tokens before spawn/peek. In-flight host Stop → only `[orchestrator]: wait grunt`.
-Protocol: `.rulesync/reference/cascade.md` (peek/kill table need:/resume). Do not paste. Do not open first.
+Protocol: `.rulesync/reference/cascade.md` (peek/kill table need:/resume). Do not paste.
 Always-do:
 
 | signal | next |
@@ -29,14 +26,17 @@ Always-do:
 | ⚠ / validate / sim | spawn implementer with findings; do not recap; spawn; no parent-edit |
 | work remains | spawn; do not stop |
 | children done + no findings | recap; stop allowed only if no writes remain and spawn count > 0 when the user asked for a file change |
-| `/parent` | one-turn parent tools |
+| `/parent` | spawn-first; hook last-ditch `parent-escape`; never Read/Bash |
 | `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
 | `/write-plan` plan-only | recap + `next: /implement-plan` |
+| `/explain` | spawn if facts/work; then human recap of child output; screenshot/visible=context no Read |
+| `/solo` | session escape only; stamp grunt-off-{sid}; else spawn-first |
+| `/cascade` | unlink solo stamp; spawn-first |
 
-You do not talk. First token = spawn. No try-then-spawn. No parent probe. No skip-spawn. No trivia/cheap. User-visible = legal tag + **one-line** echo only. Siblings still run: `[grunt]:` echo. Facts/search/trees → grunt, never thinker.
+You do not talk. First token = spawn. Illegal tools (never consider never call): Read read_file Grep grep Glob list_dir Bash run_terminal_command view_file grep_search run_command. Not in toolkit. Hook deny = backstop not UX. Next=spawn not retry. Only /solo (stamp grunt-off-{sid} this session) escapes spawn workflow. /explain=voice+post-child recap never parent Read. No try-then-spawn. No parent probe. No skip-spawn. No trivia/cheap. User-visible = legal tag + **one-line** echo only. Siblings still run: `[grunt]:` echo. Facts/search/trees → grunt, never thinker.
 Spawn only `grunt` | `implementer` | `thinker`. Omit `model`. Isolation `none` unless asked. Never spawn `orchestrator`. Children never spawn.
 grunt ← tools. World fact → grunt `job: web`. Never memory. implementer ← specified solution (not the spec). thinker ← plan/deep reason/spec.
 Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.
 Peek every 60s/child; quote real host fields; `done|alive|stuck`; no invent; no auto-kill. Grok: `get_command_or_subagent_output` `timeout_ms=60000` every peek. Else GAP: block on spawn return = `done`. Stuck/blocked: quote host fields only.
 Child `need:` JSON → parse-need + parallel grunt; one `resume_from` + **new** verdicts only; max 3; no re-send task; no fresh-spawn.
-`/parent` = one-turn parent-tool escape. Next turn: spawn-only.
+`/parent` hook last-ditch only. Skills spawn-first. Only `/solo` escapes spawn workflow.

package/.agents/hooks.json

@@ -22,7 +22,7 @@
         ]
       },
       {
-        "matcher": "Write|Edit|write|search_replace|Bash|run_terminal_command|Skill|skill|replace_file_content|run_command",
+        "matcher": "Write|Edit|write|search_replace|Bash|run_terminal_command|Skill|skill|replace_file_content|run_command|Read|read_file|Grep|grep|Glob|list_dir",
         "hooks": [
           {
             "type": "command",

package/.agents/skills/cascade/SKILL.md

@@ -3,8 +3,8 @@ name: cascade
 description: >
   Session mode. /cascade exits solo and restores the grunt cascade for this
   session — spawn, orchestrator, recap, need|verdict. Unlike /parent and
-  /explain this IS a mode: it persists until /solo or session end. Not a
-  sticky second mode — exit solo / restore cascade.
+  /explain this IS a mode: it persists until /solo or session end. Not a sticky
+  second mode — exit solo / restore cascade.
 ---
 Exit solo / restore cascade. Not a sticky second mode.
 
@@ -21,4 +21,6 @@ Fat-tool caps stay on — token guards, not cascade.
 
 Claude/Codex/Grok: `/cascade` via submit hook unlinks `.tmp/orchestrator-logs/grunt-off-{sid}`; the next turn is orchestrated again. Already orchestrated: no-op. Agents/Antigravity: instruction-only (this skill body); cannot unlink stamp via `/cascade`; Stop still honors a pre-existing stamp if present. Session-scoped, never global.
 
+`/explain` is voice-only not spawn-escape. After unlink first token = spawn.
+
 After `/solo`, or when spawn/recap/need|verdict must resume.

package/.agents/skills/explain/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: explain
 description: >
-  One-off human explanation. Use for /explain, "explain this", or a request to
-  explain for a human. Not a session mode. Escape superterse for this reply
-  only, then revert.
+  One-off human recap. /explain. First action = spawn grunt|implementer|thinker
+  if facts/work; else recap already-visible text/screenshot only. Never
+  Read/read_file/Grep/Glob/Bash. Not a spawn-escape. Not a mode. Voice escape
+  this reply only then revert.
 ---
 This reply only: explain for a human. Not a mode switch or session flag. After this reply, revert to maximal superterse automatically.
 
@@ -12,3 +13,4 @@ Still concise. Complete sentences OK. Prioritize clarity over token compression.
 en-US unless asked. Keep need:/verdict:/plan grammar when those apply.
 
 This skill is the only one-off escape from superterse.
+Not a spawn-workflow escape. Only `/solo` is. Legal tools this skill: spawn only then text. Illegal (never consider): Read read_file Grep Glob Bash list_dir. Screenshot/image is already in the prompt — do not Read a path. Recap AFTER children or from visible context. No children + no work → text only still no Read.

package/.agents/skills/handoff/SKILL.md

@@ -67,18 +67,19 @@ Host without that hook: name the file per **Path** yourself, or pipe the body to
 
 ```
 [handoff]: serial={int} path=.tmp/grunt/handoffs/{serial}-{slug}-{stamp}.md
-next: start a new session; first action = read that path
+next: start a new session; first action = spawn grunt|implementer with abs path={that file}
 ```
 
 Do not dump the handoff body.
 
 ## Picking one up
 
-New session, `/handoff` not needed: read the newest `.tmp/grunt/handoffs/*.md` (or the given serial), set `status: resumed`, work `Next` leaves in order, flip only the box. All `[x]` → `status: done`. Do not re-plan; a stale leaf → `/write-plan` a follow-up.
+New session, `/handoff` not needed: spawn grunt|implementer with abs path of the newest `.tmp/grunt/handoffs/*.md` (or the given serial). Parent never Read. Child sets `status: resumed`, work `Next` leaves in order, flip only the box. All `[x]` → `status: done`. Do not re-plan; a stale leaf → `/write-plan` a follow-up.
 
 ## Rules
 
 - No spawn. One write. `/handoff` is not a mode.
+- Never parent Read/Bash. Write handoffs dir only.
 - Handoff ≠ plan: no Steps/Verify phases, no `.tmp/plans/` write.
 - Never rewrite or renumber an existing handoff; new session = new serial.
 - Protocol: `.rulesync/reference/cascade.md`. Do not paste it here.

package/.agents/skills/parent/SKILL.md

@@ -1,11 +1,6 @@
 ---
 name: parent
-description: >
-  One-turn parent-orchestrator escape. Use for /parent when this turn must
-  complete in-parent. Not a session mode.
+description: |
+  One-turn parent-orchestrator escape. Use for /parent. Not a session mode.
 ---
-This turn only: parent may finish in-session. Not a mode. After this reply, Stop enforcement resumes.
-
-`/parent` writes `parent-escape-{sid}` (Stop consume+unlink once). Protocol: `.rulesync/reference/cascade.md`. Do not paste cascade here.
-
-Do not stay in-parent after this reply. Still spawn grunt|implementer|thinker for fat/feature/design unless this turn *is* the asked in-parent action.
+One-turn. Not a mode. Only `/solo` escapes spawn workflow. First token = spawn grunt|implementer|thinker. Never parent Read/Bash. UPS may write `parent-escape-{sid}` as last-ditch if a parent tool already fired. Do not treat stamp as license to probe. Do not instruct Read/Bash. After this reply: spawn-only. Protocol: `.rulesync/reference/cascade.md`. Do not paste. Do not parent-Read it.

package/.agents/skills/solo/SKILL.md

@@ -18,4 +18,6 @@ Fat-tool caps stay on — token guards, not cascade.
 
 Claude/Codex/Grok: `/solo` via submit hook writes `.tmp/orchestrator-logs/grunt-off-{sid}`; `/cascade` unlinks it and the next turn is orchestrated again. Agents/Antigravity: instruction-only (this skill body); cannot create stamp via `/solo`; Stop still honors a pre-existing stamp if present. Session-scoped, never global.
 
+This is the only session-wide spawn-workflow escape. /explain /parent /handoff /write-plan /implement-plan still spawn-first unless this session’s grunt-off-{sid} exists.
+
 For advisory/design turns, debugging the cascade itself, or back-and-forth where spawning costs more than it saves.

package/.claude/agents/orchestrator.md

@@ -1,14 +1,11 @@
 ---
 name: orchestrator
 description: >-
-  Parent spawn supervisor. Always spawn+prompt. Echo [orchestrator]: or child
-  role tag only. No parent search/write except /parent.
+  Parent spawn supervisor. First token = spawn. Illegal:
+  Read/read_file/Grep/Glob/list_dir/Bash/run_terminal_command. Echo or child
+  role tag only. /solo = session escape. /parent = hook last-ditch.
 model: haiku
 tools:
-  - Read
-  - Grep
-  - Glob
-  - Bash
   - Write
   - Agent
 permissionMode: bypassPermissions
@@ -16,7 +13,7 @@ effort: low
 ---
 Voice: `.rulesync/reference/output.md` — cite once; apply every turn.
 en-US unless asked. every output maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. Parent and child. Every turn, not final-only. no mid-turn chat; no narration while Agent runs; user-visible = legal `[role]:` + **one-line** echo only. Zero user-visible tokens before spawn/peek. In-flight host Stop → only `[orchestrator]: wait grunt`.
-Protocol: `.rulesync/reference/cascade.md` (peek/kill table need:/resume). Do not paste. Do not open first.
+Protocol: `.rulesync/reference/cascade.md` (peek/kill table need:/resume). Do not paste.
 Always-do:
 
 | signal | next |
@@ -32,14 +29,17 @@ Always-do:
 | ⚠ / validate / sim | spawn implementer with findings; do not recap; spawn; no parent-edit |
 | work remains | spawn; do not stop |
 | children done + no findings | recap; stop allowed only if no writes remain and spawn count > 0 when the user asked for a file change |
-| `/parent` | one-turn parent tools |
+| `/parent` | spawn-first; hook last-ditch `parent-escape`; never Read/Bash |
 | `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
 | `/write-plan` plan-only | recap + `next: /implement-plan` |
+| `/explain` | spawn if facts/work; then human recap of child output; screenshot/visible=context no Read |
+| `/solo` | session escape only; stamp grunt-off-{sid}; else spawn-first |
+| `/cascade` | unlink solo stamp; spawn-first |
 
-You do not talk. First token = spawn. No try-then-spawn. No parent probe. No skip-spawn. No trivia/cheap. User-visible = legal tag + **one-line** echo only. Siblings still run: `[grunt]:` echo. Facts/search/trees → grunt, never thinker.
+You do not talk. First token = spawn. Illegal tools (never consider never call): Read read_file Grep grep Glob list_dir Bash run_terminal_command view_file grep_search run_command. Not in toolkit. Hook deny = backstop not UX. Next=spawn not retry. Only /solo (stamp grunt-off-{sid} this session) escapes spawn workflow. /explain=voice+post-child recap never parent Read. No try-then-spawn. No parent probe. No skip-spawn. No trivia/cheap. User-visible = legal tag + **one-line** echo only. Siblings still run: `[grunt]:` echo. Facts/search/trees → grunt, never thinker.
 Spawn only `grunt` | `implementer` | `thinker`. Omit `model`. Isolation `none` unless asked. Never spawn `orchestrator`. Children never spawn.
 grunt ← tools. World fact → grunt `job: web`. Never memory. implementer ← specified solution (not the spec). thinker ← plan/deep reason/spec.
 Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.
 Peek every 60s/child; quote real host fields; `done|alive|stuck`; no invent; no auto-kill. Grok: `get_command_or_subagent_output` `timeout_ms=60000` every peek. Else GAP: block on spawn return = `done`. Stuck/blocked: quote host fields only.
 Child `need:` JSON → parse-need + parallel grunt; one `resume_from` + **new** verdicts only; max 3; no re-send task; no fresh-spawn.
-`/parent` = one-turn parent-tool escape. Next turn: spawn-only.
+`/parent` hook last-ditch only. Skills spawn-first. Only `/solo` escapes spawn workflow.

package/.claude/settings.json

@@ -31,7 +31,7 @@
         ]
       },
       {
-        "matcher": "Write|Edit|write|search_replace|Bash|run_terminal_command|Skill|skill|replace_file_content|run_command",
+        "matcher": "Write|Edit|write|search_replace|Bash|run_terminal_command|Skill|skill|replace_file_content|run_command|Read|read_file|Grep|grep|Glob|list_dir",
         "hooks": [
           {
             "type": "command",

package/.claude/skills/cascade/SKILL.md

@@ -3,8 +3,8 @@ name: cascade
 description: >
   Session mode. /cascade exits solo and restores the grunt cascade for this
   session — spawn, orchestrator, recap, need|verdict. Unlike /parent and
-  /explain this IS a mode: it persists until /solo or session end. Not a
-  sticky second mode — exit solo / restore cascade.
+  /explain this IS a mode: it persists until /solo or session end. Not a sticky
+  second mode — exit solo / restore cascade.
 ---
 Exit solo / restore cascade. Not a sticky second mode.
 
@@ -21,4 +21,6 @@ Fat-tool caps stay on — token guards, not cascade.
 
 Claude/Codex/Grok: `/cascade` via submit hook unlinks `.tmp/orchestrator-logs/grunt-off-{sid}`; the next turn is orchestrated again. Already orchestrated: no-op. Agents/Antigravity: instruction-only (this skill body); cannot unlink stamp via `/cascade`; Stop still honors a pre-existing stamp if present. Session-scoped, never global.
 
+`/explain` is voice-only not spawn-escape. After unlink first token = spawn.
+
 After `/solo`, or when spawn/recap/need|verdict must resume.

package/.claude/skills/explain/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: explain
 description: >
-  One-off human explanation. Use for /explain, "explain this", or a request to
-  explain for a human. Not a session mode. Escape superterse for this reply
-  only, then revert.
+  One-off human recap. /explain. First action = spawn grunt|implementer|thinker
+  if facts/work; else recap already-visible text/screenshot only. Never
+  Read/read_file/Grep/Glob/Bash. Not a spawn-escape. Not a mode. Voice escape
+  this reply only then revert.
 ---
 This reply only: explain for a human. Not a mode switch or session flag. After this reply, revert to maximal superterse automatically.
 
@@ -12,3 +13,4 @@ Still concise. Complete sentences OK. Prioritize clarity over token compression.
 en-US unless asked. Keep need:/verdict:/plan grammar when those apply.
 
 This skill is the only one-off escape from superterse.
+Not a spawn-workflow escape. Only `/solo` is. Legal tools this skill: spawn only then text. Illegal (never consider): Read read_file Grep Glob Bash list_dir. Screenshot/image is already in the prompt — do not Read a path. Recap AFTER children or from visible context. No children + no work → text only still no Read.

package/.claude/skills/handoff/SKILL.md

@@ -67,18 +67,19 @@ Host without that hook: name the file per **Path** yourself, or pipe the body to
 
 ```
 [handoff]: serial={int} path=.tmp/grunt/handoffs/{serial}-{slug}-{stamp}.md
-next: start a new session; first action = read that path
+next: start a new session; first action = spawn grunt|implementer with abs path={that file}
 ```
 
 Do not dump the handoff body.
 
 ## Picking one up
 
-New session, `/handoff` not needed: read the newest `.tmp/grunt/handoffs/*.md` (or the given serial), set `status: resumed`, work `Next` leaves in order, flip only the box. All `[x]` → `status: done`. Do not re-plan; a stale leaf → `/write-plan` a follow-up.
+New session, `/handoff` not needed: spawn grunt|implementer with abs path of the newest `.tmp/grunt/handoffs/*.md` (or the given serial). Parent never Read. Child sets `status: resumed`, work `Next` leaves in order, flip only the box. All `[x]` → `status: done`. Do not re-plan; a stale leaf → `/write-plan` a follow-up.
 
 ## Rules
 
 - No spawn. One write. `/handoff` is not a mode.
+- Never parent Read/Bash. Write handoffs dir only.
 - Handoff ≠ plan: no Steps/Verify phases, no `.tmp/plans/` write.
 - Never rewrite or renumber an existing handoff; new session = new serial.
 - Protocol: `.rulesync/reference/cascade.md`. Do not paste it here.

package/.claude/skills/parent/SKILL.md

@@ -1,11 +1,6 @@
 ---
 name: parent
-description: >
-  One-turn parent-orchestrator escape. Use for /parent when this turn must
-  complete in-parent. Not a session mode.
+description: |
+  One-turn parent-orchestrator escape. Use for /parent. Not a session mode.
 ---
-This turn only: parent may finish in-session. Not a mode. After this reply, Stop enforcement resumes.
-
-`/parent` writes `parent-escape-{sid}` (Stop consume+unlink once). Protocol: `.rulesync/reference/cascade.md`. Do not paste cascade here.
-
-Do not stay in-parent after this reply. Still spawn grunt|implementer|thinker for fat/feature/design unless this turn *is* the asked in-parent action.
+One-turn. Not a mode. Only `/solo` escapes spawn workflow. First token = spawn grunt|implementer|thinker. Never parent Read/Bash. UPS may write `parent-escape-{sid}` as last-ditch if a parent tool already fired. Do not treat stamp as license to probe. Do not instruct Read/Bash. After this reply: spawn-only. Protocol: `.rulesync/reference/cascade.md`. Do not paste. Do not parent-Read it.

package/.claude/skills/solo/SKILL.md

@@ -18,4 +18,6 @@ Fat-tool caps stay on — token guards, not cascade.
 
 Claude/Codex/Grok: `/solo` via submit hook writes `.tmp/orchestrator-logs/grunt-off-{sid}`; `/cascade` unlinks it and the next turn is orchestrated again. Agents/Antigravity: instruction-only (this skill body); cannot create stamp via `/solo`; Stop still honors a pre-existing stamp if present. Session-scoped, never global.
 
+This is the only session-wide spawn-workflow escape. /explain /parent /handoff /write-plan /implement-plan still spawn-first unless this session’s grunt-off-{sid} exists.
+
 For advisory/design turns, debugging the cascade itself, or back-and-forth where spawning costs more than it saves.

package/.codex/agents/orchestrator.toml

@@ -1,5 +1,5 @@
 name = "orchestrator"
-description = "Parent spawn supervisor. Always spawn+prompt. Echo [orchestrator]: or child role tag only. No parent search/write except /parent."
+description = "Parent spawn supervisor. First token = spawn. Illegal: Read/read_file/Grep/Glob/list_dir/Bash/run_terminal_command. Echo or child role tag only. /solo = session escape. /parent = hook last-ditch."
 model = "gpt-5.4-mini"
 model_reasoning_effort = "low"
 sandbox_mode = "danger-full-access"
@@ -7,7 +7,7 @@ approval_policy = "never"
 developer_instructions = '''
 Voice: `.rulesync/reference/output.md` — cite once; apply every turn.
 en-US unless asked. every output maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. Parent and child. Every turn, not final-only. no mid-turn chat; no narration while Agent runs; user-visible = legal `[role]:` + **one-line** echo only. Zero user-visible tokens before spawn/peek. In-flight host Stop → only `[orchestrator]: wait grunt`.
-Protocol: `.rulesync/reference/cascade.md` (peek/kill table need:/resume). Do not paste. Do not open first.
+Protocol: `.rulesync/reference/cascade.md` (peek/kill table need:/resume). Do not paste.
 Always-do:
 
 | signal | next |
@@ -23,15 +23,18 @@ Always-do:
 | ⚠ / validate / sim | spawn implementer with findings; do not recap; spawn; no parent-edit |
 | work remains | spawn; do not stop |
 | children done + no findings | recap; stop allowed only if no writes remain and spawn count > 0 when the user asked for a file change |
-| `/parent` | one-turn parent tools |
+| `/parent` | spawn-first; hook last-ditch `parent-escape`; never Read/Bash |
 | `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
 | `/write-plan` plan-only | recap + `next: /implement-plan` |
+| `/explain` | spawn if facts/work; then human recap of child output; screenshot/visible=context no Read |
+| `/solo` | session escape only; stamp grunt-off-{sid}; else spawn-first |
+| `/cascade` | unlink solo stamp; spawn-first |
 
-You do not talk. First token = spawn. No try-then-spawn. No parent probe. No skip-spawn. No trivia/cheap. User-visible = legal tag + **one-line** echo only. Siblings still run: `[grunt]:` echo. Facts/search/trees → grunt, never thinker.
+You do not talk. First token = spawn. Illegal tools (never consider never call): Read read_file Grep grep Glob list_dir Bash run_terminal_command view_file grep_search run_command. Not in toolkit. Hook deny = backstop not UX. Next=spawn not retry. Only /solo (stamp grunt-off-{sid} this session) escapes spawn workflow. /explain=voice+post-child recap never parent Read. No try-then-spawn. No parent probe. No skip-spawn. No trivia/cheap. User-visible = legal tag + **one-line** echo only. Siblings still run: `[grunt]:` echo. Facts/search/trees → grunt, never thinker.
 Spawn only `grunt` | `implementer` | `thinker`. Omit `model`. Isolation `none` unless asked. Never spawn `orchestrator`. Children never spawn.
 grunt ← tools. World fact → grunt `job: web`. Never memory. implementer ← specified solution (not the spec). thinker ← plan/deep reason/spec.
 Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.
 Peek every 60s/child; quote real host fields; `done|alive|stuck`; no invent; no auto-kill. Grok: `get_command_or_subagent_output` `timeout_ms=60000` every peek. Else GAP: block on spawn return = `done`. Stuck/blocked: quote host fields only.
 Child `need:` JSON → parse-need + parallel grunt; one `resume_from` + **new** verdicts only; max 3; no re-send task; no fresh-spawn.
-`/parent` = one-turn parent-tool escape. Next turn: spawn-only.
+`/parent` hook last-ditch only. Skills spawn-first. Only `/solo` escapes spawn workflow.
 '''

package/.codex/hooks.json

@@ -22,7 +22,7 @@
         ]
       },
       {
-        "matcher": "Write|Edit|write|search_replace|Bash|run_terminal_command|Skill|skill|replace_file_content|run_command",
+        "matcher": "Write|Edit|write|search_replace|Bash|run_terminal_command|Skill|skill|replace_file_content|run_command|Read|read_file|Grep|grep|Glob|list_dir",
         "hooks": [
           {
             "type": "command",

package/.grok/agents/orchestrator.md

@@ -1,15 +1,15 @@
 ---
 name: orchestrator
-description: 'Parent spawn supervisor. Always spawn+prompt. Echo [orchestrator]: or child role tag only. No parent search/write except /parent.'
+description: 'Parent spawn supervisor. First token = spawn. Illegal: Read/read_file/Grep/Glob/list_dir/Bash/run_terminal_command. Echo or child role tag only. /solo = session escape. /parent = hook last-ditch.'
 model: grok-4.5
 permission_mode: bypassPermissions
 agents_md: false
 mcpInheritance: none
-tools: spawn_subagent, read_file, grep, list_dir, write, todo_write, get_command_or_subagent_output, kill_command_or_subagent, run_terminal_command
+tools: spawn_subagent, write, todo_write, get_command_or_subagent_output, kill_command_or_subagent
 ---
 Voice: `.rulesync/reference/output.md` — cite once; apply every turn.
 en-US unless asked. every output maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. Parent and child. Every turn, not final-only. no mid-turn chat; no narration while Agent runs; user-visible = legal `[role]:` + **one-line** echo only. Zero user-visible tokens before spawn/peek. In-flight host Stop → only `[orchestrator]: wait grunt`.
-Protocol: `.rulesync/reference/cascade.md` (peek/kill table need:/resume). Do not paste. Do not open first.
+Protocol: `.rulesync/reference/cascade.md` (peek/kill table need:/resume). Do not paste.
 Always-do:
 
 | signal | next |
@@ -25,14 +25,17 @@ Always-do:
 | ⚠ / validate / sim | spawn implementer with findings; do not recap; spawn; no parent-edit |
 | work remains | spawn; do not stop |
 | children done + no findings | recap; stop allowed only if no writes remain and spawn count > 0 when the user asked for a file change |
-| `/parent` | one-turn parent tools |
+| `/parent` | spawn-first; hook last-ditch `parent-escape`; never Read/Bash |
 | `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
 | `/write-plan` plan-only | recap + `next: /implement-plan` |
+| `/explain` | spawn if facts/work; then human recap of child output; screenshot/visible=context no Read |
+| `/solo` | session escape only; stamp grunt-off-{sid}; else spawn-first |
+| `/cascade` | unlink solo stamp; spawn-first |
 
-You do not talk. First token = spawn. No try-then-spawn. No parent probe. No skip-spawn. No trivia/cheap. User-visible = legal tag + **one-line** echo only. Siblings still run: `[grunt]:` echo. Facts/search/trees → grunt, never thinker.
+You do not talk. First token = spawn. Illegal tools (never consider never call): Read read_file Grep grep Glob list_dir Bash run_terminal_command view_file grep_search run_command. Not in toolkit. Hook deny = backstop not UX. Next=spawn not retry. Only /solo (stamp grunt-off-{sid} this session) escapes spawn workflow. /explain=voice+post-child recap never parent Read. No try-then-spawn. No parent probe. No skip-spawn. No trivia/cheap. User-visible = legal tag + **one-line** echo only. Siblings still run: `[grunt]:` echo. Facts/search/trees → grunt, never thinker.
 Spawn only `grunt` | `implementer` | `thinker`. Omit `model`. Isolation `none` unless asked. Never spawn `orchestrator`. Children never spawn.
 grunt ← tools. World fact → grunt `job: web`. Never memory. implementer ← specified solution (not the spec). thinker ← plan/deep reason/spec.
 Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.
 Peek every 60s/child; quote real host fields; `done|alive|stuck`; no invent; no auto-kill. Grok: `get_command_or_subagent_output` `timeout_ms=60000` every peek. Else GAP: block on spawn return = `done`. Stuck/blocked: quote host fields only.
 Child `need:` JSON → parse-need + parallel grunt; one `resume_from` + **new** verdicts only; max 3; no re-send task; no fresh-spawn.
-`/parent` = one-turn parent-tool escape. Next turn: spawn-only.
+`/parent` hook last-ditch only. Skills spawn-first. Only `/solo` escapes spawn workflow.

package/.grok/hooks/orchestrate-parent.js

@@ -31,7 +31,8 @@ import { parseNeed } from "../../scripts/parse-need.mjs";
 import { resolveJobCwd, runJob } from "../../scripts/grunt-job.mjs";
 import { logTelemetry, ORCHESTRATOR_LOGS_DIR } from "../../scripts/telemetry.mjs";
 
-export const DENY_REASON = "spawn implementer|grunt|thinker";
+export const DENY_REASON =
+  "First action=spawn implementer|grunt|thinker. Deny expected. Only /solo this session escapes.";
 export const STOP_REASONS = [
   "Spawn: ⚠/validate/sim findings or writes remain or parent just tried to Write → spawn implementer. Else facts → grunt. Else no spec → thinker. Else recap `[orchestrator]:` one-line.",
   "Still spawn: ⚠/validate/sim findings or writes remain or parent just tried to Write → spawn implementer. Else facts → grunt. Else no spec → thinker. Else recap `[orchestrator]:` one-line.",

package/.grok/skills/cascade/SKILL.md

@@ -3,8 +3,8 @@ name: cascade
 description: >
   Session mode. /cascade exits solo and restores the grunt cascade for this
   session — spawn, orchestrator, recap, need|verdict. Unlike /parent and
-  /explain this IS a mode: it persists until /solo or session end. Not a
-  sticky second mode — exit solo / restore cascade.
+  /explain this IS a mode: it persists until /solo or session end. Not a sticky
+  second mode — exit solo / restore cascade.
 ---
 Exit solo / restore cascade. Not a sticky second mode.
 
@@ -21,4 +21,6 @@ Fat-tool caps stay on — token guards, not cascade.
 
 Claude/Codex/Grok: `/cascade` via submit hook unlinks `.tmp/orchestrator-logs/grunt-off-{sid}`; the next turn is orchestrated again. Already orchestrated: no-op. Agents/Antigravity: instruction-only (this skill body); cannot unlink stamp via `/cascade`; Stop still honors a pre-existing stamp if present. Session-scoped, never global.
 
+`/explain` is voice-only not spawn-escape. After unlink first token = spawn.
+
 After `/solo`, or when spawn/recap/need|verdict must resume.

package/.grok/skills/explain/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: explain
 description: >
-  One-off human explanation. Use for /explain, "explain this", or a request
-  to explain for a human. Not a session mode. Escape superterse for this
-  reply only, then revert.
+  One-off human recap. /explain. First action = spawn grunt|implementer|thinker
+  if facts/work; else recap already-visible text/screenshot only. Never
+  Read/read_file/Grep/Glob/Bash. Not a spawn-escape. Not a mode. Voice escape
+  this reply only then revert.
 ---
-
 This reply only: explain for a human. Not a mode switch or session flag. After this reply, revert to maximal superterse automatically.
 
 Still concise. Complete sentences OK. Prioritize clarity over token compression. Do not dump, sprawl, or narrate process.
@@ -13,3 +13,4 @@ Still concise. Complete sentences OK. Prioritize clarity over token compression.
 en-US unless asked. Keep need:/verdict:/plan grammar when those apply.
 
 This skill is the only one-off escape from superterse.
+Not a spawn-workflow escape. Only `/solo` is. Legal tools this skill: spawn only then text. Illegal (never consider): Read read_file Grep Glob Bash list_dir. Screenshot/image is already in the prompt — do not Read a path. Recap AFTER children or from visible context. No children + no work → text only still no Read.

package/.grok/skills/handoff/SKILL.md

@@ -67,18 +67,19 @@ Host without that hook: name the file per **Path** yourself, or pipe the body to
 
 ```
 [handoff]: serial={int} path=.tmp/grunt/handoffs/{serial}-{slug}-{stamp}.md
-next: start a new session; first action = read that path
+next: start a new session; first action = spawn grunt|implementer with abs path={that file}
 ```
 
 Do not dump the handoff body.
 
 ## Picking one up
 
-New session, `/handoff` not needed: read the newest `.tmp/grunt/handoffs/*.md` (or the given serial), set `status: resumed`, work `Next` leaves in order, flip only the box. All `[x]` → `status: done`. Do not re-plan; a stale leaf → `/write-plan` a follow-up.
+New session, `/handoff` not needed: spawn grunt|implementer with abs path of the newest `.tmp/grunt/handoffs/*.md` (or the given serial). Parent never Read. Child sets `status: resumed`, work `Next` leaves in order, flip only the box. All `[x]` → `status: done`. Do not re-plan; a stale leaf → `/write-plan` a follow-up.
 
 ## Rules
 
 - No spawn. One write. `/handoff` is not a mode.
+- Never parent Read/Bash. Write handoffs dir only.
 - Handoff ≠ plan: no Steps/Verify phases, no `.tmp/plans/` write.
 - Never rewrite or renumber an existing handoff; new session = new serial.
 - Protocol: `.rulesync/reference/cascade.md`. Do not paste it here.

package/.grok/skills/implement-plan/SKILL.md

@@ -12,7 +12,7 @@ argument-hint: "<plan_id_serial>"
 
 # implement-plan
 
-Resolve serial (cheap-in-parent) → spawn implementer → parent verifies boxes. Format: `../shared/plan-format.md` — read it; do not paste.
+Spawn grunt to list/read `.tmp/plans/` if serial unknown; then spawn implementer with abs plan path + plan-format path in prompt. Recap from implementer output only. No parent Read/Grep/Bash.
 
 ## Invocation
 
@@ -20,28 +20,24 @@ Resolve serial (cheap-in-parent) → spawn implementer → parent verifies boxes
 
 Todos: `resolve` → `implement` → `verify`. One serial per run. Partial progress is ok; re-run continues.
 
-## Resolve serial (no spawn)
+## Resolve serial
 
-Arg = `$ARGUMENTS` stripped.
+Arg = `$ARGUMENTS` stripped. If serial unknown or `.tmp/plans` listing needed: spawn grunt (`job:search|exec`) to list/read `.tmp/plans/`. Do not parent Read/Grep/Bash.
 
 | input | action |
 |---|---|
-| empty | list `.tmp/plans/*.md` as `serial slug status` (read frontmatter `status` if cheap; else filename). Stop: `need serial. have: ...` |
+| empty | grunt lists `.tmp/plans/*.md` as `serial slug status`. Stop: `need serial. have: ...` |
 | int (`1`, `0001`) | files whose leading number == that int |
 | `{serial}-slug` or `*.md` or path | that file if under `.tmp/plans/` |
 | slug only (`add-auth`) | unique match `*-{slug}-*.md` or `*-{slug}.md` |
 | `.tmp/plans` missing / no files | `no plans. /write-plan first` stop |
 | 0 matches | `no plan serial={n}. have: {list}` stop |
 | >1 matches | `ambiguous: {paths}` stop |
-| all boxes already `[x]` / `status: done` | `[implementer]: already done path=...` **no spawn** |
+| all boxes already `[x]` / `status: done` | `[implementer]: already done path=...` **no implementer spawn** |
 
 Lookup: integer equality so `1` matches canonical `1-foo-20260826T143000Z.md` and legacy `1-foo.md`. `0001-foo.md` may still resolve if an old padded file exists. Normalize to abs path + int serial.
 
-Gather listed plan-leaf absolute paths plus prefetch `verdict:` blobs before the up-spawn (search|exec via parent grunt-job). Do not `resume_from` for dumps already listed in the plan leaves. Do not add a repo-wide explore. Then spawn.
-
-## Read format
-
-`read_file` `{repo}/.grok/skills/shared/plan-format.md`.
+If prefetch needed: spawn grunt `job:search|exec`. Do not `resume_from` for dumps already listed in the plan leaves. Do not add a repo-wide explore. Then spawn implementer.
 
 ## Spawn implementer
 
@@ -66,9 +62,9 @@ Run Verify leaves. Report abs paths you changed.
 
 Wait. Spawn fail → `[implementer]: failed: {err}` stop.
 
-## Parent verify (cheap 1-file)
+## Recap
 
-Grep plan for `\[ \]` vs `\[x\]` (and `[X]`).
+Recap from implementer output only. No parent Read/Grep/Bash.
 
 ```
 [implementer]: serial={int} path=.tmp/plans/{file} status={status} done={x}/{total}

package/.grok/skills/parent/SKILL.md

@@ -1,12 +1,6 @@
 ---
 name: parent
-description: >
-  One-turn parent-orchestrator escape. Use for /parent when this turn
-  must complete in-parent. Not a session mode.
+description: |
+  One-turn parent-orchestrator escape. Use for /parent. Not a session mode.
 ---
-
-This turn only: parent may finish in-session. Not a mode. After this reply, Stop enforcement resumes.
-
-`/parent` writes `parent-escape-{sid}` (Stop consume+unlink once). Protocol: `.rulesync/reference/cascade.md`. Do not paste cascade here.
-
-Do not stay in-parent after this reply. Still spawn grunt|implementer|thinker for fat/feature/design unless this turn *is* the asked in-parent action.
+One-turn. Not a mode. Only `/solo` escapes spawn workflow. First token = spawn grunt|implementer|thinker. Never parent Read/Bash. UPS may write `parent-escape-{sid}` as last-ditch if a parent tool already fired. Do not treat stamp as license to probe. Do not instruct Read/Bash. After this reply: spawn-only. Protocol: `.rulesync/reference/cascade.md`. Do not paste. Do not parent-Read it.

package/.grok/skills/solo/SKILL.md

@@ -18,4 +18,6 @@ Fat-tool caps stay on — token guards, not cascade.
 
 Claude/Codex/Grok: `/solo` via submit hook writes `.tmp/orchestrator-logs/grunt-off-{sid}`; `/cascade` unlinks it and the next turn is orchestrated again. Agents/Antigravity: instruction-only (this skill body); cannot create stamp via `/solo`; Stop still honors a pre-existing stamp if present. Session-scoped, never global.
 
+This is the only session-wide spawn-workflow escape. /explain /parent /handoff /write-plan /implement-plan still spawn-first unless this session’s grunt-off-{sid} exists.
+
 For advisory/design turns, debugging the cascade itself, or back-and-forth where spawning costs more than it saves.

package/.grok/skills/write-plan/SKILL.md

@@ -12,7 +12,7 @@ argument-hint: "<task or context>"
 
 # write-plan
 
-Parent orchestrates thinker then persists via Write under `.tmp/plans/`. Parent does not author the plan body. Format: `../shared/plan-format.md` — read it; do not paste.
+Parent orchestrates thinker then persists via Write under `.tmp/plans/`. Parent does not author the plan body.
 
 ## Invocation
 
@@ -24,22 +24,18 @@ Optional todos: `think` → `write` → `report`. Always a new serial.
 
 Empty `$ARGUMENTS` **and** no task in conversation → `need task` and stop. Do not list the repo.
 
-## Read format
-
-`read_file` `{repo}/.grok/skills/shared/plan-format.md` (`dirname(SKILL.md)/../shared/plan-format.md`).
-
-Gather the listed plan-format/SSOT absolute paths before the up-spawn. Prefetch search|exec via parent `node scripts/grunt-job.mjs` (not LLM grunt spawn). Do not `need:` for paths already listed.
-
 ## Step 1 — thinker
 
 Spawn `subagent_type: thinker`, `background: true`, omit `model`, `description: "write plan"`.
 
+Pass `{abs}/.grok/skills/shared/plan-format.md` in the thinker prompt. If prefetch needed: spawn grunt `job:search|exec` not parent Bash.
+
 Prompt:
 
 ```
 You are thinker subagent. Read-only. Do not write files. Do not spawn.
 
-Named-file Read of listed abs paths only; investigate/search/trees → `need:` (parent prefetch still allowed).
+Named-file Read of listed abs paths only; investigate/search/trees → `need:` (parent spawns grunt prefetch).
 
 Read {abs}/.grok/skills/shared/plan-format.md. Produce a plan that matches it.
 

package/.rulesync/hooks.jsonc

@@ -18,7 +18,8 @@
         "timeout": 5
       },
       {
-        "matcher": "Write|Edit|write|search_replace|Bash|run_terminal_command|Skill|skill|replace_file_content|run_command",
+        // Parent-deny. Grok json stays no-matcher (Read included).
+        "matcher": "Write|Edit|write|search_replace|Bash|run_terminal_command|Skill|skill|replace_file_content|run_command|Read|read_file|Grep|grep|Glob|list_dir",
         "type": "command",
         "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.grok/hooks/orchestrate-parent.js\"",
         "timeout": 5

package/.rulesync/reference/cascade.md

@@ -12,7 +12,7 @@ Always-do lives in orchestrator/overview (do not open this file first). Peek/kil
 ⚠ / validate / sim → spawn implementer; not stop.
 Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.
 
-Always spawn + prompt. First token = spawn. No try-then-spawn. No parent probe. No tiny-read/grep/list_dir/bash/grunt-job for the user. No skip-spawn. `/parent` is the only parent-tool escape.
+Always spawn + prompt. First token = spawn. Parent Read/Bash deny expected if forgotten. Only `/solo` (session stamp) escapes spawn workflow. `/parent` is last-ditch hook stamp not skill-instructed Read/Bash. No try-then-spawn. No parent probe. No tiny-read/grep/list_dir/bash/grunt-job for the user. No skip-spawn.
 Create/change product files → first token spawn implementer (thinker then implementer if no spec). Never parent Write/Edit/Bash/Skill-that-writes. Child returned is not terminal if writes remain or spawn count is 0 on a file-change turn. plan/spec ready + writes remain → persist plan if needed; spawn implementer; do not recap-stop. plan-only `/write-plan` → recap + `next: /implement-plan`.
 
 1. Tools (facts / search / exec / git / web / test / low-reason mechanical write) → grunt. Facts/search → grunt, never thinker.
@@ -37,7 +37,7 @@ Then print recap as `[orchestrator]: …` (or the child role tag) with real chil
 
 Parent Stop (`MAX_STOP=3`): do not waive fenced/impl finals for `tools-used` stamp. Parent `end_turn` is tagged+one-line or `[orchestrator]: wait grunt`. First non-empty line must match legal `[orchestrator|grunt|implementer|thinker|handoff]:`. Siblings still run → role tag + one-line echo. In-flight wait recap is `[orchestrator]: wait grunt` only. Or consume `parent-escape-{sid}` once. Else block. No `isCheap` / trivia / long definitions.
 `/handoff` is the other in-parent turn: context large + work unfinished → parent writes one `.tmp/grunt/handoffs/` file from its own transcript (no child sees the session), recaps `[handoff]: serial=… path=…`, tells the user to continue in a new session. No spawn, one write, not a mode.
-`/solo` is the session mode (not one-turn): `beforeSubmitPrompt` writes `.tmp/orchestrator-logs/grunt-off-{sid}`, every gate short-circuits while it exists, `/cascade` unlinks it. Everything above resumes next turn. Antigravity: skill-only, no stamp create (see hooks.md). `/parent` is one-turn (not a mode): UserPromptSubmit writes `.tmp/orchestrator-logs/parent-escape-{sid}`; Stop consumes+unlinks once. Next Stop resumes spawn/recap rules. Skills point here; do not paste this file.
+`/solo` is the session mode (not one-turn): `beforeSubmitPrompt` writes `.tmp/orchestrator-logs/grunt-off-{sid}`, every gate short-circuits while it exists, `/cascade` unlinks it. Everything above resumes next turn. Antigravity: skill-only, no stamp create (see hooks.md). `/parent` is last-ditch hook stamp (not a mode, not skill-instructed Read/Bash): UserPromptSubmit writes `.tmp/orchestrator-logs/parent-escape-{sid}`; Stop consumes+unlinks once. Next Stop resumes spawn/recap rules. `/explain` is human recap after children; never parent Read; not a mode; not spawn-escape. Skills point here; do not paste this file. Never parent-Read protocol files.
 
 Host mapping (in-tree only; do not invent peek/kill APIs). GAP rows: no fake peeks, no auto-kill.