AGENTS.md — AgenticOS

The one instruction file for coding agents in this repository - Claude Code, Codex and any other. There is no CLAUDE.md; this is it.

Project-wide decisions and pointers to task-specific guidance. Read relevant rules, skills and documentation as needed. Keep detailed procedures and incident history outside this file. Current user instructions and higher-priority session rules take precedence.

What this is

A self-hosted, open-source, multi-tenant platform for a company's AI agents.

An agent is a versioned spec. Users configure instructions, models, capabilities and budgets in the UI, publish a version and can export it as YAML. The same agent runs through web chat, the HTTP API and channel integrations. Change an individual agent through its spec; change Python when implementing platform behaviour or capabilities. Tools reach models through the capability registry.

Stack: FastAPI, Pydantic v2, Pydantic AI, PostgreSQL with pgvector, Redis, Next.js, React, bun, next-intl and MkDocs Material. Use versions from the repository manifests and lockfiles; Python is pinned in backend/.python-version.

The repository originated from the Full-Stack AI Agent Template. Platform and template-inherited subsystems have different coverage gates, described below.

Quality and scope

• Type owned boundaries and nontrivial helpers. Do not use Any or suppressions to hide errors. Necessary suppressions need a specific explanation; route return annotations below are an explicit project convention.
• Use domain exceptions with message and details. Do not swallow exceptions or mask bugs with fallbacks.
• Keep changes scoped. Avoid speculative abstractions, unused code and unrelated cleanup. Comments explain non-obvious constraints; API contracts belong in docstrings. See .claude/rules/code-style.md.
• Test new behaviour and add regression tests for bugs. Documentation-only changes need documentation checks, not artificial application tests.
• Integrate new user-facing features with the existing product: onboarding for new pages and creation flows, and dashboard widgets for activity or state that belongs at a glance. Follow .claude/rules/frontend.md for registries, permissions, translations and anchors.

Hard boundaries

• Routes call services; services coordinate repositories. Routes must not import or call repositories directly.
• Repositories use db.flush() and db.refresh(), never db.commit(). Use DBSession: its scope="function" commits after the route returns and before the response is written. A bare Depends(get_db_session) has different timing. The agent run paths in AgentRunnerService._run and ChatAgentRunner.run explicitly commit before the model call and in terminal cleanup; app.services.telephony.runtime commits telephone admission, submission, transfer, hang-up and single-use media claims before external effects; unknown acceptance is retained for signed callbacks and cleanup, never automatic redial. VoiceCallStarter.start commits a call's row and its run before the call connects and VoiceCallSession commits again in its teardown (per-turn messages, heartbeats and approval writes use their own get_db_context() sessions); SessionService.detect_refresh_reuse commits the security response its caller is about to raise past; and WorkflowExposureService._answer commits a webhook's admission before waiting for its Respond to webhook step. See docs/architecture.md#the-requests-transaction.
• Queue background work that must happen as a job with app.services.background_jobs.enqueue, in the request's own transaction, so it commits with the rows it reads. Best-effort work that may be lost goes to spawn_after_commit. See docs/architecture.md#dispatching-background-work-from-a-request and the background-task skill.
• Collection routes use require(...) gates. Per-resource routes for agents, skills and collections delegate to a service using resolve_access; a role gate must not reject access allowed by a resource grant. Follow permissions-rbac.
• Route handlers return -> Any and declare response_model for serialization. Keep service and repository return types precise.
• Store credentials through app/core/vault.py. Connector sources reference vault secret IDs; do not put credentials in a connector's CONFIG_MODEL or introduce deployment-wide Fernet keys, CHANNEL_ENCRYPTION_KEY or app/core/crypto.py.
• Organization authority comes from membership and the permission catalog. Do not restore UserRole, User.has_role(), RoleChecker, CurrentAdmin, CurrentSuperuser or the old users.role column.
• Use datetime.now(UTC) and secrets.compare_digest() for API key comparisons.
• Migration numbering restarted after a baseline squash. Verify references against backend/alembic/versions/ and cite full filenames; use git history for removed revisions rather than assuming an old number still identifies the same migration.

Read the matching rule before writing code

Read the relevant files under .claude/rules/; their frontmatter defines the file scope. Load only the rules that apply to the change.

Read the matching skill before starting a task

Skills live in .claude/skills/<name>/SKILL.md. Read the skills matching the task; .claude/README.md explains the layout.

Commands

make dev                                          # postgres, redis, api, worker, frontend
make platform-bootstrap BOOTSTRAP_API_KEY=sk-...  # an org, an owner, a model, an agent
make check                                        # every CI job but e2e - CI runs it, not your laptop

make help lists the rest. Day to day:

Verification

Do not run the full suites on a laptop; CI runs them. make test, make test-frontend-cov, make check, make test-e2e and a whole-directory pytest or vitest take tens of minutes and load the machine somebody is working on. Locally, run small batches: the test files covering what you changed, make lint or the half of it for the side you touched, and make db-check after a model change. Run frontend commands from frontend/, backend commands from backend/ and make targets from the root.

cd backend && uv run pytest tests/test_attachments.py tests/test_transcript.py -q
cd frontend && bunx vitest run src/components/chat/chat-container.integration.test.tsx

The coverage gates, integration tests, e2e and the rest of make check are what GitHub Actions runs on every push. Push, then read the run for that commit's SHA: gh run list --branch <branch>, then gh run view <id> --log-failed for a red job. A later push can cancel an earlier run, and path-filtered jobs may be skipped, so a green run belongs to the SHA it ran on. Report failures with the job and the error, and say when a gate has not run yet. See docs/branching.md and the workflow files for CI behaviour, and .claude/rules/testing.md for scoped commands.

Environment

• Use the repository's pgvector-enabled PostgreSQL image; stock PostgreSQL lacks the vector extension required by RAG. Check the image if ingestion fails in a fresh environment.
• Match backend/.python-version when creating or syncing the backend environment. Check the interpreter actually used by uv run before relying on test results.

Testing

Read docs/testing.md, .claude/rules/testing.md and the relevant testing skill for fixtures and patterns.

• The platform layer has a 100% coverage gate. Exact modules are configured in backend/pyproject.toml; template-inherited subsystems are additionally reported by make coverage-all without that gate.
• When adding a platform module, keep [tool.coverage.run] include and the matching [[tool.ty.overrides]] include aligned, including order. backend/tests/test_coverage_gate.py checks this contract.
• Async tests use anyio: pytestmark = pytest.mark.anyio.
• Cover refusal and failure paths: tenant isolation, scopes and grants, budgets checked before model calls and recorded on failure, invalid specs rejected at publish, and secrets excluded from responses, logs and audit entries. Also cover channel sender identity, parser/routing compatibility and existing stored JSONB when tightening validation. The testing skills contain worked examples.

Documentation

Update existing documentation in the same change when described behaviour changes. Refactors with unchanged behaviour and test-only changes do not require unrelated prose edits. Update rules and skills when referenced paths or contracts change. API reference changes belong in the generating docstrings.

Read the project-docs skill for site structure, writing conventions, generated pages and build checks. Add new pages to mkdocs.yml, relevant cross-links and the topic map below. scripts/docs_drift.py contains the code-to-page trigger map; its Stop hook is a reminder, not a completeness check or a gate.

The site publishes in four languages, so a published page owes a .pl.md, a .de.md and an .es.md beside it, and editing an English page makes all three stale. The same is true of README.md, CONTRIBUTING.md, SECURITY.md and CODE_OF_CONDUCT.md, which GitHub renders rather than MkDocs: those record the fingerprint in an HTML comment, cannot pin an anchor, rewrite their own in-page links per language, and point every other link at the reader's own language. scripts/check_docs_i18n.py gates make lint on all of it and names what is missing; docs/howto/translate.md is the workflow. Record a retranslated page with --update <page>.<locale>.md — it takes paths, because stamping one nobody retranslated is how a stale translation stops being visible.

Git

• Never commit on main. Use a feature or fix branch, one PR per coherent change, squashed on merge.
• On a branch, commit and push each finished, verified piece without being asked. This is the project's exception to the global commit-on-request preference; explicit session instructions still take precedence.
• No AI attribution in commits or PR descriptions: no Co-Authored-By: Claude, Generated with Claude Code or equivalent footer.
• Stage only intended changes and review the staged diff. Exclude secrets, unrelated work and tool caches.
• Use Conventional Commits: type(scope): summary, imperative, lower case after the colon, no trailing period, at most 72 characters. Types: feat, fix, refactor, perf, test, docs, ci, build, chore. Scope names the subsystem; omit it for repository-wide changes. Use ! and a BREAKING CHANGE: footer for breaking changes.
• Add a body when the reason, verification or tradeoffs are not clear from the subject; wrap it at 72 characters. Put issue references in footers (Closes, Refs, Part-of); use Closes only when the issue is fully resolved.
• PR descriptions explain the problem, resulting behaviour, verification and material limitations. Review the diff and surrounding code before declaring work finished. .claude/commands/review.md defines the local review standard. docs/code-review.md and .github/workflows/ai-review.yml describe automated review. A failed reviewer is not a clean review; assess findings against the code and explain rejected ones.
• Fix confirmed in-scope defects; record out-of-scope defects without expanding the change. Before filing or triaging issues, read .claude/references/issue-triage.md for the repository's board conventions.

Releases

Versions follow Semantic Versioning from 1.0.0 onwards, except that the major stays 1 (below); every release before 1.0.0 was 0.0.N. CHANGELOG.md and docs/release-notes.md state that exception to operators. A release is numbered by the largest change it ships, judged by someone running a deployment, not by the size of the diff:

• Cut after the merge, never beside it. Once a PR lands on main, a chore: cut X.Y.Z PR renames the [Unreleased] block in CHANGELOG.md to ## [X.Y.Z] - YYYY-MM-DD under a new empty [Unreleased], and bumps backend/pyproject.toml, backend/uv.lock and frontend/package.json. Feature PRs write their changelog entries under [Unreleased]; the cut does not add new ones.
• Prepare a release train with make release-cut BUMP=patch (or minor); add CREATE_PR=1 to create the cut PR from fresh origin/main. The default only prints a plan. CI and CodeQL may reuse successful full runs for a proven version-only cut; missing evidence runs full checks. See docs/branching.md.
• After the cut merges, publish the release and its tag in one step: gh release create vX.Y.Z --target <cut merge commit> --notes-file <its changelog section>. Never push the tag first: it starts images.yml at once, and that attaches the release SBOMs only to a release that already exists. Production deploys wait for approval (deploy.yml).
• One release per merged change, or one for a train merged together, numbered by the largest change in it. Stacked PRs are released in merge order, each with its own number.
• An agent asked to release may pick a PATCH or MINOR number by the table above. Never propose 2.0.0 or any later major; a number the maintainer has named is the maintainer's decision.