Skip to content

docs: document evolving specs in existing projects#2902

Open
WOLIKIMCHENG wants to merge 2 commits into
github:mainfrom
WOLIKIMCHENG:docs/evolving-specs-existing-projects
Open

docs: document evolving specs in existing projects#2902
WOLIKIMCHENG wants to merge 2 commits into
github:mainfrom
WOLIKIMCHENG:docs/evolving-specs-existing-projects

Conversation

@WOLIKIMCHENG

@WOLIKIMCHENG WOLIKIMCHENG commented Jun 9, 2026

Copy link
Copy Markdown
Contributor

Description

Closes #916.

Documents how existing projects can evolve specs over time using the persistence models introduced in the Spec Persistence Models guide. The update moves the brownfield workflow into a dedicated Evolving Specs guide and links to it from the README and SDD concepts page.

Scope:

  • Adds docs/guides/evolving-specs.md with guidance for flow-forward, living spec, and flow-back workflows.
  • Keeps Spec Kit project-file updates separate from feature artifact evolution.
  • Updates README, SDD concepts, docs TOC, and DocFX content globs.
  • Removes the brownfield workflow section from the upgrade guide.

Non-goals:

  • No CLI behavior changes.
  • No new specify update command.
  • No template, script, or extension changes.

Testing

  • git diff --check
  • python -m json.tool docs/docfx.json
  • Parsed docs/toc.yml and checked updated local docs links/anchors

@WOLIKIMCHENG WOLIKIMCHENG requested a review from mnriem as a code owner June 9, 2026 05:12
@mnriem

mnriem commented Jun 9, 2026

Copy link
Copy Markdown
Collaborator

Thanks for tackling this — the gap you're addressing is real, and the step-by-step workflow is useful.

Since this PR was opened, #2856 landed on main introducing the spec persistence models page (flow-back, flow-forward, living). Your brownfield guidance should build on that vocabulary rather than existing independently.

Requested changes:

  1. Rebase onto main to pick up docs: document spec persistence models #2856.

  2. Move the new content out of upgrade.md into docs/guides/evolving-specs.md. The upgrade guide is about refreshing Spec Kit tooling — evolving your specs is a different workflow.

  3. Structure the guide around the three persistence models. One document, three sections — each with clear steps for that model:

    • Flow-forward: create a new feature directory, run the standard specify → plan → tasks → implement flow.
    • Living spec: edit spec.md first, then regenerate plan.md and tasks.md from it.
    • Flow-back: edit wherever the insight lands, then reconcile the artifact set.
  4. Drop or consolidate the sdd.md addition — that file already links to the persistence-models page. A single sentence there pointing to your new guide is enough.

  5. Keep the README.md addition but update the link target to the new guide path.

  6. Add the new page to docs/toc.yml under a Development or Guides section.

The scope stays docs-only and the core content you wrote (the step-by-step workflow) remains — it just gets framed per-model so readers with different conventions get tailored guidance.

@WOLIKIMCHENG WOLIKIMCHENG force-pushed the docs/evolving-specs-existing-projects branch from 73aa021 to 15c46be Compare June 10, 2026 02:16
@WOLIKIMCHENG

WOLIKIMCHENG commented Jun 10, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the detailed review. I've updated the PR to build on the spec persistence models and moved the brownfield guidance into docs/guides/evolving-specs.md. The guide is now organized around flow-forward, living spec, and flow-back, with the README, SDD concepts page, docs TOC, and DocFX content globs updated accordingly.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Establish best practices for evolving specs as features are added to existing projects

2 participants