agentleFS
andrewgolovanovandrewgolovanov/agent-os/AGENTS.md

agent-os

AGENTS.md7 starsChanged 3 months agoMITView on GitHub

This repository is the portable Agent OS source. Keep user project code and mutable operational state in the selected private AGENT_OS_HOME; only Agent OS core, app/plugin components, reusable workflows, tests, and product documentation belong in the source candidate.

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repositoryOne other file it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

9 rules. About 0 are common, 8 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Treat private AGENT_OS_HOME/config/projects.yaml as the canonical registry for project keys, aliases, project roots, and repository paths.

    line 9
  2. Distinctive:

    Read the registered project root AGENTS.md before working on that project.

    line 12
  3. Distinctive:

    Before Git-sensitive conclusions or mutations, verify the exact path, repository root, remotes, branch, HEAD, and worktree status.

    line 13
  4. Distinctive:

    Keep one canonical owner for each fact.

    line 33
  5. Distinctive:

    Prefer a small reversible change.

    line 34
  6. Distinctive:

    Treat documentation as part of the implementation, not as later cleanup.

    line 40
  7. Distinctive:

    Keep agent-facing commands, required checks, routing, and ownership rules in the nearest applicable AGENTS.md.

    line 41
  8. Distinctive:

    Write repository documentation, READMEs, agent instructions, examples, and release notes in English.

    line 42
  9. Distinctive:

    Update only affected documents.

    line 43

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Agent OS repository instructions

Purpose

This repository is the portable Agent OS source. Keep user project code and mutable operational state in the selected private AGENT_OS_HOME; only Agent OS core, app/plugin components, reusable workflows, tests, and product documentation belong in the source candidate.

Always

  • Treat private AGENT_OS_HOME/config/projects.yaml as the canonical registry for project keys, aliases, project roots, and repository paths.
  • Automatic Codex project sync may add deterministic existing local project roots discovered from public active-thread cwd metadata or the current task cwd; Git is optional. It may attach or fill verified repository metadata later only when the Git root equals the registered project root. It must skip conflicts, missing paths, ambiguous overlaps, and transient worktrees without a durable checkout; it never imports thread content or creates Task Board outcomes. After registration it may link a known stable Slack channel only when the normalized channel name has exactly one registered project owner and every labeled outcome is either unassigned or already attributed only to that project. It may attribute only unfinished unassigned outcomes; completed and conflicting attribution are immutable. All ambiguous Slack cases, manual onboarding, nested or multi-repository changes, and relinking remain preview-first.
  • Resolve a project through the registry before substantive project work.
  • Read the registered project root AGENTS.md before working on that project. For a multi-repository registration, then obey any more specific repository AGENTS.md before editing that repository.
  • Before Git-sensitive conclusions or mutations, verify the exact path, repository root, remotes, branch, HEAD, and worktree status.
  • Preserve unrelated changes. Never move project repositories, change remotes, publish, deploy, or write to external services without explicit user intent.
  • Record durable current state through tools/task-board; do not rely on chat history as the only copy of an important decision or next step.

Route by task

TaskRead first
Agent OS architecture or documentationdocs/README.md, then the owning document
Add or change a registered project.agents/skills/onboard-project/SKILL.md
Work on a registered projectAGENT_OS_HOME/config/projects.yaml, then the registered project root AGENTS.md
Start or resume durable workdocs/task-board.md, then resolve the exact private outcome through tools/task-board or Task Bridge
Task correlation, Codex activity, or checkpointsAGENT_OS_HOME/config/task-bridge.yaml, then docs/task-bridge.md
Slack monitor or review intakeAGENT_OS_HOME/config/monitors.yaml, then docs/slack-monitor.md or docs/review-intake.md
Install or repair optional integrationsdocs/optional-integrations.md, then the relevant plugin skill and provider state
Create or change a skilldocs/extending.md and the skill's SKILL.md

Working contract

  1. Discover and verify facts before editing structured records.
  2. Keep one canonical owner for each fact; documentation may explain a fact but must not silently fork it.
  3. Prefer a small reversible change. Use preview or dry-run behavior for tools that can mutate state.
  4. Validate the affected layer and report exactly what was and was not verified.
  5. For material Agent OS changes, update the owning doc, docs/state.md, and docs/changelog.md; add a decision record when rationale must survive.

Documentation maintenance

  • Treat documentation as part of the implementation, not as later cleanup. In the same change, update every relevant document whose claim became inaccurate because user-visible behavior, setup, commands, paths, naming, architecture, security boundaries, validation, or release behavior changed.
  • Keep agent-facing commands, required checks, routing, and ownership rules in the nearest applicable AGENTS.md. Keep human installation, usage, and contribution guidance in the nearest relevant README. Keep deeper product facts in the owning document under docs/.
  • Write repository documentation, READMEs, agent instructions, examples, and release notes in English. Private user-authored project and task content may follow the user's language.
  • Update only affected documents; do not mechanically touch every AGENTS.md or README. Before handoff, search for removed or renamed commands, paths, and product names, and run every validation command that was added or changed.

Validation

Run ruby tools/validate-agent-os after structural or registry changes. Run tools/sync-plugin-runtime --check after changing any runtime file bundled by the plugin or app. Run tools/task-board validate after task-state tooling changes and tools/slack-state validate after dispatcher-state changes. Validate every changed plugin skill, run node test/plugin_packages_test.mjs after plugin hook or manifest changes, and start a fresh Codex task for real hook-pickup verification. Run repository-specific checks from the registered repository and its closest AGENTS.md.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.