docs: document Articles IV, V & VI as project-customizable in spec-driven.md by Copilot · Pull Request #2467 · github/spec-kit

Copilot · 2026-05-06T13:51:17Z

spec-driven.md claimed "nine articles" but only documented six — Articles IV, V, and VI were silently missing between Article III and Articles VII & VIII.

Changes

spec-driven.md — adds #### Articles IV, V & VI: Project-Specific Standards between Article III and Articles VII & VIII:
- Identifies each article's typical domain: IV → integration concerns, V → operational concerns, VI → lifecycle concerns
- Frames these as the primary customization points that teams define via /speckit.constitution, not as universal fixed requirements
- Notes that /speckit.constitution supports fewer or more principles than the template default, and that /speckit.analyze validates spec, plan, and task artifacts against every principle in the project constitution
- Adds a pointer in the constitution introduction to /speckit.constitution as the recommended command for creating or updating the constitution, and to .specify/memory/constitution.md as the resulting file

Copilot

Copilot's findings

Files reviewed: 1/1 changed files
Comments generated: 3

mnriem · 2026-05-06T19:21:50Z

@copilot apply changes based on the comments in this thread

Copilot · 2026-05-06T19:24:19Z

@copilot apply changes based on the comments in this thread

Applied all three review comments in d4ec0b7:

Removed the "fixed in the Spec Kit framework" framing — the section now describes IV–VI as the typical customization focus areas while noting that /speckit.constitution lets teams define fewer or more principles than the template.
Collapsed Article V and VI into a single bullet that correctly reflects the template grouping them under one [PRINCIPLE_5_NAME] / [PRINCIPLE_5_DESCRIPTION] slot by default, with a note that teams can expand to separate articles via /speckit.constitution.
Reworded the /speckit.analyze sentence to say it validates all spec/plan artifacts against every principle in the project constitution, rather than implying article-number-specific logic.

Copilot

Copilot's findings

Files reviewed: 1/1 changed files
Comments generated: 2

mnriem · 2026-05-06T19:36:00Z

@copilot apply changes based on the comments in this thread

Match the style of existing articles which state principles and rationale without referencing specific Spec Kit commands.

Replace 'clarification pipeline' tooling references with principle-effect language matching Articles I-III and VII-IX.

Article VI now covers governance and versioning of all project artifacts (constitution, specs, plans, tasks), not just constitution amendments. This matches what spec-driven.md itself describes: specifications versioned in branches, requirement changes propagating across artifacts, and cross-artifact consistency.

Constitution and specifications are the versioned sources of truth. Plans and tasks are derived execution artifacts. Implementation gaps are addressed through new specifications, preserving the feed-forward dependency direction rather than retrofitting code back into specs.

Support all three schools: new spec, update existing spec, or regenerate derived artifacts. The only invariant is that specs drive implementation, not the reverse, and gaps are addressed through specifications rather than untracked code changes.

Constitution uses semantic versioning (major/minor/patch). Specifications use branch-based workflows (feature branches, reviewed and merged like code). Consistent with the existing description in spec-driven.md line 21.

Spec versioning is now tool-agnostic: 'versioned and reviewable before acceptance' rather than prescribing branch-based workflows.

- Remove git branch references from conceptual sections (lines 21, 152) - Remove memory/constitution.md file path from principles section - Replace 'immutable principles' with 'governing principles' to reconcile with Article VI semantic versioning - Constitutional Evolution section now acknowledges principles themselves can evolve through governed process, not just their application

…actice'

Copilot

Copilot's findings

Files reviewed: 1/1 changed files
Comments generated: 3

mnriem · 2026-05-11T20:22:15Z

@copilot apply changes based on the comments in this thread

…I framing

Copilot · 2026-05-11T20:25:24Z

@copilot apply changes based on the comments in this thread

Applied all three review comments in the latest commit:

Line 277: Added a sentence to the constitution intro pointing readers to /speckit.constitution as the command to create/update the constitution, and noting that it writes to .specify/memory/constitution.md.
Lines 321–324: Removed the "complete, unambiguous, and verifiable before planning begins" framing (which contradicted the "stable enough" guidance on line 29). The new section uses "for example" language throughout, avoiding any prescriptive timing.
Lines 321–329: Replaced the three separate Article IV / V / VI sections (each with universal MUST blocks) with a single combined #### Articles IV, V & VI: Project-Specific Standards section. It frames these as the primary customization points—describing only common choices via bullet points—and explicitly notes that /speckit.constitution is the mechanism for defining them and that fewer or more principles than the template default are supported.

Copilot

Copilot's findings

Files reviewed: 1/1 changed files
Comments generated: 2

mnriem · 2026-05-12T14:55:32Z

@copilot apply changes based on the comments in this thread

…logy

Copilot · 2026-05-12T14:57:14Z

@copilot apply changes based on the comments in this thread

Applied both comments in the latest commit:

Renamed "Integration concerns (Article IV)" to "Requirement quality and coverage (Article IV)" so the label matches the examples (testability, unambiguity, traceability).
Added a clarifying sentence that in the constitution file these slots are expressed as named principles—not fixed numbered headings—so readers understand "Articles IV–VI" are conceptual methodology positions rather than a rigid structure in .specify/memory/constitution.md.

Copilot

Copilot's findings

Files reviewed: 1/1 changed files
Comments generated: 2

Copilot AI self-assigned this May 6, 2026

Copilot AI review requested due to automatic review settings May 6, 2026 13:51

Copilot AI assigned mnriem May 6, 2026

Copilot AI removed the request for review from Copilot May 6, 2026 13:51

Copilot started work on behalf of mnriem May 6, 2026 13:51 View session

Copilot AI linked an issue May 6, 2026 that may be closed by this pull request

docs: Document Articles IV, V, VI as project-customizable in spec-driven.md #2466

Open

Copilot AI requested review from Copilot and removed request for Copilot May 6, 2026 13:54

Copilot AI changed the title ~~[WIP] Document Articles IV, V, VI as project-customizable in spec-driven.md~~ docs: document Articles IV, V & VI as project-customizable in spec-driven.md May 6, 2026

Copilot AI requested a review from mnriem May 6, 2026 13:55

Copilot finished work on behalf of mnriem May 6, 2026 13:55

mnriem marked this pull request as ready for review May 6, 2026 16:38

mnriem requested review from Copilot and removed request for Copilot May 6, 2026 16:38

Copilot started reviewing on behalf of mnriem May 6, 2026 16:39 View session

mnriem requested review from Copilot and removed request for Copilot May 6, 2026 19:05

Copilot started reviewing on behalf of mnriem May 6, 2026 19:06 View session

Copilot AI reviewed May 6, 2026

View reviewed changes

Comment thread spec-driven.md Outdated

Comment thread spec-driven.md Outdated

Comment thread spec-driven.md Outdated

Copilot started work on behalf of mnriem May 6, 2026 19:22 View session

Copilot finished work on behalf of mnriem May 6, 2026 19:25

mnriem requested a review from Copilot May 6, 2026 19:29

Copilot started reviewing on behalf of mnriem May 6, 2026 19:30 View session

Copilot AI reviewed May 6, 2026

View reviewed changes

Comment thread spec-driven.md Outdated

Comment thread spec-driven.md Outdated

Copilot started work on behalf of mnriem May 6, 2026 19:36 View session

mnriem added 10 commits May 11, 2026 09:26

docs: remove /speckit.* command references from Articles IV-VI

8f87999

Match the style of existing articles which state principles and rationale without referencing specific Spec Kit commands.

docs: align Articles IV-V language with existing article style

85fc96b

Replace 'clarification pipeline' tooling references with principle-effect language matching Articles I-III and VII-IX.

docs: recommend versioning models for constitution and specs

25175e2

Constitution uses semantic versioning (major/minor/patch). Specifications use branch-based workflows (feature branches, reviewed and merged like code). Consistent with the existing description in spec-driven.md line 21.

docs: remove git branch implementation detail from Article VI

e3bcefd

Spec versioning is now tool-agnostic: 'versioned and reviewable before acceptance' rather than prescribing branch-based workflows.

docs: rename 'The SDD Workflow in Practice' to 'The SDD Process in Pr…

515baba

…actice'

docs: replace 'workflow' with 'process' throughout spec-driven.md

2116770

mnriem force-pushed the copilot/docs-spec-driven-update-articles-iv-v-vi branch from 550aaac to 2116770 Compare May 11, 2026 14:50

mnriem requested a review from Copilot May 11, 2026 14:51

Copilot started reviewing on behalf of mnriem May 11, 2026 14:51 View session

Copilot AI reviewed May 11, 2026

View reviewed changes

Comment thread spec-driven.md

Comment thread spec-driven.md Outdated

Comment thread spec-driven.md Outdated

Copilot started work on behalf of mnriem May 11, 2026 20:22 View session

docs: address review feedback on constitution intro and Articles IV–V…

e48cb8c

…I framing

Copilot finished work on behalf of mnriem May 11, 2026 20:27

mnriem requested a review from Copilot May 12, 2026 13:06

Copilot AI reviewed May 12, 2026

View reviewed changes

Comment thread spec-driven.md Outdated

Comment thread spec-driven.md Outdated

Copilot started work on behalf of mnriem May 12, 2026 14:55 View session

docs: fix Article IV label and clarify principles vs articles termino…

e6b2e26

…logy

Copilot AI requested review from Copilot and removed request for Copilot May 12, 2026 14:57

Copilot finished work on behalf of mnriem May 12, 2026 14:57

mnriem requested a review from Copilot May 12, 2026 16:18

Copilot AI reviewed May 12, 2026

View reviewed changes

Comment thread spec-driven.md

Comment thread spec-driven.md

Uh oh!

Conversation

Copilot AI commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mnriem commented May 6, 2026

Uh oh!

Copilot AI commented May 6, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

mnriem commented May 6, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mnriem commented May 11, 2026

Uh oh!

Copilot AI commented May 11, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

mnriem commented May 12, 2026

Uh oh!

Copilot AI commented May 12, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented May 6, 2026 •

edited

Loading