Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
99 lines (79 loc) · 4.72 KB

CONTRIBUTING.md

File metadata and controls

99 lines (79 loc) · 4.72 KB
Raw

Contributing

Thanks for the interest. agentmats is partly bot-maintained, partly human — here's how the split works so you know where to land.

Who owns what

Area Owner
New release content for an existing agent (commands, flags, config keys) Bot — daily auto-PR per agent, self-merges on a clean review (see AGENTS.md)
Bug fixes (broken layout, typos, dead links) Humans
Design / CSS / accessibility / responsive tweaks Humans
Style guide changes and structural rework Humans
Content corrections to existing entries Either — PRs welcome
New version snapshots into versions/ Bot at release; humans for historical
Adding a new agent placemat Humans — see below

Each agent has its own daily sync routine (claude-code, codex, kimi-code, hermes, antigravity), staggered 15 minutes apart. A clean bot PR passes its own code-reviewer pass and squash-merges itself within minutes, so you'll usually find the change already on main rather than sitting as an open PR. If a bot run is about to make the same change you're planning and its PR is still open — meaning its review pass flagged something — comment there instead of opening a duplicate.

Ground rules

Before opening a PR, skim AGENTS.md — the Style Guide and Content Rules sections are short and they're what reviewers check against. Key points:

  • Verified content only. New commands/flags must be backed by that agent's official docs, changelog, or --help output. Anything not yet confirmed goes in with class="unverified".
  • Never truncate code with .... Show the full flag/path.
  • Don't edit versions/*.html. Those are frozen snapshots, ever.
  • Don't hand-edit changes.json or feed.xml. They're generated by scripts/build-changes.js.
  • No external dependencies. Everything is self-hosted, no build step.
  • Touch one agent directory per PR (sync PRs especially) — cross-agent changes make review and revert harder.

Adding an agent

A new placemat is the highest-risk contribution here, because the cheapest way to fill a card is to copy a neighbour's — and that's exactly how a past Antigravity attempt shipped fabricated rows (see AGENTS.md's "Adding a new agent" section for the full story).

Before writing a line of HTML:

  1. Read AGENTS.md § Adding a new agent in full. The rule that matters most: source every card from that agent's own vendor reference, never from a sibling placemat.
  2. Extract an inventory first. Build <agent>/sources.json's inventory block — the real slash commands, settings keys, and hook events, each with a source URL and fetched date — from the vendor's published reference. The test suite checks every row you write against this inventory, so fabricated content fails CI instead of review.
  3. Only then build the eight canonical cards (card-keys, card-slash-core, card-slash-tools, card-cli, card-settings, card-env, card-skills, card-hooks) and the Rosetta table row for the new agent, marking anything you couldn't verify against the reference as unverified.
  4. Open a new-agent-request issue first if you haven't already — it's where we track the vendor reference URL and agree the agent is in scope.

Checks every PR must pass

node tests/placemat.test.js               # structural suite + inventory gate
node scripts/build-changes.js --all --check   # generated files are fresh

CI also runs HTML validation (html5validator) over every page except versions/. Please get these green locally before requesting review — CI runs the same three checks and is the gate for merge on human PRs. Bot PRs carry an additional gate: a code-reviewer subagent pass over the diff (see AGENTS.md) that must come back clean before the routine merges its own PR.

Workflow

  1. Open an issue first for non-trivial changes — design rework, new sections, a new agent, or anything that touches an auto-update pipeline.
  2. Fork, branch from main, keep changes scoped to one concern (and one agent directory, for content changes) per PR.
  3. Test locally: python3 -m http.server 8000 and click through.
  4. Run the checks above.
  5. PR against main using the PR template's checklist.

Reporting issues

  • Bugs / broken behavior → use the Bug report template
  • Wrong or outdated entry → use the Content correction template
  • Missing agent → use the New agent request template
  • Security → see SECURITY.md, do not file publicly

Code of Conduct

Participation is governed by the Code of Conduct.