Peer Directory Clone Installation

Peer Directory Clone places HVE Core as a sibling folder next to your project. This is the simplest method for developers working with local VS Code without devcontainers.

When to Use This Method

✅ Use this when:

• You're using local VS Code (no devcontainer)
• You're working solo on a project
• You want the simplest possible setup
• You're developing or testing HVE Core itself

❌ Consider alternatives when:

• You use devcontainers → Git-Ignored Folder or Mounted Directory
• You use Codespaces → GitHub Codespaces
• Your team needs version control → Submodule
• You need paths that work everywhere → Multi-Root Workspace

How It Works

HVE Core is cloned into a sibling directory. Your project's VS Code settings reference it using relative paths.

projects/
├── my-project/              # Your project
│   └── .vscode/
│       └── settings.json    # Points to ../hve-core
│
└── hve-core/                # Sibling directory
    └── .github/
        ├── agents/
        ├── prompts/
        └── instructions/

Quick Start

Install the complete HVE Core VS Code extension for the fastest setup. For guided installation-method selection, MCP configuration, or selective clone adoption, ask an agent to use the included hve-core-installer skill. Use the manual steps below for direct configuration.

Manual Setup

Step 1: Clone HVE Core

Open a terminal in your project's parent directory:

# Navigate to parent of your project
cd /path/to/projects

# Clone HVE Core as a sibling
git clone https://github.com/microsoft/hve-core.git

Your directory structure should now look like:

projects/
├── my-project/
└── hve-core/

Step 2: Update VS Code Settings

Create or update .vscode/settings.json in your project:

{
  "chat.agentFilesLocations": {
    "../hve-core/.github/agents/ado": true,
    "../hve-core/.github/agents/data-science": true,
    "../hve-core/.github/agents/design-thinking": true,
    "../hve-core/.github/agents/github": true,
    "../hve-core/.github/agents/project-planning": true,
    "../hve-core/.github/agents/hve-core": true,
    "../hve-core/.github/agents/hve-core/subagents": true,
    "../hve-core/.github/agents/security": true
  },
  "chat.promptFilesLocations": {
    "../hve-core/.github/prompts/ado": true,
    "../hve-core/.github/prompts/design-thinking": true,
    "../hve-core/.github/prompts/github": true,
    "../hve-core/.github/prompts/hve-core": true,
    "../hve-core/.github/prompts/security": true
  },
  "chat.instructionsFilesLocations": {
    "../hve-core/.github/instructions/ado": true,
    "../hve-core/.github/instructions/coding-standards": true,
    "../hve-core/.github/instructions/github": true,
    "../hve-core/.github/instructions/hve-core": true,
    "../hve-core/.github/instructions/shared": true
  },
  "chat.agentSkillsLocations": {
    "../hve-core/.github/skills": true,
    "../hve-core/.github/skills/accessibility": true,
    "../hve-core/.github/skills/shared": true,
    "../hve-core/.github/skills/coding-standards": true,
    "../hve-core/.github/skills/data-science": true,
    "../hve-core/.github/skills/design-thinking": true,
    "../hve-core/.github/skills/hve-core": true,
    "../hve-core/.github/skills/installer": true,
    "../hve-core/.github/skills/project-planning": true,
    "../hve-core/.github/skills/rai": true,
    "../hve-core/.github/skills/rpi": true,
    "../hve-core/.github/skills/security": true
  }
}

Step 3: Validate Installation

Verify HVE Core directories are accessible:

ls ../hve-core/.github/agents

You should see .agent.md files. Then validate in VS Code:

1. Reload VS Code window (Ctrl+Shift+P → "Developer: Reload Window")
2. Open GitHub Copilot Chat (Ctrl+Alt+I)
3. Click the agent picker dropdown
4. Verify RPI Agent and Documentation appear, then confirm /rpi-research is available

Updating HVE Core

To get the latest version:

cd ../hve-core
git pull

No VS Code restart required. Changes take effect immediately.

Troubleshooting

Agents Not Appearing

Check the relative path

# From your project directory
ls ../hve-core/.github/agents

If the path doesn't resolve, verify:

1. HVE Core is cloned at the correct location
2. Your terminal is in your project directory
3. The relative path in settings.json is correct

Check VS Code settings

1. Open Command Palette (Ctrl+Shift+P)
2. Type "Preferences: Open User Settings (JSON)"
3. Verify no conflicting settings override your workspace settings

Path Breaks After Moving Project

Relative paths break if your project moves. Options:

1. Re-clone HVE Core next to the new location
2. Update settings.json with the new relative path
3. Switch to Multi-Root Workspace for portable paths

Doesn't Work in Devcontainer

Peer directory clone doesn't work in devcontainers because the container can't access files outside the mounted workspace.

Solutions

• Use Git-Ignored Folder for self-contained installation
• Use Mounted Directory to share HVE Core across projects
• Use Multi-Root Workspace for the most portable solution

Limitations

Aspect	Status
Devcontainers	❌ Not supported
Codespaces	❌ Not supported
Team sharing	⚠️ Each developer clones separately
Portable paths	⚠️ Breaks if project moves
Version pinning	⚠️ Manual (use git checkout)
Setup complexity	✅ Very simple
Update process	✅ Just git pull

Next Steps

• Your First Workflow - Try HVE Core with a real task
• Multi-Root Workspace - Upgrade to portable paths
• Submodule - Add version control for teams

---

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.