docs(adr): 0029 prompts are thin user-triggered steering messages

Record the house rule for the apm prompt primitive: a single-intent,
user-triggered, parameterised message that steers existing skills or
agents by name and carries no procedure of its own. It also sets the
prompt description contract (one plain sentence, no trigger clause).

Add the glossary terms settled in the same grill to CONTEXT.md: apm
primitive, Prompt, Instruction and Hook. Narrow the Skill entry's Avoid
list and log the prompt ambiguity as resolved.

Refs #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 16:30:58 +00:00
parent ff2b8b6c1b
commit 701e96d4b3
2 changed files with 99 additions and 1 deletions

View File

@@ -48,7 +48,31 @@ _Avoid_: agent hygiene
A reusable slash command defined as a `SKILL.md` file following the
[Agent Skills open standard](https://agentskills.io), authored at
`plugins/<plugin>/.apm/skills/<skill>/SKILL.md`.
_Avoid_: command, prompt, macro
_Avoid_: command, macro; and "prompt" for a skill — a **Prompt** is a different artifact
**Prompt**:
A single-intent, user-triggered message with parameters, authored as
`plugins/<plugin>/.apm/prompts/<name>.prompt.md` — the text a user would otherwise type repeatedly.
It carries no procedure beyond steering existing skills or agents by name; once it holds reusable
know-how, bundled files, or anything the model should find on its own, it is a **Skill** in the
wrong container. This is a house rule, stricter than apm, which frames a prompt as a full workflow.
_Avoid_: command (the Claude-side deployed form), workflow, macro
**Instruction**:
A scoped rule authored as `plugins/<plugin>/.apm/instructions/<name>.instructions.md`, applied when
the agent touches files matching its `applyTo` glob. Omitting `applyTo` makes it always-on in every
session of every repo that installs the package — a legitimate way for a package to ship guidance to
consumers, but a deliberate choice, never a default. A rule for this repo alone belongs in
**AGENTS.md**, not in an instruction.
_Avoid_: rule (the Claude-side deployed form under `.claude/rules/`), guideline, standard
**Hook**:
A runtime callback a harness fires inside its own tool loop, authored as one JSON file per concern
under `plugins/<plugin>/.apm/hooks/` in apm's canonical shape — nested entries, PascalCase events,
`${PLUGIN_ROOT}` script paths — which apm renders per target. Reach is narrowed in the package's
`apm.yml` `targets:`, never by filename. The last resort among apm primitives: procedure belongs in
a **Skill**, and a hook is only for "this must always happen at this event".
_Avoid_: trigger, callback script (the script is the hook's payload, not the hook)
**apm package**:
The deployable unit apm builds and installs — one or more skills, agents, hooks, commands, and MCP
@@ -58,6 +82,13 @@ _Avoid_: bundle, module, source tree; and bare "plugin" for the *installable art
ADR-0024 is an apm package and not a Claude Code plugin. "Plugin" stays correct as a modifier in the
repo's settled compounds — **Plugin marketplace**, "plugin units", `plugins/`.
**apm primitive**:
Any content type authored under `plugins/<name>/.apm/` — skills, agents, hooks, instructions, and
prompts. Skills and agents each have their own author skill; `primitive-author` covers the other
three, so its name is narrower in practice than the term. `factory-audit` audits all five.
_Avoid_: component, asset, artifact (unqualified); bare "primitive" when only the three
non-skill, non-agent types are meant — say "hook, instruction, or prompt"
**Output profile**:
A named ecosystem format `apm pack` can compile the marketplace manifest into, declared per profile
under root `apm.yml`'s `marketplace.outputs:`. apm defines `claude` and `codex`; each writes to its
@@ -193,3 +224,8 @@ _Avoid_: namespace, category
an audit running in the same context as the work it checks shares that work's blind spots. The
recheck belongs to `factory-audit`, not to `forge`, which routes only to the author
skills and never to an audit.
- "prompt" meant both apm's `.prompt.md` primitive and, loosely, any slash command or a skill — resolved:
a **Prompt** is the `.prompt.md` primitive under the house rule above. apm calls a prompt "a
callable program for an LLM", but on Claude it deploys as a model-invocable command with fewer
frontmatter keys than a skill, and Codex receives nothing. A fat prompt is a worse skill on every
harness, so the procedure goes in the skill and the prompt only steers it.