Problem

When spec-kit is initialized in an existing project, there's no clear workflow for keeping specs synchronized as new features are developed. Users report that re-running specify init overwrites user-modified files (like constitution.md), and manually managing spec updates becomes error-prone at scale.

This is particularly problematic for brownfield projects where development continues iteratively post-initialization.

Current Pain Points

• Re-running specify init --here to get latest templates overwrites customized configuration
• No documented workflow for incrementally adding feature specs without regenerating everything
• Specs diverge from codebase as the project evolves
• Unclear how to keep templates/prompts in sync with spec-kit releases while preserving project-specific changes
• Related issues: How to update to the latest spec-kit prompts? #785, Easiest way and best practice to update to the new release once I have spec-kit installed and running in my project #324, Document how to update spec-kit or add an update CLI command/script #361

Desired Outcome

Establish and document a sustainable pattern for evolving specs throughout a project's lifecycle, including:

1. Preservation Strategy

• Identify which files should never be overwritten (constitution.md, project-specific specs)
• Define which files should be updated automatically (templates, prompts)
• Provide tooling or clear manual steps for safe updates

2. Feature Evolution Workflow

• Step-by-step guide: initialize spec-kit → build features → add new feature specs
• How to write new specs when repository has evolved since initialization
• Handling existing code/features when writing new specs

3. Versioning & Updates

• How to upgrade spec-kit without destroying project state
• Suggested update frequency and triggers
• Rollback procedures if needed

4. Tooling

• Consider specify update CLI command (alternative: clear documentation)
• Safe merge strategy for template updates
• Validation that specs stay aligned with constitution

Acceptance Criteria

• Documented workflow for adding feature specs post-initialization
• Guidelines on preserving vs. updating .specify/ contents during upgrades
• Example: Adding a second feature to a project initialized with one feature
• Decision: update CLI command vs. documented manual process
• Update README "Development phases" to emphasize iterative enhancement workflow

Related Issues

• Document how to update spec-kit or add an update CLI command/script #361 - Document how to update spec-kit
• How to update to the latest spec-kit prompts? #785 - How to update to latest spec-kit prompts
• Easiest way and best practice to update to the new release once I have spec-kit installed and running in my project #324 - Best practices for updating to new release
• Discussion Evolving specs #152 - Evolving specs and keeping them in sync