atelier-orchestrator
Orchestrate the full atelier workflow in one task window using pi teams runtime teams plus predefined agents, spawning right-side worker panes only when a phase is active and routing review loops unti
SKILL.mdskills/atelier-workflow/atelier-orchestrator/SKILL.md
GitHubatelier-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.mdwhen orchestrating initiative mode../references/initiative-workflow-contract.mdwhen orchestrating initiative mode../../references/communication-mode.md- relevant tracked
AGENTS.mdchain - applicable
AGENTS.override.mdonly 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-planneratelier-plan-revieweratelier-implementeratelier-plan-sat-revieweratelier-maint-revieweratelier-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
- Confirm task slug, repo cwd, and desired outcome.
- Before creating any runtime team or spawning any teammate, run
pi --list-models. - Choose an appropriate provider, model, and thinking level for each teammate based on the task.
- 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.
- Prefer providers in this order when suitable:
openai-codex,zai,github-copilot,anthropic. - Show the human a proposal table in this exact shape:
team_mate | provider | model | thinking level. - Ask for approval or refinement. Do not create a team or spawn teammates until the human approves the model plan.
- Keep only the lead alive at start.
- Run discovery yourself with
grill-mestyle questioning. - Create only the runtime team needed for the current phase.
- Spawn workers incrementally as artifacts become reviewable.
- Preserve planner/implementer live context across their whole phase.
- Shut down the current phase team before moving to the next phase.
- 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.mddirectly
Human communication channel
Treat send_notification as a real two-way human channel, not broadcast-only:
send_notificationcan 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_createorspawn_teammateuntil 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
%% mermaid-hash: dd8cda28
stateDiagram-v2
[*] --> Discovery
Discovery --> PlanningSetup: brief clarified
PlanningSetup --> PlannerOnly: create plan team\nspawn planner
PlannerOnly --> PlannerOnly: planner drafts/revises
PlannerOnly --> PlanningReviewLoop: initial PLAN.md ready\nspawn plan-reviewer
PlanningReviewLoop --> PlanningReviewLoop: reviewer findings -> planner revises\nsame planner + same reviewer stay alive
PlanningReviewLoop --> ImplementationSetup: plan approved\nshutdown planning team
ImplementationSetup --> ImplementerOnly: create impl team\nspawn implementer
ImplementerOnly --> ImplementerOnly: first implementation pass
ImplementerOnly --> ImplementationReviewLoop: implementation ready for review\nspawn reviewers
ImplementationReviewLoop --> ImplementationReviewLoop: reviewers findings -> implementer fixes\nsame implementer + same reviewers stay alive
ImplementationReviewLoop --> DistillSetup: implementation accepted\nshutdown impl team
DistillSetup --> Distill: create distill team\nspawn distiller
Distill --> Done: distill complete\nshutdown distill team
Done --> [*]
Activation guards
%% mermaid-hash: b9a2e93c
flowchart TD
A[Planner spawned] --> B{Initial PLAN.md exists?}
B -- No --> A
B -- Yes --> C[Spawn plan-reviewer]
D[Implementer spawned] --> E{Initial implementation pass exists?}
E -- No --> D
E -- Yes --> F[Spawn code reviewers]
Treat the diagrams above as normative workflow shape. If prose and diagram ever seem to disagree, follow the artifact-first / same-context workflow encoded in the diagrams.
Workflow
Use the diagrams above as the primary workflow contract.
1. Bootstrap
- Normalize task slug and packet path.
- Detect mode immediately.
- If the starting packet already has a
Parent initiativefield inINDEX.md, treat the run as initiative-child mode, notsingle-task, even if the human entered directly at the child packet.
- If the starting packet already has a
- Validate parent initiative routing before planning when in initiative-child mode.
- Resolve the recorded parent initiative path early.
- If the parent packet is missing, unreachable, or clearly stale, stop normal orchestration and ask the human for the correct parent location or an explicit no-sync decision.
- Do not claim final completion while parent sync state is unresolved.
- No worker team yet.
- Keep a compact state summary in chat.
- Include parent sync state in status when applicable:
n/a,pending,blocked, orcomplete.
2. Discovery
- Lead runs discovery in
grill-mestyle. - Stop when the brief is sufficient for planning.
3. Planning loop
- Create planning runtime team if missing.
- Spawn planner first.
- Spawn plan-reviewer only after first
PLAN.mddraft exists. - Keep the same planner and same reviewer alive until planning is accepted.
- Route findings back to the same live planner.
- Shut down planning team only after planning gate passes.
4. Implementation loop
- Create implementation runtime team if missing.
- Spawn implementer first.
- Spawn reviewers only after first implementation pass is ready for review and committed.
- Keep the same implementer and same reviewers alive until implementation is accepted.
- Route findings back to the same live implementer.
- Route them as an explicit work order, not a passive FYI.
- State that the implementer should apply the fixes now, not acknowledge-and-wait.
- Require the implementer to commit the initial implementation pass before first review handoff, and to commit each review-fix cycle before reporting back.
- Route reviewer requests against the exact implementation commit hash produced by the latest implementer handoff.
- Ask for a reply only after code/artifact updates plus validation evidence and commit hash, or an explicit blocker needing human decision.
- Shut down implementation team only after implementation gate passes.
5. Distill / closeout
- Create distill runtime team if missing.
- Spawn distiller.
- If distill changes the workspace, require a focused commit before the distiller reports back.
- Shut down distill team only after closeout gate passes.
Task protocol
Create team tasks for every material work item.
Minimum set:
discoveryoptional, lead-ownedplanningplan-reviewimplementationplan-satisfaction-reviewmaintainability-reviewdistill
Update status explicitly:
pendingin_progresscompleted
Do not leave ownership or status implicit.
Spawn / shutdown policy
Create a phase team only if:
- the phase actually needs it now
- it has a clear artifact contract
- it has clear exit criteria
Spawn a worker only if:
- the worker is needed now
- the artifact it needs already exists, or it is the artifact producer for that phase
- keeping it alive will preserve useful live context
Shut down the phase team when:
- its gate passed
- it has no immediate follow-up work
- keeping it alive would only create idle panes
- Do not shut down or recreate phase workers between same-phase iterations just because they are temporarily waiting on each other.
- Preserve the same planner + plan-reviewer contexts until planning is fully accepted.
- Preserve the same implementer + reviewers contexts until implementation is fully accepted.
When phase work is done:
- verify inbox/task state
- process approved worker shutdowns if pending
- shut down the team cleanly
Waiting / polling policy
- Prefer event-driven orchestration over tight polling.
- After dispatching a worker, do not immediately re-check status in a rapid loop.
- Default behavior: send the work, state the expected reply, then explicitly conclude your turn and become idle.
- After dispatch, assume you will be resumed automatically when a new teammate message arrives; do not manufacture wake-ups yourself.
- Only poll when a human explicitly asks for progress, when a timeout/risk threshold matters, or when a worker has been silent longer than reasonably expected for the task size.
- Never do repetitive
check_teammate/ inbox polling every few seconds. - Polling via
wait_background_processis prohibited without a strong explicit reason, such as an external long-running job, a human-requested progress check, or a real timeout/risk boundary. - For normal teammate orchestration, wait for messages instead of scheduling artificial wake-ups.
- If you must poll, use a coarse cadence measured in minutes, not seconds, unless the task is known to complete almost instantly.
Gate rules
Planning gate passes only when:
PLAN.mdexists- packet placeholders exist
review-planreports no blocking findings- the plan is handoff-ready for a fresh implementer
Implementation gate passes only when:
- implementation is complete against the approved packet
- validation evidence exists
- the latest implementer handoff includes the commit hash for the current accepted implementation state
- plan-satisfaction review has no blocking findings
- maintainability review has no blocking findings
- any required amendments are recorded in
AMENDMENTS.md
Artifact-first reviewer activation
- Do not start any reviewer before the artifact it reviews exists.
atelier-plan-reviewerstarts only after an initialPLAN.md/ packet draft exists.atelier-plan-sat-reviewerandatelier-maint-reviewerstart only after an initial implementation pass exists, is committed, and is explicitly declared ready for review.- Keep review tasks
pendinguntil their artifact-first precondition is satisfied.
Closeout gate passes only when:
- distillation is complete or an explicit no-op is recorded
- if distill changed the workspace, the latest distiller handoff includes the commit hash for that final distill state
- cleanup decision is made
- and, for initiative-child mode, parent sync is
completeor the human has explicitly approved a blocked no-sync outcome
Adjudication rules
- Do not let workers self-approve.
- Do not let reviewers silently expand scope.
- If a worker finds the packet unsafe or contradicted by the codebase, stop the loop and escalate as an amendment decision.
- If implementation reveals a better but non-essential design, require it to be recorded as a review note, not silently adopted.
- If a finding is unclear, ask for a sharper statement instead of paraphrasing loosely.
- If a teammate goes silent after likely meaningful work, treat that as a protocol failure and correct it explicitly rather than normalizing silence.
- If a teammate prints local status or conclusions without explicitly replying to the requesting side, treat that as a protocol failure; require an explicit requester-facing handoff instead of accepting pane-local output as done.
- If an implementer replies with acknowledgement/status only after routed findings and no blocker, treat that as a protocol failure; immediately restate the work order as
apply fixes now, then report after validation, not as a fresh optional suggestion.
State machine
Typical states:
discoveryplanningplan-reviewimplementationcode-reviewdistilldone
At each transition, restate:
- current state
- active phase team
- exit criteria
- next owner
Do not
- keep all phase teams alive from the start
- spawn reviewers before their reviewed artifact exists
- collapse all review phases into one generic reviewer
- let chat memory replace packet artifacts
- let planner implement
- let implementer rewrite the plan silently
- write tracked
AGENTS.mddirectly - skip orderly phase-team shutdown
- aggressively poll teammates every few seconds
- substitute frantic status checking for normal asynchronous waiting
Initiative mode
Atelier operates in two modes. Choose one explicitly at the start:
single-task— direct task-packet path (grill-me->plan-task->review-plan->implement-task-> reviews ->distill-knowledge)initiative— parent initiative plus child task packets
Use initiative when discovery produces:
- too much shared context for one healthy
PLAN.md - multiple child-worthy workstreams
- cross-repo or cross-boundary coordination needs
Initiative phase order is exact:
grill-meframe-initiativestabilize-initiative-language- optional
design-split-options split-initiativereview-initiative-splithydrate-child-packet- per-child local loop (
grill-meoptional,design-child-contractoptional,plan-task,review-plan,implement-task,review-code-plan-satisfaction,review-code-maintainability,extract-artifact-candidates) sync-initiative- final
distill-knowledge
Initiative orchestration rules:
- do not hydrate a child until split review is
ready - run children in dependency order from
TASK_GRAPH.md - only children with satisfied dependencies and child status
readyare eligible to start - each child row must declare
Packet Root; hydrate the child packet there and run the child-local loop from that repo by default - the parent initiative packet stays in the orchestrating repo even when child packets live elsewhere
- packet-state mutations belong to packet writers; orchestrator chooses the next phase but does not invent parallel packet-state semantics
- if the orchestrator is entered directly on a hydrated child packet that already declares
Parent initiative, that is still initiative mode; do not silently downgrade tosingle-task - initiative-child preflight is mandatory before planning:
- resolve the declared parent initiative path
- verify the parent packet exists and is writable in the current environment
- if validation fails, block and ask the human how to proceed instead of running to local closeout and declaring success
- after a child local loop finishes, run
sync-initiativebefore starting the next child - do not treat child-local distill/no-op as final completion while parent sync is still
pendingorblocked - if parent sync cannot run because the parent packet is missing/unavailable, require an explicit human decision before closeout
- after
sync-initiative, move to the next eligiblereadychild or finish with finaldistill-knowledge - durable distill follows residue ownership and may require separate passes in different repos before final closeout
Notification points in initiative mode:
- initiative framing started / complete
- language stabilization complete
- split review failed / passed
- child hydration started
- child plan review failed / passed
- implementation started
- code review failed / passed
- sync started / complete
- final distill started / complete
- any human decision needed
When reporting initiative-child progress, always include parent sync state: pending, blocked, or complete.
If parent sync is blocked by a missing or stale parent path, notify the human promptly and ask for the exact routing decision needed.
Communication
Honor active caveman mode for user-facing replies per ../../references/communication-mode.md. Keep durable artifacts normal unless the human asks otherwise. Drop caveman for safety/clarity when needed, then resume.
References
See REFERENCE.md for runtime team naming, predefined agent names, and example team_create / spawn_teammate flows.