docs: source ADR-0029 claims and sync ADRs and hook docs with behaviour
- cite the VS Code prompt-file deprecation and the verbatim apm quote - add ADR-0029 boundary-clause enforcement and Consequences - mark superseded ADR-0019 passages; record neutral lock advice, source fork and reloadSkills, amend for the hook hardening - move the ADR-0025 amendment out of the Decision list - amend ADR-0022 for create keeping 0.1.0 - fix hooks.md merge and event claims, README guard caveat, gates.md Vale globs, and pin the research registry URL 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:
@@ -8,17 +8,21 @@ parameters. It is the text a user would otherwise type again and again. It carri
|
||||
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 stricter than apm. apm's docs call a prompt "a callable program for an LLM", and 0.28.0
|
||||
scaffolds one as a numbered-steps workflow (`apm_cli/workflow/discovery.py`). On every harness this
|
||||
repo targets, a prompt with a full workflow in it is a worse skill:
|
||||
This is stricter than apm. apm frames a prompt as a program: its docs state that "a prompt is a
|
||||
program for an LLM" (microsoft.github.io/apm/concepts/what-is-apm/, "Secure by default"; the same
|
||||
sentence is in the apm-cli 0.28.0 package README), and 0.28.0 scaffolds one as a numbered-steps
|
||||
workflow (`apm_cli/workflow/discovery.py`). On every harness this repo targets, a prompt with a full
|
||||
workflow in it is a worse skill:
|
||||
|
||||
- **Claude Code.** Custom commands have been merged into skills. "Both create `/deploy` and work
|
||||
the same way", and both are model-invocable by default (code.claude.com/docs/en/skills.md).
|
||||
apm 0.28.0 keeps only `description`, `allowed-tools`, `model`, `argument-hint` and `input` for
|
||||
Claude (`_PRESERVED_COMMAND_KEYS`) and drops `disable-model-invocation`. A deployed prompt is
|
||||
therefore a model-visible skill with fewer frontmatter keys, and it cannot be made user-only.
|
||||
- **Copilot / VS Code.** Prompt files are marked deprecated for Agent Host, and VS Code offers a
|
||||
migration to agent skills.
|
||||
- **Copilot / VS Code.** "Prompt files are deprecated for Agent Host sessions and aren't loaded by
|
||||
Agent Host", and VS Code offers a migration that converts existing prompt files to agent skills
|
||||
(code.visualstudio.com/docs/agent-customization/prompt-files). They still load in the Local agent,
|
||||
which that page says will be removed in a future release.
|
||||
- **Codex.** Codex receives no prompts at all.
|
||||
|
||||
The one job a prompt does better than a skill is a short, parameterised "do this now, using X and Y"
|
||||
@@ -45,10 +49,28 @@ happen, the cost is bounded: the prompt is a thin wrapper that calls the right s
|
||||
- `description` is present and non-empty (FAIL).
|
||||
- It is 250 characters or fewer (SUGGESTION).
|
||||
- It has no "Use when" trigger clause (SUGGESTION).
|
||||
- It has no `Not X -> Y` boundary clause (SUGGESTION).
|
||||
- **`factory-audit`, judgment step.** A body that clearly carries reusable procedure is a FAIL. A
|
||||
borderline body is a SUGGESTION. There is deliberately no line-count or heading heuristic: the
|
||||
call is made by reading the content, because any threshold misfires.
|
||||
|
||||
## Consequences
|
||||
|
||||
- **`factory-audit` gains a prompt mode.** `*.prompt.md` is a Step 0 dispatch row with its own
|
||||
`references/prompt-flow.md`, and `scripts/lib-checks-primitive.sh` carries the three description
|
||||
checks above plus the judgment step (ADR-0025, amendment 2026-09-28). A prompt that was fine under
|
||||
apm's framing — a trigger clause, a boundary clause, a numbered workflow — now draws findings.
|
||||
- **`primitive-author` refuses procedure-bearing prompts.** Its prompt reference opens with the
|
||||
boundary gate, so a "make me a command" request that carries reusable know-how is redirected to
|
||||
`skill-author` before any file is written. That makes skill-vs-prompt a checked boundary rather
|
||||
than an authoring preference.
|
||||
- **Codex gets no prompts from this repo.** apm deploys none to Codex, so anything a prompt steers
|
||||
must also be reachable there through the skill it names. Keeping procedure in the skill is what
|
||||
makes that true; a fat prompt would be content Codex users silently never see.
|
||||
- **Reversing this is cheap in files, not in routing.** No prompt exists in the repo yet, so the rule
|
||||
constrains new work only. Loosening it later means re-deciding the description contract, and every
|
||||
prompt written under it would need a trigger clause added.
|
||||
|
||||
## Considered options
|
||||
|
||||
- **Fat workflow prompts as peers of skills (rejected).** This follows apm's framing. But every
|
||||
|
||||
Reference in New Issue
Block a user