sage

Drives task-by-task execution from an approved plan with quality gates between each task. Reads the plan, finds the next incomplete task, dispatches implementation, validates, updates progress, and continues. Use after a plan is approved and the user says "go", "start building", "execute the plan", or "implement the feature".

Enforces test-driven development: write failing test, write minimal code to pass, refactor. Mandatory for all implementation work. Use when writing any production code, implementing features, fixing bugs, refactoring, or when the user says "write code", "implement", "fix this", or "add a feature". Code written before its test is deleted.

Configure Sage preset and project settings. Switch between base, startup, enterprise, or opensource constitution presets. Use when the user says "configure sage", "change preset", or "sage settings".

Preserves and restores context across agent sessions using plan file checkboxes as source of truth. Use when starting a new session, resuming previous work, ending a session, or when the user says "continue from last time", "what was I doing", or "save progress".

Architecture Decision Records, System spec, Milestone plan

Brief (medium+ tasks), Spec, Implementation plan

Session resumption with context

Root cause diagnosis with evidence, Reproducing test, Minimal patch

Parses workflow flags (--quality-locked, --autonomous, --subagents) from $ARGUMENTS at the start of /build and /architect commands. Uses a deterministic python3 runtime with a prose-rule fallback if python3 is unavailable. Returns a strict JSON contract that the agent trusts unconditionally.

Presenting work for approval and formatting the response footer. Use when reaching an approval gate, showing a spec, plan, brief, or finished deliverable, offering the user choices, or when unsure which zone footer a response should end with.

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.

Recording decisions in the right log. Use when a decision needs to be written down, when the user asks why something was decided, when writing an ADR or a decision entry, or when unsure whether something belongs in the initiative's log or the global one.

Sage's quality gates and the file checks each workflow must pass. Use when an edit was blocked, when asking why a hook stopped you, when a gate fails or reports UNVERIFIABLE, before claiming work is done, or when you need the spec/plan preconditions for build, fix, or architect.

Choosing which Sage workflow fits a request. Use when the user asks what to run, which command or workflow to use, where to start, or when a request is ambiguous or spans multiple surfaces and needs to be routed to build, fix, architect, review, learn, reflect, or continue.

Sizing a task before doing it. Use when the user asks which tier a task is, how big or small a change is, whether something needs a spec or a plan, whether to just do it or slow down, or when deciding how much process a piece of work deserves.

Sage's persistent memory. Use when the user says remember this, store this, don't forget, note for next time, what do we know about X, have we seen this before — and whenever the user corrects you, an approach fails repeatedly, or you discover a non-obvious gotcha worth keeping.

Use after implementation passes the quality gates, when a change needs an independent pass over the code before it ships, or when the user asks to "QA this", "check the implementation", or "verify it matches the spec". Applies to Standard and Comprehensive scopes with the Task tool available; Lightweight tasks skip.

Start here. Sage reads project state, routes via keywords, classifies intent, and guides you to the right workflow.

Activates when the user starts any substantial task: building, creating, redesigning, analyzing, researching, planning, fixing, improving, evaluating, writing, auditing — code, products, content, or strategy. Also activates when the user asks what to do next, says "continue," seems uncertain where to start, or begins a new session. This is Sage's intelligent process navigator.

Autonomous iteration toward a measurable outcome. Use when the user wants to optimize a numeric metric through repeated modify-verify cycles — reduce bundle size, increase test coverage, improve query time, lower readability score. Not for exploratory research, subjective judgment, or tasks without a verification command.

First-run project setup that detects tech stack, selects quality packs, and generates .sage/ directory with CLAUDE.md. For new projects, guides technology selection. Use when no .sage/ directory exists, when the user says "set up sage", "initialize", "get started", or when starting a brand new project from scratch.

"Corrects the most common BaaS architecture mistakes agents make — security rules as authorization, data modeling for queries, minimizing serverless functions, real-time by default, and client-direct access patterns. Applies to Firebase, Supabase, and similar platforms."

Flutter patterns — widget architecture, state management, Impeller renderer, platform-adaptive design

Next.js 14/15 App Router patterns — server components, data fetching, caching, server actions

React Native patterns — New Architecture (Fabric/TurboModules), Expo, navigation, performance

When --quality-locked is active, loop review/revise at each Quality Gate until findings reach a clean bar (no Critical, no Major, only cosmetic Minor) or the iteration cap (10) is reached. Uses a deterministic Python checker for classification and decision logic; agent runs the actual review and revision steps.

Knowledge entries in sage-memory, Docs in .sage/docs/

Cycle review, Learnings with prevention rules, Next-cycle seeds

Independent artifact review via sub-agent delegation. Evaluates completeness, consistency, and quality with severity classification.

Integrates sage-memory into Sage workflows. Teaches the agent when to remember (store findings during work), when to recall (search memory at session start and task start), and how to learn (structured knowledge capture via sage learn). Use when the user mentions memory, remember, recall, learn, capture knowledge, onboard to codebase, or when starting any session where sage-memory MCP tools are available.

Use when the user picks [A] Review at a spec/plan/ADR/root-cause/fix-plan checkpoint, or asks for an independent review before implementation begins. Applies to Standard and Comprehensive scopes with the Task tool available; Lightweight tasks skip.

Use as the code-quality gate after spec-compliance and constitution checks pass, or when the user says "review my code", "quality check", "security review", or "is this code good". Runs as an independent sub-agent when the Task tool is available.

Branch-per-initiative git discipline for all delivery workflows. Defines branch naming by workflow, the propose-confirm creation protocol, dirty-tree and detached-HEAD handling, the always user-gated merge protocol, worktree support for parallel sessions, and abandonment cleanup. Activates only in git repositories — silently inactive everywhere else. Use when starting /build, /fix, /architect, or /build-x at Standard+ scope, when resuming an initiative, when offering a merge at a completion checkpoint, or when the user wants a second concurrent initiative.

Integrates sage-memory into Sage workflows. Teaches the agent when to remember (store findings during work), when to recall (search memory at session start and task start), and how to learn (structured knowledge capture via sage learn). Use when the user mentions memory, remember, recall, learn, capture knowledge, onboard to codebase, or when starting any session where sage-memory MCP tools are available.

Creates implementation plans from specifications by breaking work into small tasks (2-5 min each) with exact file paths, tests, and dependency ordering. Use after a spec is approved and before implementation begins, or when the user says "create a plan", "break this down", "how should we build this", or "task breakdown".

Use during implementation — loaded by build-loop before each task — whenever code is being written and should hold to universal quality standards, regardless of language or stack. Active while writing, not a post-hoc review checklist.

When --autonomous is active, skip user-facing elicitation rounds. The agent makes elicitation decisions from memory, codebase patterns, constitution principles, and prior cycle context. Every decision cites its source. Substantive decisions with no signal fall back to asking the user.

Use when authoring or editing a skill that enforces a rule an agent could rationalize past — a discipline skill — or when a shipped discipline skill is being skipped, ignored, or only partially followed. Also use when reviewing a discipline skill before release.

Fixture discipline skill that is MISSING its compliance_marker. The harness must exit 2 (setup error) when asked to run this.

Fixture discipline skill with a marker but NO sibling TESTS.md. The harness must exit 2 (setup error) because there is no scenario to dispatch.