github · harsha09 · Aug 15, 2026 · Aug 15, 2026 · Aug 15, 2026 · Aug 15, 2026
@@ -2,6 +2,24 @@
 
 <!-- insert new changelog below this comment -->
 
+## [Unreleased]
+
+### Added
+
+- feat(commands): add `/speckit.revise` to edit the current feature spec in place (add/remove/reword ACs, FRs, stories) and cascade into plan/tasks
+
+### Changed
+
+- teach `/speckit.implement` and `/speckit.taskstoissues` to skip cancelled revision tasks
+- teach lean implement the same skip rules; refuse to regenerate `tasks.md` after a revision
+- teach `/speckit.converge` to inventory only live spec IDs and stop when revision tasks are still open
+- teach plan (core and lean) and analyze to ignore SUPERSEDED/RETIRED IDs; lean specify must not overwrite a living spec
+- stop implement from sending a Revision-phase task list back to `/speckit.tasks`
+- first-generation tasks inventory only live IDs; persist `plan_status` on `revisions.md`
+- clarify/checklist do not overwrite living-spec history; init lists `/speckit.revise`
+- hook git auto-commit on `before_revise` / `after_revise`
+- document living-spec revise in evolving-specs, spec-persistence, and agentic-sdd
+
 ## [0.16.4] - 2026-08-14
 
 ### Changed

@@ -184,6 +184,7 @@ Additional commands for enhanced quality and validation:
 | Command              | Agent Skill            | Description                                                                                                                          |
 | -------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
 | `/speckit.clarify`   | `speckit-clarify`      | Clarify underspecified areas (recommended before `/speckit.plan`; formerly `/quizme`)                                                |
+| `/speckit.revise`    | `speckit-revise`       | Revise the current spec in place (add/remove/reword ACs or FRs) and cascade into plan/tasks                                          |
 | `/speckit.analyze`   | `speckit-analyze`      | Cross-artifact consistency & coverage analysis (run after `/speckit.tasks`, before `/speckit.implement`)                             |
 | `/speckit.checklist` | `speckit-checklist`    | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") |
 

@@ -184,6 +184,7 @@ Spec Kit 可与 30 多个 AI 编码助手协作 —— 既包括 CLI 工具，
 | 命令                 | 助手技能               | 说明                                                                                              |
 | -------------------- | ---------------------- | ------------------------------------------------------------------------------------------------- |
 | `/speckit.clarify`   | `speckit-clarify`      | 澄清描述不充分的部分（建议在 `/speckit.plan` 之前使用；旧称 `/quizme`）                            |
+| `/speckit.revise`    | `speckit-revise`       | 就地修订当前规格（增删或改写验收标准 / 功能需求），并级联更新 plan/tasks                           |
 | `/speckit.analyze`   | `speckit-analyze`      | 跨制品的一致性与覆盖度分析（在 `/speckit.tasks` 之后、`/speckit.implement` 之前运行）              |
 | `/speckit.checklist` | `speckit-checklist`    | 生成自定义质量清单，校验需求的完整性、清晰度与一致性（好比"为自然语言写单元测试"）                 |
 

@@ -71,7 +71,7 @@ derived from it.
 In this model, teams update `spec.md` first and then regenerate or revise
 `plan.md` and `tasks.md` from that source. The plan and task list are still
 valuable, but they are treated as disposable derivations rather than permanent
-sources of truth.
+sources of truth. Use `/speckit.revise` to edit the current spec in place.
 
 Living spec works well when:
 

@@ -39,7 +39,8 @@ derived from it.
 
 When intended behavior changes, revise the existing `spec.md` first. Then
 regenerate or manually revise downstream artifacts so they match the updated
-spec:
+spec. Use `/speckit.revise` to apply a known add, remove, or reword on the
+current spec (do not run `/speckit.specify` again for that).
 
 1. Start from a clean working tree or a dedicated branch so every generated
    change is reviewable.

@@ -123,6 +123,7 @@ After initialization, you should see the following commands available in your co
 - `/speckit.implement` - Execute implementation tasks
 - `/speckit.analyze` - Validate cross-artifact consistency
 - `/speckit.clarify` - Identify and resolve ambiguities
+- `/speckit.revise` - Revise the current spec in place and cascade into plan/tasks
 - `/speckit.checklist` - Generate quality checklists
 - `/speckit.constitution` - Create or update project principles
 - `/speckit.converge` - Assess codebase against artifacts and append remaining tasks

@@ -120,6 +120,14 @@ Checks the codebase against the spec, plan, and tasks. If it finds gaps, it appe
 /speckit.converge
 ```
 
+### After shipping: `/speckit.revise` — change the current spec
+
+When requirements change on the **same** feature (add or drop an acceptance criterion, retire an FR), do **not** run `/speckit.specify` again. That opens a new feature directory. Use `/speckit.revise` instead. If `plan.md` or `tasks.md` is still missing, run plan then tasks. If revise reports `plan_status: needs-rebuild`, rerun `/speckit.plan`. Then analyze, implement, and converge.
+
+```text
+/speckit.revise Remove password login. Add AC: Given an expired session, When the user submits, Then redirect to SSO
+```
+
 > [!TIP]
 > For a full reference on each command — arguments, output, phased implementation, and how they interact — see [Agentic SDD](reference/agentic-sdd.md).
 

@@ -9,6 +9,8 @@ The commands are designed to run in order, but only `/speckit.specify` is strict
 
 ```text
 /speckit.constitution -> /speckit.specify -> /speckit.clarify -> /speckit.plan -> /speckit.checklist -> /speckit.tasks -> /speckit.analyze -> /speckit.implement -> /speckit.converge
+# after ship, when the spec itself changes:
+/speckit.revise -> [/speckit.plan if missing or plan_status: needs-rebuild] -> [/speckit.tasks if tasks.md missing] -> /speckit.analyze -> /speckit.implement -> /speckit.converge
 ```
 
 ## `/speckit.constitution`
@@ -21,7 +23,7 @@ Creates or updates the project **constitution** — the guiding principles that
 
 ## `/speckit.specify`
 
-Creates or updates the feature **specification** from a natural-language description. Focus on the **what** and **why** — the user-facing behavior and goals — not the tech stack, which belongs in `/speckit.plan`.
+Creates or updates the feature **specification** from a natural-language description. Focus on the **what** and **why** — the user-facing behavior and goals — not the tech stack, which belongs in `/speckit.plan`. For a known add, remove, or reword on the current spec, use `/speckit.revise`.
 
 This workflow may also maintain `checklists/requirements.md`, the built-in spec-quality checklist that `/speckit.specify` creates and `/speckit.clarify` re-evaluates. That lifecycle is separate from custom checklists generated by `/speckit.checklist`.
 
@@ -37,7 +39,7 @@ Asks up to five targeted questions about underspecified areas of the current spe
 /speckit.clarify Focus on the task card behavior: status changes, comment limits, and who can be assigned.
 ```
 
-Clarifying before planning keeps you from designing on top of ambiguity. If `/speckit.analyze` later surfaces requirement gaps, come back and run `/speckit.clarify` (or `/speckit.specify`) again.
+Clarifying before planning keeps you from designing on top of ambiguity. If `/speckit.analyze` later surfaces requirement gaps, come back and run `/speckit.clarify` (or `/speckit.specify`) again. For a known add, remove, or reword on the current spec, use `/speckit.revise`.
 
 When `checklists/requirements.md` exists, `/speckit.clarify` may update its evaluated state as part of tightening the spec. This exception applies only to the built-in requirements checklist, not to custom review checklists.
 
@@ -65,7 +67,7 @@ Run it with no arguments for a broad pass, or pass a focus area to target one as
 /speckit.checklist Focus on the Kanban board interactions and comment permissions.
 ```
 
-Review the generated checklist. If it surfaces gaps, loop back to `/speckit.clarify` or `/speckit.specify` to tighten the spec before breaking the work down, then mark each custom checklist item `[x]` only after the requirements-quality criterion has been reviewed and satisfied.
+Review the generated checklist. If it surfaces gaps, loop back to `/speckit.clarify` or `/speckit.specify` to tighten the spec before breaking the work down, then mark each custom checklist item `[x]` only after the requirements-quality criterion has been reviewed and satisfied. For a known current-spec delta, use `/speckit.revise`.
 
 ## `/speckit.tasks`
 
@@ -83,7 +85,7 @@ Performs a **read-only** cross-artifact consistency and quality analysis across
 /speckit.analyze
 ```
 
-Run it before implementing, while the artifacts can still be adjusted cheaply. If it surfaces issues, **return to the earlier step that owns them** and fix them at the source — `/speckit.specify` or `/speckit.clarify` for requirement problems, `/speckit.plan` for design problems, `/speckit.tasks` to regenerate the task list — then re-run `/speckit.analyze` until it comes back clean. You can also run `/speckit.analyze` again after implementation as an extra review.
+Run it before implementing, while the artifacts can still be adjusted cheaply. If it surfaces issues, **return to the earlier step that owns them** and fix them at the source — `/speckit.specify` or `/speckit.clarify` for requirement problems, `/speckit.plan` for design problems, `/speckit.tasks` to regenerate the task list — then re-run `/speckit.analyze` until it comes back clean. You can also run `/speckit.analyze` again after implementation as an extra review. For a known current-spec delta, use `/speckit.revise`.
 
 ## `/speckit.implement`
 
@@ -109,6 +111,16 @@ For a large feature, work in stages to avoid overwhelming the agent's context
 
 Verify each stage works before moving to the next.
 
+## `/speckit.revise`
+
+Applies a **known requirement delta** to the **current** feature spec — add, remove, or reword acceptance criteria, functional requirements, stories, or success criteria — then cascades into `plan.md` / `tasks.md` when those files exist and records the change in `revisions.md`. It does not create a new feature directory and does not write application code.
+
+```text
+/speckit.revise Remove password login. Add AC: Given an expired session, When the user submits, Then redirect to SSO
+```
+
+Run this when the spec itself changed. Then `/speckit.analyze` (if plan and tasks exist), `/speckit.implement` (skips cancelled tasks), then `/speckit.converge`. Do not run `/speckit.converge` first — converge assumes the spec is stable.
+
 ## `/speckit.converge`
 
 Assesses the codebase against the feature's spec, plan, and tasks to confirm nothing was missed. It is **append-only**: it never edits or deletes code, and its only possible write is adding tasks to `tasks.md`. Run it only after `/speckit.implement` has run on the current `tasks.md`.

@@ -635,6 +635,8 @@ Standard events (defined by core):
 - `after_constitution` - After constitution update
 - `before_taskstoissues` - Before tasks-to-issues conversion
 - `after_taskstoissues` - After tasks-to-issues conversion
+- `before_revise` - Before `/speckit.revise` living-spec revision
+- `after_revise` - After `/speckit.revise` living-spec revision
 
 ### Hook Configuration
 

@@ -225,6 +225,7 @@ Available hook points:
 - `before_analyze` / `after_analyze`: Before/after cross-artifact analysis
 - `before_checklist` / `after_checklist`: Before/after checklist generation
 - `before_clarify` / `after_clarify`: Before/after spec clarification
+- `before_revise` / `after_revise`: Before/after living-spec revision
 - `before_constitution` / `after_constitution`: Before/after constitution update
 - `before_taskstoissues` / `after_taskstoissues`: Before/after tasks-to-issues conversion
 

@@ -406,7 +406,8 @@ settings:
 #                   before_tasks, after_tasks, before_implement, after_implement,
 #                   before_analyze, after_analyze, before_checklist, after_checklist,
 #                   before_clarify, after_clarify, before_constitution, after_constitution,
-#                   before_taskstoissues, after_taskstoissues
+#                   before_taskstoissues, after_taskstoissues,
+#                   before_revise, after_revise
 hooks:
   after_tasks:
     - extension: jira

@@ -35,6 +35,7 @@ This extension provides Git operations as an optional, self-contained module. It
 | `before_checklist` | `speckit.git.commit` | Yes | Commit outstanding changes before checklist |
 | `before_analyze` | `speckit.git.commit` | Yes | Commit outstanding changes before analysis |
 | `before_taskstoissues` | `speckit.git.commit` | Yes | Commit outstanding changes before issue sync |
+| `before_revise` | `speckit.git.commit` | Yes | Commit outstanding changes before living-spec revision |
 | `after_constitution` | `speckit.git.commit` | Yes | Auto-commit after constitution update |
 | `after_specify` | `speckit.git.commit` | Yes | Auto-commit after specification |
 | `after_clarify` | `speckit.git.commit` | Yes | Auto-commit after clarification |
@@ -44,6 +45,7 @@ This extension provides Git operations as an optional, self-contained module. It
 | `after_checklist` | `speckit.git.commit` | Yes | Auto-commit after checklist |
 | `after_analyze` | `speckit.git.commit` | Yes | Auto-commit after analysis |
 | `after_taskstoissues` | `speckit.git.commit` | Yes | Auto-commit after issue sync |
+| `after_revise` | `speckit.git.commit` | Yes | Auto-commit after living-spec revision |
 
 ## Configuration
 

@@ -50,6 +50,9 @@ auto_commit:
   before_taskstoissues:
     enabled: false
     message: "[Spec Kit] Save progress before issue sync"
+  before_revise:
+    enabled: false
+    message: "[Spec Kit] Save progress before spec revision"
   after_constitution:
     enabled: false
     message: "[Spec Kit] Add project constitution"
@@ -77,3 +80,6 @@ auto_commit:
   after_taskstoissues:
     enabled: false
     message: "[Spec Kit] Sync tasks to issues"
+  after_revise:
+    enabled: false
+    message: "[Spec Kit] Revise specification"
@@ -83,6 +83,11 @@ hooks:
     optional: true
     prompt: "Commit outstanding changes before issue sync?"
     description: "Auto-commit before tasks-to-issues conversion"
+  before_revise:
+    command: speckit.git.commit
+    optional: true
+    prompt: "Commit outstanding changes before spec revision?"
+    description: "Auto-commit before living-spec revision"
   after_constitution:
     command: speckit.git.commit
     optional: true
@@ -128,6 +133,11 @@ hooks:
     optional: true
     prompt: "Commit after syncing issues?"
     description: "Auto-commit after tasks-to-issues conversion"
+  after_revise:
+    command: speckit.git.commit
+    optional: true
+    prompt: "Commit specification revision?"
+    description: "Auto-commit after living-spec revision"
 
 tags:
   - "git"

@@ -50,6 +50,9 @@ auto_commit:
   before_taskstoissues:
     enabled: false
     message: "[Spec Kit] Save progress before issue sync"
+  before_revise:
+    enabled: false
+    message: "[Spec Kit] Save progress before spec revision"
   after_constitution:
     enabled: false
     message: "[Spec Kit] Add project constitution"
@@ -77,3 +80,6 @@ auto_commit:
   after_taskstoissues:
     enabled: false
     message: "[Spec Kit] Sync tasks to issues"
+  after_revise:
+    enabled: false
+    message: "[Spec Kit] Revise specification"
@@ -13,13 +13,15 @@ Use Lean when you want the structured specify → plan → tasks → implement p
 | `speckit.specify` | `spec.md` | Create a specification from a feature description |
 | `speckit.plan` | `plan.md` | Create an implementation plan from the spec |
 | `speckit.tasks` | `tasks.md` | Create dependency-ordered tasks from spec and plan |
-| `speckit.implement` | *(code)* | Execute all tasks in order, marking progress |
+| `speckit.implement` | *(code)* | Execute live tasks in order, skipping cancelled or superseded ones |
 | `speckit.constitution` | `constitution.md` | Create or update the project constitution |
 
 ## What It Replaces
 
 Lean overrides the five core workflow commands with self-contained prompts that produce each artifact directly — no separate template files involved. The result is a shorter, more direct workflow.
 
+Living-spec edits still use the unmodified core `/speckit.revise` (lean does not replace it).
+
 ## Installation
 
 ```bash

@@ -15,8 +15,10 @@ $ARGUMENTS
 2. **Load context**: `.specify/memory/constitution.md` and `<feature_directory>/spec.md` and `<feature_directory>/plan.md` and `<feature_directory>/tasks.md`.
 
 3. **Execute tasks** in order:
-   - Complete each task before moving to the next
+   - Skip any task line that contains `CANCELLED`, `SUPERSEDED`, or a struck-through task ID (`~~T012~~`), even when the checkbox is still `- [ ]`. Do not implement them, do not mark them `[x]`, and do not count them as remaining work.
+   - Prefer the latest `Revision R#` phase plus any cleanup tasks it added
+   - Complete each remaining live task before moving to the next
    - Mark completed tasks by changing `- [ ]` to `- [x]` in `<feature_directory>/tasks.md`
    - Halt on failure and report the issue
 
-4. **Validate**: Verify all tasks are completed and the implementation matches the spec.
+4. **Validate**: Verify all **live** (non-cancelled, non-superseded) tasks are completed and the implementation matches **live** items in the spec (struck `SUPERSEDED` / `RETIRED` lines are not required).
@@ -15,5 +15,7 @@ $ARGUMENTS
 2. **Load context**: `.specify/memory/constitution.md` and `<feature_directory>/spec.md`.
 
 3. Create an implementation plan and store it in `<feature_directory>/plan.md`.
+   - Only plan **live** (unmarked) FRs, ACs, and SCs. Lines marked `SUPERSEDED` or `RETIRED` are historical — do not restore them.
+   - If `plan.md` already exists and `revisions.md` is present, do **not** overwrite it unless the latest `revisions.md` entry has `plan_status: needs-rebuild` (or the user asked). Even then, do not resurrect retired IDs.
    - Technical context: tech stack, dependencies, project structure
    - Design decisions, architecture, file structure
@@ -10,6 +10,8 @@ $ARGUMENTS
 
 ## Outline
 
+If `.specify/feature.json` or the named directory already has a `spec.md` and the user stated a **concrete delta** (add, remove, or reword a named AC, FR, story, or success criterion), do **not** write anything. Recommend `/speckit.revise` and stop. Never overwrite an existing `spec.md`.
+
 1. **Ask the user** for the feature directory path (e.g., `specs/my-feature`). Do not proceed until provided.
 
 2. Create the directory and write `.specify/feature.json`:
@@ -18,6 +20,7 @@ $ARGUMENTS
    ```
 
 3. Create a specification from the user input and store it in `<feature_directory>/spec.md`.
+   - If that path already has a `spec.md`, stop — do not overwrite it
    - Overview, functional requirements, user scenarios, success criteria
    - Every requirement must be testable
    - Make informed defaults for unspecified details
@@ -15,5 +15,7 @@ $ARGUMENTS
 2. **Load context**: `.specify/memory/constitution.md` and `<feature_directory>/spec.md` and `<feature_directory>/plan.md`.
 
 3. Create dependency-ordered implementation tasks and store them in `<feature_directory>/tasks.md`.
+   - If `tasks.md` already exists and has a `Revision R#` phase (or `revisions.md` is present), do **not** overwrite it. Stop and tell the user `/speckit.revise` already maintains the list.
+   - First generation: inventory only **live** (unmarked) FRs, ACs, and SCs. Never emit tasks for `SUPERSEDED` or `RETIRED` lines.
    - Every task uses checklist format: `- [ ] [TaskID] Description with file path`
    - Organized by phase: setup, foundational, user stories in priority order, polish