docs(spec): add spec evolution guidance — V1 scoping and delta specs

[ayobamiseun]

Summary

Answers two long-open user questions about what happens to a spec after V1:

• Recommended way to handle V2 features without polluting V1 spec? #150 — should the spec mark itself as a V1 and mention the V2 backlog, and what's the workflow for V2 features (e.g. SQLite → PostgreSQL, manual step → OCR) after /build and /ship?
• Support for multiple/parallel specs #180 (workflow half) — /spec writes a single global SPEC.md, which gets overwritten when you spec something else.

Closes #150

What changed

skills/spec-driven-development/SKILL.md

• The spec template gains an Out of Scope (Deferred) section — V2 ideas are captured in the spec without expanding V1, and the V1 boundary becomes enforceable during implementation (answering Recommended way to handle V2 features without polluting V1 spec? #150's first question directly).
• New Spec Evolution: V1 Scoping and Follow-Up Changes section: once a spec has shipped, a change gets its own small delta spec (objective / current behavior / new behavior / success criteria / boundary deltas), saved alongside the original (SPEC-postgres-migration.md next to SPEC.md), run through the same gated workflow, and folded back into the original after shipping — the original spec always describes the current system, delta specs describe transitions (answering Recommended way to handle V2 features without polluting V1 spec? #150's second question).
• Two new rationalization rows, two red flags, and two verification items covering mid-build scope creep and "the feature already has a spec" changes.

.claude/commands/spec.md + .gemini/commands/spec.toml (kept in parity; validate-commands passes)

• One guard line: if SPEC.md exists and the request is a change to what it describes, write a delta spec instead of overwriting. This fixes the overwrite pain in Support for multiple/parallel specs #180 at the workflow level.

evals/cases/spec-driven-development.json

• Frontmatter description gains the evolution vocabulary ("shipped spec", "V1", "V2 backlog", "follow-up spec"), and two positive trigger prompts phrased the way the issue authors actually asked verify it routes:
  • "We shipped the V1 we specced — how do I spec the V2 features we deferred?"
  • "This feature already has a spec, but now we want OCR instead of the manual step — spec that change before building"

Non-overlap check

• Feature: Standardize spec directory structure to prevent overwriting #73 (spec directory restructuring, stale since April) is the other approach to Support for multiple/parallel specs #180's storage question. This PR deliberately stays out of that territory — no directory conventions changed, just "don't overwrite; write a delta file". If Feature: Standardize spec directory structure to prevent overwriting #73 revives, the delta-spec guidance composes with any directory layout it picks.
• No other open PR touches the Spec Evolution topic; feat: replace plain-text confirmations with question tool in 10 skills #195 and docs(skills): add WHEN: trigger phrases to 20 skill descriptions #175 touch this SKILL.md for unrelated reasons (confirmation UX, trigger phrasing) with no line overlap in the sections edited here.

Verification

Rebased on current main (6bcfeb9), all tiers green locally:

• validate-skills.js — 24 skills, 0 errors
• validate-commands.js — 8 commands, parity holds across Claude/Gemini twins
• run-evals.js — 126 checks passed, 0 errors; both new trigger prompts route within top-3; rank-1 rate unchanged at 85%

[addyosmani]

I like this one a lot. V1-scoping-with-a-V2-delta is a real question people hit the moment a spec survives contact with a second feature, and answering #150 and #180 inside the spec skill itself is the right home for it rather than a separate doc. Nice that you kept the command files in parity and shipped an eval case with it, that's the bar now. Let me read the guidance end to end to make sure it doesn't bloat the spec flow, but this is on-mission and close to a yes.

[federicobartoli]

Could we mirror this guard in commands/spec.toml too? Antigravity still instructs the agent to always overwrite SPEC.md; validate-commands does not compare prompt bodies.

[ayobamiseun]

Good catch — I'd missed that commands/ is a third twin and that validate-commands only diffs presence/descriptions, not bodies. Added the same guard line to commands/spec.toml in ce60dbc.

[federicobartoli]

Could we align this filename with the downstream workflow? /build auto only recognizes SPEC.md, docs/SPEC.md, or files under spec/, and does not allow root-level SPEC-*.md files as uncommitted planning artifacts. It may therefore select the old spec or stop at the clean-baseline check.

[ayobamiseun]

Confirmed on both counts: discovery wouldn't select a root-level delta spec, and the clean-baseline check would stop on it. Rather than move delta specs into spec/ (which would drift into #73's storage-convention territory), ce60dbc updates all three /build twins: a root-level SPEC-<change>.md is now an accepted spec path (taking precedence over SPEC.md when the run is building that follow-up change) and SPEC-*.md is included in the planning-artifact exclusions. SKILL.md now states the convention is recognized downstream.

[federicobartoli]

How should a delta spec satisfy the existing “covers all six core areas” verification? This template intentionally omits Commands, Project Structure, Code Style, and Testing Strategy. Could the verification distinguish full specs from delta specs and require only the affected core areas?

[ayobamiseun]

Agreed, the checklist item contradicted the delta template. In ce60dbc it now distinguishes the two: full specs cover all six areas; delta specs cover only the areas the change affects (at minimum objective, success criteria, and boundary deltas) and inherit the rest from the original.

[federicobartoli]

Could we explicitly answer whether the spec itself should be labeled V1? The Deferred section explains how to capture the V2 backlog, but the version-labeling part of #150 remains ambiguous.

[ayobamiseun]

Made it explicit in ce60dbc: the spec template title is now # Spec: [Name] — V[N], and Spec Evolution says to label the version in the title and bump it when a shipped delta is folded back in, so the V1/V2 boundary is stated in the artifact itself rather than implied.