ai-praxis: Instructions file for Codex

AI Praxis - Development Instructions

This file contains instructions for developing and improving THIS repository itself.

If you're here to bootstrap another project, see bootstrap/AGENTS.md instead.

Project Purpose

This repository is a comprehensive methodology system for AI coding assistants. When users point their AI tool at this repo, it reads the instructions in /bootstrap and uses them to set up the praxis system in the user's own project.

Supported Tools: Claude Code, Cursor, Windsurf, Cline, and other MCP-compatible AI assistants.

Guiding Principles

1. Tool-agnostic first - AGENTS.md is the primary format; CLAUDE.md is a forwarding shim. Every feature must work across tools, with tool-specific branches only where unavoidable.
2. Methodology over config - We teach patterns and principles, not dump config files. The bootstrap should make the user's project self-sufficient.
3. Progressive disclosure - Don't overwhelm. Start with what matters most, let users discover depth as they need it.
4. Minimal footprint - Generate only what the project needs. No bloat, no unused templates, no speculative features.
5. Idempotent and safe - Running bootstrap twice should not break anything or duplicate content.

What This Repo Is NOT

• Not a plugin - We don't ship runtime code that hooks into AI tools
• Not a config dump - We don't copy dozens of files into ~/.claude/
• Not Claude-specific - Despite the CLAUDE.md shim, the system targets all AI coding assistants
• Not prescriptive about stack - We detect and adapt to the user's tech stack, not impose one

Repository Structure

ai-praxis/
├── AGENTS.md                    # You are here (meta instructions)
├── CLAUDE.md                    # Forwarding file for Claude Code
├── README.md                    # Human documentation
├── examples/                    # Real-world AGENTS.md examples by stack
├── tasks/                       # Backlog of improvement ideas (gitignored)
└── bootstrap/
    ├── AGENTS.md                # Entry point router (mode selection)
    ├── .state/                  # Environment setup state
    │   ├── .gitkeep
    │   └── environment-state.template.json
    ├── environment/             # Mode 1: Environment setup (global tools)
    │   ├── AGENTS.md           # Environment orchestrator
    │   └── procedures/
    │       ├── 01-install-serena.md
    │       ├── 02-install-mcp-servers.md
    │       └── 03-install-agents.md
    ├── project/                 # Mode 2: Project bootstrap (project files)
    │   ├── AGENTS.md           # Project orchestrator
    │   ├── procedures/
    │   │   ├── 00-analyze-project.md
    │   │   ├── 01-generate-agents-md.md
    │   │   ├── 02-generate-docs.md
    │   │   ├── 03-setup-adrs.md
    │   │   └── 04-setup-contexts-commands-agents.md
    │   └── verification.md      # Post-bootstrap verification
    ├── templates/               # Shared templates for both modes
    │   ├── AGENTS.md.template
    │   ├── adr-template.md
    │   ├── agents/              # Agent definition templates
    │   ├── commands/            # Slash command templates
    │   ├── contexts/            # Behavior mode templates (dev, review, research)
    │   ├── guides/              # Guide templates (TDD, code quality, etc.)
    │   ├── hooks/               # Hook script templates (Claude Code)
    │   ├── hooks.json.template  # Hook config template
    │   └── rules/               # Rule templates (common + language-specific)
    │       └── common/          # Language-agnostic rules
    └── reference/               # Shared reference docs
        ├── guardrail-principles.md
        ├── serena-best-practices.md
        └── token-optimization.md