Protect what matters

Agents write to your brains on your behalf. You decide which parts they can only propose changes to, and what instructions they follow while they work.

Ground truth

Every brain has a ground-truth/ folder for facts somebody has checked: agreed numbers, current status, decisions that stand. Files there show a Ground Truth badge.

An agent can never change ground truth directly. Its change becomes a proposal, and a person on the Approve role decides. People on the Approve role can save there directly, and their save is recorded.

Every brain also protects routines/, which holds the instructions for routines. A routine runs with nobody watching, so a person approves every change to what it is told.

Protect more folders

Each brain lists its protected paths in .brain/policy.yml. Each entry is a path pattern with a reason a person can read:

version: 1

protected:
  - path: "ground-truth/**"
    reason: "Facts the team has checked. Agents may only propose changes."
  - path: "policies/**"
    reason: "Customer-facing policy. Legal reviews every change."

An agent's write to any of these paths becomes a proposal. ground-truth/ and routines/ stay protected whatever the file says.

Only admins and the owner can change .brain/policy.yml. Ask the assistant to make the change and it is sent to an admin for approval.

Reaching in from other brains

The same file decides whether an agent working in another brain may reach into this one:

• allow: it can read here.
• ask: it must ask, and a person approves the request first. Requests appear under Proposals, as Access requests.
• deny: it can't.

cross_brain_access: ask

Whatever this says, an agent can only reach a brain the person it acts for can reach. To keep a brain from certain people altogether, see Restrict a brain to certain people.

The agent contract: AGENTS.md

Each brain has an AGENTS.md file at its top level. It tells every agent working in that brain how to behave there: what goes in which folder, how to date a status, what never to write. ako gives it to every agent that works in the brain, including Claude when you connect it to ako.

ako writes a starting AGENTS.md when you create a brain. You see it as The agent contract in the last step of setup. Edit it like any other file.

For instructions that apply across many brains, such as house style, use a skill instead.