Summary

hve-core artifacts (agents, instructions) are already largely compatible with GitHub Copilot CLI because they are markdown files in .github/. However, several VS Code-specific UX features used across agents and prompts have no CLI equivalent, and CLI-specific documentation is missing. This issue tracks the work to close those gaps.

Full research: .copilot-tracking/research/2026-02-10-copilot-cli-support-research.md

What Already Works

Gaps to Close

HIGH severity

• Prompt files not supported in CLI — 23 prompt files use ${input:} variables and agent: delegation, neither of which exist in CLI. High-value prompts should be converted to agents or documented as VS Code-only.
• Handoffs between agents — 7 agents use handoffs: for interactive workflow chaining (VS Code chat buttons). CLI has no equivalent. Agent bodies need text-based continuation instructions for CLI users.
• ${input:variableName} template variables — Extensive use across prompts. Resolved by converting prompts to agents where users pass parameters as natural language.

MEDIUM severity

• #file: context injection — 3 agents and 9 prompts use #file: references. Replace with prose instructing the agent to read the file directly.
• runSubagent availability — 8 agents depend on this VS Code tool. CLI support is unknown. Document as environment-dependent.
• VS Code-specific tool names — 4 agents declare tools: arrays with VS Code-namespaced identifiers. CLI ignores unrecognized tool names.
• Skills format verification — hve-core uses SKILL.md; CLI may require skill.json. Needs verification.

Recommended Work (Priority Order)

1. Documentation (low effort, high impact) — Create docs/getting-started/methods/cli.md setup guide; add CLI workflow section to docs/rpi/README.md
2. Agent body adaptation (medium effort, high impact) — Add environment-agnostic continuation instructions to 7 handoff agents and replace #file: references in 3 agents
3. Prompt-to-agent conversion (medium effort, medium impact) — Convert high-value VS Code-only prompts (e.g., github-add-issue, git-commit) to dual-purpose agents
4. target schema extension (low effort, low impact) — Add "cli" to target enum in agent frontmatter schema; mark hve-core-installer as target: vscode
5. CLI MCP configuration guide (low effort, medium impact) — Document MCP server setup for CLI users
6. Hooks support (low effort, low impact) — Explore pre-built hooks for validation/linting/security

Related Issues

• fix(agents): Custom agents not discovered by GitHub Copilot CLI without manual symlink #392 — Custom agents not discovered by Copilot CLI without manual symlink
• fix(agents): maturity, etc. are not supported frontmatter for agents in copilot CLI #360 — Custom agent frontmatter fields not supported by Copilot CLI

Open Questions

• Does CLI discover SKILL.md or require skill.json?
• Are .github/prompts/*.prompt.md consumed by CLI at all?
• Does CLI parse the full agent frontmatter (tools, handoffs, mcp-servers)?
• Does .github-private support instructions and skills, or agents only?