frontend/.claude/skills/agent-orchestrator/SKILL.md

name, description

name

description

agent-orchestrator

Breaks down large, multi-step software tasks into structured sub-agents on the Claude Code CLI using the Task tool. Use this skill whenever the user describes a complex project or feature that has multiple components - e.g., "build a login API with JWT and unit tests", "set up a CI/CD pipeline with Docker and GitHub Actions", "create a full-stack todo app with auth, REST API, and frontend". Trigger this skill when the task clearly has more than one distinct sub-system, layer, or concern that could be worked on in parallel or in sequence. DO NOT trigger for simple, single-step tasks like "write a function to reverse a string" or "fix this bug".

Agent Orchestrator

A skill for decomposing large engineering tasks into parallel and sequential sub-agents on Claude Code CLI using the Task tool.

When to Use

Trigger when the user's task has multiple distinct components - for example:

• "Build a REST API with authentication, rate limiting, and unit tests"
• "Set up a monorepo with shared packages, CI pipeline, and deployment configs"
• "Create a data pipeline: ingest transform store visualize"

Do not trigger for single-step tasks (e.g., "rename this variable", "add a README").

---

Prompt Template

Copy the block below and paste it into your Agent Code CLI session. Replace the placeholder in the TASK variable with your actual task description.

---

You are a senior engineering orchestrator operating inside the Agent Code CLI.

TASK: "Build a login API with JWT and unit tests"

---

Your job is to analyze this task, decompose it into well-scoped sub-tasks, identify dependencies between them, and execute them using the Task tool.

Follow these steps exactly:

---

## STEP 1 - Guard: Is this task complex enough?

If the task can be completed in a single step by a single agent (e.g., "rename a variable", "write one function"), respond with:
> "This task is simple enough to handle directly - no orchestration needed."
Then complete it yourself. Stop here.

Otherwise, continue.

---

## STEP 2 - Decompose the task into sub-tasks

Analyze the TASK string. Break it into a flat list of concrete, independently scoped sub-tasks. Each sub-task must:
- Have a clear, specific goal
- Be executable by a single focused agent
- Produce a concrete output (file, module, config, test suite, etc.)

Output the list in this format:

Sub-tasks:
  [T1] <sub-task title> - <one-sentence description>
  [T2] <sub-task title> - <one-sentence description>
  [T3] ...

---

## STEP 3 - Identify dependencies and execution mode

For each sub-task, decide whether it can run in parallel with others, or must run after a specific predecessor.

Label each sub-task as one of:
  [PARALLEL]               - no dependencies, can start immediately
  [SEQUENTIAL - after Tx]  - must run only after sub-task Tx completes

Rules:
- If a sub-task depends on an artifact produced by another (a file, schema, interface, module), mark it SEQUENTIAL.
- If two sub-tasks are fully independent (different files, no shared state), mark both PARALLEL.
- Do not start any SEQUENTIAL sub-task until its prerequisite is confirmed complete.

Output the dependency plan in this format:

Dependency Plan:
  [T1] <title>    [PARALLEL]
  [T2] <title>    [PARALLEL]
  [T3] <title>    [SEQUENTIAL - after T1]
  [T4] <title>    [SEQUENTIAL - after T2, T3]

---

## STEP 4 - Confirm plan before execution

Print the full decomposition and dependency plan to the user.
Then print:
> "Starting execution. Spawning parallel sub-agents now..."

Do not skip this confirmation step.

---

## STEP 5 - Execute using the Task tool

Use the **Task tool** to spawn sub-agents. Follow this protocol:

### 5a. Spawn all [PARALLEL] sub-tasks simultaneously
- Call the Task tool for each PARALLEL sub-task at the same time (do not wait for one to finish before spawning the next).
- Each Task call must include a self-contained prompt describing exactly what to build, where to put files, and what the expected output is.

### 5b. Monitor and gate SEQUENTIAL sub-tasks
- Wait for each prerequisite Task to complete before spawning its dependent.
- Once a prerequisite completes, immediately spawn the next Task.

### 5c. Task prompt format
Each task spawned via the Task tool must include:

  - Role: "You are a focused sub-agent. Complete exactly this sub-task and nothing else."
  - Sub-task goal (from Step 2)
  - Output location (file path or module name)
  - Any relevant interfaces or contracts from predecessor tasks (if SEQUENTIAL)
  - Instruction to report back: "When done, summarize what you built and list output files."

---

## STEP 6 - Synthesize and report

After all Tasks complete:
1. Collect each sub-agent's summary.
2. Verify that all expected outputs exist.
3. Report to the user:
   - What was built
   - File/module structure
   - Any issues or gaps found
   - Suggested next steps (e.g., "Run `npm test` to verify", "Review the generated OpenAPI spec")

---

Begin now with STEP 1.

---

Tips for Customizing the Template

• Replace the TASK value with your actual task string. Keep it on one line, in quotes.
• Add context if needed: Append lines after TASK: like STACK: "Node.js, PostgreSQL, Jest" or CONSTRAINTS: "Use ESM modules only" - the orchestrator will incorporate them.
• For monorepos or specific file layouts: Add a STRUCTURE: hint, e.g.:

  STRUCTURE: "src/api/, src/auth/, src/tests/, docker-compose.yml"
  

• To limit parallelism (e.g., on resource-constrained machines): Add MAX_PARALLEL_AGENTS: 2 after the TASK line.

---

Example Usage

Input task:

"Build a login API with JWT authentication and unit tests"

Expected orchestrator output (before execution):

Sub-tasks:
  [T1] Project scaffold - Initialize Node.js project, folder structure, and dependencies
  [T2] Database schema - Define User model and migration for PostgreSQL
  [T3] Auth service - Implement JWT sign/verify logic and password hashing
  [T4] Login route - Build POST /auth/login endpoint with validation
  [T5] Middleware - Create JWT auth middleware for protected routes
  [T6] Unit tests - Write Jest tests for auth service and login route

Dependency Plan:
  [T1] Project scaffold      [PARALLEL]
  [T2] Database schema       [PARALLEL]
  [T3] Auth service          [SEQUENTIAL - after T1]
  [T4] Login route           [SEQUENTIAL - after T3]
  [T5] Middleware            [SEQUENTIAL - after T3]
  [T6] Unit tests            [SEQUENTIAL - after T4, T5]

Starting execution. Spawning parallel sub-agents now...

T1 and T2 spawn immediately. T3 spawns once T1 completes. T4 and T5 spawn once T3 completes. T6 spawns last.

---

Notes

• This skill requires Agent Code CLI with the Task tool enabled.
• Each spawned sub-agent has no memory of the others - pass all needed context explicitly in the Task prompt.
• For very large tasks (10+ sub-tasks), consider breaking the orchestration into phases and applying this skill recursively per phase.