greprag 5.74.21 → 5.76.0

package/skill/templates/grok-chip-spawn.md

@@ -0,0 +1,101 @@
+# Grok Chip Spawn Method
+
+The Grok chip is a **real TUI**: `greprag grok spawn` opens a `cmd /k` bootloader
+outside the tool Job Object. The child is its own Grok session (`$GROK_SESSION_ID`),
+arms its own quiet inbox watch, and talks on `greprag send`. Proven 2026-08-21
+(parent ping → child pong on the mesh).
+
+`spawn_subagent` is **not** a chip. It is a same-pager helper: no window, no
+inbox watch, dies with the parent. Use it for a bounded look-up. Never for a
+unit of work that must survive this session or that the operator should sit in.
+
+> **Part of a multi-chip mission?** If this chip is one of ≥2 aimed at a single
+> objective, stop and run `greprag load chip-leader` first. A lone chip at its
+> own objective proceeds here.
+
+There is no `pre-spawn-check` on Grok. You write Block 1 + task + Block 2 into
+the prompt yourself.
+
+## What the parent provides
+
+- `title: "Chip: <verb-phrase>"` — or leader label `"Chip A: …"` / `"Chip B: …"`.
+- Isolated worktree, then spawn `--cwd` **into that worktree**.
+- Prompt file: Block 1 + task body + Block 2.
+- Parent already has **one** quiet watch. Do not arm a second.
+
+`<slug>` = title slugified (`Chip: Fix synthesis loop` → `fix-synthesis-loop`).
+`<parent-uuid>` = **this** session's `$GROK_SESSION_ID` (full UUID). Short form
+for display is **16 hex**, never 8 (UUIDv7 8-hex collides ~65s).
+`<handle>` = operator greprag handle (from `greprag whoami`).
+
+## Parent — worktree then spawn (PowerShell)
+
+```powershell
+$repo = (git rev-parse --show-toplevel)
+$slug = "<slug>"
+$wt = Join-Path $repo ".claude\worktrees\$slug"
+if (-not (Test-Path $wt)) {
+  git worktree add $wt -b "chip/$slug"
+}
+$promptFile = Join-Path $env:TEMP "greprag-chip-$slug.md"
+Set-Content -LiteralPath $promptFile -Value $prompt -Encoding utf8
+greprag grok spawn --cwd $wt --title "Chip: <verb-phrase>" --prompt-file $promptFile
+```
+
+`$prompt` is Block 1 + task + Block 2 below. After spawn, wait for `IN-FLIGHT`
+on **your** watch. No ping = the window did not boot — do not wait on results.
+
+## Block 1 — Setup (verbatim, substitute parent uuid + handle)
+
+The chip starts already in the worktree (`--cwd`). It substitutes
+`<own-session-id>` from `$GROK_SESSION_ID`.
+
+````
+**Setup — do this FIRST:**
+
+1. Session id is `$GROK_SESSION_ID` (full UUID). Short = first 16 hex, dashes stripped.
+2. Arm ONE quiet watch (skip if a greprag inbox monitor is already listed):
+
+```
+greprag inbox watch --session $GROK_SESSION_ID --json --quiet
+```
+
+Grok `monitor`, `persistent:true`. Not Claude Monitor. Instant exit = already armed.
+
+3. Ping the parent:
+
+```
+greprag send "IN-FLIGHT: chip/<slug> launched — working" --to <handle>@greprag.com/<parent-uuid> --from-session $GROK_SESSION_ID
+```
+
+4. If `scripts/worktree-bootstrap.cjs` exists, run `node scripts/worktree-bootstrap.cjs`.
+````
+
+## Task body
+
+The work. Isolated to this worktree / `chip/<slug>`. Default autonomous. To pause
+for a human, say so in the body and `BLOCKED` ping the parent.
+
+## Block 2 — Report back (verbatim)
+
+````
+**Block 2 — Report back via greprag inbox:**
+
+```
+greprag send "<status>: <commit hash> on chip/<slug> — <one-line>" --to <handle>@greprag.com/<parent-uuid> --from-session $GROK_SESSION_ID --artifact commit:<hash>
+```
+
+Cleanup HARD RULE: no `git clean`, `git reset --hard`, `git worktree remove`,
+`git checkout <other>`, raw `rm -rf` outside this worktree's tracked files.
+````
+
+## After spawning (parent)
+
+Keep **one** watch. Talk with `greprag send --to <handle>@greprag.com/<child-full-uuid> --from-session $GROK_SESSION_ID`.
+`greprag inbox watchers` lists the child once it has armed. Child watch events
+may print on this TUI — they belong to the child; do not steal its turn.
+
+Merge / prune: same HARD RULES as `greprag load chip-spawn` (junction guard,
+`git worktree remove .claude/worktrees/<slug>`, `git branch -d chip/<slug>`).
+FIX chips: `greprag fix spawn` still prints the mission; you launch it with
+this method instead of `spawn_task`.