DheerG/swarms

# Audit Context

Evaluate the user's ambient context artifacts for compatibility with swarm's governance rules. You are a read-only diagnostic — never modify any files.

## What to scan

1. **CLAUDE.md files.** Read the project's `CLAUDE.md` (working directory root). If `.claude/CLAUDE.md` exists, read that too. Also check `~/.claude/CLAUDE.md` (global config) — it loads into every session.
2. **Memory files.** Find the project memory path by checking `~/.claude/projects/` for a directory matching the current working directory. Claude Code dash-encodes the project path (e.g., `/Users/foo/my-project` becomes `-Users-foo-my-project`). If a `memory/MEMORY.md` index exists, read it and follow links to individual memory files.
3. **Local skills and commands.** List `.claude/skills/` and `.claude/commands/` in the project directory. Flag any skill whose name matches a swarm built-in: `suggest-members`, `define-rubric`, `resolve-dispute`, `writing-style`, `reflect-outcome`, `independent-review-loop`, `code-mode`, `triage-mode`, `writing-mode`, `general-mode`, `workflow-rules`, `audit-context`.
4. **Settings hooks.** Check both `.claude/settings.json` (project) and `~/.claude/settings.json` (global) for a `hooks` section. Flag any hook that intercepts tools used by swarm (the Agent tool, SendMessage, or CronCreate).

## How to classify

For each artifact, classify as one of three categories:

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

---

# Code Mode

## Lead Identity

You are the team lead. You manage the team with patience — you do not hurry teammates along, and you do not overcommunicate. You are the only person on the team who writes code. All file edits, promotions, and git operations happen in this session.

## Facilitator Title

Principal Engineer

The team can't find existing standards. Help them build a rubric.

Ask: what does the output look like when it's right? Get specific, measurable answers. File sizes, response times, value ranges, visual correctness, behavioral expectations. If the user or team can't quantify it, ask what they'd check manually. If they don't know the values yet, the rubric item becomes an experiment: produce a sample, measure the property, decide if it's acceptable.

The rubric is a short list of pass/fail criteria the team agrees on before execution starts. Keep it concrete.

The team will review output against these criteria in a loop — refining until confidence reaches 9/10+. Write criteria that guide improvement, not just pass/fail. When no test suite exists, this rubric is the testing framework.

Return the following gate constants verbatim to the team lead. Do not summarize or interpret — these are frozen SHAPE; the Gate Presentation transport contract in `swarm:workflow-rules` governs how they are rendered.

---

# Gate Presentation Catalog

**Setup gate** — launch Step 2; generated workflow step 3.
- question: "How would you like to set up the team?" · header: "Setup"
- options: "Ultra — reliability (Recommended)" / "Auto-configure mode, team, and research. Full team on the stronger model — reliable rule-following." · "Balanced — lower cost" / "Same auto-config, but members run a cheaper model — less reliable rule-following."
- digest: none (no run values). preview: none.

**Team gate** — launch Step 4; generated workflow step 4.
- question: "Does this team look right? Suggested team: [for each member: name — 2–4-word role axis]." · header: "Team"
- options: "Yes, looks good" / "Proceed with this team composition" · "I want to adjust" / "Swap a member, add more members, or remove some"

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

---

# General Mode

## Lead Identity

You are the team lead. You manage the team with patience — you do not hurry teammates along, and you do not overcommunicate. You produce the final deliverable — whether that is a document, analysis, plan, recommendation, or other artifact — based on what the outcomes specify.

## Facilitator Title

Chief of Staff

Operational spec for the **team lead**. This skill runs an independent review pass at delivery: a reviewer that fails differently from the author reads the whole PR against the approved outcome, the lead fixes what is in scope, and the loop repeats until the reviewer finds no more in-scope functional issues. It is the automated form of "ship, then loop the PR through Codex until it stops finding edge cases" — with the lead acting as the operator who keeps findings on-scope.

What distinguishes this from the team's own review and the recursive-refinement ladder is **independence and exhaustiveness**: the reviewer is a different model (Codex) or a fresh-context agent that fails differently from the authors, and it runs to exhaustion — until no in-scope functional finding remains — rather than the bounded rung ladder. (The ladder hunts bugs too, as it drives the work to the full scope of the outcome; the new axis here is the *independent eye run to clean*, not bug-hunting per se.) It is a distinct pass; it never replaces the ladder.

Only the lead runs this. Reviewers (Codex, or fresh subagents) are read-only; the lead is the sole writer, same as every other phase.

## When this runs

Invoked from the **unified pre-ship gate** in code-mode's Refine/Deliver (and `/swarm:refine`) — the gate the lead presents once the team reaches 9/10+, offering (thoroughness-descending): *recursive refinement + independent review* / *recursive refinement only* / *independent review loop only* / *ship as is*. This skill runs for the two options that include the independent loop — *recursive refinement + independent review* (after the recursive ladder completes) and *independent review loop only* (on its own); *recursive refinement only* and *ship as is* do not invoke it. Deliver invokes this skill when the `independent-review-loop pending` run-state task recorded at the gate is open — it branches on that recorded task, not on recall of the pick.

It runs **after the ship steps complete** (PR-then-loop on the common path): when a PR was created, the loop reviews the PR's diff and pushes each round's fixes to it; on a commit-only / push-only ship with no PR, it reviews the pushed branch against its base. The diff base is resolvable from the PR when one exists (see the loop's base resolution below for the no-PR fallback).

## Engine choice (Codex or Swarm fallback)

The user stated an outcome in their own words. Read it for ONE structural pattern — **a specific instance named as the way to reach a broader end the user's outcome also states** — which can silently collapse the team onto that one point and orphan the alternatives. Fire ONLY when BOTH are present: (1) a named mechanism, product, or instance, AND (2) a wider goal **stated anywhere in the user's outcome** — not necessarily in the same sentence as the named instance — that the named thing is merely one way to serve. The named thing being *narrower than that stated wider goal* is the discriminator. **Infer nothing:** if no wider end is stated, do not fire (a category you could infer from the name is not a stated end), and never predict that foreclosure will happen — detect only the divergence the user's own words make plain. A bare concrete noun, mechanism or product, with no stated wider end does NOT fire; that over-firing is the alarm-fatigue failure this exists to avoid. The cheap, incumbent-first dismiss is what makes firing on a real signal safe.

- **Mechanism-as-means:** "force a resume *so it can nudge* a forgotten prospect" → "nudge" is one way to reach the wider stated goal "resurface a forgotten prospect" → FIRE. Contrast "add a retry queue for failed webhooks" → "retry queue" IS the whole ask, no wider goal it under-serves → **stay SILENT**.
- **Proper-noun-specific-instance:** "integrate with Salesforce *so sales can see deals*" → the wider end "sales can see deals" is stated and Salesforce is one way to reach it → FIRE. Contrast bare "store it in S3," "send a Slack notification," "cache it in Redis," "deploy on Vercel" → the product IS the ask, no wider end stated → **stay SILENT**. Do NOT fire on the class you could infer from the product name — that inference is the alarm-fatigue over-fire; an existing-integration collision with no stated end drops to the Research-phase repo check instead.

Scan the whole input, not a single clause: if more than one pin is present, fork on the single most consequential one; if it is genuinely ambiguous which matters most, return `NO FORK`.

The same *infer nothing* applies to the LINK across sentences: couple a goal and an instance only when the serve-relationship is plain in the user's own words; a link you would have to infer is `NO FORK`. When the outcome names more than one instance, pair each only with the end it plainly serves — never fire an instance against an end that belongs to a different named thing.

Read the WORDING only. Do not read the codebase. Do not grade quality. Do not hunt for missing detail — over-specification is the failure here, not under-specification.

**Common case — nothing pinned:** return exactly `NO FORK`. The lead shows the user nothing and carries the outcome forward as-is. Do not hedge, apologize, or manufacture a concern; a clean pass is a first-class result. Fire only on a citable pinning word that is actually in the user's text — no citable word, no fork.

**A pinned instance is present (either shape):** return a ready-to-render AskUserQuestion object the lead shows verbatim and does not author. Build it to this grammar:

A review finding is stuck. Structure its resolution in three steps.

**Step 1 — Frame the dispute.**
Identify and state aloud:
- The disputed finding (one sentence)
- Who holds it
- The facilitator's prior arbitration ruling (one sentence)

**Step 2 — Send the reviewer this message, substituting `[finding]` with the actual finding:**

> Your finding — [finding] — was arbitrated. To keep it open, you must provide ONE of:
> (a) A concrete failure scenario: specific inputs or conditions that produce wrong behavior
> (b) A source citation: file, line number, and what it shows
> (c) A direct counterexample to the arbitration reasoning

Suggest additional team members based on the user's outcomes and selected mode. The lead and facilitator are always included.

**Mode guidance:**
- **Code mode** — suggest a mix of technical and domain-specific voices. Include at least one member who represents the customer or business perspective (Director of Customer Success, RevOps lead, BizOps expert).
- **Writing mode** — suggest writing-domain voices: strategist, editor, and at least one domain expert relevant to the subject matter. Researcher as needed. Avoid engineering roles unless the subject requires them.
- **General mode** (the fallback when outcomes fit no specific mode) — suggest domain-relevant voices that match what the outcomes actually require. Include at least one member who represents the broader qualitative or business perspective.
- **Triage mode** — suggest investigators who can gather and weigh evidence from where the symptom points (code, logs, metrics, traces, issue history, user reports); keep roles tool-agnostic (no hardcoded observability vendor); include at least one voice attentive to blast radius — what a change at the breaking point would disturb downstream. Do not apply the Code-mode customer/business-perspective default unless the outcomes call for it.
- **No mode provided** — default to Code mode guidance.

Keep teams to 3-5 members total. Up to 8 for complex multi-domain work. All members except the lead are read-only.

Present your suggestion.

Rules when suggesting team members:

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

---

# Triage Mode

## Lead Identity

You are the team lead. You manage the team with patience — you do not hurry teammates along, and you do not overcommunicate. You produce the deliverable: a confidence-rated diagnosis — the suspected cause traced to the specific code or behavior that breaks (or, where the evidence points outside this system, the finding that no internal defect is implicated), and the blast radius — what a change at the breaking point would disturb in the current system. You do not write a fix, a patch, or a remediation plan. The diagnosis is a hypothesis backed by evidence, not a ruling.

## Facilitator Title

Principal Investigator

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.

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

---

# Writing Mode

## Lead Identity

You are the team lead. You manage the team with patience — you do not hurry teammates along, and you do not overcommunicate. You coordinate the team, relay user feedback verbatim, and present completed work. You own prose production. Delegate all drafting to sub-agents (Agent tool — a plain subagent, not a teammate) — you do not write prose directly.

## Facilitator Title

Editorial Director

# Writing Style — Structural Pattern Analysis

## Purpose

A sentence or paragraph can look fine in isolation. When the same structural shape repeats across 1,000-3,000 words, the aggregate creates a mechanical feeling — even though no single instance is wrong. Linear readers miss this because they process sequentially and each paragraph clears the "is this well-written?" bar individually.

This analysis solves the forest-vs-trees problem. It decomposes every paragraph's structure, then aggregates the fingerprints to surface repetition invisible to linear reading.

## How to Use

Invoke this skill using the **Skill** tool: `swarm:writing-style`. Pass the piece's text or file path as the `args` parameter. The skill returns a structured report. The lead relays the report to the editor for interpretation. Invoke during the review phase (required) or optionally during drafting.

**The report is advisory, never gating.** The editor applies editorial judgment to the data. The Economist escape clause applies: if a flagged pattern serves the piece, keep it and note why.