ZeroSlop AGENTS.md

AGENTS.md

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

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.
• $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.