From sdd-workflow
Define and manage non-negotiable project principles (Constitution) and verify synchronization with other documents
How this skill is triggered — by the user, by Claude, or both
Slash command
/sdd-workflow:constitutionThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Define the project's non-negotiable principles (Constitution)
examples/constitution_as_code.jsonexamples/constitution_file_structure.mdexamples/principle_template.mdexamples/validation_report.mdreferences/best_practices.mdreferences/prerequisites_directory_paths.mdreferences/prerequisites_plugin_update.mdreferences/prerequisites_principles.mdscripts/validate-files.shtemplates/en/constitution_output.mdtemplates/en/constitution_template.mdtemplates/ja/constitution_output.mdtemplates/ja/constitution_template.mdDefine the project's non-negotiable principles (Constitution) and verify that all specifications and design documents comply with them.
Read the following prerequisite references before execution:
references/prerequisites_plugin_update.md - Check for plugin updatesreferences/prerequisites_principles.md - Read AI-SDD principles documentreferences/prerequisites_directory_paths.md - Resolve directory paths using SDD_* environment variablesOutput templates are located under templates/${SDD_LANG:-en}/ within this skill directory.
The SDD_LANG environment variable determines the language (default: en).
A Project Constitution defines non-negotiable principles that form the foundation of all design decisions.
| Characteristic | Description |
|---|---|
| Non-negotiable | Not open to debate. Changes require careful consideration |
| Persistent | Consistently applied across the entire project |
| Hierarchical | Higher principles take precedence over lower ones |
| Verifiable | Can automatically verify spec/design compliance with principles |
| Principle Category | Example Principles |
|---|---|
| Architecture | Library-First, Clean Architecture |
| Development | Test-First, Specification-Driven |
| Quality | Test Coverage > 80%, Zero Runtime Errors |
| Technical | TypeScript Only, No Any Types |
| Business | Privacy by Design, Accessibility First |
$ARGUMENTS
| Subcommand | Description | Additional Arguments |
|---|---|---|
init | Initialize constitution file | [context] (optional) |
validate | Validate constitution compliance | - |
add | Add new principle | "principle-name" |
bump-version | Version bump | major|minor|patch |
/constitution init # Initialize constitution file (interactive)
/constitution init "TypeScript/React Web application" # Initialize with context (non-interactive)
/constitution validate # Validate constitution compliance
/constitution add "Library-First" # Add new principle
/constitution bump-version major # Major version bump
Create a constitution file in the project:
/constitution init
Generated File: ${CLAUDE_PROJECT_DIR}/${SDD_ROOT}/CONSTITUTION.md
Processing Flow:
${CLAUDE_PROJECT_DIR}/${SDD_ROOT}/CONSTITUTION.md already existstemplates/${SDD_LANG:-en}/constitution_template.md{Principle Name}, {Description of the principle}, {Applicable scope}, {Validation item},
YYYY-MM-DD, etc.) with project-specific contentCRITICAL: The output language MUST match the template language. Do NOT mix languages regardless of the user's global language settings.
SDD_LANG=en (or unset) → All content in English (use templates/en/)SDD_LANG=ja → All content in Japanese (use templates/ja/)Content: Template customized for the project
Add a new principle to a constitution:
/constitution add "Library-First"
Process:
Command: /constitution show
Output Content:
Command: /constitution update
Interactive Prompts:
What type of change?
1. Add new principle (MAJOR)
2. Modify existing principle (MAJOR)
3. Clarify existing principle (MINOR)
4. Update enforcement methods (MINOR)
> 1
Describe the new principle:
> ...
Rationale:
> ...
How will it be enforced?
> ...
Are there exceptions?
> ...
Review proposed change:
[Display formatted principle]
Confirm (y/n)?
> y
Constitution updated
Version: 1.0.0 -> 2.0.0
Changes: Added principle P4
Version Bump Rules:
| Change Type | Version Impact | Example |
|---|---|---|
| Add principle | MAJOR (X.y.z) | 1.0.0 -> 2.0.0 |
| Modify principle | MAJOR (X.y.z) | 1.0.0 -> 2.0.0 |
| Remove principle | MAJOR (X.y.z) | 1.0.0 -> 2.0.0 |
| Clarify principle | MINOR (x.Y.z) | 1.0.0 -> 1.1.0 |
| Update enforcement | MINOR (x.Y.z) | 1.0.0 -> 1.1.0 |
| Fix typo | PATCH (x.y.Z) | 1.0.0 -> 1.0.1 |
Verify all specifications and design documents comply with constitution:
/constitution validate
Optimized Execution Flow:
Phase 1: Shell Script - Execute validate-files.sh to scan file structure:
bash "${CLAUDE_PLUGIN_ROOT}/skills/constitution/scripts/validate-files.sh"
This script:
${CLAUDE_PROJECT_DIR}/${SDD_REQUIREMENT_PATH}/**/*.md)*_spec.md)*_design.md)$CLAUDE_ENV_FILE:
CONSTITUTION_REQUIREMENT_FILES - List of requirement filesCONSTITUTION_SPEC_FILES - List of spec filesCONSTITUTION_DESIGN_FILES - List of design filesCONSTITUTION_SUMMARY - JSON summary with file countsPhase 2: Claude - Read files from pre-scanned lists and validate content
Validation Targets:
${CLAUDE_PROJECT_DIR}/${SDD_REQUIREMENT_PATH}/**/*.md${CLAUDE_PROJECT_DIR}/${SDD_SPECIFICATION_PATH}/**/*_spec.md${CLAUDE_PROJECT_DIR}/${SDD_SPECIFICATION_PATH}/**/*_design.md${CLAUDE_PROJECT_DIR}/${SDD_ROOT}/PRD_TEMPLATE.md${CLAUDE_PROJECT_DIR}/${SDD_ROOT}/SPECIFICATION_TEMPLATE.md${CLAUDE_PROJECT_DIR}/${SDD_ROOT}/DESIGN_DOC_TEMPLATE.mdValidation Items:
| Validation Item | Check Content |
|---|---|
| Principle Mention | Are principles mentioned in specs/designs? |
| Principle Compliance | Do implementation decisions follow principles? |
| Contradiction Detection | Are there descriptions contrary to principles? |
| Template Sync | Do templates reflect latest constitution? |
Validation Output Format: See examples/validation_report.md for the complete report template.
Command: /constitution sync
Purpose: Ensure principles are reflected in other documents
Actions:
Update Specification Template:
Update Design Template:
Update Task Templates:
Update Checklist Template:
Output:
# Constitution Sync Report
## Documents Updated
- [x] `${CLAUDE_PROJECT_DIR}/${SDD_ROOT}/SPECIFICATION_TEMPLATE.md`
- Added P1 reference to API section
- Updated constraints to include P3
- [x] `${CLAUDE_PROJECT_DIR}/${SDD_ROOT}/DESIGN_DOC_TEMPLATE.md`
- Added "Principle Compliance" section
- Updated decision framework to match constitution
- [x] `skills/checklist/templates/checklist_template.md`
- Added principle verification items
- CHK-CONST-001: P1 verification
- CHK-CONST-002: P2 verification
- CHK-CONST-003: P3 verification
## Sync Status
All documents synchronized with Constitution v2.0.0
Update constitution version:
/constitution bump-version major # Major version bump (breaking change)
/constitution bump-version minor # Minor version bump (add principle)
/constitution bump-version patch # Patch version bump (typo fix)
Semantic Versioning:
| Version Type | Use Case | Example |
|---|---|---|
| Major | Remove/significantly change existing principle (breaking) | 1.0.0 -> 2.0.0 |
| Minor | Add new principle | 1.0.0 -> 1.1.0 |
| Patch | Fix expression of principle, typo fix | 1.0.0 -> 1.0.1 |
For a complete constitution file example with all categories (Business, Architecture, Development Methodology, Technical Constraints), principle hierarchy, verification items, and change history, see:
Reference: examples/constitution_file_structure.md
Save Location: ${CLAUDE_PROJECT_DIR}/${SDD_ROOT}/CONSTITUTION.md
Depending on sub command, use the templates/${SDD_LANG:-en}/constitution_output.md template for output formatting.
YYYY-MM-DD → actual date)| Document | Sync Content |
|---|---|
${CLAUDE_PROJECT_DIR}/${SDD_ROOT}/SPECIFICATION_TEMPLATE.md | Add principle reference sections |
${CLAUDE_PROJECT_DIR}/${SDD_ROOT}/DESIGN_DOC_TEMPLATE.md | Add principle compliance checklist |
*_spec.md | Design based on principles |
*_design.md | Explicitly state principle compliance |
Running /constitution validate automatically verifies:
| Scenario | Command | Purpose |
|---|---|---|
| Project Start | /constitution init | Create constitution file |
| Add New Principle | /constitution add | Add principle and bump version |
| Before Creating Spec | /constitution validate | Check latest constitution |
| Before Review | /constitution validate | Verify constitution compliance |
| Major Policy Change | /constitution bump-version major | Major version bump |
1. Propose change (discuss in Issue, etc.)
|
2. Team approval
|
3. Update constitution file
|
4. Bump version
|
5. Update affected documents
|
6. Verify with /constitution validate
Major version bump required for any of the following:
See references/best_practices.md for detailed guidance on:
Constitution (Project-Level Principles)
|
PRD (Business Requirements)
|
Specification (Logical Design)
|
Design Document (Technical Implementation)
|
Implementation (Code)
Constitution principles are checked at each level.
${CLAUDE_PROJECT_DIR}/${SDD_ROOT}/CONSTITUTION.mdreferences/best_practices.md for additional recommendationsnpx claudepluginhub toshikiimagawa/ai-sdd-workflow --plugin sdd-workflowAuthors enforceable project constitutions for greenfield projects with testable principles, enforcement mechanisms, rationale, and amendment processes.
Creates or updates a project constitution from interactive or provided principle inputs, ensuring dependent templates stay in sync.
Creates, updates, or validates .constitution.md file for Spec Kit workflow, defining project mission, principles, constraints, quality standards, and checking codebase alignment.