Skip to content

Latest commit

 

History

History
355 lines (294 loc) · 27.1 KB

File metadata and controls

355 lines (294 loc) · 27.1 KB

VS Code Foundry — Design Doc (v2 — FORK architecture)

Status: APPROVED for implementation Author: Claude Code (Opus 4.7), branch vs_code_foundry Date: 2026-05-11 (rewritten after user clarification: this is a fork, not an extension of Claude Code) Forge cycle: streamlined — 5 parallel research agents + spec-review subagent; rewritten after user clarified scope


0. Scope clarification (the change from v1 → v2)

v1 of this doc assumed VS Code Foundry would install assets into ~/.claude/ (the canonical Claude Code path) and use claude --agent bob as the orchestration backend. The user clarified on 2026-05-11 that this is wrong.

v2 (this doc): VS Code Foundry is a FORK. It is a parallel, self-contained agentic workflow for VS Code + GitHub Copilot users. It:

  • Does NOT touch ~/.claude/ at any time — install, runtime, or update.
  • Does NOT require Claude Code to be installed. Users who have only VS Code + Copilot can adopt foundry without ever installing the claude CLI.
  • Does NOT modify or read the existing ~/.claude/agents/*.md files at runtime. Foundry has its own .agent.md persona files inside the fork.
  • OPTIONALLY bridges to Claude Code via a tool that's disabled out-of-box. Users who have both can opt in to delegate sub-tasks to claude if they want. Default: foundry uses Copilot subagents + Codex/Gemini CLIs for cross-model work.
  • Has its own home directory on the user's machine (default ~/.vs-code-foundry/, configurable). NOT ~/.claude/.
  • Has its own public repo for distribution (new repo OR a vs-code-foundry/ subdir in the existing agent-foundry repo). The R&D lives in /path/to/internal-rnd/vs-code-foundry/ during development.
  • Can coexist with Claude Code on the same machine. They are separate ecosystems. The user can switch between claude (terminal) and VS Code with @foundry (IDE) without either knowing about the other.

This is a clean, principled fork. From the user's perspective, "do I have Claude Code or not?" and "do I have VS Code Foundry or not?" are independent installation choices.

1. TL;DR

Build a self-contained agentic workflow for VS Code + GitHub Copilot that delivers the forge → bob → alf → pa cascade pattern (proven in Claude Code) using only VS Code Copilot's native customization primitives plus a focused Python MCP server.

Deliverables:

  • 5 custom Copilot agent files (*.agent.md) at vs-code-foundry/agents/ — full persona bodies, NOT thin wrappers
  • 1 Python MCP server at vs-code-foundry/foundry-server/ (~800-1100 LOC, stdlib JSON-RPC 2.0, MCP spec 2025-11-25 with Tasks primitive)
  • 1 skill family at vs-code-foundry/skills/vs-code-copilot-foundry/ — documentation, references, scripts
  • 4 workspace templates at vs-code-foundry/templates/AGENTS.md, .vscode/mcp.json, .github/copilot-instructions.md, .github/agents/ mirrors
  • 1 installer at vs-code-foundry/installer/install-foundry.{sh,ps1,py} — installs to user-chosen paths (NOT ~/.claude/)
  • Tests at vs-code-foundry/foundry-server/tests/ — MCP protocol contract, tool schemas, subprocess delegation, install dry-run
  • README at vs-code-foundry/README.md — what this is, who it's for, how to install
  • No VS Code extension in v1. v2 may add one for one-click install.

2. Goals

  1. Behavioral parity with Claude Code's forge → bob → alf cascade, but achieved via VS Code Copilot Chat (and Copilot CLI) using custom agents + foundry-server MCP tools.
  2. Multi-model orchestration in one chat session. User picks a Copilot model as the narrator (Opus 4.7 / GPT-5.4 / Gemini 3.1 Pro). Persona model: fallback chains handle availability. runSubagent delegates sub-tasks to other Copilot models. foundry_codex / foundry_gemini MCP tools delegate to external CLIs for deep cross-model work.
  3. Zero coupling to Claude Code. Foundry works standalone. Users without claude installed get the full experience via Copilot native + Codex CLI + Gemini CLI. The optional foundry_claude tool is OFF by default; user opts in if they have claude and want to delegate to it.
  4. Cross-tool consistency for users who do have both. Same workspace conventions (AGENTS.md, project-local progress/, docs/plans/, etc.) — so a user running claude and a user running @foundry in VS Code on the same repo see the same files and decisions.
  5. Sandbox-aware. git-cli-bridge (sibling skill, not a runtime dependency) provides patterns foundry-server reuses for Gemini/Copilot delegation under corporate egress allowlists. We don't ship git-cli-bridge as part of foundry; we just document compatibility.

3. Non-goals (v1)

  • VS Code extension. Deferred to v2.
  • Modifying anything under ~/.claude/. Off-limits.
  • Replacing Claude Code. Coexistence is the goal.
  • GitHub Cloud Coding Agent integration. v2.
  • Marketplace publication. v2.
  • Auto-generating personas from ~/.claude/agents/*.md. Drift risk; bodies are hand-authored in this fork.

4. Key research findings (validated 2026-05-11 via 5 parallel research agents)

Finding Source Impact on fork architecture
Custom agent file format = *.agent.md in .github/agents/ (workspace) or ~/.copilot/agents/ (user) Brief 02 §1 Foundry's 5 personas ship to these paths. NOT ~/.claude/agents/.
VS Code Copilot Chat 1.110+ also reads ~/.claude/agents/ and ~/.claude/skills/ IF PRESENT Brief 01 §3, Brief 02 §8a Useful for coexistence: if user has both, both surfaces work. But foundry doesn't install there.
.vscode/mcp.json uses top-level servers key, NOT mcpServers Brief 03 §1.2 Foundry's template uses servers.
MCP spec 2025-11-25 with Tasks primitive in VS Code 1.107+ Brief 03 §3 Long-running tools (forge_design, bob_execute) return Task handles instead of blocking.
128-tool ceiling per chat request Brief 03 §5 Foundry stays ~12-15 tools; safe.
Custom agents support model: ['Opus 4.7', 'GPT-5.5', ...] fallback chains Brief 02 §1, Brief 04 §A Persona files use display-name strings for portability.
runSubagent with per-call model override; max nesting 5; sub-model ≤ parent cost-tier Brief 01 §3, Brief 04 §B Foundry → forge → bob fits within depth-5; cost-tier constraint documented in multi-model.md.
BYOK GA in VS Code 1.117 (Apr 22 2026) on Business/Enterprise Brief 04 §1 Documented in byok-setup.md as the highest-fidelity multi-model path.
vscode:mcp/install?<json> deeplink (one-click install) Brief 03 §1.4 Used in foundry installer + README.
Per-token billing flips 2026-06-01 Brief 01 §0 Token-efficient persona design.
Copilot CLI v1.0.44 (May 8, 2026) with --agent, /agent, /fleet (parallel) Brief 01 §5 Foundry's CLI walk-through uses these.

5. Architecture (final, v2)

User's machine
├── ~/.vs-code-foundry/                 NEW HOME — installed by foundry installer
│   ├── server/
│   │   ├── foundry_server.py          MCP server (Python stdlib)
│   │   ├── foundry_jobs.py
│   │   ├── foundry_skills.py
│   │   ├── foundry_resources.py
│   │   └── schemas.py
│   ├── agents/                         Reference copies of the 5 persona files
│   │   ├── foundry.agent.md
│   │   ├── forge.agent.md
│   │   ├── bob.agent.md
│   │   ├── alf.agent.md
│   │   └── pa.agent.md
│   ├── version.json                    Installed version + checksum
│   └── config.json                     User preferences (path overrides, opt-in flags)
│
├── ~/.claude/                          UNTOUCHED — foundry does not install or modify
│   └── (existing Claude Code setup, if user has it)
│
└── /path/to/workspace/                 User's project (post-foundry install)
    ├── .github/
    │   ├── agents/                     Workspace-level Copilot custom agents
    │   │   ├── foundry.agent.md       Copy of ~/.vs-code-foundry/agents/foundry.agent.md
    │   │   ├── forge.agent.md
    │   │   ├── bob.agent.md
    │   │   ├── alf.agent.md
    │   │   └── pa.agent.md
    │   └── copilot-instructions.md    Workspace-specific Copilot guidance
    ├── .vscode/
    │   └── mcp.json                    foundry-server entry (servers key)
    └── AGENTS.md                       Cross-tool project conventions (read by Copilot, Codex, Gemini)

5.1 Why two copies of the agent files (~/.vs-code-foundry/agents/ AND .github/agents/)?

  • ~/.vs-code-foundry/agents/ is the source-of-truth that the foundry installer manages (atomic updates, version checksums).
  • .github/agents/ is the workspace-canonical location that VS Code Copilot discovers natively. Committed to the workspace repo so teammates get the same personas.
  • The installer copies (not symlinks) so the workspace is self-contained (works on Windows, in containers, in CI).
  • Updates: bash ~/.vs-code-foundry/upgrade.sh re-copies from ~/.vs-code-foundry/agents/ to the workspace.

5.2 The 5 custom Copilot agents (full personas, NOT wrappers)

Each *.agent.md is a complete persona definition. Bodies are written specifically for VS Code Copilot's tool surface (uses runSubagent, foundry-server/* MCP tools, native Copilot agent mode features). They are NOT derived from ~/.claude/agents/*.md at runtime, though their concept and structure mirrors those files.

File Purpose Key frontmatter Body sketch
foundry.agent.md Top-level entry. Routes by complexity. model: [Opus 4.7, GPT-5.5, Sonnet 4.6], agents: [forge, bob, alf, pa], tools: [foundry-server/*, search/*, readfile, edit/*] Read user task, classify TRIVIAL/SIMPLE/MEDIUM/COMPLEX, delegate via runSubagent or act directly.
forge.agent.md Design phase. model: [Opus 4.7, GPT-5.5], agents: [bob], tools: [foundry-server/*, search/*, web/fetch], handoffs: [{label: "Implement", agent: bob, send: false}] Triple-model design exploration: call foundry_codex + foundry_gemini for challenger/analyst output; synthesize design; offer handoff button to @bob.
bob.agent.md Execution. model: [Opus 4.7], agents: [alf], tools: [foundry-server/*, edit/*, execute/*, readfile] Read approved design from chat or docs/plans/. Decompose into WPs. For each WP, edit files and run tests via VS Code tools. Optionally invoke foundry_claude if user has opted in and the WP is highly nested.
alf.agent.md Review/evolution. model: [Opus 4.7, Sonnet 4.6], agents: [bob], tools: [foundry-server/*, search/codebase, web/fetch], handoffs: [{label: "Hand approved fixes to bob", agent: bob}] Review a target (skill / code / dependency). Evidence-first. Produce ranked findings. Offer handoff to bob for approved fixes.
pa.agent.md Task lifecycle. model: [Sonnet 4.6, Opus 4.7], agents: [forge, bob, alf], tools: [foundry-server/foundry_task_*, foundry-server/foundry_log_action], mcp-servers: [foundry] Workspace tasks, action logging, routing. Optional integration with external pa-server if user has it (separate from foundry-server).

5.3 foundry-server (Python MCP, ~800-1100 LOC)

Lives in the user's ~/.vs-code-foundry/server/ after install. Python 3.10+ stdlib JSON-RPC 2.0 over stdio. Zero non-stdlib dependencies (matches pa-server pattern).

MCP capabilities declared in initialize response:

  • protocolVersion: "2025-11-25"
  • tools.listChanged: true AND top-level tasks: {} (cover both possible spec shapes per spec-review M3; smoke-test which is accepted by VS Code 1.119 in WP-4)
  • resources.listChanged: true, resources.subscribe: true
  • sampling: {} (server can request LLM via host)

Tool surface (15 tools — 12 logical entries; foundry_task_* expands to 4 CRUD):

Tool Async (Tasks)? readOnlyHint Purpose
foundry_health no yes Backends (codex, gemini, optional claude) + version + active jobs
foundry_design yes no Spawn codex exec parallel to gemini -p for design exploration; aggregate; produce design doc
foundry_execute yes no Drive a WP loop using VS Code Copilot's runSubagent; or (opt-in) delegate to claude --agent bob
foundry_review yes no Run review against a target; produce evolution report
foundry_codex yes no codex exec --ephemeral subprocess (full Codex CLI session)
foundry_gemini yes no gemini -m gemini-3.1-pro-preview -p subprocess (full Gemini CLI session)
foundry_claude yes no OPT-IN: claude -p --output-format json subprocess. Disabled by default; enabled in ~/.vs-code-foundry/config.json
foundry_status no yes Job status by handle
foundry_cancel no no Cancel a job
foundry_skill_list no yes Enumerate skills in ~/.vs-code-foundry/skills/ (foundry's own) and optionally ~/.claude/skills/ (if exists + opt-in)
foundry_skill_invoke yes varies Inline-load a skill body as additional context for a sub-task
foundry_log_action no no Append to ~/.vs-code-foundry/actions.jsonl (foundry's own action log; NOT pa-server)
foundry_task_create / _list / _get / _update mixed varies Local SQLite task store at ~/.vs-code-foundry/tasks.db

Resources surfaced:

  • foundry://design/<workspace-path> — read design docs from workspace docs/plans/
  • foundry://agents/<name> — read foundry's own persona files (read-only display)
  • foundry://config — current foundry config + version + opt-in flags
  • foundry://tasks/<id> — local task store

Notes on the optional foundry_claude tool:

  • Disabled by default in ~/.vs-code-foundry/config.json ("enable_claude_bridge": false).
  • User opts in by editing the config or running foundry-cli enable claude-bridge.
  • When enabled, requires claude in PATH; foundry-server checks this on every invocation.
  • Used when the user has Claude Code set up AND wants to delegate a sub-task to a specific Claude agent (e.g., the existing canonical bob for contract-driven execution against existing infrastructure).
  • This is the ONE place foundry ever reads ~/.claude/ — and only via subprocess (claude reads its own config), never directly.

5.4 Skill family (documentation + scripts, lives in ~/.vs-code-foundry/skills/ after install)

File Purpose
~/.vs-code-foundry/skills/vs-code-copilot-foundry/SKILL.md Parent skill (<500 lines, cross-tool compliant — also discoverable by VS Code Copilot's skill loader at ~/.vs-code-foundry/skills/ if the user adds this path to chat.agentSkillsLocations)
references/setup-vscode-chat.md, setup-copilot-cli.md, multi-model.md, byok-setup.md, custom-agents-spec.md, mcp-tools-spec.md, troubleshooting.md, architecture.md Reference docs
scripts/ Setup, verify, generate-deeplink, version-check

5.5 Workspace templates (deployed by installer into the user's project)

Template Deploys to Purpose
AGENTS.md workspace root Cross-tool project conventions
.vscode/mcp.json workspace .vscode/ foundry-server entry + any user-side MCP servers
.github/copilot-instructions.md workspace .github/ Copilot-specific guidance
.github/agents/*.agent.md (5 files) workspace .github/agents/ Per-workspace copy of the 5 personas (so teammates get them via git)

5.6 Installer (installer/install-foundry.{sh,ps1,py})

Cross-platform. Asks the user:

  1. Where should ~/.vs-code-foundry/ live? (default ~/.vs-code-foundry/)
  2. Install to current workspace? (yes / no) — if yes, lays down AGENTS.md, .vscode/mcp.json, .github/agents/*.agent.md, .github/copilot-instructions.md
  3. Enable optional Claude Code bridge? (default no)
  4. Run post-install smoke test? (default yes)

Detects:

  • code --version (VS Code installed?)
  • copilot --version (Copilot CLI installed?)
  • codex --version (Codex CLI installed?)
  • gemini --version (Gemini CLI installed?)
  • claude --version (Claude Code installed? — only relevant if user opts into the bridge)

Generates a vscode:mcp/install?<json> deeplink for one-click MCP install.

5.7 Multi-model orchestration

Same three-layer approach as v1 of this doc, but now everything routes through foundry-owned paths:

  1. Narrator: user picks Copilot model in chat dropdown.
  2. Persona fallback chain: each *.agent.md declares model: ['Opus 4.7', 'GPT-5.5', 'Sonnet 4.6'].
  3. Sub-task delegation:
    • Lightweight critique → runSubagent to another foundry agent with different model.
    • Deep cross-CLI → foundry_codex / foundry_gemini MCP tools (spawn full external CLI session).
    • OPT-IN deep Claude → foundry_claude MCP tool (spawns claude -p if user enabled and claude in PATH).

5.8 What this does NOT touch

To be explicit:

  • ~/.claude/ (any subdirectory) — NEVER modified.
  • ~/.codex/ — NEVER modified (foundry uses codex exec as a black-box subprocess only).
  • ~/.gemini/ — NEVER modified.
  • ~/.copilot/ — installer DOES write to ~/.copilot/agents/ if the user picks "user-level install for @foundry etc." (optional flow); otherwise only ~/.vs-code-foundry/ is foundry's territory.
  • The internal-rnd project's existing skills/agents at ~/.claude/skills/ and ~/.claude/agents/ — NEVER read, written, or imported by foundry. Foundry has its own skill set inside its home.
  • The internal-rnd project's installer/ directory — that's for the Claude Code skill foundry; foundry's installer is the SEPARATE vs-code-foundry/installer/.

6. Component breakdown (R&D paths in this branch)

/path/to/internal-rnd/                            R&D project root
├── vs-code-foundry/                                       NEW FORK ROOT
│   ├── README.md                                          v0 in WP-1
│   ├── INSTALL.md                                         v0 in WP-1
│   ├── skills/
│   │   └── vs-code-copilot-foundry/
│   │       ├── SKILL.md                                   WP-1
│   │       ├── references/
│   │       │   ├── setup-vscode-chat.md                   WP-9
│   │       │   ├── setup-copilot-cli.md                   WP-9
│   │       │   ├── multi-model.md                         WP-9
│   │       │   ├── byok-setup.md                          WP-9
│   │       │   ├── custom-agents-spec.md                  WP-9
│   │       │   ├── mcp-tools-spec.md                      WP-9
│   │       │   ├── architecture.md                        WP-9
│   │       │   └── troubleshooting.md                     WP-9
│   │       └── scripts/
│   │           ├── verify-foundry-setup.sh                WP-10
│   │           └── generate-install-link.py               WP-7
│   ├── agents/                                            5 persona files
│   │   ├── foundry.agent.md                               WP-2
│   │   ├── forge.agent.md                                 WP-2
│   │   ├── bob.agent.md                                   WP-2
│   │   ├── alf.agent.md                                   WP-2
│   │   └── pa.agent.md                                    WP-2
│   ├── foundry-server/                                    Python MCP server (R&D)
│   │   ├── foundry_server.py                              WP-4 + WP-5
│   │   ├── foundry_jobs.py                                WP-6
│   │   ├── foundry_skills.py                              WP-6
│   │   ├── foundry_resources.py                           WP-6
│   │   ├── schemas.py                                     WP-4
│   │   ├── __main__.py                                    WP-4
│   │   ├── pyproject.toml                                 WP-4
│   │   └── tests/
│   │       ├── test_jsonrpc_protocol.py                   WP-8
│   │       ├── test_tool_schemas.py                       WP-8
│   │       ├── test_jobs_lifecycle.py                     WP-8
│   │       └── fixtures/                                  WP-8
│   ├── templates/                                         Workspace assets
│   │   ├── AGENTS.md.template                             WP-3
│   │   ├── .vscode/mcp.json.template                      WP-3
│   │   └── .github/
│   │       ├── copilot-instructions.md.template           WP-3
│   │       └── agents/                                    Mirror of agents/ (5 files copied at install)
│   └── installer/
│       ├── install-foundry.sh                             WP-7
│       ├── install-foundry.ps1                            WP-7
│       ├── install-foundry.py                             WP-7 (cross-platform impl)
│       └── verify-foundry-setup.sh                        WP-10
└── (rest of internal-rnd unchanged)

7. WP plan (post-fork-clarification)

WP Scope Files Lines Depends on
WP-1 Skill family scaffold (SKILL.md, README, INSTALL) 3 ~400
WP-2 5 custom Copilot agent persona files 5 ~600 (120 each) WP-1
WP-3 4 workspace templates 4 ~300 WP-1
WP-4 foundry-server MCP protocol + easy tools (health, status, cancel, skill_list, log_action, task_*) 4 ~600 WP-1
WP-5 foundry-server Tasks-primitive long-running tools (design, execute, review, codex, gemini, claude opt-in, skill_invoke) (extends WP-4) ~400 WP-4
WP-6 Extract jobs / skills / resources to separate modules if WP-4+5 exceeded ~800 LOC 3 ~300 WP-5
WP-7 Installer (sh, ps1, py) + deeplink generator 4 ~700 WP-2, WP-3
WP-8 Tests for foundry-server 4-6 ~500 WP-6
WP-9 8 reference docs 8 ~2500 WP-2, WP-3, WP-4, WP-5
WP-10 verify-foundry-setup.sh + manual smoke test 2 ~200 WP-7, WP-8
WP-11 Update history.md / tasks.md / session_control.md / PROJECT.md / index.md + final commit 5 ~150 (additions only) WP-10

Total: ~6,500 LOC across all WPs. Mostly markdown + Python stdlib. Single bob spawn target ~4-6 hours.

8. Risks (post-rewrite)

Risk Mitigation
*.agent.md frontmatter format may evolve WP-10 smoke-tests each persona in copilot --agent <name> -p "ping". Documented [UNVERIFIED] fields.
User's VS Code doesn't auto-detect ~/.copilot/agents/ (we install to workspace .github/agents/ as primary) Workspace install is the canonical primary path (per Brief 02 §1 verified). User-level is secondary.
tools.tasks: true shape vs top-level tasks: {} WP-4 declares BOTH (capability flag + top-level) and lets VS Code accept whichever it understands.
Subprocess codex / gemini not in PATH foundry_health reports per-backend; installer detects and warns. Foundry still works with subset.
Cost-tier ceiling on subagents (sub-model can't exceed parent tier) Documented in multi-model.md. Personas declare model fallback chains the average user can actually run.
128-tool ceiling Foundry is 15 tools; safe. User's other MCP servers might push past — we warn in setup docs.
Per-token billing flip on 2026-06-01 Token-efficient persona design + foundry-server foundry_status exposes consumption per job when Copilot provides it.
Drift between foundry's persona files and Claude Code's canonical bob.md/etc. By design. Fork has independent evolution. If user wants 1:1 fidelity, they enable foundry_claude bridge.
Installer destroys workspace files if user re-runs Installer always backs up to .foundry-backup/<timestamp>/ before overwriting.
~/.vs-code-foundry/ lives in user's home and may not be writable in some envs (containers, CI) Installer accepts --prefix <path> override; falls back to ${XDG_DATA_HOME}/vs-code-foundry/ then /usr/local/share/vs-code-foundry/.

9. Publishing strategy (v2 path)

When v1 ships:

  • The vs-code-foundry/ directory under internal-rnd is published either as:
    • Option A: new public repo vs-code-foundry on GitHub
    • Option B: subdirectory in the existing agent-foundry public repo (with separate README)
  • Decision deferred until v1 ships; both are easy.

The existing internal-rnd publish-to-github pipeline targets ~/.claude/skills/agent-foundry. We do NOT extend it to handle vs-code-foundry. Instead vs-code-foundry has its own minimal publish flow (likely just git push from vs-code-foundry/ to the new repo root, or a 30-line helper script).

10. Cross-references

  • ~/.claude/skills/forge/SKILL.md — Claude Code's forge skill (conceptual ancestor; foundry's forge.agent.md is an independent persona inspired by it)
  • ~/.claude/agents/{bob,alf,pa,wiki}.md — Claude Code's agents (conceptual ancestors; foundry's bob.agent.md/etc. are independent personas)
  • ~/.claude/skills/gh-copilot-cli/SKILL.md — Copilot CLI reference (foundry uses the same MCP + agent file format)
  • ~/.claude/skills/codex-orchestration/SKILL.md — cross-CLI delegation patterns (foundry-server reuses the codex/gemini subprocess pattern)
  • ~/.claude/skills/git-cli-bridge/SKILL.md — sandbox bridge (foundry inherits the pattern; not a runtime dependency)
  • ~/.claude/pa-server/pa_server.py — MCP server reference implementation pattern (foundry-server mirrors the shape)
  • research/vs-code-copilot-2026/{01..05}-*.md — 5 research briefs driving this design
  • research/vs-code-copilot-2026/foundry-server-sketch.md — implementation reference

11. Bob spawn briefing (when v1 implementation starts)

When bob is spawned for implementation:

  • Working tree: /path/to/internal-rnd/ on branch vs_code_foundry
  • Target directory: /path/to/internal-rnd/vs-code-foundry/ (this is the fork root; everything goes here)
  • NEVER touch: ~/.claude/, ~/.codex/, ~/.gemini/, ~/.copilot/, or the internal-rnd project's installer/ (top-level — that's for Claude Code skill publishing)
  • Reference implementation: ~/.claude/pa-server/pa_server.py (read-only; pattern to mirror for foundry-server)
  • HARD-RULES:
    • Cross-tool portability rules apply to vs-code-foundry/skills/vs-code-copilot-foundry/SKILL.md (run ~/.claude/skills/research-for-skills/cross-tool-portability/scripts/verify-skill-portability.sh against it)
    • No Co-Authored-By: Claude lines in commit messages
    • Stash before destructive operations
    • One commit per WP (or every 30-60 min)
    • Tests must pass before declaring a WP done
  • Tool count limit: be aware of the 128-tool ceiling per chat request (foundry must stay ≤20 tools)
  • Spec review feedback applied: see docs/reviews/2026-05-11-vs-code-foundry-spec-review.md for M1/M2/M3 remediations
    • M1: install to .github/agents/ (workspace) as primary path; ~/.copilot/agents/ user-level as secondary
    • M2: 15 tools (12 logical entries; foundry_task_* is 4)
    • M3: declare both tools.tasks: true AND top-level tasks: {} in initialize response, let client accept whichever