Large-task orchestration (reliable fan-out)

Grok self-parallelizes to cheaper models mainly on large tasks. For medium/large product work, force decomposition so work does not stay solo on the expensive frontier model.

Required decomposition (before coding)

1. Split the goal into N ≥ 2 disjoint workstreams with non-overlapping write scopes (paths, packages, or mesh/role ids).
2. Each stream gets:
   • Own worktree (isolation=worktree or git worktree add under ~/.grok/worktrees/…)
   • Own portless / dev port (never share a fixed port across jobs)
   • Own temp directory (never share /tmp/openclinxr_*.png or similar fixed names)
3. Prefer deepseek-v4-pro (bounded write) / deepseek-v4-flash (scout) via spawn_subagent or OPENCLINXR_WORKER=1 GROK_SUBAGENTS=1 grok -p … --model deepseek-v4-pro --yolo. Parent keeps orchestration + integration.
4. Parent integrates: verify, merge worktrees, update SSOT once — workers do not touch PROJECT_STATUS.md, docs/openclinxr/*registry*, docs/_archive/**, or AGENTS.md.

Worker session env (required for headless / --yolo)

export OPENCLINXR_WORKER=1
export GROK_SUBAGENTS=1
# Optional alias signal for hooks NO-OP only: GROK_SUBAGENT=1
# Bounded autonomy (prefer over blanket --yolo): --always-approve avoids hangs. --deny rules are
# the DETERMINISTIC control (blocks rm/push non-interactively); --sandbox workspace is BEST-EFFORT
# (fails open under some spawn contexts). --cwd is NOT a boundary. Real safety = --deny +
# intended-files-only. VERIFIED in agentic-eval permission-bounds.test.ts; formatWorkerHeadlessDispatchFlags().
grok -p "<scoped task>" --model deepseek-v4-pro \
  --always-approve --sandbox workspace --deny 'Bash(rm -rf *)' --deny 'Bash(git push *)' \
  --cwd <worktree> --max-turns 40

OPENCLINXR_WORKER=1 makes repo-mutating SessionStart hooks (docs hygiene auto-run, CEO rehydrate, post-slice Stop) NO-OP so workers stay in pathScope files. GROK_SUBAGENTS=1 exposes spawn_subagent in headless -p (without it the tool is absent — multi-level grok→deepseek tiering cannot fire). See formatWorkerHeadlessEnvPrefix in packages/openclinxr/agent-loop/src/grok-repo-agent-spawn.ts.

Per-job temp-file convention (anti-race)

Never use a fixed path like /tmp/openclinxr_skin_albedo_mixed.png across parallel jobs.

# Per-process unique root
export OPENCLINXR_JOB_TMP="${TMPDIR:-/tmp}/openclinxr-job-${USER:-u}-$$-$(date +%s)-${OPENCLINXR_JOB_ID:-job}"
mkdir -p "$OPENCLINXR_JOB_TMP"

# Per-mesh / per-artifact names
#   $OPENCLINXR_JOB_TMP/<meshId>_albedo.png
#   $OPENCLINXR_JOB_TMP/<meshId>_<stage>_<pid>.png
# Prefer mktemp when writing single files:
ALBEDO=$(mktemp "${OPENCLINXR_JOB_TMP}/${MESH_ID:-mesh}_albedo.XXXXXX.png")

Rules:

Ports (portless / dev servers)

• Each workstream claims a distinct port or portless identity.
• Pattern: derive from job id / pid (BASE_PORT + ($$ % 1000) or portless project name openclinxr-w-$$).
• Never hardcode a single shared 5173 / 8787 for parallel workers.

Fan-out recipe (parent)

1. List N streams with writeRoots + done_when.
2. Spawn N workers in parallel (background=true + isolation=worktree, or N headless OPENCLINXR_WORKER=1 GROK_SUBAGENTS=1 processes in distinct worktrees).
3. Wait / merge; run focused verify once.
4. Parent (CEO) updates PROJECT_STATUS.md + post-slice — not workers.

Skill cross-links

• Worker scoped session: .grok/skills/worker-scoped-session/SKILL.md
• Temp paths detail: .grok/skills/per-job-temp/SKILL.md
• Headless regen loop: .grok/skills/regen-score-report/SKILL.md
• Docs: ~/.grok/docs/user-guide/16-subagents.md (isolation/worktree), 14-headless-mode.md (--yolo, --max-turns), 20-background-tasks.md