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:
38
CONTEXT.md
38
CONTEXT.md
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user