Lifecycle States
How a spec moves across state folders, and what the transition command does and does not check.
A spec's state is expressed twice: by the folder it sits in and by the Status field of its header. The CLI keeps both in step.
State mapping
| Folder | Status | Act | Set by |
|---|---|---|---|
specs/draft/ | Draft | I | iniciar_spec.mjs |
specs/defined/ | Defined | I → II | $fireskill-04-validate when the Definition Gate passes |
specs/planned/ | Planned | II | $fireskill-05-tasks when the Plan Gate passes |
specs/in-progress/ | Implementing | III | $fireskill-07-implement before the first production change |
specs/review/ | Reviewing | III | $fireskill-07-implement when the Delivery Gate passes |
specs/completed/ | Complete | III | $fireskill-04-validate, at the final acceptance |
The transition command
bun run fireskill transition <NNNN>-<slug> <folder>
For example:
bun run fireskill transition 0001 defined
Real output: 0001-convite-de-membros-por-e-mail draft → defined Defined.
What it does:
- Finds the spec by its number (
0001) or its full directory name (<NNNN>-<slug>); an unknown identifier fails withspec not found. - Accepts only the moves in the table below; anything else fails with
invalid transition: <from> to <to>. - Rewrites the
Statusline ofspec.mdand moves the whole package (withresearch/) to the destination folder. - Refuses to overwrite an existing destination.
- Refreshes the milestone index afterwards (the same as
milestones sync).
What it does not do: it does not read or check the gates. A spec whose Definition Gate is Pending can be moved to defined. The gates are the responsibility of the skills, which move the spec only after their gate passes.
| From | Allowed destinations |
|---|---|
draft | defined |
defined | draft, planned |
planned | defined, in-progress |
in-progress | planned, review |
review | in-progress, completed |
completed | review |
bun run fireskill migrate moves specs from the previous layout (specs/specs/) into these folders, once.
What each state means
- Draft: the spec is being written. Problem, actors, requirements and scenarios are still being settled.
- Defined: the Definition Gate passed. The scope is locked for planning.
- Planned: the Plan Gate passed. Tasks exist and the tests fail for the right reason (RED).
- In progress: implementation. Specialists are loaded, code is written until the tests are green, visual reviews happen.
- Review: the Delivery Gate passed; final acceptance is pending. Here you may run
$fireskill-the-judgeon the diff. - Completed: accepted. Evidence, documentation and Definition of Done are recorded.
Going back
Going back happens through $fireskill-update-spec, which sets the status and gates that the change invalidates (see Quality Gates) and then uses the allowed backward moves above.
Ready to build and launch your SaaS?
Get 100% full source code ownership, zero proprietary wrappers, and architecture engineered for millions of requests on Cloudflare.