versioning-constitutions

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}/