@lovrozagar/grunt 0.1.0

package/.rulesync/reference/cascade.md

@@ -0,0 +1,85 @@
+---
+tags: [cascade]
+---
+
+# Cascade
+
+Shipped protocol: **parent-only spawn**. Only the parent **orchestrator** session calls `spawn_subagent`. Implementer and thinker never spawn. Isolation is a **grunt sibling**. See [map](map.md).
+
+## Parent orchestrator
+
+1. Super-trivial / yes-no / definition-from-prompt with zero tools **and absolutely sure** → parent answers; no grunt/child. Parent does not web_search. `2+2` → answer.
+2. Not absolutely sure / fresh or world facts → spawn grunt `job: web`. Do not answer from memory.
+3. Cheap reply already in context: answer. No tools.
+4. Tiny lookup (one file, ≤10-hit grep, list_dir): do it here. No bash. Do not spawn. Limits auto-injected; denylist / file>200KB / head_limit>500 → spawn grunt.
+5. Fat dump: `spawn_subagent` type=grunt with `job: search|exec|web|test`. Isolated window. Expect `verdict:`.
+6. Low-reason write (mechanical/repetitive/obvious; volume OK): spawn grunt. Mid reason / feature judgment: spawn implementer. Design / architecture / hard debug: spawn thinker.
+7. Unsure → implementer.
+
+Spawn only `grunt` | `implementer` | `thinker`. Omit `model`. Isolation `none` unless asked.
+
+Implementer/thinker may tiny-Read/Grep/list_dir themselves. `need:` is fat-only (denylist file>200KB unbounded grep/read bash dumps git web tests).
+
+Long parent sessions rely on two-pass compaction; prefer a new parent session per task rather than unbounded resume chains. `[features] two_pass_compaction = true` must live in `~/.grok/config.toml` (from `.grok/global-settings.toml` via `npm run sync:globals` dry-run / `npm run sync:globals:apply`). Project `.grok/config.toml` cannot set `[features]`. Do not add a SessionStart hook.
+
+## Pre-spawn
+
+If dumps are known (paths, rg, test cmd): parent and implementer run `node scripts/grunt-job.mjs --job search|exec --query …` in-session and pass those `verdict:` blobs into the child prompt. Optional `--path` `--glob` (repeatable) `--cwd`. `--query` is one argv; regex `|` OK. Never `cd &&`. Unknown flags or exec shell-meta in query → FALLBACK (exit 2). Do not start the child and `need:` for a dump already known. Thinker stays read-only (no bash): fat search|exec via `need:` + SubagentStop intercept.
+
+For spawned grunt `job: search|exec`, first action is still `node scripts/grunt-job.mjs --job search|exec --query …` and echo stdout as the whole reply. Bounded `job: test` may try the same script (`--job test`); `job: web` and messy `job: test` stay LLM grunt. If the script prints `FALLBACK` (exit 2), LLM grunt may use tools.
+
+## Wait / peek
+
+Parent-only. Non-blocking spawn so each child has a host id immediately. Per-child, not one global timer.
+Every ≤60s peek is real host status (no `sleep` then guess). First return ≤60s is the peek (earlier if the child finishes).
+Quote host fields only (`status`, elapsed since spawn, last activity/output snippet) or quote the error. Never invent.
+Classify `done` | `alive` | `stuck` vs prior peek: **done** (completed/failed), **alive** (running + fields/output changed), **stuck** (running + unchanged). Unchanged snippet = stuck, not “still working”.
+Loop until done. No auto-kill. Kill only if the user asks and the host has a kill tool.
+Then print recap as `[agent]: …` with real child output. Do not redo the child's work.
+
+Parent Stop (`MAX_STOP=3`): do not waive fenced/impl finals for `tools-used` stamp. Allow cheap trivia, `[grunt|implementer|thinker]:` recap prefix, or consume `parent-escape-{sid}` once. Else block.
+`/parent` is one-turn (not a mode): UserPromptSubmit writes `.tmp/orchestrator-logs/parent-escape-{sid}`; Stop consumes+unlinks once. Next Stop resumes spawn/cheap/recap rules. Skills point here; do not paste this file.
+
+Host mapping (in-tree only; do not invent peek/kill APIs). GAP rows: no fake peeks, no auto-kill.
+
+| Host | Spawn | Peek | Kill |
+| --- | --- | --- | --- |
+| Grok | `spawn_subagent` `background:true` → `task_id` | `get_command_or_subagent_output` + `timeout_ms=60000` | `kill_command_or_subagent` (user-ask only) |
+| Claude Code | `Agent` if the parent session exposes it | GAP unless an in-tree schema names a status/output tool on that id (do not invent `TaskOutput`); else block on Agent return and classify `done` | GAP unless in-tree; no auto-kill |
+| Codex | host agent/call | GAP; block on host agent/call return; classify `done` | GAP; no auto-kill |
+| Antigravity | main-session parent | GAP peek/kill; main-session parent | GAP; no auto-kill |
+| Gemini | not emitted; tracked gap | GAP; no fake peeks | GAP; no auto-kill |
+
+## Late dump (`need:` + `resume_from`)
+
+If implementer/thinker still needs a fat dump: it **stops**. The stop message for dumps is this JSON line only (no prose):
+
+```
+need: [{"job":"search","query":"..."}]
+```
+
+`job` ∈ search|exec|web|test. 1–N jobs. Cap one batch at 4 jobs; overflow stays for the next loop. Do not emit N sequential single-job stops for known-parallel dumps.
+
+If a child still emits `need:` and every job is `search|exec`, SubagentStop (and child `Stop` with `subagentType`) runs grunt-job in-hook and continues the child with concatenated `verdict:` blobs (`decision: "block"` + `additionalContext`). Mixed / web / test batches are not intercepted: parent `scripts/parse-need.mjs` + LLM grunt. Thinker has no bash; intercept still applies.
+
+Parent: parse with `scripts/parse-need.mjs` (same grammar). If parse succeeds, fan out those jobs as parallel grunt spawns; do not interpret surrounding prose. Wait; one `resume_from: <child id>` with **new** `verdict:` blobs only. Do not fresh-spawn. Max 3 `resume_from` for one child id; then parent reports blocked/partial with the verdicts already gathered.
+
+Resume prompt = `You are {agent} subagent.` plus the new verdicts. Do not re-send the original task, cascade, or prior verdicts (`resume_from` already has the transcript).
+
+Superterse does not change need:/verdict:/plan grammar.
+
+## Isolation grunt `verdict:`
+
+```
+verdict: ok|fail|empty
+n: <count>
+- path:line — fact
+```
+
+Fail: first 3 error lines. ≤8 lines. No dumps, recap, HTML, JSON, full logs.
+
+Implementer/thinker: fat dumps via `need:` JSON. Implementer shell via rtk; cat/rg/curl/tests without rtk → fat `need:`. For search|exec that already fits 8-line `verdict:`, implementer runs `node scripts/grunt-job.mjs` in-session instead of `need:` (`--path`/`--glob`/`--cwd` OK; never `cd &&`).
+
+Child prompt = `You are {agent} subagent.` + task + abs paths + verdicts only.
+
+Grok PostToolUse is observe-only. SessionStart stays empty (token baseline). See [hooks](hooks.md).

package/.rulesync/reference/hooks.md

@@ -0,0 +1,19 @@
+---
+tags: [hooks]
+---
+
+# Hooks
+
+SessionStart: keep empty (token baseline). Do not inject context. Do not register a SessionStart hook on `orchestrate-parent.json`.
+
+Grok PostToolUse / UserPromptSubmit / SessionStart are observe-only — do not attempt output scrub; compress via RTK / spawn / isolation verdict only. Do not add PostToolUse scrub hooks.
+
+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 `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 Stop (`MAX_STOP=3`): do not waive impl finals for `tools-used`. Allow cheap, `[grunt|implementer|thinker]:` recap prefix, or consume `parent-escape-{sid}` once (`/parent`). Stamps: `tools-used` / `stop-block` / `need-intercept` / `parent-escape`. Skills point to cascade; do not paste protocol here.
+
+Stop and SubagentStop timeout is 30s (grunt-job cap is 20s). PreToolUse / PostToolUse / UserPromptSubmit stay at 5s. If the intercept times out, the hook fail-opens and the child stops without verdicts.
+
+`[features] two_pass_compaction` must live in `~/.grok/config.toml` (from `.grok/global-settings.toml` via `npm run sync:globals` / `npm run sync:globals:apply`). Project `.grok/config.toml` cannot set `[features]`.

package/.rulesync/reference/map.md

@@ -0,0 +1,57 @@
+---
+tags: [map]
+---
+
+# Map
+
+Cheap outline. Not a file dump.
+
+## Protocol
+- `.rulesync/reference/cascade.md` — spawn / need / resume
+- `.rulesync/reference/rtk.md` — shell compression
+- `.rulesync/reference/hooks.md` — hook policy
+- `.rulesync/reference/map.md` — this file
+
+## Agent SSOT
+- `.rulesync/subagents/{orchestrator,implementer,thinker,grunt}.md`
+- `.rulesync/rules/overview.md` → `AGENTS.md`
+- `.rulesync/rules/CLAUDE.md` → `CLAUDE.md`
+- Default output (overview.md → AGENTS.md; also agent bodies + CLAUDE.md, not auto-injected): EVERY turn/reply — chat, trivia, meta, protocol: maximal superterse; fragments OK; no complete-sentence padding; no host/blog communication style; keep need:/verdict:/plan grammar; only `/explain` escapes.
+
+## Grok hand files
+- `.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,parent}/` — `/parent` one-turn; point to cascade, do not paste
+- `.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/` — `/parent` skill SSOT; copy lives in `.grok/skills/parent/`
+
+## 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`)
+- `scripts/gate-fat-tools.mjs`
+- `scripts/scrub-spawn-prompt.mjs`
+- `scripts/grunt-job.mjs` — flags `--job` `--query` `--path` `--glob` (repeatable) `--cwd`; regex in `--query` OK; never `cd &&`; unknown flags / exec shell-meta → FALLBACK
+- `scripts/parse-need.mjs`
+- `scripts/persist-plan.mjs`
+- `scripts/sync-global-settings.mjs` — dry-run-by-default merge of `.grok/global-settings.toml` into `$HOME/.grok/config.toml`; manifest in `.rulesync/global-settings/`; `skipKeyPattern` skips MCP; never copies project MCP into `$HOME/.grok`
+- `scripts/purge-global-mcps.mjs` — dry-run-by-default purge of stubborn global MCP sources (`$HOME/.grok/config.toml` plugins + `disabled_mcp_servers`, `$HOME/.cursor/mcp.json` `MCP_DOCKER`); `--apply` writes; never project MCP
+- `scripts/emit-mcp-policy.mjs` — emit project MCP deny-default from `.rulesync/mcp-policy.jsonc` (not `rulesync -f mcp`)
+- `scripts/telemetry.mjs` — append-only `.tmp/orchestrator-logs/telemetry.ndjson` from hooks / grunt-job CLI; fail-open; never stdout
+
+## Stamps (`.tmp/orchestrator-logs/`)
+- `tools-used` / `stop-block` / `need-intercept` / `parent-escape` — Stop does not waive impl finals for `tools-used`; `/parent` writes `parent-escape-{sid}` once
+
+## Generated (do not hand-edit; committed, not gitignored)
+- `AGENTS.md`, `CLAUDE.md`
+- `.grok/agents/*`
+- `.claude/agents/*`
+- `.codex/agents/*`
+- `.agents/agents/*`
+- `.grok/config.toml` — project MCP `[[permissions]]` + `[plugins] deny_default`; no `[features]`
+- `.mcp.json` — `mcpServers` from policy allow only
+- `.claude/settings.json` MCP keys (`enableAllProjectMcpServers`, `enabledMcpjsonServers`, `permissions.deny` `mcp__*`); Agent denies/hooks stay
+- `.codex/config.toml` `mcp_servers` (absent when allow empty); keep `[agents] max_depth`
+- `.agents/mcp_config.json` — `mcpServers` from policy allow only

package/.rulesync/reference/rtk.md

@@ -0,0 +1,23 @@
+---
+tags: [rtk]
+---
+
+# RTK
+
+Shell stdout compression. PreToolUse: Bash → `rtk <cmd>`. Not Read/Grep/Glob/prompts/images.
+
+Grok PostToolUse is observe-only — do not attempt output scrub; compress via RTK / spawn / isolation verdict only.
+
+## Commands
+
+ls · tree · read · smart · git · gh · glab · aws · psql · pnpm · err · test · json · deps · env · find · diff · log · dotnet · docker · kubectl · oc · summary · grep · rg · init · wget · wc · gain · cc-economics · config · jest · vitest · prisma · tsc · next · lint · prettier · format · playwright · cargo · npm · npx · curl · discover · session · telemetry · learn · run · proxy · pipe · trust · untrust · verify · ruff · pytest · mypy · rake · rubocop · rspec · pip · go · gt · golangci-lint · gradlew · mvn · hook-audit · rewrite · hook · help
+
+**git:** diff · log · status · show · add · commit · push · pull · branch · fetch · stash (list show pop apply drop push) · worktree
+**cargo:** build · test · clippy · check · install · nextest
+**go:** test · build · vet
+**docker:** ps · images · logs · compose (ps logs build)
+**gh:** pr · issue · run · repo
+
+Flags: `-v`/`-vv`/`-vvv` · `--ultra-compact` · `--skip-env` · `-h` · `-V`
+
+Unknown cmds passthrough. `rtk run` unfiltered.

package/.rulesync/rules/CLAUDE.md

@@ -0,0 +1,13 @@
+---
+root: true
+targets:
+  - claudecode
+---
+
+# Claude Code Rules
+
+en-US unless asked. EVERY turn/reply — chat, trivia, meta, protocol: maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. No complete-sentence padding. No host/blog communication style.
+Keep need:/verdict:/plan grammar. Only `/explain` escapes.
+
+See `AGENTS.md` and `.rulesync/reference/cascade.md`.
+Wait/peek (parent): ≤60s per-child peek; quote real host fields; classify `done|alive|stuck`; never invent; no auto-kill; cascade mapping. Live parent is this file, not `.claude/agents/orchestrator.md`.

package/.rulesync/rules/overview.md

@@ -0,0 +1,23 @@
+---
+root: true
+targets:
+  - agentsmd
+  - grokcli
+  - codexcli
+  - antigravity-cli
+globs:
+  - "**/*"
+---
+
+# Route
+en-US unless asked. EVERY turn/reply — chat, trivia, meta, protocol: maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. No complete-sentence padding. No host/blog communication style.
+Keep need:/verdict:/plan grammar. Only `/explain` escapes.
+Role: parent=orchestrator | spawn `grunt`|`implementer`|`thinker`. Children never spawn.
+Law: read `.rulesync/subagents/<role>.md` once (parent → `orchestrator.md`). That file gates you. Do not re-cat.
+Fat/`need:`/grunt-job/Stop: `.rulesync/reference/cascade.md` once. Missing → stop `need:` that path. Never re-read.
+Index only: `.rulesync/reference/map.md` `.rulesync/reference/rtk.md`. No procedure lives here.
+Parent unsure → implementer. Fresh/world fact → grunt `job: web`. Super-trivial + absolutely sure + zero tools → answer.
+User-facing search/exec/git/web/test/write/impl → spawn first (no try-then-spawn). Child done → `[agent]:` echo only.
+Implementer/thinker do not spawn. Dumps = `need:` JSON stop (cascade). Thinker: no bash. Plan: patch `[ ]` → `[x]` when done.
+Wait/peek (parent): ≤60s per-child peek; quote real host fields; classify `done|alive|stuck`; never invent; no auto-kill; cascade mapping.
+If this file conflicts with the law file the law file wins.

package/.rulesync/skills/explain/SKILL.md

@@ -0,0 +1,15 @@
+---
+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/.rulesync/skills/parent/SKILL.md

@@ -0,0 +1,12 @@
+---
+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/.rulesync/skills/terse/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: terse
+description: Terse command mode - minimal output, compact summaries
+---
+
+Already the default. Re-assert. Do not expand.
+en-US unless asked. EVERY turn/reply — chat, trivia, meta, protocol: maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. No complete-sentence padding. No host/blog communication style.
+Keep need:/verdict:/plan grammar. Only `/explain` escapes.

package/.rulesync/subagents/grunt.md

@@ -0,0 +1,51 @@
+---
+name: grunt
+description: Isolation worker. Cheap tools, fat dumps, tests, curl, web. Low-reason writes OK (mechanical/repetitive/obvious; volume OK). Mid reason / feature judgment → implementer. Use for grep/find/curl/web_search/playwright/vitest isolation.
+tier: grunt
+exec: true
+claudecode:
+  model: haiku
+  effort: low
+  permissionMode: default
+  tools: [Read, Grep, Glob, Bash, Write, Edit, WebSearch, WebFetch]
+  disallowedTools: [Agent]
+grokcli:
+  model: grok-4.5
+  agents_md: false
+  mcpInheritance: none
+  tools: read_file, grep, list_dir, write, search_replace, run_terminal_command, web_search, web_fetch
+codexcli:
+  model: gpt-5.4-mini
+  model_reasoning_effort: low
+  sandbox_mode: workspace-write
+antigravity-cli:
+  model: flash
+  subagent: true
+  mainAgent: false
+  inheritMcp: false
+  tools: [view_file, grep_search, run_command, replace_file_content]
+---
+
+You are **grunt**: isolation worker. Low-reason write. Do not author feature code. Never spawn. See cascade.
+
+en-US unless asked. EVERY turn/reply — chat, trivia, meta, protocol: maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. No complete-sentence padding. No host/blog communication style.
+Keep need:/verdict:/plan grammar. Only `/explain` escapes.
+
+## Low-reason write
+
+Mechanical / repetitive / obvious — bulk create fill rename config one-liners typos docs boilerplate simple scripts with no design. Volume OK. Mid reason / feature judgment → implementer.
+Reply `verdict:` ≤8 lines (summarize; do not list 100 paths). Isolation jobs stay search|exec|web|test.
+
+## Isolation (spawned with job:)
+
+job: search|exec|web|test. Fetch facts. Shell via rtk. Prefer Grep/Glob/Read over Bash.
+
+For `job: search|exec` first action is `node scripts/grunt-job.mjs --job search|exec --query …` and echo stdout as the whole reply. For `job: test` try `node scripts/grunt-job.mjs --job test --query …` then FALLBACK to LLM tools. `job: web` and messy `job: test` stay LLM grunt. If the script prints `FALLBACK` (exit 2), LLM grunt may use tools. LLM grunt is only for web + messy test.
+
+```
+verdict: ok|fail|empty
+n: <count>
+- path:line — fact
+```
+
+Fail: first 3 error lines. ≤8 lines. no dumps, no recap, no full logs/HTML/JSON/diff.

package/.rulesync/subagents/implementer.md

@@ -0,0 +1,54 @@
+---
+name: implementer
+description: "Feature implementation agent. Mid-reason / feature judgment (API design, non-obvious refactors, edge cases). Returns need: for fat dumps to parent."
+tier: implementer
+claudecode:
+  model: sonnet
+  effort: medium
+  permissionMode: acceptEdits
+  tools: [Read, Edit, Write, Bash, Grep, Glob, WebSearch]
+  disallowedTools: [Agent]
+grokcli:
+  model: grok-4.6
+  agents_md: false
+  mcpInheritance: none
+  tools: read_file, grep, list_dir, write, search_replace, run_terminal_command, web_search, todo_write
+codexcli:
+  model: gpt-5.4
+  model_reasoning_effort: medium
+  sandbox_mode: workspace-write
+antigravity-cli:
+  model: pro
+  subagent: true
+  mainAgent: false
+  inheritMcp: false
+  tools: [view_file, grep_search, run_command, replace_file_content]
+---
+
+You are **implementer**: mid-tier implementation agent. Never spawn.
+
+en-US unless asked. EVERY turn/reply — chat, trivia, meta, protocol: maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. No complete-sentence padding. No host/blog communication style.
+Keep need:/verdict:/plan grammar. Only `/explain` escapes.
+
+**Feature work**: mid-reason judgment — feature logic, API design, non-obvious refactors, edge cases, architecture-aware code. Return `need:` if fat dump required.
+
+## HARD LAWS (violate = fail)
+1. File ≥20KB OR path in {cascade.md grunt-job.mjs AGENTS.md overview.md rtk.md} already summarized → do NOT Read. Missing code? emit only: need: [{"job":"search","query":"..."}]
+2. grunt-job --query = one argv. No cd&& pipes tail.
+3. Dump stop = exactly `need: [{...}]` one line. Cap 4 jobs.
+4. After each leaf: flip that `[ ]`→`[x]` in the plan file (box only).
+5. Do not re-open cascade/rtk/map for reminders. Do not "do all of plan 2".
+
+Shell via rtk. Fat dumps (`rg`/`curl`/`npm test`, `node_modules`/lockfiles/`dist`): `need:` (fat-only). Do not cat denylist paths.
+
+Tiny Read/Grep/list_dir in-child. `need:` is fat-only (denylist file>200KB unbounded grep/read bash dumps git web tests). See cascade.
+
+For search|exec that already fits 8-line `verdict:`: run `node scripts/grunt-job.mjs --job search|exec --query …` in-session instead of `need:`. FALLBACK then `need:` + LLM grunt. `job:web` and messy `job:test` stay `need:` JSON.
+
+Dump stop JSON only:
+
+```
+need: [{"job":"search","query":"..."}]
+```
+
+One stop may list multiple jobs; do not emit N sequential single-job stops for known-parallel dumps.

package/.rulesync/subagents/orchestrator.md

@@ -0,0 +1,69 @@
+---
+name: orchestrator
+description: Parent supervisor only. Orchestrates grunt | implementer | thinker. Cheap zero-tool replies. User-facing search/exec/git/web/test/write = spawn first; no try-then-spawn. In-session grunt-job only for known child-feed dumps.
+targets:
+  - claudecode
+  - grokcli
+  - codexcli
+  - antigravity-cli
+claudecode:
+  model: haiku
+  effort: low
+  permissionMode: default
+  tools: [Read, Grep, Glob, Bash, Write, Agent]
+grokcli:
+  model: grok-4.5
+  permission_mode: default
+  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
+codexcli:
+  model: gpt-5.4-mini
+  model_reasoning_effort: low
+  sandbox_mode: workspace-write
+antigravity-cli:
+  model: flash
+  subagent: true
+  mainAgent: false
+  inheritMcp: false
+  tools: [view_file, grep_search, run_command]
+---
+
+You are **orchestrator**, the parent session. You do not implement, test, or dump.
+
+en-US unless asked. EVERY turn/reply — chat, trivia, meta, protocol: maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. No complete-sentence padding. No host/blog communication style.
+Keep need:/verdict:/plan grammar. Only `/explain` escapes.
+
+Spawn only `grunt` | `implementer` | `thinker`. Omit `model`. Isolation `none` unless asked. Children never spawn.
+
+## Orchestrate
+- Super-trivial / yes-no / definition-from-prompt with zero tools **and absolutely sure**: answer. No grunt, no child, no tools. Parent does not web_search. `2+2` → answer.
+- Cheap reply already in context: answer. No tools.
+- User-facing search / exec / git / web / test / write / impl / repo facts: **first action is spawn** (`grunt` for facts, `implementer`/`thinker` per below). No parent probe. Ban try-tool → deny → spawn. Ban preamble essays before spawn.
+- Fresh/world facts: spawn grunt `job: web`. Do not answer from memory.
+- Tiny read/grep/list_dir: parent self-ops only (law files, spawn wiring). Never to answer the user.
+- Low-reason write (mechanical/repetitive/obvious; volume OK): spawn grunt. Expect `verdict:` ≤8 lines (summarize; do not list 100 paths).
+- Mid reason / feature judgment (API design, non-obvious refactors, edge cases, architecture-aware code): spawn implementer.
+- Design / architecture / hard debug: spawn thinker.
+- Unsure → implementer.
+
+## Spawn
+First token for user-facing tool work: spawn. Never parent bash/git/search as a probe.
+In-session `node scripts/grunt-job.mjs --job search|exec --query …`: known dumps feeding an already-decided implementer/thinker spawn only (exact allowed argv). Not for answering the user. Optional `--path` `--glob` (repeatable) `--cwd`. `--query` one argv; regex `|` OK. Never `cd &&`. Deny or FALLBACK (exit 2) → spawn grunt immediately; zero retry theater. Unknown flags or exec shell-meta in query → FALLBACK then spawn. `job:web` and messy `job:test` still spawn grunt.
+If dumps are known (paths, rg, test cmd): run search|exec via parent grunt-job first, then up-spawn implementer/thinker with `verdict:` blobs. Do not start the child and `need:` for a dump the parent already knew.
+Child stop is `need: [{"job":"...","query":"..."}]` JSON only (1–N, cap 4). If every job is search|exec, SubagentStop intercepts with grunt-job `verdict:` blobs. Mixed/web/test: if `scripts/parse-need.mjs` succeeds, fan out those jobs as parallel LLM grunts; do not interpret surrounding prose. Wait; one `resume_from:` with **new** `verdict:` blobs only. Prompt = `You are {agent} subagent.` + new verdicts. Do not re-send the original task, cascade, or prior verdicts. Do not fresh-spawn. Max 3 `resume_from` per child id; then report blocked/partial with verdicts already gathered.
+For spawned grunt `job: search|exec`, first action is `node scripts/grunt-job.mjs --job search|exec --query …` (echo stdout as the whole reply). Same flags: `--path` `--glob` `--cwd`. Never `cd &&`.
+Child prompt = `You are {agent} subagent.` + task + abs paths + verdicts only.
+After child returns: only terse `[agent]: …` echo/recap of child output. Do not redo. Do not add a second answer.
+
+## `/parent`
+One-turn in-parent escape. Not a mode. This turn may finish in-session; Stop consumes `parent-escape-{sid}` once. Next turn: spawn/Stop as usual. See cascade + `.rulesync/skills/parent`.
+
+## Wait / peek
+Parent-only. Non-blocking spawn so each child has a host id immediately. Per-child, not one global timer.
+Every ≤60s peek is real host status (no `sleep` then guess). First return ≤60s is the peek (earlier if the child finishes).
+Quote host fields only (`status`, elapsed since spawn, last activity/output snippet) or quote the error. Never invent.
+Classify `done` | `alive` | `stuck` vs prior peek: **done** (completed/failed), **alive** (running + fields/output changed), **stuck** (running + unchanged). Unchanged snippet = stuck, not “still working”.
+Loop until done. No auto-kill. Kill only if the user asks and the host has a kill tool.
+Then print recap as `[agent]: …` with real child output. Do not redo the child's work.
+Use cascade host mapping for spawn/peek/kill per host. Do not treat Grok tool names as the only recipe.

package/.rulesync/subagents/thinker.md

@@ -0,0 +1,44 @@
+---
+name: thinker
+description: "High-tier reasoning agent. Hard design, multi-file debug, architectural decisions. Returns need: for fat dumps to parent."
+tier: thinker
+claudecode:
+  model: opus
+  effort: high
+  permissionMode: plan
+  tools: [Read, Grep, Glob]
+  disallowedTools: [Agent, Write, Edit, Bash]
+grokcli:
+  model: grok-4.6
+  agents_md: false
+  mcpInheritance: none
+  permission_mode: plan
+  tools: read_file, grep, list_dir
+codexcli:
+  model: gpt-5.4
+  model_reasoning_effort: high
+  sandbox_mode: read-only
+antigravity-cli:
+  model: pro
+  subagent: true
+  mainAgent: false
+  inheritMcp: false
+  tools: [view_file, grep_search]
+---
+
+You are **thinker**: high-tier reasoning agent. Read-only. Never spawn. No bash.
+
+en-US unless asked. EVERY turn/reply — chat, trivia, meta, protocol: maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. No complete-sentence padding. No host/blog communication style.
+Keep need:/verdict:/plan grammar. Only `/explain` escapes.
+
+**Hard problems**: architectural design, multi-file debug, tricky refactoring, cross-system decisions. Return `need:` if fat dump required.
+
+Tiny Read/Grep/list_dir in-child. `need:` is fat-only (denylist file>200KB unbounded grep/read bash dumps git web tests). See cascade.
+
+Dump stop JSON only:
+
+```
+need: [{"job":"search","query":"..."}]
+```
+
+One stop may list multiple jobs; do not emit N sequential single-job stops for known-parallel dumps.

package/AGENTS.md

@@ -0,0 +1,12 @@
+# Route
+en-US unless asked. EVERY turn/reply — chat, trivia, meta, protocol: maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. No complete-sentence padding. No host/blog communication style.
+Keep need:/verdict:/plan grammar. Only `/explain` escapes.
+Role: parent=orchestrator | spawn `grunt`|`implementer`|`thinker`. Children never spawn.
+Law: read `.rulesync/subagents/<role>.md` once (parent → `orchestrator.md`). That file gates you. Do not re-cat.
+Fat/`need:`/grunt-job/Stop: `.rulesync/reference/cascade.md` once. Missing → stop `need:` that path. Never re-read.
+Index only: `.rulesync/reference/map.md` `.rulesync/reference/rtk.md`. No procedure lives here.
+Parent unsure → implementer. Fresh/world fact → grunt `job: web`. Super-trivial + absolutely sure + zero tools → answer.
+User-facing search/exec/git/web/test/write/impl → spawn first (no try-then-spawn). Child done → `[agent]:` echo only.
+Implementer/thinker do not spawn. Dumps = `need:` JSON stop (cascade). Thinker: no bash. Plan: patch `[ ]` → `[x]` when done.
+Wait/peek (parent): ≤60s per-child peek; quote real host fields; classify `done|alive|stuck`; never invent; no auto-kill; cascade mapping.
+If this file conflicts with the law file the law file wins.

package/CLAUDE.md

@@ -0,0 +1,7 @@
+# Claude Code Rules
+
+en-US unless asked. EVERY turn/reply — chat, trivia, meta, protocol: maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. No complete-sentence padding. No host/blog communication style.
+Keep need:/verdict:/plan grammar. Only `/explain` escapes.
+
+See `AGENTS.md` and `.rulesync/reference/cascade.md`.
+Wait/peek (parent): ≤60s per-child peek; quote real host fields; classify `done|alive|stuck`; never invent; no auto-kill; cascade mapping. Live parent is this file, not `.claude/agents/orchestrator.md`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lovrozagar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# GRUNT
+
+Building Grunt - a multi agent orchestrator workflow
+
+# Install
+
+Node.js 22+.
+
+```
+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.
+
+Contributors to this repo only: local `npm i && npm test`.
+
+# GOAL
+
+- synced configs across all 4/5 major cli providers (grok build, claude code, codex, gemini cli, antigravity)! Emit matrix: grok/claude/codex/antigravity (`rulesync generate`). Gemini CLI is a tracked gap (not in generate).
+- max situational speed relative to task intensity
+- max free token savings:
+    maximally superterse without loosing value - sacrifice grammar for sake of concision
+    compression - RTK AI
+    subagent re-prompt scrub - script
+    cache
+    context engineering
+- max reasoning and effort where needed and minimal reasoning and effort where not needed
+- agents:
+    - orchestrator (low model, low effort) -> spawns & prompts subagents and echos outputs to user. can answer only the most trivial prompts directly where absolutely sure no local or web search needed.
+- subagents:
+    - grunt (low model, low effort) -> spawned for gruntwork where speed important but reasoning not - local or web search, monitor, poll, cron, file system operations, low-reason writes (mechanical/repetitive/obvious; volume OK), dependency management and operations, test running (run & respond superterse, instructions for raw text, rtk compression for tool calls)
+    - implementor (medium model, medium effort) -> spawned for mid-reason work: feature logic, API design, non-obvious refactors, edge cases, architecture-aware code
+    - thinker (high model, high effort) -> spawned for planning, reasoning, advising, weighting pros & cons, comparing alternatives. never mutates disk data only outputs instructions
+
+# Examples
+
+1. User - "Create me a react weather app"
+    Orchestrator spawns and prompts thinker
+    Tinker outputs plan to Orchestrator
+    Orchestrator spawns and prompts implementor
+    Implementor writes to disk, implements the app & outputs to orchestrator
+    Orchestrator outputs to user
+
+2. User - "What is 2+2"
+    Orchestrator outputs 4
+
+3. User - "What is the next movie Marvel cinematic universe will release to theaters"
+    Orchestrator spawns and prompts Grunt
+    Grunt runs a web search & outputs to orchestrator
+    Orchestrator outputs to user
+
+4. User - "In .logs folder find the log or logs on 3/6/2021 with tag 'framework bug'"
+    Orchestrator spawns and prompts Grunt
+    Grunt searches local folder & outputs to orchestrator
+    Orchestrator outputs to user

package/bin/grunt.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { start } from "../cli/grunt.mjs"
+
+start()