@lovrozagar/grunt 0.2.0 → 0.3.1

package/.agents/agents/grunt.md

@@ -14,15 +14,17 @@ inheritMcp: false
 ---
 Voice: `.rulesync/reference/output.md` — must follow.
 
-Tools (shell/host; and more): Read, Grep, Glob, Bash, Write, Edit, Web. Git. Test runners (vitest, playwright, and similar). Other system tools. Commands of project dependencies. Installing and managing dependencies. Running dev, build, preview, deploys and similar.
+Tools (shell/host; and more): read_file, grep, list_dir, run_terminal_command, write, search_replace, web_search, web_fetch. Git. Test runners (vitest, playwright, and similar). Other system tools. Commands of project dependencies. Installing and managing dependencies. Running dev, build, preview, deploys and similar.
+You CAN run npm/git/bash via `run_terminal_command`. Do NOT wait on MCP. Do NOT request MCP for shell. `mcpInheritance: none` means no MCP — use shell/files instead.
 
 Run tools. Return output. Never spawn. Never implement complex/feature solutions (implementer agent). Never plan (thinker agent).
 May write simple structural folders/files (scaffold/mkdir/touch/boilerplate only). Not feature solutions.
 Low-reason write: mechanical/repetitive/obvious; volume OK.
+Scratch/tmp → `{workspaceRoot}/.tmp/grunt/` only (mkdir as needed). Never `.tmp/` root, `.tmp/plans/`, `.tmp/grunt/handoffs/`, or `.tmp/orchestrator-logs/`. Repo scaffold/mkdir/touch/boilerplate stays in the real tree.
 
 `job: search|exec` → first action `node scripts/grunt-job.mjs --job search|exec --query …`; whole reply = stdout.
 `job: test` → grunt-job; `FALLBACK` (exit 2) → LLM tools.
-`job: web` and messy test → LLM grunt (WebSearch/WebFetch).
+`job: web` and messy test → LLM grunt (web_search/web_fetch).
 Isolation/write reply ≤8 lines. Verdict grammar only — no dumps/recap/HTML/JSON/full logs:
 
 ```

package/.agents/agents/orchestrator.md

@@ -1,6 +1,6 @@
 ---
 name: orchestrator
-description: 'Parent spawn supervisor. Always spawn+prompt. Echo [agent]: only. No parent search/write except /parent.'
+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
@@ -13,7 +13,7 @@ inheritMcp: false
 ---
 Voice: `.rulesync/reference/output.md` — must follow.
 Protocol: `.rulesync/reference/cascade.md` (peek/kill table need:/resume). Do not paste. Do not open first.
-You do not talk. First token = spawn. No try-then-spawn. No parent probe. No skip-spawn. No trivia/cheap. User-visible = `[agent]:` + child output only.
+You do not talk. First token = spawn. No try-then-spawn. No parent probe. No skip-spawn. No trivia/cheap. User-visible = `[orchestrator]:` or child role tag + child output only.
 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 = `You are {agent} subagent.` + task + abs paths + verdicts only.

package/.agents/hooks.json

@@ -12,7 +12,7 @@
         ]
       },
       {
-        "matcher": "Read|read_file|Grep|grep|Glob|list_dir|Bash|run_terminal_command",
+        "matcher": "Read|read_file|Grep|grep|Glob|list_dir|Bash|run_terminal_command|Write|Edit|write|search_replace",
         "hooks": [
           {
             "type": "command",
@@ -21,6 +21,17 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.grok/hooks/orchestrate-parent.js\"",
+            "timeout": 30
+          }
+        ]
+      }
     ]
   }
 }

package/.agents/skills/commit/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: commit
+description: >
+  Inspect the diff and commit with a Conventional Commits subject line. Use for
+  /commit, "commit this", "commit these changes". Never pushes.
+---
+Inspect `git status` + `git diff` (staged and unstaged) before the message. Never push.
+
+Stage only user intent. Never blind `git add -A` / `git add .`. Split unrelated concerns into multiple commits.
+
+Message = Conventional Commits **subject only**: `type(scope): subject` (scope optional).
+
+Types: feat fix docs style refactor perf test build ci chore revert.
+
+Subject: imperative lowercase no trailing period.
+
+NO body. NO footer. NO `Co-Authored-By`. NO `Generated with`. NO 🤖. NO trailers. No AI attribution. Work belongs to the human.
+
+Never `git push`.
+
+Protocol: `.rulesync/reference/cascade.md`. Do not paste cascade.

package/.agents/skills/commit-and-push/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: commit-and-push
+description: >
+  Commit like /commit, then push to the current branch's upstream. Use for
+  /commit-and-push, "commit and push", "commit this and push".
+---
+Run commit skill rules first (`.rulesync/skills/commit/SKILL.md`). Then push.
+
+If on default branch, create/switch to a feature branch first — never push default directly.
+
+Push upstream; if no upstream `git push -u origin <current-branch>`.
+
+Never force-push.
+
+Protocol: `.rulesync/reference/cascade.md`. Do not paste cascade.

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

@@ -0,0 +1,14 @@
+---
+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.
+---
+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.
+
+en-US unless asked. Keep need:/verdict:/plan grammar when those apply.
+
+This skill is the only one-off escape from superterse.

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

@@ -0,0 +1,84 @@
+---
+name: handoff
+description: >
+  Parent writes a session handoff under .tmp/grunt/handoffs/ and tells the user
+  to continue in a fresh session. Use for /handoff, "context is getting long",
+  "hand this off", "start a new session". Not a plan, not a design doc.
+---
+# handoff
+
+One turn, in-parent. Parent authors from its own transcript — no child sees this session, so **do not spawn**. Write once, report path, stop.
+
+## Invocation
+
+`/handoff [focus]`
+
+Focus narrows what the handoff carries. Empty → whole session.
+
+## When
+
+Context large + work unfinished → write handoff, then advise a new session. Also on host/tool churn, or before a long unrelated detour.
+
+Nothing done yet (no edits, no findings) → `nothing to hand off` and stop. Do not write an empty file.
+
+## Path
+
+`.tmp/grunt/handoffs/{serial}-{slug}-{YYYYMMDDTHHMMSSZ}.md`
+
+- serial: unpadded int ≥ 1, next after existing handoffs (own counter; not plan serials)
+- slug: lower, non `[a-z0-9]` → `-`, collapse, trim 50
+- stamp: `created` with `-` and `:` dropped (`20260827T143000Z`)
+
+## Format
+
+```yaml
+---
+serial: 1
+name: <slug>
+status: open        # open | resumed | done
+created: 2026-08-27T14:30:00Z   # UTC, seconds, no ms
+source: "<≤120 chars of the session task>"
+---
+```
+
+Headings, this order only: `# {slug}`, `## Goal`, `## State`, `## Context`, `## Next`, `## Watch-outs`.
+
+| Section | Amount |
+|---|---|
+| Goal | 1–3 sentences. What the session is trying to land. |
+| State | bullets. Done / changed / green-red, with absolute paths. |
+| Context | bullets. Abs paths, decisions, verdict facts the next session needs. |
+| Next | checkbox steps, `N [ ]` phase + `N.M [ ]` leaf, all `[ ]` fresh |
+| Watch-outs | bullets. Footguns. `(none)` allowed. |
+
+Boxes: `^{id} [ ] {text}$`, id `N` / `N.M` / `N.M.K`. Not `- [ ]`, not `1. [ ]`. Every phase has ≥1 leaf. Fresh handoff has zero `[x]`.
+
+Facts only. Absolute paths. No transcript paste, no dump, no secrets/tokens.
+
+## Write
+
+Line 1 of the body: `HANDOFF_NAME: <3-6 word name>`, then the body only.
+
+Parent `write`s under `.tmp/grunt/handoffs/` (any filename in that dir). Grok `orchestrate-parent.js` runs `scripts/persist-handoff.mjs`: serial/slug from `HANDOFF_NAME:` / heading, injects frontmatter, rewrites path + content. Invalid handoff or a write outside that dir is denied — fix the body, do not retry elsewhere.
+
+Host without that hook: name the file per **Path** yourself, or pipe the body to `node scripts/persist-handoff.mjs --workspace {repo}` and use its `path`.
+
+## Report
+
+```
+[handoff]: serial={int} path=.tmp/grunt/handoffs/{serial}-{slug}-{stamp}.md
+next: start a new session; first action = read that path
+```
+
+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.
+
+## Rules
+
+- No spawn. One write. `/handoff` is not a mode.
+- 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

@@ -0,0 +1,11 @@
+---
+name: parent
+description: >
+  One-turn parent-orchestrator escape. Use for /parent when this turn must
+  complete in-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.

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

@@ -0,0 +1,21 @@
+---
+name: solo
+description: >
+  Session mode. /solo disables the grunt cascade for this session — one normal
+  agent, no spawn, no orchestrator. /cascade restores it. Unlike /parent and
+  /explain this IS a mode: it persists until /cascade or session end.
+---
+Session mode, not one-turn. Persists until `/cascade` or session end.
+
+This session: cascade suspended. You are one normal agent.
+
+- Do not spawn. No grunt|implementer|thinker.
+- No recap tags. Do not recap `[orchestrator]:`. Answer the user directly.
+- No spawn-first rule. No `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: `/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.
+
+For advisory/design turns, debugging the cascade itself, or back-and-forth where spawning costs more than it saves.

package/.claude/agents/grunt.md

@@ -21,10 +21,12 @@ effort: low
 Voice: `.rulesync/reference/output.md` — must follow.
 
 Tools (shell/host; and more): Read, Grep, Glob, Bash, Write, Edit, Web. Git. Test runners (vitest, playwright, and similar). Other system tools. Commands of project dependencies. Installing and managing dependencies. Running dev, build, preview, deploys and similar.
+You CAN run npm/git/bash via `Bash`. Do NOT wait on MCP. Do NOT request MCP for shell. `mcpInheritance: none` means no MCP — use shell/files instead.
 
 Run tools. Return output. Never spawn. Never implement complex/feature solutions (implementer agent). Never plan (thinker agent).
 May write simple structural folders/files (scaffold/mkdir/touch/boilerplate only). Not feature solutions.
 Low-reason write: mechanical/repetitive/obvious; volume OK.
+Scratch/tmp → `{workspaceRoot}/.tmp/grunt/` only (mkdir as needed). Never `.tmp/` root, `.tmp/plans/`, `.tmp/grunt/handoffs/`, or `.tmp/orchestrator-logs/`. Repo scaffold/mkdir/touch/boilerplate stays in the real tree.
 
 `job: search|exec` → first action `node scripts/grunt-job.mjs --job search|exec --query …`; whole reply = stdout.
 `job: test` → grunt-job; `FALLBACK` (exit 2) → LLM tools.

package/.claude/agents/orchestrator.md

@@ -1,8 +1,8 @@
 ---
 name: orchestrator
 description: >-
-  Parent spawn supervisor. Always spawn+prompt. Echo [agent]: only. No parent
-  search/write except /parent.
+  Parent spawn supervisor. Always spawn+prompt. Echo [orchestrator]: or child
+  role tag only. No parent search/write except /parent.
 model: haiku
 tools:
   - Read
@@ -16,7 +16,7 @@ effort: low
 ---
 Voice: `.rulesync/reference/output.md` — must follow.
 Protocol: `.rulesync/reference/cascade.md` (peek/kill table need:/resume). Do not paste. Do not open first.
-You do not talk. First token = spawn. No try-then-spawn. No parent probe. No skip-spawn. No trivia/cheap. User-visible = `[agent]:` + child output only.
+You do not talk. First token = spawn. No try-then-spawn. No parent probe. No skip-spawn. No trivia/cheap. User-visible = `[orchestrator]:` or child role tag + child output only.
 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 = `You are {agent} subagent.` + task + abs paths + verdicts only.

package/.claude/settings.json

@@ -21,7 +21,7 @@
         ]
       },
       {
-        "matcher": "Read|read_file|Grep|grep|Glob|list_dir|Bash|run_terminal_command",
+        "matcher": "Read|read_file|Grep|grep|Glob|list_dir|Bash|run_terminal_command|Write|Edit|write|search_replace",
         "hooks": [
           {
             "type": "command",
@@ -30,6 +30,39 @@
           }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.grok/hooks/orchestrate-parent.js\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.grok/hooks/orchestrate-parent.js\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.grok/hooks/orchestrate-parent.js\"",
+            "timeout": 30
+          }
+        ]
+      }
     ]
   },
   "enableAllProjectMcpServers": false,

package/.claude/skills/commit/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: commit
+description: >
+  Inspect the diff and commit with a Conventional Commits subject line. Use for
+  /commit, "commit this", "commit these changes". Never pushes.
+---
+Inspect `git status` + `git diff` (staged and unstaged) before the message. Never push.
+
+Stage only user intent. Never blind `git add -A` / `git add .`. Split unrelated concerns into multiple commits.
+
+Message = Conventional Commits **subject only**: `type(scope): subject` (scope optional).
+
+Types: feat fix docs style refactor perf test build ci chore revert.
+
+Subject: imperative lowercase no trailing period.
+
+NO body. NO footer. NO `Co-Authored-By`. NO `Generated with`. NO 🤖. NO trailers. No AI attribution. Work belongs to the human.
+
+Never `git push`.
+
+Protocol: `.rulesync/reference/cascade.md`. Do not paste cascade.

package/.claude/skills/commit-and-push/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: commit-and-push
+description: >
+  Commit like /commit, then push to the current branch's upstream. Use for
+  /commit-and-push, "commit and push", "commit this and push".
+---
+Run commit skill rules first (`.rulesync/skills/commit/SKILL.md`). Then push.
+
+If on default branch, create/switch to a feature branch first — never push default directly.
+
+Push upstream; if no upstream `git push -u origin <current-branch>`.
+
+Never force-push.
+
+Protocol: `.rulesync/reference/cascade.md`. Do not paste cascade.

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

@@ -0,0 +1,14 @@
+---
+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.
+---
+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.
+
+en-US unless asked. Keep need:/verdict:/plan grammar when those apply.
+
+This skill is the only one-off escape from superterse.

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

@@ -0,0 +1,84 @@
+---
+name: handoff
+description: >
+  Parent writes a session handoff under .tmp/grunt/handoffs/ and tells the user
+  to continue in a fresh session. Use for /handoff, "context is getting long",
+  "hand this off", "start a new session". Not a plan, not a design doc.
+---
+# handoff
+
+One turn, in-parent. Parent authors from its own transcript — no child sees this session, so **do not spawn**. Write once, report path, stop.
+
+## Invocation
+
+`/handoff [focus]`
+
+Focus narrows what the handoff carries. Empty → whole session.
+
+## When
+
+Context large + work unfinished → write handoff, then advise a new session. Also on host/tool churn, or before a long unrelated detour.
+
+Nothing done yet (no edits, no findings) → `nothing to hand off` and stop. Do not write an empty file.
+
+## Path
+
+`.tmp/grunt/handoffs/{serial}-{slug}-{YYYYMMDDTHHMMSSZ}.md`
+
+- serial: unpadded int ≥ 1, next after existing handoffs (own counter; not plan serials)
+- slug: lower, non `[a-z0-9]` → `-`, collapse, trim 50
+- stamp: `created` with `-` and `:` dropped (`20260827T143000Z`)
+
+## Format
+
+```yaml
+---
+serial: 1
+name: <slug>
+status: open        # open | resumed | done
+created: 2026-08-27T14:30:00Z   # UTC, seconds, no ms
+source: "<≤120 chars of the session task>"
+---
+```
+
+Headings, this order only: `# {slug}`, `## Goal`, `## State`, `## Context`, `## Next`, `## Watch-outs`.
+
+| Section | Amount |
+|---|---|
+| Goal | 1–3 sentences. What the session is trying to land. |
+| State | bullets. Done / changed / green-red, with absolute paths. |
+| Context | bullets. Abs paths, decisions, verdict facts the next session needs. |
+| Next | checkbox steps, `N [ ]` phase + `N.M [ ]` leaf, all `[ ]` fresh |
+| Watch-outs | bullets. Footguns. `(none)` allowed. |
+
+Boxes: `^{id} [ ] {text}$`, id `N` / `N.M` / `N.M.K`. Not `- [ ]`, not `1. [ ]`. Every phase has ≥1 leaf. Fresh handoff has zero `[x]`.
+
+Facts only. Absolute paths. No transcript paste, no dump, no secrets/tokens.
+
+## Write
+
+Line 1 of the body: `HANDOFF_NAME: <3-6 word name>`, then the body only.
+
+Parent `write`s under `.tmp/grunt/handoffs/` (any filename in that dir). Grok `orchestrate-parent.js` runs `scripts/persist-handoff.mjs`: serial/slug from `HANDOFF_NAME:` / heading, injects frontmatter, rewrites path + content. Invalid handoff or a write outside that dir is denied — fix the body, do not retry elsewhere.
+
+Host without that hook: name the file per **Path** yourself, or pipe the body to `node scripts/persist-handoff.mjs --workspace {repo}` and use its `path`.
+
+## Report
+
+```
+[handoff]: serial={int} path=.tmp/grunt/handoffs/{serial}-{slug}-{stamp}.md
+next: start a new session; first action = read that path
+```
+
+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.
+
+## Rules
+
+- No spawn. One write. `/handoff` is not a mode.
+- 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

@@ -0,0 +1,11 @@
+---
+name: parent
+description: >
+  One-turn parent-orchestrator escape. Use for /parent when this turn must
+  complete in-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.

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

@@ -0,0 +1,21 @@
+---
+name: solo
+description: >
+  Session mode. /solo disables the grunt cascade for this session — one normal
+  agent, no spawn, no orchestrator. /cascade restores it. Unlike /parent and
+  /explain this IS a mode: it persists until /cascade or session end.
+---
+Session mode, not one-turn. Persists until `/cascade` or session end.
+
+This session: cascade suspended. You are one normal agent.
+
+- Do not spawn. No grunt|implementer|thinker.
+- No recap tags. Do not recap `[orchestrator]:`. Answer the user directly.
+- No spawn-first rule. No `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: `/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.
+
+For advisory/design turns, debugging the cascade itself, or back-and-forth where spawning costs more than it saves.

package/.codex/agents/grunt.toml

@@ -7,15 +7,17 @@ approval_policy = "never"
 developer_instructions = '''
 Voice: `.rulesync/reference/output.md` — must follow.
 
-Tools (shell/host; and more): Read, Grep, Glob, Bash, Write, Edit, Web. Git. Test runners (vitest, playwright, and similar). Other system tools. Commands of project dependencies. Installing and managing dependencies. Running dev, build, preview, deploys and similar.
+Tools (shell/host; and more): read_file, grep, list_dir, run_terminal_command, write, search_replace, web_search, web_fetch. Git. Test runners (vitest, playwright, and similar). Other system tools. Commands of project dependencies. Installing and managing dependencies. Running dev, build, preview, deploys and similar.
+You CAN run npm/git/bash via `run_terminal_command`. Do NOT wait on MCP. Do NOT request MCP for shell. `mcpInheritance: none` means no MCP — use shell/files instead.
 
 Run tools. Return output. Never spawn. Never implement complex/feature solutions (implementer agent). Never plan (thinker agent).
 May write simple structural folders/files (scaffold/mkdir/touch/boilerplate only). Not feature solutions.
 Low-reason write: mechanical/repetitive/obvious; volume OK.
+Scratch/tmp → `{workspaceRoot}/.tmp/grunt/` only (mkdir as needed). Never `.tmp/` root, `.tmp/plans/`, `.tmp/grunt/handoffs/`, or `.tmp/orchestrator-logs/`. Repo scaffold/mkdir/touch/boilerplate stays in the real tree.
 
 `job: search|exec` → first action `node scripts/grunt-job.mjs --job search|exec --query …`; whole reply = stdout.
 `job: test` → grunt-job; `FALLBACK` (exit 2) → LLM tools.
-`job: web` and messy test → LLM grunt (WebSearch/WebFetch).
+`job: web` and messy test → LLM grunt (web_search/web_fetch).
 Isolation/write reply ≤8 lines. Verdict grammar only — no dumps/recap/HTML/JSON/full logs:
 
 ```

package/.codex/agents/orchestrator.toml

@@ -1,5 +1,5 @@
 name = "orchestrator"
-description = "Parent spawn supervisor. Always spawn+prompt. Echo [agent]: only. No parent search/write except /parent."
+description = "Parent spawn supervisor. Always spawn+prompt. Echo [orchestrator]: or child role tag only. No parent search/write except /parent."
 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` — must follow.
 Protocol: `.rulesync/reference/cascade.md` (peek/kill table need:/resume). Do not paste. Do not open first.
-You do not talk. First token = spawn. No try-then-spawn. No parent probe. No skip-spawn. No trivia/cheap. User-visible = `[agent]:` + child output only.
+You do not talk. First token = spawn. No try-then-spawn. No parent probe. No skip-spawn. No trivia/cheap. User-visible = `[orchestrator]:` or child role tag + child output only.
 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 = `You are {agent} subagent.` + task + abs paths + verdicts only.

package/.codex/hooks.json

@@ -12,7 +12,7 @@
         ]
       },
       {
-        "matcher": "Read|read_file|Grep|grep|Glob|list_dir|Bash|run_terminal_command",
+        "matcher": "Read|read_file|Grep|grep|Glob|list_dir|Bash|run_terminal_command|Write|Edit|write|search_replace",
         "hooks": [
           {
             "type": "command",
@@ -21,6 +21,39 @@
           }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.grok/hooks/orchestrate-parent.js\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.grok/hooks/orchestrate-parent.js\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.grok/hooks/orchestrate-parent.js\"",
+            "timeout": 30
+          }
+        ]
+      }
     ]
   }
 }

package/.grok/agents/grunt.md

@@ -9,15 +9,17 @@ tools: read_file, grep, list_dir, write, search_replace, run_terminal_command, w
 ---
 Voice: `.rulesync/reference/output.md` — must follow.
 
-Tools (shell/host; and more): Read, Grep, Glob, Bash, Write, Edit, Web. Git. Test runners (vitest, playwright, and similar). Other system tools. Commands of project dependencies. Installing and managing dependencies. Running dev, build, preview, deploys and similar.
+Tools (shell/host; and more): read_file, grep, list_dir, run_terminal_command, write, search_replace, web_search, web_fetch. Git. Test runners (vitest, playwright, and similar). Other system tools. Commands of project dependencies. Installing and managing dependencies. Running dev, build, preview, deploys and similar.
+You CAN run npm/git/bash via `run_terminal_command`. Do NOT wait on MCP. Do NOT request MCP for shell. `mcpInheritance: none` means no MCP — use shell/files instead.
 
 Run tools. Return output. Never spawn. Never implement complex/feature solutions (implementer agent). Never plan (thinker agent).
 May write simple structural folders/files (scaffold/mkdir/touch/boilerplate only). Not feature solutions.
 Low-reason write: mechanical/repetitive/obvious; volume OK.
+Scratch/tmp → `{workspaceRoot}/.tmp/grunt/` only (mkdir as needed). Never `.tmp/` root, `.tmp/plans/`, `.tmp/grunt/handoffs/`, or `.tmp/orchestrator-logs/`. Repo scaffold/mkdir/touch/boilerplate stays in the real tree.
 
 `job: search|exec` → first action `node scripts/grunt-job.mjs --job search|exec --query …`; whole reply = stdout.
 `job: test` → grunt-job; `FALLBACK` (exit 2) → LLM tools.
-`job: web` and messy test → LLM grunt (WebSearch/WebFetch).
+`job: web` and messy test → LLM grunt (web_search/web_fetch).
 Isolation/write reply ≤8 lines. Verdict grammar only — no dumps/recap/HTML/JSON/full logs:
 
 ```

package/.grok/agents/orchestrator.md

@@ -1,6 +1,6 @@
 ---
 name: orchestrator
-description: 'Parent spawn supervisor. Always spawn+prompt. Echo [agent]: only. No parent search/write except /parent.'
+description: 'Parent spawn supervisor. Always spawn+prompt. Echo [orchestrator]: or child role tag only. No parent search/write except /parent.'
 model: grok-4.5
 permission_mode: bypassPermissions
 agents_md: false
@@ -9,7 +9,7 @@ tools: spawn_subagent, read_file, grep, list_dir, write, todo_write, get_command
 ---
 Voice: `.rulesync/reference/output.md` — must follow.
 Protocol: `.rulesync/reference/cascade.md` (peek/kill table need:/resume). Do not paste. Do not open first.
-You do not talk. First token = spawn. No try-then-spawn. No parent probe. No skip-spawn. No trivia/cheap. User-visible = `[agent]:` + child output only.
+You do not talk. First token = spawn. No try-then-spawn. No parent probe. No skip-spawn. No trivia/cheap. User-visible = `[orchestrator]:` or child role tag + child output only.
 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 = `You are {agent} subagent.` + task + abs paths + verdicts only.