divide-and-conquer

name	divide-and-conquer
description	Decompose complex work into a Beads-backed execution graph with generated `WORKGRAPH.md` views, then run an NTM-style swarm by ready frontier with no write overlap. Use before parallel execution for large-ish, UI-facing, multi-file, multi-domain, naturally parallel, naturally orchestrated, subgoal-oriented, or review-sensitive tasks.
license	MIT
metadata	{"requires_beads":true}

Divide and Conquer

Decompose a task into a br epic with child issues, then execute that graph through an NTM-managed swarm. Autonomous: analyze -> load or mint the epic in br -> write/tighten the full node contract in Beads -> spawn a wave swarm using br ready/br scheduler -> dispatch Beads-rendered node briefs (each carrying a br issue ID) -> monitor -> collect evidence attachments -> reconcile br state -> advance waves -> run final integration review (close-eligible epic, flush JSONL) -> commit .beads/issues.jsonl with the slice changes -> report. Markdown files are generated views or evidence attachments only. No approval gates.

For massive runs, this skill can add a subgoal tier between the root slice and leaf execution nodes. A subgoal is a Beads-backed delegation boundary over a filtered ready frontier, represented by a durable subgoal controller issue plus slice:{root} and subgoal:{slug} labels. Use subgoals when a single orchestrator would otherwise serialize independent frontiers or fill its context tending one child process at a time.

Default Marker

Start with a stable first progress message such as:

Using \divide-and-conquer` to build the ready frontier, spawn an execution swarm, and hand the workgraph off wave by wave.`

Shared cross-skill rules live in references/orchestration-contract.md. Use that file for worker ownership, background-task collection, and detached handoff semantics.

Before building the graph or spawning a swarm, apply the no-ragrets Edge-Capture Contract: name the nearest valuable artifact or decision, name the proof that would show it improved, gather enough evidence to move confidently in source order, and justify the coordination cost of each worker wave. When this skill is composing or tightening Beads, no-ragrets is the bead authoring gate: each child issue must encode the outcome, evidence, failure avoided, write scope, validation, dependencies, stop rules, and model route a future orchestrator needs without rereading the chat. Bias toward useful agent coverage for non-trivial work; do not shrink the graph just to save tokens. If the artifact or proof is unclear but the initiative is still promising, route the uncertainty through wiki-duel, dueling-idea-wizards, describe, or a small discovery wave instead of stopping for human solidification.

Beads node synthesis and describe-style node contract guidance live in references/workgraph-synthesis.md. Blocked-node handling, closeout discipline, and the visual-parity lane live in references/failure-mode-contracts.md; apply them before marking a wave blocked, before final reporting, and before accepting design-related work. Subgoal synthesis and split patterns live in the same reference set; the shared definition and label grammar live in _shared/references/orchestration-contract.md and _shared/references/beads-contract.md.

Beads Is the Source of Truth

Every divide-and-conquer run uses beads_rust (br) as the canonical store for nodes, dependencies, status, and the ready frontier. WORKGRAPH.md is now a rendered view of br state, not the authoritative artifact. Cross-skill conventions (naming, labels, lifecycle, attribution env vars, commit policy) live in _shared/references/beads-contract.md.

Bootstrap on entry (idempotent):

python3 ~/.claude/skills/_shared/scripts/br_helpers.py ensure
export BR_AGENT_NAME=divide-and-conquer BR_HARNESS=claude-code BR_MODEL="$CLAUDE_MODEL"

Use the helper rather than raw br calls so attribution and JSON envelopes are consistent across panes. The helper exposes: ensure, status, ready, scheduler, mint-node, update-node, hydrate-node, render-node-brief, claim, block, done, render-workgraph, flush.

After minting the graph, immediately run br ready --json or the helper equivalent and verify that intended first-wave child nodes are actually ready. Some br versions model --parent as a dependency edge, which can make child issues appear blocked by the open epic. If that happens, do not dispatch from a stale mental model. Use labels/external refs for epic grouping, remove or avoid the blocking parent-child edge for actionable nodes, or use a scheduler mode that explicitly understands non-blocking hierarchy before spawning workers.

This skill now defaults to an external NTM swarm for execution. Do not fall back to ad hoc local subagents or /codex:rescue as the primary path unless the user explicitly asks to bypass the swarm. Before declaring ntm unavailable, normalize the common agent-shell PATH gap:

export PATH="$HOME/.local/bin:$PATH"
command -v ntm >/dev/null 2>&1 || test -x "$HOME/.local/bin/ntm"
ntm version >/dev/null 2>&1 || ntm deps -v >/dev/null

If ntm is still unavailable after that check, stop and surface the missing prerequisite instead of silently degrading.

Because execution is swarm/NTM-coordinated, vibing-with-ntm is mandatory for every divide-and-conquer run. Activate it through sbp when needed, then follow its operator, reservation, transport, and review-loop guidance.

Before any ntm spawn, prove the NTM project name resolves to the repo you intend to edit. NTM derives pane working directories from projects_base/session_name; a wave name that does not map to the target repo can launch workers in a sibling or empty checkout. This root preflight belongs to divide-and-conquer because it is an execution-safety gate, not a live operator-tending concern. See NTM Project Root Preflight.

Use this skill for large-ish, UI-facing, multi-file, naturally parallel, or review-sensitive tasks even when the user did not explicitly ask for a swarm. When Beads are clearly defined, prefer Grok 4.5 for bounded task-runner work: cwd/workflow routing, worker-request cleanup, read-only inventories, bounded scripting, fixtures/docs cleanup, generated-command cleanup, and scoped commit batching. A Bead is clear enough for Grok 4.5 only when it names the exact write scope or read-only artifact, validation commands, stop rules, review owner, and final authority. Route through the shared Grok lanes in ../_shared/references/orchestration-contract.md: voice-to-text dispatcher for cheap routing/preflight, the NTM Grok plugin when interactive pane preflight passes, Swimmers or the local Grok 4.5 route for maintained task-runner sessions, and direct headless Grok with a prompt file for bounded one-shots. If Grok 4.5 stalls, emits no artifact, violates scope, or needs a judgment it does not own, escalate the node to Codex gpt-5.6-sol max, or route design/UX work to a Grok 4.5 design lane, and record the route failure in the result artifact. Design-related execution nodes should run on Grok 4.5 through the NTM Grok plugin when preflight passes, otherwise through the Swimmers/local/direct headless Grok 4.5 route. If no Grok 4.5 design route is available, surface the routing blocker rather than silently reassigning design work to Codex. Runtime orchestration must run on Grok 4.5 through the NTM plugin: it owns frontier reads, claims, dispatch, tending, harvest, and convergence, but never planning. System design, domain-planner quality loops, no-ragrets bead composition, decomposition, dependency topology, acceptance-criteria design, impactful architecture/code decisions, integration review, commit acceptance, and final say must run on Codex gpt-5.6-sol; if SOL is unavailable, use Codex gpt-5.6-terra at ultra. Require a final fresh-eyes reviewer pass before completion.

Model Routing Is Mandatory

Route every ready node before spawning workers:

• Grok 4.5 owns NTM runtime orchestration. Route root and subgoal controller loops to the NTM Grok plugin. Grok may census, read the accepted ready frontier, claim hydrated leaves for workers, dispatch, observe, unstick, harvest, reconcile verified statuses, and detect convergence. It must not decompose goals, invent or repair plan topology, author material acceptance criteria, resolve architectural ambiguity, synthesize planning branches, or make final acceptance decisions. When those needs appear, it dispatches an authority node and waits for the accepted result before continuing.
• Codex GPT-5.6 SOL owns planning and final authority. Route no-ragrets bead composition, divide-and-conquer decomposition and root synthesis, domain-planner sessions and quality loops, system design, architecture, security-sensitive or high-impact code decisions, ambiguous repairs, integration review, commit acceptance, and any final-say review node to Codex gpt-5.6-sol. If SOL is unavailable, use Codex gpt-5.6-terra with ultra effort for those same roles. SOL uses medium by default; use max for pivotal/high-consequence planning or when another model is demonstrably struggling. Planning/authority nodes may author or repair Beads and may overrule task-runner output; the Grok controller may not.
• Grok 4.5 owns design/UX and visual review work. Treat a node as design-related when it touches UI/UX, visual design, design systems, frontend screen or component layout, CSS/tokens, responsive behavior, screenshots, visual parity, product interaction copy, or fresh-eyes review of those surfaces. Dispatch these nodes to Grok 4.5 through the NTM Grok plugin when available, or through the approved sidecar/direct Grok 4.5 route. If no Grok 4.5 design route is available, surface the route blocker and keep Codex as final acceptance authority, not as the default design worker.
• Grok 4.5 is the preferred bounded task-runner lane for clear Beads. The voice-to-text dispatcher is the preferred cheap router for cwd selection, skill-tag extraction, request cleanup, broad evidence bucketing, and other clerk work. For execution nodes that are task-runner safe, prefer Grok 4.5 through the NTM Grok plugin when preflight passes; otherwise use the Swimmers hidden-session lane with spawn_tool: "grok", the locally configured Grok 4.5 route, or direct headless Grok with a prompt file for a bounded one-shot. Good candidates are $commit/logical commit batching, mechanical scripts, fixtures, narrow docs edits, generated-command cleanup, manifest/file classification, and other "task rabbit" work with explicit files, validation, and revertability. Record Model route: Grok dispatcher for pure routing/preflight, Model route: Grok CLI sidecar for a Grok-authored read-only evidence artifact, and Model route: Grok 4.5 2.5 task-runner for narrow writer or commit-runner nodes. Do not treat a Grok 4.5 result as authority to bypass Beads hydration, ownership, validation, stronger-model review, or the final review gate. If the result is empty, off-scope, validation-failing, or asks for judgment beyond the Bead, escalate authority questions to Codex gpt-5.6-sol max or reroute design/UX work to the Grok 4.5 design lane instead of retrying indefinitely. For task-selection heuristics and CASS query examples, see references/grok-sidecar-selection.md.
• Routine non-design execution first checks task-runner safety. If a backend, API, data, test, refactor, validation, ops, or integration node has exact Beads guidance and is cheap to verify/revert, prefer Grok 4.5 as the task runner. If the node is broad, high-impact, secret-bearing, architecture-sensitive, integration-heavy, or still fuzzy, route it to Codex gpt-5.6-sol at the ordinary default effort: --cod=N:gpt-5.6-sol:medium.
• Ambiguous nodes are design-related if visual/product interaction quality is a material acceptance criterion; otherwise route ambiguity to Codex gpt-5.6-sol. Split mixed nodes before launch when the model routing would otherwise be unclear.
• Record the selected route in the Beads dispatch contract and worker prompt: Model route: Grok 4.5 NTM orchestrator, Model route: Grok dispatcher, Model route: Grok CLI sidecar, Model route: Grok 4.5 task-runner, Model route: Grok 4.5 design/UX, Model route: Codex gpt-5.6-sol medium, Model route: Codex gpt-5.6-sol max escalation, or Model route: Codex gpt-5.6-terra ultra fallback.

Related Skills

• [[skill-issue]]
• no-ragrets for the Edge-Capture Contract before broad work, reusable workflow changes, or worker-wave execution
• ntm for command reference, session inspection, and swarm debugging
• vibing-with-ntm for swarm orchestration patterns, pane hygiene, and transport-layer recovery when the problem is NTM rather than the workgraph
• codex-tmux only when the user explicitly wants a detached single-worker fallback instead of an NTM swarm
• modes-of-reasoning-project-analysis and dueling-idea-wizards as sibling swarm-heavy skills with stronger NTM operator patterns worth borrowing

Artifact Storage

Execution artifacts belong alongside the active client overlay in skillbox-config, not in the repo root and not in /tmp.

Repo hygiene is a hard requirement. New divide-and-conquer waves MUST NOT write or ask workers to write WORKGRAPH.md, EXECUTION_CONTEXT.md, WG-*_RESULT.md, DAC_FINAL_RESULT.md, .dac/, or .ntm/ inside the product repo unless the user explicitly asks for a repo-local proof artifact. Product repos should receive product changes and intentional .beads/issues.jsonl updates only.

Resolve client context with the shared helper first:

python3 ~/.claude/skills/_shared/scripts/resolve_context.py "$PWD" --format json

Then resolve the invocation artifact root using this order:

1. workflow_builder.invocation_root from the resolved context
2. client_dir + /invocations when client_dir is present
3. Stop and surface the missing overlay/artifact-root prerequisite

Treat relative roots as relative to client_dir. If the resolver returns absolute paths, use them directly.

Create one run directory per execution:

{invocation_root}/{repo_slug}/divide-and-conquer/{run_id}/

Where:

• repo_slug = matched repo id from the overlay when available, otherwise the basename of the working repo
• run_id = timestamped execution id such as 2026-04-09T16-22-31Z

Store these optional/generated artifacts in the run directory:

• EPIC_ID.txt — the br epic ID for this run; sole pointer back to the source-of-truth state in .beads/
• WORKGRAPH.md — generated view (regenerate with br_helpers.py render-workgraph --epic {id} --out <absolute-run-dir>/WORKGRAPH.md); never edit by hand
• EXECUTION_CONTEXT.md — optional generated dispatch summary rendered from Beads; never the authoritative worker contract
• WG-*_RESULT.md — per-node worker evidence attachments (changed files, validation output, blockers); status and contract remain in br
• DAC_FINAL_RESULT.md — final integration evidence summary
• any copied monitor notes or wave summaries

If the slice already has a br epic with open children, treat that epic as the durable graph: list its children with br_helpers.py ready --label slice:{name} and skip re-minting nodes. Always create a fresh invocation run directory for this execution's artifacts and write EPIC_ID.txt pointing at the reused epic.

Live pane state, transcript tails, attention-feed output, restarts, rate-limit status, queue-dry checks, and swarm tending notes belong to vibing-with-ntm and the NTM runtime. Export only the concise evidence needed for reconciliation into this run directory. Do not mirror the full NTM session into the product repo.

Modes

Modes customize decomposition for specific projects: split boundaries, swarm sizing heuristics, naming conventions, validation commands, and preferred worker mix. Stored in modes/ (gitignored, never committed).

How Modes Work

Project-specific configuration (split boundaries, swarm sizing heuristics, validation commands, wave labels, reviewer preferences, and artifact roots) lives in the client overlay: skillbox-config/clients/{client}/overlay.yaml -> auto-generated context.yaml.

Client Config Resolution (Step 0)

1. Look for context.yaml in the working tree (generated from the client overlay)
2. If found, load project-specific settings automatically
3. If not found, tell the user no overlay matches and create one using the skillbox-quickstart scan + generate flow before proceeding
4. If no skillbox-config/ exists, create one; do not fall back to generic decomposition

Swarm Runtime (Default)

divide-and-conquer uses an external NTM swarm with split authority. The Grok 4.5 runtime controller owns accepted-frontier selection, claims, dispatch, monitoring, collection, and convergence. A Codex planning authority owns decomposition, topology, synthesis, integration acceptance, and final say; workers execute the nodes.

The lead is handoff-first. It should not personally implement or deeply audit a leaf Bead merely because it selected that Bead. For non-trivial work, the lead claims the node for a named worker, dispatches the Beads-rendered brief, then moves on to admitting/tending the next ready node or subgoal while monitoring evidence. Lead-authored edits are reserved for graph tightening, orchestration artifacts, final integration, shared-file arbitration, and tiny emergency unblocks that are explicitly recorded as root-owned.

Runtime knobs

Argument	Default	Description
--project=NAME	derived from cwd + wave id	NTM swarm project name
--grok=1	1 controller	Installed Grok 4.5 NTM runtime orchestrator for frontier/dispatch/tending/harvest; never planning
Grok 4.5 design/UX lanes	auto	UI/UX, visual design, design-system, screenshot, visual parity, interaction-copy, and fresh-eyes review nodes
--cod=N:gpt-5.6-sol:medium	auto	Default Codex planning/authority panes
--cod=N:gpt-5.6-sol:max	escalation only	Pivotal/high-consequence planning or another model struggling
--cod=N:gpt-5.6-terra:ultra	SOL fallback only	Planning/authority fallback when GPT-5.6 SOL is unavailable
--gmi=N	0	Optional Gemini panes
Grok 4.5 runners	eligible clear Beads	Grok plugin or sidecar lanes via voice-to-text/NTM Grok/Swimmers/local task-runner routes for explicit task-runner nodes
--max-workers=N	10	Hard cap per wave
--wave-timeout-min=N	45	Hard timeout for a wave before collect-and-triage
--monitor-cron	every 3 minutes	Swarm health checks and nudges

Worker sizing rules

• Size each wave from the current ready frontier, not from the full graph
• Default to one worker per ready node
• If the frontier exceeds --max-workers, split it into multiple subwaves
• Prefer Grok 4.5 for task-runner-safe nodes when the Bead gives an exact write scope or read-only artifact, validation, stop rules, and stronger-model review owner; keep dispatcher/preflight nodes read-only
• Route design-related execution nodes and design/fresh-eyes review nodes to Grok 4.5; use Codex gpt-5.6-sol medium for ordinary authority and max for pivotal planning or explicit failed-model escalation, not as the default design worker
• Route NTM controller/orchestration loops to Grok 4.5. Route no-ragrets bead composition, decomposition/synthesis, domain-planner sessions, system design, impactful execution, integration review, and final-say nodes to Codex gpt-5.6-sol; use gpt-5.6-terra:ultra only when SOL is unavailable
• Use gpt-5.6-sol:medium for normal Codex authority allocations and gpt-5.6-sol:max only for the named escalation triggers
• For planning/authority, fall back to gpt-5.6-terra at ultra; do not use a lower model merely because the controller is Grok
• Default SOL to medium. Use SOL max for pivotal/high-consequence planning or when Grok/another model has demonstrably struggled. Terra always uses ultra and only when SOL is unavailable.

Subgoal Mode

Use subgoal mode when the root ready frontier is too large or too naturally parallel for one lead to supervise as a single wave sequence. The purpose is to run multiple independent child frontiers at the same time while keeping Beads as the source of truth and keeping final integration root-owned.

Do not use subgoals for ordinary 2-8 node slices, strict dependency chains, or work whose subgoal-level write scopes overlap. In those cases, widen the normal ready frontier, split into subwaves, or keep the graph sequential.

Subgoal Shape

Represent each subgoal with:

• one subgoal controller issue labeled slice:{root}, subgoal:{slug}, and subgoal-role:controller
• leaf execution issues labeled slice:{root}, subgoal:{slug}, and subgoal-role:leaf
• controller notes fields for subgoal_id:, frontier_filter:, parent_run_dir:, subgoal_run_dir:, child_orchestrator:, ntm_project:, max_workers:, max_subgoal_depth:, isolation:, and status_artifact:
• controller design blocks for writes:, shared_files:, stop_rules:, and escalation:

The root slice:{root} label must remain on every controller and leaf. Do not model subgoals as parent-child readiness edges unless the installed br version has been proven to support non-blocking hierarchy.

Subgoal Admission

Before launching a subgoal cohort:

1. Prove the live br ready --label slice:{root} --label subgoal:{slug} behavior is AND semantics, or apply helper-side AND filtering after a broader query. If this cannot be proven, fail closed and do not launch subgoals.
2. Partition the ready frontier by subgoal:{slug} and exclude leaves without the root slice:{root} label.
3. Verify subgoal-level writes: do not overlap across the active cohort and no active leaf depends on another active subgoal.
4. Treat shared_files: as root-owned and sequential. Child orchestrators may propose edits to shared files but may not apply them.
5. Run vibing-with-ntm's swarm-load-guard.sh once for the whole workspace run and admit only as many subgoals and leaf workers as the global budget can support. Do not re-run the load check independently inside each subgoal and treat every local pass as permission to spawn.

Execution Modes

Default mode is meta-lead multiplexing:

• The root lead keeps one context but admits several ready subgoal controllers at once.
• It launches or tends one compact NTM session per active subgoal, each scoped by that controller's frontier_filter:.
• It monitors controller state and concise subgoal status, not every child leaf pane tail.

Escalation mode is delegated child orchestration:

• Use this only when subgoal count, depth, or context pressure is already too high for meta-lead multiplexing.
• The initial child substrate is NTM child orchestrator sessions; do not add a second substrate until the NTM path has a proven recovery contract.
• The root claims the controller issue for the child orchestrator before dispatch and verifies the claim with br show.
• The child orchestrator may claim, block, and close only leaf issues matching both slice:{root} and its assigned subgoal:{slug}.
• The child writes SUBGOAL_RESULT.md inside subgoal_run_dir: and proposes any cross-subgoal graph change there instead of mutating topology directly.

Optional isolation:

• isolation: checkout is the default.
• isolation: worktree is appropriate when static write-scope proof is weak or the subgoal is large. Worktrees move overlap risk to a loud merge/integration step; they do not make overlapping edits impossible. Define a single root-owned .beads/ mutation policy before using worktrees.

Subgoal Completion

Never accept a subgoal as done from controller status, child prose, or SUBGOAL_RESULT.md alone. The root accepts completion only after an independent gate proves:

br ready --label slice:{root} --label subgoal:{slug} is empty
AND no in-flight leaf set changed for at least two operator ticks
AND expected validation and SUBGOAL_RESULT.md evidence exist
AND the latest child output has no unresolved blocker or convergence-warning language

Then the root performs cross-subgoal integration, validates shared files, flushes Beads, runs the final review wave, and commits. Subgoal workers and child orchestrators do not commit.

NTM Project Root Preflight

Run this before every wave spawn, including review waves:

export PATH="$HOME/.local/bin:$PATH"
repo_root="$(git rev-parse --show-toplevel)"
pwd
rg '^projects_base' ~/.config/ntm/config.toml
ntm version
ntm list --json

Then verify the proposed $WAVE_PROJECT resolves to repo_root. If projects_base/$WAVE_PROJECT is not the target checkout, do not spawn the wave by basename. Prefer collision-free session names backed by explicit projects_base symlinks. Fix the NTM project mapping first, choose a supported session name that maps to the actual repo, or block the Beads node with the exact root resolution problem.

Record the result in the dispatch contract:

NTM root preflight:
- repo_root: <absolute git root>
- wave_project: <ntm session name>
- projects_base mapping: <verified target path or blocker>
- result: pass | blocked

ntm spawn success, an idle pane, or a worker saying it is in the right repo is not sufficient proof. A spawn can report success but create no session when the name prefix-collides with an existing session, and tmux prefix matching can mask the miss. After spawn, prove exact tmux session identity before dispatch:

tmux has-session -t "=${WAVE_PROJECT}"
tmux list-panes -t "=${WAVE_PROJECT}" -F '#{session_name}:#{window_index}.#{pane_index} #{pane_current_path}'

Use the leading = for exact tmux target matching. After dispatch, verify pane output or a robot inspection shows the node brief landed in the intended checkout before counting the node as in flight.

Process

1. Analyze the Task

Read the conversation to understand:

• What the user wants accomplished
• What files or systems are involved
• What dependency edges matter
• Whether the task is actually ready for orchestration

2. Decide Whether a Workgraph Is Relevant

Use a workgraph when any of these are true:

• The task has 2+ plausible concern-owned execution nodes
• Dependency edges matter to launch order
• The user explicitly wants an orchestrated or parallel split
• You need a durable artifact to explain and reuse the split across waves

If the work collapses to one concern or a strict dependency chain, do not invent fake parallelism. The graph can still be useful for sequencing, but the execution should stay narrow.

If the split itself is unclear, use ask-cascade on the first blocking strategic fork before inventing nodes or launching a swarm.

3. Decide Whether Subgoals Are Relevant

Before minting or dispatching a very large graph, decide whether normal waves are enough:

• If the ready frontier is at or below --max-workers, writes are disjoint, and one lead can tend one session, use the normal ready-frontier path.
• If the work naturally separates by repo, service, domain, layer, or read-only investigation group, and those groups can advance independently, add subgoal controllers.
• If the work is a strict discovery -> act chain or shares migrations, generated files, global runtime state, or a single validation bottleneck, keep it inside one frontier and encode dependencies instead of inventing subgoals.

When subgoals are relevant, mint or tighten the controller issues before leaf dispatch. The controller is the durable boundary; NTM session names and SUBGOAL_RESULT.md artifacts are derived views/evidence.

4. Load or Synthesize the Beads Epic

Before inventing a split, check whether the slice already has a br epic with open children:

frontier_json="$(python3 ~/.claude/skills/_shared/scripts/br_helpers.py ready --label slice:{slug})"

If the epic exists and the ready frontier is non-empty:

• Treat the helper's output as the default launch proposal
• Respect each issue's writes (in --design) even if the user asked broadly
• Do not pull blocked or deferred issues into the same wave

If no epic exists and orchestration is still relevant:

• Create an invocation run directory under the resolved invocation root
• Apply the no-ragrets bead authoring gate: name the desired outcome, evidence, and failure avoided for the slice, then encode those facts into the epic and each child issue instead of leaving them in chat or a markdown-only plan
• Mint the epic and child nodes via br_helpers.py mint-node, following the field mapping in _shared/references/beads-contract.md: --concern, --repo, --writes, --done-when, --validate, --model-route, --risk, --depends-on, --epic. Synthesis prose lives in references/workgraph-synthesis.md; treat it as guidance for what content each node carries, not where state lives.
• Keep the slice focused on this execution, usually 2-8 nodes
• Write EPIC_ID.txt to the run directory, then regenerate WORKGRAPH.md as a view: br_helpers.py render-workgraph --epic $(cat <absolute-run-dir>/EPIC_ID.txt) --out <absolute-run-dir>/WORKGRAPH.md
• Immediately run br_helpers.py ready --label slice:{slug} and treat the result as wave 1

The rendered WORKGRAPH.md is a scratch view, not a second plan document. State changes flow through br update/br close; never hand-edit the markdown.

5. Tighten Fuzzy Nodes Before Swarm Launch

Use describe only when a node is still fuzzy, not as mandatory ceremony for every node.

When a ready node still has vague done_when, validate_cmds, or non-goals:

• Do not launch a writer yet
• Run a node-local describe pass or fresh review to tighten the contract
• If the review exposes a real strategic decision, route that one blocking question through ask-cascade
• Update the issue in place: br update {id} --acceptance-criteria '…' --notes 'validate: …' --design '…'
• Re-query the frontier with br_helpers.py ready --label slice:{slug} before launching the wave

6. Hydrate the Beads Dispatch Contract

Before spawning the swarm, make Beads hold the complete dispatch contract. A ready node is not launchable until br show {id} --json or br_helpers.py hydrate-node {id} exposes:

• original ask or node description
• repo path, branch/HEAD, and run directory
• current dependencies, blocked state, and ready frontier membership
• writes, done_when, validate_cmds, risk_gate, non-goals, and stop rules
• global constraints: no remote push, no cross-repo edits, no write-scope theft
• model route per node: Grok 4.5 NTM orchestrator for frontier/claim/dispatch/ tending/harvest/convergence only; Codex gpt-5.6-sol for no-ragrets bead composition, decomposition/synthesis, domain-planner sessions, architecture, impactful execution, integration review, and final say, with Codex gpt-5.6-terra ultra as the SOL-unavailable fallback; Grok 4.5 design/UX for design-related nodes; Grok dispatcher for read-only router/preflight nodes; Grok CLI sidecar for Grok-authored read-only artifacts; Grok 4.5 task-runner as the preferred runner for narrow writer, scripting, fixture/docs cleanup, generated-command cleanup, classification, or commit-runner nodes with exact writes, validation, stop rules, explicit review ownership, and final authority
• expected Beads assignee per node (BR_AGENT_NAME) and the exact claim verification command

Use Beads-first helper commands:

python3 ~/.claude/skills/_shared/scripts/br_helpers.py hydrate-node <issue-id>
python3 ~/.claude/skills/_shared/scripts/br_helpers.py render-node-brief <issue-id>

If hydrate-node reports missing dispatch fields, update the issue first with br_helpers.py update-node or br update; do not patch the missing context into EXECUTION_CONTEXT.md. That file may be rendered for humans or transport debugging, but workers must receive a Beads-rendered node brief.

7. Spawn the Wave Swarm

For each ready frontier wave, launch an NTM swarm sized to that wave.

frontier_json="$(python3 ~/.claude/skills/_shared/scripts/br_helpers.py ready --label slice:${SLICE_SLUG})"
# Optional: ranked by br's evidence-aware scheduler instead of plain priority
# frontier_json="$(python3 ~/.claude/skills/_shared/scripts/br_helpers.py scheduler)"

ntm spawn "$WAVE_PROJECT" \
  --grok=1 \
  --cod="${NUM_CODEX}:gpt-5.6-sol:medium" --grok="${NUM_GROK}:grok-4.5" \
  --no-user \
  --stagger-mode=smart

If the Grok plugin preflight passes and the frontier has Grok 4.5 design/UX or task-runner nodes, include the Grok count explicitly:

ntm spawn "$WAVE_PROJECT" \
  --grok=1 \
  --cod="${NUM_CODEX}:gpt-5.6-sol:medium" \
  --grok="${NUM_GROK}:grok-4.5" \
  --no-user \
  --stagger-mode=smart

The first --grok=1 is the installed Grok 4.5 controller allocation; NUM_GROK counts Grok execution/design workers and may be zero. Discover the controller's pane by command/title after spawn rather than assuming pane 0 because plugin panes may be reported as user. If any worker count is zero, omit that worker flag. Never satisfy a design-related node by increasing NUM_CODEX, and never satisfy a Codex planning/authority node by increasing NUM_GROK. If the provider rejects or cannot allocate GPT-5.6 SOL, retry only the Codex planning/authority allocation as --cod="${NUM_CODEX}:gpt-5.6-terra:ultra". Do not invoke the fallback merely because a worker's task or validation failed; Terra ultra is an availability fallback, not a retry lottery. Grok 4.5 task-runner nodes are launched after the same Beads claim handshake, through the NTM Grok plugin when preflight passes, the voice-to-text/Swimmers Grok lane, a local Grok 4.5 task-runner route, or a direct headless Grok one-shot, and are tracked by their issue ID plus result artifact. Do not inflate the Codex count to cover a Grok-routed node, and do not rely on ntm --robot-* alone as proof that a Grok 4.5 runner completed; verify the artifact, Beads state, validation, and stronger-model review.

Wait for the swarm to be ready:

ntm --robot-wait="$WAVE_PROJECT" --condition=idle --timeout=120s

Prefer wave-scoped swarm names such as dac-<repo>-wave-01, dac-<repo>-wave-02, and dac-<repo>-review.

Optionally render EXECUTION_CONTEXT.md inside the run directory after the Beads contract is complete. Treat it as a cached view for humans and transport debugging. Never hand-edit it to add worker-only context.

Before dispatch, verify the run directory is outside the product repo root and under the resolved invocation root. If it resolves to the repo root, .dac/, .ntm/, /tmp, or any untracked repo-local scratch directory, stop and repair the artifact root before spawning workers.

Transport Hygiene

If the swarm transport looks wrong, fix that before blaming the node brief.

• After each dispatch, verify the target pane actually switched onto the new brief. ntm send reporting success is not enough.
• If a pane still shows an unrelated prior task, a stale generic prompt, or an idle shell after dispatch, treat it as contaminated. Respawn that pane and resend the node brief before advancing the wave.
• Prefer artifact-aware checks over coarse activity labels: a node is not meaningfully in flight until its expected absolute <absolute-run-dir>/WG-*_RESULT.md path is plausible and the pane output matches the assigned node.
• When the failure surface is NTM itself rather than decomposition or prompt quality, consult vibing-with-ntm or ntm if available instead of improvising ad hoc transport rituals.

8. Dispatch Node-Specific Prompts

Send each worker a unique node prompt. Stagger dispatch by 15-20 seconds to avoid thundering-herd effects:

for pane in <pane indexes for this wave>; do
  ntm send "$WAVE_PROJECT" --pane="$pane" "$(cat <<'PROMPT'
  <INSERT NODE-SPECIFIC PROMPT>
  PROMPT
  )"
  sleep 18
done

Lead-Owned Claim Handshake

Do not rely on worker prose or prompts to make bv/br state truthful. The lead must claim every node for the intended worker before allowing real edits.

For each node, immediately before sending the node brief:

BR_AGENT_NAME="<worker-id>" BR_HARNESS="ntm" BR_MODEL="<model-id>" \
  br update "<issue-id>" --claim --json

br show "<issue-id>" --json \
  | jq -e '.[0].status == "in_progress" and .[0].assignee == "<worker-id>"'

If this verification fails, do not dispatch the pane. br update --claim can assign the system user in some environments, so verify the assignee through br show and repair with br update <id> --assignee <worker-id> --json when needed. Prefer br_helpers.py claim when available because it performs this assignee repair automatically. Send the brief only after br show confirms status=in_progress and the expected assignee. ntm send success, active pane output, modified files, or a worker saying "claimed" are not sufficient.

Before any closeout, verify the issue is still attributed. If a worker closed a node with a blank assignee, repair attribution with br update <id> --assignee <worker-id> --json and add a comment explaining the reconciliation.

Every worker prompt MUST include:

1. A node brief rendered from Beads (br_helpers.py render-node-brief <id>)
2. The exact br issue ID for the node, plus the absolute run directory path for evidence artifacts
3. The node's concern, depends_on, writes, done_when, validate_cmds, and risk_gate (read these from br show {id} if not inlined)
4. The hard ownership rule: edit only the declared writes
5. The lifecycle commands and claim gate:
   • The lead has already claimed the issue for this worker; on entry the worker must run br show {id} --json and confirm status=in_progress with its BR_AGENT_NAME
   • If the claim is missing or assigned to someone else, the worker must stop and report instead of editing
   • On blocked: br update {id} -s blocked --notes "{reason}"
   • On done: br close {id} --reason "{summary}" --suggest-next --json
6. The attribution preamble: export BR_AGENT_NAME=<role> BR_HARNESS=<harness> BR_MODEL=<model> before any br mutation
7. The artifact boundary: write evidence only to the absolute run directory, never to the product repo root, .dac/, .ntm/, or /tmp
8. The stop rule: if required edits escape writes, leave the issue in_progress, write the smallest Beads graph change proposal in the result artifact, and do NOT close the issue
9. The result artifact contract below

Node Worker Prompt Contract

Use a compact brief like this:

You own one divide-and-conquer node inside an execution swarm.

Source of truth: br (run `br show <issue-id>` for the live contract)
Issue ID: <prefix>-wg-001-<slug>-<hash>
Run directory: <absolute path under skillbox-config invocation root>
Concern: <concern>
Depends on: <ids already satisfied, or None>
Writes: <expected paths/globs, or None>

Underlying ask:
<plain-language user outcome for this node>

Done when:
- <binary completion check>

Validate:
- <command>

Risk gate:
- none | <gate>
Model route:
- Grok 4.5 NTM orchestrator for ready-frontier reads, claim/dispatch, tending,
  harvest, and convergence only; it never plans or makes final decisions
- Grok dispatcher for read-only router/preflight nodes
- Grok CLI sidecar for Grok-authored read-only evidence artifacts
- Grok 4.5 task-runner for narrow scripting, docs, fixtures, or commit
  batching nodes with explicit write scope, validation, stop rules,
  stronger-model review, and final authority; escalate to Codex gpt-5.6-sol if the
  runner stalls, drifts, or cannot validate
- Grok 4.5 design/UX for design-related nodes and design/fresh-eyes review;
  Codex gpt-5.6-sol medium owns ordinary authority; SOL max owns pivotal
  planning or failed-model escalation
- Codex gpt-5.6-sol for planning, decomposition/synthesis, system design,
  domain-planner sessions, no-ragrets bead composition, impactful execution,
  integration review, and final say; Codex gpt-5.6-terra ultra only when SOL
  is unavailable
Expected Beads assignee:
- <worker-id>

Non-goals:
- <explicitly out of scope>

Rules:
- export BR_AGENT_NAME=<role> BR_HARNESS=<harness> BR_MODEL=<model> before any br call
- On entry: verify the lead's claim with `br show <id> --json`; do not edit
  until it shows `status=in_progress` and `assignee=<worker-id>`
- Work only inside the repo and inside your declared write scope
- Do not commit; the integration wave commits everything together
- Do not create repo-local orchestration artifacts. No repo-root
  `WORKGRAPH.md`, `EXECUTION_CONTEXT.md`, `WG-*_RESULT.md`,
  `DAC_FINAL_RESULT.md`, `.dac/`, or `.ntm/`.
- If you need edits outside `writes`, do NOT close the issue. Report the
  smallest Beads graph update needed and leave status=in_progress for the orchestrator
- Run your validate commands before declaring success
- On done: `br close <id> --reason "<summary>" --suggest-next --json` and write
  `<absolute-run-dir>/WG-001_RESULT.md` with the required sections
- On blocked: `br update <id> -s blocked --notes "<reason>"` and write the
  blocker section in `<absolute-run-dir>/WG-001_RESULT.md`

Node Result Artifact

Every worker MUST write <NODE_ID>_RESULT.md such as WG-001_RESULT.md in the absolute invocation run directory. If the worker cannot write there, it must stop and report the artifact-root blocker instead of writing a fallback file in the product repo, .dac/, .ntm/, or /tmp:

# WG-001 Result

## Status
done | blocked | needs_rework

## Summary
One paragraph on what changed.

## Files Changed
- path/to/file

## Validation
- Command: <validate command>
- Result: pass | fail
- Notes: <short output summary>

## Workgraph Notes
- Suggested graph update, if any

## Blockers
- Only if blocked or needs_rework

9. Monitor the Wave

Set up monitoring immediately after dispatch:

CronCreate(
  cron: "*/3 * * * *",
  recurring: true,
  prompt: "Check divide-and-conquer wave $WAVE_PROJECT. Run:
    1. ntm --robot-is-working=$WAVE_PROJECT
    2. ntm --robot-tail=$WAVE_PROJECT --lines=80
    3. test <absolute-run-dir> -ef \"$(git rev-parse --show-toplevel)\" && echo BAD_RUN_DIR || true
    4. ls -la <absolute-run-dir>/WG-*_RESULT.md 2>/dev/null
    5. br show <each-active-issue-id> --json

  For each active node, determine:
  (a) working / idle / stuck / rate-limited?
  (b) has it produced its WG-*_RESULT.md file?
  (c) if output exists, is validation explicit or hand-wavy?
  (d) does br show status=in_progress with the expected assignee?

  ACTIONS:
  - If a node is open/unassigned after dispatch: stop/nudge the pane, repair
    the claim, and do not count the node as in-flight until br confirms it
  - If worker idle + no result: remind it of its node and result file
  - If worker stuck for 2 checks: send an unblock prompt tied to the node
  - If result is superficial: demand explicit validation and file list
  - If all nodes in the wave are done, blocked, or timed out: cancel this cron and report

  Report concisely: N done, N working, N blocked, quality observations."
)

Nudge Prompts

Generic nudge (idle, no result):

ntm send "$WAVE_PROJECT" --pane="$N" "You own node WG-00N. Finish the node, run its validate commands, and write WG-00N_RESULT.md only at <absolute-run-dir>/WG-00N_RESULT.md. Do not create repo-root, .dac, .ntm, or /tmp fallback artifacts. Stay inside the declared write scope."

Depth nudge (result lacks proof):

ntm send "$WAVE_PROJECT" --pane="$N" "<absolute-run-dir>/WG-00N_RESULT.md is not sufficient yet. Add the exact files changed, explicit validation commands, and whether the node is done, blocked, or needs_rework. Do not write evidence files in the product repo."

Boundary nudge (scope drift):

ntm send "$WAVE_PROJECT" --pane="$N" "Do not code past your declared write scope. If the node truly needs broader edits, stop and propose the smallest Beads graph change instead."

10. Collect Results and Advance the Graph

Once the wave has produced results, or the timeout is reached:

1. Cancel the monitoring cron
2. Capture final pane state:

   ntm --robot-tail="$WAVE_PROJECT" --lines=200
   

3. Read every <absolute-run-dir>/WG-*_RESULT.md for the active wave completely. Treat repo-root, .dac/, .ntm/, or /tmp result files as misplaced evidence that must be moved to the run directory before reconciliation.
4. Cross-reference each issue's current state with br show {id}. The lead should already have claimed each issue before dispatch; never trust worker prose, pane activity, or file changes alone.
5. Independently run each node's validate_cmds yourself before treating it as done
6. Reconcile br state to the verified outcome:
   • Still open/unassigned but work landed: repair attribution first with BR_AGENT_NAME=<worker-id> br update {id} --claim --json, then close only after validation passes
   • Closed with blank assignee: repair attribution with br update {id} --assignee <worker-id> --json and add a reconciliation comment
   • Validation passed: leave it closed (or run br close {id} --reason … if the worker forgot)
   • Real blocker: first apply the blocked-node handling contract in references/failure-mode-contracts.md; carve any model-solvable prep or proof child before blocking the smallest affected node
   • Needs rework: br reopen {id} — the issue returns to the ready frontier
7. Re-render the view: python3 ~/.claude/skills/_shared/scripts/br_helpers.py render-workgraph --epic $(cat <absolute-run-dir>/EPIC_ID.txt) --out <absolute-run-dir>/WORKGRAPH.md
8. Re-query the frontier: python3 ~/.claude/skills/_shared/scripts/br_helpers.py ready --label slice:{slug}
9. Launch the next ready wave

Do not mark a node done based only on a worker's self-report.

11. Repeat Until the Graph Is Exhausted or Truly Blocked

Continue wave by wave until one of these is true:

• All execution nodes are done
• The remaining graph is genuinely blocked on a user decision or external system after the blocked-node handling contract has exhausted model-solvable prep
• Validation failures show the graph itself needs to be rewritten before more work

If a node's result reveals a better decomposition, update the graph before the next wave instead of forcing the old split.

12. Run a Final Integration and Review Wave

After all execution nodes are complete, the root runs final integration in this same invocation. Final integration and closeout are never left as open or blocked Beads for a future session. Use the same swarm runtime; do not default to /codex:rescue.

Spawn a small review swarm: one Grok runtime controller, one independent Grok fresh-eyes reviewer, and one Codex final-authority reviewer:

ntm spawn "$REVIEW_PROJECT" --grok=2:grok-4.5 --cod=1:gpt-5.6-sol:medium --no-user --stagger-mode=smart
ntm --robot-wait="$REVIEW_PROJECT" --condition=idle --timeout=120s

If SOL is unavailable, replace the Codex allocation with --cod=1:gpt-5.6-terra:ultra; do not ask the Grok controller to make the final acceptance decision. If the review becomes pivotal/high-consequence or another model has already failed to resolve it, use --cod=1:gpt-5.6-sol:max instead.

Reviewer prompt:

• Read the original task, live Beads state via br show / hydrate-node, the rendered WORKGRAPH.md view if present, and the current git diff
• Confirm the graph intent matches the repo state
• Run relevant build, test, lint, and typecheck commands
• Fix only integration bugs or validation failures
• For UI, UX, visual, design-system, screenshot, or ambiguous review-heavy work, use Grok 4.5 for the fresh-eyes review of the final diff and validation evidence. If the Grok 4.5 design route is unavailable, record that route blocker and use Codex gpt-5.6-sol max only for pivotal authority or explicit failed-model triage; ordinary authority remains SOL medium.
• For visual parity, ask independent fresh-context reviewers the ORIGINAL question and require severity-classified findings until two consecutive reviews report no blocker or material shortfall.
• Run br epic close-eligible --json to retire the slice's epic if every child is closed; surface any leftover open child as the blocker
• Run python3 ~/.claude/skills/_shared/scripts/br_helpers.py flush so .beads/issues.jsonl reflects current state
• Commit if there are clean, scoped changes to save (include .beads/issues.jsonl, exclude .beads/*.db*). Prefer Grok 4.5 for the mechanical execution of a $commit node when the Bead names the exact commit scope, validation, leave-list, and no-wildcard staging rules; Codex gpt-5.6-sol owns acceptance of the commit plan and final review of the result.
• Write <absolute-run-dir>/DAC_FINAL_RESULT.md

DAC_FINAL_RESULT.md MUST end with:

{
  "commit_hash": "<hash or null>",
  "summary": "<1-2 sentence summary>",
  "files_changed": <number>,
  "status": "success" | "error"
}

13. Report to User

When the final review result is available:

• If commit_hash is present, show the commit and file summary
• If no commit was made, say why
• If the graph is blocked, report the exact blocking node and the smallest next decision needed

Rules

• br (the slice's epic + child issues in .beads/) is the execution source of truth
• WORKGRAPH.md is a generated view; never hand-edit it — re-render with br_helpers.py render-workgraph
• State changes flow through br update/br close, not markdown rewrites
• Invocation artifacts (EXECUTION_CONTEXT.md, WG-*_RESULT.md, DAC_FINAL_RESULT.md, EPIC_ID.txt) still live under the overlay-backed invocation root in skillbox-config, but only EPIC_ID.txt is a pointer to source-of-truth Beads state; the rest are generated views or evidence attachments
• Never create new repo-local .dac/, .ntm/, repo-root WG-*_RESULT.md, repo-root WORKGRAPH.md, repo-root EXECUTION_CONTEXT.md, or repo-root DAC_FINAL_RESULT.md files. Existing legacy files may be read as historical evidence, but new waves use the overlay-backed invocation root.
• Ready frontier comes from br_helpers.py ready or scheduler; do not pre-dispatch blocked nodes
• Subgoal frontiers require both slice:{root} and subgoal:{slug} filters; prove multi-label br ready AND semantics or use helper-side AND filtering before launch
• Subgoal controller issues are durable delegation boundaries. NTM session names and SUBGOAL_RESULT.md files are derived evidence, not topology
• The Codex root planning authority owns subgoal creation, shared files, cross-subgoal graph shape, final integration judgment, and commit acceptance. The Grok runtime controller coordinates final validation, Beads flush, and the accepted commit operation.
• Child orchestrators may claim/close/block only leaf issues in their assigned slice:{root},subgoal:{slug} frontier and must propose cross-subgoal changes to the root instead of mutating topology directly
• Do not accept a subgoal as done from controller status or child prose; run the independent completion gate before rollup
• writes ownership is a hard boundary, not a suggestion
• Default to NTM swarm execution; do not substitute local ad hoc workers
• Cwd/workflow routing, skill-tag extraction, cleaned-request drafting, read-only clerk/preflight nodes, bounded scripting, fixture/docs cleanup, generated-command cleanup, classification, and scoped commit-runner nodes should prefer the voice-to-text Grok dispatcher, NTM Grok plugin, Swimmers hidden Grok sessions, direct headless Grok, or a local Grok 4.5 task-runner route when the Bead is explicit; reconcile all output through the normal Beads/result-artifact contract, validation, and stronger-model review
• NTM runtime orchestration must use a Grok 4.5 plugin controller. Design-related nodes and design/fresh-eyes review nodes should also use Grok 4.5. Planning, no-ragrets bead composition, decomposition/synthesis, domain-planner sessions, system design, impactful execution, integration review, commit acceptance, and final-say nodes must use Codex gpt-5.6-sol by default, with Codex gpt-5.6-terra at ultra only when SOL is unavailable
• The lead must claim every dispatched node for the assigned worker and verify status=in_progress plus assignee before edits begin; unclaimed pane activity does not count as in-flight work
• The lead must not collapse into a leaf worker. After dispatching one Bead or subgoal, continue selecting, claiming, dispatching, and tending other ready work unless the root is performing final integration or a recorded emergency unblock
• One worker per ready node; one wave per ready frontier
• If the frontier is too large, batch it; do not oversubscribe the swarm
• Prefer 2-8 meaningful nodes; 10 is the hard cap per wave
• Use describe only for fuzzy nodes
• Use ask-cascade only for the first blocking strategic ambiguity
• Every worker gets its br issue ID, the run directory path, the verified claim/assignee, and the lifecycle commands (br show claim check, --reason --suggest-next)
• Workers stamp BR_AGENT_NAME/BR_HARNESS/BR_MODEL before any br mutation
• Node workers do not commit; only the final integration review commits, and it includes .beads/issues.jsonl while excluding .beads/*.db*
• Independently run validate_cmds and reconcile br state before treating any node done
• If ntm or br is missing or broken, stop and surface the prerequisite gap
• Sequential waves are fine; fake parallelism is not