fix(agents): Custom agents not discovered by GitHub Copilot CLI without manual symlink

[WilliamBerryiii]

Component

Custom Agents

Bug Description

Custom agents defined in HVE-Core's .github/agents/ folder are not automatically discovered by GitHub Copilot CLI. Users must manually create a symlink or junction from their consuming project's .github/agents/ folder to the HVE-Core .github/agents/ path for the CLI to detect and use the agents.

This affects users who:

• Install HVE-Core via the VS Code extension (agents packaged in extension, not in workspace)
• Use clone-based installation but work in a separate project workspace
• Want to use HVE-Core agents from Copilot CLI in any project

Root Cause Analysis

VS Code Extension Installation:
The VS Code extension packages agents as contribution points, making them available to VS Code's Copilot Chat. However, Copilot CLI performs its own file-system scan for .github/agents/*.agent.md files within the current working directory. The extension's contribution mechanism doesn't create these files in the user's project.

Clone-Based Installation:
When HVE-Core is cloned as a peer directory, submodule, or mounted folder, the agents exist in the HVE-Core workspace but not in the consuming project's .github/agents/ folder. Multi-root workspace configurations help VS Code discover them, but Copilot CLI only scans the current directory tree.

Discovery Mechanism Difference:

Environment	Discovery Method	HVE-Core Agents Visible?
VS Code Copilot Chat	Extension contribution points + workspace scan	✅ Yes
Copilot CLI	File system scan of $(pwd)/.github/agents/	❌ No (without symlink)

Expected Behavior

Custom agents from HVE-Core should be detected by GitHub Copilot CLI without requiring manual symlink/junction creation when:

1. The HVE-Core VS Code extension is installed
2. HVE-Core is configured via any supported installation method (submodule, peer clone, multi-root workspace)

Steps to Reproduce

1. Install HVE-Core via VS Code extension
2. Open a terminal in any project directory
3. Run gh copilot or use Copilot CLI commands
4. Attempt to use an HVE-Core agent (e.g., task-researcher)
5. Observe: Agent is not available

Verification:

# Check if agents are in expected location
ls .github/agents/
# Result: Empty or directory doesn't exist

# VS Code shows agents in picker, but CLI doesn't find them

Workaround

Create a symlink or junction from the consuming project's .github/agents/ folder:

Windows (PowerShell as Administrator):

# Junction (recommended for Windows)
New-Item -ItemType Junction -Path ".\.github\agents" -Target "C:\path\to\hve-core\.github\agents"

# Symlink (requires Developer Mode or admin)
New-Item -ItemType SymbolicLink -Path ".\.github\agents" -Target "C:\path\to\hve-core\.github\agents"

macOS/Linux:

# Create symlink
ln -s /path/to/hve-core/.github/agents .github/agents

Note: After creating the symlink, you may encounter issue #360 (unsupported frontmatter fields like maturity and handoffs).

Potential Solutions to Consider

1. Documentation Update: Document the symlink workaround in installation guides with platform-specific instructions

2. Installer Agent Enhancement: Extend hve-core-installer agent to optionally create the symlink during installation

3. CLI-Compatible Agent Variants: Generate stripped-down agent files without unsupported frontmatter for CLI use

4. Post-Install Script: Add an npm script or PowerShell script to set up CLI compatibility symlinks

5. Multi-Root Workspace Export: For multi-root workspace installations, provide a script to export agents to the primary workspace

Related Issues

• fix(agents): maturity, etc. are not supported frontmatter for agents in copilot CLI #360: Custom agent frontmatter (maturity, handoffs, argument-hint) not supported by Copilot CLI - Users who resolve this discovery issue will immediately encounter the frontmatter compatibility issue

Environment

• Copilot CLI version: v0.0.400-0 (prerelease)
• VS Code: 1.106+
• HVE-Core: Extension and clone-based installations affected
• OS: Windows, macOS, Linux (all affected)

[WilliamBerryiii]

@agreaves-ms FYI