Praxis

Abstract

Praxis is a provider-agnostic orchestrator for the execution phase of spec-driven development, built with FastAPI, SQLite, Docker, and Git: brainstorm, spec, and plan wherever you like, then hand it the plan. It is set up inside the coding assistant you already work in and wired in over MCP, so that assistant governs other coding harnesses without anyone leaving the session. The harnesses write the code; Praxis runs the gated loop: it decomposes every plan to fit the model that will implement it, runs each task in a disposable container on its own branch, applies the verify gate when one is configured, has a second model review the diff, and delivers a pull request that waits for your approval. Never a blind dispatch.

  decompose ──▶ dispatch ──▶ implement ──▶ open PR ──▶ verify ──▶ review ──┬──▶ merge gate
   planner      parallel       worker       branch      gate      reviewer │      park
                                                                           │ fail
                                                                           ▼
                                                       re-dispatch with feedback, max 3

The Problem

You plan with a strong model because judgment is what it does best, then hand the implementation to a cheaper tool to save tokens. That handoff has no safety net: the worker starts without your context, gets tasks too hard for it, and you only find out when the code comes back wrong. And every assistant is locked to its own vendor's models by design.

Methodologies & Architecture

  ┌────────────────────────────────────────────────────────────┐
  │  THE ASSISTANT YOU ALREADY WORK IN                         │
  │  your agentic AI, with Praxis wired in over MCP            │
  └──────────────────────────────┬─────────────────────────────┘
                                 │  dispatch · steer · approve
                                 ▼
  ┌────────────────────────────────────────────────────────────┐
  │  PRAXIS ENGINE             FastAPI · SQLite · Docker · Git │
  │  four roles: plan · implement · review · verify,           │
  │  each routed to its own provider, model, and harness       │
  │  capability gate ─▶ decompose ─▶ dispatch ─▶ govern        │
  └──────────────────────────────┬─────────────────────────────┘
                                 │  one task per isolated, disposable container
                                 ▼
  ┌────────────────────────────────────────────────────────────┐
  │  WORKER HARNESSES, doing the typing (a pluggable set)      │
  │  OpenCode · any OpenAI-compatible model (LM Studio)        │
  │  Antigravity · Gemini                                      │
  └──────────────────────────────┬─────────────────────────────┘
                                 │
                                 ▼
  ┌────────────────────────────────────────────────────────────┐
  │  reviewed pull requests, parked for your approval          │
  │  GitHub · plan/{date}-{slug} ─▶ agent/{task-slug}          │
  └────────────────────────────────────────────────────────────┘

• Implement a Plan: Hand Praxis a plan.md (execute_plan, REST and MCP) and it capability-gates the plan against the worker, decomposes anything too coarse, and drives every task to the merge gate; the smallest case is a single dispatched task while your session moves on.
• Auto-Delegate Mode (beta): A global toggle: the reasoning model stops editing files and becomes full-time planner and reviewer, delegating every task to the default worker. Ships as a preview.
• Capability-Aware Task Decomposition: The core mechanism: a capability profile of the implementing model sizes every task, escalates what exceeds the worker's reach, and tunes itself from recorded outcomes.
• Four Roles, Routed Independently: Plan, implement, review, and verify are separate seats, each pointing at any provider (claude, codex, agy, or a local OpenAI-compatible endpoint); cost efficiency is a consequence, never the motivation.
• Pluggable Worker Harnesses: OpenCode (any OpenAI-compatible model) and Antigravity (Gemini) are the two tested workers; one Docker entrypoint contract extends the set.
• MCP as the Primary Control Surface: Dispatch, plan execution, polling, logs, and cancellation are ordinary MCP tool calls; a Typer CLI and a live SSE dashboard drive the same REST API.

How Each Change Is Governed

• Isolation: every task in a throwaway container cloned fresh from origin; your working tree is never touched.
• Branching: plan/{date}-{slug} groups tasks on agent/{task-slug} branches; an integration PR parks at the end.
• Verify gate (when configured): runs before any model reads the diff; blank means "not configured", errors fail closed.
• Review: a second model inspects every diff against intent; a fail re-dispatches with feedback, up to three attempts.
• Merge: human-gated by default; protected branches never automate. Nothing reaches your default branch without you.

Results & Engineering Quality

• execute_plan driven end to end on real repositories, decomposition through merge.
• CI on ubuntu and windows runners with an enforced 80% coverage gate, strict mypy, ruff.
• CodeQL, dependency review, lockfile audit, and secret scanning on every push and weekly.
• A read-only doctor points every red at its fix; rate limits pause and auto-resume; dead runs are reconciled, never left stuck.
• One idempotent setup command; Docker Compose with Caddy auto-HTTPS and SQLite persistence.