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

Bắt đầu với việc khởi tạo Specify CLI và cài đặt hiện có của các lệnh specify, plan và tasks, sau đó kiểm tra cách xử lý spec.md, plan.md, tasks.md, revisions.md và Git hooks. Xem xét các tiêu chí chấp nhận và yêu cầu về kiểm thử tự động trước khi quyết định lệnh mới sẽ tích hợp với implement, analyze và taskstoissues như thế nào. Công việc được xem là hoàn tất khi revise đã được cài đặt, các artifact hiện có được giữ nguyên, các thay đổi về yêu cầu và cập nhật nhiệm vụ được ghi lại, đồng thời được bao phủ bởi các bài kiểm thử và tài liệu.

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