# 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](docs/implementation-plan.md). The architecture boundary is in [docs/architecture.md](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.

```powershell
# 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:

```bash
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:

| Target | Root path | Validation | Branch strategy |
|--------|-----------|------------|-----------------|
| **control** | `C:\CatastroSwitch` | Schema/sample validation, script syntax | Feature branches from `main` |
| **runtime** | `C:\src\vscode-multiagent` | `compile-check-ts-native`, `valid-layers-check`, targeted tests | Feature branches from `catastroswitch` |

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

| Scope | Commands |
|-------|----------|
| Control repo schemas/examples | Validate samples against schemas |
| Control repo scripts | `pwsh -NoProfile -Command "& { . .\scripts\<name>.ps1 -WhatIf }"` |
| Runtime fork `src/` | `npm run compile-check-ts-native` |
| Runtime fork `extensions/` | `npm run gulp compile-extensions` |
| Runtime fork layering | `npm run valid-layers-check` |
| Runtime fork unit tests | `scripts\test.bat --grep <pattern>` |
| Runtime fork integration tests | `scripts\test-integration.bat` |
| Runtime fork browser tests | `npm run test-browser-no-install -- --run <path>` |

## 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)