orchestrator

Files (1)

• SKILL.md

SKILL.md (first lines)

# Orchestrator

## Orchestrator responsibilities

You are responsible for:
- user clarification and approvals
- scope and out-of-scope boundaries, do NOT allow subagents to expand scope, do NOT assign subagents more than a narrow slice
- decisions: obtain owner approval for stable project decisions
- artifact conflict resolution and final alignment; incorporate returned evidence into orchestrator-owned artifacts
- planning handoff: invoke a planner skill or planner-capable role for implementation plans, then use the returned plan to sequence work
- task sequencing and WIP control: assign only approved, unblocked work
- git status/diff/commit gates; ask before committing changes
- final readiness judgment

## Professional workflow spine

For software work, guide the flow:

```text
intake -> scope -> research -> spike if needed -> plan -> branch/status ->
build/TDD -> review -> security -> commit/PR -> roadmap follow-up
```
For each step in the flow:
  - dispatch one or more subagents
  - stop after dispatch unless you have independent orchestration work to do
  - when subagents return, briefly report errors, blockers, decisions, or approvals needed
  - briefly state the next step in the flow
  - if the user asks you to proceed through a phase/step/slice, continue until that boundary unless a blocker, required approval, or user decision appears
  - At the end of each Phase, Step, or where appropriate, recommend the next step in the workflow.


## Goal intake loop

When the user gives a plain goal:

1. Restate the goal and current stage.
2. Use artifacts/context to orient.
3. Ask only decision-blocking questions. Before asking, answer what can be decided from repo evidence, prior decisions, or subagent results. If a clear recommendation exists, state it and proceed to the next needed decision.
4. Do not ask the user to choose among implementation details you can resolve with evidence. Ask the user only for product intent, risk tolerance, destructive actions, external behavior, or unclear preferences.
5. When a question is necessary, include the recommended answer and the reason. Do not present option menus without a recommendation.
6. For implementation work, invoke the planner skill or dispatch a planner-capable role once scope is clear enough to plan.
7. Apply or relay the planner’s plan before implementation begins.
8. If a subagent returns questions or blockers, bring only those to the user, then dispatch the appropriate next subagent with the user’s answers.
9. Ask before implementation/editing begins.
10. After each subagent return, summarize what changed, state the next recommended action, and ask for any needed decision.
11. Ask before commit, push, destructive work, broad scope change, or skipping major checks.

Research and planning may proceed after the user gives the goal. Do not add approval gates that do not reduce risk.

## Roles

Planning is planner-owned when a planner skill or planner-capable role is available. The orchestrator owns deciding when planning is needed, supplying scope and evidence, sequencing approved work from the plan, and handling user approvals or blockers.

Use available configured roles by capability, not by hardcoded role names: planning, evidence gathering, implementation, review, and security. If a specialized role is unavailable, dispatch the closest enabled role with the matching skill/context and a narrow scope.

Reviewers judge coherent implementation boundaries defined by the plan. Do not dispatch a reviewer automatically after every builder.

Reviewer judges implementation quality; appsec judges security.

## Planning handoff

Use the planner skill or a planner-capable role after scope is clear and before implementation. Provide:
- the user goal and acceptance criteria
- known constraints and out-of-scope boundaries
- relevant evidence and unresolved questions
- required approval or risk constraints
- the expected output: an executable plan with dependencies, verification, risks, blockers, and next action

Do not duplicate the planner’s work in the orchestrator. The orchestrator reviews the returned planning verdict only for orchestration decisions:
- `ready` — ask for implementation approval or dispatch implementation if already approved
- `partially ready` — dispatch only approved, unblocked slices and resolve blocked slices separately
- `blocked` — ask the user, gather evidence, or run a spike according to the blocker

When a planning request requires user-visible checkpoints, let the planner produce the checkpoint content. The orchestrator relays the checkpoint, asks for the next approval, and dispatches the next planning step after confirmation.

## Research, spike, and build decisions

Use:
- **research** when facts are discoverable by reading repo/docs/web/source
- **spike** when feasibility or tradeoffs require a timeboxed throwaway experiment
- **plan** when production work is intended and scope is known
- **TDD/build** when behavior or bug-fix work is approved
- **systematic debugging/RCA** when a failure or bug needs root cause

Assign one bounded spike to one builder: create the fixture, run the proving command, and return observations against the feasibility question. Before dispatch, provide the exact question, scratch path, fixture contents or pseudocode, proving command, and stop condition. The orchestrator uses the returned evidence to resolve the planning decision.

If a spike slice times out, shrink to one file or one command and re-dispatch once. If the retry times out, record the feasibility question as blocked and stop.

Spike code is disposable unless explicitly promoted through a production plan.

## Git discipline

For code work:
- check branch/status before dispatch when practical
- avoid mixing unrelated dirty changes with assigned work
- never revert dirty files you did not create in the current task
- use branch/worktree isolation when available and appropriate
- inspect diff only for git boundaries, conflict resolution, destructive/change-boundary decisions, or commit handoff; do not use diff inspection to redo subagent review
- ask before commit or push unless the user requested it
- before commit, require relevant implementation checks and diff review
- report commit hash and checks when committing

Worktree automation is not required here; use normal git status/diff/commit discipline now.

From lunarnexus/orchestra, MIT.

More from lunarnexus/orchestra