# Coordinator Pattern

> Decompose complex tasks into parallel sub-agent work using the Research → Synthesis → Implementation → Verification pattern. Inspired by Claude Code's Coordinator Mode. Use when a task is too large for a single agent pass, needs multiple perspectives, or benefits from parallel execution. Works with any agent that can spawn sub-tasks.

- **Type:** Skill
- **Install:** `agentstack add skill-victorgjn-agent-skills-coordinator-pattern`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [VictorGjn](https://agentstack.voostack.com/s/victorgjn)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [VictorGjn](https://github.com/VictorGjn)
- **Source:** https://github.com/VictorGjn/agent-skills/tree/main/coordinator-pattern

## Install

```sh
agentstack add skill-victorgjn-agent-skills-coordinator-pattern
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Coordinator Pattern

Decompose complex tasks into parallel sub-agent work — inspired by Claude Code's Coordinator Mode.

## Concept

When a task is too big for one agent pass, break it into phases. The coordinator (you, the main agent) never does the grunt work directly. You decompose, delegate, synthesize, and verify.

The pattern: **Research → Synthesis → Implementation → Verification**

## When to Use

- Task touches **3+ files or areas** that can be investigated independently
- Work can be **parallelized** (independent changes, research threads, analysis axes)
- Task needs **verification** — implementation should be checked by a fresh agent with no implementation bias
- You need **multiple perspectives** (technical, product, user, security)

## When NOT to Use

- Single-file edits or simple lookups
- Tasks that are strictly sequential (each step depends on the previous)
- Tasks where the user wants to stay hands-on at every step

## The 4 Phases

### Phase 1: Research (Parallel Workers)

Spawn workers to investigate the problem space. Each worker gets a **focused, self-contained mandate**. Workers have no shared state — each prompt must contain all context needed.

```
Workers (launched concurrently):
  Worker A: "Find all files related to authentication. List them, summarize the 
             patterns used, note any inconsistencies. Write findings to 
             /tmp/research-auth.md"
  
  Worker B: "Map the database schema for users and sessions. List all migrations 
             in order. Note any pending schema changes. Write findings to 
             /tmp/research-schema.md"
  
  Worker C: "Search for all TODO/FIXME comments related to auth or sessions. 
             Check existing test coverage for auth flows. Write findings to 
             /tmp/research-tests.md"
```

**Critical rule**: Never say "based on your findings." Each worker prompt specifies **exactly what to find and where to write it**.

**How to spawn** depends on your agent:
- **Claude Code**: Use the `Agent` tool (formerly `Task`) — it spawns a sub-agent with its own context
- **Any CLI agent with bash**: Run parallel background commands
- **Sauna**: Use the `subagent_batch` skill
- **Custom systems**: Any async task queue works

### Phase 2: Synthesis (Coordinator Only)

**You** (the coordinator) read all worker findings. Don't delegate this.

```
1. Read all research outputs (/tmp/research-*.md)
2. Identify conflicts between workers' findings
3. Identify gaps — what was missed?
4. Make decisions where workers found ambiguity
5. Write a concrete implementation spec per task
```

The spec for each implementation worker should contain:
- **Exact files** to create or modify
- **Exact changes** to make (not vague instructions)
- **Constraints** to follow (patterns, style, dependencies)
- **Definition of done** — how the worker knows it's finished

**Anti-pattern**: "Implement auth improvements based on the research." 
**Correct**: "In `src/auth/middleware.ts`, add rate limiting: max 5 attempts per IP per minute using the existing `redis` client. Add tests in `tests/auth/rate-limit.test.ts` covering: success, rate-limited, and reset-after-window cases."

### Phase 3: Implementation (Parallel Workers)

Spawn workers with the precise specs from synthesis. Each worker gets:

```
Worker A spec:
  FILES TO MODIFY:
    - src/auth/middleware.ts — add rateLimitMiddleware() function
    - src/auth/config.ts — add RATE_LIMIT_WINDOW and MAX_ATTEMPTS constants
  
  EXACT CHANGES:
    1. Add function rateLimitMiddleware(req, res, next) that checks Redis 
       for attempt count by IP, returns 429 if exceeded
    2. Export constants: RATE_LIMIT_WINDOW = 60, MAX_ATTEMPTS = 5
  
  CONSTRAINTS:
    - Use existing Redis client from src/lib/redis.ts
    - Follow error handling pattern from src/auth/session.ts
    - Add JSDoc comments
  
  DONE WHEN:
    - Functions exist and are exported
    - No TypeScript errors
    - Write summary to /tmp/impl-auth.md
```

### Phase 4: Verification (Fresh Workers)

Spawn **new** workers that didn't participate in implementation. They check the work with no implementation bias.

```
Verification worker spec:
  CHECK:
    1. Read the implementation spec (paste it in full)
    2. Read each modified file
    3. Verify every spec point was correctly implemented
    4. Run: npm test (or equivalent)
    5. Check for regressions in related files
    6. Check for security issues in new code
  
  REPORT FORMAT:
    For each spec point: PASS / FAIL + evidence
    Any issues found with suggested fixes
    Test results summary
    Write to /tmp/verify-result.md
```

## Communication Between Phases

Workers can't talk to each other. The coordinator is the only entity that reads all outputs and writes all inputs. Use the filesystem as the shared scratchpad:

```
/tmp/coordinator/           (or any temp directory)
  plan.md                   ← Coordinator's synthesis
  research-worker-a.md      ← Worker A findings  
  research-worker-b.md      ← Worker B findings
  impl-worker-a.md          ← Worker A implementation log
  impl-worker-b.md          ← Worker B implementation log
  verify-result.md          ← Verification report
```

In a real project, you might use `.claude/tasks/` or any convention that works.

## Rules (from Claude Code's Coordinator)

1. **Parallelize aggressively** — launch independent workers concurrently, don't serialize what can run simultaneously
2. **Workers are isolated** — no shared state, no references to other workers' context
3. **Coordinator reads everything** — only the coordinator has the full picture
4. **Be explicit in specs** — workers should never need to guess or infer
5. **Verify independently** — verification workers must not trust implementation workers' self-reports
6. **Ban lazy delegation** — never say "implement based on research." Read the research. Specify exactly what to do.

## Scaling Guide

| Task Complexity | Research Workers | Impl Workers | Verify Workers |
|:-:|:-:|:-:|:-:|
| Small (1-3 files) | 1-2 | 1 | 1 |
| Medium (5-15 files) | 2-3 | 2-3 | 1-2 |
| Large (15+ files) | 3-5 | 3-5 | 2-3 |

**Max**: 5 workers per phase. Beyond that, coordination overhead exceeds the gains.

## Example: Add API Rate Limiting

```
User: "Add rate limiting to all API endpoints"

Phase 1 — Research (3 workers, parallel):
  → Worker A: List all API routes, their middleware chains, current auth
  → Worker B: Check existing rate limiting code, Redis setup, config patterns
  → Worker C: Research rate limiting best practices for this framework

Phase 2 — Synthesis (coordinator):
  → Read all findings
  → Decide: sliding-window via Redis, per-endpoint config, 3 tiers (public/auth/admin)
  → Write spec: Worker A gets middleware + config, Worker B gets tests + docs

Phase 3 — Implementation (2 workers, parallel):
  → Worker A: Rate limit middleware + Redis integration + per-route config
  → Worker B: Test suite + API docs update + migration script

Phase 4 — Verification (1 worker):
  → Run tests, check all routes have rate limiting, verify Redis cleanup
  → Load test with curl to confirm 429 behavior
```

## Running It

### Claude Code

```
You are a coordinator. Decompose this task using the coordinator-pattern:

[paste task]

Follow the 4-phase pattern: Research → Synthesis → Implementation → Verification.
Use the Agent tool to spawn workers. Write coordination artifacts to .claude/tasks/.
```

### Any Agent with File Access

The pattern works with any agent that can:
1. Read and write files (for the scratchpad)
2. Spawn sub-tasks or run parallel commands
3. Execute verification steps (run tests, check types)

The skill is the **process**, not the tooling.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [VictorGjn](https://github.com/VictorGjn)
- **Source:** [VictorGjn/agent-skills](https://github.com/VictorGjn/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-victorgjn-agent-skills-coordinator-pattern
- Seller: https://agentstack.voostack.com/s/victorgjn
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.