VS Code Foundry

A self-contained agentic workflow for VS Code + GitHub Copilot that delivers a disciplined design → build → review cascade using Copilot's native customization stack (custom agents, agent skills, MCP) plus two small Python MCP servers.

Status: v0.3.0 shipped 2026-05-18. Tested against Copilot CLI 1.0.44, VS Code 1.119, MCP spec 2025-11-25.

v0.3.0 ships with KIT, a personal-os subsystem providing the @kit universal-altitude persona for cross-workspace task tracking, day planning, and queued cross-window prompts. It merges in the former vs-code-personal-os project (subtree merge, full history preserved). See personal-os/PROJECT.md for the subsystem.

What this is

If you've used Claude Code's forge → bob → alf → pa cascade and wished you could get the same discipline inside VS Code with Copilot, this is for you. Foundry brings the pattern over to VS Code's customization primitives — no Claude Code installation required.

You get six custom Copilot agents you can call by name in chat:

• @foundry — top-level router. Classifies your task and delegates.
• @forge — design exploration with parallel Codex/Gemini challenger output.
• @bob — execution. Reads an approved design, decomposes into work packages, edits files, runs tests.
• @alf — review. Surfaces drift, stale dependencies, missing tests; hands approved fixes back to bob.
• @pa — task lifecycle. Local task store, action logging, routing.
• @kit (v0.3.0+) — universal-altitude command desk. Cross-workspace task tracking, daily morning brief, queued cross-window prompts. Sits above the coding cascade; can call into it.

Behind these are two MCP servers (v0.3.0+):

• foundry-server — exposes 15 tools for cross-model orchestration (Codex CLI for GPT-5.4 challenger work, Gemini CLI for analyst work, optional Claude CLI bridge if you have it).
• personal-os-server — exposes 14 KIT tools (kit_status, kit_refresh, kit_task_*, kit_queue_prompt, kit_outbox_show, kit_inbox_*, ...). State lives under ~/.vs-code-foundry/personal-os/.

Microsoft Agent Skills alignment (v0.2.0+)

On 2026-05-13 Microsoft announced Agent Skills in Visual Studio (Insiders), standardizing on the agentskills.io spec — the same spec Foundry adopted in v0.1.x. Foundry v0.2.0 installs its skill family to the MS-standardized global path (~/.copilot/skills/) so VS Copilot, VS Code Copilot, and any agentskills.io-conformant client auto-discovers it natively. The workspace installer also scaffolds <workspace>/.github/skills/ for project-specific skills. See PROJECT.md for the full relationship breakdown.

What this is NOT

• Not a Claude Code replacement. Claude Code (the claude CLI) is a separate, excellent tool. Foundry coexists with it. If you have Claude Code installed and want sub-tasks to delegate to it, enable the optional bridge.
• Not a VS Code extension. v1 is file-based. Install puts agent definitions in .github/agents/, MCP config in .vscode/mcp.json, server in ~/.vs-code-foundry/. v2 may ship an extension for one-click setup.
• Not modifying ~/.claude/. Anywhere. Ever.

Quick install

# 1. Clone (TBD: actual public URL once published)
git clone https://github.com/<owner>/vs-code-foundry ~/vs-code-foundry-src
cd ~/vs-code-foundry-src

# 2. Run the installer (interactive — asks where to put things)
bash installer/install-foundry.sh

# 3. In your project workspace, open VS Code, start Copilot Chat (Ctrl+Alt+I)
#    Pick a model (Claude Opus 4.7 recommended for the narrator).
#    Type: @foundry health
#    Expect: a backends + active jobs report.

# 4. Then try the real thing:
#    @foundry build a small CLI tool that prints HELLO
#    (Watch forge run, then bob build it, all in one chat thread.)

For a full walkthrough see INSTALL.md.

Architecture in one diagram

Your VS Code + Copilot Chat
│
├─ Model picker: Opus 4.7 / GPT-5.4 / Gemini 3.1 Pro / ...
│
├─ @foundry.agent.md      ← installed by foundry installer at
├─ @forge.agent.md           .github/agents/ (workspace) AND
├─ @bob.agent.md             ~/.vs-code-foundry/agents/ (user)
├─ @alf.agent.md
├─ @pa.agent.md
└─ @kit.agent.md          ← v0.3.0: universal-altitude command desk
       │
       │ MCP tool calls (namespaced per server)
       ▼
foundry-server (Python, ~/.vs-code-foundry/server/)
       │
       ├─ subprocess: codex exec   (GPT-5.4 — for challenger / research)
       ├─ subprocess: gemini -p    (Gemini 3.1 Pro — for analyst / brainstorm)
       └─ OPT-IN: claude -p        (Claude — if user enabled the bridge)

personal-os-server (Python, ~/.vs-code-foundry/personal-os/server/)
       │
       └─ State subtree: ~/.vs-code-foundry/personal-os/
            kit.db, events.jsonl, state/, outbox/<ws>/, inbox/<ws>/

~/.claude/ is never touched by any of this.

Requirements

Required	Version	Notes
VS Code	1.107+	MCP spec 2025-11-25 with Tasks primitive (needed for long-running tools)
GitHub Copilot (any plan)	current	Pro+ recommended for Opus 4.7 access
Python	3.10+	For foundry-server. Standard library only — no pip deps.

Recommended (cross-model orchestration)
GitHub Copilot CLI	1.0.44+	For copilot --agent ... headless mode
Codex CLI (codex)	0.118+	GPT-5.4 challenger via foundry_codex tool
Gemini CLI (gemini)	0.36+	Gemini 3.1 Pro analyst via foundry_gemini tool

Optional (cross-tool bridge)
Claude Code (claude)	2.1.x+	Required IF you enable foundry_claude bridge tool (off by default)

What goes where

After install, several locations matter:

Location	What's there	Why
~/.vs-code-foundry/server/	foundry-server Python MCP server	foundry-server runs as a subprocess of VS Code Copilot
~/.vs-code-foundry/personal-os/server/	personal-os-server Python MCP server (v0.3.0+)	personal-os-server runs as a second co-registered MCP subprocess
~/.vs-code-foundry/personal-os/	KIT state subtree (kit.db, events.jsonl, state/, outbox//, inbox//)	v0.3.0+; can be relocated via PERSONAL_OS_HOME env var
~/.vs-code-foundry/agents/	Source-of-truth persona files (6 personas as of v0.3.0)	Updated by foundry's upgrade script
~/.copilot/skills/vs-code-copilot-foundry/	Foundry's vs-code-copilot-foundry skill family	MS-standardized global path (v0.2.0+). Auto-discovered by VS Copilot / VS Code Copilot natively.
~/.vs-code-foundry/skills/vs-code-copilot-foundry	Backward-compat symlink → canonical location	Created automatically by v0.2.x installer; removable in v0.3.x
<your-workspace>/.github/agents/*.agent.md	Workspace copies of personas	What VS Code Copilot actually loads when you type @foundry / @kit
<your-workspace>/.github/skills/	Workspace skills scaffold (drop project-specific SKILL.md files here)	MS-standardized workspace path (v0.2.0+)
<your-workspace>/.vscode/mcp.json	MCP server config	How VS Code starts foundry-server
<your-workspace>/AGENTS.md	Cross-tool project conventions	Read by Copilot, Codex CLI, Gemini CLI, etc.
<your-workspace>/.github/copilot-instructions.md	Workspace Copilot guidance	Always-on context for Copilot in this project

Multi-model in one chat

Pick a model in the Copilot dropdown — that's your "narrator." Each foundry agent declares a fallback chain in its frontmatter:

model:
  - Claude Opus 4.7 (anthropic)   # primary
  - GPT-5.5 (openai)              # fallback
  - Claude Sonnet 4.6 (anthropic) # last resort

Sub-tasks within a foundry workflow can use different models via:

• runSubagent (native Copilot, with cost-tier constraint: sub ≤ parent)
• foundry_codex MCP tool (delegates to Codex CLI / GPT-5.4 — full external session)
• foundry_gemini MCP tool (delegates to Gemini CLI / Gemini 3.1 Pro — full external session)
• foundry_claude MCP tool (OPT-IN: delegates to Claude CLI — full external session)

For the highest-fidelity multi-model experience (your own Anthropic / OpenAI / Google keys plugged into Copilot), see BYOK setup. Requires Copilot Business or Enterprise.

License + non-affiliation

Foundry is open-source (LICENSE TBD: likely MIT to match agent-foundry). It is not affiliated with GitHub, Microsoft, Anthropic, OpenAI, or Google. Custom agents and MCP servers are documented extension points; this project uses them.

Status / changelog

• v0.3.0 (2026-05-18) — vs-code-personal-os subtree-merged in; KIT (@kit universal-altitude persona) ships alongside forge/bob/alf/pa; two-MCP-server topology by default; AGENTS.md reconciled to R1-R13.
• v0.2.0 (2026-05-15) — Microsoft Agent Skills alignment (skill family relocated to ~/.copilot/skills/).
• v0.1.x (2026-05-11..13) — initial release, Windows hardening, Codex bugfix bundle, CHANGELOG + CI.

See CHANGELOG.md for the full per-release notes and history.md for session-level context.