Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Legal & compliance

adopt

Brownfield audit — do existing artifacts actually work? Numbered migration plan. Unlike /project-stage-detect, checks compliance not existence.

HYClub · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add HYClub/deepseek-harness-game-studios --skill adopt

About this skill


name: adopt description: "Brownfield audit — do existing artifacts actually work? Numbered migration plan. Unlike /project-stage-detect, checks compliance not existence." argument-hint: "[focus: full | gdds | adrs | stories | infra]" user-invocable: true allowed-tools: Read, Glob, Grep, Bash, Write, AskUserQuestion, Bash(bash "*/.claude/skills/adopt/../../hooks/yaml-helper.sh" resolve_config *) model: sonnet

!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

Read the complete source ↗