Versioning Constitutions

Core Principle

Constitution versions are immutable snapshots of architectural truth.

When foundational rules change (patterns, tech stack, architecture), create a new version rather than editing in place. This preserves history, enables rollback, and makes changes explicit.

When to Use This Skill

ALWAYS create a new version when:

Adding a new mandatory pattern (e.g., adopting effect-ts for error handling)
Removing OR relaxing a mandatory pattern (e.g., making next-safe-action optional)
Changing tech stack (e.g., migrating from Prisma to Drizzle)
Updating architectural boundaries (e.g., adding new layer)
Deprecating rules that are no longer valid
Major library version changes with breaking patterns (e.g., Next.js 15 → 16)

CRITICAL: Removing or relaxing a mandatory pattern ALWAYS requires a new version, even if existing code would still work. "Non-breaking" is not sufficient - any change to mandatory patterns needs versioning for audit trail.

Do NOT use for:

Fixing typos or clarifying existing rules (edit current version directly)
Adding examples to existing patterns (edit current version directly)
Project-specific implementation details (those go in specs/)

Test for Constitutionality:

Before adding content to constitution, ask: "If we violate this rule, does the architecture break?"

✅ Constitutional: "Must use next-safe-action" → violating breaks type safety & validation
❌ Not constitutional: "Forms should have wrapper, fields, button" → violating just looks different

Constitution = Architectural rules. Specs = Implementation patterns.

Process

Step 1: Determine Version Number

Read docs/constitutions/current/meta.md to get current version.

Version increment rules:

Increment by 1 (v1 → v2, v2 → v3)
No semantic versioning (major.minor.patch)
Sequential only

Step 2: Create New Version Directory

# Create new version directory
mkdir -p docs/constitutions/v{N}

# Copy structure from current
cp docs/constitutions/current/*.md docs/constitutions/v{N}/

Step 3: Update Content

Edit files in new version directory with changes:

meta.md - Update version number, date, changelog
architecture.md - Update if architectural boundaries changed
patterns.md - Update if mandatory patterns changed
tech-stack.md - Update if libraries added/removed
schema-rules.md - Update if database philosophy changed
testing.md - Update if testing requirements changed

Critical - Minimal Changes Only:

Only change what NEEDS changing for this version
NO reorganizing sections ("while I'm here")
NO reformatting code examples
NO alphabetizing lists
NO renaming headings for style
NO creating new categories unless absolutely required

The diff should show ONLY the substantive change, not stylistic improvements.

Step 4: Update Symlink

# Remove old symlink
rm docs/constitutions/current

# Create new symlink pointing to new version
ln -s v{N} docs/constitutions/current

Step 5: Verify References

Check that all references still work:

# Find all references to constitutions
grep -r "@docs/constitutions/current" .claude/
grep -r "docs/constitutions/current" .claude/

All references should use current/ symlink, never hardcoded versions.

Step 6: Document in meta.md

MANDATORY: Update meta.md with complete documentation:

New version number (e.g., "Version: 2")
Creation date (e.g., "Created: 2025-01-17")
Previous version reference (e.g., "Previous: v1")
Summary of WHAT changed (e.g., "Removed Redux prohibition")
Rationale for WHY (e.g., "React Server Components handle all state needs, Redux adds complexity without benefit")

The WHY is critical. In 6 months, the context will be lost. Document:

What problem does this change solve?
What decision or discussion led to this?
Why now vs earlier/later?

DO NOT rely on git commit messages or external docs. meta.md must be self-contained.

Quality Checklist

Before updating symlink:

New version directory exists at docs/constitutions/v{N}/
All 6 files present (meta, architecture, patterns, tech-stack, schema-rules, testing)
meta.md has correct version number and changelog
Changes documented with rationale (why, not just what)
Old version remains untouched (immutable)
References in commands use current/ not v{N}/

Common Mistakes

Mistake 1: Editing Current Version for Breaking Changes

Wrong: Edit docs/constitutions/current/patterns.md directly when removing next-safe-action requirement

Right: Create v2, update patterns.md in v2, update symlink

Why: Breaking changes need versioning. Commands/specs may reference old patterns.

Mistake 2: Hardcoding Version in References

Wrong: @docs/constitutions/v2/architecture.md

Right: @docs/constitutions/current/architecture.md

Why: When v3 is created, all references break. Symlink abstracts version.

Mistake 3: Reorganizing for Style

Wrong: "Let me alphabetize sections and rename files while versioning"

Right: Only change content that needs substantive updates

Why: Gratuitous changes obscure what actually changed. Diff should show real changes.

Mistake 4: Forgetting to Update meta.md

Wrong: Copy files, update content, update symlink, done

Right: Update meta.md with version, date, and changelog

Why: Future you won't remember why version changed. Document the why.

Mistake 5: Versioning Implementation Details

Wrong: Create v2 because we changed button component structure

Right: Constitution = foundational rules only. Implementation goes in specs/

Why: Constitution is for patterns/architecture/stack, not implementation choices.

Mistake 6: Rationalizing In-Place Edits

Wrong: "This change is non-breaking, so I can edit v1 in-place per the meta.md guidance"

Right: Removing/relaxing ANY mandatory pattern requires versioning, even if "non-breaking"

Why: Audit trail matters more than technical breaking changes. Future readers need to know WHEN rules changed, not just that they did. Git history is not sufficient - constitution versions create explicit snapshots.

Quick Reference

# Check current version
cat docs/constitutions/current/meta.md

# Create new version
mkdir -p docs/constitutions/v{N}
cp docs/constitutions/current/*.md docs/constitutions/v{N}/

# Edit content
# Update meta.md, then other files as needed

# Update symlink
rm docs/constitutions/current
ln -s v{N} docs/constitutions/current

# Verify
ls -la docs/constitutions/current
grep -r "constitutions/v[0-9]" .claude/  # Should return nothing

Example: Adding New Pattern

Scenario: We're adopting effect-ts for error handling and deprecating throw/catch.

Step 1: Current version is v1 (read meta.md)

Step 2: Create v2

mkdir -p docs/constitutions/v2
cp docs/constitutions/current/*.md docs/constitutions/v2/

Step 3: Update content

meta.md: Version 2, date, "Added effect-ts error handling pattern"
patterns.md: Add new section on Effect error handling
tech-stack.md: Add effect-ts to approved libraries
Leave other files unchanged

Step 4: Update symlink

rm docs/constitutions/current
ln -s v2 docs/constitutions/current

Step 5: Verify references (should all use current/)

Step 6: meta.md documents why (type-safe error handling, eliminate throw)

Testing This Skill

See test-scenarios.md for pressure scenarios and RED-GREEN-REFACTOR tests.

versioning-constitutions