AGENTS.md

1# AGENTS.md
2 
3> Guidance for AI coding agents working on **this** repo (agents-md, the AGENTS.md generator).
4> Read this first. Verify live state (read the code) before changing anything. Meta-note: this
5> file is also a live example of what the tool produces.
6 
7<!-- agents-md:begin id=overview -->
8## Overview
9`agents-md` generates and safely maintains an `AGENTS.md` (the cross-tool standard for AI coding
10agents) for any repository. It ships two ways from one repo: a **zero-dependency Node CLI**
11(`bin/agents-md.js`, run via `npx`) and a **Claude Code skill** (`SKILL.md`). Both write the same
12AGENTS.md and obey the same safe-marker contract. No runtime dependencies; Node >= 16.
13<!-- agents-md:end id=overview -->
14 
15<!-- agents-md:begin id=commands -->
16## Commands
17- Run the CLI locally: `node bin/agents-md.js` (in any target repo)
18- Try it end to end: `npx github:eugeniughelbur/agents-md`
19- Help / dry run: `node bin/agents-md.js --help` · `--dry-run`
20- No build, no install, no tests yet (_TBD: add a test harness with fixture repos_).
21<!-- agents-md:end id=commands -->
22 
23<!-- agents-md:begin id=testing -->
24## Testing
25Manual for now: run the CLI against a throwaway repo (`git init` + a `package.json`) and verify
26the three write modes (create, marker-update, no-clobber sidecar). _TBD: automate with fixtures._
27<!-- agents-md:end id=testing -->
28 
29<!-- agents-md:begin id=structure -->
30## Project structure
31- `bin/agents-md.js` — the CLI (detect facts → build sections → safe write → symlink CLAUDE.md)
32- `SKILL.md` — the Claude Code skill (LLM-powered variant; same contract)
33- `templates/AGENTS.template.md` — the section skeleton with markers
34- `README.md`, `llms.txt`, `docs/` — docs + discoverability surface
35<!-- agents-md:end id=structure -->
36 
37<!-- agents-md:begin id=conventions -->
38## Code style & conventions
39- **Zero runtime dependencies.** Use only Node built-ins (`fs`, `path`, `child_process`). This is
40  a trust + portability promise; do not add npm deps to the CLI.
41- CommonJS, Node >= 16. Keep the CLI a single readable file.
42- Keep the CLI (deterministic) and the SKILL.md (LLM) in sync on the **marker contract** and the
43  section list.
44<!-- agents-md:end id=conventions -->
45 
46<!-- agents-md:begin id=git -->
47## Git & PR workflow
48Default branch `master`. Public repo `eugeniughelbur/agents-md`. GitHub Pages serves `/docs`.
49Conventional, descriptive commits.
50<!-- agents-md:end id=git -->
51 
52<!-- agents-md:begin id=gotchas -->
53## Gotchas & hard-won lessons
54- The marker regex must escape the HTML-comment markers; a bad regex would corrupt user files.
55- **Never** widen the write logic to overwrite a markerless `AGENTS.md` — the no-clobber sidecar
56  is the product's core promise. Breaking it breaks trust.
57- `CLAUDE.md` symlink is intentional: Claude Code does not read `AGENTS.md` natively (as of 2026).
58<!-- agents-md:end id=gotchas -->
59 
60<!-- agents-md:begin id=security -->
61## Security & secrets
62The tool reads repo metadata only and `.env.example` (never real `.env` values), and never writes
63secrets into the generated file. No network calls, no telemetry. Keep it that way.
64<!-- agents-md:end id=security -->
65 
66<!-- agents-md:begin id=boundaries -->
67## Boundaries
68- ✅ **Always**: keep the CLI zero-dependency; keep CLI and skill in sync; test the three write modes before pushing.
69- ⚠️ **Ask first**: changing the marker syntax (it is a compatibility contract with already-generated files); changing the default section set.
70- 🚫 **Never**: overwrite a handwritten (markerless) AGENTS.md; add runtime npm dependencies; make network calls or add telemetry; commit secrets.
71<!-- agents-md:end id=boundaries -->
72 
73## Notes
74<!-- Human-owned. Never touched by re-runs of agents-md. -->
75- This repo is both the tool and its own first user. Dogfood changes here before shipping.
76 
77---
78<!-- Generated/maintained by agents-md (https://github.com/eugeniughelbur/agents-md).
79     Content INSIDE agents-md:begin/end markers is regenerated on re-run; everything outside is preserved. -->
80