This skill MUST be invoked when the user says "write principles", "define governance", "create constitution", or "write a constitution". SHOULD also invoke when user mentions "governance", "principles", "enforcement", or "amendment process". Core skill for greenfield projects.
Write project constitutions that teams actually follow. Every principle must be enforceable, testable, and justified. Vague aspirations are rejected in favor of actionable constraints with measurable criteria.
humaninloop:brownfield-constitution instead, which provides Essential Floor + Emergent Ceiling approachhumaninloop:validation-constitution for quality checkshumaninloop:syncing-claude-md| Mistake | Problem | Fix |
|---|---|---|
| Vague principles | "Code should be clean" has no enforcement | Add specific, measurable criteria: "Functions MUST be ≤40 lines" |
| Missing enforcement | Principles without verification become suggestions | Every principle needs CI automation, code review checklist, or audit process |
| Untestable criteria | "Good architecture" can't be verified | Define binary pass/fail: "No domain imports from infrastructure layer" |
| No rationale | Future maintainers don't know why rules exist | Explain the failure mode prevented and success enabled |
| Skipping SYNC IMPACT | Constitution changes without audit trail | Always update the SYNC IMPACT REPORT header with version changes |
| CLAUDE.md drift | AI assistants operate with outdated guidance | Include CLAUDE.md Sync Mandate section; update both files together |
Every principle MUST have three components. A principle without all three is incomplete and should not be accepted.
How compliance is verified. Without enforcement, a principle is a suggestion.
**Enforcement**:
- CI runs `ruff check .` and blocks merge on violations
- Code review MUST verify test files accompany new functionality
- Quarterly audit checks exception registry for staleness
Enforcement Types:
| Type | Examples | Strength |
|---|---|---|
| CI Automated | Linting, tests, coverage gates | Strongest—no human judgment needed |
| Code Review | Architecture compliance, security review | Strong—explicit checklist item |
| Tooling | Pre-commit hooks, IDE plugins | Medium—can be bypassed |
| Audit | Quarterly review, compliance check | Weaker—periodic, not continuous |
What pass/fail looks like. A principle without testable criteria is merely an aspiration.
**Testability**:
- Pass: `flutter analyze` exits with code 0
- Pass: All functions have ≤10 cyclomatic complexity
- Fail: Any file exceeds 400 lines without documented exception
Testability Requirements:
Why this constraint exists. Future maintainers need this to evaluate if the rule is still relevant.
**Rationale**: Tests written after implementation tend to validate what was built rather than what was intended. Test-first ensures requirements drive implementation, catches defects early, and produces inherently testable, modular code.
Rationale Requirements:
### I. [Principle Name]
[Declarative statement of the constraint using RFC 2119 keywords]
- [Specific rule 1]
- [Specific rule 2]
- [Specific rule 3]
**Enforcement**:
- [How compliance is verified]
- [Specific commands or processes]
**Testability**:
- [Pass/fail criteria]
- [Measurable thresholds]
**Rationale**: [Why this constraint exists—what failure it prevents, what success it enables]
Use precise language for requirements:
| Keyword | Meaning | Example |
|---|---|---|
| MUST | Absolute requirement; no exceptions | "Tests MUST pass before merge" |
| MUST NOT | Absolute prohibition | "Secrets MUST NOT be committed" |
| SHOULD | Recommended; valid exceptions exist | "Functions SHOULD be under 40 lines" |
| SHOULD NOT | Discouraged; valid exceptions exist | "Magic numbers SHOULD NOT appear" |
| MAY | Optional; implementation choice | "Teams MAY adopt additional linting rules" |
See references/RFC-2119-KEYWORDS.md for detailed usage.
Every constitution MUST include these sections:
Track changes as HTML comment at file top. This provides an audit trail of constitution evolution.
<!--
SYNC IMPACT REPORT
==================
Version change: X.Y.Z → A.B.C (MAJOR|MINOR|PATCH: Brief rationale)
Modified principles: [List or "None (enforcement details updated)"]
Added sections:
- [New section name]
Removed sections:
- [Removed section name] (or "None")
Configuration changes:
- [File/path change]: [old] → [new]
- [Structural change description]
Templates requiring updates:
- CLAUDE.md: [Status - updated ✅ or pending ⚠️]
- [Other templates]: [Status]
Follow-up TODOs:
- [Any deferred items] (or "None")
Previous reports:
- X.Y.Z (YYYY-MM-DD): [One-line summary of that version's changes]
- W.X.Y (YYYY-MM-DD): [One-line summary]
- ...
-->
Version History Best Practice: Maintain a rolling log of previous versions in the SYNC IMPACT REPORT. This provides:
Example from mature constitution:
<!--
Previous reports:
- 3.1.0 (YYYY-MM-DD): Added CLAUDE.md synchronization mandate
- 3.0.0 (YYYY-MM-DD): Adopted hexagonal architecture, added strategic abstraction principle
- 2.1.0 (YYYY-MM-DD): Added unification trigger to API consistency principle
- 2.0.0 (YYYY-MM-DD): Added API consistency principle
- 1.8.0 (YYYY-MM-DD): Added exception registry and process
-->
See references/SYNC-IMPACT-FORMAT.md for complete format.
Numbered principles (I, II, III...) with Enforcement/Testability/Rationale.
Naming Conventions:
(NON-NEGOTIABLE)Common Principle Categories:
| Category | Examples |
|---|---|
| Development Process | Test-First, Code Review, Documentation |
| Code Quality | Linting, Complexity Limits, Coverage |
| Architecture | Layer Rules, Dependency Flow, Module Boundaries |
| Security | Auth, Secrets, Input Validation |
| Operations | Observability, Error Handling, Performance |
| Governance | Versioning, Dependencies, Exceptions |
Greenfield Recommendation: Beyond the Essential Floor (I-IV: Security, Testing, Error Handling, Observability), greenfield constitutions SHOULD include architectural principles. See references/RECOMMENDED-PATTERNS.md for:
These patterns establish good foundations from day one. It's easier to start with architectural discipline than to retrofit it later.
Document mandated technology choices with rationale:
## Technology Stack
| Category | Choice | Rationale |
|----------|--------|-----------|
| Language | Python 3.12 | Type hints, performance, ecosystem |
| Framework | FastAPI | Async-first, Pydantic integration |
| Testing | pytest | Fixtures, parametrization, plugins |
| Linting | ruff | Fast, replaces multiple tools |
Define automated checks that block merge:
## Quality Gates
| Gate | Requirement | Measurement | Enforcement |
|------|-------------|-------------|-------------|
| Static Analysis | Zero errors | `ruff check .` | CI automated |
| Type Checking | Zero errors | `pyright` | CI automated |
| Test Suite | All pass | `pytest` | CI automated |
| Coverage | ≥80% | `pytest --cov-fail-under=80` | CI automated |
| Security | No vulnerabilities | `pip-audit` | CI automated |
Define how the constitution itself evolves:
## Governance
### Amendment Process
1. Propose change via PR to constitution file
2. Document rationale for change
3. Review impact on existing code
4. Obtain team consensus
5. Update version per semantic versioning
### Version Policy
- **MAJOR**: Principle removal or incompatible redefinition
- **MINOR**: New principle or significant expansion
- **PATCH**: Clarification or wording improvement
### Exception Registry
Approved exceptions MUST be recorded in `docs/constitution-exceptions.md` with:
- Exception ID, Principle, Scope, Justification
- Approved By, Date, Expiry, Tracking Issue
**Version**: X.Y.Z | **Ratified**: YYYY-MM-DD | **Last Amended**: YYYY-MM-DD
Define synchronization requirements. This is critical because AI coding assistants read CLAUDE.md as their primary instruction source.
## CLAUDE.md Synchronization
The `CLAUDE.md` file at repository root MUST remain synchronized with this constitution.
It serves as the primary agent instruction file and MUST contain all information
necessary for AI coding assistants to operate correctly.
**Mandatory Sync Artifacts**:
| Constitution Section | CLAUDE.md Section | Sync Rule |
|---------------------|-------------------|-----------|
| Core Principles (I-X) | Principles Summary | MUST list all principles with enforcement keywords |
| Layer Import Rules | Architecture section | MUST replicate layer rules table |
| Technology Stack | Technical Stack | MUST match exactly |
| Quality Gates | Quality Gates | MUST match exactly |
| Development Workflow | Development Workflow | MUST match branch/review rules |
| Project Management | Project Management | MUST include tool conventions |
**Synchronization Process**:
When amending this constitution:
1. Update constitution version and content
2. Update CLAUDE.md to reflect all changes in the Mandatory Sync Artifacts table
3. Verify CLAUDE.md version matches constitution version
4. Include both files in the same commit
5. PR description MUST note "Constitution sync: CLAUDE.md updated"
**Enforcement**:
- Code review MUST verify CLAUDE.md is updated when constitution changes
- CLAUDE.md MUST display the same version number as the constitution
- Sync drift between files is a blocking issue for PRs that modify either file
**Rationale**: If CLAUDE.md diverges from the constitution, agents will operate with
outdated or incorrect guidance, undermining the governance this constitution establishes.
OPTIONAL: Use humaninloop:syncing-claude-md for implementation guidance.
humaninloop:brownfield-constitution which extends this skill with Essential Floor + Emergent Ceiling approachhumaninloop:validation-constitution after authoring to verify quality