AGENTS.md

Project Overview

CatastroSwitch is a machine-local workspace switching control plane built inside a VS Code fork. The project uses a two-repo architecture:

• Control repo (C:\CatastroSwitch): Durable docs, schemas, contracts, workflow agents, prompts, branding sources, and bootstrap scripts. No runtime product code lives here.
• Runtime fork (C:\src\vscode-multiagent on the catastroswitch branch): A fork of microsoft/vscode carrying CatastroSwitch product changes. The fork tracks microsoft/vscode as upstream and carries product changes on a long-lived catastroswitch branch.

The implementation roadmap is in docs/implementation-plan.md. The architecture boundary is in docs/architecture.md.

Setup

Control repo

PowerShell 7 (pwsh) required. The control repo uses helper scripts for fork bootstrap, workspace generation, branding export, and upstream sync.

# Bootstrap the VS Code fork locally
.\scripts\bootstrap-vscode-fork.ps1

# Generate the local maintenance workspace
.\scripts\generate-local-workspace.ps1

# Export product icons from logo.svg
.\scripts\export-product-icons.ps1

Runtime fork

Node.js 20+ required. After bootstrap, the runtime fork follows standard VS Code development:

cd C:\src\vscode-multiagent
npm install
npm run compile-check-ts-native   # Type-check src/ changes
npm run valid-layers-check        # Verify architectural layering

When editing the runtime fork, also read C:\src\vscode-multiagent\AGENTS.md and C:\src\vscode-multiagent\.github\copilot-instructions.md for VS Code-specific conventions.

Repository Structure

Control repo

CatastroSwitch/
├── assets/logo.svg              # Canonical branding source
├── docs/
│   ├── implementation-plan.md   # Durable roadmap (only source of truth)
│   └── architecture.md          # Boundary and integration rules
├── schemas/                     # Machine-readable contracts
│   ├── workspace-registry.schema.json
│   └── agent-session-snapshot.schema.json
├── examples/                    # Sample payloads for contracts
├── scripts/                     # Bootstrap and maintenance entrypoints
├── .github/
│   ├── agents/                  # Workflow agent definitions
│   ├── prompts/                 # Workflow entry prompts
│   ├── skills/                  # Repository-specific skills
│   ├── instructions/            # File-scoped instructions
│   └── copilot-instructions.md  # Workspace-wide Copilot guardrails
└── AGENTS.md                    # This file

Runtime fork

CatastroSwitch product code lives under src/vs/workbench/contrib/catastroswitch/ and related seams in the VS Code codebase. The fork has its own conventions — see the fork's AGENTS.md and copilot-instructions.md for VS Code-specific rules.

Two-Repo Workflow

Every planned task must specify which repo it targets:

Agents must not mix control-repo changes with runtime-fork changes in the same task unless explicitly justified.

Git Workflow

Control repo

• Feature branches from main: feature/<short-description>, fix/<short-description>.
• Small, focused PRs with merge commits.
• Direct commits on main are blocked unless CATASTROSWITCH_ALLOW_MAIN_COMMIT=1 is set.

Runtime fork

• Feature branches from catastroswitch: feature/<short-description>.
• main tracks upstream microsoft/vscode — never commit product changes to main.
• catastroswitch is the product branch — periodically rebased onto refreshed main.
• Upstream sync: .\scripts\sync-upstream-and-rebase.ps1.

Agent Behavior

• Strive for concise, simple solutions — prefer the simplest implementation that correctly solves the problem.
• Propose simpler alternatives — if a problem can be solved in a simpler way than what was asked, state it before implementing.
• Stop when scope is too large — if asked to do too much in one request, stop and clearly state what is too much before proceeding.
• Respect the boundary — control-repo agents that need to edit runtime code must read the runtime fork's own AGENTS.md and copilot-instructions.md first.

Conventions

Control repo

• No mutable execution-state JSON — docs/implementation-plan.md is the only roadmap. When a JSON contract needs to point back, use planPath.
• Additive-first — prefer new CatastroSwitch-specific files over modifying shared surfaces.
• Machine-local model — workspaces, sessions, switch history, and agent status are all machine-local, not window-local or cloud-synced.
• Schema-driven contracts — workspace routing and session monitoring use JSON Schema contracts in schemas/.
• PowerShell 7 — scripts use pwsh features (ConvertFrom-Json -Depth 32, etc.). Do not assume Windows PowerShell compatibility.

Runtime fork (summary; defer to fork's own docs for details)

• TypeScript with tabs — VS Code convention, not spaces.
• Narrow core seams — surgical changes to VS Code internals, broad changes in CatastroSwitch-specific modules.
• Same-window switching — the UI uses same-window workspace switching, not new windows.
• Disposable hygiene — register disposables immediately; use DisposableStore, MutableDisposable.
• Service injection — constructor injection only; no service locator.
• Localization — all user-facing strings via nls.localize().
• No npm run compile — use npm run compile-check-ts-native for type-checking src/ changes.

Validation Matrix

CI and Copilot Guardrails

• .github/copilot-instructions.md — workspace-wide Copilot guardrails for grounding, validation, and repo conventions
• .github/instructions/ — file-scoped instructions for specific file surfaces
• .github/skills/catastroswitch-phase-quality/SKILL.md — phase audit and implementation quality workflow
• .github/agents/ — workflow agent definitions (Orchestrator, Planner, CodingAgent, Reviewer, Gatekeeper, Phase Gatekeeper, Phase Auditor, Researcher)
• .github/prompts/ — workflow entry prompts (run-phase, implement-task, gate-stage, phase-gate)