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:

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:

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