microsoft / microsoft/hve-core

hve-builder.instructions.md ships with only 2 of 7 packages containing affected skills

Open
#2,649 0 comments 1 reaction 1 assignee View on GitHub

@WilliamBerryiii is already working on this.

Since Aug 9, 2026.

bug foundation instructions packaging priority-2 skills tech-debt
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.