Files

Defame1297 965208bddd fix(kyberforge): resolve PR #144 review and audit round 2

- factory-audit: ./ and bare/absolute script checks scoped to command
  position (no false FAILs on ./src or printf); hook sources limited to
  .apm/hooks or package-root hooks/; Kiro-aware lowercase events;
  unfilled template placeholders FAIL; repo-only instructions FAIL at
  any scope; Vale description FAIL documented; bats 367 -> 378
- primitive-author: split-quote/spaced paths and handler-less entries
  promoted to Must; Step 4.2 renders into a scratch consumer instead of
  a no-op dry run; dispatch and gate hand-off trimmed
- apm-workflow 1.0.2: mutual boundary with primitive-author
- forge: no double package bump; gotcha wording
- skill-author: create keeps seeded 0.1.0 (ADR-0022); portable,
  retry-safe new-skill.sh; template and flow consistency fixes
- hook docs: cite the ADR-0019 correction; guard caveat

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KkT7RSDwDbmrM9T34b6sTi

2026-09-28 20:50:22 +00:00

2.8 KiB

Raw Blame History

source_keys

apm-cli-installed-source

apm-docs-llms-full

Authoring an apm instruction

Reached from SKILL.md Step 1 for an instruction. Run the Gate, then write against the checklist, then return to SKILL.md Step 3.

Gate

An instruction is a scoped rule: it applies when the agent touches files matching its applyTo glob. On Claude it deploys to .claude/rules/<stem>.md with applyTo renamed to paths:.

A rule for this repo alone → it belongs in the repo's AGENTS.md, which is the single always-on source. Stop and hand to agentsmd-author.
No file pattern fits → an instruction without applyTo is always-on in every session of every repo that installs this package, and apm compile can fold it into the global sections of AGENTS.md and CLAUDE.md (CLAUDE.md is skipped when .claude/rules/ is populated, AGENTS.md when .github/instructions/ is, unless --force-instructions). Say exactly that to the user and continue only on an explicit yes. Legitimate when a package deliberately ships guidance to its consumers; never a default.
Procedure the agent follows step by step → a skill. Stop and hand to skill-author.
A rule scoped to a file pattern → continue.

Checklist

Copy assets/templates/name.instructions.md.template and drop .template only on the final path.

Must:

The path is .apm/instructions/<stem>.instructions.md, directly in that directory, not a symlink or hardlink.
description is a non-empty string. Only apm compile warns when it is missing; apm install deploys it silently.
The body is non-empty after trimming whitespace. apm deploys an empty rule silently.
applyTo is a non-empty glob or comma-separated list — top-level commas only as separators, alternation inside {} ("**/*.{ts,tsx}"), braces and brackets balanced — or absent after the Gate's explicit yes. An empty applyTo: "" is neither.
The stem is unique across the package and its dependencies: a .claude/rules/<stem>.md collision is silently overwritten.

Should:

Write applyTo as a scalar string, not a YAML list. Copilot receives the source verbatim, and its handling of a list is unverified.
Keep frontmatter to description and applyTo, plus optional author and version. No target consumes other keys, and Claude drops them.
Put any rationale Claude needs in the body. description never reaches Claude — it survives for Copilot and as index text in Cursor rules and compiled AGENTS.md/CLAUDE.md.
Keep relative markdown links resolvable from the source file.
Check the glob against the tree: one that matches nothing here fires only in consumer repos that have such files, and one broader than the rule's real scope spends context on every file it touches.

2.8 KiB Raw Blame History

Authoring an apm instruction

Gate

Checklist

2.8 KiB

Raw Blame History