SuperAPI AI Directory

spec-flow

General & other

View repository

Updated 10-16 09:31

About this skill

Spec Flow

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.json and each spec's progress.json as the single source of state.
  • Treat spec.md、plan.md、acceptance-report.md、archive-summary.md as business artifacts.
  • Treat slash commands as the only user entry point, and the runtime as the only state writer.

Start Here

  1. Check whether the workspace already has .specs/bin/spec-flow.mjs。
  2. If not, first execute /spec-flow init, and land assets/runtime/spec-flow-runtime.mjs as the workspace runtime.
  3. Choose an action based on the current task, rather than mechanically advancing through stages.
  4. When persistence is needed, update state only through node .specs/bin/spec-flow.mjs ... .
  5. 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.md and plan.md。
  • Use deep analysis for complex tasks, but do not enter implement。
  • For new tasks, use runtime new to create a spec; for major revisions, use runtime amend to bump the version.
  • For detailed rules, see references/action-plan.md。

implement

  • Read the current spec.md、plan.md and progress.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-reviewer agent; 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 runtime accept to 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;accept after 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.json or any progress.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.md to confirm the CLI conventions.
  • Before writing any document, first look at references/spec-schema.md to confirm the minimal structure.
  • Each time you resume interrupted work, first look at references/recovery-rules.md。

Templates And Assets

Tool Strategy

  • For local exploration, prioritize reading workspace files.
  • For external research, prioritize using the process defined in the agents/external-resource-explorer agent.
  • For third-party libraries or standards, prioritize using context7; for general best practices, prioritize using exa; 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".