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.
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:
Built through iterations of testing and tuning. Every critical test passes.
| Test | What it proves | |
|---|---|---|
| T1: Trivial skip | Doesn't over-trigger on "fix this typo" | |
| T4: Non-trivial activate | Fires problem-classification on design tasks | |
| G2: Gap analysis | Runs all 7 cognitive debiasing checks | |
| G3: Security auto-detect | Recognizes auth code without being told "security" | |
| G4: Informed-consent skip | Names the skipped risk, offers the QUICK tier, then respects the user's call | |
| Q1: Diagnostic quality | 5 hypotheses + Strong Inference discriminating test | |
| Q2: Decision quality | Adds "do nothing," asks weights, steelmans the loser | |
| Q3: Code quality | Catches 17 violations including SQLi, MD5, no auth | |
| Q4: Architecture quality | Reversibility, boundary analysis, bottleneck ID |
Each skill is a behavioral protocol with mandatory gates — not a reference document to browse.
| Skill | What it enforces | When it fires |
|---|---|---|
| intent-alignment | Spec mirroring, three-interpretations check, misunderstanding premortem | First, whenever a request could be read more than one way |
| problem-classification | 4 gates: name type → enumerate constraints → select frameworks → frame approach | Before any new design or feature |
| gap-analysis | 7 checks: inversion, second-order, MECE, map vs territory, adversarial, simplicity, reversibility | Before finalizing any design or plan |
| security-reasoning | STRIDE per trust boundary, attack surface table, top 3 mitigations | Auth, crypto, input handling, payments |
| diagnostic-reasoning | 5 hypotheses, Strong Inference discriminating test, 5 Whys root cause | Debugging and failure investigation |
| code-quality-analysis | 15 pass/fail checks across readability, structure, safety, purity, design | Writing, reviewing, or refactoring code |
| architecture-reasoning | Reversibility classification, build/buy/adopt, boundary analysis, bottleneck ID | Architecture and module decisions |
| decision-analysis | Weighted criteria, expected value, second-order, pre-mortem, steelman | Trade-offs and choosing between alternatives |
| strategic-reasoning | JTBD, SWOT with cross-referencing, kill list, measurable OKRs | Business strategy and roadmap decisions |
| performance-reasoning | Baseline before changes, Theory of Constraints, same-methodology verification | Making working code faster, cheaper, or smaller |
| testing-strategy | Test-type classification, high-value failure modes, fail-then-pass regression proof | Deciding what to test; verifying a bug fix is real |
| estimation | Bounded decomposition, reference-class forecasting, explicit ranges and padding | Before committing to effort, time, or cost |
| skill-authoring | Gap named with incident, trigger tested against false positives, adversarial pressure-test | Creating or rewriting an agent skill |
| scoping | MUST/SHOULD/WON'T split, non-empty cut list, acceptance criteria on every MUST | Turning a vague ask into an MVP boundary |
| project-planning | Testable done-criterion per task, explicit dependencies, riskiest work sequenced first | Turning a settled goal into a sequenced plan |
| domain-modeling | Entity invariants, lifecycle ownership, illegal states made unrepresentable | Designing a data model, schema, or entities |
| codebase-comprehension | Entry points, data-flow trace, full blast radius before an edit | Changing code you didn't write or don't yet understand |
| prompt-design | Task spec, named failure modes, ≥3 adversarial tests before shipping | Writing or revising a reusable prompt |
/plugin marketplace add xD4O/praxis
/plugin install praxis@praxis
Restart Claude Code. The router is injected at session start automatically.
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" }
]
}
]
}
}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.
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.
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).
| Command | Runs | Reach for it when |
|---|---|---|
/analyze |
problem-classification | Starting a new feature or design — before touching anything |
/architect |
architecture-reasoning | Weighing a structural decision: boundaries, build-vs-buy, data model |
/comprehend |
codebase-comprehension | Changing code you didn't write — map the blast radius first |
/decide |
decision-analysis | Choosing between alternatives and you want the trade-off made explicit |
/diagnose |
diagnostic-reasoning | A bug or failure needs root-causing before you change code |
/domain |
domain-modeling | Designing a schema or the core entities of a system |
/estimate |
estimation | Committing to an effort, time, or cost number |
/plan |
project-planning | Turning a settled goal into a sequenced build plan |
/prompt |
prompt-design | Writing or revising a reusable prompt or agent instruction |
/quality |
code-quality-analysis | Reviewing or refactoring a diff or a specific file |
/scope |
scoping | Deciding what's in and out of a first version |
/threat-model |
security-reasoning | Any auth, crypto, input-handling, PII, or payments code or design |
/validate |
gap-analysis | A design, plan, or recommendation is about to be called final |
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.
Six iterations from a passive reference that agents ignored to behavioral enforcement that holds under adversarial pressure:
- The description IS the enforcement. If it reads as a suggestion, the agent skips it.
- Sub-skill namespaces don't resolve locally.
Skill(praxis)works.Skill(praxis:sub-name)doesn't. Sub-protocols load via bash file reads. - HARD-GATEs work — but only after invocation. The description must compel invocation; body gates are second-line defense.
- Agents adapt protocol intensity to context. Under time pressure, the agent runs compressed STRIDE instead of full ceremony. This is correct behavior.
- 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.
- 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.
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.
MIT