Initial contracts (a2c-workflow)

Checklist of shared contracts that must be defined before broad implementation across a2c_core, a2c_cli, and a2c_tui. These are implementation specifications — not new architectural decisions.

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

Define them in Phase 1 (implementation-plan.md); stabilize before Phase 3 CLI and Phase 4 TUI expand.

Contract summary

#	Contract	Owner package	Blocks
C1	Metadata file shapes	a2c_core.schemas	Validation, CLI inspect, TUI diagnostics
C2	IDs and naming conventions	a2c_core.contracts	ADR paths, workflow IDs, config keys
C3	Core config structure	a2c_core.schemas	Bootstrap, user prefs, repo profile
C4	CLI result envelope (JSON)	a2c_core.schemas + a2c_cli serializer	Extension, CI automation, --json
C5	TUI-to-core interaction model	a2c_core.services API	All TUI screens
C6	AI workflow I/O boundaries	a2c_core.workflows	Decomposition, approval flows

---

C1 — Metadata file shapes

Objective: Machine-readable models for A2C repository artifacts.

Artifact	Minimum fields (draft)	Validation
Workflow manifest	version, workflow_id, source_docs_path, required_metadata_files	Semver int for version; snake_case workflow_id
Navigation meta	Reading order, sidebar hints	Non-empty doc paths relative to docs/
ADR index	Grouped ADR list with status	File refs must exist
Repo profile pointer	Profile id, optional overrides	Profile id registered in profiles/

Deliverable: a2c_core/schemas/metadata.py + JSON Schema references + round-trip tests. M2: WorkflowManifest, AdrRecord, ProfilePointer implemented.

Still open: Exact field list for consumer-project AGENTS.md metadata hook; navigation meta / ADR index machine-readable files.

---

C2 — IDs and naming conventions

Kind	Convention	Example
Workflow ID	lowercase snake	a2c, superbuild
ADR filename	NNNN-kebab-title.md	0006-three-package-python-structure-in-a2c-core.md
Package import	a2c_core, a2c_cli, a2c_tui	PEP 503 normalized names
CLI command	colon or space group (a2c repo validate)	Document in CLI help
Config keys	dot-separated namespaces	core.log_level, workflows.approval_required
Error codes	A2C_<DOMAIN>_<NNN> string	A2C_SCHEMA_001

Deliverable: naming-conventions.md + a2c_core.contracts.naming. M2: implemented and tested.

---

C3 — Core config structure

Layered configuration (first valid wins unless merge rules say otherwise):

1. Built-in defaults (a2c_core packaged defaults)
2. User config file (path from env A2C_CONFIG or XDG)
3. Project-local .a2c/config.yaml (or TBD filename)
4. CLI/TUI flags (override for single invocation)

Minimum schema:

# Illustrative — not final
version: 1
core:
  log_level: info
workflows:
  approval_required: true
  default_profile: null
release:
  forge: none
  project: null

Deliverable: Pydantic model + loader with explicit merge documentation. M2: A2CConfig + project-local loader; multi-layer merge deferred.

---

C4 — CLI result envelope (JSON)

All JSON commands emit a single top-level shape when --json is set (extension depends on this — ADR-0007):

{
  "ok": true,
  "command": "repo.validate",
  "version": "0.1.0",
  "data": {},
  "errors": [],
  "warnings": []
}

Field	Rule
ok	false iff command failed; non-zero exit code
command	Stable dotted name — extension keys off this
version	Product version from a2c_core.__version__
data	Command-specific payload — schema per command documented
errors / warnings	{ "code", "message", "path"? } objects

Deliverable: a2c_core/schemas/results.py + a2c_cli serializer (M3) + golden-file tests. M2: CliResultEnvelope and ServiceResult types.

Still open: Streaming/progress events for long-running workflows (future data.type: "progress" extension).

---

C5 — TUI-to-core interaction model

TUI screens call synchronous or async service functions on a2c_core.services — never subprocess CLI.

Pattern	Use
ServiceResult[T]	Success value + errors list (mirrors CLI envelope semantically)
Screen → service	Pass repo_root: Path, loaded config
Mutation operations	Require explicit user confirm in TUI after core returns a Proposal object
Errors	Map A2C_* codes to user-facing strings in TUI layer only

Deliverable: a2c_core/services/__init__.py public API + validate_repository. M2: discovery, loader, validation, RepositorySnapshot.

---

C6 — AI workflow I/O boundaries

Boundary	Input	Output
Decomposition workflow	Repo snapshot metadata, user goal text, active plan batch	Structured CommitPlanProposal — file paths, scope, stop condition
Approval gate	Proposal + user decision	ApprovedProposal or abort reason
Evaluation fixture	Frozen repo tree + prompt inputs	Expected proposal JSON (no LLM in CI unit tests)

Rules:

• Workflow modules accept structured types only — no raw chat history in core API
• Prompt file loading from packaged assets — paths resolved by a2c_core, not CLI
• LLM provider adapters live in a2c_core.workflows.providers (interface TBD)
• Human-in-control: no file writes from workflow without ApprovedProposal

Deliverable: Protocol types + one reference fixture test before Milestone 5. M2: CommitPlanProposal, ApprovedProposal stub types only.

---

Definition of done (Phase 1 contracts)

Before starting Phase 3 (CLI) at scale:

• C1–C3 models exist with unit tests (M2)
• C4 envelope implemented with inspection commands (doctor, validate, list, show) — types in M2; CLI --json in extension-readiness slice
• C5 service facade stub documented (M2: validate_repository)
• C6 input/output types defined (M2 stubs)

Related

• package-boundaries.md
• implementation-plan.md