docs: add Compound Engineering patterns + guide-reviewer agent

4 patterns issus du plugin compound-engineering d'Every.to intégrés dans le guide (Named Perspective Agents, Swarm vs Sequential, Skill Quality Gates, Brainstorm-before-planning). Évaluation formelle 4/5. - guide/ultimate-guide.md: +~90 lignes (4 insertions) - docs/resource-evaluations/2026-03-04-compound-engineering-every-to.md - .claude/agents/guide-reviewer.md: audit accuracy/style guide content - CLAUDE.md: command naming conventions section - CHANGELOG.md: entrée [Unreleased] documentant les changements Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-04 17:25:02 +01:00 · 2026-03-04 17:25:02 +01:00 · 3788369839
commit 3788369839
parent 6e1f7a3e3b
5 changed files with 403 additions and 0 deletions
--- a/.claude/agents/guide-reviewer.md
+++ b/.claude/agents/guide-reviewer.md
@ -0,0 +1,87 @@
+---
+name: guide-reviewer
+description: Vérifier accuracy factuelle, détecter marketing speak, checker anti-AI markers (em dashes, staccato), tone Bold Guy dans le guide ou une section. Retourne une liste de findings classés par type. Use when reviewing newly added guide content before committing.
+model: haiku
+color: blue
+tools: Read, Grep, Glob, mcp__claude-code-guide__search_guide, mcp__claude-code-guide__read_section
+---
+
+Tu es un relecteur expert de documentation technique. Ta mission : auditer l'exactitude et le style d'un texte ajouté au Claude Code Ultimate Guide.
+
+## Ce que tu vérifies
+
+### 1. Accuracy factuelle
+
+- Les claims sont vérifiables (pas de "X% improvement" sans source)
+- Les noms d'outils, commandes, et APIs sont exacts
+- Les numéros de lignes ou sections référencés existent
+- Aucune information inventée ou hallusinée
+
+### 2. Marketing speak
+
+Patterns à signaler :
+- Superlatifs non prouvés ("blazingly fast", "perfect", "powerful")
+- Adverbes vides ("easily", "seamlessly", "simply")
+- Affirmations non sourcées ("studies show", "everyone agrees")
+- Promesses marketing sans preuve
+
+### 3. Anti-AI markers (CLAUDE.md ANTI_AI.md rules)
+
+Détecter :
+- Em dash `—` (interdit — remplacer par virgule ou restructurer)
+- Staccato : 3+ phrases de moins de 5 mots consécutives
+- Pattern "Ce n'est pas X. C'est Y." utilisé plus d'une fois
+- Punchline finale trop parfaite ou symétrique (slogan)
+- Paragraphes avec une seule idée systématiquement
+
+### 4. Tone Bold Guy
+
+Le texte doit être :
+- Direct et factuel (pas de détours)
+- Sans bullshit marketing
+- Positif sans être creux
+- Avec des exemples concrets quand il affirme quelque chose
+
+## Format de sortie
+
+```
+## Guide Review Findings
+
+### Accuracy
+- [FACTUAL ERROR] Ligne X : "claim" — problème + correction suggérée
+- [UNVERIFIED CLAIM] Ligne X : "claim" — source manquante
+
+### Marketing Speak
+- [MARKETING] Ligne X : "term" — remplacer par formulation factuelle
+
+### Anti-AI Markers
+- [EM DASH] Ligne X : passage concerné
+- [STACCATO] Lignes X-Y : 3 phrases courtes consécutives
+- [SLOGAN] Dernière phrase : trop symétrique
+
+### Tone
+- [BOLD GUY] Ligne X : affirmation sans exemple concret
+
+### Summary
+X findings total — Y bloquants (accuracy), Z style
+```
+
+Si aucun problème : "Clean — no findings."
+
+## Instructions
+
+1. Lis le texte fourni (section ou fichier)
+2. Pour chaque finding, cite le passage exact entre guillemets
+3. Propose une correction concrète pour chaque finding
+4. Priorise les findings d'accuracy (plus graves que le style)
+5. Ne propose pas de réécriture complète — signale les points précis
+
+## Déclenchement
+
+Utiliser quand l'utilisateur dit : "review cette section", "check ce texte avant commit", ou "audite cette addition"
+
+Exemple :
+```
+Review le texte suivant avant commit dans le guide :
+[texte à vérifier]
+```
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

 ## [Unreleased]

+### Added
+
+- **For Tech Leads & Engineering Managers** (`guide/learning-with-ai.md`, nouvelle §12) — section dédiée aux tech leads et engineering managers, angle mort identifié via évaluation de ressource (Mathieu Eveillard, "Génération LLM"). Le guide couvrait uniquement la perspective individuelle ; cette section adresse la responsabilité organisationnelle. Contenu : modèle d'onboarding 4 semaines (semaine 1 sans AI pour calibration avant que l'outil masque les lacunes, validé par Create Future 2025 : training structuré → 14-42% → 35-65% time savings), 5 métriques de croissance réelle vs. vélocité, 3 modèles de mentoring scalables (pair rotations, architecture hot seat 15min/semaine, CLAUDE.md collectif), template de politique AI d'équipe pour `CLAUDE.md` partagé, 6 warning signs au niveau équipe avec réponses spécifiques, quick checklist. Nouvelle section "Team & Organizational Research" dans les sources (Create Future 2025, Stanford Digital Economy 2025, LeadDev, Stack Overflow Gen Z). Fichier d'évaluation créé : `docs/resource-evaluations/2026-03-04-eveillard-generation-llm.md`.
+
+- **Compound Engineering patterns** (`guide/ultimate-guide.md`, 4 insertions) — patterns portables issus du plugin compound-engineering d'Every.to (Kieran Klaassen, prod-tested sur Cora), absents du guide jusqu'ici. (1) **Named Perspective Agents** : distinction entre persona roleplay (anti-pattern, interdit §3.x) et named perspective (DHH = fat models + thin controllers + REST pragmatique condensé en un token), avec caveat sur le drift entre versions de Claude. (2) **Swarm vs Sequential** : tableau comparatif des deux modes de coordination multi-agents, règle de décision (Swarm = indépendant + thoroughness, Teams = dépendances séquentielles). (3) **Skill Quality Gates** : checklist 9 critères content au-delà de la validation frontmatter (`/audit-agents-skills`). (4) **Brainstorm-before-planning + hiérarchie documentaire** : workflow `docs/brainstorms/ → docs/plans/` avant de coder, tableau des 5 répertoires avec leur rôle distinct (CLAUDE.md = règles, solutions/ = problèmes résolus, brainstorms/ = réflexion, plans/ = plans actifs, todos/ = tâches éphémères). Évaluation formelle : `docs/resource-evaluations/2026-03-04-compound-engineering-every-to.md` (4/5 HIGH VALUE).
+
+- **Session Auto-Rename pattern** — instruction comportementale dans `~/.claude/CLAUDE.md` qui fait renommer automatiquement les sessions par Claude après 2-3 échanges, sans hook ni script. Format `[action] [subject]` (ex: "fix auth middleware", "refactor hook system"), max 50 chars, verbe d'action en premier. Utile pour retrouver les sessions via `/resume` quand plusieurs tournent en parallèle. Limitation documentée : le tab terminal WebStorm ne peut pas être renommé (ANSI sequences filtrées par JetBrains). Template : `examples/claude-md/session-naming.md`. Guide : nouvelle sous-section "Session Auto-Rename" dans §1.3 Session Continuation. Compteur templates 175→176.
+
+- **Straude** (`guide/third-party-tools.md`, section Token & Cost Tracking) — fiche complète pour straude.com, dashboard social pour tracker la consommation Claude Code avec leaderboard et streaks. Inclut : description fonctionnelle, tableau des données transmises au serveur (coûts, tokens, modèles, hostname), analyse de sécurité basée sur inspection directe du code source (`npm pack straude@0.1.9`), verdict (pas de malware, réserves sur la maturité et l'absence de privacy policy), recommandation `--dry-run` en première utilisation. Évaluation complète : `docs/resource-evaluations/straude-evaluation.md`. Entrées ajoutées dans `machine-readable/reference.yaml`.
+
 ## [3.30.1] - 2026-03-04

 ### Documentation
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -154,6 +154,19 @@ These commands are defined in `.claude/commands/` and automate:
 - Landing site synchronization verification
 - Git commit and push to both repositories

+### Command Naming Conventions
+
+Implicit prefixes used in `.claude/commands/`:
+
+| Prefix | Pattern | Examples |
+|--------|---------|---------|
+| `audit-*` | Quality checks with scored output | `audit-agents-skills`, `audit-deps` |
+| `update-*` | Sync or refresh data from external source | `update-infos-release`, `update-threat-db` |
+| `security-*` | Security scans, ascending depth | `security-check` (quick), `security-audit` (full) |
+| *(no prefix)* | Core guide workflow commands | `release`, `sync`, `version`, `changelog` |
+
+When adding a new command, pick the prefix that matches the action type. Avoid creating new prefix categories unless the existing four don't fit.
+
 ## Conventions

 ### Documentation Style
--- a/docs/resource-evaluations/2026-03-04-compound-engineering-every-to.md
+++ b/docs/resource-evaluations/2026-03-04-compound-engineering-every-to.md
@ -0,0 +1,188 @@
+# compound-engineering (Every.to) - Resource Evaluation
+
+**Evaluated**: 2026-03-04
+**Source**: https://github.com/EveryInc/every-marketplace (plugin compound-engineering)
+**Article**: https://every.to/p/the-compound-engineering-philosophy (Kieran Klaassen, Every.to)
+**Type**: Claude Code Plugin (agents + commands + skills) + Engineering Philosophy
+**License**: MIT
+**Status**: Active — prod-tested at Every.to on Cora (their flagship AI product)
+
+---
+
+## Executive Summary
+
+**Final Score**: **4/5 (HIGH VALUE)**
+
+Compound Engineering is a production-tested engineering philosophy from Every.to, implemented as a full Claude Code plugin: 29 specialized review agents, 22 workflow commands, 20 domain skills. The philosophy formalizes a Plan → Work → Review → Compound loop with explicit 50/50 allocation between feature work and system improvement. Several patterns are absent from the guide and portable without installing the plugin: Named Perspective Agents (DHH, Kent Beck as opinion shortcuts), Swarm Mode (ad-hoc parallel reviewers), Skill Quality Gates (explicit checklist beyond frontmatter), and the Brainstorm-before-planning workflow. The multi-tool AI converter (Claude → GPT-4 → Gemini syntax) is innovative but out of scope for this guide.
+
+---
+
+## Resource Overview
+
+### Plugin Structure
+
+| Component | Count | Examples |
+|-----------|-------|---------|
+| Agents | 29 | DHH reviewer, Kent Beck reviewer, swarm orchestrator |
+| Commands | 22 | /workflows:plan, /workflows:work, /workflows:review, /workflows:compound |
+| Skills | 20 | security, performance, architecture, accessibility |
+| Directory structure | 4 | docs/brainstorms/, docs/plans/, docs/solutions/, todos/ |
+
+### Core Concepts
+
+- **Plan → Work → Review → Compound loop**: 40% plan, 10% implement, 40% review, 10% compound
+- **50/50 rule**: Half time building features, half improving the system
+- **Named Perspective Agents**: Agents named after known engineers (DHH, Kent Beck) as compact opinion shortcuts
+- **Swarm Mode**: On-demand parallel specialist review, no predefined team structure
+- **Brainstorm-before-planning**: Check existing brainstorms before creating a plan, avoid re-solving solved problems
+- **Docs-as-memory**: Structured directory hierarchy replaces ad-hoc CLAUDE.md sprawl
+
+### Production Context
+
+Compound Engineering runs in production at Every.to on Cora, their AI-native note-taking and knowledge product. Kieran Klaassen is a founding engineer. The patterns described come from a live codebase, not a theoretical framework.
+
+---
+
+## Evaluation
+
+### Score: 4/5 (HIGH VALUE)
+
+**Justification**:
+
+1. **Credible source**: Every.to is a serious AI-native company. Kieran Klaassen is a practitioner, not a blogger. The plugin is open-source and contains real agents with real prompts, not marketing copy.
+
+2. **Portable patterns**: Named Perspective Agents, Swarm Mode, Skill Quality Gates, and the Brainstorm-before-planning workflow all work with any Claude Code setup. Zero dependency on the plugin itself.
+
+3. **Real implementation**: 29 agents means 29 actual system prompts you can read and learn from. Most Claude Code content describes patterns without showing real implementations. This one shows the code.
+
+4. **Novel patterns**: Named Perspective Agents and Swarm Mode are not documented anywhere in the current guide. Both are immediately applicable and distinct from existing patterns (scope-focused agents, agent teams).
+
+5. **Philosophy depth**: The 50/50 allocation rule and the adoption ladder (stages 0-5) are concrete decision tools, not vague recommendations.
+
+**Why not 5/5**:
+
+- No quantified metrics — no "X% improvement" in shipping velocity, review catch rate, or defect rate. All claims are qualitative.
+- Named Perspective Agents are opinion-based — whether a DHH agent reliably encodes "fat models, thin controllers" depends on Claude's training, which varies by version.
+- Several agents are short (<20 lines) and may not be more effective than a well-crafted inline prompt.
+- The multi-tool AI converter is the most novel feature but is completely out of scope for this guide.
+
+### Caveats
+
+- **Named personas risk drift**: DHH's opinions evolve. A static "DHH agent" may become outdated or diverge from his current thinking as Claude's training data shifts.
+- **Swarm vs Teams**: Swarm Mode (ad-hoc) and Agent Teams (persistent, coordinated) solve different problems. Conflating them is a common confusion point.
+- **Plugin install not required**: Installing the plugin adds 29 agents + 22 commands to every project, which may be excessive. The patterns work without it.
+
+---
+
+## Portable Patterns
+
+### 1. Named Perspective Agents
+
+Instead of generic "reviewer" agents, name agents after engineers whose views you want represented:
+
+```markdown
+---
+name: dhh-reviewer
+description: Review code from DHH's perspective (Rails conventions, fat models, thin controllers, pragmatic REST)
+---
+```
+
+The name serves as a compressed prompt — it bundles a recognizable set of opinions into a single token rather than spelling them out. Works for: DHH (Rails, REST), Kent Beck (TDD, simplicity), Martin Fowler (refactoring, patterns).
+
+**Constraint**: Only works for engineers whose views Claude has been trained on and whose opinions map to a distinct, stable style.
+
+### 2. Swarm Mode
+
+On-demand parallel review across multiple specialists, without predefined coordination:
+
+```bash
+/slfg                      # Start swarm
+/workflows:review --swarm  # Launch all relevant reviewers in parallel
+```
+
+Unlike Agent Teams (which have a persistent lead + member structure), swarm is stateless: each reviewer gets the PR/diff independently, reports findings, and the human synthesizes. Best for: final review before merge, unfamiliar codebase areas, thoroughness over coordination.
+
+### 3. Skill Quality Gates
+
+Beyond frontmatter validation, Compound Engineering defines explicit content quality criteria for skills:
+
+- Frontmatter must include name, description, allowed-tools
+- "When to Apply" section is required (not optional)
+- Methodology must be structured (steps, not paragraphs)
+- No TODOs or placeholder language
+- allowed-tools scoped to minimum necessary
+- Output format must be documented
+- No AskUserQuestion in cross-platform skills
+
+### 4. Brainstorm-before-planning Workflow
+
+Before creating a plan, check if a brainstorm already exists:
+
+```
+docs/brainstorms/    <- Thinking documents (problem exploration)
+docs/plans/          <- Active implementation plans
+docs/solutions/      <- Solved problems with context
+todos/               <- Task tracking
+```
+
+Agent instruction: "Before creating a plan for X, check docs/brainstorms/ for existing thinking on this topic."
+
+---
+
+## Gap Analysis
+
+### Current Guide Coverage (Before Integration)
+
+| Pattern | Coverage |
+|---------|---------|
+| Compound Engineering philosophy | Partial (added in recent release, loop + plugin) |
+| Named Perspective Agents | Not documented |
+| Swarm Mode | Not documented |
+| Skill Quality Gates (content criteria) | Not documented (frontmatter validation only) |
+| Brainstorm-before-planning workflow | Not documented |
+| Docs directory hierarchy (brainstorms/plans/) | Partial (solutions/ mentioned, not the full hierarchy) |
+
+### Post-Integration Target
+
+- Named Perspective Agents: subsection after Pat Cullen Multi-Agent Code Review example
+- Swarm vs Sequential: comparison table after Agent Teams decision tree
+- Skill Quality Gates: checklist after "Validating Skills" section
+- Compound Engineering expansion: brainstorm workflow + docs hierarchy added to existing CE section
+
+---
+
+## Integration Details
+
+### Placement
+
+| Insert | Section | After |
+|--------|---------|-------|
+| 1A Named Perspective | 3.x Multi-Agent | Pat Cullen example (~l.6406) |
+| 1B Swarm vs Sequential | 9.20 Agent Teams | Decision tree (~l.19643) |
+| 1C Skill Quality Gates | 5.2 Skills | Validating Skills (~l.6720) |
+| 1D CE Expansion | 3.x CE Philosophy | Plugin paragraph (~l.4455) |
+
+### reference.yaml keys to add
+
+```yaml
+named_perspective_agents: "guide/ultimate-guide.md:XXXX"
+swarm_mode: "guide/ultimate-guide.md:XXXX"
+skill_quality_gates: "guide/ultimate-guide.md:XXXX"
+compound_engineering_brainstorm: "guide/ultimate-guide.md:XXXX"
+compound_engineering_source: "https://every.to/p/the-compound-engineering-philosophy"
+compound_engineering_score: "4/5 HIGH VALUE - 2026-03-04"
+```
+
+---
+
+## Sources
+
+| Source | Type | Date |
+|--------|------|------|
+| [every.to compound-engineering article](https://every.to/p/the-compound-engineering-philosophy) | Primary — authored by Kieran Klaassen | 2026 |
+| [EveryInc/every-marketplace](https://github.com/EveryInc/every-marketplace) | Plugin source (agents, commands, skills) | 2026-03-04 |
+| Every.to Cora product | Production context | Ongoing |
+
+---
+
+**End of Evaluation**
--- a/guide/ultimate-guide.md
+++ b/guide/ultimate-guide.md
@ -4454,6 +4454,36 @@ This drops the full `docs/brainstorms/`, `docs/solutions/`, `docs/plans/`, and `

 Installing the plugin is not required to apply the philosophy. The `docs/solutions/` pattern and the loop work with your existing Claude Code setup.

+#### Brainstorm-before-planning
+
+One specific pattern from compound-engineering that works independently: before creating a plan, check if relevant thinking already exists.
+
+The instruction to add to CLAUDE.md or an agent:
+
+```
+Before creating a plan for any feature or problem, check docs/brainstorms/ for existing
+thinking on this topic. If a brainstorm exists, use it as input. If not, create a new
+brainstorm file before writing the plan.
+```
+
+The brainstorm document is not a plan. It explores the problem space: what we know, what we don't know, what we've tried before, what constraints exist. The plan comes after. Most teams skip this step and write plans that repeat reasoning already done in a previous session.
+
+#### The Documentation Hierarchy as Project Memory
+
+The full directory structure the plugin establishes separates four distinct types of documents that most projects conflate:
+
+| Directory | Content | Lifecycle |
+|-----------|---------|-----------|
+| `CLAUDE.md` | Rules and constraints for the AI | Updated rarely, high signal |
+| `docs/brainstorms/` | Problem exploration, open questions | Created before planning, kept as reference |
+| `docs/plans/` | Active implementation plans | Created from brainstorms, archived after completion |
+| `docs/solutions/` | Solved problems with full context | Created after completion, referenced when similar problems appear |
+| `todos/` | Task tracking | Ephemeral, replaced each sprint |
+
+CLAUDE.md contains rules. `docs/solutions/` contains solved problems. `docs/brainstorms/` contains thinking. The separation matters because an AI reading CLAUDE.md expects constraints, not a log of past decisions. When these get mixed, the AI treats old decisions as current rules.
+
+You can adopt this structure incrementally: start with `docs/solutions/` (highest ROI), add `docs/brainstorms/` when plans start repeating prior reasoning, add the rest when you have a repeating workflow.
+
 ### Build for the Model 6 Months Out

 > **"Don't design your workflows around the limitations of today's model. Build for where the technology will be in six months."**
@ -6405,6 +6435,37 @@ Scope-focused agents for comprehensive PR review:
 **Source**: [Pat Cullen's Final Review](https://gist.github.com/patyearone/c9a091b97e756f5ed361f7514d88ef0b)
 **Implementation**: See `/review-pr` advanced section, `examples/agents/code-reviewer.md`, `guide/workflows/iterative-refinement.md` (Review Auto-Correction Loop)

+### Named Perspective Agents
+
+The guide lists "roleplaying expertise personas" as a bad reason to use agents (see §3.x, When NOT to use agents). Named Perspective Agents are a different pattern and should not be confused with it.
+
+**The distinction**:
+
+| Pattern | What it is | Problem |
+|---------|-----------|---------|
+| Persona roleplay (anti-pattern) | "You are a senior backend developer with 10 years of experience" | Generic role, adds nothing over a good prompt |
+| Named Perspective | "Review from DHH's perspective" | Encodes a specific, recognizable set of engineering opinions |
+
+A Named Perspective Agent uses a well-known engineering name as a compressed prompt. Naming an agent "DHH" bundles the following without spelling it out: fat models, thin controllers, REST conventions over configuration, skepticism of premature abstraction, Rails pragmatism. The name is a shortcut to a distinct opinionated style, not a costume.
+
+**When it works**: Only for engineers whose views Claude has been trained on and whose opinions map to a stable, recognizable style. DHH (Rails), Kent Beck (TDD, simplicity), Martin Fowler (refactoring, patterns) are good candidates. Random names are not.
+
+**Example** (from Every.to compound-engineering plugin):
+
+```markdown
+---
+name: dhh-reviewer
+description: Review code from DHH's perspective. Prioritize Rails conventions, fat models, thin controllers, pragmatic REST, and skepticism of unnecessary abstraction.
+allowed-tools: Read, Grep
+---
+```
+
+The agent's value is in surfacing a coherent perspective that might disagree with your default approach, not in simulating a person.
+
+**Caveat**: Named Perspective Agents can drift as Claude's training evolves. Treat the name as a convenient shorthand, not a guarantee that the agent will track a real person's current opinions.
+
+*Source: Every.to compound-engineering plugin (2026)*
+
 ### Parallelization Decision Matrix

 ```
@ -6719,6 +6780,24 @@ skills-ref to-prompt ./my-skill     # Generate <available_skills> XML for agent

 > **Beyond spec validation**: `/audit-agents-skills` extends frontmatter checks with content quality, design patterns, and production readiness scoring. Works on both skills and agents together with weighted criteria (32 points max per file).

+### Skill Quality Gates
+
+Before publishing or committing a skill, run through this content checklist. `/audit-agents-skills` scores frontmatter and structure; this checklist covers the content layer that automated tools miss.
+
+**Checklist (Every.to compound-engineering criteria, adapted)**:
+
+- [ ] **Frontmatter complete**: `name`, `description`, `allowed-tools` all present and accurate
+- [ ] **"When to Apply" section**: explicitly states the triggers and anti-triggers (when NOT to use)
+- [ ] **Methodology is structured**: numbered steps or a clear decision sequence, not free-form paragraphs
+- [ ] **No TODOs or placeholders**: every section is complete and actionable
+- [ ] **allowed-tools scoped to minimum**: if the skill only reads files, don't grant Bash; if it searches, don't grant Edit
+- [ ] **Output format documented**: what does Claude produce? Example or template included
+- [ ] **No AskUserQuestion for cross-platform skills**: skills invoked by other agents should not block on interactive prompts
+- [ ] **Single responsibility**: one skill, one domain — not a catch-all that dispatches to sub-skills
+- [ ] **Description is a trigger sentence**: the `description` field should tell Claude when to activate this skill, not what it does internally
+
+A skill that passes these 9 gates is ready for production use or sharing via the agentskills.io registry.
+
 ## 5.3 Skill Template

 ```markdown
@ -19642,6 +19721,32 @@ Complex coordination needed? ──YES──> Agent Teams ✓
                            ──NO──> Single agent
 ```

+### Swarm vs Sequential Coordination
+
+Two distinct coordination patterns exist for multi-agent review, and the choice matters:
+
+| Dimension | Sequential Specialists | Swarm Mode |
+|-----------|----------------------|------------|
+| **Structure** | Predefined lead + members | Ad-hoc, no hierarchy |
+| **Coordination** | Lead assigns tasks, synthesizes | Each reviewer works independently |
+| **Leadership** | Team lead orchestrates | Human synthesizes findings |
+| **Task assignment** | Lead delegates to specific agents | All relevant agents get the same input |
+| **Best for** | Tasks with dependencies between reviewers | Independent review, final pre-merge pass |
+| **When to use** | Complex workflows, state needs sharing | PR review, unfamiliar codebase, thoroughness |
+
+**Swarm Mode in practice** (Every.to compound-engineering pattern):
+
+Launch all relevant specialist reviewers in parallel against the same diff or PR, with no coordination between them. Each produces independent findings. You read all findings and decide what to act on.
+
+```bash
+# Swarm: all reviewers see the same input, report independently
+/workflows:review --swarm   # Every.to compound-engineering command
+```
+
+This is distinct from Agent Teams: there is no persistent team structure, no shared context between agents, no lead synthesizing in real time. It is faster to set up and appropriate when thoroughness matters more than coordination.
+
+**Rule of thumb**: Use Agent Teams for workflows with sequential dependencies (agent A's output feeds agent B). Use Swarm when each reviewer can work from the same starting point and you want maximum coverage with minimum setup overhead.
+
 ### Practitioner Testimonial

 **Paul Rayner** (CEO Virtual Genius, EventStorming Handbook author):