Issue Description

Summary

This issue helps us prepare for further usage of GitHub Cloud Agents.

Ensure that GitHub Copilot Coding Agent (Cloud Agent) and custom agents can use the same tools and versions as the local developer environment defined by the HVE Core devcontainer—without modifying the devcontainer itself.

This issue documents why this parity is required and how to implement it using a dedicated Copilot setup workflow.

---

Problem Statement

HVE Core defines a rich, well-scoped local development environment via a devcontainer, including:

• Node.js (LTS) and npm-based tooling
• Python 3.11
• PowerShell 7
• Security and quality tools (e.g. gitleaks, checkov, shellcheck, markdown tooling)
• Repo-specific npm and PowerShell scripts

However, GitHub Copilot Coding Agent runs in an ephemeral GitHub Actions environment that does not automatically inherit the devcontainer configuration.

As a result:

• Copilot Cloud Agent may be missing required tools
• Repo scripts (npm run lint:*, PowerShell-based checks, security scans) may fail or behave differently
• Custom agents become environment-dependent and unreliable
• Copilot-generated PRs cannot be trusted to match local developer behavior

This creates a tooling mismatch between:

• Local developers (devcontainer)
• CI workflows
• GitHub Copilot Cloud Agent and custom agents

---

Why This Matters

Consistency and Trust

Copilot Cloud Agent must be able to run the same commands and the same checks as human contributors to be treated as a first-class collaborator.

Reliable Custom Agents

Custom agents rely on predictable tooling to:

• Execute structured workflows
• Run repo-specific scripts
• Perform validation and security analysis

Without parity, agent behavior becomes non-deterministic.

Clear Separation of Responsibilities

We explicitly do not want to:

• Duplicate or refactor the devcontainer
• Move devcontainer logic into CI
• Maintain multiple “definitions” of the dev environment

Instead, we need a documented bridge between the devcontainer and Copilot’s execution environment.

---

Proposed Solution

Introduce a Copilot setup workflow that runs before the Copilot Cloud Agent starts work and installs the same core tooling as the devcontainer.

Key characteristics:

• Lives at: .github/workflows/copilot-setup-steps.yml
• Contains exactly one job named copilot-setup-steps (required by Copilot)
• Runs on a GitHub-hosted runner
• Installs tools needed by:
  • Built-in GitHub Copilot Cloud Agent
  • HVE Core custom agents
• Does not modify the devcontainer

This workflow becomes the contract that guarantees tool availability for all agent-based automation.

---

Implementation Plan

1. Add Copilot Setup Workflow

Create .github/workflows/copilot-setup-steps.yml with the following responsibilities:

• Checkout repository
• Install Node.js (LTS) and run npm ci
• Install Python 3.11
• Ensure PowerShell 7 is available
• Install required CLI tools (e.g. Azure CLI, shellcheck, gitleaks, checkov, mermaid-cli)
• Optionally emit tool versions for diagnostics

This mirrors capabilities, not implementation details, of the devcontainer.

---

2. Document the Rationale

Explicitly document:

• Why the devcontainer is not reused by Copilot Cloud Agent
• Why this workflow exists
• That this workflow is the single source of truth for agent tooling
• That custom agents must assume tooling is provided via this setup step

This prevents future contributors from:

• Attempting to “fix” Copilot by editing the devcontainer
• Adding ad-hoc installs inside agent prompts or unrelated workflows

---

3. Align Custom Agents to the Contract

Ensure that:

• Custom agents rely on repo scripts (npm run …, PowerShell scripts) rather than reimplementing logic
• Agent instructions assume tools are present after setup
• Agent failures are reproducible locally via the devcontainer

---

Acceptance Criteria

• Copilot Cloud Agent can run existing repo scripts without missing-tool failures
• PowerShell-based linting and validation scripts execute successfully
• Security tools (e.g. gitleaks, checkov) are available to agents
• No changes are required to .devcontainer/devcontainer.json
• Clear documentation explains the devcontainer ↔ Copilot environment bridge
• Custom agents behave consistently across local dev, CI, and Copilot Cloud Agent

---

Non-Goals

• ❌ Refactoring or simplifying the devcontainer
• ❌ Replacing devcontainer logic with CI logic
• ❌ Introducing multiple competing environment definitions
• ❌ Installing tools dynamically inside agent prompts

---

Notes / Future Considerations

• This pattern can be reused across other repositories adopting HVE Core
• Larger or self-hosted runners can be introduced later if needed
• Tool version pinning strategies (e.g. manifests or version managers) can be layered on top without changing the devcontainer

Related documentation: https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment?tool=webui

---

Additional Context

No response