Praxis
(πρᾶξις)
The practice of doing
A filesystem-based methodology for agentic development. Zero dependencies. Just folders, markdown, and native AI tools.
The Problem
AI agents are powerful but forgetful. Every new session starts from zero. The context window is a blank slate — yesterday’s decisions, last week’s architecture choices, the reason you picked PostgreSQL over MySQL — all gone unless someone writes it down.
Context amnesia
AI forgets everything between sessions.
Ephemeral decisions
Prompts disappear, decisions go unrecorded.
No structured handoff
Starting from scratch every session.
No validation
Conventions exist but nothing enforces them.
Adoption Tiers
You don’t have to use everything on day one. Start small and add structure as complexity grows.
Files Only
Zero dependencies
The minimum viable Praxis. Just 3 files and 1 folder. You get session continuity and task tracking with near-zero overhead.
- Context chain (3 documents)
- Work orders with acceptance criteria
- Session continuity
- Audit trail via filesystem
Best for: Solo developers, small projects, quick experiments
Files + Linter
Any Unix system
The full development lifecycle with automated validation. 50 checks enforce the methodology so agents don’t drift.
- Full development lifecycle pipeline
- Research and planning stages
- praxis-lint validation (50 checks)
- CI/CD integration
Best for: Medium projects, multi-session work, projects that need planning before building
Files + MCP
MCP-compatible AI
Native tools that turn the methodology into something the AI doesn’t just follow, but calls. Session start, work order creation, context updates, quality gates — all as native tool calls.
- 12 native MCP tools
- One-call session start
- Auto-numbered work orders
- Enforced quality gates
- Multi-agent routing
Best for: Teams, complex projects, multi-agent orchestration
Each layer adds automation. None of them add lock-in.
Core Components
Context Chain
3 documentsLiving documents that survive every session
source_of_truth.md (canonical rules), context_capsule.md (session handoff), checkpoint.md (milestones). Read at start, written at end. The heartbeat of Praxis.
Work Orders
Structured tasksThe standardized unit of AI work
Formal documents with scope, acceptance criteria, and a pending-to-executed lifecycle. The work order is to AI development what the shipping container was to global trade.
4-Stage Pipeline
4 stagesEvery folder maps to a lifecycle stage
Research, Planning, Execution, Reports. When you open a Praxis project, you immediately know where everything is and why it’s there.
Validation (praxis-lint)
50 checksConvention-enforced, not just convention-based
7 categories of automated validation — structure, context freshness, work orders, naming, security, SOT consistency, and orphan detection. Zero dependencies, one file, any Unix system.
MCP Server (praxis-mcp)
12 toolsMethodology as native tool calls
The AI doesn’t need to be told how to follow Praxis — it calls the tools, and the tools enforce the methodology. Session start, work order creation, context updates, quality gates.
Development Pipeline
Why Work Orders Beat Prompts
Operating Modes
Praxis supports two operational modes with extensible topologies and full provider agnosticism.
Default Modes
Solo mode for individual agents, Triangle mode for multi-agent collaboration. Triangle is a role topology, not a provider lock-in.
Solo Mode
One AI agent operates independently. Work orders are a flat queue. The default when only one provider init file exists.
Best for: Solo developers, single-agent workflows
Mixed-Provider Triangle
Three different providers, each filling a specialized role.
Same-Provider Triangle
The same provider in three parallel sessions, each with a different role.
Triangle is the recommended starting pattern because it is simple and predictable. Praxis itself is not limited to three agents.
Beyond Triangle
Scale to N-agent graphs with mixed providers, same-provider parallel sessions, and private/self-hosted nodes, while keeping the same core contract.
- Role ownership stays explicit
- Work order routing stays deterministic
- Validation and phase gates stay enforced
Praxis governs coordination and context continuity across agents. It does not constrain which provider or model you use.
Provider Integration
Praxis is provider-agnostic. It works with any AI assistant that can read and write files. Providers and roles are decoupled.
Claude Code
CLAUDE.md
dev/init/CLAUDE_INIT.md
Codex CLI
AGENTS.md
dev/init/CODEX_INIT.md
Gemini CLI
GEMINI.md
dev/init/GEMINI_INIT.md
Any other
Provider convention
dev/init/PRAXIS_INIT.md
Private / Local LLM
Provider convention
dev/init/PRAXIS_INIT.md
The same provider can fill multiple roles via separate sessions if role boundaries are preserved.
Validation
praxis-lint transforms Praxis from convention-based to convention-enforced.
Structure
Required folders exist for your tier
Context Freshness
Handoff docs aren’t stale (capsule < 7 days, checkpoint < 30 days)
Work Orders
Executed WOs are truly complete — no unchecked boxes
Naming
Files follow the {number}_{date}_{desc}.ext convention
Security
No secrets in tracked files (private keys, AWS keys, connection strings)
SOT Consistency
Source of Truth matches reality — referenced folders exist
Orphans
No files in wrong locations — no loose files at dev/ root
Exit Codes
Where It Runs
Claude Code
SessionStart hook — runs automatically, feeds findings to AI
GitHub Actions
CI workflow — blocks PRs with failures
Pre-commit hook
Git hook — validates before every commit
Any AI agent
Init file instruction — AI runs linter as first action
Manual
Run from terminal anytime
MCP Server
Methodology as a Service
Session Lifecycle
session_startReads the full context chain, lists pending WOs, detects tier/mode/providers, returns structured health assessment
session_endChecks whether context documents were updated during the session by comparing file modification times
detect_projectDetermines tier, mode, active providers, and structural completeness — no side effects
Context Chain
read_contextReads context documents with rich metadata: file size, age in days, parsed structural sections
update_capsuleSection-aware update for context_capsule.md — replaces only specified sections, preserves everything else
update_checkpointAppends a new milestone to checkpoint.md — auto-numbers, enforces table format
Work Orders
list_work_ordersLists all work orders with parsed metadata — handles Solo and Triangle mode folder structures
read_work_orderReads a specific work order by number or filename with criteria completion state
create_work_orderCreates a new work order with naming convention enforcement — auto-numbers, auto-dates, routes to correct folder
complete_work_orderValidates all acceptance criteria are checked, then moves to executed/ — rejects if criteria are unchecked
Validation
lintRuns 50 checks across 7 categories and returns structured JSON findings
Scaffolding
scaffoldCreates the complete dev/ folder structure based on tier, mode, and agent list
The Impact
The AI doesn’t need to be told how to follow Praxis. It calls the tools, and the tools enforce the methodology.
The Foundation
Why Filesystem?
Zero dependencies
Works anywhere there’s a file system. No installs, no accounts, no subscriptions.
Git-friendly
The dev/ folder can be tracked or gitignored. Full version history for free.
AI-native
Every AI agent can read and write files. Not every AI agent can call APIs or query databases.
Human-readable
Open any file in any text editor. No special tools needed to understand the project state.
Portable
Copy the dev/ folder to a new machine, a new project, a new team. It just works.
Transparent
No hidden state. Everything is visible, auditable, and diffable.
Praxis works without the MCP server. Any AI that can read a file can follow the methodology. The MCP server doesn’t replace this foundation — it accelerates it.
The methodology came from property management — years of managing construction projects, coordinating contractors, tracking work orders across multiple sites, and maintaining audit trails for compliance. AI agents have the same coordination problems as human teams.
Every rule in this methodology exists because its absence caused a real problem on a real project. Nothing is theoretical. Everything is praxis.
Evolution & Proof
The same patterns were independently reinvented across three projects. That was the signal — these weren’t project-specific hacks, they were a methodology.
Master plans
Manually written markdown plans for multi-week projects losing context in the ChatGPT web interface.
Work orders
Conversational prompts too imprecise for complex execution — acceptance criteria and structured tasks emerged.
Terminal agents
IDE and terminal agents (Windsurf → Claude Code → Codex) replaced web interface workflows.
Source of Truth
Decision drift across sessions required one canonical record — the SOT document was born.
Context chain + dev/ convention
Session state and milestones needed their own files. Root directory chaos resolved with the dev/ folder convention.
Foundation
Initial public release — two years of organic practice formalized into a spec. Context chain, work orders, four-stage pipeline, provider init system, adoption tiers, and operating modes.
Validation
praxis-lint added — 50 automated checks that enforce the methodology. Trust but verify.
This portfolio was built entirely using Praxis. Every work order, context handoff, and audit trail lives in the dev/ folder of this repository.