shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

constitution-governance

Guide OAK constitution maintenance with amendment workflows, validation

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

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:

  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

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

  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

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