Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion skills/agent-instructions/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: cmk:agent-instructions
description: This skill should be used when the user asks to "set up CLAUDE.md", "set up AGENTS.md", "agent instructions", "add engineering rules", "make the instructions thinner", or needs to establish or maintain a thin, multi-vendor root instruction file backed by on-demand engineering rules under docs/rules/.
version: 0.2.0
version: 0.2.1
---

# Agent Instructions
Expand Down
15 changes: 9 additions & 6 deletions skills/agent-instructions/references/rules-doc-comments.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,9 +58,12 @@ than no comment.
## Never reference the issue tracker from source

A doc comment, test name, or identifier must never name a tracked issue,
pull request, review round, or finding label — the reader of the code has no
guaranteed access to that system, and the reference rots the day the ticket
does. Write the reasoning the ticket stood for, in the code's own words,
even if that duplicates wording that also lives in the tracker. A path to
another file inside the same repository (a design doc, a decision record) is
fine, since anyone with the repository can open it.
pull request, review round, finding label, acceptance-criterion number
(`AC4`), or requirement/workstream label with no in-repo definition — the
reader of the code has no guaranteed access to that system, and the
reference rots the day the ticket does. Write the reasoning the ticket stood
for, in the code's own words, even if that duplicates wording that also
lives in the tracker. A path to another file inside the same repository (a
design doc, a decision record) is fine, since anyone with the repository can
open it. A label is canonical only if the repository itself defines it; a
delivery report merely quoting it does not count.
15 changes: 15 additions & 0 deletions skills/agent-instructions/references/rules-naming.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,21 @@ Add tokens only to restore domain or semantic context that would otherwise
be lost — not to repeat an enclosing namespace or narrate implementation
details already visible in the type.

## Names are never work-tracking coordinates

A ticket ID, an acceptance-criterion number (`ac4`), a review-round or
finding label, or a requirement/workstream code with no in-repo definition
must not appear in an identifier, file, directory, binary, module, stack, or
test name. Such a name records where the work was tracked, not what the
thing is; a reader of the code has no guaranteed access to the tracker, and
the reference rots the day the ticket closes. Name the capability or
behavior instead — the binary that proves chain anchoring is
`chain-anchor-proof`, not `proj424-proof`. Citing an in-repo canonical
artifact (a decision record number, a `docs/…` path) is fine inside a
comment, but never as a substitute for a self-descriptive name. An existing
deployed identity that already carries such a name changes only under the
compatibility-aware rename rule below.

## Renames are atomic and compatibility-aware

Update every call site, import, test, and doc reference in the same change.
Expand Down
Loading