agents-md-kit

Canonical AGENTS.md templates for Paperclip agent roles, with drift-guard verbatim markers that pair with the agents-md-lint tool (PLA-15 deliverable; final home TBD).

This repository is a Paperclip extension (per upstream CONTRIBUTING.md: "If the idea fits as an extension, prefer building it with the plugin system"). It is not part of paperclipai/paperclip core. Operators clone or copy from it at agent-author time.

What's inside

File	Role	When to use
templates/Coder.md	IC software engineer	Hiring an engineer agent
templates/QA.md	IC QA / verification engineer	Hiring a QA agent
templates/CTO.md	Engineering manager	Hiring a manager agent
templates/UXDesigner.md	IC product designer	Hiring a designer agent
templates/SecurityEngineer.md	IC security engineer	Hiring a security agent
templates/_authoring-guide.md	Reference	How to add a template, what the verbatim markers mean

Every template carries <!-- lint:verbatim:start --> … <!-- lint:verbatim:end --> blocks around the canonical execution contract, safety preamble, and heartbeat-exit instruction. agents-md-lint's rule AM402 verifies these regions appear byte-for-byte in any live AGENTS.md derived from the template.

Install

There are three supported install paths. Pick the one that matches your workflow.

1. One-shot copy (recommended for new hires)

# From your agent-config repo, where AGENTS.md will live:
curl -sSL https://raw.githubusercontent.com/claudegoogl-sudo/agents-md-kit/main/scripts/install.sh \
  | bash -s -- --role Coder --agent-name MyEngineer --company Acme --manager-title CTO --issue-prefix ACM

This downloads templates/Coder.md, fills the placeholders, and writes AGENTS.md in the current directory.

2. Git clone (for repeated authoring or CI use)

git clone https://github.com/claudegoogl-sudo/agents-md-kit.git
cp agents-md-kit/templates/Coder.md AGENTS.md
sed -i \
  -e 's/{{agentName}}/MyEngineer/g' \
  -e 's/{{companyName}}/Acme/g' \
  -e 's/{{managerTitle}}/CTO/g' \
  -e 's/{{issuePrefix}}/ACM/g' \
  AGENTS.md

3. Reference from paperclip-create-agent skill

The paperclip-create-agent skill points at this repo's templates/ directory. When using the skill to draft a hire, reference the template by raw URL, e.g.:

https://raw.githubusercontent.com/claudegoogl-sudo/agents-md-kit/main/templates/Coder.md

Verifying drift

Install agents-md-lint (PLA-15 deliverable) and run:

# Pre-hire check: verify your draft passes against the canonical template
agents-md-lint --against-template path/to/agents-md-kit/templates/Coder.md ./AGENTS.md

# CI: lint every live AGENTS.md against its matching template at once
agents-md-lint --kit path/to/agents-md-kit/templates/

AM402 fires if any verbatim region drifts. AM001 fires if a required section is missing. See templates/_authoring-guide.md for the full diagnostic table.

Versioning

This kit is versioned via git tags (v0.1.0, etc.). Pin to a tag in CI to keep the lint reproducible:

git clone --branch v0.1.0 https://github.com/claudegoogl-sudo/agents-md-kit.git

Contributing

1. Edit a template in templates/ (don't touch text inside <!-- lint:verbatim:start --> blocks unless you intend to bump the canonical contract).
2. If you change a verbatim region, you must update every live AGENTS.md derived from that template in the same release.
3. Add the rationale to CHANGELOG.md.
4. Open a PR; CTO sign-off required for any verbatim-region change.

See templates/_authoring-guide.md for the full authoring rules.

License

MIT — see LICENSE.

Provenance

• Restructured from PR paperclipai/paperclip#5000 per CEO Path-C decision in PLA-211.
• Tracked under PLA-212.
• Pairs with the lint tool from PLA-15.