Specification States

State machine reference for specifications — all 10 states, transitions, and rules.

Every specification moves through a lifecycle of 10 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)
`specifying`	Keep linking (dependencies, blueprints)
`validating`	Review findings, fix gaps
`ready`	Start implementation — launch your agent
`in_progress`	Monitor dashboard, resolve blocks
`ready_for_review`	Trigger Implementation Review
`in_review`	Wait for results, address findings
`reviewed`	Confirm completion
`completed`	Done 🎉

States

State	Phase	Description
`draft`	Planning	Initial state. Specification created but no planning started.
`planning`	Planning	Epics and tickets are being defined. Structural work in progress.
`specifying`	Planning	Dependencies, blueprints, and cross-epic links are being established.
`validating`	Planning	Quality checks running. Reports evaluating completeness and consistency.
`ready`	Planning	Planning complete. Specification passed the Planning Review gate.
`in_progress`	Implementation	Work sessions active. Tickets being implemented.
`ready_for_review`	Implementation	All tickets completed. Specification awaiting review.
`in_review`	Implementation	Implementation Review in progress. Quality gates being evaluated.
`reviewed`	Implementation	Review passed. All quality checks satisfied.
`completed`	Implementation	All work finalized. Specification is closed.

Transition Table

Trigger	From	To	Condition
Epic created	`draft`	`planning`	First epic added
Ticket created	`draft`	`planning`	First ticket added
Dependency added	`planning`	`specifying`	Dependency or blueprint operation performed
Blueprint linked	`planning`	`specifying`	Blueprint attached to an epic
Report requested	`specifying`	`validating`	Report or quality check triggered
Epic created	`specifying`	`planning`	Structural change during specifying
Epic created	`validating`	`planning`	Structural change during validating
Ticket created	`specifying`	`planning`	Structural change during specifying
Ticket created	`validating`	`planning`	Structural change during validating
Dependency added	`validating`	`specifying`	Linking change during validating
Planning review passed	`validating`	`ready`	Planning gate passes threshold
Planning review passed	`planning`	`ready`	Planning gate passes (if invoked directly)
Planning review passed	`specifying`	`ready`	Planning gate passes (if invoked directly)
Work session started	`ready`	`in_progress`	First `start_work_session` call
All tickets completed	`in_progress`	`ready_for_review`	Every ticket reaches `done`
Review started	`ready_for_review`	`in_review`	`start_review_session` called
Review passed	`in_review`	`reviewed`	Implementation gate passes
Completion confirmed	`reviewed`	`completed`	Final confirmation
All tickets completed (no review)	`in_progress`	`completed`	All tickets done and `requireImplementationReview` is `false`
Specification reopened	`completed`	`in_progress`	`reopen_specification` called
Specification reopened	`reviewed`	`in_progress`	`reopen_specification` called

The Planning Corridor

The three states planning, specifying, and validating form the planning corridor. Transitions within this corridor happen automatically based on the type of operation you perform:


planning <---> specifying <---> validating

Structural operations (create epics, create tickets, delete epics) → move to planning
Linking operations (add dependencies, link blueprints) → move to specifying
Evaluation operations (request reports, run checks) → move to validating

You don’t manually advance through these states. SpecForge tracks the nature of your operations and transitions accordingly. The corridor is designed for iterative refinement — freely alternate between creating structure, linking dependencies, and checking quality.

ℹ️ You can call Planning Review from any state in the corridor. If it passes, the specification exits the corridor to ready regardless of whether it was in planning, specifying, or validating.

Auto-Transitions

Several transitions happen automatically without explicit user action:

Event	Transition	Description
First epic or ticket created	`draft` → `planning`	Specification enters the planning corridor
Planning review passed	corridor → `ready`	Specification cleared for implementation
All tickets reach `done`	`in_progress` → `ready_for_review`	Triggered when the last ticket completes
All tickets done (review disabled)	`in_progress` → `completed`	When `requireImplementationReview` is `false`

Protected States

Once a specification reaches ready, it does not automatically regress to a planning state. 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 ready requires reopen_specification. Any in-progress work sessions must be completed or reset first.