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

+
+- **Article IV** addresses integration concerns—such as integration testing requirements, contract testing across service boundaries, or cross-component communication standards. The constitution template's `[PRINCIPLE_4_NAME]` / `[PRINCIPLE_4_DESCRIPTION]` slot is dedicated to this article, with an example hint of *Integration Testing*.
+
+- **Articles V & VI** address operational and lifecycle concerns—such as observability, structured logging, versioning schemes, or breaking-change policies. By default, the template groups these under a single `[PRINCIPLE_5_NAME]` / `[PRINCIPLE_5_DESCRIPTION]` slot (example hint: *V. Observability, VI. Versioning & Breaking Changes*). Teams that need separate articles can expand to additional principle sections using `/speckit.constitution`.


+
+- **Articles V & VI** address operational and lifecycle concerns—such as observability, structured logging, versioning schemes, or breaking-change policies. By default, the template groups these under a single `[PRINCIPLE_5_NAME]` / `[PRINCIPLE_5_DESCRIPTION]` slot (example hint: *V. Observability, VI. Versioning & Breaking Changes*). Teams that need separate articles can expand to additional principle sections using `/speckit.constitution`.
+
+To define these articles, populate the corresponding principle sections in `.specify/memory/constitution.md` (generated from `templates/constitution-template.md`). The `/speckit.analyze` command validates all spec and plan artifacts against every principle in your project constitution, so any rules you define here are automatically applied during analysis.


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

@copilot apply changes based on the comments in this thread

Copilot

Copilot's findings

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

Copilot

Copilot's findings

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

Copilot

Copilot's findings

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

Article IV (Requirement Quality and Coverage): driven by the clarify/checklist/analyze pipeline that validates requirement completeness, ambiguity, and traceability before planning. Article V (Non-Functional Standards): ensures projects explicitly specify performance, security, observability, and accessibility requirements rather than defaulting to functional-only output. Article VI (Governance and Versioning): codifies constitution versioning and cross-artifact consistency propagation via the /speckit.constitution command. These three articles were missing from the original document despite being actively enforced by existing templates and commands. Derived by mapping every template and command back to constitutional principles and identifying enforcement mechanisms with no article.

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


-At the heart of SDD lies a constitution—a set of immutable principles that govern how specifications become code. The constitution (`memory/constitution.md`) acts as the architectural DNA of the system, ensuring that every generated implementation maintains consistency, simplicity, and quality.
+At the heart of SDD lies a constitution—a set of governing principles that define how specifications become code. The constitution acts as the architectural DNA of the system, ensuring that every generated implementation maintains consistency, simplicity, and quality.



+#### Article IV: Requirement Quality and Coverage
+
+Specifications must be complete, unambiguous, and verifiable before planning begins:
+


+#### Article IV: Requirement Quality and Coverage
+
+Specifications must be complete, unambiguous, and verifiable before planning begins:
+
+```text
+All requirements MUST be:
+- Testable: each requirement has measurable acceptance criteria
+- Unambiguous: no vague qualifiers without quantified thresholds
+- Traceable: mapped from user stories through tasks to implementation


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

+
+Common choices for these articles include:
+
+- **Integration concerns** (Article IV): requirement quality and coverage standards—for example, rules about testability, unambiguity, and traceability that specifications must satisfy before planning begins for that project.


+Articles IV, V, and VI are the primary customization points in the constitution. Teams define these articles to address their own integration, operational, and lifecycle concerns by running `/speckit.constitution`. The principles are stored in `.specify/memory/constitution.md` and `/speckit.analyze` validates spec, plan, and task artifacts against every principle in the project constitution.
+
+Common choices for these articles include:
+
+- **Integration concerns** (Article IV): requirement quality and coverage standards—for example, rules about testability, unambiguity, and traceability that specifications must satisfy before planning begins for that project.
+- **Operational concerns** (Article V): non-functional standards—for example, explicit thresholds for performance, security, observability, and accessibility that the project requires.
+- **Lifecycle concerns** (Article VI): governance and versioning practices—for example, how the constitution and specifications are versioned, how derived artifacts stay consistent with their source, and how implementation gaps are resolved.
+
+Teams are free to name and scope these articles in whatever way best fits their project. The number of principles is also flexible—`/speckit.constitution` supports fewer or more than the template default.


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 review requested due to automatic review settings 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

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

Copilot started reviewing on behalf of mnriem May 7, 2026 18:26 View session

Copilot AI reviewed May 7, 2026

View reviewed changes

Comment thread spec-driven.md Outdated

Copilot AI review requested due to automatic review settings May 7, 2026 18:40

Copilot started reviewing on behalf of mnriem May 7, 2026 18:40 View session

Copilot AI reviewed May 7, 2026

View reviewed changes

Comment thread spec-driven.md Outdated

Copilot AI review requested due to automatic review settings May 8, 2026 19:07

Copilot started reviewing on behalf of mnriem May 8, 2026 19:08 View session

Copilot AI reviewed May 8, 2026

View reviewed changes

Comment thread spec-driven.md Outdated

Comment thread spec-driven.md Outdated

Comment thread spec-driven.md Outdated

mnriem added 11 commits May 11, 2026 09:25

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

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


		- Article IV addresses integration concerns—such as integration testing requirements, contract testing across service boundaries, or cross-component communication standards. The constitution template's `[PRINCIPLE_4_NAME]` / `[PRINCIPLE_4_DESCRIPTION]` slot is dedicated to this article, with an example hint of Integration Testing.

		- Articles V & VI address operational and lifecycle concerns—such as observability, structured logging, versioning schemes, or breaking-change policies. By default, the template groups these under a single `[PRINCIPLE_5_NAME]` / `[PRINCIPLE_5_DESCRIPTION]` slot (example hint: V. Observability, VI. Versioning & Breaking Changes). Teams that need separate articles can expand to additional principle sections using `/speckit.constitution`.


		- Articles V & VI address operational and lifecycle concerns—such as observability, structured logging, versioning schemes, or breaking-change policies. By default, the template groups these under a single `[PRINCIPLE_5_NAME]` / `[PRINCIPLE_5_DESCRIPTION]` slot (example hint: V. Observability, VI. Versioning & Breaking Changes). Teams that need separate articles can expand to additional principle sections using `/speckit.constitution`.

		To define these articles, populate the corresponding principle sections in `.specify/memory/constitution.md` (generated from `templates/constitution-template.md`). The `/speckit.analyze` command validates all spec and plan artifacts against every principle in your project constitution, so any rules you define here are automatically applied during analysis.


		At the heart of SDD lies a constitution—a set of immutable principles that govern how specifications become code. The constitution (`memory/constitution.md`) acts as the architectural DNA of the system, ensuring that every generated implementation maintains consistency, simplicity, and quality.
		At the heart of SDD lies a constitution—a set of governing principles that define how specifications become code. The constitution acts as the architectural DNA of the system, ensuring that every generated implementation maintains consistency, simplicity, and quality.

		#### Article IV: Requirement Quality and Coverage

		Specifications must be complete, unambiguous, and verifiable before planning begins:


		Common choices for these articles include:

		- Integration concerns (Article IV): requirement quality and coverage standards—for example, rules about testability, unambiguity, and traceability that specifications must satisfy before planning begins for that project.

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!

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!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

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!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented May 6, 2026 •

edited

Loading