Files

Defame1297 0ea3f69dc6 fix(kyberforge): align primitive-author and factory-audit rule tiers

Second clean-context audit found author Must/Should and audit FAIL/SUGGESTION
tiers drifting apart, and author Musts the audit never checked.

- factory-audit: FAIL on absolute or bare relative hook script paths, an
  applyTo present but empty, and unbalanced braces/brackets in applyTo;
  judgment steps for dependency stem collisions, helper .json in hook dirs,
  unresolvable instruction links, prompt model slugs and second-person
  bodies; an unmatched glob drops to SUGGESTION; deliberate tier deviations
  recorded in hook-flow.md; validate.sh --help lists the three new modes;
  DescriptionOpener message no longer prescribes "Use when".
- primitive-author: deprecated routing, extra prompt keys and the prompt
  description contract become Shoulds; hook Musts gain "contributes an
  entry", no bare relative paths, and executable-when-run-directly;
  prompt Must 1 covers hardlinks; Vale prose FAILs resolved at close.
- forge: say "hook, instruction or prompt" rather than "apm primitive".

Refs #94

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

2026-09-28 18:02:05 +00:00

3.4 KiB

Raw Blame History

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: the prompt's body reaches the model, and the model cannot invoke a skill that sets it, so the steering would dead-end (the same check factory-audit's prompt flow applies).

Description contract

One plain, user-facing sentence stating the action and naming the skills or agents 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.

Checklist

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

Must:

The path is .apm/prompts/<name>.prompt.md, directly in that directory, not a symlink or hardlink. <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.
description is present and non-empty.
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.
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.

Should:

Frontmatter keys stay within description, allowed-tools, model, argument-hint and input. Claude drops everything else with only a warning. The exception: a Copilot-only key (agent, tools, …) that is intended, with its Claude drop accepted and said so.
The description follows the contract above: one plain sentence, no trigger or boundary clause, naming the skills or agents it steers.
Spell keys in kebab-case — allowed-tools, argument-hint — not the camelCase aliases.
Omit argument-hint when input: is set; apm synthesises <a> <b> from the input names.
Keep one intent per prompt, and write the body as second-person instructions.
Keep description to 250 characters or fewer.
Give model a slug the target accepts. Copilot ignores allowed-tools and model, so neither constrains a Copilot run.

3.4 KiB Raw Blame History

Authoring an apm prompt

Gate

Description contract

Checklist

3.4 KiB

Raw Blame History