What, not how.

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.

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

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

1. Run triage first - in Claude Code via the native Skill tool as praxis:triage.
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.

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

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

Your project must maintain:

• README.md — Project overview, what it is, who it's for, how to use it. Links to technical spec.
• docs/tech-spec.md — Main technical specification (declarations only, no narrative).
• docs/specs/*.md — Split-out details when the main spec grows too large.

Technical specs are facts only: contracts, data shapes, invariants, failure modes. No interpretation, no plans.

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).

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.

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

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.

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

See .opencode/INSTALL.md.

copilot plugin install ouonet/praxis

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

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

For harnesses without plugin support, add an instruction that reads bootstrap.md first.

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

Expected: Claude Code invokes Skill(praxis:triage), then outputs praxis: scope=standard, loading=design,plan,tdd,review 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.

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

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

Design asks only needed questions, plan writes milestone tasks, ship updates living specs and CHANGELOG Unreleased.

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.

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.

You: release 1.2.0
Agent: triage -> release

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

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

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.

• 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.

bootstrap.md           # manual / fallback entrypoint
skills/<name>/SKILL.md # skills (Claude Code native + file-read harnesses)
hooks/
  hooks.json           # hook registry
  run-hook.cmd         # Windows hook runner
  session-start        # session-start hook script
.claude/               # Claude Code settings
.claude-plugin/        # Claude Code plugin manifest
.codex-plugin/         # Codex plugin manifest
.copilot-plugin/       # Copilot CLI plugin manifest
.opencode/             # OpenCode config + install doc

MIT.