Specification States
State machine reference for specifications — all 5 states, transitions, and rules.
Every specification moves through a lifecycle of 5 states. Transitions are triggered by user actions, tool calls, and automatic evaluations.
Quick Reference
| State | You should… |
|---|---|
draft | Start planning — create your first epic or ticket |
planning | Keep building structure (epics, tickets, dependencies, blueprints) |
ready | Start implementation — launch your agent |
in_progress | Monitor dashboard, resolve blocks |
done | Done 🎉 |
States
| State | Phase | Description |
|---|---|---|
draft | Planning | Initial state. Specification created but no planning started. |
planning | Planning | Epics, tickets, dependencies, and blueprints are being defined. The planning session advances through its own phases while the specification stays in planning. |
ready | Planning | Planning complete. Specification passed the Planning Review gate. |
in_progress | Implementation | Work sessions active. Tickets being implemented. |
done | Implementation | All tickets complete. Specification is closed. This is the terminal state. |
Transition Table
| Trigger | From | To | Condition |
|---|---|---|---|
| Epic created | draft | planning | First epic added |
| Ticket created | draft | planning | First ticket added |
| Planning review passed | planning | ready | Planning gate passes threshold inside complete_planning_session |
| Work session started | ready | in_progress | First start_work_session call |
| All tickets completed | in_progress | done | Every ticket reaches done |
| Specification reopened | done | in_progress | reopen_specification called |
The planning State
A specification has a single planning state — there is no corridor of auto-transitioning planning sub-states at the specification level. All structural work (creating epics, creating tickets, adding dependencies, linking blueprints) happens while the specification sits in planning.
The 7-phase planning machine — planning_spec, epic_decomposition, epic_expansion, ticket_decomposition, ticket_expansion, cross_validation, planned — advances on the PlanningSession, not on the specification. The specification stays in planning for the whole session and moves to ready only when the session’s Planning Review gate passes inside complete_planning_session.
ℹ️ You don’t manually advance the specification through planning. Drive the planning session with
action_planning_sessionoperations; the session tracks the phase and the specification advances toreadywhen the gate passes.
Auto-Transitions
Several transitions happen automatically without explicit user action:
| Event | Transition | Description |
|---|---|---|
| First epic or ticket created | draft → planning | Specification enters planning |
| Planning review passed | planning → ready | Specification cleared for implementation |
All tickets reach done | in_progress → done | Triggered when the last ticket completes |
Protected States
Once a specification reaches ready, it does not automatically regress to planning. This protection ensures validated plans remain stable during implementation.
To make structural changes to a ready specification, you must explicitly reopen the planning session — a deliberate action that acknowledges the specification needs revalidation.
⚠️ Reopening a specification past
readyrequiresreopen_specification. Any in-progress work sessions must be completed or reset first.
See Also
- Ticket States — Ticket state machine and auto-calculation rules
- Lifecycles — The two lifecycles that drive these transitions
- Quality Gates — The gates that trigger state advances