agents-md-facts

Author a minimal AGENTS.md from your repo’s facts. Never guessed.

Hand-written agent files rot. LLM-written ones often bloat and can reduce task success (Gloaguen et al., 2026). This tool authors only what the tree declares — real build/test commands, entry points, toolchain conventions. Nothing invented. Nothing padded.

Use

npx agents-md-facts            # author/refresh AGENTS.md (non-destructive; skip write if facts unchanged)
npx agents-md-facts --check    # exit 1 if missing or stale
npx agents-md-facts --dry-run  # print plan; write nothing
npx agents-md-facts --stdout   # emit managed block to stdout

Refresh only the block between:

<!-- agents:from-facts:start --> … <!-- agents:from-facts:end -->

Everything you write outside those markers is preserved.

What it authors

Orientation · setup & build · tests · where things live · conventions · guardrails · definition of done · security (if secrets files exist) · commit & PR.

Every line is a detected fact or a curated default. If it resolves no ambiguity, it is dropped.

Examples (exact tool output): examples/ — Node/TS, Python, Rust, Go.

This repo dogfoods itself: see root AGENTS.md.

CI

Fail the build when AGENTS.md drifts from the repo:

# .github/workflows/agents-md.yml
- uses: Wolfe-Jam/[email protected]

Or: npx agents-md-facts --check.

Pre-commit hook

Catch stale AGENTS.md before it lands:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/Wolfe-Jam/agents-md-facts
    rev: v0.1.0
    hooks:
      - id: agents-md-facts

Then: pre-commit install.

Ladder

BETTER on main. Short model: docs/BETTER-BEST.md.

Develop

Requires Bun.

bun install
bun test
bun run lint
bunx tsc --noEmit
bun run src/cli.ts          # refresh this repo’s AGENTS.md

See CONTRIBUTING.md. Security: SECURITY.md.

Citation

AGENTS.md is how to work in a repo. .fafa is who the agent is. Complementary, not competing.

Wolfe, J. (2026). Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era. Zenodo. https://doi.org/10.5281/zenodo.21951641

License

MIT © James Wolfe · Built on the open AGENTS.md standard.

Optional depth on facts-driven project DNA: faf.one/agents

---

⭐ Bookmarks it for you, helps other devs find it too.