Maintain the spec lifecycle of a long-term task in an action-first way.
Write business content into spec.md / plan.md / report templates, and leave state updates to the workspace runtime to avoid losing context after a session is interrupted.
Core Model
- Fix the lifecycle as
explore -> plan -> implement -> accept -> archive。 - Split the state into
status、currentAction、runState, and do not fall back to a multi-stage large state machine. - Treat
.specs/registry.jsonand each spec'sprogress.jsonas the single source of state. - Treat
spec.md、plan.md、acceptance-report.md、archive-summary.mdas business artifacts. - Treat slash commands as the only user entry point, and the runtime as the only state writer.
Start Here
- Check whether the workspace already has
.specs/bin/spec-flow.mjs。 - If not, first execute
/spec-flow init, and landassets/runtime/spec-flow-runtime.mjsas the workspace runtime. - Choose an action based on the current task, rather than mechanically advancing through stages.
- When persistence is needed, update state only through
node .specs/bin/spec-flow.mjs .... - When a template is needed, use the template files under
assets/to create or overwrite documents.
Action Router
explore
- First collect goals, constraints, existing materials, and gaps.
- Prioritize exploring the local workspace; conduct external research only when local materials are insufficient, third-party specifications are involved, or the user explicitly requests it.
- When exploration results need to be retained across sessions, create a draft spec instead of jumping directly into implement.
- For detailed rules, see
references/action-explore.md。
plan
- Converge exploration conclusions into a formal
spec.mdandplan.md。 - Use deep analysis for complex tasks, but do not enter
implement。 - For new tasks, use runtime
newto create a spec; for major revisions, use runtimeamendto bump the version. - For detailed rules, see
references/action-plan.md。
implement
- Read the current
spec.md、plan.mdandprogress.json, and start from the current step or the next step to be executed. - Write a checkpoint after completing each step; if a major deviation is found, return to
plan, and do not secretly change the state. - This action applies not only to code, but also to documents, research, processes, and operational artifacts.
- For detailed rules, see
references/action-implement.md。
accept
- Use an independent context to judge whether the artifact satisfies the spec; do not let the implementer self-evaluate.
- Prefer using a dedicated
agents/spec-acceptance-revieweragent; if the current environment does not support delegation, simulate independent acceptance in this thread and strictly follow findings-first. - After writing
acceptance-report.md, call runtimeacceptto persist the state. - For detailed rules, see
references/action-accept.md。
archive
- First confirm the acceptance result or that the user explicitly accepts forced archiving, then generate
archive-summary.md。 - The archive action performs directory migration and registry updates only through runtime
archive. - Delayed archiving is allowed;
acceptafter passing, immediate archiving in the same session is not required. - For detailed rules, see
references/action-archive.md。
Query Commands
status and resume are runtime query commands rather than lifecycle actions—the five-action model remains pure.
For rules, see references/recovery-rules.md。
Runtime Rules
- Never manually modify
.specs/registry.jsonor anyprogress.json。 - Never merely claim in markdown that a certain state has changed without writing to the runtime.
- Always let the runtime handle spec ID generation, version incrementing, archive migration, and atomic writes.
- Before executing any command, first look at
references/command-contract.mdto confirm the CLI conventions. - Before writing any document, first look at
references/spec-schema.mdto confirm the minimal structure. - Each time you resume interrupted work, first look at
references/recovery-rules.md。
Templates And Assets
assets/spec-template.md: Formal spec template.assets/plan-template.md: Executable plan template.assets/acceptance-report-template.md: Findings-first acceptance report template.assets/archive-summary-template.md: Archive summary template.assets/runtime/spec-flow-runtime.mjs: Workspace status runtime template.
Tool Strategy
- For local exploration, prioritize reading workspace files.
- For external research, prioritize using the process defined in the
agents/external-resource-exploreragent. - For third-party libraries or standards, prioritize using
context7; for general best practices, prioritize usingexa; only fall back to ordinary search when neither is available. - For complex planning or major amendments, prioritize structured deep thinking; when unavailable, degrade to conventional deep analysis.
Guardrails
- Treat action as a semantic label for the current work; do not repackage it as an implicit 11-phase process.
- Make acceptance results centered on issues and evidence; do not degrade to giving only a score.
- Let the runtime manage only state; do not let it drive business document content.
- Make the archive summary retain unfinished items, remaining risks, and key changes; do not write only "completed".