praxis

<p align="center"> <a href="https://ouonet.github.io/praxis/" target="_blank"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ouonet/praxis/main/assets/logo-dark.svg"/> <img src="https://raw.githubusercontent.com/ouonet/praxis/main/assets/logo.svg" alt="Praxis" width="260"/> </picture> </a> </p>

<p align="center"> <a href="https://ouonet.github.io/praxis/" target="_blank" style="text-decoration: none;"> <strong>What, not how.</strong> </a> </p>

---

Praxis is a discipline framework for AI coding agents. Tell your agent what you need and what done looks like—not how to do it. As AI gets smarter, this gap widens: the agent can apply domain expertise, handle edge cases, and adapt faster than step-by-step instructions allow.

Inspired by Superpowers, rewritten to be significantly cheaper while keeping the core capabilities.

📖 Full documentation

> 💡 Looking for the single-module version (v2.4.0)? If you prefer the legacy single-module setup of Praxis without multi-module topology or spec review gates, checkout or install from the single-module branch.

Quick Start

Claude Code

claude plugins marketplace add ouonet/praxis 
claude plugins install praxis@praxis
claude 'do a todo list app'

pi CLI

pi install git:github.com/ouonet/praxis
pi 'do a todo list app'

How it works

At session start, a hook injects the praxis:using-praxis startup skill. It tells your agent:

1. Classify scope inline using the triage table embedded in using-praxis — no Skill call needed. 2. Load only the skills that scope needs. Trivial tasks skip the waterfall entirely. 3. Follow the loaded skill literally; don't freelance past <gate> markers.

Multi-module is a topology, declared alongside scope: when one change spans multiple modules or repositories, the agent adds topology=multi-module to the announcement and every loaded skill follows the multi-module protocol. See Multi-module work below.

Skills

| Skill | When | | --------- | ------------------------------------------- | | onboard | existing project with no docs/tech-spec.md | | design | scope ≥ standard, anything new; also handles vague goals — clarifies before designing. After spec, dispatches focused reviewers (trigger-based, parallel) | | plan | after design | | tdd | implementing or fixing | | debug | something broken | | review | before merge / after subagent task | | worktree | non-trivial or parallel work | | subagents | independent tasks, fan-out. Each dispatch gets a ROLE charter, optional MODEL tier | | ship | merge / PR / cleanup | | release | version / tag / publish |

Skills range from ~100 to ~400 tokens each. Compare to Superpowers' 2,500–3,500 per skill.

Token budget

| | Superpowers | Praxis | | ---------------------------- | ------------- | ----------------------------- | | Bootstrap (every session) | ~2,200 | ~450 (using-praxis + inline triage) | | Per skill load | ~2,500–3,500 | ~100–400 | | Trivial task | ~11,000 | ~450 (bootstrap only) | | Standard task (design→ship) | ~30–50k | ~1,300 (bootstrap + 4 skills) | | Complex task (all skills) | ~40–60k | ~2,900 (all skills combined) |

Model tiers

When dispatching subagents (subagents skill) or design reviewers (design review gate), Praxis uses three capability tiers instead of hardcoded model IDs:

| Tier | Use when | Examples | |------|----------|----------| | fast | Mechanical edits, simple checks | rename a constant, pattern-match review | | balanced | Standard implementation, single-file work | add a function, write routine tests | | strongest | Complex reasoning, safety review | implement a protocol, review crash-recovery |

Resolution: .praxis/model-tiers.yaml in project root or user home maps each tier to a concrete model ID. No config file → all subagents use the harness default. Template: model-tiers.example.yaml.

Multi-module work

> Availability: Multi-module topology is fully supported in Praxis v4.0+.

When one change spans multiple modules or repositories, Praxis runs in multi-module topology. The agent declares it at triage and carries it on every turn:

praxis: scope=complex, topology=multi-module, loading=design,plan,worktree,subagents,review,ship

(topology=multi-module is omitted on ordinary single-module turns.)

Coordinator. You designate one existing repository as the coordinator - the agent won't infer this. It owns the cross-module spec/plan and the change manifest.

Mode marker. The coordinator spec (created at design) and workspace plan (created at plan) each open with a declaration block. This on-disk declaration is what keeps the agent in multi-module mode across a long change - it reads the declaration to re-establish mode instead of relying on session memory:

topology: multi-module
change-set: <topic-id>
coordinator: <repo path>
repos: <repo paths>

The workspace plan adds module plan paths and the integration task. Each module also gets its own spec and plan in its owning repository, referencing shared contracts defined once in the coordinator - never duplicated.

Lifecycle. design (coordinator + per-module specs) → plan (workspace + per-module plans) → tdd/subagents per module → integrate against the coordinator's acceptance → commit in dependency order, coordinator last, recording each SHA as the revision set.

Safety. Each repo is inspected before editing - a missing repo, red baseline, or unrelated dirty change blocks the change. Praxis never auto-clones, resets, rebases, or discards. Put the change-set ID in branch names and commit subjects, e.g. [praxis:checkout-v2]. Cross-repo commits aren't atomic; the recorded revision set is the reproducibility boundary.

Full protocol: skills/references/multi-module.md (experimental).

Documentation Structure

Praxis enforces a strict documentation structure and keeps code and docs in sync at every step.

Living Documentation

Living documentation — describes the current system state and direction. Always in sync with code.

• README.md — for users: what it is, who for, how to use it
• docs/tech-spec.md — for developers/agents: current system state (format)
• *docs/specs/.md** — details split out of the tech-spec when it grows too bulky; referenced by path
• docs/ROADMAP.md — direction and milestones (exists when project has ≥3 milestones or long-term direction)

docs/tech-spec.md uses a structured declaration format:

purpose / user / use-case / architecture / stack / entry /
contract / flow / invariant / constraint / convention / milestone

Facts only — no interpretation, no plans. If details are bulky — e.g. a complex flow (branching, async, multi-actor) that needs a diagram — split into docs/specs/ and link; the spec keeps a one-line summary.

Project artifacts — records and conventions. Append-only or static.

• CHANGELOG.md — version history, maintained by ship
• docs/decisions/ — architectural decision log, append-only

Staging Area

During active work, Praxis uses:

• docs/staging/specs/YYYY-MM-DD-<topic>.md — Working spec for the current change.
• docs/staging/plans/YYYY-MM-DD-<topic>.md — Executable milestone tasks.

At ship, the staging spec merges into living docs; staging files are deleted (Git keeps history).

Code-Docs Sync

Praxis enforces synchronization at multiple checkpoints:

• During tdd: After each RED-GREEN-refactor cycle, sync docs before commit.
• If staging spec exists → update it to match reality.
• If no staging spec (small tasks) → update living docs directly.
• At ship gate: Staging spec must reflect actual code behavior.
• At review: Check that README/comments reflect actual behavior.

Quality and doc-coverage are verified: tdd runs lint/format/typecheck + checks against convention; review/ship verify contract covers the full surface, env/errors documented, README commands runnable. See skills/references/quality.md.

The rule: Code changes without doc updates fail review. Docs that don't match code block merge.

Install

Install from a branch

To pin or test a specific git branch or tag, append #<branch> (or --ref <branch>) to the install source URL as supported by your agent harness.

> Single-module (v2.4.0 legacy): Append #single-module or @single-module to install from the legacy single-module branch (e.g. pi install git:github.com/ouonet/praxis@single-module).

---

Claude Code

claude plugins marketplace add ouonet/praxis
claude plugins install praxis

To update after new releases:

claude plugins update praxis

> Claude Code does not auto-update plugins. Run the update command manually after repo changes.

Codex (CLI / app)

Praxis is distributed as a Codex marketplace. Register the marketplace from the CLI:

codex plugin marketplace add ouonet/praxis

Then open the plugin directory and install it from the Codex UI:

/plugins

Search for praxis and select Install Plugin.

If the marketplace was already added before an update, refresh it first:

codex plugin marketplace upgrade praxis-marketplace

OpenCode

See .opencode/INSTALL.md.

GitHub Copilot CLI

copilot plugin install ouonet/praxis

(Or symlink .copilot-plugin/plugin.json per Copilot's plugin convention.)

VsCode Copilot

open customization of copilot -> Plugins -> Install Plugin From Source -> input  "ouonet/praxis"

Antigravity CLI

agy plugin install https://github.com/ouonet/praxis

Antigravity imports Praxis through the Gemini-compatible plugin path, including the session-start hook.

Gemini CLI

gemini extensions install https://github.com/ouonet/praxis

The extension loads skills/using-praxis/SKILL.md as session context, so triage runs from the first turn.

pi CLI

pi install git:github.com/ouonet/praxis

Praxis is distributed as a native pi package — pi auto-discovers skills from the package.json manifest. The using-praxis bootstrap is injected at session start automatically.

> Specific branch/tag: append @<branch> to install from a specific branch or tag (e.g. pi install git:github.com/ouonet/praxis@single-module).

Install to project scope (.pi/settings.json, shared with team):

pi install -l git:github.com/ouonet/praxis

Update:

pi update git:github.com/ouonet/praxis      # update one package
pi update --extensions                       # update all packages
pi update --all                              # update pi + packages

Uninstall:

pi remove git:github.com/ouonet/praxis

Qoder CLI CN

Qoder CLI CN auto-discovers skills from the project's skills/ directory — no hooks or manual loading needed.

Clone this repo and symlink (or copy) the skills/ directory into your project:

git clone https://github.com/ouonet/praxis.git ~/.qoder-cn/praxis
ln -s ~/.qoder-cn/praxis/skills ./skills

Or install as an SDK plugin by pointing to the .qoder-plugin/ manifest in your project config.

The using-praxis skill is auto-discovered and triggered at session start by its description.

Manual / fallback

For harnesses without plugin support, add an instruction that reads skills/using-praxis/SKILL.md first.

Verify it's working

Start a fresh session. Send: let's build a react todo list.

Expected: outputs praxis: scope=standard, loading=design,plan,tdd,review (no Skill(praxis:triage) call — triage is inline) and starts asking clarifying questions before touching code.

Send: fix the typo "teh" in README.

Expected: agent outputs praxis: scope=trivial, loading= and just fixes it. No design doc, no plan, no TDD ceremony.

Examples

Vague goal

You: I want to build something that helps developers manage their workflow
Agent: triage → vague → design

Design asks one clarifying question per turn until the problem is concrete enough to spec. If exploration produces a knowledge artifact (protocol spec, RE findings), it goes to docs/decisions/ via archive.

Tiny fix

You: fix the typo "teh" in README
Agent: triage → trivial → edit → done

Standard feature

You: add OAuth login with GitHub
Agent: triage → design → plan → tdd → review → ship

Design investigates facts and asks only the current decision frontier in dependency order; plan writes milestone tasks; ship updates living specs and CHANGELOG Unreleased.

Parallel work

You: migrate the entire API from REST to tRPC
Agent: triage → design → plan → worktree → subagents → review → ship

Subagents expand milestones at dispatch time; the coordinator reviews and marks tasks complete.

Multi-module change

You: add a shared checkout flow across the api and web repos
Agent: triage → topology=multi-module → design (asks you to designate coordinator) → plan → tdd/subagents per module → integrate → ship

You designate one existing repo as coordinator; it holds the shared contract and integration check. Each module keeps its own spec/plan in its owning repo. At ship, non-coordinator repos commit in dependency order and the coordinator commits last, all sharing the change-set ID; their SHAs form the revision set.

Onboard existing project

You: take over this project / add Praxis to this codebase
Agent: triage → onboard

Onboard explores the codebase and produces docs/tech-spec.md — a factual record of stack, contracts, conventions, and invariants. No code changes, no plans. After confirmation, the normal design → plan → tdd flow resumes.

Release

You: release 1.2.0
Agent: triage → release

Release confirms the version, moves CHANGELOG Unreleased, then asks before commit, tag, push, or publish.

Common Signals

| You ask | Praxis does | | ---------------------- | ---------------------------------- | | I want to build X (vague) | vague → design (clarifies first) | | fix typo | trivial | | add small field | small → tdd | | add feature | standard → design/plan/tdd/review | | migrate module | complex → worktree/subagents | | change spans repos/modules | topology=multi-module (coordinator) | | failing behavior | debug | | take over this project | onboard | | release 1.2.0 | release |

Compared to Superpowers

Praxis is directly inspired by Superpowers. The core idea is the same: inject structured discipline into an agent session via skill files.

| Superpowers skill | Praxis equivalent | | ----------------------------------------------------------------- | ------------------------------------------ | | using-superpowers | using-praxis (triage inline) | | brainstorming | design | | writing-plans | plan | | executing-plans | tdd | | test-driven-development | tdd | | systematic-debugging | debug | | requesting-code-review / receiving-code-review | review | | using-git-worktrees | worktree | | dispatching-parallel-agents / subagent-driven-development | subagents | | finishing-a-development-branch | ship | | verification-before-completion | gate markers in tdd / ship | | writing-skills | — (not needed; skills are plain Markdown) | | — | onboard (no Superpowers equivalent) | | — | archive (no Superpowers equivalent) | | — | release (no Superpowers equivalent) |

Philosophy difference: Superpowers gives agents detailed recipes—prose specs, step-by-step plans, narrative reasoning. Praxis gives agents declarations of intent—decisions, contracts, validation gates. This works because:

• Agents get smarter; recipes become obsolete. Declarations stay relevant.
• Leaner artifacts = faster iteration and long-term maintainability.
• The agent brings domain knowledge; Praxis provides what matters, not how to do it.

Token savings: The skill files are smaller (avg ~230 vs ~1,760 tokens), and artifacts are too. Praxis design outputs a spec (decisions, contracts, invariants) with no narrative; plan outputs milestone stubs with one-line goals. At ship, working notes are archived and the spec merges into living docs—context stays lean across sessions.

When to use Superpowers: You want battle-tested, narrative-rich workflows and token cost isn't a constraint.

When to use Praxis: You want agents to think, not follow recipes. You want specs and plans that survive across sessions and scale with AI capability.

Philosophy

• Intent, not instruction. Tell the agent what to achieve and what done looks like. Let it decide how to do it.
• Pay for discipline only when it pays back. Triage decides.
• Skills are short. If a rule needs 3,000 tokens to express, it's probably not a rule, it's a manual.
• Cross-harness via env detection, not per-harness skill copies.
• No ceremony around the rules — state each rule once, clearly.

Layout

skills/<name>/SKILL.md # skills (using-praxis is the entrypoint; manual/fallback reads it directly)
skills/references/     # shared protocols (multi-module, quality, reviewers)
model-tiers.example.yaml # template for .praxis/model-tiers.yaml
hooks/
  hooks.json           # hook registry
  run-hook.cmd         # Windows hook runner
  session-start        # session-start hook script
package.json           # npm package + pi package manifest (pi auto-discovers skills)
.claude/               # Claude Code settings
.claude-plugin/        # Claude Code plugin manifest
.codex-plugin/         # Codex plugin manifest
.copilot-plugin/       # Copilot CLI plugin manifest
.qoder-plugin/         # Qoder CLI CN plugin manifest
.opencode/             # OpenCode config + install doc
gemini-extension.json  # Gemini CLI extension manifest

License

MIT.