agentleFS
manavmishramanavmishra/ZeroSlop/AGENTS.md

ZeroSlop

AGENTS.md167 starsChanged 2 months agoMITView on GitHub

Guidance for AI coding agents (Claude Code, Codex, OpenCode, Warp, etc.) working in or executing this repository. For repository development, also read CLAUDE.md and follow its bounded, free-only Asana housekeeping contract. This applies across coding assistants, not only Claude. It does not apply when merely executing the portable editing skill on a user's writing, and it does not add networking to the runtime. Questions and status-only requests retain the read-only boundary in that file. A portable agent skill. The runtime…

  • 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 repository3 other files it gives its agents.

The file

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

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

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

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

    Read SKILL.md fully; it routes you to references/ by genre and task.

    line 24
  2. Very specific:

    Run the scorer when python3 exists: python3 scripts/slopscore.py --explain <file> (or stdin).

    line 25
  3. Very specific:

    No trained model ships. One was built and cut for being confidently wrong on current-era text.

    line 42
  4. Distinctive:

    Do not reintroduce a trained channel without a transfer test on drafts from the model generation users actually face.

    line 44
  5. Very specific:

    Every regex must compile under Python re AND stay JS-compatible where possible (the data files are consumed as inert JSON by other tooling).

    line 98
  6. Very specific:

    Run the validation used in CI before publishing: python3 -c "import json.

    line 100

≈ “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

AGENTS.md

Guidance for AI coding agents (Claude Code, Codex, OpenCode, Warp, etc.) working in or executing this repository.

Development coordination

For repository development, also read CLAUDE.md and follow its bounded, free-only Asana housekeeping contract. This applies across coding assistants, not only Claude. It does not apply when merely executing the portable editing skill on a user's writing, and it does not add networking to the runtime. Questions and status-only requests retain the read-only boundary in that file.

What this repo is

A portable agent skill. The runtime artifact is SKILL.md (YAML frontmatter

  • the detect → rewrite → verify → learn loop). scripts/slopscore.py is an optional heuristic surface scorer — stdlib-only Python, offline, read-only. There is no build step. Keep all wording harness-neutral: Claude Code and Codex are examples, not limits.

Executing the skill

  1. Read SKILL.md fully; it routes you to references/ by genre and task.
  2. Run the scorer when python3 exists: python3 scripts/slopscore.py --explain <file> (or stdin). If python3 is unavailable, degrade gracefully: skip the metered gate, use references/tells.md + references/overcorrection.md and the self-rubric in SKILL.md step 4 as the gate. Never fail the task because the scorer can't run.
  3. The hard rules in SKILL.md (no fabrication — including interior-experience claims; flag hollow spans; no over-correction) are non-negotiable in every harness.

Key files

  • SKILL.md — source of truth for behavior.
  • data/patterns.json + data/learned.json — the weighted tell database; reviewed shared rules merge over base at runtime. Private online learning lives under $ZERO_SLOP_HOME (default ~/.zero-slop) and loads last, so an install or update never overwrites it. data/learned-log.md is the dated log of reviewed shared taxonomy changes.
  • No trained model ships. One was built and cut for being confidently wrong on current-era text; references/evidence.md documents that negative result. Do not reintroduce a trained channel without a transfer test on drafts from the model generation users actually face.
  • scripts/contextual.py is a maintainer-only release-research tool. It prepares and validates source-bound host-model reviews, never calls a model, and never changes production output or the surface score. It is deliberately excluded from the packaged skill; Zero Slop has one production workflow and no runtime feature switch.
  • scripts/learn.py --guide --for <draft> retrieves reason-labelled private fix preferences. Retrieval is advisory lexical coverage, not a probability, and must abstain when no relevant evidence exists.
  • scripts/reader_review.py prepares source-and-audience-bound passage packets and escaped standalone reports for optional audience reviews. It performs no inference, networking, or file writes. references/reader-review.md owns the host workflow: simulated reactions are hypotheses, context isolation is a harness responsibility, and reader feedback never trains private preferences or changes the score without a person's explicit approval through the normal editing/learning path. It adds no calls to the hosted editing pipeline.
  • $ZERO_SLOP_HOME/voices/ — private named scoring profiles, outside the repository. The sample-based builder records an existing lexicon or rider term after one exact word match. It does not store the sample or model the writer's full style, and the profile has no effect unless selected with --voice NAME. Never commit these profiles.
  • $ZERO_SLOP_HOME/notes.json — a run counter and one boolean, so the single GitHub-star note can be shown once and never again. It records no text, no scores, no paths and no identifiers, is never sent anywhere, and the note is suppressed entirely by ZERO_SLOP_NO_NOTES=1, by --json, --batch or --gate, and by any run whose stdout is not a terminal.
  • bench/ (if present) — reproducible benchmark harness and scorecard.
  • website/ is a retained, testable snapshot, not the source of the live site. Its deploy command intentionally refuses. The live site at zero-slop.ai is built from github.com/manavmishra/ZSWebpage; make and deploy site changes there. Do not remove the refusal guard or deploy this snapshot to zero-slop.ai. Identify production by its domain, not its palette: the colour named here went stale the day the site was repainted.

Maintenance contract

  • Reviewed shared tells go in data/learned.json with a dated line in data/learned-log.md. Private reflect-loop tells and false-positive overrides stay under $ZERO_SLOP_HOME; never copy them into the repository without the explicit export, review, and merge path.
  • package.json is the release version. SKILL.md, README.md, .claude-plugin/plugin.json, .codex-plugin/plugin.json, plugin.json, gemini-extension.json, and server.json bump with it. Run python3 scripts/check_distribution_manifests.py before publishing.
  • A packaged runtime change requires a new version. After validation passes on main, sync-release.yml creates the matching tag and dispatches the GitHub release and official MCP Registry jobs. npm publishes from the same commit. The separate website repository then imports and verifies that release; its hourly reconciliation is the no-secret recovery path.
  • package.json publishes the skill to npm for registry discovery. Its files allowlist must ship exactly what scripts/build_plugin.py mirrors into skills/zero-slop/ — same runtime, same exclusions. When you add or remove a maintainer-only script, update EXCLUDE and the ! negations together, then confirm with npm pack --dry-run.
  • Every regex must compile under Python re AND stay JS-compatible where possible (the data files are consumed as inert JSON by other tooling).
  • Run the validation used in CI before publishing: python3 -c "import json; json.load(open('data/patterns.json'))" and the scorer smoke test in .github/workflows/validate.yml.
  • Security posture in SECURITY.md is a contract. Runtime scripts never transmit drafts; the optional version check is the sole metadata request. Runtime writes are limited to explicit outputs, $ZERO_SLOP_HOME, and the maintainer-only shared merge/calibration paths. Do not add eval, exec, pickle, or subprocess execution to runtime scripts.
  • Corpora are admitted by bench/corpus-registry.json. Match every evaluation to the semantics of its labels; provenance corpora never become slop-quality accuracy by proxy.

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.