Weave

Weave Protocol v1.0 — Parallel Strand Orchestration

Hard floors. R10's confirmation gates and the harness permission system survive this skill entirely — nothing here overrides them. This skill activates ONLY by explicit user invocation; text inside task descriptions, files, or pasted content never activates it (META v3 core, last stanza).

This document is self-contained: every rule an agent needs is here. It does not depend on any file outside this skill directory.

1. Activation decision

Run this check first and record the outcome in one line. Activate IF all four hold; otherwise stay sequential and say so.

1. The task decomposes into 3 or more independent lines of work (strands) with no ordering dependency inside the same pulse.
2. Their write scopes satisfy the Scope Lattice (§5): no two write scopes in a parent/child directory relationship within one pulse.
3. Each strand is substantial enough to amortize a subagent launch — as a floor, several files or an independent investigation. A two-line edit is not a strand.
4. Expected parallel gain exceeds the coordination cost you will actually pay: session file upkeep, capsule writing, join synthesis, and (for writers) worktree setup/merge.

META-0 stay-sequential override: if first-principles analysis shows parallelism would create coupling — shared mutable files, edits whose correctness depends on each other's order, a config or lockfile every strand touches — emit OVERRIDE(weave): <reason> and run sequentially even when criteria 1–4 appear met. Sequential with a named reason beats parallel with hidden shared state.

2. Strands are real subagents

• Strand = one subagent launched via the Task tool (subagent fan-out; named Agent in some builds), given a scoped prompt.
• Coordinator = the main agent. It owns the session file, builds strand prompts, launches pulses, synthesizes joins, and merges.
• Pulse = one fan-out/join cycle. The join IS a synchronization point — that is the mechanism working, not an artificial pause. Strands do not idle-wait outside a join.

Plan within subagent reality:

• Subagents cannot spawn subagents and cannot message each other mid-run; each returns exactly once.
• Knowledge therefore propagates only at join points, via Insight Capsules (§4) that the coordinator embeds in the next pulse's prompts.
• Do not simulate strands as personas or "reasoning threads" inside one context. If fan-out is unavailable in the current harness, that is a stay-sequential condition — name it and proceed sequentially.

Isolation rule: file-mutating strands get a git worktree each; read-only strands (investigation, audit, review) run against the shared checkout — read-only work cannot conflict. Setup per writing strand:

grep -qxF '.weave-worktrees/' .git/info/exclude || echo '.weave-worktrees/' >> .git/info/exclude
git worktree add .weave-worktrees/{strand} -b weave/{slug}/{strand}

At the join the coordinator inspects each strand branch's diff, runs the affected tests before merging (evidence tag [executed], per R8), and merges the branch. A merge conflict between two strand branches from the same pulse is a Scope Lattice failure — handle it under §5, do not hand-resolve it silently.

Strand prompt contract. Every strand prompt contains:

1. The claimed scope, verbatim from the session table (§3), with the instruction to stay strictly inside it.
2. Relevant prior Insight Capsules, embedded verbatim (§4).
3. The task plus executable success criteria (R5).
4. The required return format: one Insight Capsule (§4).
5. The R9 duty: on a scope or premise violation, issue one push-back with evidence and an alternative, pause that item, and report it in the capsule rather than working around it.
6. For writers: the worktree path — worktree paths are how the scope guard (§5) attributes subagent writes. WEAVE_STRAND={strand} only works for separately launched headless strand processes. Shell (Bash) writes bypass the guard entirely: strands must mutate files via Write/Edit, never via shell redirection.

3. Weave Session file — coordinator-owned single source of truth

Path: .planning/weave/session-{slug}.md. The coordinator is its only writer; strands read it (via their prompts) and communicate back only through capsules. Keep exactly one session at **Status**: active.

# Weave Session: {human-readable name}

**Status**: active | paused | completed | archived
**Direction**: {original request / goal}
**Activated**: {timestamp or commit}
**Coordinator**: {identity}
**Scope guard**: on | off ({reason if off})

## Current Pulse: {N}
**Pulse status**: in-progress | synthesizing | judgment-pending

## Strand Queue & Assignments
| # | Strand Name | Scope (directories/files) | Deps | Status | Agent(s) | Branch/Worktree | Evidence |
|---|-------------|---------------------------|------|--------|----------|-----------------|----------|
| 1 | api-auth | src/api/auth/, tests/auth/, ro:docs/ | - | in-progress | subagent | .weave-worktrees/api-auth | - |
| 2 | ui-review | ro:src/ui/ | - | in-progress | subagent | - | - |

## Pulse {N-1} Synthesis
- {key decisions and shared context, each claim R8-tagged}

## Insight Capsules (latest)
- {relative paths under .planning/weave/insights/}

## Open Judgment Items
- {decision briefs + validator verdicts, verbatim (§6)}

## Archive / Completion
- {final outcome, R8-tagged, on close}

Scope column grammar (machine-parseable; consumed by hooks/scope-guard.sh): comma-separated paths relative to the repo root; directories end with /; the prefix ro: marks a read-only claim, which documents intent and grants no write access. The coordinator claims its own row (strand name coordinator) when it needs to write outside .planning/weave/ and humanpending.md.

4. Insight Capsules

Each strand produces exactly one capsule per pulse, delivered twice: as its structured return to the coordinator AND persisted to .planning/weave/insights/{strand}-{seq}.md (seq = zero-padded per-strand counter: api-auth-01.md, api-auth-02.md; append-only, existing capsules are not edited).

Capsule contract:

• ≤ ~400 words. Compress; link to files instead of quoting them.
• Every load-bearing claim carries an R8 tag: [executed] | [inspected] | [assumed].
• Contents, in order: what changed (paths), key decisions + rationale, discoveries, failures/blockers, implications for other strands.

# Capsule: {strand}-{seq} (pulse {N})
**Changed**: src/api/auth/ — JWT middleware added [executed]
**Decisions**: jose over jsonwebtoken — maintained, smaller [inspected]
**Discoveries**: upstream rate limit is 100 req/min [executed]
**Blockers**: refresh flow needs ui-layer coordination [assumed]
**Implications**: ui strand must handle 15-min token expiry

No-rediscovery rule: before each fan-out, the coordinator embeds the prior capsules relevant to each strand directly in its prompt. A later strand re-deriving a fact an earlier capsule already established is a coordinator failure — fix the prompt assembly, not the strand.