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

| Command | Purpose | |---------|---------| | oak constitution validate --json | Validate structure and reality alignment | | oak constitution add-amendment | Add versioned amendment | | oak constitution update-agent-files | Sync agent instruction files | | oak constitution list-agent-files --json | List synced agent files | | oak constitution analyze --json | Analyze project for reality checks |

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:

| Type | Version Bump | When to Use | Examples | |------|--------------|-------------|----------| | Major | X.0.0 | Breaking changes that invalidate existing requirements | Changing from TDD to test-after, removing mandatory reviews | | Minor | 0.X.0 | New requirements without breaking existing ones | Adding E2E requirements, new architectural section | | Patch | 0.0.X | Clarifications that don't change meaning | Fixing typos, clarifying ambiguous language |

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)

| Dimension | 1 | 3 | 5 | |-----------|---|---|---| | Clarity & Enforceability | Vague, untestable | Some clear, some ambiguous | All explicit and measurable | | Alignment with Standards | Contradicts practices | Mostly aligned | Fully reflects team practices | | Completeness & Coverage | Major gaps | Core areas covered | Comprehensive with rationale | | Consistency & Traceability | Contradictions present | Minor inconsistencies | Fully coherent | | Operational Readiness | Cannot act on it | Partially actionable | Teams can follow today |

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:

| Requirement Area | Validation Approach | |-----------------|---------------------| | Coverage targets | Run coverage tool, compare to target | | E2E tests | Search for e2e/integration test files | | CI/CD | Check .github/workflows, gitlab-ci, etc. | | Code review | Check branch protection, recent PR history | | Documentation | Check README, docs/, API docs existence |

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) are derived from the constitution and contain:

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:

Backup existing: Always create backup before sync
Diff review: Compare constitution-derived vs. local content
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

| Trigger | Review Type | Scope | |---------|-------------|-------| | Quarterly | Scheduled | Full constitution review | | Post-incident | Reactive | Affected sections | | Team change | Adaptive | Governance, onboarding sections | | Major release | Milestone | All sections |

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:

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

Common Governance Issues

| Issue | Symptom | Solution | |-------|---------|----------| | Drift | Agent files don't match constitution | Run sync workflow | | Staleness | Requirements outdated | Quarterly review + amendments | | Over-prescription | Too many MUSTs, team ignores | Downgrade to SHOULD, focus on critical | | Under-prescription | Inconsistent practices | Add specific requirements | | Reality gap | Requirements vs. actual practice | Add timelines or adjust requirements | | Version confusion | Unclear which version is current | Update metadata, sync agent files |

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

| Approach | When to Use | Effort | |----------|-------------|--------| | Validate only | Constitution mostly good, minor fixes | Low | | Incremental | Good structure, needs updates | Medium | | Regenerate | Significant gaps, easier to restart | High |

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