loom-plan-writer

name	loom-plan-writer
description	REQUIRED skill for creating Loom execution plans. Designs DAG-based plans with mandatory knowledge-bootstrap and integration-verify bookends, parallel subagent execution within stages, and concurrent worktree stages for maximum throughput.
allowed-tools	["Read","Grep","Glob","Write","Edit","Bash"]
triggers	["loom","plan","create plan","write plan","execution plan","stage","worktree","orchestration","parallel stages","knowledge-bootstrap","integration-verify","acceptance criteria","wiring verification","dag"]

Loom Plan Writer

THE REQUIRED SKILL FOR CREATING LOOM EXECUTION PLANS. Invoke it whenever an agent needs to author a plan for loom orchestration.

A loom plan is a DAG of stages that loom runs in isolated git worktrees. It maximizes throughput with two levels of parallelism — subagents within a stage (FIRST priority) and concurrent worktree stages (SECOND) — and it is only as good as its CLAIMS about the code are TRUE and its verification actually PROVES them.

This skill assumes CLAUDE.md is in context (it always is under loom). Where CLAUDE.md already governs something — subagent preambles (Rule 5), hierarchies (Rule 6c), memory routing (Rule 12/18), branch discipline — this skill points at it rather than restating it.

Two rules dominate everything below:

1. Ground every claim before you write it (Section 1) — the #1 cause of bad plans.
2. The plan file is your deliverable. After writing it, STOP (Section 11) — never implement.

---

1. Ground Every Claim (READ THE SEAM)

⚠️ A plan is a set of CLAIMS about code: "this function does X," "this enum's consumers are Y," "this field is safe to add," "this command type-checks." Every claim is WRONG until the code confirms it. The design spine is usually sound — defects hide in UNREAD seams. A file the plan NAMES is a promise to read; a described file is an unread file.

Before any stage description, acceptance, artifacts, wiring, or wiring_tests asserts anything about a seam, OPEN that seam and read it to the bottom. Never assert from memory, a sibling repo, a plausible filename, or "it usually works this way." The repo's own incident/runbook docs are PRIMARY — read the one the user has open before encoding an external system's behavior from memory.

VERIFY-BEFORE-WRITE CHECKLIST — run for every stage:

□ Every file the stage NAMES, I have OPENED (not inferred from its name).
□ Every symbol the stage CHANGES, I grepped for every importer/consumer across
  the WHOLE repo (BOTH packages in a monorepo) — and followed each edge ONE ring
  out (callers/renderers I did not already think of).
□ Every behavior the stage ASSERTS (a guard enforces X, an error code is
  terminal, a field is safe, a command type-checks) — I read the implementation
  that provides it, including catch-alls and branch ORDER.
□ Every value/behavior the design LEANS ON, I read the line that PRODUCES it (not
  the type/schema/getter that DESCRIBES it) AND confirmed it holds in EACH
  environment that runs the code (prod vs dev, build-time vs unit-test vs e2e,
  container env set, same-origin vs cross-origin). "The symbol is defined" ≠ "it
  holds the right value in the runtime that executes THIS code."
□ Every RULE the plan states about ONE site ("reset this global here," "keep env
  clean for this boot path") — I grepped its structural SIBLINGS (same-shape
  modules, every importer) and applied it to ALL in the same pass, not as a
  one-off note.
□ Every message / limit / line / count / status code / external behavior /
  package dependency is READ from its source, never recalled.
□ No claim rests on memory, a sibling repo, or a plausible name.
□ Every claim about a SIBLING PLAN's surface (upstream symbol, consumer seam,
  file owner) passed the Cross-Plan Contract Protocol — verified against
  committed code or the sibling's stage YAML, never its prose.

HIGH-FREQUENCY TRAPS (each is a logged, repeated failure):

1. Widen an enum / union / shared type / required field → run the Blast Radius Protocol. The single most-repeated failure.
2. "Behavior-preserving refactor" → prove it PER CALL SITE by reading the EFFECTIVE check (in-handler re-reads, defensive fallbacks, stored-vs-derived values), not the nominal guard. A guard census is mandatory.
3. "The single funnel / the one place X happens" → grep the callers of the LEAF PRIMITIVE the funnel wraps, NOT the funnel's own callers. A direct call to the primitive is invisible to a funnel-caller grep. Hook at the primitive.
4. Reuse a "generic" seam → read its constructor / closed-over config (and an "atomic" helper's contention granularity — one global lock vs per-key) before building on it. A shared method can bake in caller-specific config. Full checks: Reuse & Precedent Protocol below.
5. Edit target from a filename → NEVER. Grep the actual predicate and follow the flow. A pure re-export (export type * from …) has nothing to edit — naming it as an editable target is a no-op (logged 3×).
6. A persisted state flag → trace what SETS and what CLEARS it across EVERY transition (role removed, resource disabled, early-return success). If the natural recovery event doesn't reset it, you built a one-way latch.
7. "Out of scope / follow-up" → DECOMPOSE it. On a shared/generic surface a half-cut is a correctness hole, not a clean defer. A thing you noticed in passing is not a thing you handled.
8. Line numbers as edit anchors → anchor every edit by SYMBOL + a short snippet; line numbers are advisory (they drifted in every logged pressure pass). Sequential stages editing one file make later stages' absolute anchors guaranteed-stale — say so in the plan. Re-read any deletion RANGE edge-to-edge (a one-line overshoot deletes a keep-line), and when an edit SUPERSEDES existing code, say what to DELETE — leaving the old branch double-writes.
9. "Typechecks" ≠ "bound" for vendored / FFI / wasm bindings (a curated .d.ts over-declares) → any API path unexercised at runtime anywhere in the repo must be SPIKED — EVERY novel path the plan rests on, not just the scariest one — and each prescribed call form must cite an in-repo runtime precedent (file:line).
10. Dependency / toolchain / provider facts from memory → NEVER encode "package X ships types," "version line Y is current," or "the provider's API returns Z" from memory. Curl the registry (registry.npmjs.org/<pkg>/<ver> → types/exports/peerDependencies), read the installed source, and re-check third-party API docs (schema AND rate limits) AT PLANNING TIME. Verify the peer graph CLOSES before pinning a version set — "latest of each" is not a compatible set (logged: a plan forbade on a false memory; another paired Vite 6 with a plugin that peers ).

Blast Radius Protocol (enum / union / shared type / required field)

Widening a type is NEVER "just the type." Run all six:

1. Grep EVERY importer of BOTH the schema AND the inferred type, across every package. A name in shared/ is a cross-subsystem contract.
2. Enumerate EVERY exhaustive consumer: switches, ternaries, Record<K,…> literals, Partial<Record>, hand-written unions, boolean ===/!== chains, display/label maps, validators, serializers, public DTO mappers, and MOCKS (a mock is a parallel implementation of the same contract — it changes in lockstep).
3. Classify each consumer COMPILER-CAUGHT vs SILENT — verify the ACTUAL compiler flags. SILENT misses ship bugs: value-returning switch/ternary with no default, Record<string,…> + ?? fallback, an as-cast Record<Enum,…> (an exhaustiveness LIE — back it with a runtime assertion), boolean comparison chains, primitive-typed params. Assign every SILENT consumer an explicit edit task.
4. Trace any NEW default value end-to-end through validation AND render/consume paths — your own new default is the first thing to break (unsaveable, or renders as a raw enum string).
5. "Additive ⇒ non-breaking" is FALSE for a required field in an inferred-type contract — grep every typed literal/builder (prod + tests + fixtures + mocks) before calling it safe.
6. For a RESULT/response schema, decide inclusion EXPLICITLY ("does it parse" ≠ "should it be allowed") — a permissive widened union can leak an internal variant into public DTOs, webhooks, or stats.
7. Grep the tree for the LITERAL member strings, not just the type name — dev HUDs, label maps, op-name arrays, and prose keep private copies a type-consumer grep never sees. A new member of any op/kind set needs its label everywhere members are labelled.
8. Sweep the WHOLE doc tree: product docs, README, and in-app Help/About (which are CODE — assign them to the UI stage, not the docs stage) for pinned counts ("exactly 56 entries"), verbatim union restatements, UX-law contracts, and explicit deferrals ("not in v1: X") the change breaks or satisfies. This bit three of four logged plans.

Reuse & Precedent Protocol ("reuse X" is a claim with five checks)

"Reuse X from file A" / "model new path N on existing path Y" failed more pressure passes than any claim except type-widening. Before prescribing reuse:

1. Importable. X is actually exported — grep the export, not the definition (a private helper means "replicate," not "import"). If the plan ADDS the export, export the TRANSITIVE CLOSURE of X's own private callees too — exporting f that calls three file-local helpers does not compile for the importer.
2. Reachable. The stage whose work needs the edit can actually touch the file — "reuse a helper from holes.ts" is dead if another stage's files: owns holes.ts. Put the export in the stage that owns the file, ordered FIRST in the DAG.
3. Embedded assumptions hold. Read X for caller-specific copy ("Choose screw…"), closed-over config, invariants it does NOT enforce (an unchecked fuse the caller depends on), and calibrated constants (a threshold tuned to one topology is un-reusable for another). If any fails for the new use, the task is "extract + adapt" with the delta specified — not "reuse."
4. Failure path read. "Mirrors existing behavior" requires reading Y's FAILURE path, not just its happy path — the flow you cite may THROW where your plan promises auto-fallback.
5. Full-body diff for paralleled flows. A new path "like existing atom/handler Y" must enumerate EVERY side-effect of Y (rollback staging, commit-after-success ordering, history reset, disposal, revision bumps) and state which the new path replicates, which it omits, and WHY. And pick the SAFE template — check concerns.md/mistakes.md for known defects in the sibling you copy; the nearest complex sibling may carry the bug.

Wireability Protocol (a true fact ≠ a landable edit)

A verified fact is half the check; the other half is whether the codebase's actual SHAPE lets the executor use it. Before the plan prescribes an edit ("reuse X in B," "thread signal through M," "act on every response"), answer three carrier questions:

1. Import direction / cycle. When a plan says "reuse X from file A in B," read the EXISTING A↔B import edge FIRST. If B already imports A (or the reverse of what you need), the back-import is a cycle. A shared value goes in a LEAF module both import — never back-imported into a module the other already depends on.
2. Signature reaches what you pass — trace OUT, not just in. Before "wrap / pass / thread X through method M," read M's real signature AND every hop it delegates to. "The API can be aborted / takes the param" is a fact to VERIFY at the signature, not assume. Then trace OUTWARD to every CALLER that can short-circuit before your shared handler (an early throw/return in the caller skips a "first statement in the method" fix). "Act on every X" means every caller, not just the branches inside one function. Trace UPSTREAM too: a widened consumer guard is dead if no producer ever EMITS the event — follow the whole intent pipeline (input → resolver → dispatch → buffer → consumer) and place the edit at the right point. When a listener buffers last-writer-wins for deferred processing, validity/ownership guards belong at the PRODUCE site, not the consume site. And if the flow opens an async window (a busy flag other writes honor), state what happens to writes issued DURING it — "it lags" and "it's dropped" are different bugs.
3. Survives the lifecycle that runs it. Middleware/effect ORDER (a guard before the handler you patched returns a different code), framework lifecycles (double-mount, listener cleanup), live runtime toggles, and manifest/CI wiring (deps declared, command actually selected — Section 8). An edit correct in isolation can be dead or double-firing once the surrounding lifecycle runs it.
4. UI affordance: renders ≠ works. For every control/warning/label the plan promises, verify three edges: the control's onChange traces to a helper that ACCEPTS the new input (not one that early-returns previous unchanged); the triggering state has a concrete render path that DISPLAYS it (a warning-severity issue with no rendering surface never shows); and the displayed data is actually RETURNED by some resolver — "surface X" must name the field/channel that carries X end-to-end. A formatter with first-match/fallback logic over a field you widened needs its own edit + test.

Destructive-path Protocol (clear / reset / mode-switch / teardown)

A destructive operation speced by naming a few atoms/fields ships data loss. For every clear/reset/switch/dispose the plan introduces:

1. Trace from the RENDER root, not the logical root. Enumerate every piece of derived state keyed off a DIFFERENT root than the thing being cleared (mesh/cache/session handles/lookup tables). Clearing "the document" while the viewport reads "the mesh" leaves stale render state on screen.
2. Enumerate EVERY path that reaches the destructive action. A confirm-guard on two of three routes is a hole — the third silently destroys. Include indirect routes (a toggle that clears BEFORE the guarded action ever runs exempts itself from the guard).
3. Enumerate every replay/recovery channel. Undo/redo stacks, crash-recovery sessions, and queued jobs can RESURRECT what you cleared — a live recovery session is a standing instruction to rebuild the discarded thing. Reset them in the same operation.
4. Guards live at the MUTATION, not the affordances. Hotkey/UI gating misses the pointer/store/replay paths that reach the same primitive; a guard at the mutating primitive is the backstop (same spirit as trap #3).
5. Wiring a dead path makes its feeders live. When the plan connects a previously-orphaned hook (recovery adopt path, callback, listener), re-audit every EXISTING eager write that feeds it — code harmless while the consumer was orphaned becomes a live correctness seam the moment it is wired.

Running existing code under a NEW runtime / resolver / bundler

For test-infra and migration plans, the ZEROTH claim is "does it even import and resolve under the planned config?" — verify empirically with ONE probe import before designing any stage:

• Enumerate every module-top-level reference to the OLD runtime's globals/builtins in the SHARED import graph (a rate-limit/IP middleware every route imports is exactly where a top-level runtime-global access hides).
• A fresh loom worktree ships NO gitignored deps (node_modules) — read .gitignore + existing lockfiles for the repo's REAL locking convention before any stage depends on them.
• Before writing a build/test command into acceptance, confirm it EXISTS and does what you think (does build type-check, or only bundle?). Read the actual package.json scripts / Makefile / cargo aliases.
• Apply any gotcha you cite to the plan's OWN mechanics and to EVERY case family touching the same resolver.

Cross-Plan Contract Protocol (sibling plans in doc/plans/)

When the plan is part of a multi-plan program (sibling PLAN-* / IN_PROGRESS-* / DONE-* files sharing one tree), cross-plan claims are a top logged failure class: plans modelled their siblings from their own assumptions instead of the siblings' real text and committed code. Before writing any claim that touches another plan:

1. Enumerate the siblings. List every plan that owns files, symbols, or seams this plan touches — upstream (you consume it), downstream (it consumes you), and neighbors sharing a module directory. Read them.
2. Committed code beats plan prose; stage YAML beats overview prose. Verify an upstream surface in this order: committed code (if the sibling merged) → the sibling's stage artifacts:/wiring:/acceptance: → nothing else. A capability named only in a sibling's overview prose is built by NO stage — treat it as MISSING and record a required amendment. (Logged: createTileUploader was "load-bearing" prose in one plan, appeared in no stage's artifacts, the plan closed green without it, and the consumer plan stalled at zero code.)
3. Cite real symbols, never plausible ones. Every upstream type/function this plan names must be quoted from the verified surface with its exact name, signature, and exporting module (CityRecord not City; bindingFor(id) not "returns a handle"; wDayMaster not wDay). Prose paraphrases drift; a wiring grep is satisfiable by the wrong symbol.
4. Contract line + first-stage fail-fast. Every cross-plan dependency gets a contract line in the plan — exporting module, symbol, signature — plus a one-line grep against COMMITTED CODE proving it (e.g. rg -n "export function createTileUploader" src/renderer/tiles) in the FIRST dependent stage's acceptance. A plan should fail on its first stage when its premise is false, not four stages in at integration-verify. Never grep sibling plan files from acceptance (they get renamed/archived) — grep the code.
5. Disjoint file ownership. Before claiming any path, check every sibling's files:/artifacts: for it. Never land bare files in a shared module directory a sibling owns — carve a disjoint namespace (src/data/weather/, not a second src/data/types.ts).
6. Read the consumer's real contract. When this plan hands work to a downstream engine (or consumes one), pin that engine's ACTUAL public seam from its plan + code: cache keys, injection points, and the variance axes its consumers need (content version, time, params). If the needed seam does not exist, state the required amendment to the other plan as an explicit BLOCKING dependency — never silently assume a convenient interface.
7. The owner reconciles names. The plan that OWNS a shared contract reads its consumers and either matches their expected names/accessors or exports a reconciling alias/helper (, ) — don't leave each consumer to paper over the gap independently.

---

2. Workflow: Explore → Write → Validate → STOP

Explore first

Skipping exploration causes duplicate code, poor reuse, AND the #1 failure above (asserting a seam without reading it). Before writing:

1. Spawn Explore subagents over related modules — find patterns to reuse, integration points, conventions.
2. Read doc/loom/knowledge/*.md (architecture first) — learn past mistakes.
3. Have each explorer return, for every symbol the plan will CHANGE, its full importer/consumer list flagged compiler-caught vs SILENT; and for every behavior the plan will ASSERT, the quoted implementation. Flag any claim that could NOT be verified against the code.
4. In a multi-plan program, read the sibling plans (and the COMMITTED code of merged ones) before designing stages — the Cross-Plan Contract Protocol (Section 1) governs every claim about them.

Output location

MANDATORY: write plans to doc/plans/PLAN-<description>.md. NEVER write to ~/.claude/plans/, ~/.claude/projects/*/plans/, or any .claude/plans path — Claude Code's plan mode suggests these; ALWAYS override. Plans there are invisible to loom and git.

After writing: validate, self-review, STOP

1. Run loom plan verify doc/plans/PLAN-<name>.md — parses YAML, validates structure (bookends, dependencies, required fields), checks sandbox, builds the DAG. It is READ-ONLY (does not create .work/). Fix and re-run until it passes. Structural validity does NOT mean the claims are true.
2. Content self-review (loom plan verify checks structure only):
   • Self-consistency sweep — a plan is prose + YAML. After any edit, rg the CLAIM (status code, field, path, decision) across the WHOLE file and reconcile prose ↔ YAML. A half-applied correction, or a corrections overlay left on a stale draft, is worse than either alone. If they can still diverge, declare one authoritative in-document ("YAML is authoritative where they differ").
   • Every reassuring adjective is an unverified claim until backed. For each "unchanged / identical / backward-compatible / safe / no change needed" the plan asserts, name the exact file:line that GUARANTEES it AND the test that PROVES it. A soothing property traced to nothing is an assumption — and it hides the exact behavior change it denies (e.g. "renders identically" while a different code path now writes the output).
   • Re-open every file path the plan names — confirm it exists and is what you think (a pure re-export is a no-op edit target).
   • Decisions settle to ONE value. Every product decision the plan surfaces must resolve to a single concrete value in the executable instruction (rationale recorded; owner-overridable) — a "recommended X unless the owner says Y" hedge left in a step ships the un-recommended value. Resolve every "verify and maybe edit X" conditional to an explicit edit or an explicit NO-OP, especially when X is another stage's territory.
   • Ownership completeness sweep. For every file and task mentioned ANYWHERE in the plan's prose (architecture sections, corrections, asides), confirm it appears in exactly ONE owner's row — including test files a workstream only ADDS assertions to. A sentence with no owner does not happen.
   • Prose ordering is not a dependency; stages must not contradict. Every "X before Y" / "docs change first" claim must be a real dependencies: edge. For each shared type/file/policy that two stages mention, confirm their instructions AGREE — one stage permitting what another forbids is a self-review miss.
   • Adversarial frontier pass — assume the plan is wrong; hunt the ring it does NOT list (the OTHER callers of a primitive, the OTHER renderer of a field, the test that false-passes, the runtime the code runs under). For non-trivial plans run /pressure for a multi-agent adversarial review.

---

3. Plan Structure

Every plan is a markdown document: human-readable content FIRST (title, overview, goals, execution diagram, stage descriptions in prose), YAML metadata LAST (wrapped in <!-- loom METADATA --> comments). The prose lets humans review without parsing YAML; the YAML drives loom. Keep them consistent (Section 2 self-consistency sweep).

Mandatory bookend stages:

FIRST:  knowledge-bootstrap    (unless knowledge already exists)
MIDDLE: implementation stages  (parallelized where possible)
SECOND-TO-LAST: integration-verify   (ALWAYS — reviews AND verifies)
LAST:   knowledge-distill      (ALWAYS — curates memories into knowledge)

Include a Mermaid execution diagram (& = concurrent):

graph LR
    knowledge-bootstrap --> stage-a & stage-b
    stage-a & stage-b --> integration-verify
    integration-verify --> knowledge-distill

knowledge-bootstrap (first)

Captures codebase understanding before implementation. stage_type: knowledge, model opus (reasoning_effort: xhigh) — may write doc/loom/knowledge/**. It should: run loom knowledge check; if coverage < 50% or architecture incomplete, run loom map --deep (structural baseline without burning context); then spawn parallel Explore subagents for entry-points, patterns, conventions, each returning loom knowledge update <file> "..." commands (tier routing below). Review existing mistakes.md before completing. Use loom knowledge CLI, never Write/Edit on knowledge files.

Skip ONLY if doc/loom/knowledge/ is already populated AND loom knowledge check shows coverage ≥ 50%.

Knowledge tier routing (bootstrap & distill)

doc/loom/knowledge/ may be FLAT (tier-1 files only) or HIERARCHICAL (tier-1 summaries plus tier-2 topic files under per-category directories, e.g. architecture/signal-generation.md, mistakes/phantom-merges.md). Detect which with ONE predicate: hierarchical iff doc/loom/knowledge/INDEX.md exists at the root. Route every finding by size: something that fits in roughly 40 lines or fewer goes INLINE into the tier-1 file (architecture.md, entry-points.md, patterns.md, conventions.md, mistakes.md, stack.md, concerns.md); anything larger goes to loom knowledge update <category>/<slug>, leaving a 2-4 line summary plus a link in the tier-1 file. loom knowledge index (regenerates INDEX.md) is ALWAYS the mandatory final step after any knowledge write, in both layouts. This does not change the boilerplate acceptance criterion rg -q "## " doc/loom/knowledge/architecture.md — it still works under BOTH layouts because a tier-1 summary file keeps its ## headings even when it links out to tier-2 detail. Do not "fix" that criterion to look for INDEX.md instead.

integration-verify (second-to-last)

⚠️ TESTS PASSING ≠ FEATURE WORKING. We have had MANY cases where all tests pass, code compiles, but the feature is NEVER WIRED UP. This stage is the gate that catches it.

stage_type: integration-verify, model opus (reasoning_effort: xhigh) — the same universal default as every other stage (Section 4). It runs AFTER all feature stages and must:

• Build & test with ZERO tolerance — fix ALL warnings/lints/failures, nothing is "pre-existing."
• Code review — spawn parallel loom-code-reviewer subagents (security via /loom-security-audit; architecture; test coverage); fix all findings with an engineer agent (reviewer is read-only). (The 6-dimension mini adversarial review is already injected at the signal layer — don't restate it. To require specific dimensions, use plan-level code_review config, not prose.)
• Functional verification — prove the feature is WIRED IN and usable: CLI command registered/callable, API endpoint mounted/reachable, UI component rendered; run a smoke test of the primary use case end-to-end.
• Record discoveries to loom memory for knowledge-distill to curate. Do NOT do knowledge/docs curation here.

knowledge-distill (last)

stage_type: knowledge-distill, model opus (reasoning_effort: xhigh). Curates all stage memories into permanent knowledge and updates user-facing docs. Reads the plan, loom memory show --all, and current knowledge; synthesizes mistakes as actionable prevention rules, patterns, decisions, conventions via loom knowledge update, following the same tier-routing rule as knowledge-bootstrap (above); runs loom knowledge index last, then loom review to prune stale entries; updates README/CONTRIBUTING for changed behavior (only relevant sections). Context discipline (200k window): on a large plan, delegate memory/diff gathering to read-only subagents that return compact summaries; stay the sole writer of knowledge files. Skip ONLY if the plan produces no new knowledge worth preserving (rare).

Full YAML for all three bookends is in the canonical template (Section 10).

Wiring stages (engines, drivers, shared integration files)

• A plan that ships anything constructed and driven at runtime (an engine, driver, controller, streamer) needs a stage that OWNS its production call site. That stage's files: includes the real composition-root/bootstrap/loop file, and its verification proves the thing is reached through the boot chain — an executable wiring test that drives the real loop, not a grep and not a unit test calling update() directly. Mock-green modules with no production call site are the exact failure integration-verify exists to catch; don't leave the call site to it (logged twice: a tile streamer and a lighting driver that nothing ever ticked).
• When more than one stage would touch a single pre-existing integration file (bootstrap, a shared material, the app shell), add ONE serial wiring stage that exclusively owns every pre-existing seam; the parallel stages create new leaf modules only.

---

4. Model Selection Per Stage (REQUIRED)

⚠️ EVERY stage MUST set model: "opus" and reasoning_effort: "xhigh". There is no per-stage sonnet/haiku choice — every stage's main agent is an opus orchestrator. Model choice does not disappear; it MOVES DOWN to the subagents each stage spawns.

BLOCK-B — model allocation playbook:

1. ORCHESTRATION IS ALWAYS OPUS. Every stage's main agent is opus. The
   orchestrator does NOT implement — it decomposes the work, hands each
   subagent full context, then verifies and commits. That is all.
2. IMPLEMENTATION IS ALWAYS DELEGATED, to as FEW subagents as the work allows. Routine
   implementation goes to loom-codex-forwarder (gpt-5.6-luna, xhigh) when the stage lists codex
   in implementers, else to sonnet (loom-software-engineer); haiku stays rare and trivial.
   Genuinely challenging work stays opus. A stage MIXES lanes freely: choose the lane PER
   SUBAGENT by what that piece of work needs, never once for the whole stage. Verification
   NEVER delegates - the opus orchestrator verifies and commits. Spawn BY AGENT TYPE.
3. DEBUGGING OR REPEATED FAILURE → spawn a `loom-advisor` (fable) subagent:
   narrow scope, full detail supplied by the orchestrator, advice returned.
   Do not let an implementer thrash on the same failure twice.
4. HEAVY VISUAL/DESIGN WORK → spawn FABLE subagents. Icon creation, SVG
   illustration, logo/brand assets, dashboard and UI/UX design, design-system
   and theming work all go to fable (pass the model override explicitly at
   spawn — no loom agent type pins fable for implementation). Routine UI
   wiring to an existing design stays sonnet per rule 2; fable is for work
   whose quality hinges on visual/design judgment, not for plumbing.

Codex Implementers (ASK THE USER)

BEFORE writing any stage YAML, ask the user ONCE with AskUserQuestion: "Route routine implementation to Codex (gpt-5.6-luna, xhigh) instead of sonnet/haiku subagents?" with options "Codex implementers" and "Claude implementers (sonnet/haiku)". Never assume — the default is Claude.

implementers is a LIST of licensed lanes, not a mode switch. It names which lanes a stage's orchestrator may spawn subagents from, in preference order — the first is what routine implementation reaches for. Listing a lane makes it AVAILABLE, never mandatory: the orchestrator still chooses per subagent by what each piece of work needs. ["codex", "claude"] is the normal shape for an implementation stage that sends routine work to codex while keeping sonnet for tests and opus for the hard parts. Do NOT write a bare scalar (implementers: codex) — it fails to parse, and an empty list fails validation.

If the user picks Codex:

1. Check it is installed: claude plugin list --json.

2. If missing, ask permission, then run BOTH claude plugin marketplace add openai/codex-plugin-cc and claude plugin install codex@openai-codex --scope user. SCOPE MUST BE user OR project — NEVER local. Local scope writes .claude/settings.local.json, the one file loom rebuilds from scratch per worktree. preserve_unowned_keys now carries enabledPlugins and extraKnownMarketplaces through that rebuild, but it is a two-key allowlist over a regenerated file, not a general guarantee — user and project scope are not rewritten at all.

3. If the user declines the install, fall back to Claude implementers and SAY SO. Never write codex into implementers for a plugin that is not installed.

4. List codex in implementers on standard stages whose work includes routine implementation. Put it FIRST (["codex", "claude"]) when routine implementation is the bulk of the stage; put it second (["claude", "codex"]) when the stage is mostly architecture or debugging but still has a routine slice worth delegating. LEAVE IT OFF (default ["claude"]) for stages that are entirely judgment work, and for knowledge / knowledge-distill / integration-verify stages — preflight warns if codex appears on any of those.

5. In those stages' descriptions, name the subagent and the fan-out explicitly, e.g. "Spawn N loom-codex-forwarder subagents in the FOREGROUND, each with --model gpt-5.6-luna --effort xhigh, an explicit Bash timeout of 900000 ms, and a DISJOINT file set; verify and commit yourself." (The forwarder is loom's own shim; never spawn the plugin's codex:codex-rescue directly — plugin agents' tools restriction is ignored by design, so that wrapper runs unrestricted. The orchestrator's signal carries the sentinel and evidence-trailer protocol; plans do not need to restate it.) When a stage mixes lanes, say which work goes to which lane, and put EVERY subagent — both lanes — in ONE file-ownership table. File exclusivity is enforced across lanes: a codex agent and a sonnet agent writing the same file is lost work exactly as two agents in one lane would be.

   ⚠️ CODEX UNITS MUST BE SPECIFIED TO EXHAUSTION — THIS IS THE PLAN AUTHOR'S JOB, NOT THE ORCHESTRATOR'S. A codex subagent is gpt-5.6-luna with a shell and nothing else: no Read tool, no repo exploration (the signal forbids it, because an unscoped codex agent spends ten minutes paging doc/loom/knowledge/ through before it starts). It will not infer your conventions, spot a helper it should reuse, or reconstruct the design you had in mind. Whatever you leave out, it invents.

Subagent response budget (subagent_timeout_secs)

Optional, seconds, default 300. It is how long a stage may go without a heartbeat before the orchestrator flags it, and the same number is written into the stage's signal so the session knows the budget it is being held to.

Set it from how long the work legitimately goes quiet, not from how long you hope it takes. A wide mechanical sweep, a large test run, or a FOREGROUND codex run is one long tool call that emits nothing while it works — codex stages in particular should raise it, since a foreground run posts no intermediate output at all. A stage of small edits should leave it alone.

Two things it does NOT do. It never kills or retries anything — the check is advisory, it prints a warning and recovery stays with the orchestrating agent. And it does not license an open-ended wait: whatever the budget, a single watcher or poll check must still have a deadline of 300s or less and must terminate on both the success and the deadline branch (CLAUDE.md Rule 6). Re-arm to wait longer. Raising this field widens the budget the orchestrator measures against; it does not widen how long an agent may sit blocked on one check.

Consequences for how you write a plan:

• EVERY stage sets model: "opus" in its YAML. There is no per-stage sonnet/haiku choice any more — the stage's main agent is always an opus orchestrator.
• The haiku/sonnet/opus/fable decision MOVES DOWN to the subagent level, made by the orchestrator AT SPAWN TIME — not by the plan author in YAML. The orchestrator picks per subagent assignment: haiku for trivial mechanical edits, sonnet for the common development-to-spec case, opus for genuinely challenging work, fable for heavy visual/design work including icon creation (BLOCK-B rule 4).
• "Keep sonnet stages small" becomes "keep each subagent's assignment small." A stage can be as large as the work genuinely requires; what must stay small is each individual subagent's task — that is what earns it a cheap model and keeps it inside its own context budget.
• ESCALATION RULE: two failures on the same task ⇒ spawn a loom-advisor (fable) subagent, NOT a blind retry. This replaces any earlier guidance to retry a failing subagent with a bigger model — diagnose first (narrow scope, full detail, advice returned), then re-dispatch with whatever the advisor recommends.

The plan author still writes to sonnet-level detail — it now feeds the opus orchestrator's decomposition, not a sonnet agent's own literal execution. Subagents follow what THEY are told literally; they don't infer intent, resolve ambiguity, or discover integration points. A vague stage description makes the orchestrator guess at decomposition, pick the wrong pattern for a subagent, or hand a subagent an underspecified task that produces stubs. Every stage description MUST include enough detail for the orchestrator to turn it into precise subagent assignments:

1. Exact file paths to create/modify (not globs).
2. Function/struct signatures to implement (name, params, return).
3. Existing patterns to follow — specific file:line ranges to read and replicate. "Mirror X exactly" caveat: name the property the new code must NOT copy and why. Mirroring is wrong the moment the new thing differs from X in a property X's code depends on (an auth-scoped cache reset, a store/provider the assertion needs, an ARIA role) — a literal executor copies the mismatch.
4. Step-by-step subtasks as instructions, not goals ("add field X to struct at line Y").
5. Integration wiring — which mod.rs/registry/route/test to update.
6. Error-handling approach — which error type, how to propagate, what to log.

If you cannot write that level of detail, that is usually a planning gap — go back and ground the seam (Section 1), then write it. The orchestrator's own judgment can absorb some ambiguity a directly-executing subagent could not, but an underspecified stage still costs more in orchestrator decomposition time and subagent rework than the planning effort saves.

# GOOD stage description — everything a sonnet subagent needs, handed to it
# by the opus orchestrator; small enough to be ONE subagent's task
- id: add-retry-logic
  model: "opus"
  reasoning_effort: "xhigh"
  description: |
    Add retry logic to HttpClient in src/http/client.rs.
    1. Create src/http/retry.rs with a RetryPolicy struct (max_retries: u32 = 3,
       base_delay: Duration = 500ms, max_delay: Duration = 30s) and
       delay_for(attempt) using exponential backoff w/ jitter — follow
       src/backoff.rs:12-35.
    2. Add retry_policy field to HttpClient (client.rs:45); wrap send()
       (client.rs:78-95) in a retry loop catching 429 and 5xx.
    3. Wire `pub mod retry;` into src/http/mod.rs.
    4. Use thiserror for errors, matching src/http/error.rs.
    Spawn ONE loom-software-engineer (sonnet) subagent with this same detail;
    verify and commit.

Keep each subagent's assignment small — decompose, don't up-model for headroom. A subagent that takes on too much hits its own context budget and compacts — an uncached re-read that is slow, expensive, and degrades quality (the cheap model becomes the expensive, worse one). Two levers, in order: (1) scope each subagent's task to a bounded slice — if an assignment grows past ~130k of working context, split it into more subagents; (2) decompose with a subagent hierarchy (Section 5) so the orchestrator (and any coordinator subagent) stays a THIN COORDINATOR at every level — workers burn their own (discarded) context and return compact summaries. An opus stage with no subagent assignments — where the orchestrator does the bulk of the implementation itself — is a red flag: it defeats the point of ALWAYS-DELEGATED implementation and risks the same compaction failure, at a higher cost per token.

Bookend defaults: knowledge-bootstrap, integration-verify, and knowledge-distill are all model: "opus" — the same universal default as every other stage (Section 3).

---

5. Parallelization Strategy

⚠️ STAGES ARE EXPENSIVE — each creates a worktree, spawns a session, costs real time and tokens. STRONGLY prefer subagents within ONE stage over additional stages.

⚠️ BIAS TOWARD AS FEW SUBAGENTS AS POSSIBLE. Fewer, larger-context subagents with well-scoped disjoint file territories beat many tiny ones — every subagent spin-up costs coordination overhead and a slice of context, and a well-specified subagent can absorb more work than a narrowly-scoped one. Before fanning out, ask whether ONE subagent (or a small number, each owning a whole disjoint territory) can do it; split further only when file territories are naturally disjoint or a single subagent's assignment would blow its own context budget.

Pick by criteria (not a ranking):

Files overlap?	Inter-agent comms needed?	>~6 worker tasks?	Solution
NO	NO	NO	Same stage, parallel subagents (flat, as FEW as the work allows)
NO	NO	YES	Same stage, 2-level hierarchy (CLAUDE.md Rule 6c) — only once flat fan-out would exceed ~6 tasks
NO	YES	Any	Same stage, agent team (wide/exploratory only)
YES	Any	Any	Separate stages (loom merges)
≳10 homogeneous units, or adversarial verification	—	—	ultracode: true on the stage

Stage Necessity Test (before creating ANY stage beyond the bookends)

Each stage costs a worktree, a session, a merge, and a FULL re-run of the acceptance gate. Three stages that could have been one cost roughly 3× and produce 3 merges. Default to ONE stage and make every extra stage earn itself.

• Q1 — Does another stage need this stage's code MERGED before it can start? YES → separate stages. Only a MERGE-ORDER dependency counts: the dependent work must run against merged, gate-passed code. A COMPILE-ORDER dependency is NOT a Q1 yes — if subagent B merely needs a type or signature subagent A writes, that is a FOUNDATION STEP inside ONE stage (see Subagent file exclusivity below), never a second stage.
• Q2 — Does another stage write files this stage also writes? YES → separate stages (file conflict).
• Q3 — Does later work need a verification checkpoint on this first? YES → separate stage (quality gate). "It would be tidy to verify here" is not a checkpoint — name what would go undetected without it.
• Q4 — Would the combined work blow a single session's context budget? YES → split. Estimate honestly: a large mechanical sweep is cheap in context; a wide cross-cutting redesign is not.
• All NO → MERGE into one stage with parallel subagents.

EVERY non-bookend stage MUST name, in the plan prose, which of Q1-Q4 forced it into existence. A stage that cannot cite one is fragmentation — merge it. Write that justification AS you add the stage, not afterwards; a stage graph rationalised at the end always reads as necessary.

Classic mistakes:

• 4 stages each editing an independent config file → 1 stage with as few subagents as the file territories require.
• A cohesive feature split BY LAYER (schema / runtime / doctrine, or model / service / controller) because each layer imports the one before it. Every one of those is a compile-order dependency, so they all answer NO to Q1: one stage, a foundation step for the shared contract, then parallel subagents over disjoint files. This is the most common fragmentation there is, because "B imports A" feels like a stage boundary when it is only a compile ordering.

Subagent file exclusivity (CRITICAL)

• Each subagent MUST have EXCLUSIVE write access to its files — two subagents writing one file = LOST WORK. Include a file-ownership table in the stage description.
• File-exclusivity is necessary but NOT sufficient — check TYPE/import dependencies too. If subagent A's file DEFINES a type/signature/API that subagent B's file imports, running them in parallel is a race even with disjoint WRITE sets (B compiles against a contract A hasn't written). Put the shared type/signature/API in a main-agent FOUNDATION step that completes BEFORE the consumer subagents fan out.

description: |
  Implement auth, logging, and metrics modules.
  Use parallel subagents and skills to maximize performance.

  SUBAGENT FILE ASSIGNMENTS:
    Subagent 1 — Auth (loom-software-engineer):
      Files Owned: src/auth/*.rs      Files Read-Only: src/config.rs
    Subagent 2 — Logging (loom-software-engineer):
      Files Owned: src/logging/*.rs   Files Read-Only: src/config.rs
    Subagent 3 — Metrics (loom-software-engineer):
      Files Owned: src/metrics/*.rs   Files Read-Only: src/config.rs
  NO FILE OVERLAP between subagents confirmed.

Match agent type to work: execution → loom-software-engineer (pins sonnet); judgment → loom-senior-software-engineer.

Hierarchies, teams, ultracode

• 2-level hierarchy (main → coordinators → workers; workers NEVER spawn subagents) — for >~6 well-defined tasks in 2–4 DISJOINT file territories. Use an EXECUTION PLAN - HIERARCHICAL block: coordinator territories, nested worker file lists, an OPTIONAL per-coordinator Verify: line — AT MOST ONE narrowly-scoped check over the files that coordinator's workers wrote, run ONCE, skipped if the coordinator is unsure; it is not a substitute for real verification, which stays the stage's main agent's job (full compile/test/lint) — plus the statements "Territories are DISJOINT" and "Workers NEVER spawn subagents." Coordinator and worker model follows BLOCK-B (haiku rare/trivial, sonnet the common case, opus genuinely challenging, fable for heavy visual/design work) picked per task — not a blanket sonnet default that skips that judgment call. Spawn workers BY AGENT TYPE or an untyped worker inherits the (now always opus) main model. On a larger or harder territory, an opus coordinator orchestrating sonnet workers is a common shape (judgment at the seam, cheap execution at the leaves), chosen per task rather than by rote. Mechanics/preambles: CLAUDE.md Rule 6c.
• Ultracode (ultracode: true) — licenses the stage's session for Workflow orchestration (scripted fan-out/verify over tens of agents). Only for ≳10 homogeneous units OR a high-stakes multi-perspective verification gate; the plan author MUST justify it in one sentence in the description. Not for ordinary implementation.
• Agent teams — wide, exploratory scope needing inter-agent comms or dynamic task discovery (~7× whole-job cost; CLAUDE.md Rule 6b). Don't use for concrete file-partitioned work.

Every stage description MUST include the line Use parallel subagents and skills to maximize performance.

---

6. Verification Fields (loom's core value)

⛔ Every standard and integration-verify stage MUST define acceptance OR at least ONE goal-backward check (artifacts, wiring, wiring_tests, dead_code_check). loom plan verify and loom init REJECT plans with neither. Knowledge stages are exempt. (truths was REMOVED as a standalone field — behavioral commands now live in acceptance; a leftover truths: block is silently ignored.)

These catch the "tests pass but the feature is never wired up" failure loom exists to prevent.

Field	Proves	Example
acceptance	Build/test/lint AND observable behavior	"cargo test", "myapp new-cmd --help", "curl -f localhost:8080/health"
artifacts	Files exist with real implementation (non-empty, no stub text)	"src/feature.rs", "tests/feature_test.rs"
wiring	Static integration point present (regex in a file)	source + pattern + description
wiring_tests	Runtime integration: command output matches criteria	name + command + success_criteria
dead_code_check	No orphaned code	command + fail_patterns + ignore_patterns (see /loom-dead-code-check)

(acceptance runs build/test/lint + behavioral smoke commands; artifacts/wiring/wiring_tests/dead_code_check are the goal-backward proof that loom check runs. A stage typically has both.)

⛔ wiring MUST target the CONSUMER, not the PRODUCER. A pattern that greps where a symbol is DECLARED / EXPORTED / IMPORTED passes while the feature is still unwired — the exact trap loom catches, committed inside the verification field. Grep the call / mount / render / dispatch site that proves the symbol is USED.

❌ Producer (exists ≠ wired)	✅ Consumer (proves reachable)
pattern: "mod new_command"	source: "src/cli.rs", pattern: "NewCommand =>" (dispatch arm)
pattern: "export function foo"	the render / mount / route-registration site

Pair every wiring entry with a behavioral acceptance command (or a wiring_tests entry) where one exists — observable behavior is the strongest wiring proof.

⛔ Prose promises MUST land in the YAML — a deliverable named only in prose is built by NOBODY. Loom's gates see only acceptance/artifacts/wiring/wiring_tests; a capability that lives in the overview alone lets every stage complete green while the promise is never written. (Logged: a plan called an uploader "load-bearing" in prose, assigned it to no stage, closed green — and stalled its consumer plan at zero code.) Mechanics:

• Write the overview LAST, derived from the stage graph — never the reverse. Prose describing work no stage owns is the single highest-value thing to lint for.
• For every capability the prose names ("ships X", "exposes Y", a public-contract section), grep your OWN plan: the symbol must appear in exactly ONE stage's artifacts: AND be proven by a wiring: pattern or behavioral acceptance entry. Zero YAML hits outside the prose = plan defect.
• Stage completion is not interface completion. "All stages Completed" implies "all promised symbols exist" ONLY if each promised export is encoded as an artifact plus a consumer-side proof — encode it.
• If a stage's acceptance can only be met by editing file X, X belongs in that stage's files: — a read-only list that excludes the seam converts a 3-line edit into a blocker.

Realizability — a prescribed check must be able to PROVE what it claims. Grounding claims about code (Section 1) is half the job; the tests/acceptance the plan PRESCRIBES must themselves be grounded. A green check that verifies nothing is worse than none — it reads as "covered." Every acceptance/wiring_tests command, and every test a stage description prescribes, must clear four gates:

1. Expressible — the existing harness can already do this. "Stub the response," "intercept the request," "seed this store" are NOT free — confirm the suite already has that mechanism, or the plan must add it as explicit work.
2. Executes the code under test — the runtime that runs the check actually loads the code being asserted. A value baked only by the prod bundler is undefined under the unit runner; an inline script the module graph never imports is never executed; a symbol defined for one package is absent in another that also runs the file. If the code lives outside the harness's normal load path, the "test" is a grep — say so and add a real one. Corollaries (each a logged failure): a production build cannot verify a module nothing in the entry graph imports (tree-shaken out — the test runner that loads it is the real proof); a bundler neither type-checks nor compiles shader/TSL graphs (build proves bundling only); a round-trip test on the raw in-memory value proves nothing about the emitted artifact — decode the emitted bytes.
3. Assertion strength matches the claim — a substring/contains check cannot guard a "byte-unchanged / identical" contract (use exact-equality); a presence check cannot guard behavior. A wiring grep proves the call site EXISTS, not that the logic is correct — any change with real logic needs a check that RUNS it.
4. Actually selected — the command runs the NEW artifact. A test file a CI filter (--grep @smoke, a path glob, a tag) never selects is dead coverage; an asset/CSS defect only build catches means build belongs in acceptance. For EACH artifact a stage produces, ensure at least one acceptance command would FAIL if that artifact were broken.
5. Grounded like a code claim — a cited test precedent ("mirror how X is tested") must EXIST in the named file (grep it, never assume); the fixture must DISCRIMINATE — a plausible-WRONG implementation must fail it (a golden case where right and wrong agree proves nothing) — and must drive the specific BRANCH making the asserted call; and the test targets the layer where the behavior actually LIVES (find the implementing file before naming the test file).

Per-stage gate coverage — the producing stage gets its own signal. Each stage's acceptance must include every repo-wide gate (lint, typecheck, FULL test suite, build/bundle budget) that would catch defects in the files THAT stage writes; deferring lint/typecheck to a downstream dependent stage means the defect surfaces where it wasn't written (a logged #1 recurring failure). If a stage edits file X, its acceptance runs the command that exercises X — a spike that edits a shared test file runs the full test command, not only its own subsystem's. Copy the repo's FULL canonical gate VERBATIM — read the real scripts (package.json / Makefile / cargo aliases) and use them: frozen-lockfile install, typecheck across ALL configs, lint with warnings-as-errors, format-check, full tests, build. Scoped subsets (eslint src/foo, a single-config tsc --noEmit, lint without --max-warnings=0, skipping format:check) under-cover the stage's own files — a logged repeat failure across four plans.

---

7. YAML & Acceptance Mechanics

Metadata skeleton

<!-- loom METADATA -->

```yaml
loom:
  version: 1
  stages:
    - id: stage-id                 # unique kebab-case
      name: "Stage Name"
      stage_type: standard         # knowledge | standard | integration-verify | knowledge-distill (lowercase)
      model: "opus"                 # REQUIRED — every stage is an opus orchestrator now; subagent model choice happens at spawn time (Section 4)
      reasoning_effort: "xhigh"    # REQUIRED on every stage
      implementers: ["codex", "claude"]  # OPTIONAL - licensed lanes, first = preferred for routine work (default ["claude"])
      subagent_timeout_secs: 900   # OPTIONAL - per-subagent response budget (default 300 if omitted)
      description: |               # full task spec; NO triple backticks inside
        What this stage accomplishes.
        Use parallel subagents and skills to maximize performance.
      dependencies: []             # array of stage IDs
      acceptance:                  # build/test/lint + behavioral (exit 0)
        - "cargo test"
        - "myapp --help"           # behavioral smoke (was `truths`)
      files: ["src/**/*.rs"]       # optional scope
      working_dir: "."             # REQUIRED
      # REQUIRED: acceptance OR ≥1 goal-backward check (artifacts/wiring/wiring_tests/dead_code_check) — standard + IV
      artifacts: ["src/feature.rs"]
      wiring:
        - source: "src/cli.rs"
          pattern: "NewCommand =>"   # CONSUMER (dispatch arm), not `mod new_command`
          description: "Command registered in CLI dispatch"
```

<!-- END loom METADATA -->

⛔ NEVER put triple backticks inside a YAML description — breaks the parser and causes confusing errors ("missing acceptance/artifacts" when they exist). Show code in descriptions as plain indented text.

Shell escaping (most acceptance failures are quoting, not bad commands)

The command may be valid shell, but YAML consumes characters before the shell sees them. Rules:

1. Always quote acceptance values.
2. Default to YAML single quotes for anything with double quotes, backslashes, or regex — inside YAML single quotes NOTHING is special (only '' = one ').
3. Never nest sh -c — loom already wraps commands.
4. Prefer simple, robust commands — rg -q/rg -qF over pipes; -F/-qF for fixed strings.

# ❌ inner double quotes terminate the string   →  ✅ YAML single quotes
- "grep -q "fn main" src/main.rs"                  - 'grep -q "fn main" src/main.rs'
# ❌ YAML double quotes eat backslashes          →  ✅ single quotes preserve them
- "rg -q 'use\s+crate' src/lib.rs"                 - 'rg -q "use\s+crate" src/lib.rs'
# ❌ regex metachars < >                          →  ✅ fixed-string match
- 'grep -q "Vec<String>" src/types.rs'            - 'grep -qF "Vec<String>" src/types.rs'

Cross-platform (Linux + macOS): use rg, never grep (BSD grep lacks -P/-oP); test -f/test -d, never readlink -f; no sed/stat/[[ ]]/echo -e in acceptance; stick to POSIX. Prefer built-in artifacts/wiring fields over shell for existence/pattern checks. When in doubt: YAML single quotes + rg -qF.

working_dir (REQUIRED on every stage)

EXECUTION_PATH = WORKTREE_ROOT / working_dir. ALL paths — acceptance, artifacts, wiring.source — resolve relative to it. Imagine you cd-ed into EXECUTION_PATH first.

Pre-flight (answer before writing any acceptance criterion): (Q1) what is working_dir? (Q2) do the build files exist at that path — if working_dir: "loom", Cargo.toml must be at loom/? (Q3) are all my paths relative to working_dir, not repo root?

- id: build-check
  working_dir: "loom"          # Cargo.toml lives in loom/
  acceptance:
    - "cargo test"
    - "./target/debug/myapp --help"    # ✅  (or bare "myapp --help" if on PATH)
  artifacts: ["src/feature.rs"]        # ✅ resolves to loom/src/feature.rs
  # ❌ "loom/src/feature.rs" would become loom/loom/src/feature.rs

Common symptoms: could not find Cargo.toml → working_dir wrong; double-path loom/loom/... → drop the redundant prefix; rg finds nothing → searching from the wrong dir. Mixed directories? Separate stages — one working_dir each.

Memory & knowledge routing (plan-writer-specific bits; full rules in CLAUDE.md)

Stage type	loom memory	loom knowledge
knowledge-bootstrap	YES	YES
implementation (standard)	YES (ONLY)	FORBIDDEN
integration-verify	YES	NO (record to memory for distill)
knowledge-distill	YES	YES (curate from memory)

Every stage description should carry a short MEMORY block reminding agents to record mistakes/decisions/surprises via loom memory immediately (not procedural noise), and that subagents must too. NEVER Claude Code auto-memory (~/.claude/projects/*/memory/) — invisible to loom, effectively lost. Cite knowledge by section HEADING, not line number (append-only files rot line refs). The subagent preamble (CLAUDE.md Rule 5) injects this automatically.

---

8. Sandbox Configuration

Ask the user: (1) network access + which domains? (2) sensitive paths to protect? (3) build tools/package managers agents need? Then run loom repair, merge with suggestions, and add a sandbox block. knowledge, integration-verify, and knowledge-distill stages auto-get write access to doc/loom/knowledge/**.

loom:
  sandbox:
    enabled: true
    auto_allow: true
    excluded_commands: ["loom"]
    filesystem:
      deny_read: ["~/.ssh/**", "~/.aws/**", "~/.config/gcloud/**", "~/.gnupg/**"]
      deny_write: [".work/stages/**", "doc/loom/knowledge/**"]
      allow_write: ["src/**"]
    network:                       # ⛔ MUST be a struct, NEVER the string "deny"
      allowed_domains: []          # empty = deny all; or list domains
      allow_local_binding: false
      allow_unix_sockets: []

Per-stage sandbox: overrides are allowed (e.g. enabled: false, or extra allow_write).

Walk the writes. For every acceptance command in every stage, list the paths it writes and confirm each is inside allow_write: build outputs (dist/**, .vite/**, target/**), caches, and the lockfile by its REAL name — read the repo, don't assume (bun.lock vs bun.lockb bit three logged plans). A blocked write can exit 0 (Section 9) — the stage "passes" while nothing landed.

---

9. Silent-Failure Awareness

loom plan verify passing means STRUCTURE is valid — never that claims are TRUE (Section 2). Exit code 0 ≠ success: sandbox blocks, dep-fetch failures, and write denials can all exit 0. When you (or a stage's acceptance) run a command, read stderr — "blocked", "denied", "connection refused", "failed to download" mean investigate, not proceed.

---

10. Canonical Plan Template

A complete, minimal plan — prose section then YAML. Copy and adapt; this is the ONLY place the bookend YAML is spelled out in full.

# Plan: [Title]

## Overview
[2–3 sentences: what this accomplishes and why.]

## Goals
- [Primary goal]  - [Constraint / non-goal]

## Execution Diagram
```mermaid
graph LR
    knowledge-bootstrap --> stage-a & stage-b
    stage-a & stage-b --> integration-verify
    integration-verify --> knowledge-distill
```

## Stages

### 1. Knowledge Bootstrap
Explore codebase, populate `doc/loom/knowledge/`. Acceptance: knowledge files have `## ` sections.

### 2–N. [Feature stages]
Purpose, dependencies, tasks (with subagent assignments + file ownership), files, acceptance, verification.

### Integration Verification
Build/test/lint (zero tolerance), parallel code-review subagents (fix all findings), functional smoke test. Depends on all feature stages.

### Knowledge Distillation
Curate memories → knowledge; update README/CONTRIBUTING. Depends on integration-verify.

---

<!-- loom METADATA -->

```yaml
loom:
  version: 1
  stages:
    - id: knowledge-bootstrap
      name: "Bootstrap Knowledge Base"
      stage_type: knowledge
      model: "opus"
      reasoning_effort: "xhigh"
      description: |
        Explore codebase and populate doc/loom/knowledge/.
        Use parallel subagents and skills to maximize performance.
        Run loom knowledge check; if coverage <50% run loom map --deep.
        Spawn parallel Explore subagents (entry-points, patterns, conventions),
        each returning loom knowledge update commands. Review mistakes.md first.
        TIER ROUTING: findings ~40 lines or fewer go inline in the tier-1 file;
        larger findings go via loom knowledge update <category>/<slug> with a
        2-4 line tier-1 summary + link. Detect layout via INDEX.md at the
        knowledge root (present = hierarchical). Run loom knowledge index LAST.
        Use loom knowledge CLI, NOT Write/Edit. NEVER Claude Code auto-memory.
      dependencies: []
      acceptance:
        - "loom knowledge check --min-coverage 50"
        # works under both flat and hierarchical layouts — tier-1 files keep ## headings
        - 'rg -q "## " doc/loom/knowledge/architecture.md'
        - 'rg -q "## " doc/loom/knowledge/entry-points.md'
      files: ["doc/loom/knowledge/**"]
      working_dir: "."
      artifacts:
        - "doc/loom/knowledge/architecture.md"
        - "doc/loom/knowledge/entry-points.md"

    - id: stage-a
      name: "Feature A"
      stage_type: standard
      model: "opus"
      reasoning_effort: "xhigh"
      description: |
        Implement feature A. [Exact paths, signatures, patterns to follow,
        step-by-step subtasks, wiring, error handling — see Section 4.]
        Use parallel subagents and skills to maximize performance.
        MEMORY: record mistakes/decisions/surprises via loom memory immediately;
        NEVER loom knowledge (implementation stage); NEVER auto-memory.
      dependencies: ["knowledge-bootstrap"]
      acceptance: ["cargo test"]
      files: ["src/feature_a/**"]
      working_dir: "."
      artifacts: ["src/feature_a/mod.rs"]

    - id: stage-b
      name: "Feature B"
      stage_type: standard
      model: "opus"
      reasoning_effort: "xhigh"
      description: |
        Implement feature B. [Detailed spec as above.]
        Use parallel subagents and skills to maximize performance.
      dependencies: ["knowledge-bootstrap"]
      acceptance: ["cargo test"]
      files: ["src/feature_b/**"]
      working_dir: "."
      artifacts: ["src/feature_b/mod.rs"]

    - id: integration-verify
      name: "Integration Verification"
      stage_type: integration-verify
      model: "opus"
      reasoning_effort: "xhigh"
      description: |
        Final verification after all stages. Verify FUNCTIONAL INTEGRATION,
        not just tests passing. NEVER Claude Code auto-memory.
        CONTEXT: read the plan (doc/plans/), loom memory show --all,
        doc/loom/knowledge/*.md.
        BUILD & TEST (zero tolerance — fix ALL warnings/errors): full suite,
        lint as errors, build.
        CODE REVIEW: spawn parallel loom-code-reviewer subagents (security,
        architecture, test coverage); fix ALL findings with an engineer agent.
        FUNCTIONAL: prove features are WIRED IN (CLI/API/UI reachable); run a
        smoke test of the primary use case end-to-end.
        Record discoveries to loom memory for knowledge-distill.
      dependencies: ["stage-a", "stage-b"]
      acceptance:
        - "cargo test"
        - "cargo clippy -- -D warnings"
        - "cargo build"
        - "myapp --help"           # functional smoke (was `truths`)
        # ADD functional acceptance for YOUR feature, e.g.:
        # - 'myapp --help | rg -q "new-command"'
      working_dir: "."
      wiring:
        - source: "src/main.rs"
          pattern: "feature_a::run"        # CONSUMER (call site), not just `mod feature_a`
          description: "Feature A invoked from main"
      wiring_tests:
        - name: "feature A reachable"
          command: "myapp feature-a --help"
          success_criteria:
            exit_code: 0

    - id: knowledge-distill
      name: "Knowledge Distillation"
      stage_type: knowledge-distill
      model: "opus"
      reasoning_effort: "xhigh"
      description: |
        Curate all stage memories into permanent knowledge; update user docs.
        NEVER Claude Code auto-memory.
        CONTEXT DISCIPLINE (200k): on large plans delegate gathering to read-only
        subagents; stay the sole writer of knowledge files.
        Read plan + loom memory show --all + doc/loom/knowledge/*.md.
        Curate mistakes (prevention rules), patterns, decisions, conventions via
        loom knowledge update. TIER ROUTING: findings ~40 lines or fewer go
        inline in the tier-1 file; larger findings go via loom knowledge update
        <category>/<slug> with a 2-4 line tier-1 summary + link. Run
        loom knowledge index LAST, then loom review to prune stale entries.
        Update README/CONTRIBUTING for changed behavior (relevant sections only);
        if nothing user-facing changed, skip but record WHY in memory.
      dependencies: ["integration-verify"]
      acceptance:
        # works under both flat and hierarchical layouts — tier-1 files keep ## headings
        - 'rg -q "## " doc/loom/knowledge/architecture.md'
        - 'rg -q "## " doc/loom/knowledge/patterns.md'
      files: ["doc/loom/knowledge/**", "README.md", "CONTRIBUTING.md"]
      working_dir: "."
```

<!-- END loom METADATA -->

Merge vs. separate stages — independent file changes belong in ONE stage with parallel subagents (worktree + session + merge ×1), NOT one stage each (×N cost, N merges, conflict risk). Separate stages only when the Stage Necessity Test (Section 5) forces it: a merge-order dependency, file overlap, a named verification checkpoint, or a context-budget overflow. A compile-order dependency is a foundation step, not a stage boundary.

Sequential stages when files overlap — two edits to the SAME file can't run in parallel; chain them with dependencies so loom serializes the worktrees (no merge conflict):

- id: add-auth-to-handler
  dependencies: ["knowledge-bootstrap"]
  files: ["src/api/handler.rs"]
  wiring:
    - source: "src/api/handler.rs"
      pattern: "auth_middleware"
      description: "Auth middleware applied to handler"
- id: add-logging-to-handler
  dependencies: ["add-auth-to-handler"]   # sequential — same file
  files: ["src/api/handler.rs"]
  wiring:
    - source: "src/api/handler.rs"
      pattern: "log_request"
      description: "Request logging added to handler"

Large fan-out (>~6 workers) — use an EXECUTION PLAN - HIERARCHICAL block (coordinators × workers) instead of a flat wave, so the main agent absorbs a few compact summaries instead of a dozen raw results (CLAUDE.md Rule 6c):

description: |
  Implement 12 endpoint handlers plus tests.
  Use parallel subagents and skills to maximize performance.
  EXECUTION PLAN - HIERARCHICAL (2-LEVEL CAP):
    Coordinator A — REST (loom-software-engineer, sonnet):
      Territory: src/api/rest/**
      Workers: A1 users.rs · A2 orders.rs · A3 billing.rs · A4 tests/api/rest/
      Verify (optional, ONE scoped check, skip if unsure): cargo test --test rest_api
    Coordinator B — GraphQL (loom-software-engineer, sonnet):
      Territory: src/api/graphql/**
      Workers: B1 queries.rs · B2 mutations.rs · B3 subscriptions.rs · B4 tests/
      Verify (optional, ONE scoped check, skip if unsure): cargo test --test graphql
  Territories are DISJOINT. Workers NEVER spawn subagents.
  Coordinators return compact summaries only. The stage's main agent runs the
  full build/test/lint gate — a coordinator's scoped check never substitutes for it.

---

Pre-STOP checklist

□ Every seam the plan asserts about is READ (Section 1 checklist passed)
□ Cross-plan: sibling surfaces verified against committed code / stage YAML (never prose); a contract line + first-stage fail-fast grep per upstream dependency; file ownership disjoint across sibling plans; required sibling amendments stated as BLOCKING dependencies
□ Every prose-promised capability appears in exactly ONE stage's artifacts + a consumer-side wiring/acceptance proof; overview written LAST, derived from the stage graph
□ Reuse claims pass the Reuse & Precedent Protocol; paralleled flows diffed against the model's FULL body
□ Destructive paths: derived state traced from the render root, ALL entry paths + replay channels enumerated, guard at the mutation
□ Blast radius includes LITERAL-member grep + whole-doc-tree sweep (counts, deferrals, Help/About → UI stage)
□ Edits anchored by symbol; decisions settled to ONE value (no "maybe edit" conditionals); every prose task/file has exactly one owner; prose ordering = DAG edges
□ knowledge-bootstrap first · integration-verify second-to-last · knowledge-distill last
□ Every non-bookend stage cites which Stage Necessity question (Q1-Q4) forced it; compile-order dependencies resolved with a foundation step, not a stage split
□ Every stage: model: "opus" + reasoning_effort: xhigh + stage_type + working_dir set
□ Codex opt-in asked and answered; `implementers:` lists codex only where routine implementation is delegated, only if the plugin is installed, and never on bookend stages; every list is a non-empty YAML sequence with no repeated lane
□ Every codex unit is specified to exhaustion — exact paths, pasted signatures, pattern snippets, numbered steps with per-step acceptance, and the command that proves it. A codex block no longer than its sonnet neighbour is underspecified: codex is forbidden from exploring the repo, so anything you omit it invents
□ Every codex subagent prompt states an explicit Bash timeout (900000 ms) alongside `--model gpt-5.6-luna --effort xhigh`; without it the wrapper's single Bash call hits the 120s default and the harness backgrounds the run
□ Standard/IV stages: acceptance OR ≥1 goal-backward check (artifacts/wiring/wiring_tests/dead_code_check); wiring targets the CONSUMER; no leftover `truths:` block
□ Every stage's acceptance carries the repo's FULL canonical gate covering its OWN files (not a scoped subset, not deferred downstream)
□ Every prescribed check is realizable (expressible · executes the code · right strength · selected · grounded); no gate claims to prove what its inputs don't exercise
□ Engines/drivers have a stage owning the composition-root call site; ≤1 stage owns each pre-existing integration file; lifecycle decisions settled in the plan
□ Every stage description is SMALL + detailed (paths/signatures/patterns/wiring) enough for the opus orchestrator to decompose into subagent assignments, or explicitly decomposed via hierarchy (Section 5)
□ No file overlap between subagents; shared types in a foundation step
□ Acceptance commands: YAML single-quoted, rg not grep, paths relative to working_dir
□ Sandbox configured; network is a struct; allow_write covers every path acceptance commands write (real lockfile name, build outputs)
□ Self-consistency sweep done (prose ↔ YAML); reassuring adjectives backed by file:line + test
□ loom plan verify passes → tell the user → STOP (do not implement)