# Cascade Orchestration

> Reusable agent team cascade patterns — parallel dispatch, sequential pipelines, fan-out/fan-in, and cross-project propagation

- Skill: `aemerson-commits/cascade-orchestration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aemerson-commits/cascade-orchestration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aemerson-commits/cascade-orchestration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: aemerson-commits (https://skillmd.com/u/aemerson-commits)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aemerson-commits/cascade-orchestration

---


# Cascade Orchestration Patterns

Reusable patterns for orchestrating agent teams across projects. All agents use model: "opus" with max effort.

## Pattern 1: Fan-Out / Fan-In

Use when N independent tasks produce results that need synthesis.

```
Main Agent
├── dispatch N agents in parallel (fan-out)
│   ├── Agent 1 → result 1
│   ├── Agent 2 → result 2
│   └── Agent N → result N
└── synthesize all results (fan-in)
```

**Used by:** /audit-components, /env-audit, /pre-merge-review, /skill-audit

**Implementation:**
- Each agent gets a focused scope (one project, one domain, one file set)
- Agents use `isolation: "worktree"` when modifying code
- Main agent waits for all agents, then merges results
- If any agent fails, report partial results + failure reason

## Pattern 2: Sequential Pipeline

Use when each stage depends on the previous stage's output.

```
Stage 1 (parallel research agents)
    ↓ results
Stage 2 (parallel implementation agents)
    ↓ code changes
Stage 3 (parallel review agents)
    ↓ findings
Stage 4 (synthesis + report)
```

**Used by:** /research-gate → /write-plan → build → /review-impl

**Implementation:**
- Each stage can internally use Fan-Out/Fan-In
- Stage transitions are explicit — main agent gates progression
- Context from earlier stages passed to later stages via structured summaries
- Never skip stages; if a stage produces no issues, note "clean" and proceed

## Pattern 3: Per-Project Propagation

Use when a shared change must be verified/applied across all projects.

```
Trigger: shared/ file changed
├── Agent: Project A Verifier — check imports, build, test
├── Agent: Project B Verifier — check imports, build, test
├── Agent: Project C Verifier — check imports, build, test
└── Agent: Project D Verifier — check imports, build, test
```

**Used by:** /audit-components (after shared util changes), /deploy-all

**Implementation:**
- Each agent gets the same verification checklist
- Agents run in their project's directory
- Results compiled into per-project pass/fail matrix
- If ANY project fails, block the operation

## Pattern 4: Cascading Sub-Teams

Use when a domain agent needs deeper analysis than one agent can provide.

```
Domain Agent (e.g., Security Review)
├── Sub-agent: Profile A (unauthenticated attacker)
├── Sub-agent: Profile B (compromised user)
└── Sub-agent: Profile C (compromised admin)
```

**Used by:** /pre-merge-review (security, performance, UX sub-agents)

**Implementation:**
- Parent agent defines sub-agent scope and shares relevant context
- Sub-agents report to parent, not directly to main
- Parent synthesizes sub-agent results before reporting to main
- Max depth: 2 levels (main → domain → sub-agent). Never go deeper.

## Pattern 5: Conditional Dispatch

Use when some agents are only needed based on what changed.

```
Main Agent reads git diff
├── If project-a/ changed → dispatch Project A agents
├── If shared/ changed → dispatch ALL project agents
├── If workers/ changed → dispatch Worker agents
└── If backend/ changed → dispatch Backend agent
```

**Used by:** /deploy-all (selective), /session-notes (conditional steps)

**Implementation:**
- Main agent determines scope from git diff or user input
- Only dispatch agents for affected areas
- Skip unnecessary agents to save context and cost
- Log which agents were dispatched and which were skipped

## Seed Agents With Known Hub Paths

When fanning out audit/research agents for a cross-cutting concern (auth, caching, email, shared utilities), list the convergence files explicitly in EVERY agent's prompt instead of letting each agent rediscover them independently via grep. If your codebase has a `shared/` or `common/` layer imported by many consumers (CORS/auth helpers, rate limiting, alert/notification plumbing, shared UI utilities), name those specific files up front.

Each hub file is imported by many consumers. An agent that doesn't already know that spends its first pass rediscovering the hub via grep; a parallel sibling agent independently burns the same effort rediscovering it a second time. Seeding the list up front turns N redundant discovery passes into zero — cheap to do (one line per file) and it compounds with agent count.

## Multi-Project Deploy-Time Smoke Pattern

After deploying multiple projects, capture screenshots for a permanent audit trail of "what shipped today":

1. Write a Node smoke script at `test-results/smoke-YYYY-MM-DD/run-smoke-p1.mjs` (keep in a dated directory for audit history).
2. Inject authentication credentials via request headers or session cookies on the browser context.
3. Navigate each deployed URL, wait for hydration, take stage-named screenshots:
   - `app-a-01-initial.png`, `app-a-02-main-view.png`
   - `app-b-01-initial.png`, `app-b-02-loaded.png`
4. Execute: `node test-results/smoke-YYYY-MM-DD/run-smoke-p1.mjs`
5. Review each PNG visually. Screenshot review consistently surfaces issues (missing data, broken layouts, wrong colors) that HTTP 200 and unit tests miss entirely.
6. Iterate: write `run-smoke-p2.mjs` for deeper views (modals, admin settings, theme toggle), `run-smoke-p3.mjs` for admin-only areas.

The screenshot directory becomes the audit trail for the deploy. Archive it alongside the deploy commit SHA.

## Anti-Patterns

| Anti-Pattern | Why It's Bad | Do This Instead |
|-------------|-------------|-----------------|
| Dispatching without an explicit `model:` | Unpinned agents inherit the main-loop model (often the most expensive available); subagents can account for the majority of token spend | Every `Agent(...)` / workflow `agent()` call carries `model:` — use your cheapest capable model by default, escalate to a more powerful model only for critical review/security/migration gates (see `/model-selection`) |
| Agent spawns agent spawns agent (3+ deep) | Context loss, coordination overhead | Max 2 levels deep |
| All agents share one worktree | Race conditions on file writes | Each code-modifying agent gets own worktree |
| Agent does research + implementation | Scope creep, context bloat | Separate research agents from implementation agents |
| Sequential when parallel is possible | Wastes time | If tasks have no data dependency, parallelize |
| Fan-out when stages actually depend on each other | Redundant context re-fed to every agent, no real concurrency gained — a later "parallel" agent just re-derives what an earlier one already produced | Check for a real data dependency chain before splitting into parallel agents; collapse to a sequential pipeline (or one agent) if a later stage reads what an earlier stage wrote |
| Parallelizing tiny tasks | Agent overhead > task time | Only parallelize tasks that take 30s+ each |

## Skill Integration Map

| Workflow | Pattern | Agents |
|----------|---------|--------|
| `/start-day` | Fan-Out/Fan-In | 4 parallel: git pull, index, session review, memory check |
| `/research-gate` | Fan-Out/Fan-In | 4-5 parallel research agents → synthesis |
| `/audit-components` | Per-Project Propagation | N project auditors + cross-project auditors |
| `/env-audit` | Fan-Out/Fan-In | N context scanners → cross-reference synthesis |
| `/review-impl` | Sequential Pipeline | 3 context agents → 3-7 reviewers → synthesis |
| `/pre-merge-review` | Cascading Sub-Teams | 5 domains x 1-3 sub-agents each (up to 12 total) |
| `/deploy-all` | Per-Project Propagation + Conditional | N Pages agents, then Worker agents |
| `/session-notes` | Sequential Pipeline (1 agent) | ONE agent runs stages in order (vault note → docs → memory) instead of N parallel agents — the stages read each other's output, so parallelizing them re-fed overlapping context without buying real concurrency; deterministic bookkeeping steps collapse into a single script call |
| `/debug-collaborate` | Fan-Out/Fan-In | 3-4 hypothesis investigators → synthesis |
| `/write-plan` | Sequential Pipeline | Research → decompose → task list with file paths |
| `/skill-audit` | Fan-Out/Fan-In | 4 parallel checks → compliance check → report |
| `/persistent-issue` | Sequential Pipeline + Conditional | Triage → dispatch Team A-E → auto-escalate (cascade mode) |
| `/deep-root-cause` | Fan-Out/Fan-In | 3 agents: Reproducer, Data Flow Tracer, Assumption Auditor |
| `/full-stack-trace` | Sequential Pipeline | 4 agents: Frontend → API → Backend → Infrastructure |
| `/isolation-test` | Fan-Out/Fan-In + Conditional | 3 agents: Component Isolator, Data Minimizer, Environment Comparator |
| `/temporal-forensics` | Fan-Out/Fan-In | 3 agents: Race Condition Hunter, Stale State Detective, Timing Profiler |
| `/regression-bisect` | Sequential Pipeline | 3 agents: Git Bisector, Side Effect Analyzer, Rollback Verifier |
| `/full-stack-build` | Sequential Pipeline + Fan-Out/Fan-In | 2 designers → 2 builders (worktree) → 4 verifiers |
| `/worker-build` | Fan-Out/Fan-In | 3 builders (worktree) → 2 verifiers |
| `/propagate-feature` | Sequential Pipeline + Fan-Out/Fan-In | 2 differs → adapt plan → 1 propagator (worktree) → 2 verifiers |
| `/data-reconciliation` | Fan-Out/Fan-In | 4 layer samplers → reconciliation matrix |
| `/grill-me` | Sequential (conversation) | Intent interrogation → Intent Summary for /research-gate |