Constitution Governance Expertise

Guide the ongoing maintenance, amendment, and validation of engineering constitutions.

OAK Constitution Governance Workflow

Validate Current State  →  Propose Amendment  →  Apply & Version  →  Sync Agent Files

CLI Commands

oak constitution validate --json

oak constitution add-amendment

oak constitution update-agent-files

oak constitution list-agent-files --json

oak constitution analyze --json

Amendment Process

When to Amend

Amend the constitution when:

• Standards evolve: Team adopts new practices (e.g., TDD adoption)
• Reality changes: Project capabilities change (e.g., E2E infrastructure added)
• Gaps identified: Validation reveals missing or incorrect requirements
• Incidents occur: Post-mortems identify process improvements
• Team changes: New team composition requires different standards

Amendment Types (Semantic Versioning)

Constitution amendments follow semantic versioning:

Amendment Classification Guide

Major (Breaking):

• Changing MUST to MAY for core requirements
• Removing entire sections
• Fundamentally changing architectural pattern
• Reducing coverage requirements significantly

Minor (Additive):

• Adding new sections
• Adding new requirements (MUST/SHOULD)
• Documenting previously implicit practices
• Adding architectural pattern documentation

Patch (Clarification):

• Fixing typos and grammar
• Rewording for clarity (same meaning)
• Updating dates and metadata
• Adding examples to existing requirements

Amendment Workflow

1. Preflight Check
   └── Verify constitution exists
   └── Check current version
   └── Review recent amendments

2. Requirements Gathering
   └── Summary (< 80 chars)
   └── Detailed rationale
   └── Target section(s)
   └── Amendment type recommendation

3. Impact Analysis
   └── Quote affected sections
   └── Check against codebase reality
   └── Identify downstream effects

4. Apply Amendment
   └── oak constitution add-amendment
   └── Verify version bump
   └── Review diff

5. Sync Agent Files
   └── oak constitution update-agent-files --dry-run
   └── oak constitution update-agent-files
   └── Verify all files updated

6. Quality Review
   └── Run validation
   └── Check consistency
   └── Confirm next steps

Validation Framework

Quality Rubric (Score 1-5)

Structural Validation

Required sections (must exist):

• Metadata (version, author, date)
• Principles
• Architecture
• Code Standards
• Testing
• Documentation
• Governance

Metadata validation:

• Version follows semantic versioning (X.Y.Z)
• Dates follow ISO format (YYYY-MM-DD)
• Author is non-empty
• Status is valid (Draft, Ratified, Superseded)

Token validation:

• No template tokens remaining:

  {{

  ,

  }}

  ,

  [TODO]

  ,

  [PLACEHOLDER]

Language Validation

Check for weak language that should be strengthened:

• "should try to" → SHOULD
• "ideally" → SHOULD or remove
• "if possible" → MAY or be specific
• "best practice" → Specific requirement

Check for missing RFC 2119 keywords:

• Requirements without MUST/SHOULD/MAY are ambiguous
• Each requirement should have clear obligation level

Reality Alignment Validation

Compare requirements against project reality:

Alignment classifications:

• Aligned: Requirement matches reality
• Aspirational with plan: Gap exists but timeline documented
• Aspirational without plan: Gap exists, no timeline (flag as issue)
• Contradictory: Requirement contradicts reality (flag as critical)

Validation Severity Levels

Critical (must fix before adoption):

• Missing required sections
• Template tokens remaining
• Contradictions with adopted standards
• Reality contradictions without timeline

Major (should fix soon):

• Aspirational requirements without timelines
• Weak language in core requirements
• Missing rationale for MUST requirements
• Incomplete metadata

Minor (nice-to-have):

• Stylistic inconsistencies
• Missing examples
• Could use more detail
• Minor formatting issues

Agent Instruction Synchronization

What Gets Synced

Agent instruction files (e.g.,

CLAUDE.md

• Project-specific coding standards
• Testing requirements
• Documentation standards
• Architecture patterns
• Code review expectations

When to Sync

Sync agent instruction files:

• After any constitution amendment
• After adding new agents to the project
• When validation identifies drift

Sync Workflow

# Preview changes
oak constitution update-agent-files --dry-run

# Review the diff output

# Apply changes (creates backups automatically)
oak constitution update-agent-files

# Verify updates
oak constitution list-agent-files --json

Handling Sync Conflicts

When agent files have local modifications:

1. Backup existing: Always create backup before sync
2. Diff review: Compare constitution-derived vs. local content
3. Merge decision:
   • If local changes are obsolete: Allow sync to overwrite
   • If local changes are valuable: Amend constitution first, then sync
   • If both needed: Manual merge required

Governance Best Practices

Review Cadence

Change Log Maintenance

Track amendments in constitution:

## Amendment Log

| Version | Date | Type | Summary | Author |
|---------|------|------|---------|--------|
| 1.2.0 | 2025-01-15 | Minor | Added E2E testing requirements | @dev |
| 1.1.1 | 2025-01-10 | Patch | Clarified coverage enforcement | @lead |
| 1.1.0 | 2025-01-05 | Minor | Added Result Pattern for error handling | @dev |

Compliance Monitoring

Track constitution compliance:

1. Automated checks: CI/CD validates measurable requirements
2. Manual audits: Quarterly review of non-automatable requirements
3. Incident tagging: Link incidents to constitution requirements
4. Trend analysis: Track compliance over time

Common Governance Issues

Modernization Assessment

Old-Style Constitution Indicators

Detect constitutions that could benefit from modernization:

• No decision context: Requirements without "why"
• Hardcoded values: Fixed numbers without rationale
• Missing architecture: No architectural pattern documentation
• Template defaults: Generic requirements not customized
• Reality misalignment: Many aspirational MUSTs

Modernization Approaches

Recommended: Start with validation, then decide based on findings.