Status	Last updated	Parent	Read before this
complete	2026-04-30	Design - Architecture Overview	Contract - Phase Outcome

The Orchestrator

Current state

The orchestrator is whoever consumes Contract - Phase Outcome and resolves Pending Decisions. Its contract is:

• Read each Phase Outcome a skill emits.
• For every Pending Decision, choose an option (or accept the recommended one) and post the resolution as a comment on the issue, referencing the decision ID.
• Advance the issue's status when all blocking decisions are resolved, so the next skill can run.
• Decide when to invoke the next skill (manually or via automation).

The orchestrator does not write code, evaluate findings, or generate artifacts. It chooses among options that skills proposed.

Today, the orchestrator is a human PM or tech lead, working through the forge UI or driving an interactive Claude Code session that reads the Phase Outcome and asks the human for a decision.

Tomorrow, the orchestrator may be agentic for routine decisions — approving a Phase Outcome whose recommended option is unambiguous, deferring low-priority findings to the backlog automatically, escalating to a human only when something genuinely needs judgement. The dashboard work happening alongside devwork-skills is part of this trajectory.

Rationale

Lifting the orchestrator out of the skills was the change that made everything else pluggable. When approval gates lived inside skills as interactive prompts, "who decides" was hardcoded as "the human running the terminal." Externalising decisions through Phase Outcomes turns "who decides" into a separate concern that can be a person today, a UI tomorrow, an agent the day after — without rewriting any skill.

The orchestrator's contract is deliberately narrow. It chooses among options; it doesn't generate them. This bounds the trust required to let an agent take the role: an agentic orchestrator can only pick among options the skill already considered safe enough to surface. That's a much lower bar than "agent reasons freely about what to do next."

The "blocking decisions block pipeline advancement" rule is what stops orchestrators from silently dropping decisions. A skip becomes an explicit choice ("accept and continue") rather than a missed step. This matters most when the orchestrator is an agent — silent drops would be invisible failure modes.

Open questions

• The exact mechanism for an agentic orchestrator to make decisions safely (what models, what guardrails, what audit trail) is undetermined. The current Phase Outcome shape is rich enough to support either; the dashboard work will surface the requirements.