Cascade Orchestration Patterns

Reusable patterns for orchestrating agent teams across projects. Every dispatch carries an explicit model: — your cheapest capable model is the default and the floor; escalate only for critical review, security audits, architecture and migration gates (see /model-selection). Route effort per task, never max it globally.

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

Skill Integration Map