/adopt

name: adopt
description: "Brownfield onboarding — audits existing project artifacts for template format compliance (not just existence), classifies gaps by impact, and produces a numbered migration plan. Run this when joining an in-progress project or upgrading from an older template version. Distinct from /project-stage-detect (which checks what exists) — this checks whether what exists will actually work with the template's skills."
argument-hint: "[focus: full | gdds | adrs | stories | infra]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, AskUserQuestion
model: sonnet
agent: technical-director

Adopt — Brownfield Template Adoption

This skill audits an existing project's artifacts for **format compliance** with the template's skill pipeline, then produces a prioritised migration plan.

**This is not `/project-stage-detect`.** `/project-stage-detect` answers: *what exists?* `/adopt` answers: *will what exists actually work with the template's skills?*

A project can have GDDs, ADRs, and stories — and every format-sensitive skill will still fail silently or produce wrong results if those artifacts are in the wrong internal format.

**Output:** `docs/adoption-plan-[date].md` — a persistent, checkable migration plan.

**Argument modes:**

**Audit mode:** `$ARGUMENTS[0]` (blank = `full`)

• **No argument / `full`**: Complete audit — all artifact types
• **`gdds`**: GDD format compliance only
• **`adrs`**: ADR format compliance only
• **`stories`**: Story format compliance only
• **`infra`**: Infrastructure artifact gaps only (registry, manifest, sprint-status, stage.txt)

---

Phase 1: Detect Project State

Emit one line before reading: `"Scanning project artifacts..."` — this confirms the skill is running during the silent read phase.

Then read silently before presenting anything else.

Existence check

• `production/stage.txt` — if present, read it (authoritative phase)
• `design/gdd/game-concept.md` — concept exists?
• `design/gdd/systems-index.md` — systems index exists?
• Count GDD files: `design/gdd/*.md` (excluding game-concept.md and systems-index.md)
• Count ADR files: `docs/architecture/adr-*.md`
• Count story files: `production/epics/**/*.md` (excluding EPIC.md)
• `.claude/docs/technical-preferences.md` — engine configured?
• `docs/engine-reference/` — engine reference docs present?
• Glob `docs/adoption-plan-*.md` — note the filename of the most recent prior plan if any exist

Infer phase (if no stage.txt)

Use the same heuristic as `/project-stage-detect`:

• 10+ source files in `src/` → Production
• Stories in `production/epics/` → Pre-Production
• ADRs exist → Technical Setup
• systems-index.md exists → Systems Design
• game-concept.md exists → Concept
• Nothing → Fresh (not a brownfield project — suggest `/start`)

If the project appears fresh (no artifacts at all), use `AskUserQuestion`:

• "This looks like a fresh project — no existing artifacts found. `/adopt` is for

projects with work to migrate. What would you like to do?"

• "Run `/start` — begin guided first-time onboarding"
• "My artifacts are in a non-standard location — help me find them"
• "Cancel"

Then stop — do not proceed with the audit regardless of which option the user picks (each option leads to a different skill or manual investigation).

Report: "Detected phase: [phase]. Found: [N] GDDs, [M] ADRs, [P] stories."

---

Phase 2: Format Audit

For each artifact type in scope (based on argument mode), check not just that the file exists but that it contains the internal structure the template requires.

2a: GDD Format Audit

For each GDD file found, check for the 8 required sections by scanning headings:

| Required Section | Heading pattern to look for | |---|---| | Overview | `## Overview` | | Player Fantasy | `## Player Fantasy` | | Detailed Rules / Design | `## Detailed` or `## Core Rules` or `## Detailed Design` | | Formulas | `## Formulas` or `## Formula` | | Edge Cases | `## Edge Cases` | | Dependencies | `## Dependencies` or `## Depends` | | Tuning Knobs | `## Tuning` | | Acceptance Criteria | `## Acceptance` |

For each GDD, record:

• Which sections are present
• Which sections are missing
• Whether it has any content in present sections or just placeholder text

(`[To be designed]` or equivalent)

Also check: does each GDD have a `**Status**:` field in its header block? Valid values: `In Design`, `Designed`, `In Review`, `Approved`, `Needs Revision`.

2b: ADR Format Audit

For each ADR file found, check for these critical sections:

| Section | Impact if missing | |---|---| | `## Status` | **BLOCKING** — `/story-readiness` ADR status check silently passes everything | | `## ADR Dependencies` | HIGH — dependency ordering in `/architecture-review` breaks | | `## Engine Compatibility` | HIGH — post-cutoff API risk is unknown | | `## GDD Requirements Addressed` | MEDIUM — traceability matrix loses coverage | | `## Performance Implications` | LOW — not pipeline-critical |

For each ADR, record: which sections present, which missing, current Status value if the Status section exists.

2c: systems-index.md Format Audit

If `design/gdd/systems-index.md` exists:

1. **Parenthetical status values** — Grep for any Status cell containing parentheses: `"Needs Revision ("`, `"In Progress ("`, etc. These break exact-string matching in `/gate-check`, `/create-stories`, and `/architecture-review`. **BLOCKING.**

2. **Valid status values** — check that Status column values are only from: `Not Started`, `In Progress`, `In Review`, `Designed`, `Approved`, `Needs Revision` Flag any unrecognised values.

3. **Column structure** — check that the table has at minimum: System name, Layer, Priority, Status columns. Missing columns degrade skill functionality.

2d: Story Format Audit

For each story file found:

• **`Manifest Version:` field** — present in story header? (LOW — auto-passes if absent)
• **TR-ID reference** — does story contain `TR-[a