microsoft / microsoft/hve-core
hve-builder.instructions.md ships with only 2 of 7 packages containing affected skills
@WilliamBerryiii is already working on this.
Since Aug 9, 2026.
- Dominant language
- Python
- Stars
- 1.5k
- Forks
- 301
- Avg merge
- 3d 3h
- Merged PRs (30d)
- 92
Description
Discovered while remediating review findings on #2599.
## Problem
`hve-builder.instructions.md` defines the cross-artifact portability rule and the unavailable-reference contract. It does not ship with most of the skills that depend on it.
Measured against `.github/plugin/marketplace.json`:
| Package | Ships `hve-builder.instructions.md` | Contains affected skills |
|--------------------|--------------------------------------|-----------------------------------------|
| `hve-core` | yes | accessibility, mural, code-review |
| `hve-core-all` | yes | all eight |
| `coding-standards` | no | accessibility, code-review |
| `experimental` | no | mural, customer-card-render, powerpoint |
| `installer` | no | hve-core-installer |
| `project-planning` | no | accessibility, mural, backlog-templates |
| `security` | no | vex, backlog-templates |
Five of seven packages ship the skill without the rule that governs how its references behave.
## Why this matters
This is the same failure mode #2599 was written to fix, one level up. That PR made references portable by naming their targets and stating unavailable behavior per site. The per-site prose is not redundant with the instruction file precisely because, in five of seven distributions, the prose is the only carrier of that behavior.
It also means an agent operating in those packages has no attached definition of what to do when a named artifact does not resolve.
## Options
1. Add `hve-builder.instructions.md` to every package recipe that ships skills.
2. Move the unavailable-reference contract somewhere that always travels with a skill.
3. Accept the gap and rely on per-site prose, documenting that reliance explicitly.
Option 1 is mechanical but grows every package. Option 3 is the current de facto state and works only if per-site prose is enforced, which is #2647.
## Acceptance
- Either the rule ships with the skills it governs, or the reliance on per-site prose is explicit and enforced.
- The decision is recorded so future skills in these packages are unambiguous.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.