Write enforceable, testable constitution content with proper principle structure, section templates, and RFC 2119 keywords. Use when creating constitutions, writing principles, defining governance, or when you see "constitution", "governance", "principles", "enforcement", or "amendment process". Core skill for greenfield projects.
Writes enforceable, testable constitutions with three-part principles, RFC 2119 keywords, and CLAUDE.md synchronization mandates.
/plugin marketplace add deepeshBodh/human-in-loop/plugin install deepeshbodh-humaninloop-plugins-humaninloop@deepeshBodh/human-in-loopThis skill inherits all available tools. When active, it can use any tool Claude has access to.
RFC-2119-KEYWORDS.mdSYNC-IMPACT-FORMAT.mdWrite 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.
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. If you can't test it, it's not a principle—it's 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 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 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 |
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.
See syncing-claude-md skill for implementation.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.