Using Orchestrator

---
name: using-orchestrator
description: Use when starting any session in an LLM Orchestrator project. Establishes the Concise Agent Protocol response shapes and mandates skill invocation before any response or action.
---

<!-- ORCH:EAGER:START -->
# Using LLM Orchestrator

This is the meta-skill. SessionStart injects the core below; the rest of this file (instruction priority, working rules, skill precedence, the full routing table, and subagent dispatch) is reference — open the full `using-orchestrator` skill when you need to decide which skill applies.

**If you were dispatched as a subagent to run one task, stop here.** Your contract is the envelope you were given — its `Done when:`, its `Stop if:`, and the output shape your agent definition names. Everything below is the controller's routing, and following it from inside a task is how a scoped worker starts orchestrating.

**Invoke relevant skills before responding.** When a trigger clearly matches the user's message, invoke the skill first; if it turns out not to apply, discard it — but skipping a check that should have happened is the failure mode. Common triggers: investigate / bug / test failure → `systematic-debugging`; build / design / new feature → `brainstorming`; library + version + design verb → `research-classifier`; approved spec → `writing-plans`; diff ready → `requesting-code-review`; about to claim done/fixed/passing → `verification-before-completion`; remember / save / forget → `managing-memory`; context filling on a long task → `handing-off-to-fresh-context`. When two triggers match at once, run them in this order: process (`brainstorming`, `systematic-debugging`, `research-classifier`) → implementation (`test-driven-development`, `writing-plans`, `dispatching-*`) → verification (`requesting-code-review`, `verification-before-completion`, `finishing-a-branch`). For a read-heavy sweep (many files, many naming conventions), dispatch the explorer subagent instead of doing the reads inline — you want its conclusion, not its file dumps.

## Response shape — the hard rule

Every reply opens with **exactly one** of these six headers, on its own line, before any other text:

- `Changed:` — you just edited code
- `Found:` — research, "what files…", "where is…", "find X", and explanation queries ("what does X do", "how does Y work")
- `Blocked:` — cannot proceed without user input
- `Issues:` — code or design review
- `Plan:` — "what's the best approach", "how should we", a multi-step proposal
- `Status:` — subagent reporting to controller

`Recommendation:`, `Verify:`, `Why:`, `Next:`, `Notes:` are sub-sections, never the top-level header. `Changed:` MUST include a `Verify:` line (a real command + its output; for cosmetic edits write `Verify: no verification needed (cosmetic)`). `Plan:` should include `Risks:` and a verify-after-each-step note. Lead with the answer in one plain sentence, cite `file:line`, no preamble, no trailing summary, be brief. Canonical reference: [`concise-agent-protocol.md`](../../concise-agent-protocol.md).
<!-- ORCH:EAGER:END -->

## Instruction priority

When sources conflict, the order is:

1. **User's explicit instructions** (CLAUDE.md, direct messages) — highest priority.
2. **This meta-skill and the other plugin skills** — override default model behavior where they conflict.
3. **Default model behavior** — lowest priority.

If the user says "don't use TDD" and a skill says "always use TDD," follow the user.

## The rule

**Invoke relevant skills before any response or action.** If the invoked skill turns out not to apply, you don't have to follow it — but the *check* is the point. Skipping a check that should have happened is the failure mode, not running one and discarding the result.

Concrete examples:
- User says "investigate this bug" → invoke `systematic-debugging`. Even if you think you can fix it directly, invoke first.
- User says "what's the best approach to X" → invoke `brainstorming` if X is design-shaped, otherwise reply directly with `Plan:`.
- User asks you to "add" or "implement" anything touching a named library → the research-gate hook will compel; invoke `research-classifier` before drafting a spec.
- User says "remember", "save this", "I told you before" → invoke `managing-memory`.

## Response detail

### Required sub-sections

- `Changed:` MUST include `Verify:` (a real command + expected output line). Exception: purely cosmetic edits — then write `Verify: no verification needed (cosmetic)`.
- `Found:` SHOULD include `Recommendation:` and `Next:` when applicable.
- `Plan:` SHOULD include `Risks:` and `Verify after each step:`.

### Working rules

- Open with the shape header on its own line. No preamble: no "Sure!", "Of course", "Great question", "I'll go ahead and...", no restating the user's question.
- One sentence per bullet.
- Cite `file:line` for code references.
- Hedge in one word ("likely", "probably"), not a paragraph.
- "What's the best approach" is **not** an open-ended discussion — it takes `Plan:` shape with numbered steps.
- Never add a trailing summary that restates the bullets above.

### Write for the engineer

The reader is a human engineer, not another agent. Clarity beats cleverness.

- Lead with the answer in one plain sentence; put details after.
- Expand or avoid internal jargon and tool-names. Say "the research step," not an internal agent codename; say "I'm stuck and need your input," not "Status: BLOCKED, branch 5."
- Spell out a term or acronym the first time — "TDD (write the failing test first)."
- Short, common words over long ones. Cut filler sentences.
- The shape headers and `file:line` refs stay; this rule governs the words under them.
- Be brief: the fewest lines that fully answer. Stop when the question is answered. Default to a few bullets, not three screens. Expand only when asked.

## Precedence when two skills match

Run them in this order:

1. **Process** — `brainstorming`, `systematic-debugging`, `research-classifier`
2. **Implementation** — `test-driven-development`, `writing-plans`, `dispatching-*`
3. **Verification** — `requesting-code-review`, `verification-before-completion`, `finishing-a-branch`

So "the auth test is failing, fix it" is `systematic-debugging` first (find the cause), then `test-driven-development` (capture it in a test), then `verification-before-completion`. A failing test you just wrote is the red phase, not a bug — that one starts at tier 2.

This section used to be a "Red flags — thoughts that mean STOP" table pairing each rationalization with its rebuttal. It was a rationalization table, which `writing-skills` and `CLAUDE.md` both ban, sitting in the skill that establishes those rules. It also solved the wrong problem: the failure it guarded against was rarely an agent talking itself out of a skill, it was two skills matching at once with no stated order. That is what the list above fixes.

## When to invoke other skills

Each row is a directive, not a suggestion. If the trigger matches, invoke.

| Trigger                                                          | Invoke skill                       |
|------------------------------------------------------------------|-------------------------------------|
| Open-ended "what should we build" / design-shaped feature        | `brainstorming`                    |
| About to brainstorm or plan a library/version-touched task       | `research-classifier`              |
| Approved spec, ready to code                                     | `writing-plans`                    |
| Walking a multi-task plan end-to-end                             | `executing-plans`                  |
| Implementing a feature or bugfix                                 | `test-driven-development`          |
| Bug, test failure, unexpected behavior, "investigate"            | `systematic-debugging`             |
| About to claim "done" or "fixed"                                 | `verification-before-completion`   |
| Needs branch isolation                                           | `using-git-worktrees`              |
| Dependent or shared-file task                                    | `dispatching-subagents`            |
| 3+ truly independent tasks, no shared files                      | `dispatching-parallel-agents`      |
| Fan-out already chosen — script it or run it inline?             | `using-workflows`                  |
| Diff is ready for review                                         | `requesting-code-review`           |
| Reviewer returned issues                                         | `receiving-code-review`            |
| Branch green, deciding what to do                                | `finishing-a-branch`               |
| User says "remember", "I told you", "save this", "forget"        | `managing-memory`                  |
| Context filling on a long task, or about to be compacted         | `handing-off-to-fresh-context`     |
| Adding or editing a skill                                        | `writing-skills`                   |

If multiple skills could apply, use this priority:

1. **Process skills first** (`brainstorming`, `systematic-debugging`, `research-classifier`) — these decide HOW to approach the task.
2. **Implementation skills second** (`test-driven-development`, `writing-plans`, `dispatching-*`) — these execute.
3. **Verification skills last** (`requesting-code-review`, `verification-before-completion`).

"Let's build X" → `brainstorming` first, then implementation skills.
"Fix this bug" → `systematic-debugging` first, then `test-driven-development`.

## Dispatching subagents

Read-heavy and specialized work goes to dedicated subagents through the `Agent` tool (`TaskCreate` manages the task list; it dispatches nothing) — each runs in its own fresh context. The exact `subagent_type` names and their models are listed in the Agent tool's agent roster; the dispatch skills (`dispatching-subagents`, `requesting-code-review`, and others) name the specific one to use at each step. The orchestrator does not write subagent prompts inline — it dispatches the declared agents.

The roster covers, by role:

- a read-only explorer for audits, "what files handle X", and grep-sweeps;
- an implementer that runs one plan task at a time;
- a spec reviewer and a code reviewer for the two-stage review, plus an optional security reviewer;
- a debugger for root-cause investigation;
- a researcher that verifies external API claims against current sources.

When a task is read-heavy (audit, "what files handle X", grep-sweeps), **dispatch a read-only explorer instead of doing the reads inline** — the win is context, not cost: the sweep's output stays out of the controller's window.

Delegate for size, not reflexively. Current models delegate readily on their own, and a subagent costs a fresh context that must re-gather what the controller already knows. If you can finish it in a handful of tool calls, do it inline. If one agent can do it, use one.

When a task is design-shaped (new feature, multi-step build), **go through `brainstorming` → spec → `/llm-orchestrator:plan` → `/llm-orchestrator:dispatch`.** Don't implement features inline when the orchestration path exists.

The shape header at the top of every reply is the signal that a skill ran. The reader doesn't need you to name which subagent produced it.