Modifying the AI Constitution
Relevant source files
The following files were used as context for generating this wiki page:The AI Constitution, located at /memory/constitution.md, is the set of immutable principles that govern how specifications become code within the Spec-Driven Development (SDD) framework. It acts as the architectural DNA of the system, ensuring that every generated implementation maintains consistency, simplicity, and quality. Modifying the constitution is a significant action that impacts the entire development workflow, from planning to implementation.
This document outlines the process, implications, and necessary steps for amending the constitution. The process is designed to be deliberate, ensuring that any changes are propagated consistently across all project templates and tooling.
Sources: spec-driven.md:300-303, memory/constitution.md
The Role of the Constitution
The constitution defines the core development philosophy and non-negotiable rules that the AI and human developers must follow. Its primary purpose is to enforce architectural discipline and ensure the generated code is maintainable, testable, and architecturally sound.
Sources: spec-driven.md:300-303, README.md:120-121
Core Principles
The constitution is built upon a set of articles that shape the development process. While the specific articles are placeholders in the base template, the methodology document outlines key examples that form the foundation.
| Principle | Description | Source |
|---|---|---|
| Library-First | Every feature must begin as a standalone, reusable library component before being integrated into an application. | spec-driven.md:310-316 |
| CLI Interface Mandate | Every library must expose its functionality via a command-line interface that accepts text input and produces text output, supporting JSON. | spec-driven.md:318-325 |
| Test-First (Non-Negotiable) | All implementation must follow strict Test-Driven Development (TDD). Tests must be written, approved, and confirmed to fail before implementation code is written. | spec-driven.md:327-334 |
| Simplicity & Anti-Abstraction | Combat over-engineering by limiting project structures and using framework features directly rather than creating unnecessary wrappers. | spec-driven.md:336-344 |
| Integration-First Testing | Prioritize testing with realistic environments, using real databases and services over mocks and stubs. | spec-driven.md:346-352 |
| Governance | The constitution supersedes all other practices. Amendments require a formal process. | memory/constitution.md:44-47 |
The Amendment Process
Modifications to the constitution are governed by a formal process to ensure stability and consensus. The process requires explicit documentation, review, and a clear plan for migrating existing artifacts.
Sources: spec-driven.md:374-380, memory/constitution.md:44-47
This diagram illustrates the formal procedure for amending the constitution.
The Update Checklist
When the constitution is amended, dependent documents must be updated to maintain consistency. The constitution_update_checklist.md file provides a comprehensive list of files that require review and potential modification.
Sources: memory/constitution_update_checklist.md
Key Files to Update
The following table summarizes the primary templates and documents that are impacted by a constitutional change.
| File Path | Reason for Update |
|---|---|
/templates/plan-template.md | The "Constitution Check" section must be updated to reflect new or modified articles. |
/templates/spec-template.md | May need updates if new constitutional rules affect how requirements or scope are defined. |
/templates/tasks-template.md | May require changes if new rules alter task generation, ordering (e.g., TDD), or types. |
/templates/commands/plan.md | The logic for the /plan command, which reads the constitution, might need adjustment. |
/templates/commands/tasks.md | The logic for the /tasks command could be affected if task generation rules change. |
/scripts/update-agent-context.sh | If new principles affect the overall project structure or technology guidance. |
Sources: memory/constitution_update_checklist.md:7-11, templates/plan-template.md:39-68
Validation Steps
After amending the constitution and updating the related templates, the following validation steps must be performed:
- Pre-Commit Validation: Ensure all templates reference the new requirements and that no contradictions exist between documents.
- Post-Template Update: Run through a sample implementation plan to verify all new constitutional requirements are addressed.
- Version Tracking: The version number in
memory/constitution.mdand template footers must be updated.
Sources: memory/constitution_update_checklist.md:48-60
Enforcement in the Workflow
The constitution is not merely a document; it is actively enforced during the development workflow, primarily through the /plan command and its associated template.
Sources: spec-driven.md:204-208, templates/commands/plan.md:12-13
The /plan Command's Role
The /plan command is responsible for translating a feature specification into a technical implementation plan. A critical step in this process is ensuring the plan complies with the constitution.
The following sequence diagram shows how the /plan command interacts with the constitution.
The Constitution Check Gate
The plan-template.md contains a "Constitution Check" section that acts as a gate. This checklist forces the AI to explicitly verify that the generated plan adheres to each major constitutional article before proceeding.
## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
**Simplicity**:
- Projects: [#] (max 3 - e.g., api, cli, tests)
- Using framework directly? (no wrapper classes)
**Architecture**:
- EVERY feature as library? (no direct app code)
- CLI per library: [commands with --help/--version/--format]
**Testing (NON-NEGOTIABLE)**:
- RED-GREEN-Refactor cycle enforced? (test MUST fail first)
- Order: Contract→Integration→E2E→Unit strictly followed?
Sources: templates/plan-template.md:39-68, spec-driven.md:278-288
If violations are found, they must be documented in the "Complexity Tracking" section of the plan, or the plan generation will fail. This creates accountability for any deviations from the established architecture.
Sources: templates/plan-template.md:14-15, templates/plan-template.md:162-167
Conclusion
Modifying the AI Constitution is a powerful but sensitive operation that redefines the foundational rules of the development process. The established amendment procedure, centered around the constitution_update_checklist.md, ensures that changes are made deliberately and are propagated system-wide. By embedding constitutional checks directly into the automated planning workflow, the system guarantees that all development, whether by humans or AI, remains aligned with the project's core architectural principles, ensuring long-term quality and consistency.