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-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add thlandgraf/cc-marketplace.

Contents

Discovered from source

Skills 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):

  1. constitution.md (project root)
  2. 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

CategoryContents
StackLanguages, frameworks, versions
PatternsRequired architectural patterns
Anti-patternsWhat to avoid
ConventionsNaming, structure, organization
TestingTesting requirements and approaches
SecuritySecurity requirements
PerformancePerformance constraints
DependenciesDependency rules

Writing Effective Rules

DO

  • Imperative voice: "Use X" not "You should use X"
  • Be specific: "Use const by 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:

TopicClarifications Needed
AngularVersion (17+/16/legacy)? Template syntax (control flow/structural directives)? State (signals/rxjs/both)?
ReactVersion (18+/17)? Hooks vs class? State management (zustand/redux/context)?
Node.jsRuntime (node/bun/deno)? Module system (ESM/CJS)?
TypeScriptStrictness level? Target version?
CSSFramework (Tailwind/CSS modules/styled-components)?
TestingFramework (Jest/Vitest/Playwright)? Coverage requirements?
DatabaseORM 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 const over let" 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:

  1. Read the file content
  2. Compare against each relevant constitution rule
  3. 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:

  1. Recall conversation context - What files were discussed, created, or edited?
  2. Check modified files - Use git or file timestamps to find recent changes
  3. 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:

SeverityDescription
HighSecurity risks, breaking constraints, critical anti-patterns
MediumPattern violations, convention breaks, suboptimal practices
LowStyle 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 TypeExampleAction
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:

  1. Add to React section: "Prefer composition over inheritance for components"
  2. Add to General section: "Prefer composition over inheritance in all code"
  3. 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

More from thlandgraf/cc-marketplace

All 4