praxis

PRAXIS - A reasoning methodology plugin for AI coding agents.

Praxis makes your agent think before it acts — classifying problems, selecting the right reasoning frameworks for the problem type, enforcing cognitive checklists, and validating solutions before execution.

Praxis tells agents how to think — the approach, not just the answer. It reasons deeply before anything gets built, so the agent commits to a direction only after the problem is framed and the design is validated.

What it actually does

Without Praxis, you say "design an auth system" and your agent starts asking generic questions or writing code immediately.

With Praxis:

You: Help me design an authentication system for our API

Agent: Skill(praxis) — Successfully loaded skill

GATE 1 — Problem type: EXTEND (adding auth to existing API).
GATE 2 — Constraints needed before designing:
  1. Clients: First-party web? Mobile? Third-party devs? Server-to-server?
  2. Session shape: Long-lived browser sessions? Short-lived API calls?
  3. Compliance: HIPAA, PCI, SOC2?
  4. Build vs buy: Open to Auth0/Clerk, or self-hosted?
GATE 3 — Frameworks: Separation of Concerns + Backward Compatibility + STRIDE
GATE 4 — The real problem isn't "pick JWT vs sessions" — it's matching auth
  architecture to your client mix, trust boundaries, and operational capacity.

Confidence: INSUFFICIENT (<50%) — cannot recommend without constraint envelope.

The agent classified the problem, selected reasoning frameworks, asked constraint-specific questions instead of generic ones, reframed the real problem, and reported calibrated confidence — all before writing a single line of code. Another example below:

Test results

Built through iterations of testing and tuning. Every critical test passes.

The 18 skills

Each skill is a behavioral protocol with mandatory gates — not a reference document to browse.

Installation

Claude Code (plugin — recommended)

/plugin marketplace add xD4O/praxis
/plugin install praxis@praxis

Restart Claude Code. The router is injected at session start automatically.

Claude Code (manual)

Skills must be copied flat — Claude Code discovers ~/.claude/skills/<name>/SKILL.md, not nested directories:

git clone https://github.com/xD4O/praxis
cp -r praxis/skills/* ~/.claude/skills/

Optionally register the session-start hook (plugin installs get this automatically) by adding to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          { "type": "command", "command": "/absolute/path/to/praxis/hooks/session-start" }
        ]
      }
    ]
  }
}

Other agents and harnesses

Praxis skills follow the open Agent Skills format (SKILL.md), supported by Codex, Cursor, VS Code Copilot, Gemini CLI, and others — point your harness's skills directory at skills/. For harnesses without skill support, add the body of skills/using-praxis/SKILL.md to your AGENTS.md or system prompt as the router.

Verify

Ask for something non-trivial:

Help me design a notification service

Praxis should activate problem-classification before any work begins. If it doesn't, ask: "What skills do you have access to?" to verify the plugin loaded.

Slash commands

The router fires protocols automatically. These commands let you invoke one on demand — to force a protocol the router skipped, or to run a specific check against existing work. They are user-triggered only (the model won't auto-invoke them).

How it works

A slim router (~100 lines) is injected at session start via a SessionStart hook. It establishes a complexity gate — trivial tasks (fix a typo, rename a variable) skip reasoning entirely — and routes everything else to the matching protocol. Routing is compositional: a task can match several rows (a new security-sensitive feature runs problem-classification and security-reasoning, with gap-analysis always last), and three depth tiers (QUICK / STANDARD / DEEP) scale the rigor to irreversibility × blast radius, so a gut-check costs a minute while a schema decision gets fresh-context review.

Enforcement is deliberately concentrated instead of spread everywhere: one <HARD-GATE> in the router holds three invariants (no final recommendation without gap-analysis, no trust-boundary code without STRIDE, confidence stated on every analysis), and each protocol body keeps its own gates. Two failure modes are designed against explicitly: skipping — rationalization-catching names the exact thoughts agents have right before they skip ("I can handle this directly," "this is straightforward enough") and treats them as the signal to route; and compliance theater — an anti-theater check requires the agent to name which check actually changed its approach, because filling templates with plausible filler is a protocol violation, not compliance.

The router also handles the two situations rigid protocols get wrong. User override: the user is the principal — if they say "skip the analysis," the agent states what's skipped and the concrete risk, offers the QUICK tier, then respects their call. Autonomous mode: in headless, CI, or subagent runs where no user can answer, gates that would ask for confirmation instead state their assumptions in writing, cap confidence at MEDIUM, and surface open questions at the end.

What we learned building it

Six iterations from a passive reference that agents ignored to behavioral enforcement that holds under adversarial pressure:

1. The description IS the enforcement. If it reads as a suggestion, the agent skips it.
2. Sub-skill namespaces don't resolve locally. Skill(praxis) works. Skill(praxis:sub-name) doesn't. Sub-protocols load via bash file reads.
3. HARD-GATEs work — but only after invocation. The description must compel invocation; body gates are second-line defense.
4. Agents adapt protocol intensity to context. Under time pressure, the agent runs compressed STRIDE instead of full ceremony. This is correct behavior.
5. Instructions to invoke another skill must be explicit commands. Prose like "brainstorm using the analysis above" didn't trigger invocation. An explicit "Invoke Skill() NOW" did.

Philosophy

• Behavioral enforcement, not reference. Skills are protocols to follow, not documents to read.
• Reason before executing. The approach matters as much as the implementation.
• Mandatory checkpoints. HARD-GATEs prevent skipping steps that catch expensive mistakes.
• Confidence calibration. Every analysis states its confidence level. Uncertainty is explicit, not hidden.
• Composability. A reasoning layer, not an execution engine. It reasons, then hands off to whatever builds and ships — it never replaces execution skills.

Contributing

See CLAUDE.md for contributor guidelines. The short version: skills are behavioral protocols, not reference documents. If your PR adds a framework name without building the enforcement protocol, it adds zero value. Show before/after results from real agent sessions.

License

MIT

Built by @_cyr4x · GitHub