Working with agents

Amiss meets coding agents in two directions: as the gate an agent runs into, and as a check the agent runs itself before pushing.

The failing gate

When a pull request fails, everything the agent needs travels with the failure. Annotations point to introduced Fixes. Grouped Checks and pre-existing inventory stay in the job summary and report, and the exact finding and error rows carry their fixed descriptions. Even a rejected invocation teaches: it prints the closed grammar on stderr, so an agent with no book at hand can construct a working command from the refusal alone.

Check before pushing

Tell your repository’s agents to scan before they push. The staged loop works from a linked worktree too, reading that worktree’s own index, so agents running in worktree isolation keep the same gate. If the repository keeps an AGENTS.md, paste this section into it. A repository that keeps a CLAUDE.md instead takes the same block there, or bridges the two the way this repository does, with a CLAUDE.md whose whole body is @AGENTS.md. That line is an import, and the check reads it as a reference: a @path line alone in a CLAUDE.md, CLAUDE.local.md or GEMINI.md names the file beside it that Claude Code or Gemini CLI loads, so renaming AGENTS.md breaks it visibly instead of leaving the agent without its instructions. Rule files in .cursor/rules are read once a policy include binds them, {"kind": "tree", "path": ".cursor/rules", "suffix": ".mdc", "adapter": "markdown"}. The block to paste:

## Documentation checks

This repository gates documentation drift with Amiss
(https://hardmax71.github.io/amiss/). After changing documentation, or code that
documentation points at, stage the change and check the staged state before committing:

    git add -A
    amiss check --repo . --object-format sha1 \
      --base "$(git rev-parse HEAD)" --index --profile enforce-introduced --format json

Exit 0 passes. Exit 1 blocks: the blocking rows are `errors[]` and the findings whose
`effective_disposition` is `fail`; each row's `description` says what it means and how
to fix it, and `location` names the exact source position. A finding with a `fix`
carries a proven edit, and `amiss fix` with the same arguments minus `--format` applies
every one; stage the result and check again. Exit 2 means the run itself could not be
trusted, and the error rows say why. If CI passes `--repository`, `--ref` and
`--default-branch-ref`, pass the same three here, or URLs into this repository's own
files go unchecked. Fix what the row points at; never weaken
`.amiss/scanner-policy.json` to silence a finding, and leave `.amiss/router.yml` to a
maintainer, since it states which router publishes the tree.

The block assumes the binary is installed, by cargo install --locked amiss or a release binary as in Quickstart; pin the version your CI pins.

Scheduled repair

GitHub’s agentic workflows run coding agents inside Actions and describe themselves as augmenting deterministic CI rather than replacing it. Amiss is the deterministic half of that pairing: it finds drift and refuses to guess, and an agent repairs what it found. A starting recipe lives at integrations/gh-aw/docs-drift-fix.md. Copied into .github/workflows/ and compiled with the gh aw extension, it runs the scan on a schedule and reads the report. What it can prove it repairs, and the pull request it opens passes back through the same gate it started from. Findings that carry a fix hand the agent the exact edit: the document, the byte span, and the replacement text, already proven against the grammar that will re-check them.

Claude Code

This repository doubles as a Claude Code plugin marketplace. One command registers it:

/plugin marketplace add HardMax71/amiss

Installing the amiss plugin from that marketplace adds a skill that knows the invocation grammar, the exit classes, and the fix loop; its text is maintained at integrations/claude. It also adds a hook the agent cannot skip: before any shell command that commits, the staged check runs under enforce-introduced, and a blocking or untrusted result stops the commit and hands the report back to the agent, which is how Claude Code’s hooks refuse a tool call. A repository with no commit yet, or a machine without amiss on its path, commits unchecked, and the hook says so.

Codex, Copilot and other skill readers

The skill is a plain Agent Skills directory: one SKILL.md whose frontmatter names the skill and says when to use it, so an agent that reads that layout loads it without the plugin. Codex looks in .agents/skills from the working directory up to the repository root, and Copilot reads .agents/skills, .github/skills and .claude/skills. Copy the directory into one of them from the release your CI pins:

mkdir -p .agents/skills/amiss
curl -fsSL -o .agents/skills/amiss/SKILL.md \
  "https://raw.githubusercontent.com/HardMax71/amiss/v<reviewed-version>/integrations/claude/skills/amiss/SKILL.md"

Replace <reviewed-version> with the release you reviewed, the same one the check runs. The commit hook stays Claude Code’s own, so under another agent the pre-commit hook in Running it in CI is the gate the agent cannot skip.

Keyboard shortcuts