agentleFS
marcowuethrichmarcowuethrich/green-print/AGENTS.md

green-print

AGENTS.md1 starsChanged 17 days agoMITView on GitHub

A map and the rules an agent must not get wrong. Facts live in the docs it links (one fact, one home); this file stays short on purpose (tools/docs_check.py holds it under its line budget), because long instruction files are followed less well. Claude Code, Codex and Gemini CLI all read this file (CLAUDE.md imports it, .gemini/settings.json names it). Always: README.md and docs/README.md (the documentation map). Then only what the task touches: Conflict rule. A change that conflicts with an…

  • Deletes or force-pushes

The file

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

6 rules. About 1 is common, 4 are distinctive, and 1 is very specific to this project.

  • ≈1

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    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:

    Always: README.md and docs/README.md (the documentation map).

    line 10
  2. Distinctive:

    Decide or ask, never dangle: No menu of options at the end of a reply: ask with the question tool, or proceed on your recommendation and …

    line 32
  3. Distinctive:

    Before calling a change done, walk this list and say which entries applied:

    line 42
  4. Distinctive:

    Strings: no hard-coded user-facing text (ADR-012).

    line 47
  5. Common:

    No secrets in the repo, in prompts or in logs.

    line 63
  6. Distinctive:

    No AI attribution in commits, pull requests or comments.

    line 64

≈ “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 rules for GreenPrint

A map and the rules an agent must not get wrong. Facts live in the docs it links (one fact, one home); this file stays short on purpose (tools/docs_check.py holds it under its line budget), because long instruction files are followed less well. Claude Code, Codex and Gemini CLI all read this file (CLAUDE.md imports it, .gemini/settings.json names it).

Read before you code

Always: README.md and docs/README.md (the documentation map). Then only what the task touches:

If the task touchesRead
a feature a user seesits spec in docs/features/ (write or extend it first; never invent one speculatively)
persistence, sync, the APIdocs/architecture/overview.md (offline-first, write-through cache), ADR-002, ADR-003
UIdocs/style_guide.md, ADR-012 (strings), ADR-013 (focus)
testsdocs/testing.md
a decision, a new dependency, a moduledocs/architecture/decisions.md
how agents work here (skills, hooks, gates)docs/agentic/README.md

Conflict rule. A change that conflicts with an ADR: state the conflict and ask before going on. A decision that changes the architecture gets a new ADR in the same pull request.

Workflow

  1. Research. Map the code, check assumptions, reproduce a reported bug before fixing it.
  2. Strategy. A short plan; a written proposal when it is architectural.
  3. Execution. Plan, act, validate per sub-task. Done means run: the tests pass, the gate is clean, and you used what changed the way a user would (the app on a device, simulator, desktop or browser) and show the evidence (a screenshot, the output).
  • Decide or ask, never dangle. No menu of options at the end of a reply: ask with the question tool, or proceed on your recommendation and say so.
  • Work comes from issues. One issue, one branch, one worktree (.agents/worktrees/<slug>), one pull request that closes it. Never commit to main.
  • Delegate with intent. A lead agent plans, hands self-contained tasks to subagents, integrates and reports. Pick each subagent's model and effort by the task's hardest step (docs/agentic/README.md, Subagents).

Hit every surface

Before calling a change done, walk this list and say which entries applied:

  • Platforms: Android, iOS, Desktop (JVM), Web (Wasm); the server when the API changes.
  • Offline: works without the server, syncs when it comes back (write-through cache).
  • Reverse states: a way in needs a way out (create, edit, archive, delete, undo).
  • Accessibility: content descriptions, keyboard focus order, touch targets.
  • Strings: no hard-coded user-facing text (ADR-012).
  • Docs: fix what the change makes wrong, in that fact's one home.

Gates (zero findings, no baseline)

  • ./gradlew prePRcheck runs once before a pull request opens: ktlint, detekt, the shared, Compose UI and server tests, the Android and Wasm builds. A finding gets fixed; a suppression only at its line with the reason beside it, never a baseline or a raised threshold.
  • A docs or agent-files-only change runs python3 tools/docs_check.py instead.
  • Merge only when every check is green and every review thread is resolved; never --admin.

Guardrails

  • tools/agent_guard.py (a Claude Code PreToolUse hook) refuses destructive commands: pushes to main, force pushes, --no-verify, git reset --hard, dropping or cleaning a database. A refusal is the owner's to run by hand, never worked around.
  • No secrets in the repo, in prompts or in logs. Credentials come from a vault at run time.
  • No AI attribution in commits, pull requests or comments.

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.