Repository guidelines

Praxis Agents OS is the open source platform behind Praxis Agents for creating, operating, and governing AI agents. Optimise for a small, maintainable foundation and a non-technical operator. Put complexity behind defaults and progressive disclosure. Prefer removing bespoke internals over preserving compatibility.

Read before changing files

Read the instructions and references that apply to the task:

• For all writing, read and follow the technical language guide, including comments and docstrings.
• For backend changes, read backend guidelines.
• For frontend changes, read frontend guidelines.
• For reviews and final self-review, use the review checklist.
• For implementation details, use the documentation index. Read the relevant domain and provider references before editing that area.

Read app instructions explicitly even when starting from the repository root. Linked implementation documents are task-specific references, not startup imports. For the instruction layout and its rationale, see the agent instruction guide.

Working rules

Apply these rules throughout the task:

• Do not create Git commits without explicit human approval. A request to implement, fix, or change code does not authorise git commit.
• Read nearby code before editing. Complete the requested scope, make routine implementation choices, and keep changes focused. Report unrelated findings instead of adding refactors, abstractions, or features to the change.
• Keep functions easy to follow. Use cyclomatic complexity as design feedback and extract focused helpers when that makes control flow clearer.
• Use GitHub issues for public tracking and docs/architecture/ for durable design decisions. Keep scratch plans and private implementation notes local.
• Before proposing broad capabilities, check architecture notes and recent history for prior decisions and rejected approaches.
• When behaviour, routes, settings, or setup changes, update the owning docs in the same change. Update AGENTS.md when guidelines or navigation change; keep provider inventories and implementation details in focused references. When a change alters a flow that an internal skill describes, update the file under apps/api/services/agents/runtime/internal_skills/ too.
• Describe public capabilities as implemented only when wired end to end. Mark incomplete capabilities as pending.
• Keep secrets, generated caches, virtual environments, local databases, and build outputs out of Git.
• You are working as a swarm of agents collaborating to reach the same goals. There is a private message board available to you and all other agents at docs/message-board/. You may create or update any files in this dir to help communicate your progress with other agents and ensure you are collaborating in the best way to reach the goals without clashing or competing.

Security and product boundaries

Preserve these boundaries in every change:

• Treat workspace isolation, approvals, delegation, credentials, audit, and sessions as high-risk areas. Add tests in proportion to risk.
• Keep CORS, cookies, CSRF, rate limits, and provider validation strict. Use explicit local configuration instead of weakening production behaviour.
• Keep console email and local filesystem storage local-only, with settings validation rejecting them elsewhere.
• Keep agent actions on external systems permissioned, observable, and reversible where practical.
• For Docker changes, keep local services bound to 127.0.0.1, production images small and non-root, and runtime secrets outside images.
• For GCP bootstrap and deployment, use an explicit ENV_FILE and preserve the bootstrap's typed approval gate. Read deploy/gcp/README.md first.

Tests

Write tests that catch real regressions, and keep the suites fast. Every test must fail for a plausible bug that no other test already catches.

Test these thoroughly, with one focused case per distinct rule:

• Security boundaries: workspace isolation and row-level security, auth, sessions, CSRF, rate limits, credentials, approvals, delegation, audit records, and handling of untrusted content. Include the denial path, not only the allowed path.
• Logic that can break silently, such as parsers, reducers, formatting of money and numbers, scope rewriting, idempotency, and resume or retry without duplicate effects.
• Provider boundaries: what we send to and accept from external APIs, with one representative case per operation family.
• Runtime behaviour, with one deterministic scenario per distinct behaviour.

Don't add these:

• Assertions on copy, labels, headings, or long lists of toContain checks over rendered HTML. One smoke render per presenter family is enough.
• Tests of constants, enums, registry listings, settings defaults, schema shapes, or framework behaviour such as FastAPI routing, Pydantic validation, or React rendering.
• Tests that assert mock call sequences instead of outcomes.
• The same rule proved again at another layer. Test it once, as close to the behaviour as you can, usually in a service test or scenario.
• Parametrize or it.each matrices that exercise the same code path. Pick one to three representative cases, favouring the security-relevant ones.
• Copies of a generic contract test for each provider, tool, or storage backend.
• Tests for legacy data or backfill paths. No production deployment exists yet.
• Real sleeps or retry backoff. Patch the clock, shorten the setting, or use a status that doesn't retry.

When you change code, update or remove the tests it affects instead of adding new ones beside them. Before you add a test, check whether an existing test already covers the rule.

Repository and verification

apps/api contains the FastAPI backend and separate Python worker. apps/web contains the Vite and React frontend. apps/renderer contains the isolated media renderer (ffmpeg behind a shared driver); see video tools. The root Makefile wraps local development; Docker Compose provides Postgres and optional application services.

Use the relevant checks and report anything you could not run:

• make bootstrap prepares local configuration and dependencies; make dev starts the local development stack. See local development for details.
• make check runs backend lint and format checks, Alembic drift checks, database-backed pytest, and the complete frontend pnpm check.
• make media-renderer-check runs the renderer's isolation and ffmpeg tests on Linux in Docker. Run it when apps/renderer changes.
• Run the most relevant checks for changed files before finishing. Keep test scope proportional to the change and use each app's documented commands.
• Production dependency audits match CI and require registry access: python3 .github/scripts/dependency_audit.py api and python3 .github/scripts/dependency_audit.py web. For a full sweep that also checks Cloudflare Radar Zero-Wire and new CVEs, use the dependency security audit skill.
• You are working as one part of a team of agents collaborating to reach the same goals. There is a private message board available to you and all other agents at docs/message-board/. You may create or update any files in this dir to help communicate your progress with other agents and ensure you are collaborating in the best way to reach the goals without clashing or competing.