| 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 executionntm for command reference, session inspection, and swarm debuggingvibing-with-ntm for swarm orchestration patterns, pane hygiene, and
transport-layer recovery when the problem is NTM rather than the workgraphcodex-tmux only when the user explicitly wants a detached single-worker
fallback instead of an NTM swarmmodes-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:
workflow_builder.invocation_root from the resolved contextclient_dir + /invocations when client_dir is present- 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 reporun_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 handEXECUTION_CONTEXT.md — optional generated dispatch summary rendered from Beads; never the authoritative worker contractWG-*_RESULT.md — per-node worker evidence attachments (changed files, validation output, blockers); status and contract remain in brDAC_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)
- Look for
context.yaml in the working tree (generated from the client overlay)
- If found, load project-specific settings automatically
- If not found, tell the user no overlay matches and create one using the skillbox-quickstart scan + generate flow before proceeding
- 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:
- 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.
- Partition the ready frontier by
subgoal:{slug} and exclude leaves without
the root slice:{root} label.
- Verify subgoal-level
writes: do not overlap across the active cohort and no
active leaf depends on another active subgoal.
- Treat
shared_files: as root-owned and sequential. Child orchestrators may
propose edits to shared files but may not apply them.
- 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})"
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:
- A node brief rendered from Beads (
br_helpers.py render-node-brief <id>)
- The exact
br issue ID for the node, plus the absolute run directory path
for evidence artifacts
- The node's
concern, depends_on, writes, done_when, validate_cmds,
and risk_gate (read these from br show {id} if not inlined)
- The hard ownership rule: edit only the declared
writes
- 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
- The attribution preamble:
export BR_AGENT_NAME=<role> BR_HARNESS=<harness> BR_MODEL=<model> before any br mutation
- The artifact boundary: write evidence only to the absolute run directory,
never to the product repo root,
.dac/, .ntm/, or /tmp
- 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
- 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:
- Cancel the monitoring cron
- Capture final pane state:
ntm --robot-tail="$WAVE_PROJECT" --lines=200
- 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.
- 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.
- Independently run each node's
validate_cmds yourself before treating it as
done
- 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
- 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
- Re-query the frontier:
python3 ~/.claude/skills/_shared/scripts/br_helpers.py ready --label slice:{slug}
- 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 truthWORKGRAPH.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
