Compiled Directives

Compiled directives are the enforcement format for your architectural decisions. Tell Claude to compile your governance after capturing decisions, and it reads your accepted ADRs and active invariants and produces .claude/rules/governance.md — a short, actionable file Claude reads automatically every session.

The problem it solves

ADRs are detailed documents. An ADR for "use hexagonal architecture" might be 200 lines of rationale, alternatives considered, consequences, and context. That's valuable for humans reading the decision history. It's not the right format for Claude to enforce during coding.

The compiled output strips the rationale and extracts the directive:

ADR source (200 lines of context and rationale)

Compiled directive (1 line):
  - Keep business logic in the domain layer. No framework imports in domain/*.
    Adapters live in adapter/. (ref: ADR-003)

Same decision. Different format for different purposes. The ADR is the source of truth. The compiled output is the enforcement format.

How to compile

After capturing decisions with "Save this decision" or adding invariants with "That's a hard rule", tell Claude:

"Compile governance"

Or trigger it directly:

/edikt:compile

Claude reads all accepted ADRs and active invariants, extracts directives, and writes .claude/rules/governance.md.

✅ Governance compiled: .claude/rules/governance.md

  5 ADRs → 6 directives
  1 invariant → 1 directive
  7 total directives

  Claude will read these directives automatically in every session.

What gets compiled

Accepted ADRs — only ADRs with status: accepted are compiled. Draft ADRs represent decisions still in progress. Superseded ADRs are skipped (and flagged if still referenced by active specs).

Active invariants — only invariants with status: active are compiled. Revoked invariants are skipped.

Guidelines — files in docs/guidelines/ (if the directory exists) are compiled as team preferences. No status filtering — all guidelines are included.

# ADR frontmatter — status gates inclusion
status: accepted   # included
status: draft      # skipped
status: superseded # skipped, warns if referenced

The output file

Compile writes to .claude/rules/governance.md:

---
paths: "**/*"
---
<!-- edikt:compiled — generated by /edikt:compile, do not edit manually -->

# Governance Directives

## Architecture

- Claude Code is the only supported platform. Do not write code or
  configuration targeting Cursor, Copilot, or other tools. (ref: ADR-001)

## Implementation

- Use hexagonal architecture. Business logic in domain/. Adapters in adapter/.
  No framework imports in domain/. (ref: ADR-003)

## Constraints

- Every command and template must be a .md or .yaml file. No TypeScript,
  no compiled binaries, no build step. Non-negotiable. (ref: INV-001)

## Process

- Stop hook uses type:command with regex detection — not type:prompt.
  type:prompt breaks UX. (ref: ADR-005)

The paths: "**/*" frontmatter means Claude reads this file on every file it touches — not just specific types. Governance directives apply everywhere.

Contradiction detection

Before compiling, Claude checks for contradictions between accepted ADRs:

CONTRADICTION DETECTED
  ADR-001: "Claude Code only — no multi-tool support"
  ADR-007: "Support Cursor for rule distribution"

  Resolve before compiling. Supersede one or reconcile both.

Cross-source conflicts are also detected — guidelines that contradict ADRs or invariants:

CONFLICT: guideline vs invariant
  guidelines/testing.md: "Always mock the database in all tests"
  INV-001: "Integration tests must hit a real database, no mocks"

  Source: guidelines/testing.md (line 12) vs INV-001 (Rule section)
  Action: Scope the guideline to unit tests only, or amend INV-001.

Invariant conflicts are errors — invariants always win. ADR conflicts are warnings — the team decides.

CI validation

Run /edikt:compile --check in CI to validate without writing:

/edikt:compile --check

  Sources: 5 ADRs (4 accepted), 2 invariants (2 active), 1 guideline
  Contradictions: 0
  Conflicts: 0
  Directives: 8 would be generated

  All clear — governance compiles cleanly.

Exit code 1 if contradictions or conflicts exist. This catches governance drift in CI before it reaches production.

When to recompile

Recompile after:

• Telling Claude "Save this decision" (new ADR captured)
• Telling Claude "That's a hard rule" (new invariant added)
• Updating a guideline file
• Changing an ADR status (draft → accepted)

The command output will remind you when recompilation is needed:

Run /edikt:compile to update governance directives.

Guidelines

Guidelines are the extension point for team-specific knowledge that doesn't fit ADRs (decisions) or invariants (hard constraints). Examples:

• docs/guidelines/testing.md — "always test error paths first"
• docs/guidelines/api.md — "camelCase responses, snake_case DB columns"
• docs/guidelines/naming.md — "services end with Service, repos end with Repository"

Guidelines are freeform markdown. They compile into the ## Team Guidelines section of governance.md.

See /edikt:compile for full command reference.