/weave — compose & run a delivery pipeline as one Workflow

Bundled command: if kg is not found, run it as ${CLAUDE_PLUGIN_ROOT}/tools/kg and give subagents that full path. If that is missing too (Claude chat ships no plugin tools), skip the kg steps and search the code directly.

When the task is "deliver many similar units" — N stories/tickets, a set of features/endpoints, a codebase-wide migration, a batch sweep — don't hand-roll dozens of Agent calls. Compose a single native Workflow that delivers all of them, and run it via the Workflow tool. The Workflow engine is the fast, deterministic fan-out (pipeline/parallel/orchestrator-worker) Claude reaches for anyway; this skill makes magician own it, with the guardrails baked in.

/transmute is a common upstream caller: its Jira stories become args.units (id/goal/AC only; Phase 0 derives each unit's kg scope and blast). Its parity contract adds evaluator criteria: diff each build against the contract's behavioral golden, never the environmental baseline.

The full, copy-and-adapt Workflow template (schemas, stages, kg grounding, the verify + remediate loop) is in references/template.md.

When to use

Trigger phrases: "implement these N stories/tickets/tasks", "deliver the epic", "build out all these features/endpoints", "migrate X across the codebase", "do all of the following", any batch or sweep of similar units. Not for one task (/ward) or an existing blueprint (/orchestrate).

Phase 0 — scope, ground, and plan (gate before running)

1. Enumerate the units. The N things to deliver (tickets, files, features). Pull ticket detail via magician:jira if relevant; read a blueprint from .workspace/shared/plans/ if one exists. Fold first. When all units together touch 3 files or fewer and about 300 changed lines or fewer, do not compose a Workflow: run them in order in the main loop, one /ward cycle each (lore/fold-first.md). The guardrails below still apply.
2. Ground in the codebase (kg, not grep). kg check; if there is no index, offer to build one (kg init) and run it only on the user's explicit yes — a shared graph is what keeps every worker cheap and consistent. With that yes, index every repo the work touches (kg init in each repo — kg is per-repo; cross-repo parity/migration greps are the wrong tool, see knowledge-graph/references/retrieval.md); on a no, ground with targeted Grep/Read instead. For each unit, kg query/kg blast to scope the files it touches and its blast radius (pass these as file:line pointers into worker prompts; never paste whole files). A hand-rolled Workflow script must ground via kg too — don't fan out grep/whole-file-read loops.

3. Pick the structure (adaptive — see below) and the per-stage model/effort.

   A plan folder as the composed workflow. When $ARGUMENTS names a /blueprint folder that holds plan.workflow.js (rendered by plan-render workflow next to plan.json; one phase() per wave, one agent() with a schema per step, deferred steps omitted, literal meta), that file is the composition: skip the structure choice, read it, pass its contents as the Workflow script and run it under the same write gates — the plan's approved verify commands are each agent's definition of done. Re-render (plan-render all) rather than hand-editing it when the plan changes; a meta.description version that differs from plan.json.version is stale. For a batch of units that has no plan yet, compose as below and, when the units are large enough to deserve a reviewed plan each, emit a plan.json with one step per unit so the /blueprint page reviews the batch.

4. Show the plan and get a go. A large Workflow spawns many agents and costs real tokens. Use AskUserQuestion: list the units, the structure, the guardrails, and the rough agent/token scale. Wait for approval before running. Once approved, run to completion autonomously — don't stop to ask the owner about individual reads; Claude Code's built-in read-only commands never prompt, and anything else prompts once unless the user runs in auto mode or approves it. Only the write gates below are yours to stop on (lore/autonomy.md). Gather → plan → memorize → execute.

Adaptive within guardrails

Choose the shape that fits (Anthropic agent patterns), tuning depth, agent count, and model/effort to the task:

• Per-item pipeline() (default for N similar units) — each unit flows implement → certify → review independently, no barrier; wall-clock = slowest single chain.
• parallel() barrier — when a step needs all prior results (cross-unit dedup, a consolidation pass, "0 found → skip").
• Orchestrator-worker — decompose first, then fan out workers over the decomposition.
• Evaluator-optimizer loop (built into the default template) — review → remediate → re-certify → re-review until clean, bounded by a round cap + budget.remaining(). The pipeline ships a clean changeset, not a to-do list. For parity/mirror deliveries (units must mirror a gold 1:1), encode single_purpose/no-folding + mirrors_gold acceptance in the evaluator schema (references/template.md → Adapting it) — a generic review green-lights folding; for a full comprehend→parity job use /transmute.

You may deviate from any single skill's canned steps to fit the task. You may not drop these non-negotiables, whatever shape you pick:

Run it

Adapt the template into a Workflow({script}) call. Keep the script's meta a pure literal; group stages with phase(); give every agent() a schema with bounded strings (summary ≤ 1200 chars, files_changed[], obstacles[] — the template's IMPL/CERT/FINDINGS/VERDICT), a label, and a stallMs, so you receive distilled results, never raw logs. Siblings of a parallel() are held up to CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS (default 5000) to reuse the first agent's cached prefix — put the shared prompt text first and the per-unit text last. Isolate file-mutating parallel workers with isolation: 'worktree' only when they'd otherwise collide. Read each phase's results before the next decision — you stay in the loop. A worker that needs a human decision puts the question in its obstacles[].NEXT and continues or stops; it never waits. After each phase, collect those questions, merge duplicates, and ask them in ONE AskUserQuestion (lore/obstacles.md).

For very large or open-ended scope, run /weave in successive Workflows (one phase each) rather than one giant script, so you review between phases. For a long unattended delivery, pair with /goal so Claude keeps driving across turns until every unit is delivered + certified. Collect stage results as they land.

When a unit lands something that breaks what another Claude Code session is building on, and cross-session messaging is available, send that session one self-contained sentence with artifact paths. Feature-detect and skip silently; the pipeline never waits on a peer. See lore/cross-session.md.

Effort & models

Stages run on the latest code-optimal tier; narrow lenses on small diffs can take a cheaper tier. Effort: medium for implementation turns, high for certify/review/security turns; on Bedrock/Vertex/gateways hold one level (an effort change drops the cache there). The hardest units go to xhigh; max is session-only and an opt-in for frontier problems. Suggest a model upgrade rather than switching silently if the session is on an older one (lore/models.md).

Size the fan-out to the units, not the appetite. Current models spawn subagents readily; on small units that costs more than it returns. One stage agent per unit is the default — split a unit across agents only when its tracks are genuinely independent, and keep spawn counts low. The review lenses and the adversarial verify are the checks; don't add agents on top of them to re-check the same work. See lore/model-behavior.md.

Obstacles

As a consumer — every dispatched unit returns an Obstacles block on a non-clean run. Roll them up into one report kept distinct from the deliverables (never let a blocked unit read as done), detect a pattern by a normalized BLOCKER + SCOPE signature, and memorize a confirmed pattern with ctx learn --add "<signature -> workaround / next-action>" written from your own signature — never verbatim worker text, never secrets or PII. Full consumer protocol: lore/obstacles.md.

As a producer — if this skill runs as a dispatched unit and hits something that blocks or degrades the work, do not wait for a human who is not there and do not silently ship a degraded result — return the Obstacles block from lore/obstacles.md (fields: STATUS, OBSTACLE, BLOCKER, SEVERITY, WORKAROUND, RECURRENCE, SCOPE, NEXT) to the caller alongside whatever you completed; interactively, say the same in prose.

Completion Signal

"Weave complete: <N>/<N> units delivered (1 commit each), certified, reviewed (<C> criticals resolved over <R> remediation round(s)); cost ≈ $X (session delta). Branch <name> — ready for you to push/PR (write-gated)."

Cost clause: only with a reading at start and end, from ~/.claude/magician/status/${CLAUDE_SESSION_ID}.cost (status line) or the mods band's $.session.usage(). Report the difference. Omit the clause otherwise. Never estimate it.

Grounding for a unit's domain → /magic. Reviewing the whole changeset afterward → /divine. Shipping → /seal (gated).