Claude-Code-Game-Studios/.claude/skills/adopt/SKILL.md

name, description, argument-hint, user-invocable, allowed-tools, context, agent

name	description	argument-hint	user-invocable	allowed-tools	context	agent
adopt	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.	[focus: full | gdds | adrs | stories | infra]	true	Read, Glob, Grep, Write, AskUserQuestion	fork	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:

• 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

Read silently before presenting anything.

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?

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), stop:

"This looks like a fresh project with no existing artifacts. Run /start instead — /adopt is for projects that already have work to migrate."

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-epics-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

Artifact	Path	Impact if missing
TR registry	docs/architecture/tr-registry.yaml	HIGH — no stable requirement IDs
Control manifest	docs/architecture/control-manifest.md	HIGH — no layer rules for stories
Manifest version stamp	In manifest header: Manifest Version:	MEDIUM — staleness checks blind
Sprint status	production/sprint-status.yaml	MEDIUM — /sprint-status falls back to markdown
Stage file	production/stage.txt	MEDIUM — phase auto-detect unreliable
Engine reference	docs/engine-reference/[engine]/VERSION.md	HIGH — ADR engine checks blind
Architecture traceability	docs/architecture/architecture-traceability.md	MEDIUM — no persistent matrix

2f: Technical Preferences Audit

Read .claude/docs/technical-preferences.md. Check each field for [TO BE CONFIGURED]:

• Engine, Language, Rendering, Physics → HIGH if unconfigured (ADR skills fail)
• Naming conventions → MEDIUM
• Performance budgets → MEDIUM
• Forbidden Patterns, Allowed Libraries → LOW (starts empty by design)

---

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.

---

Phase 4: Build the Migration Plan

Compose a numbered, ordered action plan. Ordering rules:

1. BLOCKING gaps first (must fix before any pipeline skill runs reliably)
2. HIGH gaps next, infrastructure before GDD/ADR content (bootstrapping needs correct formats)
3. MEDIUM gaps ordered: GDD gaps before ADR gaps before story gaps (stories depend on GDDs and ADRs)
4. LOW gaps last

For each gap, produce a plan entry with:

• A clear problem statement (one sentence, no jargon)
• The exact command to fix it, if a skill handles it
• Manual steps if it requires direct editing
• A time estimate (rough: 5 min / 30 min / 1 session)
• A checkbox - [ ] for tracking

Special case — systems-index parenthetical status values: This is always the first item if present. Show the exact values that need changing and the exact replacement text. Offer to fix this immediately before writing the plan.

Special case — ADRs missing Status field: For each affected ADR, the fix is: /architecture-decision retrofit docs/architecture/adr-[NNNN]-[slug].md List each ADR as a separate checkable item.

Special case — GDDs missing sections: For each affected GDD, list which sections are missing and the fix: /design-system retrofit design/gdd/[filename].md

Infrastructure bootstrap ordering — always present in this sequence:

1. Fix ADR formats first (registry depends on reading ADR Status fields)
2. Run /architecture-review → bootstraps tr-registry.yaml
3. Run /create-control-manifest → creates manifest with version stamp
4. Run /sprint-plan update → creates sprint-status.yaml
5. Run /gate-check [phase] → writes stage.txt authoritatively

Existing stories — note explicitly:

"Existing stories continue to work with all template skills — all new format checks auto-pass when the fields are absent. They won't benefit from TR-ID staleness tracking or manifest version checks until they're regenerated. This is intentional: do not regenerate stories that are already in progress."

---

Phase 5: Present Summary and Ask to Write

Present a compact summary before writing:

## Adoption Audit Summary
Phase detected: [phase]
Engine: [configured / NOT CONFIGURED]
GDDs audited: [N] ([X] fully compliant, [Y] with gaps)
ADRs audited: [N] ([X] fully compliant, [Y] with gaps)
Stories audited: [N]

Gap counts:
  BLOCKING: [N] — template skills will malfunction without these fixes
  HIGH:     [N] — unsafe to run /create-epics-stories or /story-readiness
  MEDIUM:   [N] — quality degradation
  LOW:      [N] — optional improvements

Estimated remediation: [X blocking items × ~Y min each = roughly Z hours]

Ask: "May I write the full migration plan to docs/adoption-plan-[date].md?"

---

Phase 6: Write the Adoption Plan

If approved, write docs/adoption-plan-[date].md with this structure:

# Adoption Plan

> **Generated**: [date]
> **Project phase**: [phase]
> **Engine**: [name + version, or "Not configured"]
> **Template version**: v0.4.0+

Work through these steps in order. Check off each item as you complete it.
Re-run `/adopt` anytime to check remaining gaps.

---

## Step 1: Fix Blocking Gaps

[One sub-section per blocking gap with problem, fix command, time estimate, checkbox]

---

## Step 2: Fix High-Priority Gaps

[One sub-section per high gap]

---

## Step 3: Bootstrap Infrastructure

### 3a. Register existing requirements (creates tr-registry.yaml)
Run `/architecture-review` — even if ADRs already exist, this run bootstraps
the TR registry from your existing GDDs and ADRs.
**Time**: 1 session (review can be long for large codebases)
- [ ] tr-registry.yaml created

### 3b. Create control manifest
Run `/create-control-manifest`
**Time**: 30 min
- [ ] docs/architecture/control-manifest.md created

### 3c. Create sprint tracking file
Run `/sprint-plan update`
**Time**: 5 min (if sprint plan already exists as markdown)
- [ ] production/sprint-status.yaml created

### 3d. Set authoritative project stage
Run `/gate-check [current-phase]`
**Time**: 5 min
- [ ] production/stage.txt written

---

## Step 4: Medium-Priority Gaps

[One sub-section per medium gap]

---

## Step 5: Optional Improvements

[One sub-section per low gap]

---

## What to Expect from Existing Stories

Existing stories continue to work with all template skills. New format checks
(TR-ID validation, manifest version staleness) auto-pass when the fields are
absent — so nothing breaks. They won't benefit from staleness tracking until
regenerated. Do not regenerate stories that are in progress or done.

---

## Re-run

Run `/adopt` again after completing Step 3 to verify all blocking and high gaps
are resolved. The new run will reflect the current state of the project.

---

Phase 7: Offer First Action

After writing the plan, don't stop there. Pick the single highest-priority gap and offer to handle it immediately:

If there are parenthetical status values in systems-index.md:

"The most urgent fix is the systems-index.md status values — this breaks multiple skills right now. I can fix these in-place in under 2 minutes. Shall I edit the file now?"

If ADRs are missing Status fields:

"The most urgent fix is adding Status fields to your ADRs. Shall I start with docs/architecture/adr-0001.md using /architecture-decision retrofit?"

If GDDs are missing Acceptance Criteria:

"The most important GDD gap is missing Acceptance Criteria — without these, /create-epics-stories can't generate stories. Shall I start with design/gdd/[highest-priority-system].md using /design-system retrofit?"

Use AskUserQuestion:

• "What would you like to do now?"
  • Options: "Fix [most urgent gap] now", "Review the full plan first", "I'll work through the plan myself", "Run /project-stage-detect for broader context"

---

Collaborative Protocol

1. Read silently — complete the full audit before presenting anything
2. Show the summary first — let the user see scope before asking to write
3. Ask before writing — always confirm before creating the adoption plan file
4. Offer, don't force — the plan is advisory; the user decides what to fix and when
5. One action at a time — after handing off the plan, offer one specific next step, not a list of six things to do simultaneously
6. Never regenerate existing artifacts — only fill gaps in what exists; do not rewrite GDDs, ADRs, or stories that already have content