agentleFS
sergeyklaysergeyklay/.agents/AGENTS.md

.agents

AGENTS.md6 starsChanged 50 days agoApache-2.0View on GitHub

.agents/ is the canonical source. templates/ may contain only host-specific differences; do not duplicate canonical content there. Run asdf install shfmt or asdf install bats when a tool is unavailable. These constraints protect canonical source files and installed host views.

The file

Show its rules and text

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

13 rules. About 0 are common, 3 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

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

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

    Before finishing any change: make check (runs every CI gate from ci.yml locally)

    line 7
  2. Very specific:

    After changing scripts/install.sh or installer behavior: bats test/

    line 8
  3. Very specific:

    Before finishing a shell-script change: shfmt -d scripts

    line 9
  4. Very specific:

    Before finishing an installer change: shellcheck scripts/install.sh

    line 10
  5. Very specific:

    Run asdf install shfmt or asdf install bats when a tool is unavailable.

    line 12
  6. Very specific:

    Keep behavior shared by hosts in .agents/.

    line 30
  7. Very specific:

    Run make validate after changing a skill.

    line 31
  8. Distinctive:

    Follow the surrounding style.

    line 32
  9. Distinctive:

    Treat every checkout outside the assignment as read-only.

    line 34
  10. Very specific:

    Write scratch files to the session scratchpad or a mktemp -d directory, never inside this repository.

    line 35
  11. Very specific:

    Run a negative control before reporting any green.

    line 37
  12. Distinctive:

    Run the destructive git commands the Working Agreement lists under "Surgical Changes".

    line 52
  13. Very specific:

    Write into an installed host directory.

    line 53

≈ “Common” is an estimate: at least 1 in 5 of the 42,283 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

.agents

.agents/ is the canonical source. templates/ may contain only host-specific differences; do not duplicate canonical content there.

Commands

  • Before finishing any change: make check (runs every CI gate from ci.yml locally)
  • After changing scripts/install.sh or installer behavior: bats test/
  • Before finishing a shell-script change: shfmt -d scripts
  • Before finishing an installer change: shellcheck scripts/install.sh

Run asdf install shfmt or asdf install bats when a tool is unavailable.

Gotchas

  • The installer skips a host whose root directory does not exist; inspect its output.
  • --rules does not remove stale destination files. Legacy Working Agreement cleanup happens only after a successful --context installation.
  • A Claude paths overlay marks a rule that must not become an OpenCode global instruction.
  • --context overwrites the host-native context file and removes only legacy rules that match the canonical content.
  • lint, typecheck and the other file-selecting gates read git ls-files; an untracked file is skipped silently and the gate can still exit 0. Stage it first.
  • Everything tracked under .agents/skills/ ships to five host directories; keep tests and fixtures in test/, which ships nowhere.
  • make validate applies its 17,500-byte ceiling to the skill body, not to SKILL.md as a file: split_frontmatter hands _check_body only the text after the closing ---. No gate lints a skill as Markdown either; lint-markdown selects README.md and docs/.

Boundaries

These constraints protect canonical source files and installed host views.

Always

  • Keep behavior shared by hosts in .agents/; add host-specific frontmatter or prompt fragments only in templates/.
  • Run make validate after changing a skill.
  • Follow the surrounding style. Do not refactor adjacent legacy content without a separate task.
  • Work in the assigned checkout or worktree. A separate worktree is optional; preserve other sessions' changes in a shared checkout.
  • Treat every checkout outside the assignment as read-only. Run runtime tests and mutation controls in an isolated scratch copy.
  • Write scratch files to the session scratchpad or a mktemp -d directory, never inside this repository. Delete your own directory when you finish, and move anything that must outlive the task into .tasks/.
  • Stage a new file with git add <path> before running any gate, for the reason under Gotchas: the file-selecting gates read git ls-files, skip an untracked file, and still exit 0.
  • Run a negative control before reporting any green. prove-checks owns what that requires.
  • Land a delegate's branch only in the form you were asked for. Verification finishes the work; it does not authorize merging, pushing, or opening a PR. When the form was not named, ask before the branch moves anywhere.

Ask first

  • Changes to host-wide settings in .claude/, .gemini/, or .opencode/.
  • Installer destinations or stale-file migration behavior.
  • Canonical skill content, its validators, or vendor templates.
  • Any write outside the assigned checkout or worktree.

Never

  • Put a project-specific fact into any artifact here. Everything tracked in this repository installs into every project on the host, so a repository or service name, a schema, a port, a ticket prefix or a team convention belongs in that project's own context file; this repository carries only what is explicitly useful to every project.
  • Edit installed files under $HOME as a substitute for updating this source repository.
  • Copy a path-scoped Claude rule into OpenCode's global rules.
  • Run the destructive git commands the Working Agreement lists under "Surgical Changes". In a shared checkout they destroy a parallel session's uncommitted work.
  • Write into an installed host directory. sync_context in scripts/install.sh names them: $HOME/.claude, $HOME/.codex, $HOME/.copilot, $HOME/.gemini, $HOME/.config/opencode.
  • Revert or reformat a change you cannot trace to your own brief.

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.