AGENTS.md git:20260609.002eb29A

Immutable. This exact content is served forever at /api/v1/blob/8895b75bb71bedcd.

# Agent Instructions

## Scope

- Repository: `axiom`.
- Product: Claude Code plugin marketplace.
- Marketplace catalog: `.claude-plugin/marketplace.json`.
- Plugins live under `plugins/<plugin>`. Do not assume a default current plugin;
  infer the relevant plugin from the user request or changed files.
- Claude compatibility file: `CLAUDE.md` imports this file.

## Repository Map

```text
.claude-plugin/marketplace.json
plugins/<plugin>/.claude-plugin/plugin.json
plugins/<plugin>/README.md
plugins/<plugin>/CHANGELOG.md
plugins/<plugin>/package.json
plugins/<plugin>/release.config.js
plugins/<plugin>/skills/<skill>/SKILL.md
plugins/<plugin>/skills/<skill>/evals/evals.json
plugins/<plugin>/skills/<skill>/reference.md
dev/<plugin>/
.github/workflows/
.github/scripts/
package.json
package-lock.json
```

## Canonical Sources

- `.claude-plugin/marketplace.json` owns marketplace plugin order, plugin names,
  plugin descriptions, categories, and `source: "./plugins/<plugin>"`.
- `plugins/<plugin>/.claude-plugin/plugin.json` owns shipped plugin manifest
  metadata. Semantic-release owns its `version`.
- `plugins/<plugin>/README.md` owns plugin-level docs and must include a
  non-empty `## Eval history` section.
- `plugins/<plugin>/skills/<skill>/evals/evals.json` owns shipped eval scenario
  coverage for that skill.
- `dev/<plugin>/` owns eval run output, grading artifacts, benchmark workspaces,
  and other non-shipped eval data.
- The root `README.md` is partly generated from the sources above. Do not treat
  generated root README content as canonical data.

## Edit Rules

- Keep plugin names, skill names, and directories lowercase kebab-case.
- Use directory-format skills only: `skills/<skill>/SKILL.md`.
- Register each plugin in `.claude-plugin/marketplace.json` with
  `source: "./plugins/<plugin>"`.
- Treat `package.json` and `package-lock.json` as release and lint tooling only.
  Shipped plugins must not depend on root npm packages at runtime.
- Do not hand-edit `plugins/<plugin>/.claude-plugin/plugin.json` `version`.
- Do not hand-edit `plugins/<plugin>/CHANGELOG.md`.
- Semantic-release owns plugin version bumps, changelog entries, tags, and
  GitHub Releases.
- Do not modify `dev/` or `plugins/` unless the user explicitly asks. Read them
  only as needed for validation, packaging context, or release wiring.
- Ignore local scratch unless explicitly requested:
  `.DS_Store`, `*.local.md`, `.claude/settings.local.json`, `.claude/plans/`,
  `DEMO-file-example-spec.md`, `DEMO-skill-creator-evals.md`,
  `skill-evals-showcase.html`, and `what-is-a-skill.png`.
- Keep eval run output under `dev/<plugin>/`. Do not move eval run data into a
  shipped plugin directory.
- Do not hand-edit generated root `README.md` regions. Update their canonical
  sources, then run `npm run docs:readme`.

## Generated README Regions

The root `README.md` has three generated marker blocks:

- `plugin-badges`: generated by `.github/scripts/sync-readme-badges.mjs` from
  `.claude-plugin/marketplace.json` and plugin manifests.
- `eval-index`: generated by `.github/scripts/sync-readme-evals.mjs` from
  marketplace entries, shipped skill eval manifests, and plugin README eval
  history sections.
- `plugin-list`: generated by `.github/scripts/sync-readme-plugins.mjs` from
  marketplace entries and plugin manifests.

Use these commands for generated README work:

```bash
npm run docs:readme
```

```bash
npm run docs:readme:check
```

If a generated block is wrong, fix the source data or generator. Do not patch
the generated block directly.

## Adding A Plugin

When adding a shipped plugin:

- Create `plugins/<plugin>/` using lowercase kebab-case.
- Add `plugins/<plugin>/.claude-plugin/plugin.json`; do not hand-edit
  `version` after creation.
- Add `plugins/<plugin>/README.md` with a non-empty `## Eval history` section.
- Add at least one directory-format skill under
  `plugins/<plugin>/skills/<skill>/SKILL.md`.
- Add shipped eval coverage under
  `plugins/<plugin>/skills/<skill>/evals/evals.json`.
- Put eval run output, grading, and benchmarks under `dev/<plugin>/`, not under
  `plugins/<plugin>/`.
- Register the plugin in `.claude-plugin/marketplace.json`; marketplace order is
  root README display order.
- Run `npm run docs:readme` after changing marketplace entries, plugin
  manifests, plugin READMEs, or shipped eval manifests.

## Release Inputs

- PR source branch names must be `feat/<short-kebab-slug>`,
  `fix/<short-kebab-slug>`, or `chore/<short-kebab-slug>`. Dependabot branches
  under `dependabot/**` are allowed automation. The `Branch name` PR check
  enforces this.
- PR squash commit title must be a valid Conventional Commit.
- Version impact:
    - `feat:` gives a minor release.
    - `fix:` and `perf:` give a patch release.
    - `feat!:` or a `BREAKING CHANGE:` footer gives a major release.
    - `chore:`, `ci:`, `docs:`, `refactor:`, `test:`, `style:`, and `build:` do
    not release.
- The type is the header prefix (stock Conventional Commits) — nothing precedes
  it. A gitmoji, if used, goes immediately after the colon as the start of the
  subject (`feat(scope): ✨ subject`), never before the type (`✨ feat:`). The
  `Conventional Commit title` PR check enforces this.

## Validation

Run the smallest relevant check set for the files changed.

For generated root README blocks:

```bash
npm run docs:readme:check
```

For branch-name convention changes or local testing of a branch name:

```bash
PR_BRANCH=chore/example-slug npm run check:branch-name
```

For JavaScript tooling changes:

```bash
npm run lint
```

```bash
npm run lint:fix
```

For marketplace entries, shipped plugin layout, skill directories, or shipped
eval manifests:

```bash
npm run check:repo
```

For plugin manifest or shipped plugin structure changes, validate the specific
plugin. If multiple shipped plugins changed, run `npm run check:plugins:local`
instead.

```bash
claude plugin validate ./plugins/<plugin>
```

For workflow, Dependabot, pre-commit, or repository YAML changes:

```bash
npm run lint:yaml
```

For GitHub Actions or pre-commit security hook changes:

```bash
npm run check:precommit:security
```

For spelling-sensitive docs/config changes:

```bash
npm run lint:spelling
```

For Markdown edits that add or change links:

```bash
npm run lint:links
```

For broad pre-commit parity before handing off a cross-cutting change:

```bash
npx prek run --all-files
```

For Markdown edits, run the targeted Markdown quality pass in
[Markdown Rules](#markdown-rules).

```bash
npx -y markdownlint-cli2 --fix path/to/file.md
```

## Markdown Rules

- Every fenced code block must include an explicit language tag.
- Use `text` for plain output, logs, paths, directory trees, errors, and
  unstructured snippets.
- For nested fenced code blocks, the outer fence must use more backticks than
  the deepest inner fence.
- After editing Markdown, run a targeted quality pass on the edited files:

```bash
npx -y markdown-table-formatter path/to/file.md
```

```bash
npx -y markdownlint-cli2 --fix path/to/file.md
```

- If `npx` cannot write to its cache, rerun the failed command with a temp
  cache:

```bash
npm_config_cache=/private/tmp/codex-npm-cache npx -y markdownlint-cli2 --fix path/to/file.md
```

- Inspect the targeted Markdown diff after formatting:

```bash
git diff -- path/to/file.md
```

- Quote markdownlint-cli2 globs.
- Negate markdownlint-cli2 globs with `#`, not `!`.
- Use explicit file paths for targeted Markdown fixes.
- Do not rewrite unrelated Markdown sections to satisfy unrelated lint findings.