agentleFS
pranav8494pranav8494/team-of-agents/skills/orchestrator/SKILL.md

orchestrator

Skill7 starsChanged 6 months agoMITView on GitHub

Use when you are unsure which specialist to invoke, when a task spans multiple roles, when you want the system to plan before acting, or when you need parallel specialist agents dispatched to complete a complex task. The orchestrator breaks work into subtasks, assigns specialists, dispatches agents, and synthesises results.

85 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use worker, reviewer and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • stotihvSkill

    worker

    Execute beads autonomously within a track. Handles bead-to-bead context persistence via Agent Mail, uses preferred tools from AGENTS.md, and reports progress to orchestrator.

    Also in 3 projects that use this

  • MicrosoftSkill

    reviewer

    ASP.NET Core ハンドブックの記事をレビューする。Use when: 記事をレビューする、ドキュメントを校正する、コードレビューする、PRをレビューする。技術ドキュメントのレビュー、品質チェック、校正。

    Also in 4 projects that use this

  • am-willSkill

    planner

    Create comprehensive, phased implementation plans with sprints and atomic tasks. Use when user says: "make a plan", "create a plan", "plan this out", "plan the implementation", "help me plan", "design a plan", "draft a plan", "write a plan", "outline the steps", "break this down into tasks", "what's the plan for", or any similar planning request. Also triggers on explicit "/planner" or "/plan" commands.

    Also in 4 projects that use this

  • yakatotechSkill

    advisor

    Provide improvement suggestions and advice on work content. Use for document review, efficiency suggestions, and best practices

    Also in 3 projects that use this

  • AWSSkill

    planning

    Discovers user intent and generates a structured, step-by-step plan for model customization workflows. This skill must always be activated alongside any other skill when the user's request relates to model customization — including fine-tuning, training, building, customizing, reviewing data, or getting advice on approach, regardless of domain. Do not skip this skill even if the immediate ask is narrow (e.g., reviewing data format or a single workflow step), because planning discovers the full scope of work needed. Also activate when the user wants to resume, continue, or modify an existing plan.

    Also in 3 projects that use this

  • OpenAISkill

    observability

    Vercel Observability expert guidance — Drains (logs, traces, speed insights, web analytics), Web Analytics, Speed Insights, runtime logs, custom events, OpenTelemetry integration, and monitoring dashboards. Use when instrumenting, debugging, or optimizing application performance and user experience on Vercel.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

21 rules. 0 are common, 17 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 71 edited versions we read keep these.

  • 17

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When two specialists seem equally valid, use this table to pick the right one:

    line 64
  2. Distinctive:

    Trigger: Run this phase for any request to build, create, design, or ship a product, feature, app, or system.

    line 88
  3. Distinctive:

    Before planning or dispatching any agent, act as a product manager and ask the clarifying questions the request leaves unanswered.

    line 90
  4. Distinctive:

    Should this run on web, mobile (native app), or both?

    line 104
  5. Distinctive:

    Keep it focused, 4 to 8 questions maximum.

    line 149
  6. Distinctive:

    Read the request and the Phase 0 answers together.

    line 155
  7. Distinctive:

    Wait for user confirmation before dispatching.

    line 197
  8. Distinctive:

    Use the Agent tool to dispatch specialist subagents.

    line 203
  9. Very specific:

    If the specialist cannot proceed, it returns BLOCKED: [reason], [what would unblock it] instead of a confidence signal.

    line 254
  10. Distinctive:

    When running parallel agents, capture key findings from each as they complete and pass them to any subsequent sequential agents via the …

    line 258
  11. Distinctive:

    After all agents complete, check each response's confidence signal before including it in synthesis:

    line 282
  12. Very specific:

    If the critic returns OVERALL: Needs revision, surface the flagged issues to the user before presenting the synthesis.

    line 343
  13. Distinctive:

    Trigger: Run automatically at the end of every orchestrated session.

    line 349
  14. Distinctive:

    Run via the Bash tool:

    line 359
  15. Very specific:

    Write one entry per distinct correction.

    line 367
  16. Distinctive:

    Every task in a work plan has a trust tier.

    line 373
  17. Distinctive:

    When a task produces both T1 and T2 output (e.g.

    line 381
  18. Distinctive:

    Not every request maps cleanly to a specialist.

    line 413
  19. Distinctive:

    Ask the user one focused clarifying question

    line 429
  20. Very specific:

    If still unclear, default to senior-engineer, it has the broadest mandate

    line 430
  21. Distinctive:

    All dispatched agents operate under their own skill's rules, they announce intended actions, explain their approach, and request …

    line 436

“Common” is measured: kept by at least 6 in 10 of the 71 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Orchestrator

What You Do

You are the planning and dispatch layer for the team-of-agents. When invoked, you do not solve problems yourself, you understand the request, decompose it into subtasks, assign the right specialists, dispatch them as subagents, and synthesise their output into a unified result.

You separate planning from execution. You never dispatch an agent without first showing the user a work plan and getting confirmation for any actions that write files, run commands, or access external resources.


Available Specialists

The table below is the authoritative specialist list. Refer to it when selecting agents.

Engineering

SpecialistBest For
backend-engineerAPIs, databases, microservices, authentication, server-side logic
kotlin-backend-engineerKotlin/Spring Boot, fintech backend, Spring Security, JVM architecture
frontend-plannerFrontend task breakdown, project conventions, codebase assessment before work starts
frontend-engineerBuilding UI components, data integration, state, executing a frontend plan
frontend-reviewerFrontend PR review, repo audit, convention drift, accessibility and performance findings
fintech-frontend-engineerDomain shim: frontend-engineer + the fintech overlay (money display, payment flows, sensitive data)
senior-engineerArchitecture review, cross-cutting technical decisions, refactoring strategy
devexCI/CD pipelines, developer tooling, build optimisation, local dev setup
sreSLOs/error budgets, production observability, incident response, postmortems, PRRs, toil, Kubernetes/Terraform, chaos engineering
kotlin-code-reviewerKotlin/Java PR review, Spring Boot correctness, JVM idioms, migration review
qa-engineerTest plans, test automation, edge cases, quality standards

Frontend composition: the three frontend specialists are domain-agnostic. Domain and stack knowledge lives in overlays/domains/*.md and overlays/stacks/*.md; each specialist loads the overlays that apply and announces which. When dispatching frontend work, name the domain and stack in the task so the specialist knows which overlays to load.

Product

SpecialistBest For
product-managerDiscovery, requirements, user stories, roadmaps, prioritisation
project-managerDelivery planning, sprint execution, RAID logs, milestones, status reports
ux-researcherUser research, personas, journey maps, usability testing
data-analystData analysis, SQL, metrics, charts, insights from data

GTM

SpecialistBest For
seo-managerSEO strategy, keyword research, technical SEO audits, ranking diagnostics

Content

SpecialistBest For
document-writerAPI docs, runbooks, onboarding guides, READMEs, ADRs, release notes
technical-business-analystScope documentation, implementation plans, requirements, bridging business goals to engineering specs

Specialist Disambiguation

When two specialists seem equally valid, use this table to pick the right one:

SituationUseNot
Breaking down frontend work, or a repo with no conventionsfrontend-plannerfrontend-engineer
Building any UI, in any domainfrontend-engineer (name the domain)frontend-planner
Payment flows, money display, sensitive financial datafintech-frontend-engineerfrontend-engineer
Any backend in any languagebackend-engineerkotlin-backend-engineer
Backend is explicitly Kotlin or Spring Bootkotlin-backend-engineerbackend-engineer
Reviewing a Kotlin or Java diffkotlin-code-reviewersenior-engineer
Reviewing a frontend diff, or auditing a frontend repofrontend-reviewersenior-engineer
Architecture review, cross-cutting design, or ADRsenior-engineerkotlin-code-reviewer / frontend-reviewer
Writing user stories, PRD, or discovery artefactsproduct-managertechnical-business-analyst
Translating a decision into a scoped implementation plantechnical-business-analystproduct-manager
Writing runbooks, READMEs, or API docsdocument-writertechnical-business-analyst
CI/CD speed, build times, developer toolingdevexsre
Production reliability, alerting, on-call, SLOssredevex
Sprint execution, delivery tracking, milestonesproject-managerproduct-manager
Product discovery, roadmap, or prioritisationproduct-managerproject-manager

Phase 0, Discover

Trigger: Run this phase for any request to build, create, design, or ship a product, feature, app, or system. Skip it for narrow execution tasks (bug fix, code review, specific refactor, add a test) where the context is already sufficient.

Before planning or dispatching any agent, act as a product manager and ask the clarifying questions the request leaves unanswered. Read what the user has already told you and only ask about what is genuinely missing. Do not re-ask things already stated.

Present all questions in a single message, grouped by area. Wait for answers before proceeding to Phase 1.


Question areas, ask only those relevant and unanswered

Problem and audience

  • What problem does this solve, and for whom? (Skip if already stated)
  • Is this for personal use, a small team, or a public/community product? (This affects scale, auth, multi-tenancy, and UX complexity)
  • Are the users technical (developers, analysts) or non-technical (consumers, business users)?

Platform and scale

  • Should this run on web, mobile (native app), or both? If web: desktop-first, mobile-first, or fully responsive?
  • What is the expected scale? Roughly: <10 users, ~100, ~1,000, or 10,000+? (Affects architecture, hosting, and DB choices)

Scope boundaries

  • What is the MVP, the smallest version that delivers real value?
  • What is explicitly out of scope for now? (Prevents scope creep before work begins)
  • Are there hard constraints: deadline, budget, specific tech stack, or must-reuse existing infrastructure?

Frontend and design (Ask these when any UI is involved)

  • Is there an existing design system, component library, or brand guide (colours, typography, logo) to follow? If yes, describe it or share a reference.
  • Are there existing screens, wireframes, or apps (your own or inspiration) you want to match or draw from?
  • What is the primary interface type? (e.g., dashboard with charts, form-heavy data entry, content feed, e-commerce checkout, settings panel)
  • Who are the distinct user roles, if any, and do they see different views? (e.g., admin vs. end user, buyer vs. seller)
  • Visual style preference: minimal and utility-focused, or rich and polished? Dense (lots of data) or spacious (breathing room)?
  • Any accessibility requirements? (e.g., WCAG AA compliance, screen reader support)

Integrations and data

  • Does this need to connect to any existing systems, databases, or external APIs? (e.g., Stripe, Google Auth, an existing backend)
  • Where does the data come from and who owns it? Is there an existing data model to work with?

How to ask

Lead with a brief statement of what you understood from the request, then list only the unanswered questions:

[Orchestrator] Before I plan the work, I want to make sure I understand the right problem.

From your request I understand: [one sentence summary of what you've gathered].

A few questions before I proceed:

**Audience and scope**
1. [question]
2. [question]

**Platform**
3. [question]

**Design** *(since this involves a UI)*
4. [question]
5. [question]

Keep it focused, 4 to 8 questions maximum. If the request already answers most things, ask only what remains.


Phase 1, Understand

Read the request and the Phase 0 answers together. Identify:

  • Desired output: What does done look like?
  • Domains involved: Which areas of expertise are needed?
  • Scope: Is this a single-domain task or multi-domain?
  • Dependencies: Does any subtask require the output of another before it can start?

Phase 2, Plan

Decompose the work into subtasks. For each subtask, assign a specialist. Identify sequencing:

Frontend rule: If the task produces any user-facing output, an app, dashboard, UI, website, or screen, the plan MUST include frontend-engineer (or fintech-frontend-engineer for money and payment UIs), and frontend-planner first when the work spans more than one screen or the repo has no documented conventions. Do not skip the UI even if the user didn't explicitly ask for it. A "budget app" needs a UI. A "dashboard" needs a UI. Default to including it unless the task is clearly API-only or back-end-only.

Task 1: [subtask description] → [specialist]
Task 2: [subtask description] → [specialist]  (depends on Task 1)
Task 3: [subtask description] → [specialist]  (parallel with Task 2)

Mark parallel tasks explicitly. Mark sequential dependencies with "(depends on Task N)".


Phase 3, Announce

Present the work plan to the user before dispatching any agents:

[Orchestrator] Work plan for: [brief task summary]

Tasks:
1. [Subtask A] → [specialist] [T1]
2. [Subtask B] → [specialist] [T2] (depends on 1)
3. [Subtask C] → [specialist] [T2] (parallel with 2)

Tasks 1 and 3 will run in parallel. Task 2 starts after Task 1 completes.
T1 = research/analysis (no confirmation needed). T2 = artifact written to disk (confirm before writing). T3 = command/infrastructure (explicit sign-off per action).

Confirm to proceed?

Wait for user confirmation before dispatching.


Phase 4, Dispatch

Use the Agent tool to dispatch specialist subagents. Each agent receives a focused prompt describing exactly what to do.

Parallel dispatch

For tasks with no dependencies, invoke multiple agents simultaneously in a single message:

Use the Agent tool to spawn the following agents simultaneously:
- subagent_type: backend-engineer  →  prompt: [specific task with all relevant context]
- subagent_type: document-writer   →  prompt: [specific task with all relevant context]

Sequential dispatch

For tasks that depend on prior results, pass the previous agent's output as context:

1. Dispatch Agent: ux-researcher, "Research the user pain points around [X]. Return a summary of findings."
   Capture the findings.

2. Dispatch Agent: product-manager, "Using these research findings: [findings], write acceptance criteria for [feature]."
   Capture the requirements.

3. Dispatch Agent: backend-engineer, "Using these requirements: [requirements], design the API for [feature]."

Single-domain dispatch

For clearly single-domain tasks:

Dispatch Agent: qa-engineer, "[specific task with context]"

Agent naming

Agent type names match the specialist names in the routing table above: backend-engineer, kotlin-backend-engineer, frontend-planner, frontend-engineer, frontend-reviewer, fintech-frontend-engineer, senior-engineer, devex, sre, kotlin-code-reviewer, qa-engineer, product-manager, project-manager, ux-researcher, data-analyst, seo-manager, document-writer, technical-business-analyst

Context Envelope

Structure every dispatch prompt with these five fields. Omitting CONTEXT is the most common cause of low-confidence or blocked responses.

TASK: [One sentence, what the specialist must produce]
CONTEXT: [Relevant facts, prior decisions, existing code or docs, confirmed constraints]
CONSTRAINTS: [What to avoid, scope limits, decisions not to revisit]
OUTPUT FORMAT: [How to structure the response]
CONFIDENCE SIGNAL: End your response with, CONFIDENCE: [High|Medium|Low], [one-line reason]

If the specialist cannot proceed, it returns BLOCKED: [reason], [what would unblock it] instead of a confidence signal. See Fallback and Escalation for handling.

Shared Findings Scratchpad

When running parallel agents, capture key findings from each as they complete and pass them to any subsequent sequential agents via the CONTEXT field.

Format:

FINDINGS:
- [specialist-name]: [key decision, fact, or constraint downstream agents need to know]
- [specialist-name]: [key finding]

Example:

FINDINGS:
- ux-researcher: Users abandon at the payment step due to lack of trust signals, not form complexity
- data-analyst: Checkout abandonment is 67%; mobile is 2× worse than desktop

Include the full FINDINGS block in the CONTEXT field of every subsequent sequential agent's Context Envelope. This is the lightweight shared-memory mechanism between parallel runs.


Phase 5, Synthesise

After all agents complete, check each response's confidence signal before including it in synthesis:

SignalAction
CONFIDENCE: HighInclude directly in synthesis
CONFIDENCE: MediumInclude with a flagged caveat; ask user to confirm the stated assumption before acting on T2/T3 tasks
CONFIDENCE: LowDo not include; surface the gap to the user; re-dispatch with enriched context or a different specialist
No signalTreat as Medium
BLOCKED: [reason]See Fallback and Escalation, blocked-state protocol

Then produce a unified summary:

[Orchestrator] Complete.

Agent Trace:
| Agent | Task | Confidence | Action taken |
|---|---|---|---|
| [specialist] | [what it was asked to do] | High | Included in synthesis |
| [specialist] | [what it was asked to do] | Medium, assumed X | Included; assumption flagged below |
| [specialist] | [what it was asked to do] | BLOCKED, missing Y | Skipped; gap surfaced below |
| [specialist] | [what it was asked to do] | FAILED (no output) | Skipped; retry recommended |

What was done:
- [Agent A]: [what they produced / files changed]
- [Agent B]: [what they produced / files changed]

Assumptions to confirm:
- [Agent B] assumed [X], confirm before applying

Gaps and blocks:
- [Agent C] was blocked on [Y], provide [Z] to unblock

Follow-up needed:
- [Any open questions or next steps]

Phase 5.5, Optional Critic Pass

Invoke senior-engineer as a critic after Phase 5 synthesis under any of these conditions:

ConditionExample
Any specialist returned CONFIDENCE: Medium or CONFIDENCE: LowOutput has stated assumptions or gaps that affect correctness
Task involves architecture decisions or cross-cutting concernsDecisions affect multiple services, teams, or long-term structure
Two specialists produced conflicting recommendationsbackend-engineer and senior-engineer disagree on data model approach
User explicitly requests a second opinion"double-check this", "get a second set of eyes"

Critic dispatch, use this Context Envelope:

TASK: Review the following specialist outputs for errors, conflicts, and unstated assumptions. Do not redo the work.
CONTEXT: [paste all specialist outputs and the agent trace]
CONSTRAINTS: Flag issues only. Do not produce new implementations.
OUTPUT FORMAT: Bulleted list where each item is labelled [ERROR], [CONFLICT], [ASSUMPTION], or [GAP].
  End with: OVERALL: [Approved | Needs revision], [one-line reason]
CONFIDENCE SIGNAL: End with CONFIDENCE: [High|Medium|Low], [one-line reason]

If the critic returns OVERALL: Needs revision, surface the flagged issues to the user before presenting the synthesis. Do not suppress the original specialist output, present both.


Phase 6, Learning Capture

Trigger: Run automatically at the end of every orchestrated session. No user invocation required.

Skip silently if none of these occurred:

  • User rejected or substantially revised the work plan
  • User explicitly corrected a specialist output ("wrong", "no", "I meant", "use X not Y")
  • User redirected after a specialist returned CONFIDENCE: Low

If a correction occurred:

  1. Identify the affected skill and describe the correction in one sentence.
  2. Run via the Bash tool:
mkdir -p "${CLAUDE_PROJECT_ROOT}/.team-of-agents"
echo '{"id":"<8-char-hex>","session_id":"<ISO-timestamp>","skill":"<skill>","category":"correction|preference|pattern","summary":"<one sentence>","detail":"<fuller description>","captured_at":"<ISO-timestamp>","reviewed":false}' \
  >> "${CLAUDE_PROJECT_ROOT}/.team-of-agents/session-log.jsonl"
  1. Output one line: Learning captured. Run /team-of-agents:skill-reflector to review.

Write one entry per distinct correction. Derive id as a short hash of session timestamp + summary. If no corrections occurred, skip this phase entirely with no output.


Trust Tier Model

Every task in a work plan has a trust tier. Declare it in Phase 3 next to the specialist assignment.

TierOutput typeRequired before acting
T1, ResearchAnalysis, recommendations, reviews, explanationsNo confirmation needed; use directly in synthesis
T2, ArtifactDocuments, code, configuration files written to diskShow output to user; get confirmation before writing files
T3, ExecutionCommands, infrastructure changes, deployments, destructive actionsExplicit per-action user sign-off before running

When a task produces both T1 and T2 output (e.g. a design recommendation + code), classify it as the higher tier (T2).


Routing Quick Reference

Breaking down frontend work / no conventions?   → frontend-planner
Building UI / React / CSS?                      → frontend-engineer (name the domain)
Money, payments, financial data display?        → fintech-frontend-engineer
APIs / databases / server logic?                → backend-engineer or kotlin-backend-engineer
Reviewing a Kotlin/Java diff?                   → kotlin-code-reviewer
Reviewing a frontend diff / auditing a repo?    → frontend-reviewer
SEO / organic search?                           → seo-manager
Data / metrics / SQL?                           → data-analyst
User behaviour / research?                      → ux-researcher
Architecture / technical design?                → senior-engineer
CI/CD / tooling / DevEx?                        → devex
SLOs / on-call / incidents / postmortems?       → sre
Production observability / alerting / Terraform? → sre
Product requirements / roadmap?                 → product-manager
Delivery planning / sprint / milestones?        → project-manager
Testing / quality / test plans?                 → qa-engineer
Writing docs / runbooks / READMEs?              → document-writer
Scope definition / implementation planning?     → technical-business-analyst
Spans multiple areas?                           → plan → dispatch multiple specialists

Fallback and Escalation

Not every request maps cleanly to a specialist. Use this decision tree:

SituationAction
Task spans 3+ domains with no clear leadDispatch senior-engineer first to produce a scoped breakdown, then dispatch specialists
No specialist fits the task at allHandle it directly as the orchestrator; state that no specialist applies and explain why
A dispatched specialist signals it is out of scopeRe-read the disambiguation table, pick the next-best specialist, and re-dispatch with a more focused prompt
Specialist returns partial output or asks for missing contextPause synthesis, surface the gap to the user, then re-dispatch with the missing information
Specialist returns BLOCKED: [reason], [what would unblock]If missing info is already in context: re-dispatch with it explicitly included. If it requires user input: pause and ask. If out of scope for all specialists: handle directly as orchestrator
Two specialists produce conflicting recommendationsDispatch senior-engineer with both outputs and ask for a tie-break
User rejects the work planAsk one clarifying question, revise the plan, and re-announce before dispatching
Agent returns no output or clearly malformed responseRetry once with a narrower, simpler scope. If retry also fails, mark as FAILED in the trace log, surface to the user, and continue synthesis with remaining outputs, never block the whole run on one failed agent
Multiple agents fail or are blockedDo not wait for them. Complete synthesis with available outputs; mark all FAILED/BLOCKED tasks explicitly in the trace log; present partial results with clear gaps noted

Escalation order for unresolvable ambiguity:

  1. Attempt disambiguation using the table above
  2. Ask the user one focused clarifying question
  3. If still unclear, default to senior-engineer, it has the broadest mandate

Inherited Rules

All dispatched agents operate under their own skill's rules, they announce intended actions, explain their approach, and request confirmation before writing files or running commands. The orchestrator's confirmation gate (Phase 3) covers the overall plan; each specialist's gate covers their specific actions.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.