Architecture overview
A2C (Architecture-to-Commit) is a repository-native workflow for disciplined AI-assisted development. This document describes how the A2C product is structured in the a2c-workflow repository and how that repository relates to the IDE extension.
Repository: a2c-workflow
Primary Python packages: a2c_core, a2c_cli, a2c_tui
Product architecture (accepted)
The A2C product ships as two repositories:
| Repository | Role |
|---|---|
a2c-workflow | Python engine, CLI, TUI, metadata schemas, bootstrap assets, AI workflows, prompts, orchestration, evaluation fixtures, method assets (rules/, templates/, etc.), and related tests |
a2c-vscode-extension | VS Code–compatible thin client — webviews, visualizations, host compatibility (VS Code, Cursor, Theia-like), bundled platform-specific CLI binary |
There is no third repository for the A2C AI workflow. Orchestration, prompts, rules-as-assets, and workflow execution logic live inside the a2c-workflow repository — primarily in the a2c_core package.
Recorded in ADR-0005, ADR-0006, and ADR-0007.
Tool surfaces in a2c-workflow
Three Python packages in the same repository, versioned in lockstep:
| Package | Surface | Responsibility |
|---|---|---|
a2c_core | Engine | Domain logic, metadata operations, schemas and repository contracts, AI workflow orchestration and evaluation |
a2c_cli | CLI | Command entrypoints, argument wiring, human-readable and JSON command surfaces |
a2c_tui | TUI | Textual application — interactive bootstrap, configuration, diagnostics, maintenance UI |
The three-package split is for clarity of responsibility, contributor navigation, and product signaling — not independent release cadence. See ADR-0006.
VS Code extension model (accepted)
The extension is a thin client over the A2C CLI/backend:
- UI, visualization, and host-specific integration live in
a2c-vscode-extension - Business logic, workflow execution, and repository contracts stay in
a2c-workflow(a2c_core/a2c_cli) - Each extension release ships with one bundled platform-specific CLI build paired to that release — the extension does not support multiple CLI versions concurrently
See ADR-0007.
Design principles (product)
- Repo-first truth — workflow knowledge and contracts live in Git, not chat history
- Human-in-control AI — the developer sets architecture and quality bar; automation executes within constraints
- Thin clients over a stable core — IDE and TUI surfaces delegate to
a2c_core/a2c_cli - Frictionless UX — bundled CLI in the extension avoids manual toolchain assembly for IDE users
- Deterministic automation — schemas, contracts, and scripted flows produce repeatable outcomes
This repository (a2c-workflow)
a2c-workflow is the canonical workflow-method and product-core repository (ADR-0000). It defines and implements:
| Layer | Role |
|---|---|
Documentation (docs/) | Principles, phases, anatomy, ADR policy, product architecture |
Rules (rules/) | Machine-usable constraints agents read and follow |
Templates (templates/) | ADRs, specs, commit plans, architecture starters |
Prompts (prompts/) | Reusable prompt families for bounded AI execution |
Plans (plans/) | Commit-sized batch definitions |
Profiles (profiles/) | Optional stack-specific defaults |
Adapters (cursor/rules/) | Thin tool-specific wrappers |
Python packages (src/) | a2c_core, a2c_cli, a2c_tui — engine, CLI, and TUI |
Method assets and runtime AI workflow assets are co-located in this repository. There is no third repository for AI workflow orchestration.
Relationship to consuming projects
| Artifact | Role |
|---|---|
a2c-workflow | Defines the method and implements A2C tooling (engine, CLI, TUI) |
a2c-vscode-extension | IDE entry point invoking bundled CLI |
| Consumer A2C project | Adopts the method via ADR-0000; worked on with A2C tooling |
Consuming application projects own product source and release cadence. They do not silently fork A2C policy — fixes flow upstream to a2c-workflow first.
Implementation layer (next docs)
Accepted architecture is documented above. Implementation planning for the Python product in a2c-workflow lives in:
| Doc | Purpose |
|---|---|
| implementation-plan.md | Phased build plan (Phase 0–6) and milestones M1–M6 |
| package-boundaries.md | Package ownership, imports, cross-cutting concerns |
| initial-contracts.md | Contracts C1–C6 before broad coding |
Still open (future options)
| Topic | Status |
|---|---|
Exact timeline for runtime execution of all method assets from packaged a2c_core workflows | Tracked in implementation-plan.md |
| Additional IDE hosts beyond VS Code–compatible surfaces | Future ADR if scope changes |
| Remote/backend CLI distribution separate from extension bundle | Out of scope for v1 thin-client model |
pyproject.toml workspace tooling details | Phase 0 in implementation-plan.md |
Publication
Workflow docs remain authoritative in this repository. The docs-portal mirrors docs/ and companion asset directories. See docs-portal/integration.
Related
- implementation-plan.md — phased product build plan
- package-boundaries.md — Python package rules
- initial-contracts.md — first contracts checklist
- repository-anatomy.md — repository trees
- ../workflow/principles.md — governing principles
- ../adr/README.md — ADR model
- ../cursor-integration.md — Cursor and extension integration