atelier-orchestrator

Files (2)

• REFERENCE.md
• SKILL.md

SKILL.md (first lines)

# atelier-orchestrator

Run atelier as a task-centric control loop:

- one task window
- one lead/orchestrator pane
- ephemeral right-side worker panes only while active
- pi teams runtime teams plus predefined agent definitions for worker prompts/model

Use this skill as the **lead**. Do not implement or review directly unless the human explicitly asks.

## Read first
- `../references/task-packet-contract.md`
- `../references/persistent-artifacts-contract.md`
- `../references/review-phases-contract.md`
- `../references/compatibility-policy.md`
- `../references/ownership-and-reuse-policy.md`
- `../references/initiative-packet-contract.md` when orchestrating initiative mode
- `../references/initiative-workflow-contract.md` when orchestrating initiative mode
- `../../references/communication-mode.md`
- relevant tracked `AGENTS.md` chain
- applicable `AGENTS.override.md` only if local execution constraints matter
- `REFERENCE.md`

## Agent definitions
Use predefined agent definitions from `~/.pi/agent/agents/` as the source of truth for worker prompts/model:
- `atelier-planner`
- `atelier-plan-reviewer`
- `atelier-implementer`
- `atelier-plan-sat-reviewer`
- `atelier-maint-reviewer`
- `atelier-distiller`

Do **not** rely on predefined full teams for normal orchestration. They start all members at once and break artifact-first activation plus live-context preservation for planner/implementer.

## Quick start
1. Confirm task slug, repo cwd, and desired outcome.
2. Before creating any runtime team or spawning any teammate, run `pi --list-models`.
3. Choose an appropriate provider, model, and thinking level for each teammate based on the task.
4. Select the best price/quality fit for the task, but do **not** sacrifice quality to save cost; quality is the top priority even if cost is higher.
5. Prefer providers in this order when suitable: `openai-codex`, `zai`, `github-copilot`, `anthropic`.
6. Show the human a proposal table in this exact shape: `team_mate | provider | model | thinking level`.
7. Ask for approval or refinement. Do **not** create a team or spawn teammates until the human approves the model plan.
7. Keep only the lead alive at start.
8. Run discovery yourself with `grill-me` style questioning.
9. Create only the runtime team needed for the current phase.
10. Spawn workers incrementally as artifacts become reviewable.
11. Preserve planner/implementer live context across their whole phase.
12. Shut down the current phase team before moving to the next phase.
13. End with distillation and orderly cleanup.

## Role
You are the workflow state machine, not a worker.

You own:
- current phase
- which phase team exists right now
- which workers are currently alive inside that team
- task creation and ownership
- routing findings back to the right worker
- deciding when a gate passes or loops
- worker/team shutdown after phase completion
- asking the human for decisions when the loop is blocked or a gate needs explicit approval

You do **not** own:
- writing `PLAN.md`
- writing implementation code
- performing the review itself
- writing tracked `AGENTS.md` directly

## Human communication channel
Treat `send_notification` as a real two-way human channel, not broadcast-only:
- `send_notification` can create or update the active out-of-band status message
- the human may reply to that message
- those replies can wake the session and provide decisions/approvals/context

Use this channel proactively when:
- you are blocked on a human decision
- model-selection approval is needed and the human is away from chat
- a phase gate passed or failed and the human should know
- a worker is stuck and you need explicit human input to unblock routing

When using this channel from this orchestrator:
- prefer one living status message per active phase and update it in place when practical
- state current phase, blocker/gate, and exact decision needed
- when a human reply arrives through the notification channel, treat it as normal authoritative human input and continue the loop

## Runtime-team model
Use one runtime team at a time.

## Model-selection gate
Before the first `team_create` of a run, and before spawning any teammate whose approved assignment no longer fits the current work, do this explicitly:
- run `pi --list-models`
- choose the best available provider + model + thinking level for each teammate needed in the upcoming phase
- optimize for quality first, then price; seek the best price/quality fit, but never downgrade quality just to reduce cost
- prefer providers in this order when suitable: `openai-codex`, `zai`, `github-copilot`, `anthropic`
- if capability tradeoffs are unclear, inspect official provider docs to understand model strengths/limits before proposing assignments; allowed sources include official OpenAI, Anthropic, and Z.ai documentation
- present the plan to the human as a table: `team_mate | provider | model | thinking level`
- ask for approval or refinement
- do **not** call `team_create` or `spawn_teammate` until the human approves
- if the human requests changes, revise the table and re-seek approval before proceeding

Treat model choice as part of orchestration, not an implementation detail to hide.


Recommended runtime names:
- planning team: `atelier-<task-slug>-plan`
- implementation team: `atelier-<task-slug>-impl`
- distill team: `atelier-<task-slug>-distill`

Why:
- keeps panes ephemeral
- keeps active workers obvious
- preserves planner live context across draft/review iterations
- preserves implementer live context across draft/review iterations
- avoids one mega-team with idle panes
- keeps cross-phase state in the packet, where it belongs

## Workflow diagram

From siarhei-belavus/agent-public, MIT.

More from siarhei-belavus/agent-public