Skip to main content

ADR-0005: A2C product repository boundaries

  • Status: Accepted
  • Date: 2026-06-12
  • Deciders: Michel Gillet

Context​

A2C is evolving from a workflow-method repository into an implementable product with Python tooling and IDE integration. Without explicit repository boundaries, teams may:

  • split AI workflow orchestration into a third repository
  • duplicate domain logic in IDE-specific code
  • blur the line between method definition, product implementation, and consumer application repos

A2C principles require repo-first truth, thin clients over a stable core, and deterministic automation. The product needs a small, explicit repository count and clear ownership of the AI workflow runtime.

Decision​

The A2C product consists of exactly two repositories:

RepositoryOwns
a2c-workflowPython core library (a2c_core), CLI (a2c_cli), TUI (a2c_tui), metadata schemas, repository contracts, bootstrap/configuration assets, method assets (rules/, prompts/, templates/, etc.), AI workflows, orchestration, evaluation fixtures, and related tests
a2c-vscode-extensionVS Code–compatible extension, UI/webviews/visualizations, host compatibility (VS Code, Cursor, Theia-like), packaged-binary invocation

AI workflow location​

The A2C AI workflow remains inside the a2c-workflow repository — primarily in the a2c_core package. There is no third repository dedicated to AI workflow, prompts, or orchestration.

Method assets (rules/, prompts/, templates/, etc.) and runtime Python packages are co-located in a2c-workflow (ADR-0000).

Extension role​

a2c-vscode-extension is a thin client. It does not own workflow engine logic, schemas, or AI orchestration. Details of CLI bundling are in ADR-0007.

Consumer application repositories​

Repositories that use A2C to build other software remain separate. They adopt the method (ADR-0000) and are operated on by A2C tooling — they are not part of the two-product-repo count.

Rationale​

  • Stable core — one place (a2c-workflow / a2c_core) for contracts, workflows, and automation semantics
  • Thin IDE surface — extension focuses on UX and host integration, not duplicated business logic
  • No workflow sprawl — a third AI repo would fragment prompts, rules, and execution paths
  • Clear contributor mental model — engine in a2c_core, IDE in extension, method and product in a2c-workflow
  • Human-in-control AI — orchestration and policy live in a2c_core; the extension presents state and triggers commands, not autonomous workflow policy

Alternatives considered​

AlternativeVerdictReason
One repository for everything (Python backend + TypeScript extension)RejectedMixes runtime/backend and editor-extension concerns; increases contributor and operational complexity too early
Three repositories (core, AI workflow, extension)RejectedAI workflow is tightly coupled to core schemas, CLI contracts, and automation behavior — a separate repo would fragment the bounded context
Two Python packages with combined terminal surface (see ADR-0006)Rejected at package levelWeakens visible product surfaces; recorded in ADR-0006

Consequences​

Positive​

  • Predictable locations for schemas, AI workflows, CLI, TUI, and IDE code
  • Schema, CLI, TUI, and AI workflow changes can be developed and tested atomically in a2c-workflow
  • Extension and TUI can evolve UI without forking orchestration logic
  • Extension remains a thin client over a stable backend, reducing architectural blur
  • Consumer projects stay distinct from product implementation

Negative​

  • Method assets and Python product share one repository — strong internal package boundaries are required
  • Two repos still require coordinated releases (core build → extension bundle)
  • Naming (a2c-workflow repository vs a2c_core package) must be documented to avoid confusion

Migration​

  1. Bootstrap a2c-workflow with accepted package layout (ADR-0006) — Milestone 1 complete
  2. Create a2c-vscode-extension per ADR-0007
  3. Incrementally wire runtime execution of method assets through a2c_core workflows
  4. Record extension ADR-0000 when that repository is bootstrapped

Relationship to other ADRs​

ADRRelationship
ADR-0000Complements — a2c-workflow is the canonical workflow and product repository
ADR-0006Defines Python layout inside a2c-workflow
ADR-0007Defines extension thin-client and bundled CLI strategy

References​