State Machine

The canonical workflow metadata lives in shared/workflowMeta.ts, and the executable transition rules live in server/machines/ticketMachine.ts.

Use this page for the phase inventory and transition model. Use Ticket Flow for the end-to-end lifecycle narrative and artifact story.

Workflow Groups

Group id	Label
todo	To Do
discovery	Discovery
interview	Interview
prd	Specs (PRD)
beads	Blueprint (Beads)
pre_implementation	Pre-Implementation
implementation	Implementation
post_implementation	Post-Implementation
done	Done
errors	Errors

Phase Inventory

Phase	Label	Group	uiView	Review artifact	Editable	Multi-model logs	Progress kind
DRAFT	Backlog	todo	draft	—	yes	no	—
SCANNING_RELEVANT_FILES	Scanning Relevant Files	discovery	council	—	yes	no	—
COUNCIL_DELIBERATING	Council Drafting Questions	interview	council	—	yes	yes	—
COUNCIL_VOTING_INTERVIEW	Voting on Questions	interview	council	—	yes	yes	—
COMPILING_INTERVIEW	Refining Interview	interview	council	—	yes	no	—
WAITING_INTERVIEW_ANSWERS	Interviewing	interview	interview_qa	—	yes	no	questions
VERIFYING_INTERVIEW_COVERAGE	Coverage Check (Interview)	interview	council	—	yes	no	—
WAITING_INTERVIEW_APPROVAL	Approving Interview	interview	approval	interview	yes	no	—
DRAFTING_PRD	Council Drafting Specs	prd	council	—	yes	yes	—
COUNCIL_VOTING_PRD	Voting on Specs	prd	council	—	yes	yes	—
REFINING_PRD	Refining Specs	prd	council	—	yes	no	—
VERIFYING_PRD_COVERAGE	Coverage Check (PRD)	prd	council	—	yes	no	—
WAITING_PRD_APPROVAL	Approving Specs	prd	approval	prd	yes	no	—
DRAFTING_BEADS	Council Drafting Blueprint	beads	council	—	yes	yes	—
COUNCIL_VOTING_BEADS	Voting on Blueprint	beads	council	—	yes	yes	—
REFINING_BEADS	Refining Blueprint	beads	council	—	yes	no	—
VERIFYING_BEADS_COVERAGE	Coverage Check (Beads)	beads	council	—	yes	no	—
WAITING_BEADS_APPROVAL	Approving Blueprint	beads	approval	beads	yes	no	—
PRE_FLIGHT_CHECK	Checking Readiness	pre_implementation	coding	—	yes	no	—
WAITING_EXECUTION_SETUP_APPROVAL	Approving Workspace Setup	pre_implementation	approval	execution_setup_plan	yes	no	—
PREPARING_EXECUTION_ENV	Preparing Workspace Runtime	pre_implementation	coding	—	no	no	—
CODING	Implementing (Bead ?/?)	implementation	coding	—	no	no	beads
RUNNING_FINAL_TEST	Testing Implementation	post_implementation	coding	—	no	no	—
INTEGRATING_CHANGES	Preparing Final Commit	post_implementation	coding	—	no	no	—
CREATING_PULL_REQUEST	Creating Pull Request	post_implementation	coding	—	no	no	—
WAITING_PR_REVIEW	Reviewing Pull Request	post_implementation	coding	—	no	no	—
CLEANING_ENV	Cleaning Up	post_implementation	coding	—	no	no	—
COMPLETED	Done	done	done	—	no	no	—
CANCELED	Canceled	done	canceled	—	no	no	—
BLOCKED_ERROR	Error (reason)	errors	error	—	no	no	—

Transition Model

What The Diagram Emphasizes

• Approval gates are explicit workflow states, not transient UI overlays.
• The interview loop returns to user input when coverage finds gaps.
• PRD and beads coverage stay inside their own phase groups and revise automatically until clean or capped.
• CODING is intentionally self-looping because bead completion may just advance to the next runnable bead.
• Delivery is part of the machine: final test, integration, PR creation, PR review, and cleanup are all first-class states.

Safe Resume Model

Each non-terminal ticket stores both the durable ticket status and the serialized XState snapshot. On backend startup, LoopTroop validates the stored snapshot before starting an actor:

• valid snapshots are rehydrated and immediately processed, so active phases continue without waiting for a new state-change event
• missing snapshots for active tickets are reconstructed from the durable ticket status and persisted back to storage
• corrupt or impossible snapshots for active tickets move the ticket to BLOCKED_ERROR instead of silently restarting from DRAFT
• terminal tickets remain terminal and do not restart work

This keeps browser reloads, frontend reconnects, backend restarts, and OpenCode reconnect gaps from changing the workflow phase behind the user's back. The user should return to the same ticket status, or to an explicit blocked state with a retry/cancel decision.

Retry Semantics

BLOCKED_ERROR is special:

• it stores the failed state as previousStatus
• RETRY returns to that exact state, not to a generic restart point
• the retry target can be a planning phase, an approval phase, or any execution-band phase
• RETRY is rejected when previousStatus is missing, because there is no safe phase to re-enter
• CODING retry must first restore the failed bead and reset the worktree to its bead-start commit before execution can safely re-enter

This is why BLOCKED_ERROR has a dedicated errors group even though it can be reached from planning, implementation, or delivery. It is the system-wide manual recovery gate.

UI Consequences

The workflow metadata directly drives frontend behavior:

• uiView decides which workspace component renders
• reviewArtifactType decides which approval editor loads
• progressKind controls question or bead progress displays
• editable controls whether a phase can still be modified
• multiModelLogs determines whether the UI expects multi-member council logs

That is why docs that drift away from workflowMeta.ts quickly become misleading.

Related Docs

• Ticket Flow
• Frontend
• Context Isolation
• System Architecture