/adopt

name: adopt
description: Use when an existing project that was not built with X2 must be migrated to run under it, with documentation sprawl to dissolve, stories to harvest at epic altitude, an as-built design to baseline, and existing enforcement to map and arm. Runs the migration on a dedicated branch with three human gates. Do not use for a new project (that is seed), and do not use it to redesign the product or refactor code beyond what arming the enforcement requires.

X2 adopt: migrate an existing project onto X2

You are migrating a project that was built under another method onto X2. The end state: no stray documentation artifacts in the project tree, the epic story set identified and approved, `docs/` initialised and baselined with the X2 decision layer, the as-built UI replicated into `design/prototype/` and locked, the existing enforcement mapped onto the claims and armed in CI, and the project resuming under the normal X2 skills.

The philosophy guard (read first, and hold it)

The existing documentation will distract and confuse you. It is documentation-heavy: detailed acceptance criteria, plans, test plans, briefs, traceability prose. That style documents what must be true and checks code against the documents. X2 makes what must be true unbreakable or derivable, and reserves prose for decisions a machine cannot witness:

• Cross-cutting properties become invariants, stated once, enforced by the build.
• User-visible behaviour becomes the locked prototype; tests derive from it, never authored ahead.
• Interaction contracts that are not UI-visible live in one behaviour spec.
• Stories stay at epic altitude. Their job is to drive decomposition and slicing, not to fan out

into criteria. Elaborating a story toward ACs is over-production, not thoroughness.

So: keep the epochs and the stories, not the ACs. Detailed acceptance criteria are dissolution input, never story material. When you feel the pull to preserve a detailed document because it is good, ask which of the three destinations its content belongs to (invariant, locked design, behaviour spec) and send it there or record it as owed. Do not adopt the old corpus's style.

Only these survive as prose: decision records, the behaviour spec, runbooks for humans operating the system, and the claims' human-readable statements. Everything descriptive of code dies once code or a test says it; code wins over descriptive docs.

Three sources of truth, one reconciliation

Adoption inherits three independently produced accounts of the product, and they will not agree:

1. **The code: what is actually built.** The authority on what exists. It cannot describe intent, but it cannot lie about behaviour. 2. **The epics and stories: what was intended.** Scattered through the old .md corpus. In X2 the approved story set (Gate A) becomes the authority on intent, but during adoption the old docs only NOMINATE story candidates; the code and the running app CONFIRM them. An .md story the code does not witness is dead intent until the human rules otherwise; a code capability no doc mentions is a missing story. Never let a document win a conflict with the code by default: that is how a legacy documentation corpus suffocates the adoption. 3. **The UI design: how it should look and behave on screen.** The current design export becomes the authority from Gate C forward.

The triangle is reconciled edge by edge, each at its gate, divergences always surfaced and ruled, never silently resolved:

• **stories vs code** in phase 1: the harvest reads primarily from the code and the app, lists

doc-vs-code divergences (dead intent, missing story), and the human rules at Gate A.

• **stories vs design** in phase 4: the congruence map, ruled at Gate C.
• **design vs code** in phase 4: the theme drift and fidelity check, ruled at Gate C.

After the three gates, the triangle is closed: the story set matches what is built, the locked design matches the stories, and the client's divergence from the locked design is named and scheduled. That closed triangle is the adoption baseline.

Measurement

The adoption run is measured like an acceptance test. Keep an append-only turn ledger from the first message (number, what, why the human was needed, bucket), feed every human turn to it as it happens, and produce the exit report at the end. A compactible context is not durable storage: write the ledger to a file immediately, and re-read this skill after any compaction.

Phase 0: safety net

1. Verify the working tree is clean; commit anything pending under direction. 2. Tag the pre-migration state (for example `pre-x2`). Git history is the real archive: after this tag, removed files remain retrievable forever, so removal later is safe. 3. Create the migration branch (for example `x2-migration`). All adoption work happens on it. 4. **Arm the existing gates in CI now**, before anything moves: one workflow running the project's real verification commands as they stand (test suites, architecture tests, lint chains, in-process claim linters). Prove it runs green on the branch. Every later phase then works under a net: a relocation that breaks load-bearing machinery goes red on push, not at the end. Branch protection waits for phase 5; the workflow does not. 5. Submodules are out of scope entirely: they are their own repos. Record each submodule pin in VERSIONS.md during phase 2 and never touch their contents or their doc corpora.

Phase 1: survey and story harvest, then Gate A

Survey the repo and produce two artifacts:

1. **The documentation census**, every doc sorted into exactly one of four buckets:

• absorbed by enforcement: a rule a test or lint already enforces, or cheaply could; the prose

dies once the enforcement exists (note the claim or test that absorbs it).

• survives as a decision: distills into D-000-as-found or a D-0xx; the source is superseded.
• commodity byproduct: plans, briefs