
constitution
Manage project constitution files - rules, best practices, patterns, and guardrails for LLM/coding agents
- version
- 0.1.0
- GitHub stars
- 8
Install
/plugin install constitution@digital-dividend-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add thlandgraf/cc-marketplace.
Contents
Discovered from sourceSkills 1
Constitution Format Knowledge
Purpose
A constitution file defines rules, best practices, patterns, and guardrails for LLM and coding agents working in a project. Unlike human documentation, constitutions are optimized for token efficiency and machine parsing.
File Location
Standard locations (checked in order):
constitution.md(project root)doc/constitution.md
Token Budget
Hard limit: 25,000 tokens
Approximate conversion: 1 token ≈ 4 characters
Monitor size when adding rules. A well-written constitution for a medium project typically uses 5,000-15,000 tokens.
Structure
# Project Constitution
Brief one-line project description.
## <Category 1>
- Rule 1
- Rule 2 (rationale)
## <Category 2>
- Rule 3
- Prefer X over Y
- Avoid Z
Common Categories
| Category | Contents |
|---|---|
| Stack | Languages, frameworks, versions |
| Patterns | Required architectural patterns |
| Anti-patterns | What to avoid |
| Conventions | Naming, structure, organization |
| Testing | Testing requirements and approaches |
| Security | Security requirements |
| Performance | Performance constraints |
| Dependencies | Dependency rules |
Writing Effective Rules
DO
- Imperative voice: "Use X" not "You should use X"
- Be specific: "Use
constby default" not "Prefer immutability" - Include brief rationale: "Avoid any (breaks type safety)"
- Quantify when possible: "Max 300 lines per file"
- State the positive: "Use async/await" not "Don't use callbacks"
DON'T
- Write explanatory prose
- Include code examples (unless critical)
- Duplicate information
- Use filler words (very, really, always try to)
- Over-qualify (usually, in most cases, generally)
Rule Formats
Simple rule:
- Use TypeScript strict mode
Rule with rationale:
- Use TypeScript strict mode (catches null errors early)
Preference:
- Prefer composition over inheritance
Prohibition:
- Avoid `any` type
Conditional:
- Use server components by default; client components only for interactivity
Exception:
- Use strict mode (except legacy/ directory)
Quantified:
- Max 300 lines per file
- Min 80% test coverage for business logic
Example Constitution
# Project Constitution
TypeScript monorepo for e-commerce platform.
## Stack
- TypeScript 5.3+ strict mode
- React 18 with Server Components
- Next.js 14 App Router
- PostgreSQL with Drizzle ORM
- Vitest for testing
## Patterns
- Feature-based directory structure
- Repository pattern for data access
- Use server components by default
- Client components only for interactivity
- Collocate tests with source files
## Anti-patterns
- Avoid `any` type (use `unknown` if needed)
- No barrel exports in feature modules
- No circular dependencies
- Avoid prop drilling beyond 2 levels
## Conventions
- camelCase for functions/variables
- PascalCase for components/types
- kebab-case for files and directories
- Prefix interfaces with I (IUser, IProduct)
- Suffix types with Type only if needed for clarity
## Testing
- Unit tests for business logic (min 80% coverage)
- Integration tests for API routes
- E2E tests for critical user flows
- Use Testing Library, avoid implementation details
## Security
- Validate all user input at API boundary
- Use parameterized queries only
- No secrets in code or logs
- HTTPS only, secure cookies
Maintenance
- Review constitution when adding major features
- Remove rules for deprecated technologies
- Consolidate overlapping rules periodically
- Keep total under 25,000 tokens
Commands 3
Constitution Add Command
Add a new rule, best practice, or guideline to the project's constitution file based on the provided argument.
Workflow
1. Locate Constitution File
Search for existing constitution file:
constitution.md
doc/constitution.md
If no constitution exists, you will create one at constitution.md.
2. Analyze the Argument
Parse the ARGUMENT to determine:
- Is it a technology/framework (Angular, React, NestJS, etc.)?
- Is it a practice/pattern (use Prettier, prefer composition, etc.)?
- Is it a constraint/rule (no any types, max file size, etc.)?
3. Clarify Ambiguous Topics
For technologies and frameworks, use AskUserQuestion to clarify specifics:
Examples of clarifying questions:
| Topic | Clarifications Needed |
|---|---|
| Angular | Version (17+/16/legacy)? Template syntax (control flow/structural directives)? State (signals/rxjs/both)? |
| React | Version (18+/17)? Hooks vs class? State management (zustand/redux/context)? |
| Node.js | Runtime (node/bun/deno)? Module system (ESM/CJS)? |
| TypeScript | Strictness level? Target version? |
| CSS | Framework (Tailwind/CSS modules/styled-components)? |
| Testing | Framework (Jest/Vitest/Playwright)? Coverage requirements? |
| Database | ORM preference? Query style? |
4. Research Best Practices
For technologies or exotic topics, use WebSearch to find current best practices:
- Search for
"<topic> best practices 2024"or"<topic> coding standards" - Focus on official documentation recommendations
- Look for common anti-patterns to avoid
5. Compose Constitution Entry
Write a token-efficient entry following these principles:
DO:
- Use imperative voice: "Use X" not "You should use X"
- Be specific: "Use
constoverlet" not "Prefer immutability" - Include rationale briefly: "Use X (prevents Y)"
- Group related rules under headings
DON'T:
- Write prose or explanations
- Include examples unless critical
- Duplicate information
- Use filler words
Entry format:
## <Category>
- <Rule 1>
- <Rule 2> (rationale)
- Prefer X over Y
- Avoid Z (causes issues with W)
6. Add to Constitution
If constitution exists:
- Read current content
- Identify appropriate section (or create new one)
- Use Edit tool to add the new entry
If constitution doesn't exist:
- Create new file with header and first entry:
# Project Constitution
Guidelines and rules for LLM/coding agents working in this project.
## <Category>
- <Your new rule(s)>
7. Report Result
Output what was added:
Added to constitution.md:
## <Section>
- <Rule added>
- <Rule added>
Constitution size: ~X tokens (limit: 25,000)
Token Efficiency Guidelines
The constitution must stay under 25,000 tokens. When adding entries:
- Count approximate tokens (rough: 1 token ≈ 4 chars)
- If approaching limit, suggest consolidating existing rules
- Prioritize actionable rules over explanatory content
Examples
Input: Angular
Action: Ask about version, template flavor, state management, then research Angular best practices, add structured rules.
Input: "always use async/await over .then()"
Action: Add directly to Patterns section without clarification (rule is clear).
Input: htmx
Action: Research htmx best practices (exotic tech), ask about integration context, add rules.
Constitution Check Command
Check for violations against the project's constitution rules.
Workflow
1. Locate Constitution File
Search for constitution file:
constitution.md
doc/constitution.md
If no constitution exists, report:
No constitution found. Use /constitution:add to create one.
2. Load Constitution Rules
Read the constitution file and parse rules by section. Build a mental checklist of what to verify.
3. Determine Check Target
If ARGUMENT provided:
- File path → Check that specific file
- Directory path → Check all files in directory
- Description → Interpret and find relevant files
If NO ARGUMENT (default): Check the work done in the current session:
- Review files that were created or modified in this conversation
- Look at recent edits made by Claude
- Check any code that was written or changed
Use this bash command to see recent git changes as a starting point:
git diff HEAD~5 --name-only 2>/dev/null || git status --porcelain
4. Analyze Against Constitution
For each file/change being checked:
- Read the file content
- Compare against each relevant constitution rule
- Note any violations
Check categories:
- Patterns: Is the code following required patterns?
- Anti-patterns: Is the code using forbidden approaches?
- Conventions: Does naming/structure follow conventions?
- Technology rules: Are framework-specific rules followed?
- Constraints: Are limits/constraints respected?
5. Report Violations
Output a structured violation report:
## Constitution Check Results
**Target:** <what was checked>
**Constitution:** <path to constitution file>
### Violations Found
| # | Rule | Location | Issue |
|---|------|----------|-------|
| 1 | <rule violated> | `file:line` | <what's wrong> |
| 2 | <rule violated> | `file:line` | <what's wrong> |
### Suggested Fixes
1. **`file:line`** - <how to fix>
2. **`file:line`** - <how to fix>
### Summary
- Files checked: X
- Violations: Y
- Severity: <low/medium/high>
If no violations:
## Constitution Check Results
**Target:** <what was checked>
No violations found. Code complies with constitution.
Session Work Detection
When checking current session work without an argument:
- Recall conversation context - What files were discussed, created, or edited?
- Check modified files - Use git or file timestamps to find recent changes
- Focus on code changes - Prioritize checking actual code over documentation
Common session work patterns:
- New files created with Write tool
- Existing files modified with Edit tool
- Code generated in response to user requests
Violation Severity
Classify violations by impact:
| Severity | Description |
|---|---|
| High | Security risks, breaking constraints, critical anti-patterns |
| Medium | Pattern violations, convention breaks, suboptimal practices |
| Low | Style issues, minor convention deviations |
Examples
Input: (no argument) Action: Review files edited in current conversation, check against constitution rules, report any violations.
Input: src/components/
Action: Scan all files in src/components/, check each against constitution, report violations.
Input: the new auth module
Action: Find auth-related files, check implementation against constitution rules.
Constitution Clarify Command
Interpret user clarification to improve, refine, or correct existing constitution rules.
Workflow
1. Locate Constitution File
Search for constitution file:
constitution.md
doc/constitution.md
If no constitution exists, report:
No constitution found. Use /constitution:add to create one first.
2. Read Current Constitution
Load the entire constitution content to understand:
- Current sections and structure
- Existing rules that might relate to the clarification
- Overall context and patterns
3. Interpret the Clarification
Parse the ARGUMENT to understand the user's intent:
| Intent Type | Example | Action |
|---|---|---|
| Refinement | "prefer functional components over class components" | Add specificity to existing React rules |
| Correction | "actually we use Vitest not Jest" | Replace incorrect rule with correct one |
| Exception | "except in the legacy module" | Add exception clause to existing rule |
| Emphasis | "this is critical for security" | Elevate rule priority or add warning |
| Removal | "we no longer use Redux" | Remove outdated rules |
| Merge | "combine the testing rules" | Consolidate related rules |
4. Find Related Rules
Search the constitution for rules that relate to the clarification:
- Look for keyword matches
- Check for thematic connections
- Identify potential conflicts
5. Apply the Clarification
Use Edit tool to update the constitution:
For refinements/additions:
# Before
- Use React hooks
# After
- Use React hooks
- Prefer functional components over class components
For corrections:
# Before
- Use Jest for testing
# After
- Use Vitest for testing
For exceptions:
# Before
- Use TypeScript strict mode
# After
- Use TypeScript strict mode (except legacy/ directory)
For removals: Simply delete the outdated rule(s).
6. Show Changes
Output what changed:
## Constitution Updated
**Clarification applied:** <user's clarification>
### Changes Made
**Section:** <section name>
```diff
- <old rule>
+ <new rule>
Or for additions:
+ <new rule added>
Reason:
Constitution size: ~X tokens (limit: 25,000)
## Handling Ambiguous Clarifications
If the clarification is unclear or could apply multiple ways:
1. Show the possible interpretations
2. Ask which interpretation is correct
3. Apply once confirmed
Example:
The clarification "prefer composition" could mean:
- Add to React section: "Prefer composition over inheritance for components"
- Add to General section: "Prefer composition over inheritance in all code"
- Add to Testing section: "Prefer composition for test utilities"
Which interpretation is correct?
## Token Budget Awareness
When clarifying:
- Check if changes increase token count significantly
- If approaching 25,000 tokens, suggest consolidation
- Prefer making rules more concise when possible
## Examples
**Input:** `"we use tabs not spaces"`
**Action:** Find indentation rule, update to specify tabs.
**Input:** `"ignore the API layer for now"`
**Action:** Add exception to relevant rules excluding api/ directory.
**Input:** `"TypeScript 5.3 specifically"`
**Action:** Update TypeScript rules to specify version 5.3.
**Input:** `"merge all the naming conventions into one section"`
**Action:** Consolidate scattered naming rules into unified section.
Sponsors
Details
- Marketplace
- thlandgraf/cc-marketplace
- Source
- plugins/constitution
- Author
- Thomas Landgraf
- Category
- Community
- License
- MIT
- Keywords
- constitution, rules, best-practices, guardrails, patterns