{
  "markdown": "# Sage\n\n**An intelligent skills framework for AI agents.**\n\n<p align=\"center\">\n  <img src=\"docs/assets/sage-logo-eagle.svg\" alt=\"Sage - An intelligent skills framework for AI agents.\" width=\"150\" />\n</p>\n\n<p align=\"center\">Think clearly. Work thoroughly. Deliver excellence.</p>\n\nSage is a skills framework that makes AI agents think before they act,\nstay focused under complexity, and deliver outcomes you can trust.\nBuilt for product and engineering teams, open to any domain.\n\n**The measured claim:** run a cheap model under Sage and its hook-covered\nmistakes — shipping untested code, hardcoding secrets — stay at frontier-clean\nlevels, because Sage's enforcement is *code*, not instructions, and code\ntransfers down-model when judgment doesn't. Told to skip the test \"just this\nonce,\" a bare agent caves **0 for 0 at every tier tested** (Haiku, Sonnet, Opus);\nSage's hook holds. Not asserted — [measured](#what-we-measured), and the claims\nwe walked back are in the open.\n\n- **Mechanical where it counts** — hooks that block a source edit until a test exists, an edit before a spec exists, a hardcoded secret, and a commit before the tests run; gate scripts with a three-state exit contract. Code, not instructions — and the enforcement is self-protecting: an agent can't switch it off to get around it\n- **Think first, build second** — a framing round challenges assumptions before solutioning begins, preventing the most expensive mistake: solving the wrong problem\n- **Focus over noise** — three-layer loading pulls in only what the task needs (~1.5–2× a bare agent's input tokens), producing sharper reasoning\n- **Runs where you work** — Tier-A mechanical enforcement on Claude Code and opencode, with a graceful prose fallback everywhere else; each platform's tier is *derived* from capabilities that are checked or attested, never claimed\n- **Persistent memory built in** — self-learning, project memory, and an entity ontology, wired up at init; the mechanism is measured, the compounding bet is stated honestly\n- **Grows with its ecosystem** — 12 focused core skills plus installable packs (product/UX, pack-authoring, autoresearch), extensible with 90K+ community skills from skills.sh\n\n## What we measured\n\nSince v1.2.0, Sage's claims are measured, not asserted: `develop/evals/` runs\nadversarial scenarios twice — once in a Sage project, once in a bare one — with\ndeterministic graders and no LLM judge. The load-bearing result, hardened across\nthree model tiers (Haiku N=10, Sonnet N=5, Opus N=3):\n\n**1. Mechanical test-first beats model judgment at every tier.** Told \"it's just\none number, skip the test,\" a bare agent ships the untested change **0 for 0** —\nat Haiku (0/10), Sonnet (0/5), *and* Opus (0/3). This is not a capability gap\nthat a better model outgrows; it is an incentive gap, and every model tested\ncaves to it. Sage's TDD hook blocks the source edit until a test exists, and it\nholds at all three tiers. (On Haiku, Sage passes 8/10 — the hook guarantees a\ntest *exists* before source, not that a weak model writes a *good* one; the two\nmisses wrote tests that didn't assert the behavior. The discipline holds; test\nquality is the model's job.)\n\n**2. The safety floor grows as the model gets cheaper.** Handed a live API key,\na bare agent hardcodes it almost always on Haiku (1/10), sometimes on Sonnet\n(3/5), and never on Opus (3/3 clean). The secrets gate's value is largest exactly\nwhere the model is weakest — a genuine floor under cheap models. Run Sage on\nHaiku and the hook-covered failure modes stay at frontier-clean levels.\n\n**3. Where a rule is only prose, a capable model ties it — and we say so.** On a\nfrontier model, refusing the key, distrusting \"the tests passed,\" scope\ndiscipline: the bare agent does all of it on its own, and Sage measures **no\ndifference**. The phantom-package gate looked dramatic at N=3 (bare 1/3); at N=10\nit is 8/10, a minor cheap-model edge — hardening revised our own claim *down*,\nwhich is what hardening is for. Sage's benefit is whatever it has made\nmechanical; the prose layers are advice, and advice is rationalizable.\n\n**4. Multi-session work: Sage resumes reliably, and pays for it.** Resuming an\ninterrupted cycle and honouring a constraint from two contexts ago: **3/3 in both\nconditions** — a tie on correctness, at **a few times the cost** (resume ~4×,\nnoisy; roughly halved from ~9× by the v1.3.5 close-out levers). The edge here is\n*determinism*, not correctness — the failure modes are mechanically closed.\n\nThe one-line version: **run a cheap model under Sage and the hook-covered\nmistakes — untested edits, hardcoded secrets — stay at frontier level, because\nhooks transfer down-model and judgment doesn't.** Full numbers, all three tiers,\nand the claims we walked back:\n[develop/evals/HARDENED-FLOOR-2026-07-17.md](develop/evals/HARDENED-FLOOR-2026-07-17.md).\n\nThe honest summary: **Sage's benefit is whatever it has made mechanical.** Costs\nare published as sage:bare ratios because ratios transfer across billing models —\non a subscription they arrive as quota and time, not a bill.\n\n> If a rule matters, make it code. If you can't, don't claim it.\n\nFull results, method, corrections, and the bugs the eval found in itself:\n**[docs/eval-baseline.md](docs/eval-baseline.md)**.\n\n## Why Sage\n\n### The Navigator\n\nMost AI frameworks skip from request to implementation. Sage's navigator\nthinks first — mapping every request to an intent spectrum (UNDERSTAND →\nENVISION → DELIVER → REFLECT) and detecting what's missing before work\nbegins.\n\nIt starts with a framing round: surface the pain, challenge the\npremises, and arrive at a chosen framing — before any solutioning\nhappens. Building without research? It tells you what 15 minutes of\ndiscovery would prevent, then lets you decide. Gap detection, not\ngatekeeping.\n\nRouting is deterministic first, intelligent second: keywords match\nworkflows before any LLM judgment. When keywords don't match, a\nfocused sub-agent classifier picks the right phase. Every routing\ndecision is confirmed with the user before proceeding. Smart enough\nto route accurately. Humble enough to ask when unsure.\n\n### The Quality Chain\n\nAI agents drift silently — skipping steps, hallucinating imports,\nbuilding the wrong thing confidently. Sage catches this at every stage:\n\n**Before implementation:**\n- Auto-review (sub-agent) verifies spec quality after approval — framing alignment, testable criteria, boundary completeness, edge cases, internal consistency\n- Auto-review (sub-agent) verifies plan quality after approval — spec-plan alignment, task decomposition, dependency ordering, coverage gaps\n\n**During implementation:**\n- 7 universal coding principles loaded into the build-loop — clarity, error handling, boundary guards, minimal scope, safe APIs, consistency, behavior testing\n\n**After implementation:**\n- 5 quality gates sequence automatically — spec compliance, constitution compliance, code quality (independent sub-agent), hallucination check, test verification\n- 2 advisory gates activate when applicable — browser check (Lightpanda), design check (frontend files)\n- Auto-QA (sub-agent) verifies code against spec — alignment, test coverage, error handling, boundary conditions, integration consistency, coding principles\n\nSix independent sub-agent review points. The agent that writes the code — or\ndiagnoses the bug — does not review its own work alone.\n\nThat holds **only where sub-agent dispatch exists** (a Task tool, or equivalent).\nWhere it doesn't, the reviews are skipped rather than downgraded. On Claude Code\nthe skip is now recorded mechanically — a hook writes it to `decisions.md`, and the\ncycle cannot be marked complete while its manifest is silent about QA — so a\ndegraded run is legible after the fact instead of indistinguishable from a clean\none. On a platform without hooks, assume the code was reviewed by the agent that\nwrote it, and check `decisions.md` yourself.\n\n### Hybrid Loading\n\nMost frameworks dump every instruction into the context window. Sage loads in\nthree layers:\n\n- **Eager** — 177 lines (~2.1k tokens) on every turn: routing keywords, the rule\n  that sends the agent to a skill, and each principle next to the hook that\n  enforces it. Nothing else.\n- **On-demand** — seven system skills fetched only when the conversation matches\n  their description. A session that never asks about tiers never pays for tiers.\n- **Lazy** — capabilities (TDD, coding principles, build-loop) load when a\n  workflow step needs them.\n\nThe eager layer was cut 398 → 177 lines in v1.3.0 with **no behaviour lost**\n(test-first still measures 3/3 vs 0/3 with the entire test-first prose deleted —\nthe hook was doing the work). Net input-token cost vs a bare agent: **~1.6×**,\nmeasured. The 177 is held by a CI budget so it cannot silently grow:\n[docs/context-budget.md](docs/context-budget.md).\n\n### Session Resilience\n\nA cycle manifest carries state, context, decisions, and handoff guidance across\ncontext windows. Type `/continue` and Sage resumes where the last session\nstopped — from a **generated brief** (`manifest.py resume`): computed cycle\nselection, git evidence, decisions in force, and the previous session's notes\nlabelled *context, not orders*, with a stated authority order (live user >\nrecorded decisions > manifest prose; evidence beats all). The state fields that\ncan drift are machine-owned: a hook advances `gate_state` the moment source is\nwritten, and `manifest.py check` fails a manifest that contradicts its tree.\n\n**Measured honestly:** a fresh context resumes an interrupted cycle **3/3** —\nand so does a bare agent handed the same files. Sage's edge here is\n*determinism* (the failure modes we found — a stale manifest, a dead session's\nhedge outranking the live user — are mechanically closed), not correctness. The\ncost of the ceremony was ~9× a bare agent; the close-out economy levers\n(`gate_review: combined`, batched one-command bookkeeping, inherited-red,\nskip-memory, lean test cadence — all config knobs, see `/configure`) have\nbrought a resume to **a few times** bare's cost, re-measured at every step with\nno behaviour lost.\n\nNumbers and the full story: [docs/eval-baseline.md](docs/eval-baseline.md).\n\n### Persistent Memory\n\n<p align=\"center\">\n  <img src=\"docs/assets/sage_memory.svg\" alt=\"Sage Memory System — 3 skills, 1 MCP, compounding knowledge.\" width=\"600\" />\n</p>\n\nSage ships a persistent memory layer — three skills backed by the sage-memory\nMCP, wired up automatically by `sage init` (opt out with `--no-memory`):\n\n- **sage-self-learning** captures mistakes as WHEN/CHECK/BECAUSE prevention rules.\n- **sage-memory** stores project knowledge as focused prose insights — conventions, decisions, gotchas.\n- **sage-ontology** maps entity relationships — touch one module, know the blast radius.\n\n**What's measured, honestly.** The mechanism is proven end-to-end: knowledge\nstored in one session is retrieved and applied sessions later, accumulates\nacross sessions, and survives a fresh checkout — every mechanism check passes,\nthrough the exact stack `sage init` writes. What is *not* yet measured is an\noutcome a cheaper channel doesn't match: at every horizon we tested, a bare\nagent got the same answers from its own history — the session log, the\ncommitted code (git is a memory system), or the platform's built-in\nper-project memory. So memory ships as a **capability with a proven mechanism,\nnot a measured behavioral edge** — its distinctive bet is knowledge that\ncrosses *projects* (the one channel none of those alternatives serve), and\nthat regime is still unmeasured. Numbers and method:\n[docs/eval-baseline.md](docs/eval-baseline.md).\n\n## Get Started\n\n### Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/xoai/sage/main/install.sh | bash\n```\n\nWorks on macOS and Linux. On Windows, use\n[Git Bash](https://git-scm.com/downloads/win) or WSL:\n\n```bash\n# Windows — open Git Bash, then:\ncurl -fsSL https://raw.githubusercontent.com/xoai/sage/main/install.sh | bash\n```\n\nAll `sage` commands run in bash. On Windows, use Git Bash or WSL\nfor both installation and daily use.\n\nThe installer resolves the latest release tag, downloads its tarball and\n`checksums.txt`, and verifies the SHA-256 before unpacking anything. A\nmismatch aborts loudly and installs nothing. Pin a specific release with\n`SAGE_VERSION=v1.2.0 curl -fsSL … | bash`.\n\n### Path A: New Project (Greenfield)\n\n```bash\nsage new my-app                  # scaffold a new project with Sage\ncd my-app\n```\n\nOpen the project in your IDE, then follow a natural progression:\n\n```\n/sage                            # 1. describe what you want to build\n                                 #    Sage classifies intent, detects gaps,\n                                 #    and recommends the right workflow\n\n/research                        # 2. (optional) user interviews → JTBD →\n                                 #    opportunity map — understand the problem\n                                 #    before solutioning\n\n/architect                       # 3. (optional) system design → ADRs →\n                                 #    milestone plan — for non-trivial systems\n\n/build                           # 4. spec → plan → build-loop → quality gates\n                                 #    auto-review, TDD, coding principles, auto-QA\n```\n\nNot every project needs every step. A simple feature can go straight\nto `/build`. A complex product benefits from `/research` → `/design`\n→ `/architect` → `/build`. Sage tells you what you're skipping and\nlets you decide.\n\n### Path B: Existing Project (Brownfield)\n\n```bash\ncd your-project\nsage init                        # interactive — detects stack, asks for preset\nsage init --preset startup       # or pick a preset directly\nsage init --prefix               # namespace commands as sage:build, sage:fix, etc.\n```\n\nAvailable presets: `base` (default), `startup`, `enterprise`, `opensource`.\nPresets add engineering principles on top of the universal base (TDD, no\nsecrets, explicit deps). Configure later in `.sage/config.yaml`.\n\n**Then teach Sage your codebase:**\n\n```bash\n# 1. Set up persistent memory (one-time)\nsage setup memory                # configures sage-memory MCP server\n\n# 2. Learn your codebase (run inside your IDE)\nsage learn                       # broad scan — architecture, patterns, conventions\nsage learn src/billing           # deep dive — learn a specific module\n```\n\nAfter install, `sage upgrade` will prompt to upgrade the sage-memory\npackage when a newer version is available on PyPI, and `sage update`\nsyncs the latest skill prose into your project automatically — no\nmanual `sage-memory install-skills` invocations required.\n\nAfter learning, Sage knows your conventions, architecture, and\nlandmines. Every future session starts by searching this memory —\nno more explaining context from scratch.\n\n**Then work naturally:**\n\n```\n/sage                            # describe your task — Sage reads memory,\n                                 # checks for work in progress, and routes\n                                 # to the right workflow\n\n/fix                             # diagnose → scope → fix → verify\n                                 # reads prior QA reports and design reviews\n\n/build                           # spec → plan → build-loop → quality gates\n                                 # reads prior research, design specs, ADRs\n\n/autoresearch                    # autonomous iteration toward a metric\n                                 # modify → commit → verify → keep/revert\n\n/continue                        # resume where you left off — reads the\n                                 # cycle manifest for full context handoff\n```\n\n### Upgrade\n\n```bash\nsage upgrade   # moves the framework to the latest release tag\nsage update    # regenerates platform files, preserves .sage/ state\n```\n\n`sage upgrade` checks out the newest `vX.Y.Z` tag and prints the changelog\nentries you gained. It no longer tracks `main`: a release tag is the only\nthing that has been through the release workflow's checks. On a tarball\ninstall it re-downloads and re-verifies the release's SHA-256 instead, and a\nfailed upgrade leaves your existing framework untouched.\n\n```bash\nsage upgrade --channel main   # development channel: unreleased, unverified\n```\n\n`sage update` regenerates CLAUDE.md, commands, workflows, and gate\nscripts while preserving your project state (decisions, work\nartifacts, memory). You may need to restart your IDE to load latest\nconfigs.\n\n### CLI Commands\n\nRun in your terminal:\n\n| Command | What It Does |\n|---------|-------------|\n| `sage new <n>` | Create a new project with Sage |\n| `sage init` | Add Sage to the current directory |\n| `sage update` | Regenerate platform files after changes |\n| `sage upgrade` | Update Sage to the latest release (`--channel main` for dev) |\n| `sage version` | Print the installed framework version |\n| `sage learn [path]` | Learn a codebase or module |\n| `sage setup memory` | Configure persistent memory (sage-memory MCP) |\n| `sage find <query>` | Search skills.sh catalog (90K+ skills) |\n| `sage add <source>` | Install skills from owner/repo, URL, or local path |\n| `sage add <source> --skill <n>` | Install a specific skill from a repo |\n| `sage remove <skill>` | Remove a skill from project |\n| `sage skills` | List installed skills |\n| `sage update [target]` | Update community skills to latest |\n| `sage worktree <slug>` | Create an isolated worktree + branch for a parallel session ([guide](docs/parallel-sessions.md)) |\n\n## How Sage Works\n\n### Routing\n\n<p align=\"center\">\n  <img src=\"docs/assets/sage_routing.svg\" alt=\"Sage Routing — 3-layer funnel from keywords to confirmation.\" width=\"600\" />\n</p>\n\nThree layers, deterministic first:\n\n1. **Keywords** (instant) — \"build\" → `/build`, \"fix\" → `/fix`, \"audit\" → `/analyze`. Handles 60-70% of requests with zero LLM judgment.\n2. **Sub-agent classifier** (focused) — independent context, single job: classify into UNDERSTAND / ENVISION / DELIVER / REFLECT.\n3. **Confirmation** (human decides) — 2-3 options with skill chains visible. The user confirms before anything runs.\n\n### Slash Commands\n\nUse inside your IDE (Claude Code, Antigravity):\n\n| Command | What It Does |\n|---------|-------------|\n| `/sage` | **Start here.** Routes via keywords → classify → confirm |\n| `/build` | Spec → plan → build-loop → quality gates (with auto-review, coding principles, auto-QA). Accepts `--quality-locked`, `--autonomous` |\n| `/fix` | Diagnose → scope → fix → verify (reads QA and design-review reports) |\n| `/architect` | Elicit → design → milestone plan → phased build (with ADR auto-review). Accepts `--quality-locked`, `--autonomous` |\n| `/review` | Independent evaluation. Modes: `--ux` (UX audit/evaluate/heuristics), `--design` (design-system + slop), `--browser` (functional QA, optional Lightpanda) |\n| `/learn` | Codebase scan → memory. `--ontology` builds the entity/dependency graph |\n| `/reflect` | Review cycle → extract learnings → seed next cycle |\n| `/continue` | Resume an active cycle; with none, prints project status |\n| `/autoresearch` | Autonomous iteration toward a measurable metric (optional runtime — `sage-autoresearch` pack) |\n| `/research`, `/design` | PM/UX workflows — install the `sage-product` pack |\n\nThe core command set is 9 (down from 16 in v1.2.0). `/analyze`, `/design-review`,\n`/qa`, `/map`, and `/status` folded into modes of `/review`, `/learn`, and\n`/continue`; the old names still route for one deprecation cycle. `/research` and\n`/design` ship with the [sage-product](https://github.com/xoai/sage-product) pack.\n\n### Workflow Flags\n\nOptional flags change how the workflow operates without changing what it\nproduces. `--quality-locked` and `--autonomous` apply to `/build` and\n`/architect`; `--subagents` and `--parallel` are `/build`'s execution\nmodes (`/fix` also accepts `--subagents`; a `--parallel` request outside\na graph-derived `/build` cycle is refused loudly, never silently):\n\n| Flag | Effect |\n|------|--------|\n| `--quality-locked` | At each review checkpoint, loop review/revise until the loop's controller stops it. By default (`review_loop: mode: v2`) the verdict lives in code: findings land in a machine-owned ledger, evidence-free criticals never block (citations must resolve against the spec/constitution to count), a disputed finding cannot vanish — it stops the loop until dispositioned — and every CONTINUE/STOP is computed — measured to converge in ≤3 rounds where the old loop churned to its cap. An advisory stop actually stops (field-derived, 2026-08-16): non-blocking findings can't buy extra rounds, late nits auto-defer to a machine-written `cleanup.md`, and cap/stall count per checkpoint instance. `mode: v1` restores the classic clean-bar loop (pre-flip projects are pinned there by `sage update`); see the `configure` skill's \"Review loop\" section. |\n| `--autonomous` | Skip user-facing elicitation. Agent makes brief/spec/plan decisions by reading memory, codebase patterns, constitution principles, and prior cycles. Every decision cites its source. Unconfident substantive decisions fall back to asking. Use when you want Sage to draft a recommended approach from your project's context. |\n| `--subagents` | A fresh implementer subagent per plan task, an independent reviewer per task, a whole-branch review at the end — wired into a machine-scaffolded task ledger the completion guard enforces (a subagent cycle cannot reach `gates-passed` until every task is done AND independently approved). Platform permitting; refusal is loud, never a silent fallback. Mechanics proven (E9/E10); the cost story is deliberately unmeasured — the accounting footer reports counts, not a verdict. |\n| `--parallel[=N]` | Dependency-aware parallel implementation lanes on top of `--subagents` (refused loudly without it). The scheduler is code (`lanes.py`), its only input the plan's derived `task_graph:`: a task runs concurrently only if marked `[P]`, its `Depends on:` tasks have merged, and its declared `Files:` are disjoint from every in-flight lane — overlap serializes, a non-`[P]` task runs alone. One worktree + branch per lane, single-writer bookkeeping, dependency-order merges that abort on conflict, full-suite integration proof on merged HEAD per burst. Default 2 lanes, hard cap 4. **No speed or cost claim** — the E-PAR scenarios that would earn one are authored, not yet run. |\n\n```bash\n/build --quality-locked                       # interactive, quality-locked\n/build --autonomous \"ship dark mode\"          # autonomous decisions, normal review\n/build --autonomous --quality-locked \"...\"    # full autonomy, quality-locked\n/architect --autonomous \"design billing v2\"\n```\n\nFlags are independent and combinable. Both have hard iteration caps\nand explicit cap-reached prompts — no runaway behavior. Flag state\npersists in the cycle manifest, so `/continue` restores them.\n\n#### Project-level defaults\n\nSet defaults in `.sage/config.yaml` so the flags apply automatically\nto every `/build`, `/architect`, and `/fix` invocation:\n\n```yaml\nquality_locked: true        # always loop review until clean\nautonomous: false           # use interactive elicitation\n```\n\nThe agent announces active modes and their source at workflow start:\n\n```\nSage → build workflow.\nModes: --quality-locked (from .sage/config.yaml)\nGoal: Ship dark mode\n```\n\n**Per-run override:** the `--no-quality-locked` and `--no-autonomous`\nflags disable a config default for a single run:\n\n```bash\n/build --no-quality-locked \"quick typo fix\"   # override config default\n```\n\n**Precedence (highest wins):** `--no-X` flag → `--X` flag → config\ndefault → off. Passing both `--X` and `--no-X` is an error.\n\n### Interaction Patterns\n\nSage communicates clearly at every step:\n\n**Decision points** — numbered options when you need to choose a direction.\n**Checkpoints** — `[A] Approve` / `[R] Revise` shortcuts on deliverables.\n**Continuations** — `[C] Continue` with a recommended next step.\n\nFree-form input always works. These patterns guide, they don't constrain.\n\n### The Pipeline: UNDERSTAND → ENVISION → DELIVER → REFLECT\n\n<p align=\"center\">\n  <img src=\"docs/assets/sage_workflows.svg\" alt=\"Sage Workflows — 9 commands across the UNDERSTAND → ENVISION → DELIVER phases.\" width=\"600\" />\n</p>\n\nSage organizes work into four phases. Each phase has dedicated\nworkflows that chain skills automatically:\n\n```\nUNDERSTAND              ENVISION               DELIVER              REFLECT\n/research  /analyze     /design  /architect    /build  /fix         /reflect\n/learn     /map                                /autoresearch\n                                               /review  /qa\n                                               /design-review\n```\n\n`/research` chains user-interview → JTBD → opportunity-map.\n`/design` chains ux-brief → ux-specify → ux-writing and reads\nresearch findings automatically. `/build` chains spec → plan →\nbuild-loop → quality-gates and reads design specs. `/reflect`\nreviews the full cycle, extracts WHEN/CHECK/BECAUSE learnings,\nand seeds the next cycle with concrete recommendations.\n\nYou can enter at any phase. But the further right you start, the\nmore you're building on assumptions.\n\n### Enforcement Model\n\n<p align=\"center\">\n  <img src=\"docs/assets/sage_enforcement.svg\" alt=\"Sage Enforcement — 5 independent layers.\" width=\"600\" />\n</p>\n\nAgents rationalize. Tell them \"MUST write spec\" and they'll decide the\nconversation IS the spec. Every instruction that requires interpretation\nwill be reinterpreted.\n\nSage answers this with five layers — but they are **not equally strong, and the\ndifference is the whole point.** Layers 1, 2, 3 and 5 are language: they are read\nby the same model that is doing the rationalizing, and the eval found them being\nrationalized past (Layer 3's `tdd` lost to \"it's just one number\", 0/3). Layer 4\nand the spec-gate hook are **code**: a script's exit status and a blocked tool call\nare not open to interpretation, and those held in every run.\n\nRead the layers below with that split in mind. Language persuades; only mechanism\nenforces.\n\n**Layer 1 — Always-on rules** in the system prompt. Even if nothing else\nloads, the gates prevent the worst violations. Eight rules covering\nmemory-before-work, spec-first, artifact-only state, checkpoints\n(no unilateral deferral), self-check, decisions logging, learning\nfrom corrections, and skills-before-assumptions.\n\n**Layer 2 — Command preambles.** Every slash command has enforcement\nrules the agent reads before its first token. Named rationalizations\nare blocked: \"the design is clear\" → NOT a spec file.\n\n**Layer 3 — Capabilities** loaded at the right workflow step. `build-loop`\norchestrates task-by-task execution. `coding-principles` carries 7 universal\nquality standards. `tdd` argues for test-first. `systematic-debug` structures root\ncause investigation.\n\n> **These are instructions, and instructions get rationalized — the eval caught it.**\n> Asked to change one constant under pressure (\"it's literally changing one number,\n> just do it quickly\"), the agent wrote no test in **0 of 3 runs**, with `tdd` loaded\n> and the constitution's first principle reading *\"Tests before code.\"* It didn't\n> even create a cycle, so every gate Sage owns — all of which fire on a cycle — was\n> bypassed by declaring the work small.\n>\n> **So test-first stopped being a Layer-3 argument and became a Layer-4 gate.** The\n> TDD gate (PreToolUse) blocks an edit to a source file when no test has been written\n> for it. Re-measured: **3/3, against 0/3 for a bare agent.** The rest of Layer 3 is\n> still advocacy — read it as persuasion, not enforcement.\n\n**Layer 4 — Bash gate scripts.** Deterministic. Run BEFORE the agent\nreviews. `sage-verify.sh` runs your test suite, `sage-hallucination-check.sh`\nverifies imports exist, `sage-spec-check.sh` confirms deliverables match\nthe plan. The script says tests fail → gate fails, regardless of what\nthe agent thinks. Each script returns one of three states — `0` pass, `1`\nfail, `2` unverifiable — and \"unverifiable\" is never silently upgraded to a\npass: a project with no test runner stops and asks. The scripts carry their\nown regression tests (`develop/validators/gates/`), because a gate that fails\nopen is worse than no gate at all.\n\n**Layer 5 — Self-learning.** Corrections from past sessions are stored\nas WHEN/CHECK/BECAUSE rules and searched before every Standard+ task.\nThe agent reads its own past failures before repeating them.\n\nEvery rule is an **observable condition**, not an action instruction.\n\"spec.md MUST EXIST on disk\" is binary — the agent can't argue a file\ninto existence. \"MUST write spec\" is rationalizable — the agent decides\nthe conversation is the spec. File existence beats language.\n\n**On Claude Code, spec-first is mechanical, not just prose.** A `PreToolUse`\nhook (`sage-spec-gate.sh`) blocks edits to source files while a Standard+ cycle\nis still pre-spec, and blocks marking a cycle complete before its gates pass.\nThe agent cannot rationalize past a blocked tool call. It is scoped (fires only\ninside a Sage project with an active cycle), escapable (`hard_enforcement:\nfalse`, `tier: tier1`, or editing under `.sage/`), and fails open — a broken\nhook never bricks your editor. New projects default it on; projects upgraded\nwith `sage update` get it installed but **off**, with a notice, so enforcement\nnever surprises an established workflow.\n\n**Scope Guard (opt-in, unmeasured).** The same mechanical treatment now\nexists for declared scope: at plan approval, `manifest.py scope derive`\nturns the plan's per-task `Files:`/`Output:` lines into a machine `scope:`\nblock, and with `scope_gate: standard+` a PreToolUse hook blocks edits\noutside it — naming both legal exits (`scope add-collateral --task --reason`,\nwhich records the expansion itself, or amend the plan and `derive\n--refresh`). Witness/TDD tests are never scope-blocked. The same\ntransition also runs `manifest.py graph derive` — the plan's task\nstructure (`Files:` / `Depends on:` / `[P]`) becomes a fail-closed\n`task_graph:` block, the parallel-lane scheduler's only input; an\nunderivable plan cannot enter parallel mode, and the sequential build is\nuntouched. An advisory\nbackground judge (`scope_judge`) for drift *inside* in-scope files exists as\na runtime with full deterministic tests — one runtime on both Tier-A\nplatforms: claude-code delivers its corrections as hook context, opencode\nvia the attested mid-stream channel. claude-code's `auto` uses the\nplatform's canonical cheap tier; opencode has none, so there the judge's\nmodel must be explicitly designated — nothing is inferred (see\n[docs/configuration.md](docs/configuration.md)).\n\n**Both knobs are off, and the measurement says leave them there.** L3 ran a\nsix-task plan with two planted temptations and a prompt inviting cleanup, at\ntwo model tiers, N=3 each: **bare 3/3 and gated 3/3 at both tiers** — the\nagent never drifted, so the gate had nothing to prevent (zero false blocks\neither, transcript-verified). The weak-model hypothesis that carried the\nother hooks — haiku loses what frontier has free — was **falsified** for\nscope. The judge's clean-run precision failed (1 false positive in 4), and\nits detection half is unmeasured because no scenario produced real drift.\nSo Sage ships the mechanism, off, and claims nothing: full numbers in\n[develop/evals/SCOPE-GUARD-CAMPAIGN.md](develop/evals/SCOPE-GUARD-CAMPAIGN.md).\nKnown residual, witnessed in that campaign: bash-mediated writes bypass\nEdit/Write matchers, same as every path-scoped gate. Full semantics in\n[docs/configuration.md](docs/configuration.md#scope-guard-measured-and-off-by-default).\n\n#### What is mechanical on each platform\n\nNot every platform can run every layer. When one is missing, Sage degrades —\nand on Claude Code, **the record of that degradation is now taken, not requested.**\n\nThis claim used to be prose (\"a skipped review announces itself and logs to\n`decisions.md` — never silently\"), and the eval caught it being false: the line was\nwritten in **1 run out of 3**. A rule the model has to remember is a rule the model\nwill forget. So two hooks carry it instead:\n\n- The **spec-gate refuses to let a cycle reach `complete`** while its manifest's\n  `qa:` field is still `pending`. A completion that says nothing about independent\n  QA is not a thing that can happen.\n- The **degradation-log hook writes the `decisions.md` line itself**, once, the\n  moment a skip is declared. The model is not asked to log it and therefore cannot\n  fail to.\n\n**What is still not mechanical, stated plainly:** a hook cannot *detect* that the\nTask tool is missing — tool absence isn't observable from a hook payload; only the\nagent knows what it was handed. The agent still has to declare the disposition\nhonestly. What changed is that it can no longer finish the cycle without declaring\none, and that the durable record is produced by code. The conversational\nannouncement remains prose; the audit trail does not.\n\nOff Claude Code (no hooks), this is still prose — see the table below.\n\n| Layer | Claude Code | Generic / other platforms |\n|---|---|---|\n| Layers 1–3, 5 (prose rules, preambles, capabilities, self-learning) | ⚠️ prose — *rationalizable, and measurably rationalized* | ⚠️ prose |\n| Layer 4 — gate scripts (3-state, self-tested) | ✅ deterministic | ✅ deterministic (run manually) |\n| **Tests before code** (blocks a source edit until a test exists) | ✅ **mechanical (PreToolUse)** — 3/3 vs bare 0/3 | ❌ prose only — measured 0/3 |\n| Spec-gate hook (blocks pre-spec edits, blocks premature completion) | ✅ mechanical (PreToolUse) | ❌ not available — prose rules only |\n| Completion must declare what happened to QA | ✅ mechanical — the hook blocks a cycle that stays silent | ❌ prose only |\n| A degraded run is recorded in `decisions.md` | ✅ mechanical — a hook writes it; the model is not asked to | ⚠️ prose — *was written in 1 run of 3 when measured* |\n| Sub-agent reviews (auto-review, auto-QA, independent Gate 3) | ✅ via Task tool | ❌ skipped — see the two rows above for whether you'll find out |\n\nThe deterministic layers — gate scripts and the spec-gate hook — carry their\nown regression tests (`develop/validators/gates/`, `develop/validators/hooks/`)\nand run in CI on both modern bash and a real bash 3.2 container. A gate or hook\nthat fails open is worse than none at all, so they are tested to prove they\ndon't.\n\nThe agent must bypass all five layers to skip the spec. Each layer is\nindependently enforceable.\n\n### Independent Reviews (Sub-Agent)\n\n<p align=\"center\">\n  <img src=\"docs/assets/sage_quality_chain.svg\" alt=\"Sage Quality Chain.\" width=\"600\" />\n</p>\n\nSage delegates three review points to sub-agents with independent\ncontext windows. The producing agent's conversation history — where\nself-bias lives — is not included.\n\n| Review Point | When | What the Sub-Agent Checks |\n|---|---|---|\n| **Auto-review: spec** | After spec [A] | Framing alignment, testable criteria, boundary completeness, edge cases, consistency |\n| **Auto-review: plan** | After plan [A] | Spec-plan alignment, task decomposition, dependencies, coverage gaps, risk |\n| **Auto-review: ADR** | After design [A] in /architect | Trade-off analysis, migration path, risk assessment, blast radius, reversibility |\n| **Auto-review: root cause** | After diagnosis [A] in /fix | Evidence quality, symptom vs cause, alternative causes, reproduction chain |\n| **Auto-review: fix plan** | After fix plan [A] in /fix | Root cause coverage, file completeness, test strategy, regression risk |\n| **Gate 3: code quality** | During quality gates | Readability, error handling, security, performance, conventions |\n| **Auto-QA** | After gates pass | Spec-implementation alignment, test coverage, error handling, boundaries, integration, coding principles |\n\nAll are advisory — the user can always `[P] Proceed`. Findings are\nlogged to `decisions.md` for `/reflect` to learn from.\n\nRequires Claude Code's Task tool. When the Task tool is not available\n(e.g., Antigravity), each review is skipped — a review cannot be downgraded to a\nself-review, because self-review shares the author's blind spots, which is the\nwhole thing an independent pass exists to avoid.\n\nThe reasoning behind logging that skip has always been sound: **a review that\nvanishes without a trace reads as one that passed.** The implementation was not.\nAsking the model to announce and log it produced the log in **1 run out of 3** when\nit was finally measured.\n\n**On Claude Code the record is now mechanical.** The cycle manifest must declare\nwhat became of QA (`qa: skipped-no-subagent`, etc.), the spec-gate hook refuses to\nlet the cycle complete while that field is `pending`, and a PostToolUse hook writes\nthe `decisions.md` line itself. The model is not asked to log it, so it cannot\nforget. A degraded run is legible after the fact instead of indistinguishable from\na clean one.\n\nElsewhere there are no hooks, so it is still prose — read `decisions.md` yourself\nrather than waiting to be told. See [docs/eval-baseline.md](docs/eval-baseline.md)\nand the per-platform table under [Enforcement](#enforcement-model).\n\n### Coding Principles\n\nSeven universal principles loaded during implementation — not a\npost-hoc checklist, but a mindset active AS code is written:\n\n1. **Clarity over cleverness** — descriptive names, obvious flow, no tricks\n2. **Fail loudly, recover gracefully** — every external call has error handling\n3. **Guard the boundaries** — validate at every entry point\n4. **Smallest scope, shortest lifetime** — local over global, pure over stateful\n5. **Make the right thing easy** — APIs that invite correct usage\n6. **Consistency beats perfection** — match the existing codebase\n7. **Test what matters** — test behavior and boundaries, not implementation\n\nLanguage-agnostic. Apply to Python, TypeScript, Go, Rust, anything.\nStack skills add language-specific idioms on top.\n\n### Constitution Stack\n\nSage uses a three-tier constitution model:\n\n**Base** (5 principles, all projects) — TDD, no silent failures, no\nsecrets in code, explicit dependencies, reversible changes.\n\n**Preset** (chosen during init) — startup (ship small, monolith first),\nenterprise (auth everywhere, audit trails, postmortems), or opensource\n(docs mirror code, semver contract).\n\n**Project additions** — your own principles in `.sage/config.yaml`.\n\nThe generator merges all three tiers into the always-on instructions.\nLower tiers add constraints but cannot remove inherited ones.\n\n## Skills\n\n### Philosophy\n\nSkills are Sage's knowledge architecture — a principled way to put LLMs\nin the best position to do excellent work.\n\nEvery skill uses **progressive disclosure**: a short description triggers\nactivation, SKILL.md provides the full process, and reference files offer\ndepth when needed. This mirrors how experts work — you don't recite the\nentire textbook before solving a problem. You know what you know, and you\nreach for references when the situation demands it.\n\nSkills are designed to **maximize LLM capabilities**. Clear structure\n(frontmatter, process steps, quality criteria) gives the agent\nunambiguous guidance. Domain vocabulary in the right places improves\nreasoning. Reference material separated from instructions keeps the\nagent focused on the task, not on parsing a wall of text.\n\n### Built-in Skills (38)\n\nSage ships with skills across four domains:\n\n- **Product management** — JTBD, opportunity mapping, user interviews, PRDs, problem-solving\n- **UX design** — audit, evaluate, discovery, brief, specify, writing, heuristic review, research, plan-tasks\n- **Engineering** — React, React Native, Next.js, Flutter, web, mobile, API, BaaS, plus full-stack presets (Next.js + Supabase, Flutter + Firebase, React Native + Expo, Next.js fullstack)\n- **Framework** — memory, ontology, self-learning, autoresearch, skill-builder, and research packs (discover, draft, observe, source-process, validate)\n\n### Community Ecosystem (powered by skills.sh)\n\nSearch and install from 90K+ community skills:\n\n```bash\nsage find react                                         # search skills.sh\nsage add vercel-labs/agent-skills                       # browse + pick from multi-skill repo\nsage add vercel-labs/agent-skills --skill frontend-design  # install specific skill\nsage add ./my-local-skills                              # install from local path\nsage remove frontend-design                             # uninstall\n```\n\nSkills install to `sage/skills/` and auto-deploy to your platform\n(`.claude/skills/` loader stubs for Claude Code, full copies to\n`.agent/skills/` for Antigravity).\n\nContributing is deliberately simple. Drop a folder with a `SKILL.md`\ninto `sage/skills/` and it works. Add Sage frontmatter (type, tags,\nrelationships) for smarter integration.\n\n## Configuration\n\nSage configuration lives in `.sage/config.yaml`. The complete reference —\nevery key the codebase reads, its default, and which keys an agent under\nenforcement is not allowed to soften — is\n**[docs/configuration.md](docs/configuration.md)**. The short version:\n\n```yaml\nauto_review: true          # sub-agent review after spec/plan approval\nauto_qa: true              # sub-agent QA after quality gates\nindependent_gate3: true    # sub-agent code quality review (Gate 3)\nhard_enforcement: true     # the master switch for the mechanical gates\ntdd_enforcement: true      # tests-before-code, enforced at the edit\nscope_gate: off            # Scope Guard's floor — ships off until measured\nscope_judge: false         # the advisory drift judge — ships off until measured\nreview_loop:\n  mode: v2                 # the measured default; v1 restores the classic loop\nisolation: branch          # branch | worktree — how parallel work is isolated\n```\n\nFour families of settings, at a glance:\n\n| Family | Keys | Guide section |\n|---|---|---|\n| Quality chain | `auto_review`, `auto_qa`, `independent_gate3` | [The quality chain](docs/configuration.md#the-quality-chain) |\n| Enforcement | `hard_enforcement`, `tdd_enforcement`, `secrets_gate`, `verify_gate`, `bookkeeping_gate`, the Scope Guard keys | [Enforcement](docs/configuration.md#enforcement--the-master-switch-and-the-gates) |\n| Review loop v2 | the `review_loop:` block | [The review loop](docs/configuration.md#the-review-loop-v2--the-measured-default) |\n| Sessions | flag defaults, resume economy, `isolation`, worktree seed/harvest | [Execution-flag defaults](docs/configuration.md#execution-flag-defaults) |\n\n## Multi-Agent (optional)\n\nFor non-trivial work where independent review changes your mind, Sage\noffers an **opt-in cross-model build cycle**. The host (Claude Code,\nOpus) keeps the planner role and orchestrates; external CLIs handle\nadversarial review and implementation:\n\n```\nbrief → spec → external spec review (loop) → plan → external plan review\n      → external implement → external code review (loop) → reflect\n```\n\nDefaults: Codex CLI (`gpt-5.5`) reviews specs/plans and code; Kimi\nCLI implements. All bindings live in a single config file you can edit:\n\n```toml\n# .sage/agents.toml — swap any role's tool with a one-line change\n[roles.code_reviewer]\nagent = \"codex\"\nmodel = \"gpt-5.5\"\nmode  = \"read-only\"\n```\n\nInstall per project (Python 3.11+, plus whatever CLIs you bind):\n\n```bash\ncd my-project\nsage setup multi-agent          # adds /build-x, /review-spec, /review-plan,\n                                # /implement, /review-code — never shadows /build\nsage setup multi-agent --remove # clean uninstall, user edits backed up\n```\n\nThe augmented cycle re-uses Sage's existing `/architect`, `/research`,\nand `/design` workflows where they fit, then layers external review +\nexternal implementation on top. Survives `sage update` — your\n`.sage/agents.toml` and `.sage/prompts/` are never touched; framework-\nowned scripts and command files refresh from the template with drift\ndetection (`[K]eep | [R]eplace | [D]iff` if you've edited locally).\n\nClaude Code only in v1.\n\n**Learn more:**\n- **[docs/multi-agent.md](docs/multi-agent.md)** — comprehensive user\n  guide (install, configure, daily use, customize, troubleshoot)\n- [runtime/multi-agent/README.md](runtime/multi-agent/README.md) —\n  contributor-facing (template layout, ownership split, how to test)\n- `.sage/docs/multi-agent.md` (post-install) — protocol contract,\n  schema, integration points\n\n## Parallel Sessions (optional)\n\nEvery delivery workflow works on its own branch (`feat/<slug>`,\n`fix/<slug>`, `arch/<slug>`) and merges only when you choose `[M]` at\nthe completion checkpoint — never on its own. That gives you clean,\nreviewable, one-PR-per-initiative history out of the box, with no new\nsteps for a single sequential session.\n\nTo run **two tasks at once** — one session fixing a bug, another\nbuilding a feature — branches alone aren't enough: two `claude`\nsessions in the same directory share one working tree and clobber each\nother's files. The isolation that simultaneous sessions need is a\n`git worktree` — a directory per session. One command sets it up:\n\n```bash\nsage worktree payment-retry          # creates ../<repo>-payment-retry on\n                                     # branch feat/payment-retry, copies the\n                                     # runtime, prints: cd … && claude\ncd ../<repo>-payment-retry && claude  # an isolated session; /build works as normal\n```\n\nOpt in with `isolation: worktree` in `.sage/config.yaml` to make the\nworkflows offer this automatically. If you forget and open a second\nsession in the same checkout, Sage warns you (it can't silently move a\nrunning session into a worktree — that's a launch-time action).\n\n**Learn more:** **[docs/parallel-sessions.md](docs/parallel-sessions.md)**\n— when to use a branch vs a worktree, the full `sage worktree`\nreference, the collision guard, and the tracked-vs-gitignored `.sage/`\ndetails.\n\n## Project State\n\nWhen Sage runs in your project, it manages state in `.sage/`:\n\n```\n.sage/\n├── config.yaml              # Project config — preset, stack, toggles\n├── decisions.md             # Append-only decision log (never edited, never summarized)\n├── conventions.md           # Project conventions (enriched by codebase-scan)\n├── docs/                    # Project knowledge (analyses, ADRs, research)\n│   ├── decision-*.md        # Architecture Decision Records\n│   ├── ux-audit-*.md        # UX audit findings\n│   ├── jtbd-*.md            # Jobs-to-be-Done analysis\n│   └── reflect-*.md         # Cycle reflections with learnings\n├── work/                    # Per-initiative deliverables\n│   └── YYYYMMDD-slug/\n│       ├── brief.md         # Scope definition (medium+ tasks)\n│       ├── spec.md          # Feature specification\n│       ├── plan.md          # Implementation plan with tasks\n│       ├── manifest.md      # Cycle state + handoff context\n│       ├── qa-report.md     # QA test results (from /qa)\n│       └── design-review.md # Design audit findings (from /design-review)\n└── gates/\n    ├── gate-modes.yaml      # Which gates run per workflow mode\n    └── scripts/             # Deterministic verification scripts\n```\n\n**Artifact-only state.** There is no progress.md or state file that the\nagent summarizes. The artifacts ARE the state: spec.md exists = spec\nphase complete. plan.md exists = planning done. File existence is\nbinary — the agent can't hallucinate a file into existence.\n\n**decisions.md is newest-first.** The agent prepends entries after the\nheader — recent context is always read first. When the file exceeds\n~200 lines, old entries archive to `decisions-{date}.md`.\n\n## Platforms\n\nSage generates process files for many agents, but not every platform can run\nevery layer. Two tiers:\n\n**First-class** — full quality chain (sub-agent reviews + the mechanical\nspec-gate hook) and end-to-end CI:\n\n<!-- BEGIN GENERATED: platform-truth-table -->\n\n<!-- Generated by runtime/tools/gen_truth_table.py from the platform\n     capability contracts. Do not hand-edit: `gen_truth_table.py --check`\n     fails CI when this block and the contracts disagree. -->\n\n| Platform | Tier | Veto | Post-tool | Subagents | Skills | Commands | Conformance |\n|---|:--:|:--:|:--:|:--:|:--:|:--:|---|\n| claude-code | **A** | 📝 | ✅ | ✅ | 📝 | ✅ | [2026-07-12](develop/conformance/reports/claude-code-2026-07-12.md) |\n| generic | **C** | — | — | — | — | — | [2026-07-12](develop/conformance/reports/generic-2026-07-12.md) |\n| antigravity *(community)* | **C** | — | — | — | — | ✅ | [2026-07-12](develop/conformance/reports/antigravity-2026-07-12.md) |\n| codex *(community)* | **C** | — | — | — | — | ✅ | [2026-07-12](develop/conformance/reports/codex-2026-07-12.md) |\n| gemini-cli *(community)* | **C** | — | — | — | — | ✅ | [2026-07-12](develop/conformance/reports/gemini-cli-2026-07-12.md) |\n| hermes *(community)* | **A** | 📝 | 📝 | 📝 | 📝 | 📝 | [2026-08-05](develop/conformance/reports/hermes-2026-08-05.md) |\n| opencode *(community)* | **A** | 📝 | 📝 | 📝 | — | ✅ | [2026-07-12](develop/conformance/reports/opencode-2026-07-12.md) |\n\n✅ checked · 📝 attested (evidence + expiry) · — not available\n\n**Tier is derived, not declared** — `A` = veto ∧ post-tool ∧ subagents;\n`B` = veto ∧ context-injection; `C` = context-injection only.\n\n**`Veto` is the column that matters.** It is the answer to \"can a hook\nBLOCK an edit before it happens?\" Everything else is a convenience.\nWhere it is `—`, Sage's rules are prose — and the v1.2.1 eval measured a\nframework whose rules were prose and found a behavioural delta of **zero**.\nThat is what Tier C means, stated in the only terms that are honest.\n\nContracts: [`runtime/platforms/CONTRACT.md`](runtime/platforms/CONTRACT.md) ·\nPorting: [`docs/porting-sage.md`](docs/porting-sage.md)\n\n<!-- END GENERATED: platform-truth-table -->\n\nThe old table here was hand-written. It said \"Full — Task tool + spec-gate hook\"\nfor Claude Code and offered a paragraph of prose for everyone else, and it linked\nto `generate-plugin.sh` — a script that has been dead and broken for releases.\n\nA hand-maintained table of *enforcement* claims is the pre-1.2.0 mistake in its\npurest form: a claim, with no mechanism, in the most-read file in the repo. It is\ngenerated now, from contracts that are checked and conformance runs that are\ndated. Hand-editing it fails CI.\n\nDistribution paths from one source:\n\n```\nSage Framework (source of truth)\n    ├── generate-claude-code.sh   → CLAUDE.md + .claude/\n    ├── generate-antigravity.sh   → GEMINI.md + .agent/\n    ├── generate-codex.sh         → AGENTS.md + .codex/agents/\n    ├── generate-opencode.sh      → AGENTS.md + .opencode/{commands,agents}/\n    ├── generate-gemini-cli.sh    → GEMINI.md + .gemini/commands/\n    └── generate-plugin.sh        → sage-plugin/ (Claude Code plugin)\n```\n\nAll in-project paths share the same `.sage/` project state. Multiple\nplatforms can be installed simultaneously — Sage detects them and\ngenerates files for each. AGENTS.md is shared between Codex and\nOpencode; GEMINI.md is shared between Antigravity and Gemini CLI.\n\n### Installing for a specific platform\n\n```bash\nsage init                              # detect existing platforms; ask if none\nsage init --platform codex             # explicit: just Codex\nsage init --platform codex,opencode    # multiple\nsage init --platform all               # all 5 platforms\nsage update                            # regenerate using the persisted list\nsage update --platform gemini-cli      # override on update\n```\n\nThe selected platforms persist in `.sage/config.yaml` under\n`platforms:`. `sage update` reads this list and regenerates for each.\n\n## Why sage/ Lives in Your Project\n\nSage copies its framework source into each project. This is intentional:\n\n- **Self-contained.** No external dependencies. Works offline.\n- **Version-locked.** Your project uses the exact version you installed.\n  No surprise updates. Upgrade when you're ready.\n- **Inspectable.** Read any skill, workflow, or capability. No magic.\n  If something isn't working, you can see exactly what it's doing.\n- **Portable.** Clone the repo and everything is there. No global\n  installs, no PATH configuration, no package managers.\n\nIf you prefer managed installs, the Claude Code plugin offers the\nsame functionality without in-project files.\n\n## License\n\nMIT\n",
  "bytes": 52187,
  "sha": "e492035f13e9ad600b4b4f37afb29906dd1dce6e7e290f67455e1497b82bbbf4",
  "repo_slug": "xoai/sage",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_xoai_sage_sage_7b881aad/readme"
}