Adopt

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,automation_always_ask,workflow

Resolved above — use as-is. /adopt also inspects project.yaml and the legacy config files directly when reporting and writing migration state; that raw inspection is deliberate and separate from the resolved values above.

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 (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)

Automation mode: Resolve modes.automation (project.local.yaml → project.yaml → default collaborative). Every AskUserQuestion call follows .claude/docs/automation-modes.md (collaborative asks always · guided major-only · autonomous logs and proceeds; automation_always_ask categories always prompt).

workflow (per .claude/docs/workflow-modes.md). It scopes the Phase 2 audit and Phase 3 severity: full audits all doc types at full structure; standard audits only the required docs/sections (optional sections are informational, not gaps); minimal is a design/game-brief.md format check — GDDs/ADRs/UX are not expected. See Phase 2.

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

• project.stage in project.yaml (fallback production/stage.txt) — if either is present, use that value (authoritative phase)
• design/gdd/game-concept.md (or, at the minimal tier, design/game-brief.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)
• project.yaml (engine.name) / .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 project.stage / stage.txt)

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

• 10+ source files in the code root → Production
• Stories in production/epics/ → Pre-Production
• ADRs exist → Technical Setup
• systems-index.md exists → Systems Design
• game-concept.md (or design/game-brief.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 and the resolved workflow tier), check not just that the file exists but that it contains the internal structure the template requires. At minimal, scope the audit to design/game-brief.md — do not audit for GDDs, ADRs, or UX specs (they are not expected). Steps 2e (the Engine reference row only), 2f (project config) and 2g (v1.0 migration check) run at every tier.

2a: GDD Format Audit

Gather section presence deterministically — do not read the GDDs to count headings. For each GDD discovered in Phase 1, pass its path explicitly to the structure-check script:

Bash: bash .claude/scripts/gdd-structure-check.sh [path-to-gdd]

Pass paths one at a time; do not invoke it bare. The no-argument form sweeps design/gdd/ only, and a brownfield project's GDDs are not guaranteed to live there — pass whatever paths Phase 1 found. The script prints a PRESENT: list and, when applicable, an ABSENT: list per file. It reports presence only and makes no REQUIRED/ADVISORY judgment (that is the tier logic below), and it already accepts ## Detailed Design as satisfying the Detailed Rules requirement, so do not flag that alias as missing.

If the script prints Not found: for a path or errors, that is a discovery failure, not a format gap — report it as "could not audit [path]" and do not count it as a missing-sections finding.

Then apply the workflow tier resolved above to each file's PRESENT/ABSENT lists. Which sections are required (a miss = gap) vs advisory (a miss = informational):

• full — all 8 sections are required.
• standard — the 5 required (Overview, Detailed Rules, Edge Cases, Dependencies, Acceptance Criteria) + Formulas for any system that defines numeric rules (rates, curves, thresholds, costs — the system's Category is a hint, not the test); Player Fantasy and Tuning Knobs are advisory.
• minimal — GDDs are not expected; audit design/game-brief.md instead, against .claude/docs/templates/game-brief.md: each of the six required fields present and not a placeholder; the three one-liners advisory. Any GDD that does exist is checked at the standard bar, advisorily.

The script's 8 canonical labels are: Overview, Player Fantasy, Detailed Rules, Formulas, Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria.

A section reported PRESENT can still be an empty heading. For each GDD, also record with a targeted grep (not a full read):

• Placeholder-only sections — Grep pattern="\[To be designed\]" (or an equivalent empty/single-line body) marks a present-but-unwritten section.
• The **Status**: header field — Grep pattern="^>?[[:space:]]*\*\*Status\*\*:". Valid values: Draft, In Design, Designed, In Review, Approved, Implemented, Needs Revision.

The >? is load-bearing, and so are Draft/Implemented. Both emitters write this field inside a blockquote — .claude/docs/templates/game-design-document.md and /design-system produce > **Status**: … — so an anchor of ^\*\*Status\*\*: matches nothing and reports every template-compliant GDD as missing its Status. The template's own value list offers Draft and Implemented, so both must count as valid.

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 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-z]+-[0-9]+ pattern? (MEDIUM — no staleness tracking)
• ADR reference — does story reference at least one ADR? (check for ADR- pattern)
• Status field — present and readable?
• Acceptance criteria — does the story have a checkbox list (- [ ])?

2e: Infrastructure Audit

At workflow: minimal only the Engine reference row applies. The TR registry, control manifest and its version stamp, sprint status, stage file and traceability matrix are not on the minimal path, so their absence is not a gap.

2f: Project Config Audit

Read project.yaml (the primary config store) and .claude/docs/technical-preferences.md (legacy mirror). A setting counts as configured if EITHER source has a real value (in technical-preferences.md, [TO BE CONFIGURED] means unconfigured):

• engine.name/version/language/rendering/physics (else the Engine/Language/Rendering/Physics fields) → HIGH if unconfigured in both (ADR skills fail)
• naming.* (else Naming conventions) → MEDIUM
• performance.* (else Performance budgets) → MEDIUM
• Forbidden Patterns, Allowed Libraries (technical-preferences.md only — not migrated to project.yaml) → LOW (starts empty by design)

2g: v1.0 Migration Check

A project is a v1.0 project needing migration when project.yaml does NOT exist at the repo root AND at least one legacy file does: production/stage.txt, production/review-mode.txt, or a .claude/docs/technical-preferences.md with real values.

"Real values" means one of the keys the converter actually migrates — Engine, Language, Rendering, Physics, the naming, platform and performance fields, Framework, or the specialists. Not merely "some bullet is filled in": the shipped template ships one prose default (- **Required Tests**: …) that is never migrated, and counting it made every fresh clone read as a v1.0 project.

Do not hand-migrate. Run the converter, which is deterministic and covered by the framework's own test suite:

bash .claude/scripts/migrate-v1-config.sh --dry-run

The dry run writes nothing; record what it lists for the report. Do not run the converter during the audit — Phase 2 reads silently. The migration is classified BLOCKING in Phase 3, heads the plan, and Phase 7 offers it as the first action: report what the dry run listed, then ask "May I run the converter? It writes project.yaml and production/migration-report.md." If the user approves, run it without --dry-run. It writes project.yaml plus production/migration-report.md and deletes nothing — the whole operation stays reversible with git checkout.

Then tell the user to read production/migration-report.md before running:

bash .claude/scripts/migrate-v1-config.sh --finalize

--finalize deletes a legacy file only after proving its value is present in project.yaml; on mismatch it deletes nothing and exits 4. It never deletes technical-preferences.md, which still holds Forbidden Patterns and Allowed Libraries.

If the script refuses with exit 3, do not work around it. Exit 3 means one of two things, and the message says which:

• the values DISAGREE — two sources of truth and no way to know which the user edited last. Surface it and let them decide.
• a production/migration-report.md is already present — a migration ran here, so these are post-migration leftovers and --finalize is the next step, not a second migrate.

Both files merely existing is not exit 3 and must not be reported as a conflict: /start writes production/stage.txt on every new v1.1 project as a mirror, so agreement is the normal state. The script says the legacy files mirror it (values agree) and exits 0 for that.

Classify as BLOCKING in Phase 3: until migration runs, every skill reads config through the legacy fallback chain, and v1.1 settings are unavailable.

Phase 3: Classify and Prioritise Gaps

Organise every gap found across all audits into four severity tiers:

BLOCKING — Will cause template skills to silently produce wrong results right now. Examples: ADR missing Status field, systems-index parenthetical status values, engine not configured when ADRs exist.

HIGH — Will cause stories to be generated with missing safety checks, or infrastructure bootstrapping will fail. Examples: ADRs missing Engine Compatibility, GDDs missing Acceptance Criteria (stories can't be generated from them), tr-registry.yaml missing.

MEDIUM — Degrades quality and pipeline tracking but does not break functionality. Examples: GDDs missing Tuning Knobs or Formulas sections, stories missing TR-IDs, sprint-status.yaml missing.

LOW — Retroactive improvements that are nice-to-have but not urgent. Examples: Stories missing Manifest Version stamps, GDDs missing Open Questions section.

Count totals per tier. If zero BLOCKING and zero HIGH gaps: report that the project is template-compatible and only advisory improvements remain.