CLI contracts used by the extension

The extension treats the A2C CLI as the authoritative engine. These contracts are the first slice wired in v0.1.0; additional commands will gain explicit parsers and documentation before UI features depend on them.

Binary resolution

Mode	Source	Notes
Production default	resources/bin/<platform>/a2c[.exe]	One binary per extension release
Developer override	a2c.cliPath setting	Advanced/local only
Developer override	A2C_CLI_PATH env var	Takes precedence over setting

C4 JSON envelope

When --json is passed, commands emit a single top-level object:

{
  "ok": true,
  "command": "repo.validate",
  "version": "0.3.0",
  "data": {},
  "errors": [],
  "warnings": []
}

Authoritative schema: a2c-workflow initial-contracts.md (C4).

Extension adapter: src/backend/parsers/envelopeParser.ts

a2c version (implemented)

Invocation:

a2c version

Working directory: optional A2C repository root (--path not passed in v0.1.0; version is global).

Expected stdout (single line):

a2c-core <semver>

Exit code: 0 on success.

Extension adapter: src/backend/parsers/versionParser.ts

a2c doctor --json (implemented)

Field	Value
command	repo.doctor
data.root	Repository root path or null
data.healthy	true when all checks pass
data.checks	{ name, ok, message }[]

Extension: BackendClient.runDoctor(), inspectRepository()

a2c validate --json (implemented)

Field	Value
command	repo.validate
data.summaries	{ kind, parsed, loader_errors }[] per artifact type
errors / warnings	Validation issues with code, message, optional path

Extension: BackendClient.runValidate(), inspectRepository()

a2c list <kind> --json (implemented)

Command	command field
list epics	artifact.list.epics
list tasks	artifact.list.tasks
list sprints	artifact.list.sprints
list adrs	artifact.list.adrs

data.items contains planning artifact models (id, type, title, status, …) and relative_path to the Markdown source file. data.count is item length.

Extension: BackendClient.listEpics|listTasks|listSprints|listAdrs(), explorer tree categories, file open via relative_path.

a2c show <kind> <id> --json

Command	command field
show epic	artifact.show.epic
show task	artifact.show.task
show sprint	artifact.show.sprint

data.item is the full artifact model. The extension opens the file at relative_path from the list row and writes a show summary to the A2C output channel when a planning artifact is selected.

ADR rows come from list adrs --json; selecting an ADR opens relative_path via a2c.openRepositoryFile.

a2c config * --json (implemented — requires a2c-workflow with config commands)

Command	command field	Purpose
config show	config.show	Current config JSON, path, recovery mode
config catalog	config.catalog	Schema-derived field metadata for explorer
config validate	config.validate	Validate on-disk .a2c/config.yaml
config validate --stdin	config.validate	Validate YAML draft before write
config save --stdin	config.save	Validate and write JSON config to disk

Extension: BackendClient.configShow(), configCatalog(), configValidate(), inspectRepository(); commands a2c.openConfigFile, a2c.validateConfig; save hook on .a2c/config.yaml.

Until the bundled CLI is bumped to a workflow release that includes config commands, set A2C_CLI_PATH to a local a2c-workflow checkout.

a2c plan decompose-epic --json (implemented — M5 slice)

Field	Value
command	plan.decompose_epic
data.epic_id	Epic that was decomposed
data.summary	Provider summary text
data.tasks	Task draft objects (id, title, status, epic_id, body, optional rationale)
data.task_count	Length of tasks

Invocation example:

a2c plan decompose-epic epic-onboarding --provider mock --json

Provider resolution matches the CLI: --provider > decomposition.provider in config > mock.

Extension: BackendClient.planDecomposeEpic(), command a2c.proposeTasksFromEpic (palette or epic context menu). Preview is written to the A2C output channel; apply is gated behind an explicit confirmation.

Requires a2c-workflow with plan/apply JSON support (set A2C_CLI_PATH until the bundled CLI is bumped).

a2c apply tasks-from-epic --json (implemented — M5 slice)

Field	Value
command	apply.tasks_from_epic
data.epic_id	Epic whose cached proposal was applied
data.created_task_ids	Task ids written under planning/tasks/
data.count	Length of created_task_ids

Invocation example:

a2c apply tasks-from-epic epic-onboarding --json

Extension: BackendClient.applyTasksFromEpic(), invoked from the post-preview confirmation in a2c.proposeTasksFromEpic.

Error handling expectations

• Non-zero exit code → envelope still emitted when --json is set; ok is false
• Missing binary → explain bundled path and override options
• Timeout → report timeout; do not retry silently
• Unparseable stdout → report parse failure; do not infer version or status

Assumptions

1. version requires no repository context.
2. Repo-scoped commands use process cwd set to workspace.a2cRoot (or --path when invoked manually).
3. JSON contracts are required for machine-readable workflows; human text output remains for terminal use.