agentleFS
edilsonvilarinhoedilsonvilarinho/usage-monitor/.claude/skills/orchestrate/SKILL.md

orchestrate

Skill19 starsChanged 50 days agoMITView on GitHub

Runs a request through a cheap-first multi-agent workflow. The main session plans and validates, subagents on haiku execute, failures go back to the same agent, and only 3 rejections escalate to sonnet. Starts a live visual office portal showing agents, tasks and messages (skippable with --no-portal), and gates visual work behind prototypes. Use when the user asks to orchestrate, delegate to agents, or use the office portal.

173 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use define-requirements, orchestrate-plan 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.
  • sson0-erSkill

    define-requirements

    Work with the user, one question at a time, to complete the requirements document (docs/claudex/<slug>/01-requirements.md). Run by the orchestrator (parent). Stays out of design and implementation.

    Also in 3 projects that use this

  • EternallLightSkill

    orchestrate-plan

    Use when executing a locked, reviewed PLAN.md by delegating the implementation to visible worker agents in Orca, herdr, or cmux ONE PHASE at a time — splitting the plan into context-window-sized phases, giving every phase a pristine worker context, and (when the plan touches INDEPENDENT repos) running one worker per repo IN PARALLEL. Triggers on "run the plan with a worker", "execute the plan in the other pane", "split the plan into phases and build it with workers", "build the backend and frontend in parallel panes". Not for edits you can finish inline; outside Orca, herdr, or cmux use tgc-skills:orchestrate.

    Also in 3 projects that use this

  • sson0-erSkill

    record-evidence

    How to record external facts (docs, command output, codebase findings) as evidence and design choices as decisions. Used by the researcher, designer and reviewer agents.

    Also in 3 projects that use this

  • PinkneyJiangSkill

    improve-architecture

    扫描代码库中的架构摩擦点,识别浅模块并挖掘深模块演进机会。生成可视化交互式 HTML 诊断报告,并在用户确认后闭环实施深度重构。

    Also in 4 projects that use this

  • kjnezSkill

    ticket

    Work on a JIRA/Linear ticket end-to-end: read ticket details, explore codebase, create a branch, implement with TDD, run quality checks, update ticket status, and create a PR. Use when the user provides a ticket ID to implement. Triggers on requests like "/ticket PROJ-123", "work on this ticket", "implement PROJ-123".

    Also in 4 projects that use this

  • mukcoSkill

    principles

    General software engineering principles — DRY, SOLID, YAGNI, KISS, naming, code smells, and refactoring. Language-agnostic. Use alongside language-specific skills.

    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

13 rules. 0 are common, 3 are distinctive, and 10 are very specific to this project.

  • 0

    Common

    Most of the 155 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 10

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Without portal (--no-portal in the request): Never run start.mjs: no server, no browser, no URL.

    line 21
  2. Very specific:

    Every emit.mjs call below carries --sessao ${CLAUDE_SESSION_ID}, which works in both modes.

    line 25
  3. Very specific:

    If the Agents: block above says PENDENTE, the project has no agents configured yet.

    line 35
  4. Very specific:

    Ask which option they want, with AskUserQuestion:

    line 40
  5. Very specific:

    After installing, read each generated agent and fix what the manifests could not tell: conventions, forbidden paths, the real test command …

    line 46
  6. Very specific:

    If the new agents are not available to delegate to, tell the user to restart the session (or reload with /agents) and run the same request …

    line 49
  7. Very specific:

    Every subagent runs on haiku with high effort.

    line 78
  8. Distinctive:

    No delivery is accepted on the agent's own report.

    line 129
  9. Distinctive:

    Stop and ask the user to choose.

    line 162
  10. Very specific:

    Before planning any visual task, delegate to explorer with the standard prompt format.

    line 170
  11. Very specific:

    Write the return to a briefing file (for example prototipos/design-system.md): pointers plus the few values that decide the work.

    line 173
  12. Distinctive:

    Every visual task points to that briefing and names the design-system files the agent must read.

    line 175
  13. Very specific:

    If the explorer finds nothing usable at <path>, stop and tell the user.

    line 179

“Common” is measured: kept by at least 6 in 10 of the 155 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

Orchestrate

Request: $ARGUMENTS

Agents: !node ${CLAUDE_SKILL_DIR}/setup/agentes.mjs verificar || true

Mode: with or without portal

  • With portal (default). Your first action, before anything else, is to run node ${CLAUDE_SKILL_DIR}/portal/start.mjs --sessao ${CLAUDE_SESSION_ID}. The first line of your reply is the URL it prints, so the user can follow progress from the start; the plan comes after. If it prints an error, fix the portal before delegating: with the portal on, it is not optional.
  • Without portal (--no-portal in the request). Never run start.mjs: no server, no browser, no URL. The flow is identical (sections 0 to 7, same rules, same limits). Everything that goes through emit.mjs still runs, because it is the log that counts rejections and enforces the escalation limits. Only the visual layer is gone.

Every emit.mjs call below carries --sessao ${CLAUDE_SESSION_ID}, which works in both modes.

The portal lives in portal/web/ and shows one desk per agent, a task board and a communication log on a single screen. It reads the session transcripts on its own; what only you know (tasks, messages, verdicts) goes in through emit.mjs. Subcommands and flags of emit.mjs are in Portuguese by design (see references/portal-contract.md).

You are the orchestrator. With the portal on, you appear in it as agent am.

0. First run: configure the agents for this project

If the Agents: block above says PENDENTE, the project has no agents configured yet. Do this after the portal URL line (right at the start, in --no-portal mode) and before planning; if it says CONFIGURADO, skip to section 1.

  1. Show the user the detected stack and commands from the block (they come from manifests only; commands marked convenção are the ecosystem default, not verified in this project).
  2. Ask which option they want, with AskUserQuestion:
    • Install for this project (recommended): node ${CLAUDE_SKILL_DIR}/setup/agentes.mjs instalar writes the five agents to <project>/.claude/agents/ from the templates in agents/, each with a Project context section (stack, commands, rule files). It never overwrites an existing agent.
    • Use the generic agents: node ${CLAUDE_SKILL_DIR}/setup/agentes.mjs dispensar records the choice and stops asking.
  3. After installing, read each generated agent and fix what the manifests could not tell: conventions, forbidden paths, the real test command if the detected one is a convenção. Take the rules from the project's CLAUDE.md or AGENTS.md if present; do not invent any.
  4. If the new agents are not available to delegate to, tell the user to restart the session (or reload with /agents) and run the same request again.

1. Interpret the request

  • --no-portal: skip the portal (see Mode above). Strip it from the request before planning.
  • --design-system <path>: local file or folder with the project's design system (tokens, components, rules). Strip it from the request. Used by section 6 and by any visual task. A value that is not a local path (a URL, a Figma link) is not supported: tell the user and ask for a local path. If the path does not exist, stop and ask.
  • --prototypes N: number of prototypes per visual deliverable. Without the option, N = 4.
  • Work is visual when it involves a screen, front end, video, image or any artefact the user judges by looking at it. Visual work always goes through the prototype gate (section 6).
  • A request with more than one visual deliverable produces N prototypes for each.

2. Plan

Break the request into tasks with a new ID (check the project's task plan first, if there is one; IDs never repeat), an owner, exclusive paths and a verifiable acceptance criterion, preferably a command that exits 0: the agent iterates alone until it passes, without spending an orchestrator turn. Record each task in the plan and in the portal:

node ${CLAUDE_SKILL_DIR}/portal/emit.mjs tarefa --sessao ${CLAUDE_SESSION_ID} --id PE1 --titulo "Floor plan" --dono prototype-dev --estado fila

Shared specification goes in a briefing file, never in the prompt. N agents read the same file.

3. Route: haiku first

Every subagent runs on haiku with high effort. Set that in the agent's frontmatter and delegate without model or effort. Ready-made agent templates are in agents/ of this skill; section 0 installs them per project.

WorkAgent
Sweeps, locating code, gathering factsexplorer
Tests, typecheck, build, smoke, CItest-runner
Back-end codebackend-dev
Front-end codefrontend-dev
Prototype, tooling, video, audioprototype-dev
Planning, judging, integrating, shared contracts, dependencies, commitsyou

The portal draws these five names with their own desk. Any other subagent type works and is drawn as a generic desk (outro).

Sonnet only enters by escalation (section 5). Never pass model: "sonnet" in advance, nor because a task looks hard. Haiku costs 5x more above 100K prompt tokens: a large task becomes several small tasks, not one long agent.

Edit directly only a pinpoint tweak to one known file. A long command that needs no judgement (a render, for example) runs in the background in your own session: it costs no agent tokens.

4. Delegate without inflating context

Split only when it pays off: evaluate the demand before opening agents. A small or sequential task goes to one agent. Parallelism needs several truly independent tasks, never a target number of agents: every return costs one orchestrator turn with the whole context.

A delegation prompt has at most 12 lines, in this format:

Task <ID>. Briefing: <path>, section <n>.
Edit only: <paths>.
Acceptance: <command that exits 0, or verifiable criteria>.
Return: the agent's standard format.

Forbidden in the prompt: conversation summary, another agent's return, file contents the agent can read, the reason behind the request. Point to a path, do not paste text.

  • At most 4 simultaneous agents. Agents always in the background when there is other work to do.
  • Parallel code tasks go in isolation: "worktree". Exception: artefacts in exclusive folders with no shared test suite may use the same checkout, because no agent runs or reads another's work.
  • Speak in the portal at each handoff:
node ${CLAUDE_SKILL_DIR}/portal/emit.mjs fala --sessao ${CLAUDE_SESSION_ID} --de am --para prototype-dev --tarefa PE1 --texto "Floor plan is yours."
node ${CLAUDE_SKILL_DIR}/portal/emit.mjs tarefa --sessao ${CLAUDE_SESSION_ID} --id PE1 --estado andamento

5. Validate and send back

No delivery is accepted on the agent's own report. Check every criterion with your own evidence: diff, execution, screenshot or a frame extracted from the video.

node ${CLAUDE_SKILL_DIR}/portal/emit.mjs veredito --sessao ${CLAUDE_SESSION_ID} --tarefa PE1 --resultado aprovada --texto "Criteria checked."

Rejected: --resultado devolvida. The command prints the count and the action; follow the printed action, never memory. Only delivery defects reject: a BLOQUEADA return and a usage-limit interruption do not count. Never fix it in the agent's place.

  • devolver ao mesmo agente (return to the same agent): SendMessage to the same agent, which keeps its context. The first line is <ID> devolvida: <defect>, because the portal classifies by it. The message carries only the failed criterion, the evidence and the expected result. Never resend the briefing. Verdict and SendMessage go out in the same turn: each orchestrator turn resends the whole session context.
  • escalar para sonnet high (3rd rejection on haiku): run emit.mjs escalada and open a new agent of the same type with model: "sonnet" and effort: "high", because SendMessage cannot change the model. No isolation: the work continues in the path where haiku stopped, which the prompt points to with the open defect. Never paste haiku's history.
  • parar e reportar ao dono do produto (3rd rejection on sonnet): stop and report to the user what failed.
node ${CLAUDE_SKILL_DIR}/portal/emit.mjs escalada --sessao ${CLAUDE_SESSION_ID} --tarefa PE1

emit.mjs escalada refuses a task below the limit. Limits live in LIMITE_REPROVACOES in portal/emit.mjs.

6. Prototype gate (visual work)

  1. Generate N prototypes in prototipos/<deliverable>/, one agent per prototype, with genuinely different directions.
  2. Publish the gallery in the portal (/prototipos/<deliverable>/) and validate each one in a real browser. With --no-portal, open the prototipos/<deliverable>/index.html files directly in the browser and give the user those paths.
  3. Stop and ask the user to choose. No final version before the choice.

Design system

The design system is the one at --design-system <path>; without the option, look for one in the project only if the work is visual, and use it if found. Never read it yourself: the explorer does it, to keep the whole system out of your context.

  1. Before planning any visual task, delegate to explorer with the standard prompt format. Task: locate, in <path>, the tokens (colors, type, spacing), the components with their props and usage rules, and any written guidelines. Return file:line pointers, at most 20 lines. explorer is read-only and cannot write files.
  2. Write the return to a briefing file (for example prototipos/design-system.md): pointers plus the few values that decide the work. Shared specification goes in a briefing, never in the prompt.
  3. Every visual task points to that briefing and names the design-system files the agent must read. Prototypes use the existing tokens and components only.
  4. A new token, component or rule: list what is missing and ask permission first.

If the explorer finds nothing usable at <path>, stop and tell the user; do not invent a design system.

7. Wrap up

One activity, one commit, in Conventional Commits. Update the status in the project's task plan if there is one. In the final report, state what was verified, what was not, the per-agent token cost shown in the portal (with --no-portal: say the cost was not measured), and how many rejections and escalations each task had.

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.