fix(extension): inline agent content instead of path stubs in packaged plugins

[stablegenius49]

Pull Request

Description

When plugins are packaged in non-symlink environments (e.g., Windows without Developer Mode, or when Copilot CLI installs plugins), agent files were being written as single-line relative path references instead of actual YAML frontmatter content. This caused Copilot CLI to fail with 'frontmatter is malformed' errors on all agent files.

Root Cause

The New-PluginLink function was writing text stubs containing relative paths when symlinks were not supported. The Copilot CLI expects agent .md files to begin with valid YAML frontmatter (--- delimited block with at least a description field), but received single-line path strings instead.

Fix

Changed New-PluginLink to copy the actual file content when symlinks are not supported, ensuring agent files have valid YAML frontmatter in installed plugins.

Before:

else {
    [System.IO.File]::WriteAllText($DestinationPath, $relativePath)
}

After:

else {
    # Copy the actual file content instead of writing a path reference
    # This ensures agent files have valid YAML frontmatter in installed plugins
    Copy-Item -Path $SourcePath -Destination $DestinationPath -Force
}

Related Issue(s)

Fixes #785

Type of Change

Select all that apply:

Code & Documentation:

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update

Infrastructure & Configuration:

• GitHub Actions workflow
• Linting configuration (markdown, PowerShell, etc.)
• Security configuration
• DevContainer configuration
• Dependency update

AI Artifacts:

• Reviewed contribution with prompt-builder agent and addressed all feedback
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)

Other:

• Script/automation (.ps1, .sh, .py)
• Other (please describe):

Testing

This fix ensures:

• Agent files have valid YAML frontmatter when installed via copilot plugin install
• Commands, instructions, and skills continue to work correctly
• Plugin packaging works in both symlink and non-symlink environments

Validation

• Local testing shows agent files now contain actual content instead of path references
• The fix maintains the same directory structure and behavior for symlink environments
• No changes to symlink behavior when supported

Checklist

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (if applicable)

Required Automated Checks

The following validation commands must pass before merging:

• Markdown linting: npm run lint:md
• Spell checking: npm run spell-check
• Frontmatter validation: npm run lint:frontmatter
• Skill structure validation: npm run validate:skills
• Link validation: npm run lint:md-links
• PowerShell analysis: npm run lint:ps
• Plugin freshness: npm run plugin:generate

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues
• Security-related scripts follow the principle of least privilege

Additional Notes

[WilliamBerryiii]

@ Maintainers - please hold on this until we can fully confirm the backing issue is as described and we're sure of the approach. I'm on a windows box and can test this, but won't have time for a bit. @peterbryntesson .... if you have access to windows bare metal ... this would be a cool one to run to ground to make sure this fix is correct and we can generate these files correctly (e.g. the fake symlinks) without having to run the regenerate plugins in Admin via powershell.

[WilliamBerryiii]

@stablegenius49 - please sign the LCA

[WilliamBerryiii]

@stablegenius49 - I'm going to take over this branch and complete the work here so that you contribution marker remains. I really appreciate you taking a run at this one and your solution is close, but needs some additions. Should have this completed and tested today, but not sure I'll be able to cut a release until next week due to the other changes we've already merged down into main.

[WilliamBerryiii]

We've updated the PR description to align with the current pull request template. All original content has been preserved and relocated into the appropriate template sections. No action needed on your end — though you're welcome to review the updated description and fill in any remaining sections (testing details, checklist confirmations, etc.) at your convenience.

[stablegenius49]

@microsoft-github-policy-service agree

[WilliamBerryiii]

PR Compliance Update — Added the missing (extension) scope to the PR title to align with the project's Conventional Commits convention:

• Before: fix: inline agent content instead of path stubs in packaged plugins
• After: fix(extension): inline agent content instead of path stubs in packaged plugins

The PR body and Fixes #785 reference were already correctly formatted. Thank you for the contribution! 🙏

[WilliamBerryiii]

Per the linked issue, I'm going to revert this back to a draft until we have some resolution from the CLI team on how to make all this work correctly.

[chaosdinosaur]

Review of PR #907 — inline agent content instead of path stubs in packaged plugins.

The core fix is sound: replacing text-stub path references with actual file content ensures Copilot CLI can parse agent YAML frontmatter in non-symlink environments. However, the change has several downstream impacts that need attention before merging:

High priority:

• Repair-PluginSymlinkIndex becomes a silent no-op since its text-stub detection heuristic will never match full file content
• Copy-Item without -Recurse won't work correctly for the shared directory sources (docs/templates, scripts/lib) passed at line 657

Medium priority:

• The existing test 'Writes text stub when SymlinkCapable is false' will fail and needs updating

Low priority:

• Dead $relativePath computation in the non-symlink branch
• Stale comments in Generate-Plugins.ps1 referencing text stubs

5 inline comments with details and suggestions.

[chaosdinosaur]

⚠️ Functional Correctness — High: Repair-PluginSymlinkIndex is now a silent no-op

Repair-PluginSymlinkIndex detects text stubs by checking for files < 500 bytes whose content matches ^\.\./ (a relative path starting with ../). With New-PluginLink now using Copy-Item, the non-symlink fallback produces full file content that will never match this heuristic — making the entire function a silent no-op.

The caller in Generate-Plugins.ps1 (line 299) still invokes it and logs "entries fixed", but nothing will ever be fixed.

Since copied files should be committed as regular files (not mode 120000 symlinks), this function likely needs to be removed entirely, along with its call site and the comment-based help that still references "text stubs containing relative paths." If git index mode repair is still needed for some other reason, the detection logic needs reworking.

[chaosdinosaur]

⚠️ Functional Correctness — High: Copy-Item on directory sources lacks -Recurse

New-PluginLink is also called for shared directories (docs/templates, scripts/lib) at line 657 in Write-PluginDirectory. Without -Recurse, Copy-Item on a directory source copies only the top-level directory, not its contents. The old WriteAllText created a single file acting as a text-based symlink — Copy-Item on a directory is fundamentally different.

Suggestion: Add directory detection:

if (Test-Path -Path $SourcePath -PathType Container) {
    Copy-Item -Path $SourcePath -Destination $DestinationPath -Recurse -Force
}
else {
    Copy-Item -Path $SourcePath -Destination $DestinationPath -Force
}

Or keep directory sources on the symlink-only path and limit Copy-Item to file sources.

[chaosdinosaur]

🔍 Functional Correctness — Medium: Existing test will fail

The test 'Writes text stub when SymlinkCapable is false' in scripts/tests/plugins/PluginHelpers.Tests.ps1 (line 233) asserts the destination file content equals the computed relative path. After this change, the destination contains the source file's actual content, not the relative path. This test will break.

Suggestion: Update the test to validate the new copy behavior:

It 'Copies file content when SymlinkCapable is false' {
    $src = Join-Path $script:linkRoot 'src-stub.txt'
    Set-Content -Path $src -Value 'content' -NoNewline
    $dest = Join-Path $script:linkRoot 'dest-stub.txt'

    New-PluginLink -SourcePath $src -DestinationPath $dest

    Test-Path $dest | Should -BeTrue
    $destContent = [System.IO.File]::ReadAllText($dest)
    $destContent | Should -Be 'content'
}

[chaosdinosaur]

💡 Code Quality — Low: Dead code — $relativePath unused in non-symlink branch

$relativePath is computed unconditionally (line 499) but only the symlink branch uses it now. Consider moving it inside the if ($SymlinkCapable) block to avoid dead code.

[chaosdinosaur]

💡 Documentation — Low: Generate-Plugins.ps1 comments reference obsolete text-stub behavior

The comment at line 296 in Generate-Plugins.ps1 reads "Fix git index modes for text stubs on non-symlink systems" and the conditional block invokes Repair-PluginSymlinkIndex. Both reference the old text-stub pattern that this PR eliminates. Should be updated or removed consistent with the resolution for Repair-PluginSymlinkIndex.