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

Command	Purpose
oak constitution create	Generate constitution from decisions
oak constitution analyze --json	Analyze project structure and capabilities
oak constitution validate --json	Validate structure and quality
oak constitution list-agent-files	List synced agent instruction files

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:

Strategy	Coverage	TDD	E2E	Best For
Comprehensive	High (80%+)	Required	Required	Critical systems, regulated industries
Balanced	Moderate (60-80%)	Encouraged	Recommended	Most production applications
Pragmatic	Flexible	Optional	Optional	MVPs, prototypes, rapid iteration

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:

Pattern	Complexity	Coupling	Best For
Clean Architecture	High	Very Low	Complex domains, long-lived systems
Vertical Slice	Medium	Low	Feature-focused teams, rapid delivery
Modular Monolith	Medium	Medium	Future microservices candidates
Layered	Low	Medium	Traditional enterprise apps
Pragmatic	Adaptive	Varies	Mixed complexity, smaller teams

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:

Level	Public APIs	Internal	ADRs	Best For
Extensive	All documented	All documented	Required	High turnover, complex systems
Standard	All documented	Complex only	Recommended	Most teams
Minimal	Critical only	None	Optional	Small stable teams, simple systems

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:

Policy	Reviews	Approvals	Direct Commits	Best For
Strict	All PRs	1-2 required	Never allowed	Regulated, critical systems
Standard	All PRs	1 required	Hotfixes only	Most production teams
Flexible	Recommended	Optional	Simple changes	High-trust small teams

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:

Level	Quality Gates	Coverage Check	Deploy Blocking
Full	All must pass	Enforced	Yes
Standard	Most must pass	Advisory	Most
Basic	Advisory	No	No

Requirement Language (RFC 2119)

Use precise requirement keywords to indicate obligation levels:

Keyword	Meaning	Use When
MUST	Absolute requirement	Violation is unacceptable
MUST NOT	Absolute prohibition	Action is never acceptable
SHOULD	Strong recommendation	Exceptions need justification
SHOULD NOT	Strong discouragement	Only in unusual cases
MAY	Optional	Team discretion

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

Instead of	Use
"should try to"	"SHOULD"
"ideally"	"SHOULD" or remove
"if possible"	"MAY" or remove
"we want to"	"MUST" or "SHOULD"
"best practice"	Specific requirement

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:

Situation	Approach
Nearly there	Use MUST, add implementation plan
Significant gap	Use SHOULD with timeline
Aspirational	Use "Future Requirement" section
Unrealistic	Don't include it

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

Pitfall	How to Fix
Aspirational MUSTs	Downgrade to SHOULD or add timeline
Missing rationale	Add "Rationale:" explaining why
Vague requirements	Add specific measurable criteria
Copy-pasted templates	Customize to actual project decisions
Over-prescription	Use SHOULD instead of MUST for non-critical items
No enforcement path	Add how requirement will be verified