Repository navigation
[Feature]: stage wise constitution #4419
Description
Activity
Feature assessment — stage-wise-constitution · Stage 1/5: Intake
Idea Intake: Stage-wise constitution
- Slug: stage-wise-constitution
- Created: 2026-09-03T11:37:25Z
- Source: [Feature]: stage wise constitution #4419 (host: github.com, URL Trust Policy: allowlisted)
- Type: improvement
Idea (as captured)
Problem Statement
Currently we have one constitution file and if I include a lot of instructions in that file, there is a tendency for speckit to ignore some of them. And all the instructions may not be relevant for all stages of a project. For e.g. during requirements, only instructions related to defining the requirements are relevant. During the implement, only instructions related to coding are relevant.
Proposed Solution
we can have multiple constitution files e.g. constitution-specify.md, constitution-plan.md, constitution-tasks.md, constitution-implement.md etc. and each file can have instructions that are specific to the requirements, design, task breakdown, implementation stages.
This will require the commands of those specific stages to be modified to explicitly read those constitution files for a consistent experience.Alternatives Considered
No response
Component
Specify CLI (initialization, commands)
AI Agent (if applicable)
None
Use Cases
No response
Acceptance Criteria
No response
Additional Context
No response
Restated
The request proposes splitting the single constitution into stage-specific constitution files so that each Spec Kit workflow stage receives only the guidance relevant to its work. The corresponding stage commands would explicitly read their applicable constitution files.
Origin & Context
- Raised by: harishiyer007
- Trigger: A reported concern that a large, all-stage constitution can cause instructions to be ignored or applied outside their relevant workflow stage.
First-Glance Unknowns
- [NEEDS CLARIFICATION: Which workflow stages require separate constitution guidance, and should one shared constitution remain for cross-cutting principles?]
- [NEEDS CLARIFICATION: What observed behavior or examples demonstrate that instructions are being ignored today?]
- [NEEDS CLARIFICATION: How should existing projects and existing constitution files migrate?]
- [NEEDS CLARIFICATION: What precedence and behavior apply when stage-specific guidance conflicts with shared guidance?]
- [NEEDS CLARIFICATION: What are the acceptance criteria for proving that relevant instructions are consistently applied?]
Prepared on behalf of
@mnriemby GitHub Copilot (model: gpt-5.2-codex, autonomous).Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4419 · 287.1 AIC · ⊞ 30.4K · ◷
Feature assessment — stage-wise-constitution · Stage 2/5: Research
Idea Research: Stage-wise constitution
- Slug: stage-wise-constitution
- Created: 2026-09-03T11:37:25Z
- Evidence confidence (overall): low
Users & Demand
- One issue author explicitly reports that a large constitution can lead to some instructions being ignored and that guidance differs by workflow stage — [source: https://github.com/[Feature]: stage wise constitution #4419] (confidence: medium, cited).
- The issue contains no use cases, acceptance criteria, usage measurements, support examples, or additional comments that establish how frequently this problem occurs or how many users are affected — [source: https://github.com/[Feature]: stage wise constitution #4419] (confidence: high, cited).
- The affected audience appears to be Spec Kit users who maintain substantial governance guidance across multiple SDD stages — [source: https://github.com/[Feature]: stage wise constitution #4419] (confidence: low, cited; the audience is inferred from the stated problem).
Prior Art
- The current command set already has stage-specific consumers of the single live constitution:
specifyandclarifyload it for requirements work;planloads it for the Constitution Check;tasksloads it for task generation;implementloads it for governance constraints; andanalyzetreats it as the non-negotiable authority — [source: templates/commands/specify.md, templates/commands/clarify.md, templates/commands/plan.md, templates/commands/tasks.md, templates/commands/implement.md, templates/commands/analyze.md] (confidence: high, cited). - Core
/constitutionwas deliberately changed to stop propagating guidance into templates because runtime reads keep the constitution as a single source of truth and avoid stale copies — [source: https://github.com/[bug-fix] Fix constitution-preset-template-sync: remove template propagation; rely on runtime resolution (#3737) #3790] (confidence: high, cited). - An opt-in
constitution-syncpreset now provides a compatibility path for teams that want materialized, reviewed constitution guidance in project-local templates and commands, while its documentation describes drift and reconciliation/clobbering trade-offs — [source: presets/constitution-sync/README.md, https://github.com/feat(presets): add opt-in constitution-sync preset #3873] (confidence: high, cited). - The repository tests assert that the constitution-sync behavior is an opt-in wrapped command and that it must not mutate versioned preset or extension artifacts — [source: tests/test_presets.py:14561-14635] (confidence: high, cited).
Market & Context
- Within this repository, users currently have two documented governance patterns: one live constitution read by stage commands, or the opt-in constitution-sync preset for materialized project-local artifacts — [source: templates/commands/*.md, presets/constitution-sync/README.md] (confidence: high, cited).
- No external market, competitor, adoption, or comparative-product evidence was supplied in the issue or gathered for this assessment — [NEEDS CLARIFICATION: identify comparable tools or workflows and whether stage-specific policy files are a meaningful differentiator] (confidence: high, cited).
- If the reported problem persists, users may continue placing all principles in one constitution and rely on each command to selectively apply them, but the cost in missed or irrelevant guidance is not quantified — [source: https://github.com/[Feature]: stage wise constitution #4419] (confidence: low, cited).
Data & Constraints
- The proposed change would affect at least the requirements, planning, task, and implementation stages named in the issue, while the repository also has clarify, analyze, converge, checklist, and task-to-issue commands that currently reference the single constitution — [source: https://github.com/[Feature]: stage wise constitution #4419, templates/commands/*.md] (confidence: high, cited).
- Existing command templates use the path
/memory/constitution.mdas the shared runtime authority; changing the source model would need compatibility behavior for existing projects and commands — [source: templates/commands/specify.md, templates/commands/plan.md, templates/commands/tasks.md, templates/commands/implement.md] (confidence: high, cited). - The issue does not define precedence between shared and stage-specific guidance, behavior for cross-cutting principles, migration of existing constitutions, or the complete stage-to-file mapping — [source: https://github.com/[Feature]: stage wise constitution #4419] (confidence: high, cited).
- No volume, latency, compliance, or storage constraints relevant to the proposal are provided — [NEEDS CLARIFICATION: provide operational constraints and any measurable impact of constitution size or instruction omission] (confidence: high, cited).
Evidence Against the Idea
- The repository's current design intentionally reads one live constitution at runtime, avoiding duplicated or stale guidance; splitting files could reintroduce consistency and precedence problems without evidence that runtime reading is the root cause — [source: https://github.com/[bug-fix] Fix constitution-preset-template-sync: remove template propagation; rely on runtime resolution (#3737) #3790, presets/constitution-sync/README.md] (confidence: high, cited).
- A supported opt-in preset already addresses the narrower need for materialized, reviewed guidance, so the incremental value of making multiple constitution files a core behavior is unestablished — [source: presets/constitution-sync/README.md, https://github.com/feat(presets): add opt-in constitution-sync preset #3873] (confidence: medium, cited).
- The request has one stated user signal but no reproduction, observed agent transcript, acceptance criteria, or evidence that stage-specific files improve adherence; this leaves demand and effectiveness uncertain — [source: https://github.com/[Feature]: stage wise constitution #4419] (confidence: high, cited).
Gaps & Open Questions
- [NEEDS CLARIFICATION: Can the reporter provide a concrete constitution and a stage command where guidance is ignored, including the expected and observed behavior?]
- [NEEDS CLARIFICATION: Which commands/stages need dedicated files, and which principles must remain shared across every stage?]
- [NEEDS CLARIFICATION: What are the migration, precedence, discovery, and fallback rules for existing projects with
.specify/memory/constitution.md?] - [NEEDS CLARIFICATION: What measurable outcome would demonstrate improved instruction adherence or reduced irrelevant guidance?]
- [NEEDS CLARIFICATION: Is the existing constitution-sync preset insufficient for the intended workflow, and why?]
Sources
- [Feature]: stage wise constitution #4419 (host: github.com, policy: allowlisted)
- [bug-fix] Fix constitution-preset-template-sync: remove template propagation; rely on runtime resolution (#3737) #3790 (host: github.com, policy: allowlisted)
- feat(presets): add opt-in constitution-sync preset #3873 (host: github.com, policy: allowlisted)
templates/commands/*.md(repository source)presets/constitution-sync/README.md(repository source)tests/test_presets.py:14561-14635(repository source)
Prepared on behalf of
@mnriemby GitHub Copilot (model: gpt-5.2-codex, autonomous).Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4419 · 287.1 AIC · ⊞ 30.4K · ◷
Feature assessment — stage-wise-constitution · Stage 3/5: Problem
Problem Definition: Stage-wise constitution
- Slug: stage-wise-constitution
- Created: 2026-09-03T11:37:25Z
- Inputs used: intake.md and research.md
Problem Statement
Spec Kit users with substantial governance guidance need stage-relevant instructions to be noticed and applied during each SDD workflow step. The current single live constitution is read by multiple commands, and one reporter says that a large set of mixed-stage instructions can result in some guidance being ignored or irrelevant guidance being present; the frequency and severity of this failure are not yet established (source: issue #4419; repository command templates).
Affected Users & Stakeholders
- Users: Spec Kit practitioners maintaining sizeable constitutions — they may receive inconsistent stage guidance or need to mentally separate requirements, design, task, and implementation rules (source: issue [Feature]: stage wise constitution #4419; the broader persona is inferred).
- Stakeholders: The issue reporter — has direct evidence of the reported pain and can provide a reproduction (source: issue [Feature]: stage wise constitution #4419).
- Stakeholders: Spec Kit maintainers — decide whether the problem warrants a change and must preserve the current runtime-resolution and compatibility behavior (source: PR [bug-fix] Fix constitution-preset-template-sync: remove template propagation; rely on runtime resolution (#3737) #3790 and repository command templates).
- Stakeholders: Teams that review or govern materialized Spec Kit artifacts — may be affected by changes to how guidance is selected or kept consistent (source: constitution-sync preset documentation).
Goals
- Improve the rate at which applicable governance instructions are followed during the relevant workflow stage.
- Reduce the amount of stage-irrelevant guidance that competes for attention during a command.
- Make governance behavior predictable across the supported SDD command stages.
- Preserve the ability to express principles that apply across all stages.
Non-Goals
- Deciding the file layout, naming convention, precedence rules, or migration mechanism; those are solution decisions for the shaping and specification stages.
- Replacing or weakening the project constitution as the governance authority without evidence that such a change is necessary.
- Changing the substantive principles that individual projects choose to adopt.
- Addressing unrelated prompt adherence problems outside constitution guidance.
- Modifying application source code or the implementation of a user's project.
Success Metrics
- The reporter's reproducible scenario shows that applicable instructions are followed in the affected stage without requiring manual repetition (baseline: unknown; source: issue [Feature]: stage wise constitution #4419).
- In a representative evaluation set, the proportion of stage-relevant constitution instructions reflected in command outputs increases, while the proportion of stage-irrelevant instructions reflected decreases (baseline: unknown; [NEEDS CLARIFICATION: define the evaluation set and measurement method]).
- Existing projects that have only
.specify/memory/constitution.mdcontinue to receive their intended governance guidance (baseline: current behavior expected; source: repository command templates). - Users can explain which governance guidance applies to each stage with fewer clarification or correction cycles (qualitative; baseline: unknown; [NEEDS CLARIFICATION: define user sample and target improvement]).
Cost of Inaction
The reported failure mode may persist for users with large, mixed-stage constitutions: relevant guidance could be overlooked, while irrelevant guidance consumes attention. The repository would also retain an unresolved mismatch between users' desire for stage-specific applicability and the current single-file runtime model. The magnitude of this cost is unknown because no reproduction, usage data, or additional user signal was provided (source: issue #4419; research.md).
Open Questions
- [NEEDS CLARIFICATION: Can the reporter provide a concrete constitution and command where an instruction is ignored, including expected and observed behavior?]
- [NEEDS CLARIFICATION: Which workflow stages and commands are in scope, and which principles must remain cross-cutting?]
- [NEEDS CLARIFICATION: What measurable adherence or correction-cycle target would demonstrate improvement?]
- [NEEDS CLARIFICATION: What compatibility and migration outcome is required for existing
.specify/memory/constitution.mdfiles?] - [NEEDS CLARIFICATION: Why is the existing runtime-resolution model or constitution-sync preset insufficient for the reported use case?]
Prepared on behalf of
@mnriemby GitHub Copilot (model: gpt-5.2-codex, autonomous).Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4419 · 287.1 AIC · ⊞ 30.4K · ◷
Feature assessment — stage-wise-constitution · Stage 4/5: Concept
Concept: Stage-wise constitution
- Slug: stage-wise-constitution
- Created: 2026-09-03T11:37:25Z
- Recommended option: Option A — Optional stage-scoped guidance
Options
Option A — Optional stage-scoped guidance
+- Sketch: Keep a shared constitution for principles that apply everywhere, while allowing users to identify guidance relevant to a workflow stage. Each stage would receive its shared principles plus only the guidance marked for that stage, without requiring every existing project to reorganize its constitution immediately.
+- Appetite: small (budget; actual effort is uncertain until the reporter supplies a reproduction and the stage set is defined)
+- Trade-offs: This is the smallest concept that could reduce prompt competition while preserving cross-cutting rules and backward compatibility. It avoids immediately committing every project to multiple files, but it introduces a convention for classifying guidance and may not solve omissions caused by other prompt-adherence factors.
+- Rabbit holes: Defining classification semantics for ambiguous principles; deciding how conflicting shared and stage guidance behaves; supporting every command and extension stage; measuring whether adherence actually improves.Option B — Separate stage constitutions with shared principles
+- Sketch: Give each major workflow stage its own constitution guidance while retaining a shared set for principles that apply across the lifecycle. Users could maintain focused requirements, planning, task, and implementation guidance and the relevant stage would see the corresponding content.
+- Appetite: medium (budget; migration and compatibility scope are unknown)
+- Trade-offs: This most directly matches the requested mental model and can make stage ownership obvious in reviewed files. It creates more artifacts to discover, edit, validate, migrate, and keep consistent, and it risks divergent or contradictory governance.
+- Rabbit holes: The complete stage-to-file matrix; migration of existing constitutions; precedence and fallback behavior; duplicate or conflicting principles; integrations and presets that assume one constitution path; deciding whether generated copies are authoritative.Option C — Do not change the governance model yet
+- Sketch: Keep the live single-constitution runtime model and improve the evidence and authoring guidance around separating cross-cutting principles from stage-specific prose. First collect a concrete failure case and evaluate whether the existing runtime behavior actually fails before introducing a new governance model.
+- Appetite: small (budget; the required documentation and evaluation scope are unknown)
+- Trade-offs: It preserves the design that the repository deliberately chose to avoid stale copies and avoids migration cost. It may leave the reporter's problem unresolved and provides no new enforcement if the failure is reproducible.
+- Rabbit holes: Treating documentation as a substitute for a real defect; collecting evidence without a decision point; failing to distinguish ignored instructions from intentionally stage-irrelevant instructions.Recommendation
Recommend Option A — Optional stage-scoped guidance as the narrowest concept that could address the stated goals while preserving a shared source of cross-cutting principles. It limits migration risk relative to separate files and can be evaluated against the defined metrics, especially the reporter's reproducible scenario. This recommendation is provisional: the research evidence is low-confidence, and specification should not begin until the reporter supplies a reproduction, the in-scope stage set, and an adherence measurement.
Out of Scope (for the recommended option)
+- Requiring every existing project to split or rename its constitution.
+- Removing the shared constitution or changing the authority of cross-cutting principles.
+- Supporting every possible agent-specific workflow or third-party policy format in the first evaluation.
+- Defining implementation details, file schemas, command interfaces, or migration scripts.
+- Materializing copied guidance into package-owned templates or replacing the existing constitution-sync preset.Assumptions to Validate
+- The reported omissions are caused at least partly by mixed-stage guidance competing for attention, rather than solely by a separate prompt-following defect.
+- A meaningful subset of principles can be classified as shared or stage-specific without frequent ambiguity.
+- The initial stage set can be bounded to the stages named in the issue, with other commands addressed only if evidence shows they are affected.
+- Existing projects can continue operating from their current constitution during any adoption period.
+- The reporter can provide a reproducible scenario and a measurable definition of improved adherence.Prepared on behalf of
@mnriemby GitHub Copilot (model: gpt-5.2-codex, autonomous).Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4419 · 287.1 AIC · ⊞ 30.4K · ◷
Feature assessment — stage-wise-constitution · Stage 5/5: Decision — verdict needs-clarification
Decision: Stage-wise constitution
- Slug: stage-wise-constitution
- Decided: 2026-09-03T11:37:25Z
- Verdict: needs-clarification
- Artifacts reviewed: intake.md, research.md, problem.md, concept.md
Scorecard
Criterion Rating Justification Problem validity adequate A reporter describes a plausible problem with mixed-stage guidance, but no reproduction or observed command output establishes its scope or severity. Evidence strength weak Evidence consists of one issue report and repository documentation; there is no usage data, additional user signal, or measured adherence impact. Value vs. inaction unknown The cost of missed guidance is plausible but unquantified, and the current runtime model plus constitution-sync preset may already cover nearby needs. Feasibility / appetite adequate The shaped options include a bounded small concept and a larger separate-file concept, but compatibility and stage coverage remain unresolved. Strategic fit adequate The request concerns the Specify CLI and governance workflow directly, while the repository's current strategy favors one live constitution as the source of truth. Risk posture weak The major risks are identified, but precedence, migration, cross-cutting guidance, and effectiveness measurement have no agreed answers or mitigations. Verdict & Rationale
The verdict is needs-clarification. The problem is plausible and directly relevant, and a bounded concept exists, but the evidence-strength gate is not met: research is low-confidence and does not show a reproducible failure, measurable impact, or why the existing runtime-resolution model and opt-in constitution-sync preset are insufficient. Do not hand off to specification until the blocking questions below are answered and the affected scope is re-evaluated.
If needs-clarification
- Blocking questions:
- [NEEDS CLARIFICATION: Provide a concrete constitution and stage command where guidance is ignored, including the expected and observed behavior.] — revisit research.
- [NEEDS CLARIFICATION: Identify the workflow stages and commands that are in scope, and which principles must remain shared across all stages.] — revisit define.
- [NEEDS CLARIFICATION: Define a measurable adherence or correction-cycle target and the evaluation set that would demonstrate improvement.] — revisit define.
- [NEEDS CLARIFICATION: Specify the required compatibility and migration outcome for existing
.specify/memory/constitution.mdfiles.] — revisit shape. - [NEEDS CLARIFICATION: Explain why runtime resolution or the constitution-sync preset cannot address the reported use case.] — revisit research.
+- Revisit stage: research, then define and shape as needed
If go — Handoff to
/speckit-specifyNot applicable while the verdict is
needs-clarification.Prepared on behalf of
@mnriemby GitHub Copilot (model: gpt-5.2-codex, autonomous).Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4419 · 287.1 AIC · ⊞ 30.4K · ◷
This use case is already supported through presets. A preset can compose the
constitution-templateand wrap or extend the relevant stage commands (specify,plan,tasks, andimplement) so each stage receives appropriate guidance. Multiple scenario-specific presets can also be stacked or selectively enabled.This preserves a single constitution authority while avoiding new file conventions, precedence rules, and migration behavior. Therefore, I don’t think separate stage-wise constitution files require a core CLI feature; a documented preset example should be sufficient.
Posted on behalf of @mnriem by GitHub Copilot (model: GPT-5.6 Sol).
Problem Statement
Currently we have one constitution file and if I include a lot of instructions in that file, there is a tendency for speckit to ignore some of them. And all the instructions may not be relevant for all stages of a project. For e.g. during requirements, only instructions related to defining the requirements are relevant. During the implement, only instructions related to coding are relevant.
Proposed Solution
we can have multiple constitution files e.g. constitution-specify.md, constitution-plan.md, constitution-tasks.md, constitution-implement.md etc. and each file can have instructions that are specific to the requirements, design, task breakdown, implementation stages.
This will require the commands of those specific stages to be modified to explicitly read those constitution files for a consistent experience.
Alternatives Considered
No response
Component
Specify CLI (initialization, commands)
AI Agent (if applicable)
None
Use Cases
No response
Acceptance Criteria
No response
Additional Context
No response