Imported from agix-ai/agix-aos (AGENTS.md). Install upstream with npx skills add agix-ai/agix-aos. Copyright stays with the author.

AGENTS.md

Operating contract for agents working in Agix AOS — the open, self-hostable operating system for a governed AI agent fleet. This file is what an agent (or a human) reads first to understand how work is done here. It ships at the repo root of the public distribution.

What this repo is

Agix AOS runs a governed swarm: many small agents that plan, act, and verify each other's work, under a single conductor, with every consequential step gated by a contract you can read. The pieces:

• core/ — the Go engine and the agix-core CLI. The governance primitives live here: the tool-use loop, the capability boundary, the Comb (the knowledge store), and the actor≠verifier gate. CGO_ENABLED=0 — a single static binary.
• fleet/ + agents/ — the agent fleet, TypeScript on Bun (never Node). Each agent is a manifest (agents/<name>/agent.json — declarative governance metadata the Go engine reads) plus an optional behavior (agent.ts). This is the "build your own bee" surface.
• packs/ — composable capability packs (e.g. the refactoring pack) that drop a governed sub-swarm onto a target repo from a sidecar, with zero footprint in the target.
• services/ — the Hono/TypeScript web + API + connector layer.
• cli/crates/ — the Rust intra-agent bus.

The governance contract (the part that matters)

Three invariants define the system. An agent that breaks one is a bug.

1. Actor ≠ verifier. The agent that produces work never certifies it. A distinct verifier actor grades every governed result, and the verdict — not the producer's say-so — decides whether work is accepted. The engine enforces this; agents cannot self-approve.
2. Boundary as capability. An agent may only touch what its manifest's boundary grants — the files it may read/write, the tools it may call, the secrets it may receive. A tool call outside the boundary is refused, not logged-and-allowed. Credentialed tools receive a scoped grant, never a raw key.
3. External grounding beats judgment. A verdict grounded in an external oracle (a passing test suite, a clean build, an exit-0) is stronger than a model's opinion. Certified, externally-grounded results are the only ones that persist as durable knowledge in the Comb.

Build · test · run

# Go core + CLI
cd core && go build ./... && go test ./...

# The TypeScript fleet (needs Bun; never Node)
bun test fleet/tests/

# Run an agent (governed): declarative engine, scoped to a target dir
agix-core agent run <name> "<task>" --engine --repoRoot <dir>

agix-core agent list shows the fleet with each agent's caste, trust, and declared tools.

Adding or changing an agent

1. Create agents/<name>/agent.json — the manifest: name, role (queen/worker), trust, tools, and a boundary (the read/write/secret grants). Set "public": true only for agents meant to ship.
2. Optionally add agents/<name>/agent.ts — the behavior, run on Bun. It drives the Go engine through the provided context (ctx.hive.run, ctx.read/writeRepoFile, the governed tools); it never reaches outside its boundary.
3. Add a test under fleet/tests/<name>.test.ts. The suite must stay green.
4. Keep the change scoped and reviewable.

Conventions

• No secrets, ever. No API keys, credentials, personal, or private data in any committed file. Keys are resolved at runtime from your own configured backend by alias — never a literal value in a commit, config, or comment.
• Tests are the contract. go test ./... and bun test fleet/tests/ are green before you commit. A red suite is not shippable.
• Boundaries are load-bearing. When you widen an agent's boundary, say why in the manifest — a reviewer reads the boundary to know what the agent can do.
• Governance is not optional. Don't add a path that lets an agent approve its own work or write outside its grant. That is the one thing this project exists to prevent.