You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
docs: distinguish extension reconciliation from core SDD - #4948
Clarify that reconciliation of spec.md, plan.md, and tasks.md is never performed by the core Spec Kit workflow:
/speckit.analyze reports inconsistencies without editing artifacts.
/speckit.converge remains append-only and can only add missing implementation work to tasks.md.
Teams may reconcile artifacts directly, and extensions may provide commands or hooks that reconcile them during or after delivery according to the extension's documented behavior and project governance.
Reconciliation timing remains separate from persistence, which describes how the team maintains artifacts after delivery.
This updates the persistence concept, evolving-specs guide, and extension reference consistently. It does not change command, template, hook, or extension behavior.
Testing
git diff --check — passed.
npx --yes markdownlint-cli2 docs/concepts/spec-persistence.md docs/guides/evolving-specs.md docs/reference/extensions.md — passed; three files linted, zero issues.
CLI checks, pytest, and sample-project execution were not run because this change only updates documentation.
Tested locally with uv run specify --help
Ran existing tests with uv sync && uv run pytest
Tested with a sample project (if applicable)
AI Disclosure
I did not use AI assistance for this contribution
I did use AI assistance (fill in the disclosure below)
AI disclosure: Authored by GitHub Copilot on behalf of @mnriem using GPT-5.6 Sol (model ID: gpt-5.6-sol), with session-default reasoning settings. The agent autonomously authored the documentation and PR text and ran validation in an interactive session at the user's direction; no human line-by-line review is claimed. AI assistance covered documentation assessment, edits, validation, and commit/PR preparation.
Clarify that core commands never reconcile feature artifacts while teams and extensions may provide reconciliation during or after delivery. Keep that behavior separate from post-delivery persistence.
Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 423e8bf6-30ec-49e3-bdb5-dc073f812ee5
Clarify that core lacks an automatic all-artifact reconciler while contributors can rerun the command that owns each artifact. Use consistent during-delivery timing terminology.
Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 423e8bf6-30ec-49e3-bdb5-dc073f812ee5
Addressed all findings from review 5505462186 in commit 5674098a:
Replaced the blanket statement that core never reconciles artifacts with the narrower boundary that core has no dedicated automatic all-artifact reconciler.
Preserved the documented remediation path through the artifact-owning commands: /speckit.specify or /speckit.clarify, /speckit.plan, and /speckit.tasks.
Kept /speckit.analyze read-only and /speckit.converge append-only.
Standardized reconciliation timing as “during delivery.”
Clarified that teams and extensions can coordinate broader reconciliation without changing core command responsibilities.
Validation: git diff --check passed; focused markdownlint passed with zero issues.
AI disclosure: This review-round response and the documentation changes were generated by GitHub Copilot on behalf of @mnriem using GPT-5.6 Sol (model ID: gpt-5.6-sol), session-default reasoning settings, autonomous mode. AI assistance covered review assessment, documentation edits, validation, commit creation, and this summary.
Use the established remaining-work wording so converge coverage includes missing, partial, contradictory, and unrequested implementation outcomes.
Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 423e8bf6-30ec-49e3-bdb5-dc073f812ee5
Changed “missing implementation work” to the established “remaining work” wording. This preserves converge’s full documented scope, including tasks arising from missing, partial, contradictory, or unrequested implementation—not only work that is absent.
Validation: git diff --check passed; focused markdownlint passed with zero issues.
AI disclosure: This review-round response and documentation correction were generated by GitHub Copilot on behalf of @mnriem using GPT-5.6 Sol (model ID: gpt-5.6-sol), session-default reasoning settings, autonomous mode. AI assistance covered review assessment, the wording correction, validation, commit creation, and this summary.
Correct guidance: use clarify or edit spec.md for existing features
docs/guides/evolving-specs.md:52
This presents /speckit.specify as a way to revise or regenerate the current spec, but that command always creates a feature directory and copies a fresh spec template (templates/commands/specify.md:94-111). For an existing feature, readers should use /speckit.clarify or edit spec.md directly; otherwise following this reconciliation guidance can create a second feature or overwrite the current spec.
Retain specify as an existing-spec update path while documenting that callers must target the existing SPECIFY_FEATURE_DIRECTORY to avoid creating a new feature directory.
Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 423e8bf6-30ec-49e3-bdb5-dc073f812ee5
Assessed review 5505692404 against the actual command and clarified the guidance in commit acb75d48.
/speckit.specify does support updating an existing specification: templates/commands/specify.md describes it as “Create or update,” gives an explicitly supplied SPECIFY_FEATURE_DIRECTORY precedence, and writes the generated specification to that directory’s spec.md. docs/reference/agentic-sdd.md likewise directs users back to /speckit.specify for requirement problems.
The review identified a valid usage caveat rather than an invalid update path. The guide now says to target the existing SPECIFY_FEATURE_DIRECTORY when using /speckit.specify for revision and warns that omitting that explicit existing directory creates a new feature directory. /speckit.clarify remains the incremental-edit alternative.
Validation: git diff --check passed; focused markdownlint passed with zero issues.
AI disclosure: This assessment, documentation clarification, and review-round response were generated by GitHub Copilot on behalf of @mnriem using GPT-5.6 Sol (model ID: gpt-5.6-sol), session-default reasoning settings, autonomous mode. AI assistance covered command inspection, review assessment, documentation editing, validation, commit creation, and this summary.
Addressed review 5505873091 and the broader reconciliation ambiguity in commit 755add48.
After comparing the current /speckit.specify, /speckit.plan, and /speckit.tasks prompts with their historical behavior, the persistence pages no longer prescribe rerunning artifact-owning core commands as reconciliation. The guidance now states that teams reconcile artifacts directly or through extensions, while /speckit.analyze remains read-only and /speckit.converge remains append-only. The living-spec and flow-back sections likewise describe the desired artifact state without assigning reconciliation to inconsistent command regeneration behavior.
This accepts the review finding: /speckit.specify is no longer presented as an incremental update path. The separate discrepancy between its advertised “Create or update” description and its template-based replacement behavior is outside this PR.
Validation: git diff --check passed; focused markdownlint passed with zero issues.
AI disclosure: This historical assessment, documentation revision, and review-round response were generated by GitHub Copilot on behalf of @mnriem using GPT-5.6 Sol (model ID: gpt-5.6-sol), session-default reasoning settings, autonomous mode. AI assistance covered repository-history inspection, command analysis, documentation editing, validation, commit creation, and this summary.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Follow-up to #4945.
Clarify that reconciliation of
spec.md,plan.md, andtasks.mdis never performed by the core Spec Kit workflow:/speckit.analyzereports inconsistencies without editing artifacts./speckit.convergeremains append-only and can only add missing implementation work totasks.md.This updates the persistence concept, evolving-specs guide, and extension reference consistently. It does not change command, template, hook, or extension behavior.
Testing
git diff --check— passed.npx --yes markdownlint-cli2 docs/concepts/spec-persistence.md docs/guides/evolving-specs.md docs/reference/extensions.md— passed; three files linted, zero issues.CLI checks, pytest, and sample-project execution were not run because this change only updates documentation.
Tested locally with
uv run specify --helpRan existing tests with
uv sync && uv run pytestTested with a sample project (if applicable)
AI Disclosure
AI disclosure: Authored by GitHub Copilot on behalf of @mnriem using GPT-5.6 Sol (model ID: gpt-5.6-sol), with session-default reasoning settings. The agent autonomously authored the documentation and PR text and ran validation in an interactive session at the user's direction; no human line-by-line review is claimed. AI assistance covered documentation assessment, edits, validation, and commit/PR preparation.