Assemble Grok Surgical Team (Parallel)

When invoked, execute the following steps in order.

Step 1: Quick Project Survey

Read just enough to understand the work ahead:

• Project name / primary language / framework (from README, package.json, Cargo.toml, pyproject.toml, etc.)
• Recent activity: git log --oneline -5 and current branch
• Presence of tests/, docs/, AGENTS.md, CLAUDE.md, or similar
• Any obvious large modules or risky areas from the top-level structure

Do not do a full orientation. This skill is about getting the team spawned quickly.

Record a one-paragraph summary for use in subagent prompts.

Step 2: Decide the Team Composition

Ask the user one focused question:

I'll spawn the core surgical team now (Surgeon = you + Copilot + Tester).

Do you want any additional teammates?

• Language Lawyer — for tricky language, framework, or version edge cases
• Editor — for documentation-heavy work
• Toolsmith — if you need new automation or scripts
• Program Clerk — if the codebase needs reorganization alongside the work

Reply with the roles to add, or say "default" (or just "go") to proceed with Copilot + Tester only.

Wait for the user's explicit response before continuing.

Core team (always spawned):

• Copilot (read-only review agent)
• Tester (adversarial test agent, runs in isolated worktree)

Step 3: Initialize the Shared Task List

Use the todo_write tool to create the initial shared task list.

Use these task tags so roles know what to claim:

• [implement] — Surgeon claims these (you)
• [review] — Copilot claims these (depend on corresponding [implement])
• [test] — Tester claims these (depend on corresponding [implement])
• [research] — Language Lawyer claims these (if spawned)
• [docs] — Editor claims these (if spawned)
• [tooling] — Toolsmith claims these (if spawned)
• [structure] — Program Clerk claims these (if spawned)

For every significant piece of work identified in the survey, create at least:

• One [implement] task
• One dependent [review] task
• One dependent [test] task

Add clear acceptance criteria on the implement tasks. Link dependencies explicitly in the task descriptions.

Example structure (adapt to actual project):

- [implement] Core feature X (acceptance: ... )  owner: Surgeon
  - [review] Review feature X                        owner: Copilot   (blocked until parent done)
  - [test]  Test feature X                           owner: Tester    (blocked until parent done)

Call todo_write now with the initial list. This becomes the single source of truth for the whole team.

Step 4: Spawn the Team (Parallel)

Spawn all selected teammates in a single response using parallel spawn_subagent tool calls — each with the teammate's full task in one shot. There is no lightweight-first-turn/resume-turn split: give each teammate everything it needs up front (project summary, todos, file ownership, the actual task) and let it run to completion in the background.

Why direct dispatch

Spawn brooks-copilot, brooks-tester, and brooks-language-lawyer directly by subagent_type, with their full task in the initial prompt — no general-purpose indirection and no lightweight-first-turn/resume_from handoff. resume_from is kept only as an optional follow-up mechanism after a subagent completes (see Monitoring below).

The real spawn_subagent parameters

Per Grok's own subagent documentation:

capability_mode is not a spawn_subagent parameter. spawn_subagent's real parameters are exactly the six above; do not include capability_mode in spawn JSON — it does nothing there. A role's default capability comes from its agent type and any [subagents.roles.<name>].default_capability_mode set in .grok/config.toml. This repo doesn't set that, since the working restriction mechanism here is frontmatter tools: (see the Copilot/Language Lawyer notes below).

Common Rules for All Spawns

• Set background: true.
• Give each teammate its full task in the initial prompt — project summary, the specific todo item(s) it owns, file ownership boundaries, and the concrete task (spec/diff/question to investigate). Don't hold anything back for a later resume.
• Include the current todo snapshot (or tell it to read the live list via todo_write).
• Tell it to claim its tagged tasks at the start of its run.
• Point it at its role contract (.grok/agents/brooks-*.md, kept in sync with the cross-platform skill of the same name) as a one-line reminder — it isn't required reading before acting, since the agent definition's body already governs the subagent's behavior, but it's a cheap, harmless pointer if the teammate wants to double check a protocol detail.

File Ownership Rules (Include in Every Prompt)

• Copilot: Read-only across the entire repo. Never edits source. Can update todos.
• Tester: Owns tests/, **/*.test.*, **/*.spec.*, and test utilities. May run commands and edit only within that scope. Works in an isolated worktree.
• Language Lawyer: Read-only research. May use web search and fetch. Never edits files.
• Editor: Owns docs/, README*, *.md (except code-adjacent notes), and documentation sources.
• Toolsmith: Owns scripts/, tooling configs, Makefiles, and new automation. Every tool must have --help and tests.

• Program Clerk: Proposes structure changes only. Executes renames/refactors only after Surgeon approval via todo or explicit message.

  (Clarification for Editor: "code-adjacent notes" means scratch notes, TODO markers, or similar embedded alongside source code or in implementation directories. Pure project documentation (top-level and docs/ READMEs, CHANGELOG, specs, AGENTS.md-style files, and other standalone *.md) belongs to Editor. When in doubt on a *.md file, the Surgeon decides and records the assignment in the todo list.)

To support the checklist in practice, include a "Current writers" note in the initial todo_write snapshot and in every spawn prompt's "Current todos" section (e.g. "Writers active: none — Tester worktree pending apply"). This makes the live state visible to all teammates.

Copilot Spawn (Always)

Spawn brooks-copilot directly with its full review task — no general-purpose indirection, no resume needed. Its role contract is .grok/agents/brooks-copilot.md (kept in sync with the cross-platform copilot skill); that definition's body governs its behavior once spawned. Its tools: frontmatter is a confirmed, real hard restriction (write and edit tools are genuinely unavailable to it) — the only Brooks role on Grok Build with an actually-enforced read-only boundary rather than a prompt-level convention.

{
  "description": "Brooks Copilot — design-intent review for [project]",
  "subagent_type": "brooks-copilot",
  "background": true,
  "prompt": "You are the Copilot on the surgical team for [PROJECT].\n\n[project summary]\n\nYour role contract is `.grok/agents/brooks-copilot.md` (kept in sync with the cross-platform `copilot` skill).\n\nClaim your `[review]` tasks via `todo_write`, then review [WHAT_WAS_IMPLEMENTED] against [SPEC_OR_PLAN]. [Provide the diff, base SHA, or the specific files to inspect — in read-only mode it cannot run git itself.]\n\nFile ownership: strictly read-only.\n\nCurrent todos:\n[PASTE CURRENT TODO SNAPSHOT]\n\nRun the full review now and report your findings in the mandated Blocking/Important/Suggestions format."
}

Tester Spawn (Always)

Spawn brooks-tester directly with isolation: "worktree" and its full test task. Role contract: .grok/agents/brooks-tester.md (kept in sync with the cross-platform tester skill).

{
  "description": "Brooks Tester — adversarial test strategy and implementation",
  "subagent_type": "brooks-tester",
  "background": true,
  "isolation": "worktree",
  "prompt": "You are the Tester on the surgical team for [PROJECT].\n\n[project summary]\n\nYour role contract is `.grok/agents/brooks-tester.md` (kept in sync with the cross-platform `tester` skill) — follow the failure-mode enumeration before writing any test.\n\nClaim your `[test]` tasks via `todo_write`. You are in an isolated worktree — report its path in your result.\n\n[WHAT_IS_BEING_TESTED], [SPEC_OR_DESIGN], [KNOWN_RISKY_AREAS].\n\nFile ownership: strictly limited to tests/, *.test.*, *.spec.* and test utilities.\n\nCurrent todos:\n[PASTE CURRENT TODO SNAPSHOT]\n\nRun the full test strategy and implementation now."
}

Note: brooks-tester.md carries no tools: restriction, since the Tester needs full read/write/execute access to write and run test files. This is intentional, matching how the Tester subagent is left unrestricted on every other platform. The tests/-only restriction is enforced by convention and Surgeon review, not by any platform mechanism (Grok has no path-scoped tool restriction).

Optional Role Spawns

Language Lawyer (only if requested) — spawn brooks-language-lawyer directly, role contract .grok/agents/brooks-language-lawyer.md (kept in sync with the cross-platform language-lawyer skill):

{
  "description": "Brooks Language Lawyer — research on [TOPIC]",
  "subagent_type": "brooks-language-lawyer",
  "background": true,
  "prompt": "You are the Language Lawyer on the surgical team for [PROJECT].\n\n[project summary]\n\nYour role contract is `.grok/agents/brooks-language-lawyer.md` (kept in sync with the cross-platform `language-lawyer` skill) — cite sources, never guess.\n\nClaim your `[research]` tasks via `todo_write`.\n\n[THE_EXACT_QUESTION], [RELEVANT_CODE], [RUNTIME_CONTEXT].\n\nCurrent todos:\n[PASTE CURRENT TODO SNAPSHOT]\n\nRun the full Research Protocol now and report in the mandated Language Lawyer Finding format."
}

Note: .grok/agents/brooks-language-lawyer.md's tools: frontmatter grants read_file, list_dir, search_tool, use_tool, web_search, run_terminal_command, matching this role's cross-platform grant (WebFetch/WebSearch/Bash, no edit) and its own contract's allowance for small runtime experiments via Bash. Unlike Copilot, this does not fully close the write gap for this role: live testing found that including run_terminal_command (needed for its Bash-experiment allowance) also unlocks the search_replace edit tool as a side effect. This role's "never edit" boundary therefore still relies on its own prompt contract, not a platform restriction (see the .grok/agents/brooks-language-lawyer.md note for the full finding).

Editor / Toolsmith / Program Clerk (if requested) — these three have no .grok/agents/*.md definition, so they still spawn via general-purpose, with the prompt starting with an explicit skill-invocation instruction (there's no agent-definition body to fall back on for the role contract). They get their full task in the same call — no lightweight-then-resume split, same as the named roles above:

• subagent_type: "general-purpose"
• isolation: "worktree"

Full spawn examples for optional writing roles (adapt [PROJECT], summary, and todos)

Editor (documentation work):

{
  "description": "Brooks Editor — documentation accuracy and completeness for [project]",
  "subagent_type": "general-purpose",
  "background": true,
  "isolation": "worktree",
  "prompt": "At the start of this session, invoke the `editor` skill — that is your role contract.\n\nYou are the Editor on the surgical team for [PROJECT].\n\n[project summary]\n\nClaim your `[docs]` tasks via `todo_write`. You are in an isolated worktree — report its path in your result.\n\n[WHAT_DOCS_NEED_WORK], [ACCEPTANCE_CRITERIA].\n\nFile ownership: owns `docs/`, `README*`, `*.md` (except code-adjacent notes), and documentation sources.\n\nCurrent todos:\n[PASTE CURRENT TODO SNAPSHOT]\n\nRun the full documentation review and verification now."
}

Toolsmith (automation work):

{
  "description": "Brooks Toolsmith — custom automation for [project]",
  "subagent_type": "general-purpose",
  "background": true,
  "isolation": "worktree",
  "prompt": "At the start of this session, invoke the `toolsmith` skill — that is your role contract.\n\nYou are the Toolsmith on the surgical team for [PROJECT].\n\n[project summary]\n\nClaim your `[tooling]` tasks via `todo_write`. You are in an isolated worktree — report its path in your result.\n\n[WHAT_NEEDS_AUTOMATING].\n\nFile ownership: owns `scripts/`, tooling configs, Makefiles, and new automation. Every tool must have `--help` and tests.\n\nCurrent todos:\n[PASTE CURRENT TODO SNAPSHOT]\n\nBuild and verify the tool now."
}

Program Clerk (structure work):

{
  "description": "Brooks Program Clerk — code organization for [project]",
  "subagent_type": "general-purpose",
  "background": true,
  "isolation": "worktree",
  "prompt": "At the start of this session, invoke the `program-clerk` skill — that is your role contract.\n\nYou are the Program Clerk on the surgical team for [PROJECT].\n\n[project summary]\n\nClaim your `[structure]` tasks via `todo_write`. You are in an isolated worktree — report its path in your result.\n\n[WHAT_NEEDS_REORGANIZING] — the Surgeon has already approved this refactor via [todo item / explicit message].\n\nFile ownership: proposes structure changes; executes renames/refactors only after Surgeon approval (already given for this dispatch).\n\nCurrent todos:\n[PASTE CURRENT TODO SNAPSHOT]\n\nRun the reorganization now."
}

Monitoring and Optional Follow-Up

• Use get_command_or_subagent_output(task_ids=["<SUBAGENT-ID>"], timeout_ms=<N>) to retrieve a background teammate's result once it completes — the result includes tool_calls/turns metadata plus the final text.
• resume_from is available for a genuine follow-up round after a subagent has completed (e.g. "Copilot, elaborate on finding #2") — pass its subagent ID and a fresh prompt with any new context (the resumed child re-renders its system prompt/tools from the current agent definition, but doesn't automatically see anything you haven't told it). It is not needed to get a subagent's first task done.
• Stand down an idle teammate with kill_command_or_subagent(task_id).

Worktree path discovery, if x.ai/git/worktree/* extension methods aren't in your tool list (they're capability-gated): every writing teammate's spawn prompt asks it to report its worktree path in its result, or list worktrees directly with grok worktree list (a regular shell command, always available as of Grok 1.0.3 — see "Reviewing and Applying Worktree Changes" below for the full review/apply workflow).

Spawn all agents together. Do not wait for responses between spawns.

Step 5: Handoff and Monitoring Instructions

After the parallel spawn calls complete, tell the user:

Team is live.

You are the Surgeon. Claim `[implement]` tasks from the shared todo list (Ctrl+T to open the todos pane) and continue the critical path.

Your teammates are running in the background, spawned directly by name with their full task:
- Copilot (`brooks-copilot`, read-only review)
- Tester (`brooks-tester`, in isolated worktree)
- [any others]

Monitoring:
- Press **Ctrl+T** to see the shared todo list (todo_write state).
- Press **Ctrl+G** to see the tasks pane (active subagents + background tasks).
- Use the queue pane (Ctrl+;) for prompt queue / background task status.
- To check a specific teammate: use get_command_or_subagent_output with their task ID (shown in the UI).
- To stand down an idle teammate: kill_command_or_subagent(task_id).

Worktree Safety (critical for Tester and any editing roles):
- Tester (and Editor/Toolsmith when spawned with `isolation: "worktree"`) run in fully isolated git worktrees.
- **Never apply blindly.** Changes are invisible to the main workspace until you explicitly merge them.
- See the full "Reviewing and Applying Worktree Changes (Tester / Editor)" section below for the concrete command set (`x.ai/git/worktree/list`, `apply`, `status`, `remove`, `gc`), review workflow, examples (with TUI caveats), conflict handling, and non-negotiable Surgical Team safety rules.
- Copilot and Language Lawyer are strictly read-only (no worktree, no edits possible).
- Ownership rules remain absolute — never allow overlapping file writes across teammates.

Next actions:
- Start claiming your first `[implement]` task.
- When a unit is ready for review, the Copilot will pick up the dependent `[review]` task.
- Run `assemble-team` at any time for the full role reference (including optional Editor/Toolsmith for docs work).
- **Before spawning or resuming any writing role (Tester/Editor/Toolsmith/Program Clerk), run the Surgeon checklist in the Safety rules section below.** Never allow two writers with potentially overlapping ownership at the same time — serialize (Tester first for the safety net) and document current writers in the todo snapshot you pass to spawns.
- When the session is done, cancel any remaining background teammates.

Reviewing and Applying Worktree Changes (Tester / Editor)

Writing teammates run with isolation: "worktree". Their filesystem changes live in a completely separate working tree under ~/.grok/worktrees/... and have zero effect on your main workspace until you merge them.

Why this matters for the Surgical Team

• Tester can freely write and run tests in isolation without polluting your in-progress implementation.
• Editor can polish docs/READMEs without fighting your concurrent edits.
• You (the Surgeon) retain final control and visibility — exactly as Brooks intended (the Surgeon never loses the thread).

Discovery

• The worktree path is required to be surfaced by the teammate: the spawn prompts for writing roles (Tester, and Editor/Toolsmith when using isolation: "worktree") explicitly instruct them to report it in their final result.
• Active background worktrees also appear in the queue pane (Ctrl+;) and tasks pane (Ctrl+G). The shared todo list is in the todos pane (Ctrl+T).
• You can list them via platform tools: x.ai/git/worktree/list (when available to your agent session) or by inspecting ~/.grok/worktrees/<project-hash>/ on disk.

Example filesystem layout (actual x.ai/git/worktree/list output may be structured differently — use the tool or path inspection for precise IDs):

~/.grok/worktrees/<project>/
  subagent-<SUBAGENT-ID-1>/
  subagent-<SUBAGENT-ID-2>/
  subagent-<SUBAGENT-ID-3>/

Review commands (run from your main session)

Platform extension methods (appear in your tool list with the right capability):

• x.ai/git/worktree/status — progress / health of worktree sessions
• x.ai/git/worktree/list — enumerate active worktrees for the current project (preferred for obtaining usable IDs/paths)

Standard git inspection (run from your main workspace, targeting the worktree path):

• git -C <full-worktree-path> status --short and git -C <full-worktree-path> diff HEAD
• For untracked files added by the teammate: git -C <path> ls-files --others --exclude-standard

Apply (merge) workflow — only after review

Once you are satisfied with the teammate's output (after reading the diff):

# Example: apply Tester's test changes after obtaining the ID via list or first-turn confirmation
x.ai/git/worktree/apply subagent-<SUBAGENT-ID>
# or using full path:
# x.ai/git/worktree/apply ~/.grok/worktrees/<project>/subagent-<SUBAGENT-ID>/

Important TUI caveats:

• x.ai/git/worktree/apply (and the other x.ai/git/worktree/* commands) are Grok TUI extension methods, not regular shell commands. They only appear in your available tools when your current session has the appropriate capability.
• The platform will confirm the merge result (or surface conflicts). Always run git status and inspect the result immediately after applying.
• If the extension command is not available in your tool list, fall back to manual inspection + git cherry-pick or file-by-file copy from the worktree path as a last resort (rare).

The platform merges the isolated changes into your current working directory. It respects concurrent edits where possible; on conflicts you will typically see platform feedback or a prompt — review the result before continuing.

Handling Conflicts and Concurrent Edits

When the main workspace and a writing teammate's worktree have touched the same files:

• Recommended: Commit or stash your local changes in the main workspace before applying any worktree. This gives the cleanest merge.
• After x.ai/git/worktree/apply, immediately run git status and git diff --stat (or open the diff in your editor) to see what actually landed.
• If the platform reports conflicts, resolve them the normal git way (git mergetool, manual edit, git add, git commit).
• For very small overlapping changes, you can also manually copy specific files from the worktree path into your main tree and commit — this is sometimes clearer than a conflicted apply.
• Never have two writing teammates (Tester + Editor, Tester + Toolsmith, etc.) whose ownership areas could overlap running in worktrees at the same time. See the Safety rules below for the exact guardrail.

Cleanup

After a successful apply (or when discarding):

• x.ai/git/worktree/remove <id> — tear down the worktree (TUI extension method; same caveats as apply)
• x.ai/git/worktree/gc — garbage-collect stale worktrees

Example:

x.ai/git/worktree/remove subagent-<SUBAGENT-ID>

Safety rules (non-negotiable)

• Always read the diff before applying. A malicious or confused Tester could in theory introduce bad tests.
• Never have two writing teammates in worktrees at the same time if their ownership areas could overlap. This is the most common source of painful conflicts.
  • Surgeon checklist before spawning any writing role:
    1. Is there already a writing teammate (Tester/Editor/Toolsmith) with an active worktree? If yes → wait for it to finish, review + apply + remove its worktree, then spawn the next writer.
    2. If you truly need parallel writing (rare), ensure completely disjoint scopes (e.g. Tester strictly limited to tests/, Editor strictly to docs/ and top-level markdown) and document the separation in the spawn prompts + todo items.
    3. When in doubt, serialize: Tester first (tests are the safety net), then Editor.
• If a worktree contains changes you do not want, simply kill the subagent and run x.ai/git/worktree/remove. The main workspace is untouched.
• Worktree isolation is a feature, not a limitation. It is the mechanism that lets the Surgical Team achieve true parallel editing safely while the Surgeon retains final control and visibility.

This section exists because the underlying Grok platform documentation for x.ai/git/worktree/* is still light (as of 2026-08). The Surgical Team pattern makes these commands first-class concerns. Note: Grok 1.0.3 also ships a first-class top-level grok worktree list/show/rm/gc CLI subcommand (plus --worktree/--worktree-ref/--restore-code flags on the main grok command) as an always-available alternative to the TUI-extension methods below — consider it for a future simplification pass, since it doesn't depend on capability-gating.

Important Grok-Specific Notes (Internal)

• Direct dispatch: brooks-copilot/brooks-tester/brooks-language-lawyer spawn directly by name with their full task in one call. Editor/Toolsmith/Program Clerk have no .grok/agents/*.md definition and spawn via general-purpose, invoking their cross-platform skill explicitly in the prompt — all roles get their full task up front, never a lightweight-then-resume split.
• The brooks-copilot, brooks-tester, and brooks-language-lawyer definitions in .grok/agents/ are both the spawn target (via subagent_type) and discoverable for manual dispatch (grok inspect, Ctrl+Shift+A catalog). They carry the full Surgical Team protocols in their body text.
• For plugin installs, users may need to ensure .grok/agents/ from the plugin is linked or copied.
• todo_write is the single source of truth for task state across the whole team.
• Worktree changes from Tester (or other writing agents) are isolated until the Surgeon explicitly applies them. See the "Reviewing and Applying Worktree Changes (Tester / Editor)" section above for the full command set, concrete examples, conflict handling, and non-negotiable safety rules (including the Surgeon checklist for writers). This is a safety feature, not a bug.
• resume_from is kept only for genuine follow-up rounds after a subagent completes — not part of getting a teammate's first task done.

Anti-Patterns to Prevent

• Do not spawn the full team for tiny changes.
• Do not let the Surgeon context-switch instead of using the Administrator role when priorities shift.
• Do not have teammates edit overlapping files.
• Do not mark tasks complete without acceptance criteria being met and verified by the owning role.

This is the Grok-native realization of the Surgical Team. One Surgeon, many focused supporters, real parallelism, and protected focus.