Architecture

The A2C VS Code extension is a thin client over the A2C CLI/backend. Authoritative semantics live in a2c-core; this repository owns presentation, orchestration, and host integration only.

Responsibilities

Extension (this repo)

• VS Code / Cursor / Theia-like host integration
• Commands, tree views, output channels, future webviews
• Workspace and repository context detection (heuristic markers)
• CLI process invocation, timeout, cancellation
• Transport parsing adapters (stdout → typed view models)
• Preview/approval UX shells (future)

Backend (a2c-core / bundled CLI)

• Config and artifact validation
• Planning and review workflows
• Apply/mutation rules
• Doctor, list, show, validate semantics

Layer boundaries

┌──────────────────────────────────────────────┐
│  views/ + commands/     (UI integration)     │
├──────────────────────────────────────────────┤
│  state/ + core/services (orchestration)      │
├──────────────────────────────────────────────┤
│  workspace/             (repo detection)       │
├──────────────────────────────────────────────┤
│  backend/               (CLI bridge)           │
└──────────────────────────────────────────────┘
                      │
                      ▼
              bundled / override CLI
                      │
                      ▼
                 a2c-core logic

Backend integration model

1. Resolve binary — bundled platform binary by default; optional a2c.cliPath / A2C_CLI_PATH override for development.
2. Execute command — spawn process, capture stdout/stderr/exit code, enforce timeout and cancellation.
3. Parse transport — map CLI output into extension-side DTOs. Parsers are explicit and documented; they do not infer business rules.
4. Present — tree items, output channel, notifications. No silent fallback if backend fails.

Each extension release is conceptually pinned to one backend build even before packaging automation is complete.

Workspace / status model

WorkspaceOverallStatus captures user-visible readiness:

State	Meaning
no-workspace	No folder open
not-git-repo	Folder open, no .git
git-repo-no-a2c	Git repo without A2C root markers
a2c-detected	At least one known marker found
a2c-incomplete	Marker strategy reports incomplete layout
backend-unavailable	Workspace ok but CLI probe failed

Marker detection is modular (DefaultMarkerDetectionStrategy) and aligned with a2c_core.contracts.paths.ROOT_MARKERS:

• AGENTS.md
• docs/workflow-manifest.yaml
• .a2c/config.yaml

First vertical slice

A2C: Show A2C Status orchestrates:

1. Workspace detection
2. CLI binary resolution
3. a2c version probe
4. Aggregated narrative in output channel + tree refresh

This proves the thin-client loop without embedding domain validation in TypeScript.

Growth path

Future feature	Intended home
Planning explorer	views/ + CLI list/show adapters
ADR browser	views/ + CLI list adrs --json adapter
Config editor	command/webview + CLI validate contract
AI decomposition preview	preview UI + CLI plan/apply commands
Review support	diff/preview shell + backend review outputs

Forbidden drift: schema validation, artifact mutation rules, or planning semantics implemented only in the extension.

Testing strategy

• Unit-test isolated modules: CLI locator, parsers, detection, process runner (Vitest)
• ExTester UI tour under ui-test/ for screenshot documentation (npm run ui-test, npm run screenshots:update)
• Screenshot refresh is opt-in via A2C_UPDATE_EXTENSION_SCREENSHOTS=1; GitLab job test:integration:screenshots uses xvfb

Placeholders in v0.1.0

• resources/bin/** — binary packaging slots, not populated
• Tree sections: Configuration (doctor/validate), Planning and ADR explorers (read-only via CLI list/show)
• JSON CLI contracts beyond version — documented, not yet wired