Repository anatomy
A2C defines predictable repository anatomy so humans and AI can find workflow knowledge and product code in structured files. The exact trees may evolve in implementation, but accepted boundaries are stable.
Repository: a2c-workflow
Primary Python packages: a2c_core, a2c_cli, a2c_tui
A2C product repositories (accepted)
a2c-workflow — repository structure
Single repository containing workflow method assets, the Python engine, CLI, TUI, schemas, AI workflow assets, and tests. Three Python packages, one product version.
a2c-workflow/
├── README.md
├── AGENTS.md
├── CHANGELOG.md
├── LICENSE
├── pyproject.toml # packaging (implementation detail)
├── VERSION # product semver source of truth
├── docs/
│ ├── architecture/
│ ├── adr/
│ ├── workflow/
│ └── docs-portal/
├── src/
│ ├── a2c_core/ # engine — domain, schemas, AI workflow orchestration
│ │ ├── __init__.py
│ │ ├── contracts/
│ │ ├── errors/
│ │ ├── schemas/ # repository contracts, validation
│ │ ├── services/
│ │ └── workflows/ # AI orchestration, evaluation hooks
│ ├── a2c_cli/ # CLI entrypoints and command wiring
│ │ ├── __init__.py
│ │ └── commands/
│ └── a2c_tui/ # Textual TUI application
│ ├── __init__.py
│ ├── app.py
│ └── screens/
├── schemas/ # shared schema artifacts (Milestone 2+)
├── rules/ # machine-usable constraints
├── templates/
├── prompts/
├── plans/
├── profiles/
├── tests/
│ ├── test_imports.py
│ ├── test_cli_smoke.py
│ ├── test_tui_smoke.py
│ └── test_package_boundaries.py
├── cursor/rules/
├── .cursor/rules/
├── scripts/ # bump_release.py, verify_release_version.py, dev setup
└── .gitlab-ci.yml
| Path | Contains |
|---|---|
src/a2c_core/ | Domain logic, metadata, schemas, AI workflows and orchestration |
src/a2c_cli/ | CLI commands, human + JSON surfaces — thin over a2c_core |
src/a2c_tui/ | Textual UI — interactive flows over a2c_core |
rules/, prompts/, templates/, plans/, profiles/ | A2C method assets co-located with the engine |
tests/ | Package tests and workflow evaluation fixtures |
docs/adr/ | Workflow and product ADRs |
Versioning: a2c_core, a2c_cli, and a2c_tui release together under one product semver. See ADR-0006.
a2c-vscode-extension — intended top-level structure
Thin IDE client. No duplicate workflow engine — invokes bundled CLI from the matching a2c-workflow release.
a2c-vscode-extension/
├── README.md
├── CHANGELOG.md
├── package.json
├── docs/
│ ├── architecture/
│ └── adr/
├── src/
│ ├── extension/ # activation, commands, host abstractions
│ ├── webviews/ # UI panels, visualizations
│ └── hosts/ # VS Code, Cursor, Theia-like compatibility shims
├── resources/
│ └── cli/ # bundled platform-specific a2c_cli binaries per release
│ ├── linux-x64/
│ ├── darwin-arm64/
│ ├── darwin-x64/
│ └── win-x64/
├── tests/
└── .gitlab-ci.yml
| Path | Contains |
|---|---|
src/extension/ | Extension lifecycle, command registration, CLI invocation |
src/webviews/ | Visual workflow state, diagnostics, configuration UI |
src/hosts/ | Host-specific APIs (VS Code, Cursor, Theia-like) |
resources/cli/ | One CLI build per extension release — platform matrices as needed |
Relationship to core: extension version X.Y.Z bundles CLI built from a2c-workflow X.Y.Z. No multi-version CLI support in a single extension release. See ADR-0007.
ADR-0000 by repository
| Repository | ADR-0000 meaning |
|---|---|
a2c-workflow | Foundational workflow-repo decision (0000) |
a2c-vscode-extension | Foundational extension-repo decision (to be recorded in extension repo when created) |
| Downstream A2C projects | adr(workflow): adopt A2C workflow vX.Y.Z |
Canonical tree (A2C-governed application project)
Consuming projects extend anatomy with product-specific directories. Minimum A2C additions:
<project>/
├── README.md
├── AGENTS.md
├── CHANGELOG.md
├── VERSION
├── docs/
│ ├── architecture/
│ ├── adr/
│ └── release-pipeline.md
├── rules/
├── templates/
├── prompts/
├── plans/
└── profiles/
Product source (src/, include/, tests/, build files) follows the chosen stack profile. A2C tooling (a2c_cli, extension, or TUI) operates on this tree — it does not replace the application's product layout.
Directory responsibilities (method assets)
| Path | Contains |
|---|---|
docs/architecture/ | Product boundaries, repository trees, surface roles |
docs/adr/ | Append-only decision log |
rules/ | Short constraints for AI and humans |
templates/ | Blank forms — ADR, spec, commit plan |
prompts/ | Phase prompts for bounded execution |
plans/ | Ordered commit batches |
profiles/ | Stack defaults |
In a2c-workflow, these categories are runtime method assets co-located with the engine under src/a2c_core.
What does not belong where
| Do not put in… | …because |
|---|---|
a2c-vscode-extension | Workflow engine, schemas, or AI orchestration logic |
| Third AI-workflow repo | AI workflow belongs in a2c-workflow / a2c_core (ADR-0005) |
a2c-workflow | Consumer application product source — belongs in downstream A2C-governed projects |
| Extension without bundled CLI | v1 model requires paired binary (ADR-0007) |