Praxis

A CLI that installs an AI methodology layer into a codebase — the meta-development rules and authoring recipes that make AI coding agents produce correct, conformant work.

Praxis is not implementation scaffolding and not an application config generator. It writes only the methodology layer — agent instructions, native workflows, methodology permissions and plugin metadata, and its own manifest. It never touches your application code, dependencies, or runtime infrastructure.

npx @aacombarro89/praxis

What it does

Running praxis in a project:

1. Detects your stack from project files — pyproject.toml / requirements.txt / setup.py → python-backend; package.json → node; a react dependency → both node and react.
2. Offers a first-run fork — Quick start (recommended defaults, preview the diff, confirm) or Customize (choose stacks, packages, and targets).
3. Composes the methodology into your repo — it emits Claude Code rules, Codex skills, and managed AGENTS.md blocks without clobbering your own content, and records what it did in a visible, committed, hand-editable manifest: praxis.yaml.

It always previews a single diff before writing. Git is your undo.

Why it's different

Other tools generate agent instructions once; Praxis manages them:

• Versioned, pinned, drift-checked. Methodology ships as composable packages pinned in praxis.yaml, and praxis check fails CI when the installed files drift — think Renovate/Dependabot, for your agent instruction layer.
• Peer-native project facts. When Claude Code and Codex coexist, project-owned shared sections live in both native instruction files. praxis check verifies parity and upkeep fixes factual drift; neither tool depends on Praxis at runtime.
• A composition / merge step that folds methodology into an existing project without overwriting project-specific content.
• One neutral source, per-tool outputs — first-class Claude Code and OpenAI Codex support, plus a generic AGENTS.md target.

The curated methodology — Layer 1 behavioral rules plus Layer 2 stack recipes — is the starting payload that rides this machinery.

The two layers

• Layer 1 (general, stack-agnostic). Tool-neutral behavioral rules that reduce common LLM coding mistakes, plus methodology-upkeep commands: karpathy-claude, wiki-memory, session-handoff, upkeep, instruction-upkeep, safe-permissions.
• Layer 2 (stack-specific recipes). Authoring recipes for the stack you're on — node (node-recipes, node-testing), python-backend (python-backend-recipes, python-testing), and react (react-components, react-testing).

The mental model — imperative entry, declarative truth

This is the npm install pattern. One command (praxis) does the smart thing immediately and records the result in praxis.yaml. Thereafter the manifest is the source of truth: to customize, edit praxis.yaml, then run praxis sync. There is no add/remove — one obvious way to change things.

# Edit this, then run `praxis sync`.
version: 1
methodology: "0.1.0"                 # pinned; `sync` offers to bump
stacks: [node, react]                # detection-seeded, user-editable
targets: [claude-code, codex]        # which agent tools to support
packages:
  - karpathy-claude                  # behavioral rules (Layer 1)
  - wiki-memory                      # the knowledge-wiki command (Layer 1)
  - node-recipes                     # Layer 2 craft (stack: node)
  - react-components                 # Layer 2 craft (stack: react)

New methodology only reaches your repo on an explicit sync that bumps the pinned version — never behind your back.

Workspace hubs (synthetic monorepos)

A repo can be a workspace hub: a meta-repo with several independent git repos ("members") cloned beneath it, each still its own standalone checkout with its own CI. Add a workspace: section to the hub's praxis.yaml — by hand, or let praxis scaffold it for you (when the init wizard sees two or more git repos nested under the root, it offers to set the repo up as a hub):

workspace:
  members:
    - path: node-api
    - path: frontend
      name: web            # optional; defaults to the path's basename
  edges:
    - from: node-api
      to: web
      contract: docs/wiki/contracts/node-api-to-web.md  # optional

Member repos need nothing — no workspace: section of their own, no Praxis awareness at all; all cross-repo knowledge and enforcement lives in the hub. Add the workspace package (packages: [..., workspace]) and sync to get /praxis-workspace-upkeep: a hub-sovereign upkeep pass that keeps the hub's cross-repo wiki current, audits each cloned member in report-only mode, flags edges likely gone stale, and applies edits to a member only when you confirm them.

Commands

| Command | What it does | |----------------|------------------------------------------------------------------------------| | praxis | First-run wizard; apply. | | praxis sync | Reconcile the repo to praxis.yaml; offer newer methodology; diff + confirm. | | praxis check | Dry-run; report drift; non-zero exit for CI. |

--yes skips prompts for non-interactive/CI use. Repeat --target, for example praxis --yes --target codex --target agents-md, to override target detection.

Tool-neutral by construction

The methodology source is singular; Praxis emits per-tool variants from it. Claude Code (.claude/rules/, commands, settings.json), OpenAI Codex (AGENTS.md, .agents/skills/, permission profiles/rules, plugin marketplace), and the generic agents-md flat-file convention are built today. Cursor is a planned target; Copilot/Windsurf/Roo are deferred until they land.

"Memory" means the agent's memory, not the app's

In Praxis, memory always refers to the AI coding tool's curated, file-based instruction layer (CLAUDE.md or AGENTS.md, the knowledge wiki, skills, decision notes) — not a runtime memory backend for your application (Mem0, Zep, Letta, etc.). Wiring a persistence backend into your app is implementation, and out of scope. The most Praxis ships on that topic is a Layer 2 decision recipe: guidance on whether you need runtime memory and how to choose — never the backend itself.

Developing Praxis

Praxis is a TypeScript/Node CLI, and it self-hosts: it installs its own methodology and gates drift in its own CI.

npm run typecheck    # tsc --noEmit
npm run build        # tsc → dist/
npm test             # vitest over test/
npm run conformance  # vitest over conformance/
npm run selfcheck    # praxis check against this repo's emitted files

CI runs all five, in that order, on every push to main and every PR. Work lands on a feature branch and merges via PR — no direct pushes to main.

• src/ — CLI implementation (emit, sync, merge, manifest, packages, permissions, plugins, anchors, init).
• packages/<layer>/<pkg>/ — methodology source (layer1/, layer2/, plus thin external/ plugin-marketplace packages).
• test/ — unit tests mirroring src/. conformance/ — the CI-gated conformance suite.
• docs/wiki/ — the durable, in-repo knowledge wiki and canonical design doc; start at docs/wiki/index.md.

See the peer-native CLAUDE.md and AGENTS.md for the project's non-negotiable rails.