Constitution Authoring

Constitution Authoring Expertise

Guide the creation of effective engineering constitutions that balance aspirational standards with project reality.

OAK Constitution Workflow

/oak.constitution-create  →  Analyze & Gather Decisions  →  Generate  →  /oak.constitution-validate

CLI Commands

File Structure

oak/
├── constitution.md              # Main engineering constitution
└── agent-instructions/          # Per-agent instruction files (synced)
    ├── CLAUDE.md
    └── ...

Decision-Driven Constitution Creation

Constitutions should be decision-driven, not template-filled. Each section should reflect explicit decisions about project standards.

Core Decision Points

1. Testing Strategy

Choose based on project maturity, team size, and risk tolerance:

Decision questions:

• What's the cost of a bug in production?
• How often does the team refactor?
• Is there existing test infrastructure?

2. Architectural Pattern

Choose based on domain complexity and team experience:

Decision questions:

• How complex is the business domain?
• Will the team grow significantly?
• Is eventual microservices extraction needed?

3. Documentation Level

Choose based on team turnover and system complexity:

Decision questions:

• How often do new engineers join?
• How complex is the domain?
• Is this a long-term system?

4. Code Review Policy

Choose based on team trust and risk tolerance:

Decision questions:

• What's the team's experience level?
• Are there compliance requirements?
• How fast must fixes be deployed?

5. CI/CD Enforcement

Choose based on infrastructure maturity:

Requirement Language (RFC 2119)

Use precise requirement keywords to indicate obligation levels:

Language Patterns

Strong requirement (MUST):

- All public APIs MUST be documented
- Tests MUST be deterministic and repeatable
- Security patches MUST be applied within 2 weeks

Recommendation (SHOULD):

- Complex logic SHOULD include inline comments
- Code reviews SHOULD be completed within 24 hours
- Integration tests SHOULD cover critical paths

Optional (MAY):

- Teams MAY use pair programming for complex features
- Documentation MAY include diagrams
- E2E tests MAY be skipped for internal tools

Avoid Weak Language

Reality Alignment

Constitution requirements must be achievable, not aspirational fantasies.

Reality Check Questions

Before adding a requirement, ask:

1. Current State: Does the project already do this? If not, what's needed?
2. Enforcement: Can this be checked automatically? If not, how is it verified?
3. Exceptions: When is it acceptable to deviate? Document the exception process.
4. Timeline: If aspirational, when will it be achievable?

Handling Gaps

When a requirement doesn't match reality:

Example: Coverage Gap

If constitution wants 80% coverage but project has 45%:

### Coverage Requirements

**Target:** 80% code coverage for new code

**Current State:** Project-wide coverage is 45%. New code MUST meet 80% target.
Existing code coverage will be increased incrementally per the Coverage Roadmap.

**Enforcement:** Coverage checks run in CI. New code below 80% will be flagged
but not blocked until Q2 2025.

Section Writing Guide

Principles Section

Goal: Define core values that guide all other decisions.

Include:

• Code quality philosophy
• Testing philosophy
• Documentation philosophy

Each principle needs:

• Clear requirements (MUST/SHOULD/MAY)
• Rationale explaining why

Architecture Section

Goal: Document the chosen architectural pattern and its implications.

Include:

• Pattern name and description
• Core principles of the pattern
• Specific requirements for following the pattern
• Rationale for choosing this pattern

Testing Section

Goal: Define the testing strategy with measurable requirements.

Include:

• Testing philosophy (comprehensive/balanced/pragmatic)
• Unit test requirements
• Integration test requirements (if applicable)
• E2E test requirements (if applicable)
• Coverage requirements with enforcement level

Governance Section

Goal: Define how the constitution itself is maintained.

Include:

• Code review policy
• Amendment process
• Versioning approach
• Review cadence

Quality Checklist

Before finalizing a constitution:

• All decisions documented: Each section reflects an explicit decision, not a default
• Reality-aligned: Requirements match current capabilities or have timelines
• Measurable: Requirements can be verified (automated or manual)
• Consistent: No contradictions between sections
• RFC 2119 language: MUST/SHOULD/MAY used consistently
• Rationale provided: Each requirement explains "why"
• No template tokens: All {{placeholders}} replaced
• Metadata complete: Version, author, date all present

Common Pitfalls