# Sage Constitution

> The project's engineering principles and non-negotiable process rules. Use when asking whether something is allowed, what the project's principles or conventions are, why a rule exists, or when a decision seems to conflict with the constitution.

- Skill: `xoai/sage-constitution` (Agent Skill)
- Install (CLI): `npx skillmds@latest add xoai/sage-constitution`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xoai/sage-constitution/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: xoai (https://skillmd.com/u/xoai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xoai/sage-constitution

---


# The constitution

The eager layer carries each principle as one line naming the mechanism that
enforces it. This carries the reasoning, and the rules that have no mechanism
behind them.

## Engineering principles

The base set, present in every project:

| # | Principle | Enforced by |
|---|---|---|
| 1 | **Tests before code** — every behavior has a test before implementation | `sage-tdd-gate.sh` (PreToolUse — blocks the edit) |
| 2 | **No silent failures** — errors handled, logged, or propagated | Gate 3 (judgment) |
| 3 | **Secrets never in code** — env vars or a secret manager | Gate 3 (judgment) |
| 4 | **Dependencies explicit** — declared, pinned | Gate 4 (`sage-hallucination-check.sh`) |
| 5 | **Changes reversible** — migrations reversible, deploys rollbackable | Gate 3 (judgment) |

Principles 6+ come from the project's preset and its own
`.sage/constitution.md`. They are appended by the generator, numbered
continuously, and they carry exactly the same weight as the base five. A
project addition is not a suggestion.

**Read the project's own additions before assuming the base five are the whole
story.** They are in `.sage/constitution.md`, and they are where the rules that
actually bite in *this* codebase live.

## The distinction that matters

Three of the five principles above are enforced by a *judgment* gate — which
means they are enforced by a reviewer noticing, and reviewers are exactly as
reliable as their attention. Two are enforced by a script that blocks the tool
call, and those two hold whether or not anyone is paying attention.

That is not a criticism of the three. Some rules genuinely cannot be checked
mechanically ("no silent failures" requires knowing what a silent failure looks
like *here*). But it is worth being honest about which rules are load-bearing
and which are aspirational, because the eval that produced this version of Sage
found that the mechanically-enforced rules moved behavior and the prose ones,
on their own, did not.

If a principle matters and has no mechanism, that is a gap in the mechanism —
not a reason to write the prose more forcefully.

## Process rules with no script behind them

These are enforced by the model reading them, which is a real but weaker thing.

**Rule 2 — Skills before assumptions.** If a Sage skill exists for the task at
hand, read it and follow it. Do not fall back on general training when a skill
provides a specific methodology. (This is the dispatcher rule, and it is in the
eager layer for a reason: if it fails to fire, nothing else here loads.)

**Rule 3 — Document decisions.** Decisions that affect the project get
recorded — for agents *and* for the humans who arrive later. Specs, plans,
ADRs, and briefs go to `.sage/work/` or `.sage/docs/`. Even a Tier 2 task
leaves a record of what was decided and why. Partially mechanical: the
spec-gate hook blocks source edits while a cycle is `pre-spec`, so the *spec*
half has teeth. The rest is on you.

## Rationalizations

| The thought | Why it fails |
|---|---|
| "This principle does not apply to test code" | Test code is code. It is also the code you will trust the most and read the least. |
| "The project preset does not mention it, so it is optional" | The base five apply everywhere. Presets add; they do not subtract. |
| "I will follow the principle, just not right now" | The commit is the artifact. "Later" does not appear in it. |
| "It is a prototype" | Prototypes ship. That is what makes them prototypes rather than sketches. |