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 created, or findings applied to one. Not read-only review -> factory-audit. Not skills -> skill-author. Not agents -> agent-author. Not apm.yml, targets or package config -> apm-workflow.	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 only warns on instructions, exits 0, and never reads prompts. apm install exits 1 only on a hook payload Copilot would reject or on critical hidden Unicode; bad prompt input names and dropped keys merely warn — /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 named that way anywhere in the repo becomes 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	Type	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 slash command steering existing skills	prompt	references/prompt.md
Anything else (agent file, context/memory file)	none	stop; agents -> agent-author, otherwise name the unsupported type

Read only the matching reference. 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: hand over to the owner the Gate names. 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. 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, including Vale's ### Prose FAILs on an instruction or prompt.
2. Render it: in a fresh mktemp -d directory, run rtk apm install <absolute path to the owning package> --target <its targets: joined with commas, or all when it declares none> (a repeated --target keeps only the last; Codex receives no prompts), then read what each target received — .claude/settings.json and .github/hooks/, .claude/rules/ and .github/instructions/, or .claude/commands/ and .github/prompts/. A local path deploys the working tree; --dry-run renders nothing and a repo-root install resolves the remote's main.
3. Bump the owning package's apm.yml version: (minor for a new hook, instruction or prompt, patch for a fix; even if an instruction carries its own version: key) unless this branch already bumped it for unreleased work.
4. Commit verification. Inside a git worktree, once the audit is clean, run rtk git add and rtk git commit, then confirm rtk git log --oneline -1 changed from Step 1's hash: staged-but-uncommitted work is lost if the tree is cleaned up. Outside a worktree, report done on a clean audit and name that as the reason.