@lovrozagar/grunt 0.3.7 → 0.3.9

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.
 

package/.rulesync/reference/hooks.md

@@ -10,11 +10,11 @@ Grok PostToolUse / UserPromptSubmit / SessionStart are observe-only — do not a
 
 Claude / Codex / Antigravity PreToolUse still run `scripts/scrub-spawn-prompt.mjs` and `scripts/gate-fat-tools.mjs`. Grok does not — spawn/fat rewrite is `orchestrate-parent.js` only. RTK stays `rtk.json`.
 
-Parent Write|Edit|Bash|Skill-that-writes is deny on Claude+Grok+Antigravity unless `/parent`. `.tmp/plans/` and `.tmp/grunt/handoffs/` Write still persist. Parent Bash still allowed for workspace `grunt-job.mjs` `--job search|exec`. Children with a type skip parent-deny (fat-only). Skill allowlist without escape: `parent|explain|solo|cascade|handoff|write-plan|implement-plan`. Deny reason: `spawn implementer|grunt|thinker`. Parent `end_turn` is tagged+one-line or `[orchestrator]: wait grunt`.
+Parent Read|Write|Edit|Bash|Skill deny unless `/solo` (session) or `/parent` last-ditch stamp. Grok PreToolUse has no matcher (Read included). Skills spawn-first; do not instruct parent Read/Bash. `.tmp/plans/` and `.tmp/grunt/handoffs/` Write still persist. Parent Bash still allowed for workspace `grunt-job.mjs` `--job search|exec`. Children with a type skip parent-deny (fat-only). Skill allowlist without escape: `parent|explain|solo|cascade|handoff|write-plan|implement-plan`. Deny reason: `First action=spawn implementer|grunt|thinker. Deny expected. Only /solo this session escapes.`. Parent `end_turn` is tagged+one-line or `[orchestrator]: wait grunt`.
 
 Parent `run_terminal_command` is deny-by-default except `node` (optional leading `rtk`) invoking `{workspace}/scripts/grunt-job.mjs` with `--job search|exec` and `--query`. Optional `--path` `--glob` (repeatable) `--cwd`. Not `web|test`, not other scripts. META strips `--query` value first so `|` inside query is allowed; pipes/`&&` outside query still deny. Never `cd &&`. Exec shell-meta in query is grunt-job FALLBACK (exit 2), not a parent-bash allow. Unknown flags → FALLBACK.
 
-SubagentStop (and child Stop with `subagentType`) intercepts a parseable `need:` whose jobs are all `search|exec` (cap 4): runs grunt-job in-hook and continues the child with concatenated `verdict:` blobs. Mixed/web/test, parse fail, FALLBACK, `stopHookActive`, or more than 3 intercepts per child session → empty stdout (allow stop; parent LLM path). Parent `write` is deny-by-default except `.tmp/plans/` (`persist-plan.mjs`) and `.tmp/grunt/handoffs/` (`persist-handoff.mjs`); both validate + rewrite path/content, invalid body denies. Parent Stop (`MAX_STOP=3`): do not waive impl finals for `tools-used`. Parent `end_turn` is tagged+one-line or `[orchestrator]: wait grunt`. First non-empty line must match legal `[orchestrator|grunt|implementer|thinker|handoff]:`. Claude Agent launch ≠ done; in-flight host Stop → wait recap `[orchestrator]: wait grunt` only; no SendMessage. Or consume `parent-escape-{sid}` once (`/parent`). No `isCheap` / trivia. Stamps: `tools-used` / `stop-block` / `need-intercept` / `parent-escape`. Skills point to cascade; do not paste protocol here.
+SubagentStop (and child Stop with `subagentType`) intercepts a parseable `need:` whose jobs are all `search|exec` (cap 4): runs grunt-job in-hook and continues the child with concatenated `verdict:` blobs. Mixed/web/test, parse fail, FALLBACK, `stopHookActive`, or more than 3 intercepts per child session → empty stdout (allow stop; parent LLM path). Parent `write` is deny-by-default except `.tmp/plans/` (`persist-plan.mjs`) and `.tmp/grunt/handoffs/` (`persist-handoff.mjs`); both validate + rewrite path/content, invalid body denies. Parent Stop (`MAX_STOP=3`): do not waive impl finals for `tools-used`. Parent `end_turn` is tagged+one-line or `[orchestrator]: wait grunt`. First non-empty line must match legal `[orchestrator|grunt|implementer|thinker|handoff]:`. Claude Agent launch ≠ done; in-flight host Stop → wait recap `[orchestrator]: wait grunt` only; no SendMessage. Or consume `parent-escape-{sid}` once (`/parent` last-ditch, not “use parent tools”). No `isCheap` / trivia. Stamps: `tools-used` / `stop-block` / `need-intercept` / `parent-escape`. Skills point to cascade; do not paste protocol here.
 
 `/solo` writes `grunt-off-{sid}`; `/cascade` unlinks it (`beforeSubmitPrompt`, exact-match only). While set: PreToolUse allows parent tools (fat gate still runs) and skips the `defaultGrunt` spawn rewrite; Stop returns 0 **before** the `parent-escape` consume, so solo never burns the one-turn stamp. Session-scoped, fail-closed.
 

package/.rulesync/reference/map.md

@@ -23,13 +23,13 @@ Cheap outline. Not a file dump.
 - `.grok/hooks/orchestrate-parent.js` + `orchestrate-parent.json` — parent spawn/fat/stop/plan-write / SubagentStop intercept
 - `.grok/hooks/rtk.json` — RTK
 - `.grok/skills/{write-plan,implement-plan,shared}/` — hand-only (no rulesync SSOT); point to cascade, do not paste
-- `.grok/skills/{parent,explain,handoff,solo,commit,commit-and-push}/` — generated from `.rulesync/skills/`; do not hand-edit
+- `.grok/skills/{parent,explain,handoff,solo,cascade,commit,commit-and-push}/` — generated from `.rulesync/skills/`; do not hand-edit
 - `.grok/parent.md` — 1-line pointer to orchestrator agent; not SessionStart
 - `.grok/roles/*.toml`
 - `.grok/global-settings.toml` — merged into `~/.grok/config.toml` by `scripts/sync-global-settings.mjs` (not auto-loaded; project config cannot set `[features]`)
 - `.rulesync/global-settings/` — host manifest and reserved noop payloads
 - `.rulesync/mcp-policy.jsonc` — MCP deny-default SSOT (`default: deny`, `allow: []`)
-- `.rulesync/skills/{parent,explain,handoff,solo,commit,commit-and-push}/` — skill SSOT; `rulesync -f skills` emits `.grok/skills/`, `.claude/skills/`, `.agents/skills/` byte-equal. `/cascade` has no skill (hook-only: a `grunt`-adjacent listing entry risks mis-routing `Skill` vs `Agent`)
+- `.rulesync/skills/{parent,explain,handoff,solo,cascade,commit,commit-and-push}/` — skill SSOT; `rulesync -f skills` emits `.grok/skills/`, `.claude/skills/`, `.agents/skills/` byte-equal. `/cascade` = exit solo / restore cascade (not a sticky second mode)
 
 ## Scripts
 - `scripts/check-globals.mjs` — `$HOME/.grok/config.toml` `[agent].name==orchestrator` + `[features].two_pass_compaction==true`; project `.grok/config.toml` must not have `[features]`/`[agent]`; wired as `sync:globals:check` (also after emit-mcp in `rulesync:check`)
@@ -58,7 +58,7 @@ Cheap outline. Not a file dump.
 
 ## Generated (do not hand-edit; committed, not gitignored)
 - `AGENTS.md`, `CLAUDE.md`
-- `.claude/skills/*`, `.agents/skills/*`, `.grok/skills/{parent,explain,handoff,solo,commit,commit-and-push}/` (from `.rulesync/skills/`)
+- `.claude/skills/*`, `.agents/skills/*`, `.grok/skills/{parent,explain,handoff,solo,cascade,commit,commit-and-push}/` (from `.rulesync/skills/`)
 - `.grok/agents/*`
 - `.claude/agents/*`
 - `.codex/agents/*`

package/.rulesync/rules/CLAUDE.md

@@ -6,7 +6,7 @@ targets:
 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`.
 All output exclude AI attribution, Co-Authored-By, trailers, generated markers.
-Protocol: `.rulesync/reference/cascade.md`. Do not paste. Do not open first.
+Protocol: `.rulesync/reference/cascade.md`. Do not paste.
 Always-do:
 
 | signal | next |
@@ -22,13 +22,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 |
 
 Parent = this file not `.claude/agents/orchestrator.md`. You do not talk. Spawn wait echo.
 Spawn only grunt|implementer|thinker. Never spawn orchestrator. Children never spawn.
-First token = spawn. No try-then-spawn. No parent probe. After child: legal tag + one-line echo only. Siblings still run: `[grunt]:` echo. No skip-spawn. /parent = one-turn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`.
+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. After child: legal tag + one-line echo only. Siblings still run: `[grunt]:` echo. No skip-spawn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`.
+`/parent` hook last-ditch only. Skills spawn-first. Only `/solo` escapes spawn workflow.
 grunt ← tools (facts/search/exec/git/web/test/low-reason mechanical write; world fact: `job: web` never memory). implementer ← write defined solution. thinker ← plan/deep reason.
 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. `timeout_ms=60000` every peek. GAP: block on spawn return = `done`. Stuck/blocked: quote host fields only.

package/.rulesync/rules/overview.md

@@ -11,7 +11,7 @@ globs:
 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`.
 All output exclude AI attribution, Co-Authored-By, trailers, generated markers.
-Protocol: `.rulesync/reference/cascade.md`. Do not paste. Do not open first.
+Protocol: `.rulesync/reference/cascade.md`. Do not paste.
 Always-do:
 
 | signal | next |
@@ -27,13 +27,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 |
 
 Parent = orchestrator. You do not talk. Spawn wait echo.
 Spawn only grunt|implementer|thinker. Never spawn orchestrator. Children never spawn.
-First token = spawn. No try-then-spawn. No parent probe. After child: legal tag + one-line echo only. Siblings still run: `[grunt]:` echo. No skip-spawn. /parent = one-turn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`.
+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. After child: legal tag + one-line echo only. Siblings still run: `[grunt]:` echo. No skip-spawn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`.
+`/parent` hook last-ditch only. Skills spawn-first. Only `/solo` escapes spawn workflow.
 grunt ← tools (facts/search/exec/git/web/test/low-reason mechanical write; world fact: `job: web` never memory). implementer ← write defined solution. thinker ← plan/deep reason.
 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. `timeout_ms=60000` every peek. GAP: block on spawn return = `done`. Stuck/blocked: quote host fields only.

package/.rulesync/skills/cascade/SKILL.md

@@ -0,0 +1,26 @@
+---
+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.
+---
+Exit solo / restore cascade. Not a sticky second mode.
+
+Session mode, not one-turn. Persists until `/solo` or session end.
+
+This session: cascade restored. You are the parent orchestrator.
+
+- Spawn grunt|implementer|thinker.
+- Recap tags. Recap `[orchestrator]:` `[grunt]:` `[implementer]:` `[thinker]:` `[handoff]:`.
+- Spawn-first rule. `need:`/`verdict:` grammar.
+- Voice unchanged: `.rulesync/reference/output.md`. `/explain` is still the voice escape.
+
+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/.rulesync/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.
@@ -13,3 +14,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/.rulesync/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/.rulesync/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/.rulesync/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/.rulesync/subagents/orchestrator.md

@@ -1,6 +1,6 @@
 ---
 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."
 tier: cheap
 targets:
   - claudecode
@@ -11,13 +11,13 @@ claudecode:
   model: haiku
   effort: low
   permissionMode: bypassPermissions
-  tools: [Read, Grep, Glob, Bash, Write, Agent]
+  tools: [Write, Agent]
 grokcli:
   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
 codexcli:
   model: gpt-5.4-mini
   model_reasoning_effort: low
@@ -29,13 +29,13 @@ antigravity-cli:
   mainAgent: false
   inheritMcp: false
   commandExecutionPolicy: eager
-  tools: [view_file, grep_search, run_command]
+  tools: []
 geminicli:
   model: gemini-2.5-flash
 ---
 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 |
@@ -51,14 +51,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.md

@@ -1,7 +1,7 @@
 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`.
 All output exclude AI attribution, Co-Authored-By, trailers, generated markers.
-Protocol: `.rulesync/reference/cascade.md`. Do not paste. Do not open first.
+Protocol: `.rulesync/reference/cascade.md`. Do not paste.
 Always-do:
 
 | signal | next |
@@ -17,13 +17,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 |
 
 Parent = orchestrator. You do not talk. Spawn wait echo.
 Spawn only grunt|implementer|thinker. Never spawn orchestrator. Children never spawn.
-First token = spawn. No try-then-spawn. No parent probe. After child: legal tag + one-line echo only. Siblings still run: `[grunt]:` echo. No skip-spawn. /parent = one-turn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`.
+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. After child: legal tag + one-line echo only. Siblings still run: `[grunt]:` echo. No skip-spawn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`.
+`/parent` hook last-ditch only. Skills spawn-first. Only `/solo` escapes spawn workflow.
 grunt ← tools (facts/search/exec/git/web/test/low-reason mechanical write; world fact: `job: web` never memory). implementer ← write defined solution. thinker ← plan/deep reason.
 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. `timeout_ms=60000` every peek. GAP: block on spawn return = `done`. Stuck/blocked: quote host fields only.

package/CLAUDE.md

@@ -1,7 +1,7 @@
 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`.
 All output exclude AI attribution, Co-Authored-By, trailers, generated markers.
-Protocol: `.rulesync/reference/cascade.md`. Do not paste. Do not open first.
+Protocol: `.rulesync/reference/cascade.md`. Do not paste.
 Always-do:
 
 | signal | next |
@@ -17,13 +17,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 |
 
 Parent = this file not `.claude/agents/orchestrator.md`. You do not talk. Spawn wait echo.
 Spawn only grunt|implementer|thinker. Never spawn orchestrator. Children never spawn.
-First token = spawn. No try-then-spawn. No parent probe. After child: legal tag + one-line echo only. Siblings still run: `[grunt]:` echo. No skip-spawn. /parent = one-turn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`.
+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. After child: legal tag + one-line echo only. Siblings still run: `[grunt]:` echo. No skip-spawn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`.
+`/parent` hook last-ditch only. Skills spawn-first. Only `/solo` escapes spawn workflow.
 grunt ← tools (facts/search/exec/git/web/test/low-reason mechanical write; world fact: `job: web` never memory). implementer ← write defined solution. thinker ← plan/deep reason.
 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. `timeout_ms=60000` every peek. GAP: block on spawn return = `done`. Stuck/blocked: quote host fields only.

package/README.md

@@ -1,6 +1,6 @@
 # GRUNT
 
-Building Grunt - a multi agent orchestrator workflow
+Building Grunt - a multi agent orchestrator workflow. OSS, general use case, merges with existing configs, drop in any repo to switch from default provider flow to Grunt's
 
 # Install
 
@@ -11,10 +11,12 @@ npm i -D @lovrozagar/grunt
 npx @lovrozagar/grunt
 ```
 
-Same as `npx @lovrozagar/grunt init`. Merge SoT, `npm install`, `rulesync:generate`, `sync:globals:apply`, `rulesync:check`. Do not `npm test` as a consumer.
+TTY no command: menu (init default; generate, check, sync-globals, purge-mcps, doctor, help, quit). Piped/CI/`--yes`/`-y`/`--non-interactive` no command: still `init`. Same as `npx @lovrozagar/grunt init`. Merge SoT, `npm install`, `rulesync:generate`, `sync:globals:apply`, `rulesync:check`. Do not `npm test` as a consumer.
 
 `--skip-globals` skips `sync:globals:apply`. Re-init auto-skips globals when `<!-- grunt:begin -->` is in AGENTS.md/CLAUDE.md or `scripts/telemetry.mjs` exists. First init (no sentinel, no telemetry) still applies globals unless flagged.
 
+`sync-globals` / `purge-mcps`: dry-run default; `--apply` writes. `--yes` is not `--apply`. `sync-globals --host <id>`. `doctor` runs `rulesync doctor`.
+
 Contributors to this repo only: local `npm i && npm test`.
 
 # Version bump

package/bin/grunt.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
 import { start } from "../cli/grunt.mjs"
 
-start()
+start().catch(() => {
+  process.exit(1)
+})

package/cli/grunt.mjs

@@ -2,38 +2,134 @@ import { execFileSync } from "node:child_process"
 import { readFileSync } from "node:fs"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
-import { init } from "./init.mjs"
+import { destAlreadyInited, init, shouldAutoSkipGlobals } from "./init.mjs"
+import { confirm, isInteractive, select, spinner } from "./prompt.mjs"
 
 const PKG_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..")
 
 const USAGE = `Usage: grunt [command]
 
-Default (no command): init — full setup
+Default (no command): TTY menu; else init — full setup
 
 Commands:
-  init       Full setup: merge SoT, npm install, rulesync:generate, sync:globals:apply, rulesync:check
-  generate   npm run rulesync:generate
-  check      npm run rulesync:check
-  help       Show this help
-  version    Print package version
+  init          Full setup: merge SoT, npm install, rulesync:generate, sync:globals:apply, rulesync:check
+  generate      npm run rulesync:generate
+  check         npm run rulesync:check
+  sync-globals  npm run sync:globals (dry-run; --apply to write)
+  purge-mcps    npm run purge:global-mcps (dry-run; --apply to write)
+  doctor        npm run rulesync:doctor
+  help          Show this help
+  version       Print package version
 
 Flags:
-  --skip-globals  Skip sync:globals:apply (auto-skipped when already initialized)
+  --skip-globals     Skip sync:globals:apply (auto-skipped when already initialized)
+  --yes, -y          Non-interactive (not --apply)
+  --non-interactive  Same as --yes
+  --apply            Write for sync-globals / purge-mcps
+  --host <id>        sync-globals host
 `
 
+const MENU_OPTIONS = [
+  { value: "init", label: "init" },
+  { value: "generate", label: "generate" },
+  { value: "check", label: "check" },
+  { value: "sync-globals", label: "sync-globals" },
+  { value: "purge-mcps", label: "purge-mcps" },
+  { value: "doctor", label: "doctor" },
+  { value: "help", label: "help" },
+  { value: "quit", label: "quit" },
+]
+
+const YES_FLAGS = new Set(["--yes", "-y", "--non-interactive"])
+
 function pkgVersion() {
   const pkg = JSON.parse(readFileSync(path.join(PKG_ROOT, "package.json"), "utf8"))
   return pkg.version
 }
 
-function npmRun(script) {
-  execFileSync("npm", ["run", script], { cwd: process.cwd(), stdio: "inherit" })
+function npmRun(script, extra = []) {
+  const args = extra.length ? ["run", script, "--", ...extra] : ["run", script]
+  execFileSync("npm", args, { cwd: process.cwd(), stdio: "inherit" })
+}
+
+function hostValueOk(v) {
+  return v != null && v !== "" && !String(v).startsWith("-")
 }
 
-export function start() {
-  const args = process.argv.slice(2)
-  const skipGlobals = args.includes("--skip-globals")
-  const [cmd] = args.filter((a) => a !== "--skip-globals")
+export function parseArgv(argv) {
+  let skipGlobals = false
+  let apply = false
+  let host
+  let hostError = false
+  const positionals = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === "--skip-globals") {
+      skipGlobals = true
+      continue
+    }
+    if (YES_FLAGS.has(a)) continue
+    if (a === "--apply") {
+      apply = true
+      continue
+    }
+    if (a === "--host") {
+      const v = argv[i + 1]
+      if (!hostValueOk(v)) {
+        hostError = true
+        continue
+      }
+      host = v
+      i += 1
+      continue
+    }
+    if (typeof a === "string" && a.startsWith("--host=")) {
+      host = a.slice("--host=".length)
+      if (!hostValueOk(host)) hostError = true
+      continue
+    }
+    positionals.push(a)
+  }
+  return { cmd: positionals[0], skipGlobals, apply, host, hostError }
+}
+
+function hostExtra(host) {
+  return host ? ["--host", host] : []
+}
+
+function bindSpinner() {
+  const spin = spinner()
+  return (name, action) => {
+    if (action === "start") spin.start(name)
+    else if (action === "stop") spin.stop()
+  }
+}
+
+async function runInit(cwd, { skipGlobals, interactive }) {
+  if (!interactive) {
+    init(cwd, { skipGlobals })
+    return
+  }
+  if (destAlreadyInited(cwd)) {
+    const again = await confirm({
+      message: "Re-init?",
+      initialValue: true,
+    })
+    if (!again) return
+  }
+  const autoSkip = skipGlobals || shouldAutoSkipGlobals(cwd)
+  const applyGlobals = await confirm({
+    message: "Apply globals?",
+    initialValue: !autoSkip,
+  })
+  init(cwd, {
+    skipGlobals: !applyGlobals,
+    applyGlobals,
+    onPhase: bindSpinner(),
+  })
+}
+
+async function dispatch(cmd, flags, interactive) {
   if (cmd === "help" || cmd === "--help" || cmd === "-h") {
     process.stdout.write(USAGE)
     return
@@ -43,7 +139,10 @@ export function start() {
     return
   }
   if (!cmd || cmd === "init") {
-    init(process.cwd(), { skipGlobals })
+    await runInit(process.cwd(), {
+      skipGlobals: flags.skipGlobals,
+      interactive: interactive && (!cmd || cmd === "init"),
+    })
     return
   }
   if (cmd === "generate") {
@@ -54,6 +153,40 @@ export function start() {
     npmRun("rulesync:check")
     return
   }
+  if (cmd === "sync-globals") {
+    const script = flags.apply ? "sync:globals:apply" : "sync:globals"
+    npmRun(script, hostExtra(flags.host))
+    return
+  }
+  if (cmd === "purge-mcps") {
+    npmRun(flags.apply ? "purge:global-mcps:apply" : "purge:global-mcps")
+    return
+  }
+  if (cmd === "doctor") {
+    npmRun("rulesync:doctor")
+    return
+  }
   process.stdout.write(USAGE)
   process.exitCode = 1
 }
+
+export async function start() {
+  const flags = parseArgv(process.argv.slice(2))
+  if (flags.hostError) {
+    process.stdout.write(USAGE)
+    process.exitCode = 1
+    return
+  }
+  const interactive = isInteractive()
+  let cmd = flags.cmd
+  if (!cmd && interactive) {
+    const choice = await select({
+      message: "Command",
+      options: MENU_OPTIONS,
+      initialValue: "init",
+    })
+    if (choice === "quit") return
+    cmd = choice
+  }
+  await dispatch(cmd, flags, interactive)
+}