holocron/plugins/kyberforge/.apm/skills/primitive-author/SKILL.md

name, description, allowed-tools, metadata

name	description	allowed-tools	metadata
primitive-author	Use when the user wants an apm hook, instruction or prompt file created, or audit findings or feedback applied to an existing one. Not read-only review -> factory-audit. Not skills -> skill-author. Not agents -> agent-author.	Bash Read Write Edit	version category source_keys 0.1.0 factory apm-cli-installed-source apm-docs-llms-full

Gotchas

• apm compile --validate is not a gate: it reports instruction problems only as warnings, exits 0, and never reads prompts. apm install fails only on a hook payload Copilot would reject, and merely warns on bad prompt input names and dropped keys — /factory-audit is the only check that fails on the rest.
• Never draft with the real suffix outside .apm/<type>/. apm's local discovery globs **/*.instructions.md across the whole tree, so a draft or template named that way anywhere in the repo is picked up as a real instruction. The templates carry a trailing .template for this reason; drop it only on the final path.
• Never hand-write .claude/settings.json, even to test a hook. apm owns that file (ADR-0019), overwrites it outright when it is malformed, and apm audit --ci fails on anything it would not have written.

Step 1 — Dispatch

Target or intent	Primitive	Reference
A hook — .apm/hooks/<name>.json, or "run X whenever Y happens"	hook	references/hook.md
An instruction — .apm/instructions/<name>.instructions.md, or a rule for files matching a pattern	instruction	references/instruction.md
A prompt — .apm/prompts/<name>.prompt.md, or a reusable message the user types to kick off work	prompt	references/prompt.md
A skill or an agent	—	stop: route to skill-author or agent-author

Read only the reference matching the resolved primitive — each is self-contained. If the target sits inside a git worktree, capture rtk git log --oneline -1 before touching the filesystem; Step 4 needs it.

Step 2 — Boundary gate

Run the reference's Gate section before writing anything. A failed gate stops this skill: name the owner it points to — skill-author for procedure, agentsmd-author for a repo-only rule, apm-workflow for reach or targets: — and hand over. Never bend the artifact to pass the gate.

Step 3 — Create or improve

Condition	Action
No file at the target path	Create: copy the reference's template from assets/templates/, drop .template, fill every FILL IN and FILL_IN_ placeholder, and apply the reference's checklist
File exists, at least one signal	Improve: read the whole file, then apply each signal against the reference's checklist
File exists, no signal	Stop and ask whether the user meant a new file or has feedback to apply

Signals: grill output, /factory-audit findings, inline feedback, session context describing what went wrong. Group findings by root cause and fix the cause once.

Step 4 — Validate and close

1. Run /factory-audit on the file, inline in this context; resolve every FAIL before reporting done.
2. Run rtk apm install --dry-run from the repo root and read what each target will receive. On a feature branch, discard apm.lock.yaml churn afterwards (rtk git checkout -- apm.lock.yaml).
3. Bump the owning package's apm.yml version: — minor for a new primitive, patch for a fix — unless this branch already bumped it for unreleased work. A primitive has no version of its own.
4. Commit verification. Inside a git worktree, once the audit is clean, run rtk git add and rtk git commit, then re-run rtk git log --oneline -1 and confirm the hash changed from Step 1's. Staged-but-uncommitted work is silently lost if the tree is cleaned up. Outside a worktree, report done on a clean audit and name that as the reason.