ADR-0018: Legacy repository adoption workflow

Status: Accepted
Date: 2026-06-11
Deciders: Michel Gillet

Context

A2C adoption today is well supported for greenfield repositories via a2c init and a2c bootstrap, and for draft intake via prompts/bootstrap/inputs-intake.md after bootstrap. The vast majority of software that could benefit from A2C already exists: it has git history, legacy docs, CI, changelogs, and often partial ADRs or pre-commit configuration.

Running a2c bootstrap alone on such repositories is additive but incomplete:

Existing CHANGELOG.md, .pre-commit-config.yaml, and docs/adr/ are skipped, leaving policy gaps.
There is no orchestrated inventory-first path before mutation.
Operators and AI agents lack a machine-readable migration state and a batch contract comparable to inputs intake.

Superbuild migration uses eai-supmig with .migration/cli-journal.yaml and inventory-first vs bootstrap-first entry paths (ADR-0014). A2C needs an equivalent brownfield adoption workflow under the A2C method namespace.

Decision

1. First-class brownfield entry: `a2c migrate`

Introduce a2c migrate as the CLI entry for adopting A2C into an existing repository. It:

Works without A2C root markers (unlike a2c doctor full checks on non-A2C paths).
Writes .a2c/migration.yaml (schema version 1) recording entry path, optional tier, phase, completed batches, and legacy signal snapshot.
Seeds planning/migration/legacy-adoption.md from method assets (or bundled package fallback) for reliable @ prompt references before bootstrap copies prompts/.
Prints the next migration batch and Cursor invocation hint.

Flags:

Flag	Purpose
`--entry-path inventory-first\|bootstrap-first`	Adoption entry strategy
`--tier docs-only\|workflow-lite\|full`	Target adoption depth
`--status`	Print migration state only (no confirmation prompt)
`--complete-batch <id>`	Record batch completion after AI/human executes it (confirms on TTY)
`--reassess`	Request AI refresh of `anchoring-readiness.md` (confirms on TTY)
`--reset`	Delete `.a2c/migration.yaml` and `planning/migration/` (type `reset` on TTY)
`--reset-confirm reset`	Non-interactive reset acknowledgment

a2c migrate is exempt from adoption drift warnings (like init and bootstrap). On a TTY, every mutating invocation (including --complete-batch and --reassess) summarizes migration state and anchoring readiness, emits warnings when verdict is Partial or Weak, and asks “Are you sure you want to continue?” — deliberately cautious; never blocks non-interactive runs (warnings only).

2. AI-guided batch contract

Add prompts/bootstrap/legacy-adoption.md — master prompt defining seven batches:

Batch	Phase
`batch-migrate-00`	Inventory (read-only) → `inventory.md`, `plan.md`, `anchoring-plan.md`
`batch-migrate-01`	Scaffold (`a2c bootstrap` additive)
`batch-migrate-02`	Anchoring ADRs — retrospective Accepted ADRs from legacy code, in-repo docs, and migration-only `inputs/` context
`batch-migrate-03`	Governance merge (renumber legacy ADRs, architecture docs, README)
`batch-migrate-04`	Tooling merge (pre-commit, gitlint, CI)
`batch-migrate-05`	Optional canonical inputs intake
`batch-migrate-06`	Hygiene (`inputs/` gitignored, completion)

Human operators approve each batch; AI executes within merge policies documented in the prompt (no silent overwrite of legacy files).

2a. Anchoring ADRs and migration `inputs/`

Brownfield repositories often lack ADRs for decisions already embodied in code. Batch 00 produces planning/migration/anchoring-plan.md listing candidate anchoring ADRs with evidence pointers. Batch 02 creates them as Accepted retrospective records (one per commit), using:

legacy source structure and APIs;
existing in-repo documentation;
inputs/ — migration-only context supplied by the operator (design notes, wiki exports, interviews) that must not be committed to the governed repository;
git history as supporting signal only.

This is distinct from ADR-0000 (A2C adoption) and from inputs-intake (canonicalizing drafts into docs/). Migration inputs/ is read for evidence; batch 06 ensures it stays out of version control.

Batch 00 also produces planning/migration/anchoring-readiness.md with verdict Strong, Partial, or Weak. The CLI parses this file to warn the operator on every a2c migrate call. Tools inform; the human decides.

2b. Visibility and phase reports

Artifact	Role
`planning/migration/phase-00-report.md` … `phase-06-report.md`	End-of-batch summary (done, risks, recommendation) — one file per phase
`planning/migration/anchoring-readiness.md`	Verdict, coverage matrix, gaps, ways forward
`planning/migration/inventory.md`, `plan.md`, `anchoring-plan.md`	Batch 00 planning outputs

Per-phase reports make migration progress visually scannable in the IDE.

2c. Iterative reassess and reset

a2c migrate --reassess — operator added inputs/ or changed the repo; AI runs mini-batch batch-migrate-00r to refresh anchoring-readiness.md without ADR commits. Repeat until verdict is acceptable.
a2c migrate --reset — delete migration state and all planning/migration/ files; start batch 00 narrative again. Does not revert bootstrap commits or ADRs already in git history.

3. Adoption tiers

Tier	Scope
`docs-only`	ADR contract and architecture docs
`workflow-lite`	+ method assets, pre-commit, planning dirs
`full`	+ stack profile, release scaffolding, hygiene

Tier is recorded in .a2c/migration.yaml and reflected in batch 00 plans.

4. Doctor integration

When .a2c/migration.yaml is present, a2c doctor reports legacy migration status (in progress vs complete). Incomplete migration is informational until batch 06 — not a hard failure for unrelated commands.

5. Relationship to other artifacts

Artifact	Role
`docs/adr/0000-adopt-a2c-workflow.md`	Human adoption decision (consumer)
`.a2c/adoption.yaml`	Tool version anchor (ADR-0013)
`.a2c/migration.yaml`	Brownfield migration progress
`planning/migration/*`	AI-generated inventory, anchoring plan, anchoring readiness, phase reports, merge plans
`prompts/bootstrap/inputs-intake.md`	Canonical draft intake when `inputs/` still has publishable material (batch 05)

Consequences

Positive

Brownfield adoption is a documented, repeatable workflow aligned with A2C’s prompt-driven execution model.
Inventory-first path reduces risky bootstrap-on-unknown-repo mistakes.
Migration state supports support threads, doctor visibility, and future automation.

Negative

Merge policies require human review — full automation of legacy pre-commit merge is out of scope for v1.
Bundled prompt fallback must be kept in sync with prompts/bootstrap/legacy-adoption.md.
Repositories mid-migration may show doctor “in progress” until batch 06.

Context​

Decision​

1. First-class brownfield entry: a2c migrate​

2. AI-guided batch contract​

2a. Anchoring ADRs and migration inputs/​

2b. Visibility and phase reports​

2c. Iterative reassess and reset​

3. Adoption tiers​

4. Doctor integration​

5. Relationship to other artifacts​

Consequences​

Positive​

Negative​

References​