merlon
AGENTS.md20 starsChanged 41 days agoMITView on GitHub
Instructions for coding agents in this repository. CLAUDE.md is a symlink to this file, and every agent reads the same text. This is the Merlon Docs monorepo: a documentation-system Agent Skill plus a TypeScript toolchain in pnpm workspaces. The application is the merlon CLI in packages/merlon-docs-cli, built on packages/merlon-docs-core and driven through pnpm scripts. The repository deploys no server, only the static docs site. Locally, pnpm site:dev serves that site. Documentation is sharded under docs/. Shards are the source of…
- Installs packages
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.
- skill-creatorSkill
- writing-skillsSkill
- merlon-docsSkill
The file
We split this AGENTS.md into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
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
- Very specific: line 19
Run pnpm build after a fresh checkout and after editing packages/*/src, before any docs script or CLI command.
≈ “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.
Files
AGENTS.md
Instructions for coding agents in this repository. CLAUDE.md is a symlink to this file, and every agent reads the same text.
Project
This is the Merlon Docs monorepo: a documentation-system Agent Skill plus a TypeScript toolchain in pnpm workspaces. The application is the merlon CLI in packages/merlon-docs-cli, built on packages/merlon-docs-core and driven through pnpm scripts. The repository deploys no server, only the static docs site. Locally, pnpm site:dev serves that site.
Shard discipline (critical)
Documentation is sharded under docs/. Shards are the source of truth and compiled output is generated. Never hand-edit compiled files. Edit the source shard under docs/ and run pnpm docs:compile:repo. A file with <!-- merlon-shard: start ... --> markers is compiled output, and each marker gives the path of its source shard. Guide directories lists every compiled output and its shard directory. CI recompiles every guide and fails when git diff shows a stale compiled file.
Compile and check vs review: merlon compile (via docs:compile:repo) stitches shards into compiled guides so humans can review fewer, fuller files. merlon check (via docs:check) validates the documentation system — compile output, cross-links, orphans, optional lint — not whether product documentation is accurate. Factual quality comes from following the Merlon Docs skill (update shards with the code, current-docs-only) and from human review in pull requests. See Documentation and software reliability.
Text vs canvas: This repository's Merlon Docs tree is textual (Markdown shards). Diagrams and screenshots belong in insert libraries (figures/, diagrams/, etc.) and compile into guides via inline inserts. To edit canvas-native files (Excalidraw, Figma, …) in an agent session, enable the appropriate MCP; use shards as the durable source for names and intent, and keep exports in git so merlon check can link them. See Text-first content and canvas tools.
Before you run anything
Run pnpm build after a fresh checkout and after editing packages/*/src, before any docs script or CLI command. First-time bootstrap has the rest of the setup, and Requirements lists the toolchain, including Vale for the docs checks and Java for the formal models.
Commands
pnpm install # dependencies (packageManager is pinned in package.json)
pnpm build # build every package
pnpm test # unit tests
pnpm typecheck
pnpm lint
pnpm format:check
pnpm docs:compile:repo # recompile every compiled output
pnpm docs:check # compile and check the repo docs and the examples
pnpm run check # typecheck, lint, format:check, build, test, skill:validate, docs:check
pnpm formal:check # the Alloy models in formal/alloy/Local setup says how CI's checks differ from pnpm run check.
Tests
A test runs our code on input it controls and checks what our code does. Never write a test that checks a committed file's text, a value that changes by design (our package versions, dates, host paths), another tool's output, that a script merely runs, or the shape of the code. What a test checks explains each case.
Pull requests and hooks
Open every pull request as a draft, and mark it ready once, when the work is done. CI skips drafts, as Pull requests explains. The pre-commit hook runs fast offline checks, and the pre-push hook runs the full gate. Git hooks lists what each one runs.
Issues, labels, and the public roadmap
Work is tracked in GitHub, not in ad-hoc markdown backlogs.
| Surface | URL |
| Issues | https://github.com/Merlon-Docs/merlon/issues |
| Public roadmap (Project) | https://github.com/orgs/Merlon-Docs/projects/1 |
Release PR (develop → main) | https://github.com/Merlon-Docs/merlon/pulls |
Before you edit code for a scoped task, load a WORK_ITEM (issue number or URL) and follow Agent work-item tracking. When you open or first touch an issue, complete New issue intake: one priority:* label, type/component labels, a track:* label when the roadmap area is clear, Status on the org project board, and a milestone when the issue belongs to the current delivery cut.
During a release window, keep only the develop → main release PR open; close or land other pull requests so review and CI focus on that train. Dependabot stacks can be closed and refreshed on develop after the release lands.
Maintainers with project scope on gh can backfill board items with node scripts/populate-github-project.mjs --open-only. Agents without project scope should still fix labels and leave a comment if an issue is missing from the board.
Developer guides
- Versioning and releases covers how work reaches
developand how releases reachmain. - Formal models lists the guards that keep both branches tested.
- Agent Skill development covers skill source under
skills/, and why.agents/skills/is never hand-edited. - Cloud agent environments covers cloud agent setup and limits.
Code of conduct
This project follows the Contributor Covenant Code of Conduct.
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
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.

