Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/utility/adopt.md

# Skill Test Spec: /adopt

## Skill Summary

`/adopt` audits an existing project's artifacts — GDDs, ADRs, stories, infrastructure
files, and `technical-preferences.md` — for format compliance with the template's
skill pipeline. It classifies every gap by severity (BLOCKING / HIGH / MEDIUM / LOW),
composes a numbered, ordered migration plan, and writes it to `docs/adoption-plan-[date].md`
after explicit user approval via `AskUserQuestion`.

The resolved `workflow` tier scopes the audit: `full` requires all 8 GDD sections,
`standard` requires 5 (+ Formulas for numeric systems), and `minimal` — the
default, since `modes.rigor` defaults to `minimal` — audits `design/game-brief.md`
instead and checks any existing GDD only advisorily, and the plan prescribes no
infrastructure bootstrap (`/architecture-review`, `/create-control-manifest`,
`/sprint-plan`, `/gate-check` are not on the minimal path). Fixtures that exercise the
GDD and ADR audits therefore set `modes.rigor: full` in `project.yaml`.

A v1.0 project (no `project.yaml`, legacy config with real values) is migrated
only by `.claude/scripts/migrate-v1-config.sh` — `--dry-run` first, the real run
after an ask naming the files it writes, and `--finalize` left until the user
has read the migration report. `/adopt` never writes a review mode; it reports
the resolved one.

This skill is distinct from `/project-stage-detect` (which checks what exists).
`/adopt` checks whether what exists will actually work with the template's skills.

No director gates apply. The skill does NOT invoke any director agents.

---

## Static Assertions (Structural)

Checked against the SKILL.md by `/skill-test spec` — no fixture needed.

- [ ] Has required frontmatter fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools`
- [ ] Has ≥2 phase headings
- [ ] Contains severity tier keywords: BLOCKING, HIGH, MEDIUM, LOW
- [ ] Contains "May I write" or `AskUserQuestion` language before writing the adoption plan
- [ ] Has a next-step handoff at the end (e.g., offering to fix the highest-priority gap immediately)

---

## Director Gate Checks

None. `/adopt` is a brownfield audit utility. No director gates apply.

---

## Test Cases

### Case 1: Happy Path — All GDDs compliant, no BLOCKING or HIGH gaps

**Fixture:**
- `project.yaml` sets `modes.rigor: full`, `project.stage`, and `engine.name`,
  `engine.version`, `engine.language`, `engine.rendering`, `engine.physics`
- `design/gdd/` contains 3 GDD files; each has all 8 required sections with content
  and a valid `> **Status**:` field
- `docs/architecture/adr-0001.md` exists with `## Status`, `## ADR Dependencies`,
  `## Engine Compatibility`, `## GDD Requirements Addressed` and `## Performance Implications`
- `docs/architecture/tr-registry.yaml` and `docs/architecture/control-manifest.md` exist
- `docs/engine-reference/[engine]/VERSION.md` exists

**Input:** `/adopt`

**Expected behavior:**
1. Skill emits "Scanning project artifacts..." then reads all artifacts silently
2. Reports detected phase, GDD count, ADR count, story count
3. Phase 2 audit: `gdd-structure-check.sh` is run once per GDD path; all 3 GDDs
   have all 8 sections and a valid Status field
4. ADR audit: all critical sections present
5. Infrastructure audit: registry, manifest and engine reference all exist
6. Phase 3: zero BLOCKING and zero HIGH gaps — the project is reported
   template-compatible with only advisory improvements remaining (any MEDIUM/LOW
   item, e.g. a missing `sprint-status.yaml`, is listed as advisory)
7. Uses `AskUserQuestion` to ask about writing the plan; user selects write
8. Adoption plan is written to `docs/adoption-plan-[date].md`
9. Phase 6b reports the resolved review mode ("Review mode resolves to `full` —
   from `modes.rigor`, unless something pins it") and writes nothing for it
10. Phase 7 takes the "no BLOCKING or HIGH" branch: "No blocking gaps — this project
   is template-compatible. What next?"

**Assertions:**
- [ ] Skill reads silently before presenting any output
- [ ] "Scanning project artifacts..." appears before the silent read phase
- [ ] `gdd-structure-check.sh` is invoked with an explicit path per GDD (not bare)
- [ ] Gap counts show `BLOCKING: 0` and `HIGH: 0`, and the project is reported template-compatible
- [ ] `AskUserQuestion` is used before writing the adoption plan
- [ ] Adoption plan file is written to `docs/adoption-plan-[date].md`
- [ ] `modes.review_mode` is not written to `project.yaml` and `production/review-mode.txt` is not created — the review mode is reported, never pinned
- [ ] Phase 7 asks "No blocking gaps — this project is template-compatible. What next?" via `AskUserQuestion`

---

### Case 2: Non-Compliant Documents — GDDs missing sections, BLOCKING and HIGH gaps

**Fixture:**
- `project.yaml` sets `modes.rigor: full` and configures the engine
- `design/gdd/` contains 2 GDD files:
  - `combat.md` — missing `## Acceptance Criteria` and `## Formulas` sections
  - `movement.md` — all 8 sections present
- One ADR (`adr-0001.md`) is missing `## Status` section
- `docs/architecture/tr-registry.yaml` does not exist

**Input:** `/adopt`

**Expected behavior:**
1. Skill scans all artifacts
2. Phase 2 audit finds:
   - `combat.md`: 2 missing sections (Acceptance Criteria, Formulas)
   - `adr-0001.md`: missing `## Status` — BLOCKING impact
   - `tr-registry.yaml`: missing — HIGH impact
3. Phase 3 classifies:
   - BLOCKING: `adr-0001.md` missing `## Status` (story-readiness silently passes)
   - HIGH: `tr-registry.yaml` missing; `combat.md` missing Acceptance Criteria (can't generate stories)
   - MEDIUM: `combat.md` missing Formulas
4. Phase 4 builds ordered migration plan:
   - Step 1 (BLOCKING): Add `## Status` to `adr-0001.md` — command: `/architecture-decision retrofit`
   - Step 2 (HIGH): Run `/architecture-review` to bootstrap tr-registry.yaml
   - Step 3 (HIGH): Add Acceptance Criteria to `combat.md` — command: `/design-system retrofit`
   - Step 4 (MEDIUM): Add Formulas to `combat.md`
5. Gap Preview shows BLOCKING items as bullets (actual file names), HIGH/MEDIUM as counts
6. `AskUserQuestion` asks to write the plan; writes after approval
7. Phase 7 offers to fix the highest-priority gap (ADR Status) immediately

**Assertions:**
- [ ] BLOCKING gaps are listed as explicit file-name bullets in the Gap Preview
- [ ] HIGH and MEDIUM shown as counts in Gap Preview
- [ ] Migration plan items are in BLOCKING-first order
- [ ] Each plan item includes the fix command or manual steps
- [ ] `AskUserQuestion` is used before writing
- [ ] Phase 7 offers to immediately retrofit the first BLOCKING item

---

### Case 3: Mixed State — Some docs compliant, some not, partial report

**Fixture:**
- `project.yaml` sets `modes.rigor: full` and configures engine, naming and performance
- 4 GDD files: 2 fully compliant, 2 with gaps (one missing Tuning Knobs, one missing Formulas)
- ADRs: 3 files — 2 compliant, 1 missing `## ADR Dependencies`
- Stories: 5 files — 3 have TR-ID references, 2 do not
- Infrastructure: all critical files present

**Input:** `/adopt`

**Expected behavior:**
1. Skill audits all artifact types
2. Adoption Audit Summary shows `GDDs audited: 4 (2 fully compliant, 2 with gaps)`,
   `ADRs audited: 3 (2 fully compliant, 1 with gaps)` and `Stories audited: 5`
3. Gap classification:
   - No BLOCKING gaps
   - HIGH: 1 ADR missing `## ADR Dependencies`
   - MEDIUM: 2 GDDs with missing sections (Tuning Knobs, Formulas); 2 stories missing TR-IDs
4. Gap Preview has no BLOCKING bullets and shows HIGH / MEDIUM as counts
5. Migration plan lists the HIGH gap first, then MEDIUM gaps with GDD gaps before story gaps
6. Note included: "Existing stories continue to work — do not regenerate stories
   that are in progress or done"
7. `AskUserQuestion` to write plan; writes after approval

**Assertions:**
- [ ] Summary shows GDD and ADR tallies as `N (X fully compliant, Y with gaps)` and `Stories audited: 5`
- [ ] Summary shows `BLOCKING: 0` and the Gap Preview lists no BLOCKING bullets
- [ ] The 2 stories without TR-IDs are counted as MEDIUM gaps
- [ ] Existing story compatibility note is included in the plan
- [ ] HIGH gap precedes MEDIUM gaps; MEDIUM GDD gaps precede MEDIUM story gaps
- [ ] `AskUserQuestion` is used before writing

---

### Case 4: No Artifacts Found — Fresh project, guidance to run /start

**Fixture:**
- Repository has no files in `design/gdd/`, `docs/architecture/`, `production/epics/`
- No `project.stage` in `project.yaml` and no `production/stage.txt`
- No source code: none of `src/`, `Assets/` or `Source/` exists
- No game-concept.md, no game-brief.md, no systems-index.md

**Input:** `/adopt`

**Expected behavior:**
1. Phase 1 existence check finds no artifacts
2. Skill infers "Fresh" — no brownfield work to migrate
3. Uses `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?"
   - Options: "Run `/start`", "My artifacts are in a non-standard location", "Cancel"
4. Skill stops — does not proceed to audit regardless of user selection

**Assertions:**
- [ ] `AskUserQuestion` is used (not a plain text message) when no artifacts are found
- [ ] `/start` is presented as a named option
- [ ] Skill stops after the question — no audit phases run
- [ ] No adoption plan file is written

---

### Case 5: Director Gate Check — No gate; minimal tier scopes the audit to the brief

**Fixture:**
- `project.yaml` configures the engine and has no `modes` block (`workflow`
  resolves to `minimal`)
- `design/game-brief.md` exists
- `design/gdd/combat.md` exists and is missing `## Acceptance Criteria`

**Input:** `/adopt`

**Expected behavior:**
1. Phase 2 audits `design/game-brief.md`; GDDs, ADRs and UX specs are not expected
2. `combat.md` is checked at the `standard` bar advisorily — its missing Acceptance
   Criteria is reported as informational, not as a HIGH gap
3. The plan does not prescribe the infrastructure bootstrap: its Step 3 says in
   one line that it is not on the minimal path and names `/create-stories` as
   the next step (no stories exist)
4. No director agents are spawned at any point
5. No gate IDs (CD-*, TD-*, AD-*, PR-*) appear in output
6. No `/gate-check` is invoked during the skill run

**Assertions:**
- [ ] `design/game-brief.md` is audited
- [ ] Absent ADRs and UX specs are not reported as gaps
- [ ] `combat.md`'s missing Acceptance Criteria is not counted in the HIGH total
- [ ] The plan prescribes none of `/architecture-review`, `/create-control-manifest`, `/sprint-plan` or `/gate-check` — none is on the minimal path
- [ ] No director gate is invoked and no gate skip messages appear
- [ ] Skill reaches plan-writing or cancellation without any gate verdict

---

### Case 6: v1.0 Project — Converter run, never hand-migrated

**Fixture:**
- No `project.yaml` at the repo root
- `production/stage.txt` reads `Production`; `.claude/docs/technical-preferences.md`
  has `- **Engine**: Godot 4.6` and a filled naming section
- `design/gdd/` holds GDDs; no `production/migration-report.md`

**Input:** `/adopt`

**Expected behavior:**
1. Phase 2g identifies a v1.0 project needing migration (no `project.yaml`,
   legacy files with real, migratable values)
2. It runs `bash .claude/scripts/migrate-v1-config.sh --dry-run` during the
   audit (the dry run writes nothing) — it does not hand-write `project.yaml`
3. The migration is classified BLOCKING in Phase 3 and heads the plan, which
   reports what the dry run listed
4. After the plan, Phase 7 offers the migration first: it asks "May I run the
   converter? It writes `project.yaml` and `production/migration-report.md`."
   and runs it without `--dry-run` only after approval
5. It tells the user to read `production/migration-report.md` before running
   `bash .claude/scripts/migrate-v1-config.sh --finalize`, and does not run
   `--finalize` itself before the user has read the report

**Assertions:**
- [ ] `--dry-run` runs before any real migration, and its output is reported
- [ ] `project.yaml` is written only by the converter, after the ask naming `project.yaml` and `production/migration-report.md` is approved
- [ ] `--finalize` is not run before the user has read `production/migration-report.md`
- [ ] The migration is a BLOCKING item, first in the plan
- [ ] No legacy file is deleted during the run

---

## Protocol Compliance

- [ ] Emits "Scanning project artifacts..." before silent read phase
- [ ] Reads all artifacts silently before presenting any results
- [ ] Shows Adoption Audit Summary and Gap Preview before asking to write
- [ ] Uses `AskUserQuestion` before writing the adoption plan file
- [ ] Adoption plan written to `docs/adoption-plan-[date].md` — not to any other path
- [ ] Migration plan items ordered: BLOCKING first, HIGH second, MEDIUM third, LOW last
- [ ] Phase 7 always offers a single specific next action (not a generic list)
- [ ] Never regenerates existing artifacts — only fills gaps in what exists
- [ ] Does not invoke director gates at any point

---

## Coverage Notes

- The `gdds`, `adrs`, `stories`, and `infra` argument modes narrow the audit scope;
  each follows the same pattern as the full audit but limited to that artifact type.
  Not separately fixture-tested here.
- The systems-index.md parenthetical status value check (BLOCKING) is a special case
  that triggers an immediate fix offer before writing the plan; not separately tested.
- Phase 6b reports the resolved review mode and writes nothing — `review_mode` is
  fronted by `modes.rigor`, so pinning it would shadow the rigor expansion; Case 1
  asserts that nothing is written for it.
- The converter's refusals (exit 3 when its values disagree or a migration
  already ran; `--finalize` exiting 4 on a mismatch) are not separately tested;
  Case 6 covers the migration itself.