Product development guide

Milestone 1 Python scaffold in this repository (a2c-workflow). Architecture and package boundaries are in architecture/overview.md and architecture/package-boundaries.md.

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

Three lockstep PyPI distributions (a2c-core, a2c-cli, a2c-tui) share one product version. See package-publishing.md.

Packages

Package	PyPI	Role
a2c_core	a2c-core	Engine — domain, schemas, services, workflows
a2c_cli	a2c-cli	CLI — commands and output (depends on a2c-core)
a2c_tui	a2c-tui	Textual TUI (depends on a2c-core)

Dependency rule: a2c_cli and a2c_tui are peers; neither imports the other.

See architecture/package-boundaries.md.

Milestone 2 artifact contracts: architecture/artifact-contracts.md, planning-artifact-format.md, naming-conventions.md.

Setup

python -m venv .venv
# Windows: .venv\Scripts\activate
# Unix: source .venv/bin/activate
pip install -e "./packages/a2c-core" -e "./packages/a2c-cli" -e "./packages/a2c-tui" -e ".[dev]"
pre-commit install
pre-commit install --hook-type commit-msg

Or use ./scripts/setup-dev.sh / .\scripts\setup-dev.ps1 (hooks + editable install).

Run

a2c version
a2c validate
a2c list epics
a2c show epic <id>
a2c doctor
a2c plan create-epic --from-text "Add dark mode support"
a2c apply draft-epic epic-dark-mode
a2c plan create-task --from-text "Add health check endpoint"
a2c apply draft-task add-health-check-endpoint
a2c plan decompose-epic <epic-id>
a2c apply tasks-from-epic <epic-id>
a2c --help
a2c-tui

Standalone binaries (PyInstaller)

pip install -e "./packages/a2c-core" -e "./packages/a2c-cli" -e "./packages/a2c-tui" -e ".[dev]"
python scripts/build_a2c_cli_binary.py --clean   # dist/binary/a2c
python scripts/build_a2c_tui_binary.py --clean # dist/binary/a2c-tui

See cli.md for CLI binary details. CI publishes Linux artifacts from build:a2c-cli-binary and build:a2c-tui-binary.

CLI reference: cli.md. Task intake: task-authoring.md. Epic authoring: epic-authoring.md. Epic decomposition: epic-decomposition.md.

Test and lint

pytest
ruff check src tests
ruff format --check src tests
mypy src

Optional Ollama live smoke (self-hosted gpu-ollama runner): testing-ollama-ci.md.

Later milestones

Milestone	Focus
M2	Schemas, validation in a2c_core
M3	CLI validate/list/show/doctor (read-only)
M4	Epic → task decomposition (plan/apply, review-first)
M5	LLM providers for decomposition (openai, local, ollama)
M6	Epic authoring from brief (plan/apply, review-first)
M7	TUI screens
M8	Single-task intake and bug-friendly authoring
M9	Native Ollama SDK optional extra; extension-ready CLI binaries

See architecture/implementation-plan.md.

Workflow vs product docs

Topic	Doc
Git branches, hooks, CI	development-workflow.md
Product packages, CLI, TUI	This file