feat(kyberforge): add primitive-author for apm hooks, instructions and prompts

New skill that creates or improves an apm hook, instruction or prompt.
Its SKILL.md holds the shared procedure (dispatch on primitive, boundary
gate, create-or-improve, factory-audit close); one self-contained
reference per primitive carries its gate, checklist and template, drawn
from the microsoft-apm research docs and ADR-0029.

forge gains a route row sending a hook, instruction or prompt to
primitive-author through author-routes.md, and no longer lists hooks as
unroutable. factory-audit's description adds the primitive-author
boundary now that the target resolves.

Fixes #94

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KkT7RSDwDbmrM9T34b6sTi
This commit is contained in:
2026-09-28 17:22:23 +00:00
parent 70210d6a7e
commit 0d96dc8282
12 changed files with 325 additions and 22 deletions

View File

@@ -0,0 +1,59 @@
---
source_keys:
- apm-cli-installed-source
- apm-docs-llms-full
- adr-0029-prompt-house-rule
---
# Authoring an apm prompt
Reached from `SKILL.md` Step 1 for a prompt. Run the Gate, then write against the description
contract and the checklist, then return to `SKILL.md` Step 3.
## Gate
This repo holds a prompt to ADR-0029, which is stricter than apm: apm calls a prompt "a callable
program", but on Claude it deploys as a command that is a skill in every respect except that it
keeps fewer frontmatter keys, apm drops `disable-model-invocation` so it can never be made
user-only, and Codex receives no prompts at all. A prompt that carries procedure is therefore a
worse skill on every harness.
- **Reusable know-how, steps, gotchas, bundled files, or anything the model should find on its
own** → a skill. Stop and hand to `skill-author`; if a short steering message is still wanted
afterwards, come back and write it against the new skill.
- **A single-intent message the user would otherwise type repeatedly, steering existing skills or
agents by name** → continue. Confirm each skill or agent it names exists and is not
`disable-model-invocation: true`, which the model cannot invoke.
## Description contract
One plain, user-facing sentence stating the action and naming the skills it steers — "Review the
current PR with `gitea-prs` and `factory-audit`, then summarise the findings." No "Use when"
trigger clause and no `Not X -> Y` boundary: on Claude the description is model-visible, and a
trigger clause invites the router to pick the wrapper over the skills it wraps. 250 characters at
most.
## Checklist
Copy `assets/templates/name.prompt.md.template` and drop `.template` only on the final path.
Must:
1. The path is `.apm/prompts/<name>.prompt.md`, directly in that directory, not a symlink. `<name>`
is a safe path segment and unique across `.apm/prompts/` and the package root; it becomes the
Copilot filename and the Claude `/command` name.
2. `description` is present and non-empty, per the contract above.
3. Every `input:` name matches `^[A-Za-z][\w-]{0,63}$`, written in the object form
`- pr_number: "The PR to review"`. Never copy apm's published `- name: pr_number` /
`description: …` example: apm reads the map's keys, so it produces the arguments `name` and
`description`.
4. Every `${input:x}` in the body is declared in `input:`, and every declared name is used. Without
`input:`, no `${input:…}` may appear — it would reach Claude unrewritten.
5. Frontmatter keys stay within `description`, `allowed-tools`, `model`, `argument-hint` and
`input`. Claude drops everything else with only a warning.
Should:
6. Spell keys in kebab-case — `allowed-tools`, `argument-hint` — not the camelCase aliases.
7. Omit `argument-hint` when `input:` is set; apm synthesises `<a> <b>` from the input names.
8. Keep one intent per prompt, and write the body as second-person instructions.