Write a useful AGENTS.md
This is a recommendation for preparing an Oddlynew organization. It describes a useful front door, not one mandatory organization design.
Outcome
Give a newly connected agent enough local context to understand what the organization is, where to begin, how to work, and what requires verification or approval.
Each working organization should have one current AGENTS.md. It is a lightweight local constitution and routing layer. It teaches orientation, authority, and navigation. It does not contain the whole handbook.
Self-sufficient, not self-contained
A useful AGENTS.md works without private oral context. A cold agent can read it and enter the organization safely.
It can still route to local documents and maintained public recommendations. Self-sufficient means that the routes, local authority, and scope are explicit. It does not mean copying every method into the entry point.
What belongs in it
Purpose and audience. Say what the organization exists to accomplish, who works in it, and who may share the whole body of knowledge. Active membership provides organization-wide access. Use another organization when the audience differs.
What does not belong here. Name the material that must not be written into this organization and where it goes instead, for example "Personal notes go to your own private organization, not here." Agents read it before they write, so a person is asked about it once, not every time (If something lands in the wrong organization).
Start here. Point to the two or three documents that own current goals, accepted direction, active work, or the strongest evidence.
How we work here. State the few short local rules that apply across ordinary work.
Recurring loops. When repeated work has revealed a useful feedback, review, monitoring, or execution loop, state the short standing rule here and route to the document that owns the full loop. A connected agent should be able to discover that the loop exists, when it applies, where its evidence comes from, where reusable outcomes are written back, and what requires approval. Do not put the full procedure in AGENTS.md.
Maintenance loop. If this organization should be gardened on a standing basis, state the local expectation briefly: for example, garden after meaningful work, inspect recent changes daily, or run a deeper pass weekly. Name the local owner or route to the maintenance guide. If a separate higher-level gardener also reviews several organizations, say what it may propose or change here and what still requires local or human approval. Do not assume an account-wide gardener automatically has semantic authority over this organization.
Routes. Tell the agent which local index or canonical documents serve the most common jobs.
Authority and approval. State what wins when sources disagree, what must be verified, who can approve consequential actions, where a question for a person and its answer are kept (Ask a person, and keep the answer), and what must not be stored.
Integrations: policy, not inventory. Write which connection serves which task (for example: speech uses the organization's ElevenLabs connection; never personal keys or personal connectors for organization work) and that connections are found with
organizations.listConnections({ organizationId }). Leave out lists of connections, their health and their labels: those are computed live, and a hand-kept list drifts and can show connections to readers who may not use them.Adopted guidance. Explicitly adopt any public recommendation that should apply locally and state its local scope, exception, or stronger rule.
Current attention. Link one living tracker or overview when coordinated work is active. Keep changing status out of AGENTS.md itself.
A rule that needs a paragraph deserves a document that owns it. AGENTS.md states the short rule and links the owner.
A short multi-agent operating rule to adopt
Adopt the role-aware entry procedure and continuation contract in Loop and Graph Engineering. Name the local goal, current-work and return routes beside the adoption. A short local rule can say:
Work as a participant in a multi-agent system. On arrival, identify your role, current work, applicable loop, authority and return destination. Coordinators delegate bounded contributions within actual capabilities; subplanners pass narrower assignments and limits down; leaves execute or return concrete blockers. Parents reconcile and accept results and own required writeback. Preserve meaningful progress, evidence and next actions in the existing owner so another authorized participant can continue.
Keep repository and client instructions to a short entry rule and pointer. Each assignment carries its exact work address, scope, input references, allowed actions, delegation and resource limits, completion condition, artifact and return destination. Do not assume children inherit context, tools or access. Keep the full procedure in its maintained owner. Adoption teaches work organization; the runtime must provide execution and any wake source.
What does not belong
Do not copy full procedures, schemas, tables, or platform mechanics into AGENTS.md. Agents can inspect document types, schemas, metadata, and the live tool descriptions directly.
Do not paste current project status into the entry point. Dated status becomes stale where every session begins. Route to the live owner instead.
Do not create a separate document-types handbook by default. The platform already exposes type names, descriptions, schemas, and metadata. Add local type guidance only when people need to understand how a repeated category participates in the organization's work.
How a connected agent should prepare it
Do not begin with a blank questionnaire when authorized evidence can provide a useful starting point. Inspect the organization's existing documents, types, members, routes, and recent work. When the chosen client makes personal recent-work context available, use it only as evidence for a proposal.
Infer a draft purpose, audience, recurring jobs, canonical routes, local rules, and approval boundaries. Show the evidence behind important inferences and mark uncertainty. Present a concrete draft for review, then ask only questions whose answers would materially change the organization.
Prefer recognition over recall. It is easier for a person to correct "these appear to be your five recurring jobs" than to invent an organization from a blank canvas.
Client-retained context is personal and best effort. It may be stale, incomplete, or drawn from a different audience. Use it to suggest shared knowledge, never to write private context into an organization without confirmation. Distinguish what the client retained about the person, what the agent observed in the organization, and what it proposes should become shared organizational knowledge.
When the organization is empty, use the current conversation and relevant outcome patterns to propose a small starting shape. Do not force the person to learn Oddlynew's information model before the first useful task.
Adopt maintained public guidance locally
A public recommendation does not become local authority merely because it is readable or cited. The organization's AGENTS.md or owning local document must say that the recommendation applies here. Follow Reference public guidance, then state your local rule.
Useful adoptions may include:
Maintain the organization according to Distill, do not accrete: update the owner, preserve useful evidence, and archive superseded work.
Use Common document topologies when arranging work around an outcome. No topology is mandatory.
Use Reshape an organization as it grows when the organization's current routes, owners, evidence, and active attention need a deliberate intervention. Adopt it locally only when that recommendation should govern organization-wide maintenance.
Adopt a maintenance pattern appropriate to this organization. You may use only local gardening, allow a higher-level gardener to inspect several authorized organizations, or combine both. Keep local authority, audience, and approval rules explicit even when the gardener's attention spans more than one organization.
Adopt a public channel, research, writing, or workflow recommendation where it fits, while stating which local guide wins when the organization has a more specific rule.
Adopt Loop and Graph Engineering to make named outcome Loops directly requestable. State the local owner routes for outcomes such as MCP Improvement, Public Knowledge and Gardening, their authority and their completion evidence. Use Make Every Agent Run Improve the Next to improve each Loop from verified runs. Skills supply methods; dependencies and accepted handoffs connect owners. Each Loop may run manually or use its own user-chosen event or cadence in an authorized external runtime. Record and verify any actual installation separately.
Keep each adoption close to its local rule. Link the public owner instead of reproducing its explanation.
A useful starting shape
# [Organization name]
[What this organization does, who works here, and who may share all of it.]
## Start here
- [Canonical knowledge map]
- [Current strategy or goal]
- [Where current work is tracked]
## How we work here
- [Short local rule]
- [Short local rule]
- [Short local rule]
## Where to go for what
Use [Knowledge Map] to find the documents relevant to each recurring job.
## Adopted guidance
- [Public recommendation] applies here because [local scope].
- [Local guide] takes precedence for [specific concern].
## Authority and approval
[What wins, what must be verified, what requires approval, and what must not be stored.]This is a shape for the agent to adapt and present, not text the user must copy into a client.
Check that it works
Use a fresh agent or a cold read. After reading AGENTS.md, it should be able to answer:
What is this organization for?
Who is its audience?
What are the recurring jobs?
What should I read for this task?
How should I write useful outcomes back?
What requires verification or approval?
What does not belong here, and where does it go instead?
Give a fresh coordinator a representative outcome and this organization entry point. Check that it finds current work and a fitting procedure, assigns useful bounded contributions, handles a leaf that cannot delegate, and accepts verified results into existing owners. Then test a fresh coordinator resuming from the work pointer after interruption. Check organization choice, authority and local adoption throughout. Report discovery, useful execution and recovery separately; a read-through alone does not prove them.
If the agent needs oral context, reads everything, invents a new type where an existing one fits, or cannot identify the owner of changed understanding, improve the routes before adding more rules.