fix: Frontmatter formatter error using hve-core agents in Copilot CLI

[andrejpk]

Component

VS Code Extension

Bug Description

After installing the plugin via copilot plugin install hve-core@hve-core, all 18 agent files under agents/ produce warnings on every Copilot CLI launch:

custom agent markdown frontmatter is malformed: missing or malformed YAML frontmatter

Each agent file in the installed plugin is a single-line relative path reference instead of the actual agent markdown:

../../../.github/agents/hve-core/doc-ops.agent.md

The Copilot CLI expects agent .md files to begin with valid YAML frontmatter (--- delimited block with at least a description field). The relative path string is not parseable as YAML frontmatter, and does not resolve to anything meaningful from the installed plugin directory (~/.copilot/installed-plugins/hve-core/).

All 18 agents are affected (17 hve-core + 1 ado).

Root Cause

The plugin packaging process stores relative path references in agent files rather than inlining the actual content from .github/agents/. Commands, instructions, and skills use the same path-reference pattern and are handled correctly by the CLI, but agents require parseable YAML frontmatter which the path stubs do not provide.

Proposed Fix

Update the plugin packaging to inline the full agent markdown content (YAML frontmatter + prompt body) from .github/agents/ into the corresponding agents/ files in the plugin package, matching how the CLI expects to consume them.

To prevent regressions, consider adding CI tests that validate core CLI workflows

Affected Files

• hve-core/agents/doc-ops.md
• hve-core/agents/implementation-validator.md
• hve-core/agents/memory.md
• hve-core/agents/phase-implementor.md
• hve-core/agents/plan-validator.md
• hve-core/agents/pr-review.md
• hve-core/agents/prompt-builder.md
• hve-core/agents/prompt-evaluator.md
• hve-core/agents/prompt-tester.md
• hve-core/agents/prompt-updater.md
• hve-core/agents/researcher-subagent.md
• hve-core/agents/rpi-agent.md
• hve-core/agents/rpi-validator.md
• hve-core/agents/task-implementor.md
• hve-core/agents/task-planner.md
• hve-core/agents/task-researcher.md
• hve-core/agents/task-reviewer.md
• ado/agents/ado-prd-to-wit.md

Workaround

Manually copy the actual agent files from .github/agents/ in the source repo over the stub files in ~/.copilot/installed-plugins/hve-core/.

Expected Behavior

Expected to be able to use the agents in the Github CLI in a similar way to VS Code.

Steps to Reproduce

Using Copilot CLI version 0.0.4199-0 (current as of 2026-02-26):

plugin marketplace add microsoft/hve-core
copilot plugin install hve-core@hve-core

In Copilot: /agent

Additional Context

No response

[WilliamBerryiii]

I know we have an open PR on this ... but I'm trying to confirm the actual bug in a few environments. Need a bit longer to figure out what's up here and when this was introduced. If the symlinks are getting mangled, It's likely my fault - dev'ing on a non-admin or dev-mode window bare install with vscode. We do have tests for this kind of failure which is also concerning.

@andrejpk - digging deeper and need a bit more time.

[WilliamBerryiii]

@andrejpk - upon further investigation, it appears that late last week, the CLI has subtly changed it distribution mechanism such that the symlink approach, where we map the cli folders over to the extension artifacts, no longer works. I'm investigating ways we can map the cli collections onto copy of release artifacts stored in GH, to avoid this ... will try to have a fix out shortly. Thanks for bearing with us.

[WilliamBerryiii]

I have a fix idea ... @stablegenius49 ... I hope this is ok, but I'm planning to take over your branch with the additional changes that need to be made. You have the right start, but I need to do some additional work to mesh this with the release pipelines.

[WilliamBerryiii]

TLDR; Please stand by for a decision by the maintainers on the long-range approach.

Investigation Summary: Plugin Symlink Distribution Fix

Comprehensive analysis of the plugins/ symlink problem, evaluated approaches, and recommended path forward.

Problem

The plugins/ directory contains 356 git symlinks (mode 120000) whose blobs store bare relative path strings instead of file content. Every non-clone distribution channel delivers those path strings as the file body, breaking frontmatter parsing for all 244 agent, instruction, and skill artifacts.

Two independent failure modes exist:

Mode	Platform	Trigger	Symptom
A — Text Stubs	Windows (core.symlinks=false)	Git materializes symlinks as regular files containing the path string	Frontmatter parser receives ../../../.github/agents/... instead of YAML
B — Broken Targets	All platforms	CLI extracts plugins/<collection>/ to ~/.copilot/installed-plugins/	Relative symlinks (../../../.github/...) resolve to non-existent paths outside extraction directory

Architecture Context

The plugins/ directory is a necessary transformation layer — not a redundant copy of .github/. Five transformations bridge the structural gap:

1. Collection assembly — Aggregates files from multiple .github/<type>/<collection>/ paths into one collection-first directory
2. Suffix stripping — Removes .agent.md, .prompt.md, .instructions.md suffixes
3. Kind-to-subdirectory remapping — Maps prompt → commands, agent → agents, etc.
4. Plugin manifest generation — Creates per-plugin plugin.json files that don't exist in .github/
5. Shared directory copying — Includes shared content referenced by multiple collections

.github/ uses type-first layout (agents/hve-core/, instructions/hve-core/). The CLI expects collection-first layout (hve-core/agents/, hve-core/instructions/). These are inverted hierarchies that cannot be reconciled without the transformation layer.

CLI Mechanism (Confirmed)

The standalone copilot binary clones marketplace repositories to ~/.copilot/marketplace-cache/ using standard git clone. It always clones the default branch (main). Evidence chain:

• Microsoft developer on awesome-copilot feat(agents): Support full RPI workflow in OpenCode and Kilo CLI #751: "the Copilot CLI clones the repo behind the scenes and does not handle symlinks properly"
• Changelog v0.0.420: "Plugin and marketplace git repos update correctly after force-pushes"
• Changelog v0.0.422: "Show a clear, actionable error message when git is not installed"

The marketplace.json schema enforces additionalProperties: false at every level and source as ^[a-z0-9-]+$ (bare names only). No branch/ref/tag fields exist.

---

Approaches Evaluated

Approach A: Inline Copies (Recommended Immediate Fix)

Replace all 356 symlinks with real file copies using Copy-Item. Remove ~160 lines of symlink/text-stub code. Mirrors the extension pipeline's proven Copy-CollectionArtifacts pattern.

Pros	Cons
Fixes ALL distribution channels in one commit	Commits 378 generated files to git
Net-negative code change (removes ~160 lines)	Changes to shared source assets produce multiple diff entries
Git deduplication means near-zero storage overhead	Requires linguist-generated to suppress PR diff noise
Already implemented with 67/67 Pester tests passing
Proven pattern (extension pipeline already does this)

Approach B: Dual-Mode (Symlink Local + Copy CI)

Add --Inline switch to New-PluginLink for CI while retaining symlink mode for local dev.

Pros	Cons
Preserves local dev symlink convenience	Two code paths to maintain and test
CI produces correct output	Risk of symlink reintroduction if dev runs without --Inline
	Keeps Repair-PluginSymlinkIndex as conditional dead code

Approach C: Distribution Branch

CI resolves symlinks and force-pushes to a separate branch (e.g., dist).

Pros	Cons
Main branch stays clean	CLI always clones default branch — never sees the dist branch
No generated files in main	Two sources of truth, sync overhead
	Does not fix main branch consumers

Approach D: Harden Release Artifacts (Companion Only)

Make symlink resolution explicit in the release zip workflow with cp -rL.

Pros	Cons
Guards against regressions in release pipeline	Only fixes one distribution channel
One workflow edit, low risk	Does not fix git clone, GitHub API, or CLI installs
Complements any other approach

Approach E: Consumer-Side Fix

Consumers resolve symlinks on their end.

Pros	Cons
Zero changes to hve-core	Unscalable — no control over consumer environments
	Windows users without Developer Mode cannot create symlinks
	GitHub API consumers have no resolution mechanism

Approach F: Gitignore plugins/

Remove plugins/ from git, regenerate only in CI.

Pros	Cons
No generated files committed	CLI performs git clone — empty plugins/ means broken installs
Clean repository	Only viable with a separate distribution repo or release artifact consumption
	No evidence CLI supports either alternative mechanism

Approach G: Two-Phase (Inline Now + Remote Sources Later)

Phase 1: Apply Approach A (inline copies) — fixes all channels immediately.
Phase 2: Evolve marketplace.json to use remote source objects, eliminating plugins/ from git entirely.

Pros	Cons
Immediate fix + long-term elimination of committed files	Phase 2 depends on unverified CLI capabilities
Phase 1 serves as guardrail until remote sources proven	Remote sources claimed (v0.0.413) but no production usage
Aligns with CLI evolution direction	Schema changes required (additionalProperties: false blocks new fields)

Also Investigated

• pluginRoot → .github/: Cannot work due to type-first vs collection-first structural mismatch and 5 required transformations
• Separate plugin branch: Equivalent to Approach C — CLI always clones default branch
• Dedicated distribution repo (hve-core-cli): Does not solve Issue fix: Frontmatter formatter error using hve-core agents in Copilot CLI #785 — works around it by redirecting CLI users. Adds cross-repo sync complexity
• CLI dependency support: plugin.json could declare dependencies for transitive install — requires CLI and schema evolution that doesn't exist today

---

Comparative Matrix

Criterion	A: Inline	B: Dual	C: Dist Branch	D: Release	E: Consumer	F: Gitignore	G: Two-Phase
Fixes git clone	✅	✅	❌	❌	⚠️	❌	✅ (Ph1)
Fixes GitHub API	✅	✅	❌	❌	❌	❌	✅ (Ph1)
Fixes release zips	✅	✅	✅	✅	N/A	⚠️	✅ (Ph1)
Fixes CLI plugins	✅	✅	❌	❌	❌	❌	✅ (Ph1)
Code complexity	Low	Med	Med-High	Low	None	Med	Low→Med
Maintenance burden	Low	Med	Med-High	Low	None	Med	Low→Low
Diff noise	Mitigable	Mitigable	None	None	None	None	Temporary
Git storage impact	~Zero	~Zero	Doubles	None	None	Removes	~Zero→Removes
Consumer requirements	None	None	Know branch	Download	Resolve symlinks	None (broken)	None
Eliminates plugins/ from git	❌	❌	❌	❌	❌	✅ (broken)	Phase 2: ✅

---

Duplication Analysis

The user concern: committing 378 generated files feels like massive duplication. Here's the quantitative reality:

Metric	With hve-core-all	Without hve-core-all
Total committed files	378	216
Duplication overhead	173 extra copies	17 extra copies
Unique-to-total ratio	44% (167/378)	77% (167/216)
Collections available	11	10

Root driver: hve-core-all is a pure superset containing 100% of the content from every other collection. All 162 files in plugins/hve-core-all/ are duplicates. Excluding it, cross-collection duplication drops to just 9 shared hashes producing 17 extra copies — all intentional sharing of foundational assets.

Mitigation options:

1. Drop hve-core-all from plugin distribution (recommended) — 43% file reduction, 90% duplication reduction. Users install individual collections. VSIX packaging unaffected (uses collection YAML independently).
2. Accept duplication with mitigations — linguist-generated suppresses diffs, git deduplication handles storage, CI freshness checks prevent drift.
3. CLI dependency support (future) — plugin.json declares dependencies for transitive install. Requires CLI and schema evolution.

---

CLI Remote Sources — Current State

Remote plugin sources were claimed in CLI v0.0.413 changelog (2026-02-20) but:

• No production marketplace ships remote source objects in its marketplace.json
• URL-based archive resolution has no evidence of support — CLI uses git-based resolution only
• awesome-copilot (the largest known marketplace) materializes all content locally using fs.copyFileSync rather than using remote sources
• The exact JSON schema the CLI expects for remote source objects is undocumented
• marketplace-manifest.schema.json enforces additionalProperties: false at every level, blocking extension without schema changes

---

Recommendation

Approach A (inline copies) combined with dropping hve-core-all from plugin distribution:

• Fixes Issue fix: Frontmatter formatter error using hve-core agents in Copilot CLI #785 for all distribution channels in one commit
• Reduces committed files by 43% (378 → 216)
• Eliminates 90% of duplication overhead (173 → 17 intentional copies)
• Already implemented with 67/67 Pester tests passing
• Net-negative code change (~160 lines removed)
• Companion: Approach D (explicit cp -rL in release workflow) for defense-in-depth

---

Note on CLI Team Engagement

The CLI is not open-source, and its plugin resolution, remote source support, and schema evolution are undocumented. Before investing in Phase 2 (Approach G) or alternative distribution models, we need to engage the CLI team to understand:

1. Remote source roadmap — Will marketplace.json support github-type or url-type source objects? What schema will they use?
2. Branch/ref support — Will plugin sources support targeting non-default branches or tags?
3. Dependency/transitive install — Will plugin.json support declaring dependencies on other plugins?

Without this clarity, we risk building distribution infrastructure (dist repos, archive pipelines, cross-repo sync) that the CLI may never consume — exactly the pattern awesome-copilot avoided by choosing to inline content directly. Approach A gives us a working fix today while preserving optionality for whatever direction the CLI takes.

We are evaluating options .. this is NOT a committed decision, yet.