Issue Description

Summary

This issue is related to #388 and focuses on clear documentation.

Document how GitHub Copilot Coding Agent (Cloud Agent) and custom agents achieve tool parity with the local developer environment via a dedicated Copilot setup workflow, and clarify the relationship between:

• Devcontainers
• Copilot Cloud Agent
• Custom agents
• CI workflows

This documentation ensures contributors understand where tooling is defined, why duplication exists, and how to extend the setup safely.

---

Problem Statement

HVE Core now relies on two distinct—but intentionally aligned—execution environments:

1. Local development via devcontainers
2. Agent execution via GitHub Copilot Cloud Agent (GitHub Actions–backed)

While this is by design, it is not obvious to contributors that:

• Copilot Cloud Agent does not run inside the devcontainer
• The devcontainer is not reused for agent execution
• A dedicated copilot-setup-steps.yml workflow is responsible for tool parity

Without clear documentation, contributors may:

• Attempt to "fix" Copilot behavior by modifying the devcontainer
• Add ad-hoc tool installs inside agent prompts
• Duplicate setup logic across CI workflows
• Misunderstand where tooling should be added or updated

---

Why This Matters

Contributor Experience

Clear documentation reduces confusion and prevents well-intentioned but incorrect changes to the devcontainer or agent logic.

Agent Reliability

Custom agents depend on predictable tooling. Documentation ensures agents are authored against a known, stable contract.

Maintainability

By documenting a single, intentional bridge between environments, we avoid:

• Configuration drift
• Tribal knowledge
• Implicit assumptions about agent capabilities

---

Documentation Goals

This documentation should make it explicit:

• What the devcontainer is responsible for
• What the Copilot setup workflow is responsible for
• Why both exist
• How they are intentionally kept in sync
• Where contributors should make changes

---

Proposed Documentation Updates

1. Add a Dedicated Documentation Section

Add a section to the repo documentation (location TBD, e.g. docs/, CONTRIBUTING.md, or a new page) covering:

• Copilot Coding Agent execution model
• Why devcontainers are not reused by Copilot Cloud Agent
• The role of .github/workflows/copilot-setup-steps.yml
• Required job naming and behavior (copilot-setup-steps)

---

2. Define Clear Responsibilities

Document clear ownership boundaries:

Component	Responsibility
Devcontainer	Local developer experience
Copilot setup workflow	Agent tool availability
Custom agents	Orchestration & intent
CI workflows	Validation & enforcement

Emphasize that tool parity is achieved intentionally, not accidentally.

---

3. Add Contributor Guidance

Include guidance such as:

• ✅ When to update the Copilot setup workflow
• ✅ When to update the devcontainer
• ❌ When not to touch either
• ✅ How to validate changes locally vs via Copilot

---

4. Link to the Implementation Issue

Explicitly link to the implementation issue that introduces the setup workflow so readers understand:

• Where the behavior is defined
• Why it exists
• How documentation and implementation stay aligned

---

Acceptance Criteria

• Documentation clearly explains the devcontainer ↔ Copilot agent relationship
• Contributors understand why the environments are separate
• Clear guidance exists on where to add or update tools
• Custom agent authors know what tooling they can assume
• Documentation links to the Copilot setup workflow and related issues

---

Non-Goals

• ❌ Rewriting devcontainer documentation
• ❌ Duplicating GitHub Copilot official documentation
• ❌ Describing CI workflows unrelated to agent execution
• ❌ Teaching how to write custom agents (out of scope)

---

Notes / Future Considerations

• This documentation can be reused as a reference for other repos adopting HVE Core
• A short diagram could be added later to visualize environment boundaries
• If tooling is ever version‑pinned via a manifest, this doc should reference it

---

Additional Context

No response