2026-05-15 OpenClaw workspace AGENTS.md as the repo brief on a headless leased Apple Silicon cloud Mac (HK / JP / KR / SG / US)

When OpenClaw can read an entire monorepo, the highest-leverage document is often not another JSON knob—it is a disciplined AGENTS.md at the Git root that tells both humans and models what “normal” looks like. On leased Mac mini M4 builders in Hong Kong, Tokyo, Seoul, Singapore, and the United States, the same host may run xcodebuild, signing trees, and an assistant that edits Swift. This 2026-05-15 guide places AGENTS.md inside the broader policy stack: it complements workspace allowlists and monorepo guardrails, narrows intent beside multi-agent agents.json role splits, and stays deployable alongside onboard, launchd, and doctor triage—without duplicating machine-readable tool lists line for line.

Why a repo-level AGENTS.md still matters when JSON already exists

agents.json encodes identities, models, and tool surfaces; it is the contract the gateway should parse deterministically. AGENTS.md answers different questions: what product this repository builds, which directories are sacred, which test commands are authoritative, how rollbacks are staged, and who must be paged when automation proposes risky edits. On shared lease hosts, that narrative reduces ambiguous tool calls because reviewers can diff intent in prose during incidents, not only JSON arrays. Keep the file short enough to read in under two minutes aloud; push long procedures into skills bundles and link them explicitly.

Policy stack: where AGENTS.md sits relative to allowlists and agents.json

Think top-down: transport and channels, gateway routing, workspace allowlists, agent runtime JSON, optional skills, and finally repository instructions. AGENTS.md is closest to the repository’s social contract—it should never attempt to override deny-by-default filesystem policy, but it should explain why certain roots exist and how engineers expect assistants to behave inside them. When multiple agents share one host, each profile still reads the same repo; therefore AGENTS.md must remain persona-neutral while agents.json scopes tools per role.

Layer	Primary artifact	Owned by	AGENTS.md should…
Filesystem guardrails	Workspace allowlists	Platform / security	Reference roots by path, never redefine them differently
Runtime policy	agents.json	Automation owners	Explain intent behind profiles; link to JSON paths in Git
Procedural depth	Skills / runbooks	Service teams	Index stable headings; avoid pasting multi-page scripts
Human plus model context	AGENTS.md	Repo maintainers	State mission, tests, rollback, contacts in neutral tone

Recommended skeleton for AGENTS.md in OpenClaw-heavy repos

Use stable headings so both engineers and models can anchor searches. Start with a one-paragraph mission, then list non-goals explicitly—what the assistant must not attempt without human approval (production deploys, keychain mutations, deleting DerivedData for unrelated lanes). Document the canonical test entrypoints (xcodebuild test schemes, SwiftPM package selection, lint wrappers) and the environment variables that must be set for non-interactive shells. Close with escalation: Slack channel, on-call rotation, and the command used to capture gateway logs on the lease host.

• Mission and scope — product context, release cadence, supported branches.
• Directory map — which folders are generated, which hold secrets templates, where CI checkouts land.
• Verification — smallest command set that proves a change is safe.
• Rollback — Git revert strategy plus any host-side caches that must be purged.

Token budget hygiene: keep AGENTS.md thin, skills thick

Large markdown blobs compete with code snippets retrieved by file tools. Prefer tight prose, tables of links, and stable anchors. Move long sequences—release tagging, notarization stapling, multi-region rollout—into skills so the gateway can load them on demand. When you reference skills, include the relative path and a one-line trigger condition (“use after CI green on main”). Revisit size quarterly: if AGENTS.md exceeds roughly two printed pages, split by bounded context (iOS app vs backend services) while preserving a top-level index file that lists sub-briefs.

Git review, tagging, and host rollout discipline

Because AGENTS.md influences model behavior, require pull-request review from both a domain engineer and an automation owner. Tag Git releases when you change instructions materially; mirror those tags in deployment notes so lease hosts can correlate unexpected behavior with a known document version. Avoid editing AGENTS.md directly over SSH unless paired with an immediate commit—drift between working tree and origin/main is a common source of “the assistant did what the old file said.” Pair documentation updates with any agents.json edits so reviewers see policy motion in one diff.

Headless leased Mac realities: shells, editors, and symlinks

SSH sessions often run bash or zsh with different PATH exports than GUI sessions. Document the exact shell profile assumptions in AGENTS.md, and verify them with the same wrapper scripts launchd uses before trusting assistants to invoke tools. Symlinks in monorepos can cause assistants to believe they are outside allowlisted roots; align narrative guidance with the symlink resolution rules from allowlist hardening. When engineers occasionally mount remote editors, remind them that autosave plugins can create temporary files—note ignored patterns so assistants do not treat them as product code.

Decision matrix: edit AGENTS.md vs agents.json vs a new skill

Signal	Prefer AGENTS.md	Prefer agents.json	Prefer a new skill
Change is narrative or educational	Yes—mission, cautions, links	No—avoid prose in JSON	Only if procedural length is large
Change alters tool allow/deny	Add rationale footnote, then JSON	Yes—machine-enforced surface	Optional helper text inside skill
Change adds multi-step shell choreography	Link from brief to skill path	Rare—keep JSON declarative	Yes—keeps AGENTS.md readable
Change is emergency hotfix	Update after incident, not during	Use feature flags or router toggles first	Document postmortem anchors here

Nine-step runbook to introduce AGENTS.md on a leased builder

1. Confirm allowlisted roots with the 2026-05-11 workspace article; fix mismatches before prose work.
2. Draft AGENTS.md in a feature branch; circulate to iOS, backend, and security stakeholders.
3. Map each agents.json profile to sections it must read; remove duplicated tool lists from prose.
4. Extract any procedure longer than twelve steps into a skill; link it with a stable relative path.
5. Run local checks using the same Node major as production per onboard guidance.
6. Merge to main; tag policy/agents-md-YYYYMMDD for traceability.
7. Pull on the lease host; verify file hashes match Git.
8. Restart gateways only if JSON or environment variables changed; otherwise rely on file reload semantics your build documents.
9. Capture before/after metrics: denied tool attempts, average session length, human override rate.

FAQ

Question	Practical answer (2026-05-15)
Should AGENTS.md mention API keys?	No—reference vault names or env var keys only; store values in sealed files or keychain as covered in secrets articles.
Can I maintain language-specific AGENTS.md files?	Only if every variant stays synchronized on policy; otherwise pick one canonical language and translate links, not rules.
How often should we review AGENTS.md?	At least quarterly and after any major Xcode or OpenClaw upgrade; treat it like an SLO dashboard companion.

Why Mac mini M4 rentals simplify AGENTS.md rollouts

Fast NVMe and unified memory make it cheap to keep multiple agent state trees, parallel Git checkouts, and large markdown-plus-skill bundles online simultaneously—so you can rehearse documentation changes on a staging lease before touching production traffic. Compare regional capacity on the pricing page and walk engineers through SSH and optional VNC guides before widening tool scopes.