[Feature]: /speckit.revise - update the current spec without rewriting artifacts

从 Specify CLI 的初始化以及现有的 specify、plan 和 tasks 命令安装开始，然后检查 spec.md、plan.md、tasks.md、revisions.md 和 Git hooks 的处理方式。在决定新命令如何与 implement、analyze 和 taskstoissues 配合之前，先查看验收标准和自动化测试要求。完成的标准是 revise 已安装、现有构件得到保留、需求变更和任务更新被记录，并且有测试和文档覆盖这些内容。

Problem Statement

I'm frustrated when requirements change after /speckit.specify, sometimes after /speckit.implement, and the only options are bad ones.

/speckit.specify always opens a new feature folder. /speckit.clarify asks questions I already answered. /speckit.converge assumes the spec didn't move. So agents fix it by rewriting spec.md and regenerating tasks.md. History disappears. I can't tell what was dropped, and if we already shipped, nothing says "remove the old code."

I need a way to add or drop a requirement on the current feature: keep the old AC/FR visible as superseded or retired, add a new ID if something replaces it, and if plan/tasks already exist, only append, including remove-code work when implementation is already done. Not a full rewrite of the artifacts.

Proposed Solution

Add a core command /speckit.revise for requirement changes on the current feature (same specs/ folder). It is not specify, clarify, or converge.

What it should do:

• Never rewrite spec.md, plan.md, or tasks.md. Never open a new feature directory. Never touch application code.
• Add a requirement -> new ID (FR/AC/SC).
• Replace a live one -> mark the old line SUPERSEDED by {new-id}, add the new ID. Don't edit the old line to mean something else.
• No longer valid -> mark the old line RETIRED. No new ID.
• revisions.md is only a dated list of those IDs, not a second spec.
• If plan.md / tasks.md exist, only append. After implement: tasks to add new code and/or remove old code. Open tasks for a dead ID get cancelled/superseded; finished [x] tasks stay.
• Then I run /speckit.implement for the new/cleanup tasks.

Duplicates (already true on a live line) should be a no-op. Implement/analyze/taskstoissues should ignore SUPERSEDED, RETIRED, and CANCELLED lines. Git should have before/after revise hooks like the other commands.

Alternatives Considered

A few things I tried or thought about:

• Run /speckit.specify again. Always creates 002-….. Fine for a new feature, wrong for “this AC on the current spec is no longer valid.”
• /speckit.clarify. It’s for unknowns before the first plan (questions). I already know the change.
• /speckit.converge. That’s “spec is stable, code lagged.” Opposite of a requirement change. After a retire it would try to put the old behavior back.
• Edit spec.md / regenerate /speckit.tasks by hand. This is what agents do today. They rewrite the files. History and “remove the old code” both get lost.
• Make specify update in place. Mixes “new feature” and “change this feature.” Breaks teams that want a new folder per change.

That’s why I want a separate /speckit.revise instead of stretching specify/clarify/converge.

Component

Specify CLI (initialization, commands)

AI Agent (if applicable)

None

Use Cases

1. After implement, product says password login is dead, SSO only. I need the old FR marked superseded/retired, a new FR for SSO, and tasks to remove the password code and add SSO. I don’t want tasks.md regenerated.

2. Mid-flight, before implement, we add one AC (expired session -> login page). Spec gets a new AC id. Plan/tasks only gain a small append if they already exist. No new 002- folder.

3. A success criterion is no longer valid. Mark it RETIRED. If we already built toward it, append a cleanup task. If we haven’t implemented yet, just cancel the open tasks.

4. Same revise run twice (or I ask to add an AC that’s already live). Should be a no-op, no new R#, no file rewrite.

5. Spec exists, plan/tasks don’t yet. I revise first, then /speckit.plan or /speckit.tasks so they start from the updated contract.

6. Two people on the same feature: one shipped, QA/product changes the requirement. The folder still has a readable trail (old line + new id), not a silently rewritten spec.

Acceptance Criteria

• specify init installs /speckit.revise for the active agent (same as specify/plan/tasks).
• It never creates a new specs/ folder and never rewrites spec.md / plan.md / tasks.md from scratch.
• Add -> new FR/AC/SC id. Replace -> old line SUPERSEDED by {new-id}, new id added. Drop -> old line RETIRED. Live lines don’t contradict each other.
• revisions.md is only a dated id list. Re-running the same delta is a no-op (no new R#).
• If plan/tasks exist, they are only appended. After implement, retiring/superseding a requirement adds remove-old-code work (and add-new-code when something replaces it). Open tasks for a dead id are cancelled/superseded; [x] tasks stay.
• Revise does not edit application code. /speckit.implement does the add/remove. Implement, analyze, and taskstoissues ignore SUPERSEDED / RETIRED / CANCELLED lines.
• Works before plan/tasks too: only spec (+ log) changes; next step is plan or tasks, not a regenerated feature.
• Docs (README / living-spec / agentic-sdd) describe when to use revise vs specify / clarify / converge.
• Git has before/after revise hooks. Automated tests cover install + these rules. A sample project run shows the files weren’t regenerated.

Additional Context

No response