Skip to content

evolving-specs.md

Latest commit

 

History

History
90 lines (68 loc) · 3.88 KB

evolving-specs.md

File metadata and controls

90 lines (68 loc) · 3.88 KB

Evolving Specs in Existing Projects

Existing projects need two separate maintenance loops:

  • Spec Kit project-file updates refresh managed commands, scripts, templates, and shared memory files.
  • Feature artifact evolution keeps repository-specific specs/ artifacts aligned with the code and product behavior you intend to ship.

Use the upgrade workflow when you need newer Spec Kit project files. Use one of the artifact persistence models below when requirements or implementation insights change an existing project.

For the conceptual model definitions, see Spec Persistence Models.

Flow-Forward Spec

Use flow-forward when each feature directory should remain a historical record.

When you add another feature or make a substantial follow-up change, create a new feature spec through your installed /speckit.specify command and continue through the standard flow:

  1. Run /speckit.specify to create a new feature directory under specs/.
  2. Run /speckit.plan to define the implementation approach.
  3. Run /speckit.tasks to derive the work breakdown.
  4. Run /speckit.implement and review the resulting code and artifact diffs.

The previous feature directory remains intact for audit, comparison, or explaining how the project reached its current state. Use clear feature names or cross-links when a new directory supersedes or extends earlier work.

Living Spec

Use living spec when spec.md is the contract and plan.md and tasks.md are derived from it.

When intended behavior changes, revise the existing spec.md first. Then regenerate or manually revise downstream artifacts so they match the updated spec:

  1. Start from a clean working tree or a dedicated branch so every generated change is reviewable.
  2. Update spec.md with /speckit.clarify or an explicit edit.
  3. Rerun /speckit.plan or revise plan.md so the technical approach matches the revised spec.
  4. Rerun /speckit.tasks or revise tasks.md so implementation work matches the revised plan.
  5. Run /speckit.analyze before implementation resumes to catch gaps between the spec, plan, and tasks.
  6. Run /speckit.implement, then review the code and artifact diffs together.

Preserve important implementation rationale before replacing derived artifacts. If a plan or task list contains decisions that still matter, carry them forward explicitly.

Flow-Back Spec

Use flow-back when implementation discoveries are allowed to reshape the artifact set.

In this model, the first useful edit can happen wherever the insight lands: spec.md, plan.md, tasks.md, or the implementation. After the change, bring the artifact set back into alignment:

  1. Capture the discovery in the artifact closest to the work.
  2. Decide whether it changes intended behavior, implementation strategy, task breakdown, or only code.
  3. Update any other artifacts that now disagree with the accepted direction.
  4. Run /speckit.analyze to check for gaps across spec.md, plan.md, and tasks.md.
  5. Continue implementation only after the artifact set describes the behavior and approach you want future contributors to trust.

Flow-back is flexible, but it requires discipline. Do not leave a lower-level change in tasks.md or code if spec.md still says something different and the spec is meant to remain trustworthy.

Before Updating Spec Kit Project Files

Before refreshing Spec Kit project files with the terminal command specify init --here --force --integration <your-agent>, protect any project-specific material that lives outside specs/, especially .specify/memory/constitution.md and customized files under .specify/templates/ or .specify/scripts/. Use <your-agent> for the AI coding agent integration used by the target project.

Your specs/ directory is not part of the template package, but shared project files can be overwritten by a forced refresh.