A cognition protocol for coding agents

Your coding agent should have a first thought.

Sage makes AI read your team’s decisions, inspect what already exists, name the risk, and validate the result before calling the work done.

  1. 01Context
  2. 02Reuse
  3. 03Risk
  4. 04Evidence
Install Sage → Read the source
decision-trace.md thinking
request / add discount coupons to checkout
  1. context payment rules and checkout flow loaded
  2. reuse existing promotion service found
  3. risk total recalculation must stay idempotent
  4. evidence build, tests, and diff checked
PROCEED reuse the existing boundary; preserve total invariants
FORMAT Plain Markdown Review it in the same pull request as your code.
COMPATIBILITY Agent-agnostic Works with Codex, Claude Code, Cursor, Copilot, and more.
FOOTPRINT No runtime No server, account, database, or hidden team memory.
The problem

Fast code is cheap. Wrong code is expensive.

Agents can produce plausible changes in seconds. The expensive failures happen before typing: missing context, invented patterns, and risks nobody named.

01 Context

Context gets skipped

The agent solves the prompt but misses the architecture, vocabulary, and decisions your team already made.

Sage loads the team’s rules and decisions first.
02 Reuse

Existing code gets reinvented

A new helper looks reasonable in isolation while duplicating a tested boundary that was already in the repository.

Sage reads real exports and patterns before adding more.
03 Risk

Risk stays implicit

Authorization, money, destructive operations, and public contracts need explicit controls—not confident prose.

Sage names the risk and stops only for decisions that matter.
04 Evidence

“Done” has no evidence

Agents report confidence where they should report validation output.

Sage requires the real build, test, or validation output and reports the residual risk.
How it works

A repeatable thought before every change.

The protocol turns good engineering judgment into a sequence any compatible coding agent can follow.

  1. 01
    Read

    Load the team’s context

    Use the role, rules, and decisions relevant to this change.

  2. 02
    Inspect

    Find what already exists

    Read the actual exports and patterns before proposing another.

  3. 03
    Judge

    Name risk and controls

    Restate the task and its done-criteria, then separate routine work from changes that need a human decision.

  4. 04
    Build

    Make the smallest coherent change

    Preserve contracts and keep the work inside the agreed scope.

  5. 05
    Prove

    Validate and remember

    Run real checks, report evidence, and capture durable knowledge.

The difference

The same agent. A better first move.

Sage does not replace your coding agent. It gives that agent a visible, reviewable operating discipline.

prompt→code

Without Sage

  • Starts coding directly from the prompt
  • Guesses internal APIs from filenames
  • Treats every unknown as an implementation detail
  • Reports confidence instead of validation output
prompt→thought→code

With Sage

  • Restates the task and what “done” means before coding
  • Reads the relevant team context first
  • Inspects reusable code before adding more
  • Stops only for decisions that genuinely change the outcome
  • Closes with evidence and residual risk
Install

Start in three steps.

One command installs the protocol. It adds the Sage protocol, command adapters, and knowledge structure for the coding tools you select.

  1. Run the installer in your repository

    bash -c "$(curl -fsSL https://cdn.jsdelivr.net/gh/qorstack/sage@latest/install.sh)"
  2. /sage-learning

    Run once to learn the project’s real patterns.

  3. /sage your task

    Then start each code change in plain language.

How to use it

Describe the result. Sage chooses the route.

You mostly run /sage. The protocol decides whether to begin, clarify a decision, or map a larger uncertain effort.

Clear request

Start the work

Read context, assess risk, implement, and validate.

One-session fog

Grill the decision

Ask only the questions whose answers change the build.

Large uncertainty

Map the frontier

Use Wayfinder to coordinate research and decisions across sessions.

Idea→Grill→Flow→Ticket→Build→Review
Workspace

One effort. One place to look.

Decisions, system design, implementation tickets, and focused evidence stay together under one durable flow workspace. 

agents/sage/flows/checkout/
├── index.md          # start here
├── spec.md           # clarified requirements
├── flow.md           # end-to-end design
├── tickets.md        # buildable outcomes
└── evidence/
    ├── index.md      # searchable catalog
    ├── screenshots/  # smallest useful visual proof
    ├── traces/       # focused runtime evidence
    └── logs/         # relevant extracts

Context survives handoffs

Every command reuses the same stable workspace slug.

Evidence stays focused

Capture the smallest useful screenshot, trace, or log first.

Humans can review everything

It is all Markdown, ordinary files, and normal Git history.

Make judgment part of the coding workflow.

Install Sage → Star on GitHub