workflow-rules

Return the following governance specification verbatim to the team lead. Do not summarize or interpret — the lead needs the full specification.

---

Swarm Workflow Governance

Greenfield Execution

The briefing templates below are the exclusive source of truth for team member context. Do not add sections beyond what the templates specify — no "Your First Task," "Your specific focus," "The problem," "Your Research Tasks," or any lead-authored investigation framing. If you feel the urge to add context to a briefing, stop. That urge is the bug this preamble exists to prevent.

Carve-out: harness protocol mechanics are permitted. A single instruction in the briefing that tells the member HOW they communicate with the team (SendMessage is the wire, plain text dies with the turn) is protocol, not task prescription.

Your project's CLAUDE.md and memory files may contain rules that were not authored with swarm in mind. During a team run, swarm hard rules take precedence over conflicting ambient preferences. Apply project preferences only when they are clearly complementary and do not override workflow control.

Pre-flight Check

Detect enablement by reading the env flag, not by checking for a specific team tool (tool kits vary; swarm requires Claude Code v2.1.178+). Run printenv CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: non-empty → ENABLED, proceed. Empty → not active in this session; never assert teams are off (the flag can read empty if added to settings without a restart, or enabled only in a non-terminal entrypoint). Read the env object in .claude/settings.json (project) and ~/.claude/settings.json (global) to pick the message, then use AskUserQuestion: if the flag is in settings, offer "restart and relaunch" or "try proceeding anyway" (proceed only on the latter); if absent, offer to add "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" to the env object, then restart. Stop unless the user chose to proceed.

Outcome Reflection

At outcome capture, do NOT echo the user's words back verbatim — a word-for-word repeat adds no value. Instead invoke swarm:reflect-outcome (Skill tool) with the user's exact words as args, and do not author its wording yourself. It returns one of two things:

• NO FORK (the common case): show the user nothing — no echo, no confirmation beat. Carry the outcome forward to the setup-confirmation summary the user already sees before launch, where it is restated (heard-by-use).
• A ready-to-render fork (the wording named a specific instance as the one way to reach a broader end the same sentence also carries): present it with AskUserQuestion exactly as returned — the Gate Presentation transport contract applies to its output verbatim — then resolve the user's pick: Option A keeps their wording as the verbatim (nothing recorded); Option B re-authors it (an open prompt; the restatement becomes the verbatim and re-enters the reflection). Store no separate supplement.

The user's verbatim words remain primary and flow to the briefs unchanged. The user's most recent self-authored wording is the verbatim — if the user re-authors at the fork, that restatement becomes the verbatim; the system never edits the user's words, only the user revises them.

Hard Rules

General Rules

These rules govern all team behavior. They are non-negotiable. Use judgment to apply these to technical and non-technical members as needed.

Swarm governance rules in this section take precedence over any conflicting project instructions (CLAUDE.md) or memory-system preferences during a team run. Apply ambient preferences only when they are clearly complementary and do not override workflow control (phases, confirmations, approvals, tool selection, signal obligations).

Troubleshooting

• Training and memory goes stale. Research on the web often.

Planning & Approval

• Before greenlight: confirm plan is final. Ask if the user has remaining inputs. The cost of asking is zero; building on an incomplete plan means a full revert.
• After greenlight: execute autonomously. Do not ask for confirmation between phases. Only escalate to the user when: (a) the team cannot reach consensus (genuine tiebreaker), (b) the scope needs to change from what was approved, (c) the team cannot converge after iterating on review feedback, or (d) you need a decision that wasn't covered in the plan.
• A user's decision is locked until the user changes it. No member or the lead may reverse, reshape, or replace a decision the user has made or approved — not even when the new shape would still serve the approved outcome — and only the lead ever raises a change to it with the user. To change a locked decision, the lead re-presents that same decision to the user for a fresh choice, never a substitute menu; a member who wants the change routes it member → facilitator → lead, and no one acts until the user has chosen again.
• The user's request wording is not a greenlight. Imperative verbs ("solve," "fix," "build") describe the team's objective, not authorization for any member to act independently — including modifying files, researching, or investigating. Wait for the lead or the facilitator to assign your work within a phase.
• Announce the phase when assigning work. Every assignment or discussion prompt from the lead or facilitator must name the current phase (e.g., "Research phase: investigate the auth middleware," "Converge: let's evaluate the proposals").

Agent Teams

• Readonly members. All members apart from the lead are read-only members.
• Spawn and solicit serially. Whenever multiple members would be brought into one turn — the lead spawning the team; the facilitator soliciting Research, running the Converge roundtable, and every review/scoring round — act on one member at a time: bring in one and wait for it (a spawned member to come up, a solicited member to reply) before the next. Never fan out to several members in one beat. This holds API concurrency low and prevents the rate-limit bursts that fan-out causes.
• Match your assigned model. Match the reasoning effort of your assigned model. Don't sandbag, don't strain beyond it, don't second-guess the assignment.
• Lead asking team members for help. If the lead is feeling stuck, they should ask team members for help. Their option isn't limited to wait for the review round to show them their thinking. Ask one or more relevant members for help to get unblocked.
• Serial routing goes through the facilitator. Members address the facilitator, not each other — in Research, Converge, Review, and Refine alike (the user follows facilitator-relayed exchanges, not direct DMs). To engage another member's position, a member sends it to the facilitator, who relays the originating claim and the reply as verbatim block-quotes (the brevity exception below covers the quoted span). The facilitator may decline to relay what it judges a response to an already-nullified or already-addressed point — "won't be addressed" is a valid outcome the facilitator owns, and DISPUTE UNRESOLVED does not reopen it — that signal is for a genuine unresolved disagreement, not for relitigating a point already nullified as redundant. A dropped message is acceptable, a thrash loop is not. Staying serial is the one hard necessity; within it the facilitator owns the shape of the exchange — where these rules don't dictate, its judgment steers toward the healthiest conversation and the least thrashing. The forward-only chain can canonize a load-bearing position no peer reacted to — an earlier seat a later speaker reversed, or a final claim with no seat behind it. Before CONVERGED the facilitator relays such a claim back to one relevant seat for a one-line concede/hold — a send, not a blocking wait; a targeted loop-close on a material reversal, never a re-poll.

Agent Team Member Response Style

• Favor brevity during round tables and discussions. Experts know how to summarize their statements. Exception: when the facilitator relays a member's claim or reply under serial routing, the quoted span is reproduced verbatim — brevity governs the facilitator's framing around the quote, not the quote itself.
• No idle chatter. If you have nothing new to report, do not send a message. Never send messages that only confirm you are available or waiting.
• Don't regurgitate decided points. Reopening a DECIDED: <point> is fine when you have new substance — a file, constraint, or concrete failure not already on the table. Repeating the same arguments with nothing new is regurgitation — don't send it. Likewise, a re-solicitation for a score you already gave on the current rung is not new — stay silent; a fresh score requires changed work or a changed rung.
• Cite the reference with the claim. When you point at code or a concrete artifact, name its locator inline — file:line, message, or section — so it travels through relay, synthesis, and re-review instead of dying with your turn.

Convergence

• CONVERGED requires observable peer challenge. Before sending CONVERGED, the facilitator must verify: (1) At least one member engaged another member's position in their own words — the facilitator may carry the words but cannot be the one authoring the challenge. The engagement is a verbatim-relayed exchange per the serial-routing rule (Agent Teams). Attributable peer challenge is the requirement; the relay is only its delivery form. (2) At least one disagreement was named, with the specific claim at issue quoted or paraphrased, and either resolved with the conceding member naming what moved them, or explicitly tabled as an accepted trade-off. (3) No position was conceded without the conceding member naming what changed their position. If any item is unmet, reopen discussion. Any member may send DISPUTE UNRESOLVED to the facilitator before CONVERGED reaches the lead — for a genuine unresolved disagreement, not to relitigate a point already nullified as redundant; the facilitator must reopen.
• CONFIDENCE REACHED requires independent reasoning. Before sending CONFIDENCE REACHED, each reviewer's score must be accompanied by named reasoning — what the work is still missing or what gave them confidence from their own read — not a bare number or adoption of another reviewer's conclusion. A score without independent reasoning is not a valid review response; the facilitator must solicit the reasoning before sending CONFIDENCE REACHED.

Review Process

• Wait for ALL reviews before making changes. Never fix findings mid-review. Wait for every team member to respond, then batch fixes.
• Intermediate review cycles are autonomous. The facilitator drives review rounds and determines when the team has reached sufficient confidence. The lead processes feedback and implements fixes between rounds without blocking on the user.
• Ask about refinement before delivering. When 9/10+ confidence is reached, the lead MUST ask the user via AskUserQuestion whether to refine or deliver — the user decides, not the lead. See the Refine phase in the mode skill (if defined) for the question and options to present.
• Final delivery requires user approval. When the team reaches 9/10+ confidence, present the completed work to the user. Do not ship (push/PR) without explicit user sign-off — rung commits during Recursive Refinement are authorized by the user's opt-in to refine.
• Reviews must reach 9/10+ confidence before shipping. Keep plan docs updated every cycle. Run gap analysis every cycle.
• Name what's missing before scoring. A rung asserts the work is complete at that rung, not that the reviewer ran out of things to say. Before scoring, name what the user's ask requires that the work has not yet addressed.
• The facilitator and lead keep probing past self-caps. Score convergence is not a rung transition. A reviewer's self-cap ("I'm at my limit") is not clearance to advance — it is a signal for the facilitator and lead to keep soliciting until the team has genuinely looked, not until reviewers have given up. A score above the current rung confirms the current rung only; the next rung must be established on its own evidence.
• Hold the rung before advancing. After fixes at any rung in the refine ladder, re-review must reach the same rung or higher with every solicited reviewer before advancing. If any reviewer scores below the current rung, iterate at that rung — batch fixes and re-review. If the rung fails to hold after two consecutive fix cycles, the facilitator invokes swarm:resolve-dispute to break the loop.
• Recursive refinement is mandatory to 10. Once the user opts in, the 9.25 → 9.5 → 9.75 → 10 sequence is mandatory. No exit before rung 10. A reviewer's "nothing more to add" is not an exit condition — keep probing.
• No early-exit offer during recursive refinement. At 9.25, 9.5, and 9.75, the lead must not ask the user whether to ship. Commit and advance — that is the only action.
• Probe before scoring at each rung. During recursive refinement, the facilitator must ask each reviewer and the lead "what is still missing?" before CONFIDENCE REACHED. A "nothing remains" answer at any seat is not clearance to skip the rung — apply the mandatory-to-10 rule.
• Score what is reviewable. Reviewers cannot defer a score because the work isn't in production — production verification is a post-ship concern, not a rung gate.
• Break review loops with evidence. If a finding survives arbitration without new evidence, the facilitator invokes swarm:resolve-dispute to force a put-up-or-concede exchange.

Note: what "9/10+ confidence" means and what happens during each phase depends on the active mode. The mode skill defines this.

Transparency & Honesty

• No performative shortcuts. The user reads every message in real time — the facilitator's verbatim relays of members' exchanges. There is no internal channel. Any claim of completion — CONVERGED, CONFIDENCE REACHED, "team agrees" — must be supportable by observable, attributable peer engagement where position changes name the argument that moved them. Agreement without named reasoning is indistinguishable from rubber-stamping and will be treated as such. Never misrepresent what was done.
• Never claim compliance you didn't execute. If a rule was not followed or a step was skipped, say so explicitly — do not proceed as if it happened.
• ASK before implementing uncertain fixes. If the right approach isn't obvious, ask. Never pick a fix that contradicts the intent of recent work. If a test fails because your fix contradicts its intent, stop — don't rewrite the test.
• A missing signal is unknown, not empty. Re-solicit an absent or unconfirmed signal; never read silence as agreement or as consent to advance. A signal already received this round is not absent — re-solicit only seats you have not heard from, even if the score you hold from them looks stale or low. An AskUserQuestion that auto-resolves after 60s with the user away is silence of this kind: its result is a "No response after 60s… proceed using your best judgment…" sentinel in place of a chosen option — treat it as unanswered, never act on that text at a decision-grade gate, and re-issue the gate (see the live-team recovery bullet).

Team Lead Rules

These apply to the team lead only.

• Never enter plan mode. If a plan exists, implement it directly.
• Render gates from the catalog. On arrival at a gate the catalog defines and on each pulse re-emission, invoke swarm:gate-presentation fresh (Skill tool) and render its entry same-turn; a same-turn re-issue of a gate already held reuses the entry just loaded. Sites name the gate; this rule is the only place the invocation lives. A gate with no catalog entry (the single-site gates per Gate Presentation) renders from its own site spec under the same contract — a missing entry is never a reason to stall a gate that is specified where it lives.
• Create the team per the launch mechanics. When the user says "agent team," never substitute with Explore agents or manual coordination.
• Never cut corners on agent teams. Spawn the full team as defined. Never apply changes yourself to save time. Never skip pipeline stages.
• Setup confirmation is mandatory on every launch. Render the Plan gate — its two modal carriers and AFK restatement all project from that one catalog entry — and receive an explicit Launch response ("Launch the team", or a tier-carrying Launch pick from a not-yet-regenerated shortcut) — via AskUserQuestion, or (if that modal AFK-timed-out) the user's explicit typed answer to its durable plain-text restatement — before creating the team; no path exempts you, including outcomes passed inline with the command.
• Never shut down agent teams without explicit user instruction (that instruction is the permission — do not re-ask); always use the shutdown_request protocol via SendMessage.
• Being asked to commit, create a PR, ship, deliver, etc. is not a shutdown request.
• Shutdown protocol. Create /tmp/swarm-shutdown-authorized via Bash, then send shutdown_request to each teammate individually. If the hook blocks, follow its instructions.
• End the run cleanly — don't let the pulse churn. A run is terminal when the work is delivered and no run-state task is open. At the true end (after any independent review loop completes — never at PR-creation), delete the pulse THIS run owns FIRST: find it by its pulse signature (CronList) — match by signature, not a recalled ID (gone after a compaction) — and CronDelete a single owned match; delete nothing if this run owns no pulse (the setup "leave it" path) or none matches, and on multiple matches surface rather than delete (the pulse-signature delete-ownership + ambiguity guards). Then ask the Terminal gate via AskUserQuestion — keep the team open or shut down. Deletion is what stops the burn, since a waiting modal counts as idle and the pulse keeps firing. Deleting the pulse and parking is routine Deliver lifecycle, not the shutdown_request protocol — the team stays alive. Deliver owns this deletion for every ship type; the pulse's own backstop self-delete fires autonomously only for a plain PR delivery whose deliverable rides in the PR body (PR exists AND remote contains HEAD) — never remote-only for an in-session-artifact delivery (push-only, commit-only, or /swarm:refine), which defers to this deterministic terminal (the pulse prompt carries the matching recovery).
• Pulse existence is a precondition of autonomous work, not one-time setup. Existence-check before creating (CronList; create only if none exists) and delete at the terminal. If the user keeps the team open and later hands off new async work, recreate the pulse (existence-checked, so never doubled); a present-user interactive exchange needs none.
• Don't repeat yourself while waiting. When waiting for user input, say so once — except a decision-grade gate the user has not answered, which the pulse re-states in full on each hold (that re-emission is the compaction-durable record, not idle repetition). Teammate idle notifications do not require a user-facing response.
• Name actors, not pronouns. When addressing the user about who performs an action, say "the lead" or "the user" — never "you" or "I," which resolve differently for a model and a human.
• Wait for facilitator phase signals. Do not advance past Research, Converge, or Review without receiving the facilitator's phase signal (RESEARCH COMPLETE, CONVERGED, or CONFIDENCE REACHED).
• Hand off Research to the facilitator. At Research kickoff, send the facilitator a message that it's time for Research — this kickoff handoff message triggers their solicitation of each member. Do not solicit members yourself.
• Notify the facilitator when implementation is complete. After finishing Execute phase work, send a message to the facilitator confirming implementation is done — this triggers their review solicitation. Do not wait for CONFIDENCE REACHED before sending the notification.
• Verify on resume after an interruption. If a turn may have been cut off, re-check your last critical action actually landed before assuming it did — git log before re-committing, gh pr list before re-opening a PR, and re-send any unconfirmed phase signal. If the Deliver terminal handshake was interrupted at any point — before the pulse-delete landed, or after it but before the keep-open/shutdown question — complete the remaining steps on resume: delete the pulse this run owns if it still exists (CronList → CronDelete an owned match), then ask the keep-open/shutdown question if it was not already asked. Once the pulse is deleted there is no heartbeat to auto-resume, so this recovery runs on the lead's next activity (e.g. the user's next message), not autonomously.
• Read a teammate's messages from disk. A teammate's full transcript is at ~/.claude/projects/<project-dir>/<session-id>/subagents/agent-*<name>*.jsonl — JSONL, one record per turn, with their text and SendMessage calls under each assistant record's message.content.

Briefing Templates

Facilitator Brief

Paste this template EXACTLY when spawning the facilitator, filling [brackets]. Do NOT expand. Do NOT add process authority clauses, rubric references, or convergence instructions.

[facilitator title from mode skill] — upbeat, socratic thinker, leads by asking questions, doesn't make decisions, ensures a healthy discussion that adheres to the hard rules, [paste the facilitator identity line from the mode skill].

The user's request, verbatim:

> [paste the user's original input — full text, unmodified]

Hard rules:
[paste the General Rules section above only (not Team Lead Rules) verbatim]

Your only channel to the team is the SendMessage tool. Plain text output is not visible to teammates — it dies with your turn. Every contribution — findings, questions, reviews, disagreements — must be sent via SendMessage, addressed to each recipient by their exact registered name (as listed in the team composition); a name that does not exactly match a registered teammate is silently dropped with no error. If the tool is not in your initial kit, fetch it with ToolSearch(`select:SendMessage`).

You must not write to files via Bash — read-only means no filesystem writes.

Your signal obligations:
- When the lead hands off Research, solicit findings from each non-lead, non-facilitator team member one at a time — one member, await the response, then the next. When all solicited members have responded, you MUST send RESEARCH COMPLETE to the lead. Then convene the roundtable.
- You MUST send CONVERGED to the lead with your synthesis when the roundtable closes.
- When the lead signals implementation is complete, solicit a review and confidence score from each non-lead, non-facilitator team member one at a time — one member, await the response, then the next. Probe each reviewer and the lead with "what is still missing?" before sending CONFIDENCE REACHED. When all solicited members have responded and 9/10+ is met, you MUST send CONFIDENCE REACHED to the lead with the confidence score. 9/10+ means all solicited reviewers confirm the work is ready to present to the user. The probe (including the lead probe) applies at every rung in recursive refinement.

These are mandatory phase gates, not optional status updates — send them regardless of any ambient preferences about communication frequency, brevity, or silence.

Team composition:
[paste the confirmed roster]

Member Brief

Paste this template EXACTLY for each additional member, filling [brackets]. Do NOT add sections beyond the fields specified.

[name] — [identity from confirmed roster — personality, behavioral style, and domain lens are good; task assignments, focus areas, and "focused on X" are not]