Grok over ACP

Run Grok Build on this machine as a worker in the SDLC sense: a separate agent with its own transcript that you mint clean, resume by id, and never trust without verification. Transport is ACP, JSON-RPC over grok agent stdio, driven by the grok-acp command from packages/grok-acp in this repo. Stdlib Python, Linux only. If grok-acp is not on PATH, run packages/grok-acp/grok_acp.py from the checkout that holds this skill directory's real path, or install it as the package README says. This skill directory is usually a symlink.

Iron law

The operator picks Grok; you do not. Offloading is opt-in per ask. Exception: the credit-failure fallback in cursor-cloud-agents-when is pre-approved. Grok's summary is a claim, not evidence. Verify before you report.

Permissions (operator order, 2026-09-21)

Grok runs with maximum permissions, on purpose: --always-approve, _meta.yoloMode, sandbox off, and any permission request that still arrives is auto-approved. It runs as the same user, so it can read, write, run, push, and reach the network exactly as the operator can.

What still binds it: deny rules and hooks in ~/.grok/config.toml and ~/.claude/settings.json (Grok reads it). Project-level rules, hooks, and auto-loaded instructions apply only in a folder Grok already trusts; a fresh item worktree usually is not, so do not count on them. Nothing else. Scope is set by your prompt, so write the scope down.

Run it

GROK=grok-acp

# mint a clean worker for a work item
$GROK run --cwd <item worktree> --label <item-id>:builder --prompt-file <handoff.md>

# resume the same worker later: delta only
$GROK run --cwd <item worktree> --resume <item-id>:builder --prompt-file <delta.md>

One invocation is one prompt turn. Stdout is one JSON object; progress lines go to stderr. Start run in the background and read the result when notified; builds outlast a foreground shell call. --timeout defaults to 3600 seconds. On timeout or SIGTERM the client sends ACP session/cancel, waits up to 20 seconds, and exits 5; the session stays resumable. A SIGTERM before the prompt is sent stops the run with no turn spent. A label and a session each take one turn at a time: a second run gets busy (exit 2).

$GROK sessions prints the label registry, ~/.local/state/grok-acp/sessions.json. If GROK_ACP_STATE is set, the state directory is that path. The state directory and the run directories it creates are 0700. $GROK forget <label> drops a label; Grok keeps the session.

Result

SDLC fit

• Role. Grok is a builder unless the operator says otherwise. The verifier and the reviewer of that item are different agents and never see Grok's transcript. Do not read response.md or events.ndjson into their prompts. Give the verifier the ticket and the proving commands; give the reviewer the inputs pr-review names.
• One label per role per item. DER-12:builder is never reused on another item and never resumed to verify or review its own work.
• Mint = pack. The first prompt is the whole handoff: ticket, LLD slice, acceptance, paths, standards, the proving commands, and the repo rules that bind it. Tell it to read the repo AGENTS.md first. Grok cannot see this skills home, so pack the text or give the path.
• Resume = delta. What changed, what failed, what to do next. Do not re-send the spec.
• Branching is yours. Create the item branch and worktree yourself from the source Branches names; pass it as --cwd. Tell Grok to commit on that branch, never to push, and never to merge the item branch into anything. De-conflicting is still the builder's job: when project-main moves, resume the label with a delta that tells it to merge or rebase project-main into the item branch. Lands stay serialized and stay with the manager (Land path).
• Blockers and gates. Check the item's blockers before minting. Offloading the build skips no gate: Review and security still run.
• Fallback and overflow. Exit 3, or a session too long to be useful: --replace with a short handoff, per SDLC Fallback.

Handoff shape

You are the builder for <item-id> in <repo>. Read AGENTS.md first.

Goal:        <what done looks like>
Acceptance:  <from the ticket>
Design:      <LLD slice or path>
Scope:       <paths>. Do not touch <paths>.
Standards:   <language / test rules, packed or by path>
Prove it:    <exact commands that must pass>
Git:         commit on <branch>. Never push. Never merge <branch> into another
             branch or switch branches. Merge <base> into <branch> only when asked.

Finish with: files changed, commands run and their results, open risks.

After it returns

Load verify-before-done. You are the manager, not the verifier.

1. Smoke-check the worktree yourself: git status, git diff <base>..., and that the branch and git rule were kept. filesEdited misses shell-made changes. This smoke check is not the gate.
2. First pass: mint the item's verifier clean with the ticket and the proving commands. Later passes: resume that verifier_id with the delta. Never give it Grok's output.
3. verifier runs the proving commands.
4. Send verifier failures to the same Grok label as a delta.
5. At every step, take "tests pass" from the verifier, never from text.

Always

• State scope, do-not-touch paths, and the git rule in every mint.
• Keep secrets out of prompts; prompt.md is written to disk.
• Report to the operator what was offloaded, the label, and the evidence.

Ask first

• Offloading when the operator did not ask for Grok on this work.
• Pointing --cwd at a live host's config tree, $HOME, or /.
• Work that needs credentials the prompt would have to carry.

Never

• Treat ok: true as landed+verified. Run After it returns.
• Let one Grok session build and verify the same item. Mint a separate verifier.
• Feed Grok's transcript to a verifier or reviewer. Give each its Role inputs.
• Run two turns against the same session at once. Wait, then resume.
• Tighten or loosen the permission posture here without a new operator order; it is recorded above with its date. Ask the operator for one.

Red flags

• "Grok said the tests pass"
• "I'll resume the builder to double-check its own work"
• "New session each loop, it is simpler"
• "Let Grok merge it, it has the perms"