--- title: "AGENTS.md: shared context for every agent | CommitCycle" description: "Layer 1 — the part of your agent's context CC generates from the zone map, so the rules are the team's rather than one laptop's." url: https://commitcycle.com/docs/concepts/agents-md/ language: en --- # The AGENTS.md context block > Layer 1 — the part of your agent's context CC generates from the zone map, so the rules are the team's rather than one laptop's. Most teams running coding agents end up maintaining context by hand: a personal Obsidian vault, a `CLAUDE.md` that drifted three sprints ago, an `AGENTS.md` somebody wrote once. It is per-person work that produces per-person answers — the same question gets a different agent response depending on whose machine it ran on. CC generates that context instead. `cycle sync` maintains a block inside `AGENTS.md`, derived from the same [`zones.yml`](https://commitcycle.com/docs/reference/zones-yml/) the whole team reviews like code. The task currently open goes to a separate, gitignored `CLAUDE.local.md` beside it. ## What it looks like in `AGENTS.md` This is CC’s own `AGENTS.md` block. It carries no task state at all, so it is the same bytes on every branch, whether or not a task is open: ```markdown ## CommitCycle ### Where the tasks are This repository answers to the board `pow/commitcycle` at https://dash.commitcycle.com. Tasks, their specs and the record of what was decided are kept there — `.zones/board.json` is the binding. Nothing starts by editing files: a task is filed, scoped with four answers, and passes the gate, which is what issues the branch and opens whatever it is allowed to touch. Hand in with your final report as the note — `cycle submit --note "…"`, or `cc_submit` with `note` — under the headings "## Done", "## Verification" and "## Criteria". The board keeps it on the ticket; a hand-in without one leaves the reviewer only the diff. ### Protected zones - **Database schema** (`schema`, open): apps/api/migrations/**, apps/api/src/db/schema/** - **Shared contracts** (`contracts`, open): packages/contracts/** - **Enforcement layers** (`enforcement`, open): packages/hook/**, packages/action/** - **Brand and design system** (`brand`, open): .claude/skills/cc-brand/assets/brand/**, … If you are blocked, do not look for another route. Ask for access with a reason and an alternative, or carry on with the rest of the task and report the block. ### Deploys Never remove `cycle guard-deploy` from a deploy command, and never set `CC_ALLOW_BRANCH_DEPLOY=1` to make a build pass — it exists so a branch cannot reach production, and a deploy that needs it gone is the deploy it was written for. ``` The word after each zone id is its default policy, which decides reading only: `open` here means an agent may read those paths without asking, and still needs a grant to change them. The hand-in paragraph asks for the report by both routes, the CLI and the connector (CC-1331). Nothing in it says whether a task is open, and that is deliberate: a committed file that changed with every task would conflict on every merge. A repository with no task open simply has no `CLAUDE.local.md`. With no task bound to the branch there is no grant to resolve, so writes are denied everywhere, unprotected paths included — “unprotected” describes what needs no approval _inside_ a task, never a place to work without one. **The block says what the repository configures, and nothing about the machine.** On a repository that configures no hook, it gains a section this one does not have — “Nothing here is enforcing this” — saying that nothing the repository ships will stop a write, that whether something installed on the reading machine is checking anyway is a question only `cycle doctor` can answer there, and that the diff is checked at close. Whether this machine is enforcing — the plugin, the repository’s hook, or both — is said only in `CLAUDE.local.md`, the one file that never leaves the machine it is true on. ## What it looks like with a task in progress When a [grant](https://commitcycle.com/docs/concepts/grants/) exists, `cycle start` and `cycle sync` write the task half to `CLAUDE.local.md` — gitignored, so it never reaches a commit: ```markdown ### You are working on CC-42 — The audit trail page Branch `task/CC-42-the-audit-trail-page`. Access expires in about 4 hours. **What it should do.** Render the per-task audit record as a page a skeptic can read. **What it must NOT do.** Do not change what the closing gate accepts as evidence. **Open to you right now**, and nothing else: - `schema` — write: apps/api/migrations/**, apps/api/src/db/schema/** **Read before working** — the playbooks for this task's topics: - .zones/playbooks/frontend.md **Closed to this task.** You may not write there — nothing is stopping you, so this one is on you: - `contracts` (deny): packages/contracts/** - `enforcement` (deny): packages/hook/**, packages/action/** ``` Non-goals are in there on purpose. “Don’t touch the pricing logic” is worth considerably more sitting in the agent’s context than in a ticket nobody re-reads. Two details in there are worth naming. **Read before working** appears when the task declared topics that have playbooks — what earlier work on this subject already learned, handed over before the work rather than after the mistake. And the closed-zone wording changes with the enforcement state: where nothing is watching, it says so in the same sentence that states the rule, because a rule that pretends to be a wall teaches an agent that walls are negotiable. ## The two rules that shape it **It is generated, so it is delimited.** Everything between `` and `` belongs to CC; everything outside is yours and is never touched. A tool that rewrites a file people also edit has to be able to say exactly which bytes are its own. There is one block no matter how many times `sync` runs, and a sync that changes nothing does not rewrite the file. **The task half disappears with the task.** `cycle submit` clears it from `CLAUDE.local.md` in the same breath as removing the grant. A stale “you have write access to billing” left in context after the grant expired is worse than no context at all — it is confidently wrong, and it is the first thing the agent consults when deciding whether to try. The zone list survives both states. It is true whether or not a task is open. ## Why `AGENTS.md` and not `CLAUDE.md` `AGENTS.md` is the cross-tool convention, so the durable block lives there. A team running two different agents should not maintain two files that have to agree. The Claude-specific files are two: a `CLAUDE.md` that `cycle init` writes to import `AGENTS.md`, because Claude Code does not read `AGENTS.md` on its own, and the gitignored `CLAUDE.local.md` for the task in progress, which Claude Code loads directly. Layer 1 cannot stop anything. It exists because [Layer 2](https://commitcycle.com/docs/concepts/three-layers/) is a blunt instrument: a hook that denies a write costs a round trip and a confused apology, and most of those are avoidable by saying so up front. If Layer 1 and Layer 2 ever disagree, **Layer 2 is right.** The block is a courtesy to the agent, not a source of truth about what is permitted. ## What this does not solve It does not make the agent obey — nothing advisory does. It does not carry your architecture notes, your ADRs or your onboarding guide; every section in it is generated — the board this repository answers to, how to hand in, the zone map, the deploy rule and whether anything is enforcing it, with the open task in `CLAUDE.local.md` — and none of them is a section you maintain. And it does not replace a knowledge base: if your team keeps design context somewhere, keep it there. What CC removes is the part that describes **boundaries**, because that part can be derived from a file you already maintain and should never have been transcribed by hand.