SAGE — Cognitive enforcement for AI software development

生き甲斐 · Ikigai

Code with intention.

Sage gives every AI agent the ikigai of your most senior dev — the balance of four questions it asks before writing a line, so it grows with your team instead of charging ahead.

Is it needed?

Does the team or product actually need this — or does something already cover it?

Will it last?

Is it worth maintaining, in the shape the codebase already follows?

Is it safe?

What's the blast radius — settlement, auth, data, money?

Did we agree?

Does it respect the rules the team already decided in agents/sage/?

The problem

AI agents generate confidently. They rarely understand.

They reinvent helpers that already exist, miss the payment flow three files over, and ship changes your team explicitly decided against last quarter. Markdown docs don't fix this — agents skip them. Sage makes understanding a required tool call, not a suggestion.

Intent → Impact → Risk

A required pipeline that names the domain, the blast radius, and a binding decision before any code — written as plain rules the agent must follow.

Reuse before you create

Surfaces the exact existing assets and conventions to follow, so agents import instead of reinventing.

Binding risk gates

ASK pauses for a human. REJECT stops cold. Code is validated before it's written.

Where it fits

Not another agent. The layer your agents are missing.

Coding agents are great at producing code. None of them make sure it's the right code for your system, or that it respects what your team already decided. Sage is the AGENTS.md they read first — it makes understanding mandatory.

Today's AI coding agents

—

Generate & edit code, fast

—

Personal, per-session memory

—

One developer, one machine

—

Optimize for speed of output

Sage · the cognition layer

✓

Enforces understanding before any code is written

✓

Team-shared, human-approved memory — git-synced

✓

Every repo, any agent — one shared protocol file

✓

Optimizes for correctness & team alignment

Point it at the agents you already use — Claude Code · Cursor · Codex · Copilot · Antigravity. It doesn't replace them. It makes them think first.

How it works

Your agent asks. Sage answers with cognition.

Before touching code, the agent follows the pipeline in AGENTS.md and reads the team's Markdown rules. Here's the verdict it must produce for a real request.

Your request

add a refund endpoint to /payments

What the agent does (per AGENTS.md)

1. read agents/sage/payment/   # rules + decisions
2. reuse before creating
3. emit Risk: / Decision: header
4. stop on ask | reject

Domain

payment · action: create

Requires

Idempotency keyAudit logAmount validation

Impact

3 services, 7 files — touches the settlement worker & webhook retry path.

Reuse

payments/refund_service.py already exists — extend it, don't recreate.

Decision

Ask — human confirmation

Team knowledge

One brain your whole team — and every agent — shares.

When someone states a team decision, the agent writes it as a Markdown file; a human approves it by flipping status: proposed to approved; git push shares it. Next time any agent in any repo touches that domain, the rule is right there. Personal agent memory can't do this — it isn't governed, approved, or shared.

agents/sage/payment/decisions/use-idempotency-keys.md

---
title: Use idempotency keys
domain: payment
status: approved
enforcement: block
---
All payment calls MUST pass an
idempotency key. No exceptions.

payment · block ✓ approved · in git

Use idempotency keys

Plain Markdown in your repo. Edit it, diff it, review it in a PR. The agent follows it on every payment change.

source: human · committed

✓

Human-approved memory. AI proposes, a person ratifies. Nothing trusted lands unreviewed.

✓

Workspace-scoped & multi-repo. One knowledge home, auto-linked across every repo in the product.

✓

Audit log. Every recall, save, and decision is recorded — who, what, when.

✓

Approval gates. High-risk changes wait in a queue until a human approves or rejects.

✓

Tool-agnostic. Any agent — Claude Code, Cursor, Codex, Copilot — reads the same Markdown.

The cognition layer that grows with your team.