---
name: instructions-author
description: >
  Use when creating or revising an apm instructions file
  (`.apm/instructions/*.instructions.md`). Not read-only review ->
  `factory-audit`. Not skills -> `skill-author`. Not agents -> `agent-author`.
  Not AGENTS.md -> `agentsmd-author`.
compatibility: Requires the apm CLI; behaviour verified against apm 0.28.0.
allowed-tools: Bash Read Write Edit
metadata:
  version: "0.1.0"
  category: factory
  source_keys:
    - apm-docs-site
    - apm-cli-0-28-0-experiments
    - claude-code-memory-docs
---

## Gotchas

- Claude Code drops `description`; only Copilot and Cursor keep it. Write a body that explains itself.
- Quote every `applyTo`. An unquoted `**/*.py` fails to parse, compile skips the file, and `apm install` still deploys it with no `paths:`, so it loads in every session and nothing errors.
- `apm compile --validate` always exits 0 and hides the missing-`description`, missing-`applyTo` and empty-body warnings. It is not a lint gate.
- Once rules sit in `.claude/rules/`, `apm compile --target claude` writes no `CLAUDE.md` and still exits 0; an exit-code check verifies nothing.
- A source must be flat in `.apm/instructions/` and end `.instructions.md`; anything else is ignored or never installed.

## Step 1 — Dispatch

| Condition | Flow | Reference |
|---|---|---|
| No file at the target path | Create | `references/create.md` |
| A file exists, at least one improvement signal present | Improve | `references/improve.md` |
| A file exists, no signals | Stop and ask | — |

Signals: grill output, audit findings, inline feedback, a session describing a rule that loaded when it should not or failed to load. With none, ask whether the user meant to create a new file or has feedback to apply.

Read only the reference for the resolved flow. Capture `rtk git log --oneline -1` before touching the filesystem; Step 3 needs it.

## Step 2 — Contract

Gates on every file, whichever flow wrote it:

- **One topic per file.** Two topics are two files.
- **Scope.** Omit `applyTo` only for a rule that must load in every session, and tell the user it then costs context at every launch.
- **Stem.** It becomes the deployed filename, and install overwrites a hand-authored rule of the same name on most targets without a prompt. Check for a collision before choosing it.
- **Body.** Bullets, paths in backticks, nothing assuming another file is loaded, under 200 lines.

If a field, glob or location is in question, read `references/schema.md`. If the question is which target keeps which field, or what compile does, read `references/target-mapping.md`.

## Step 3 — Validate and close

- [ ] Verify with a real compile and a throwaway deploy: read `references/verify.md`. Resolve every warning and confirm a scoped rule deploys with `paths:`.
- [ ] Bump the owning package's `apm.yml` `version` — **minor** on create, **patch** on improve — because consumers compare it to detect updates.

`factory-audit` has no instructions checks yet, so nothing else gates the file; report only what the verification showed.

**Commit verification.** Once verification is clean, run `rtk git add` and `rtk git commit`. Re-run `rtk git log --oneline -1` and confirm the hash changed from Step 1's. A non-empty `git diff --stat` is not proof: staged-but-uncommitted work is lost if the tree is cleaned up. Report done only once the hash has changed.