Implementation plan (a2c-workflow)

Phased plan for building the Python product in the a2c-workflow repository. This is implementation planning — it does not change accepted architecture (overview.md, ADR-0005 through ADR-0007).

Repository: a2c-workflow Primary Python packages: a2c_core, a2c_cli, a2c_tui

Audience: Contributors and AI agents implementing the product in a2c-workflow. Target one milestone at a time (see Milestones).

Prerequisites

Before Phase 0 in a2c-workflow:

• Read accepted ADRs and package-boundaries.md
• Define initial-contracts.md during Phase 1 before scaling CLI/TUI

Phase overview

Phase	Name	Outcome
0	Repository and packaging scaffold	Installable empty packages, CI, tests
1	Schemas and core model foundations	Contracts C1–C3, validation
2	Core services	Domain operations, orchestration hooks
3	CLI surface	Commands, human + JSON output
4	TUI surface	Textual app skeleton and first flows
5	AI workflow integration	Prompts, approval, fixtures
6	Extension integration readiness	Stable JSON CLI, binary packaging

---

Phase 0 — Repository and packaging scaffold

Objective	Bootstrapped a2c-workflow repo with three packages, dev tooling, and CI — no feature logic yet
Why now	Establishes boundaries before code accumulates in the wrong package
Depends on	Accepted ADRs only

Deliverables

• a2c-workflow with src/a2c_core, src/a2c_cli, src/a2c_tui
• pyproject.toml (single product version, three packages)
• Editable install (pip install -e . or uv equivalent)
• Ruff + pytest + import boundary rule (see package-boundaries.md)
• A2C pre-commit hooks, CHANGELOG.md, VERSION, CI lint/test (ADR-0004)
• Empty __init__.py + __version__ in a2c_core
• Placeholder tests proving import graph

Risks / anti-patterns

• Putting all code in one package “temporarily”
• Skipping CI until “later”
• TUI or CLI dependencies added to a2c_core for dev ergonomics

---

Phase 1 — Schemas and core model foundations

Objective	Typed models for metadata, config, and repository contracts
Why now	CLI, TUI, and workflows share one truth — define before surfaces diverge
Depends on	Phase 0

Deliverables

• initial-contracts.md C1–C3 implemented in a2c_core.schemas / a2c_core.contracts
• Validation functions (pure, no I/O side effects in validators)
• Fixture JSON/YAML under tests/fixtures/metadata/
• CLI result envelope types (C4) — types only; serialization in Phase 3
• Service facade stubs (C5) — raise NotImplementedError where needed

Risks / anti-patterns

• Defining JSON shapes only in CLI tests
• Ad-hoc dicts instead of versioned schema models
• Validating by “file exists” only without schema evolution story

---

Phase 2 — Core services

Objective	Read/write/update metadata, validation services, decomposition orchestration hooks (deterministic rules)
Why now	Presentation layers stay thin; business rules live here before CLI/TUI grow
Depends on	Phase 1

Deliverables

• a2c_core.services.repo — discover repo root, load manifest, validate contract
• a2c_core.services.metadata — CRUD for governed artifacts (ADR index, navigation meta)
• a2c_core.services.validation — aggregate validation reports → ServiceResult
• Orchestration hooks (interfaces) for decomposition — implementations wired in Phase 5
• Unit tests with temp directory fixtures — no network, no LLM

Risks / anti-patterns

• File writes without going through service layer
• Mixing logging format strings into domain exceptions
• Calling subprocess or git from services without injectable adapters (git adapter OK if behind interface)

---

Phase 3 — CLI surface

Objective	Command groups, argument parsing, human and JSON output using core services
Why now	Headless automation and extension depend on CLI; needs stable contracts from Phases 1–2
Depends on	Phase 2 (Phase 1 envelope types)

Deliverables

• Command framework (Typer or argparse — implementation choice)
• Command groups: a2c version, a2c repo validate, a2c config (minimum)
• --json flag emitting C4 envelope
• Exit codes mapped from a2c_core.errors
• Console scripts entrypoint a2c → a2c_cli
• Integration tests: CLI against fixture repos

Risks / anti-patterns

• Business validation duplicated in command handlers
• Unstable JSON keyed by display strings instead of command + data schema
• TUI invoking CLI internally (forbidden — package-boundaries.md)

---

Phase 4 — TUI surface

Objective	Textual application: navigation, bootstrap/configuration views, diagnostics
Why now	Interactive flows after core services proven via CLI tests
Depends on	Phase 2 (not Phase 3 completion — parallel after Phase 2)

Deliverables

• a2c_tui.app:A2CApp entrypoint
• Screen map: home, repo status, validate, config editor (read-only first)
• Calls a2c_core.services per C5
• CSS/layout conventions; no domain logic in widgets
• Smoke test: launch app in headless/Textual test mode

Risks / anti-patterns

• Spawning a2c subprocess per screen
• Embedding validation rules in screen callbacks
• Importing a2c_cli for “reuse”

---

Phase 5 — AI workflow integration

Objective	Prompt/orchestration integration, human approval checkpoints, evaluation fixtures
Why now	Requires stable schemas and services; highest-risk behavior last among core features
Depends on	Phase 2; benefits from Phase 3 for headless debugging

Deliverables

• a2c_core.workflows — load prompts from packaged assets
• CommitPlanProposal / approval types per C6
• CLI: a2c plan propose (or similar) with --json and dry-run
• Evaluation fixtures: expected proposal JSON; provider mocked in CI
• Document human-in-control gates — no auto-write without approval flag

Risks / anti-patterns

• Prompt strings in TUI/CLI
• Non-deterministic CI tests hitting live LLM APIs
• Workflows writing files directly bypassing services

---

Phase 6 — Extension integration readiness

Objective	Reproducible CLI binary build and stable JSON contract for a2c-vscode-extension
Why now	Extension bundles one CLI per release (ADR-0007)
Depends on	Phase 3 JSON commands; Phase 5 for workflow commands extension will call

Deliverables

• Documented stable command set for extension v1 (version, validate, plan status, …)
• JSON schema or OpenAPI-style doc per command data payload
• CI job: build platform binaries (linux-x64, darwin-arm64, darwin-x64, win-x64)
• verify_release_version.py + tag pipeline
• Contract test: extension consumer fixture parses sample CLI JSON output

Risks / anti-patterns

• Breaking JSON fields without semver major bump
• Extension parsing human stderr instead of --json
• Shipping CLI binary not matching tagged a2c-workflow version

---

Milestones

Concrete sequence for one milestone per implementation prompt. Maps to phases above.

Milestone	Scope	Phase	Primary package	Done when
M1	Repo + package scaffold	0	all	pip install -e ., three imports work, CI green, import lint passes
M2	Minimal schemas + validation	1	a2c_core	C1–C3 models + repo validate logic in core tests (no CLI yet)
M3	First CLI commands	3	a2c_cli	a2c version, a2c repo validate --json with C4 envelope
M4	First TUI screens	4	a2c_tui	App launches; repo status + validate screens call core services
M5	First AI decomposition workflow	5	a2c_core + CLI	a2c plan propose --json + fixture test with mocked provider
M6	Extension-ready CLI build	6	a2c_cli + CI	Platform binaries in CI artifacts; JSON contract doc published

Parallelism: After M2, M3 and M4 can proceed in parallel on separate branches. M5 should wait for stable services (M2 complete; M3 helps debugging). M6 waits for M3 JSON stability.

Using this plan with AI agents

When prompting implementation:

1. State the milestone (M1–M6) explicitly
2. Reference package-boundaries.md — cite forbidden imports
3. Reference contract IDs (C1–C6) from initial-contracts.md
4. Stop at milestone boundary — do not spill into next phase without review

Still open

• Exact CLI command naming tree
• LLM provider adapter interface
• Whether M4 and M3 share a release or ship separately (same product version either way)
• a2c-workflow GitLab path and any product-specific ADR-0000 text if recorded later

Related

• package-boundaries.md
• initial-contracts.md
• repository-anatomy.md
• rules/14-product-architecture.md