Adopt

Adopt:

Brownfield Onboarding and Template Compliance Audit

What Is This?

The Adopt skill for the Happycapy Skills platform is a specialized tool designed to facilitate seamless onboarding onto existing, in-progress projects by auditing project artifacts for format compliance with the latest template standards. Unlike basic detection scripts that simply verify the existence of files, Adopt goes further: it checks whether your Game Design Documents (GDDs), Architecture Decision Records (ADRs), user stories, and infrastructure definitions actually conform to the expected formats required by the platform's pipeline skills.

This is particularly essential in brownfield scenarios, where teams join ongoing projects or need to upgrade legacy projects to newer template versions. Adopt analyzes the current state of artifacts, classifies any detected gaps by their potential impact, and generates a clear, actionable migration plan, outputting the results in a persistent, checkable markdown report.

Why Use It?

Modern development workflows increasingly rely on automated tools and pipelines to process project artifacts. However, these pipelines assume strict adherence to specific document formats. Existing projects often accumulate technical debt in the form of outdated, inconsistent, or non-compliant artifacts. This can lead to subtle but critical failures-where tools either silently ignore non-compliant files or produce incorrect results, making issues harder to diagnose.

Adopt addresses this by:

• Ensuring Compatibility: It validates that all artifacts are in the correct internal format, guaranteeing that subsequent skills and automation will function as intended.
• Reducing Risk: By classifying gaps based on their impact, it helps teams prioritize migration tasks, reducing the risk of missed requirements or faulty automation.
• Accelerating Onboarding: New team members or external contributors can quickly understand compliance gaps and required actions, shortening ramp-up time.
• Supporting Upgrades: When evolving or upgrading to a new template version, Adopt highlights what needs to change, minimizing manual guesswork.

How to Use It

Adopt is user-invocable and supports several argument modes to tailor the audit scope. The skill can be run in one of several focused modes, or with no arguments for a comprehensive audit.

Usage Syntax

/adopt [focus: full | gdds | adrs | stories | infra]

• No argument or full: Audits all artifact types for format compliance.
• gdds: Audits only Game Design Documents.
• adrs: Audits only Architecture Decision Records.
• stories: Audits only user stories.
• infra: Audits only infrastructure definitions and configurations.

Example:

Running a Full Audit

/adopt

Or explicitly:

/adopt full

This command will traverse the project directory, read all relevant artifacts using allowed tools (Read, Glob, Grep, Write), and check each for compliance with their respective template formats.

Example:

Targeted Audit (GDDs Only)

/adopt gdds

This restricts the audit to only GDD documents, useful if you are refactoring design documentation or have just imported legacy design assets.

Output

After the audit, Adopt writes a persistent migration plan to:

docs/adoption-plan-[date].md

This markdown file lists all detected format compliance issues, grouped and numbered by priority and impact. For example:

## Adoption Plan - 2024-06-07

## High Impact

1. [GDD] `docs/gdd/gameplay.md` - Missing required "Core Loop" section.
2. [ADR] `docs/adr/001-initial-architecture.md` - Uses deprecated ADR template version.

## Medium Impact

3. [Story] `stories/player-onboarding.yaml` - Incorrect field: "acceptance" should be "acceptance_criteria".

## Low Impact

4. [Infra] `infra/deploy.yaml` - Indentation style does not match required format.

When to Use It

• Joining an In-Progress Project: When onboarding to a project that has already started, run Adopt to immediately identify which artifacts need to be updated or converted for full compatibility.
• Upgrading Template Versions: If the project template or pipeline has evolved, use Adopt to audit the current state and generate a clear migration path.
• Prior to Automation Rollout: Before enabling CI/CD or documentation automation, ensure all inputs are compliant to avoid silent failures.
• After Large Imports: When importing major assets or documentation from another project or team, validate them with Adopt.

Important Notes

• Not Just Existence: Adopt does not merely check for the presence of files-it validates the internal structure and formatting against expected templates.
• Distinct from /project-stage-detect: Do not confuse Adopt with /project-stage-detect. The latter checks what exists, while Adopt checks if what exists will actually work with the platform's skills.
• Persistent and Traceable: The output is a persistent, versionable markdown file for audit trails and team review.
• Agent Role: The skill operates with the technical-director agent, ensuring authoritative analysis.
• Allowed Tools: Limited to safe read and write operations, supporting transparent audits without risk of destructive changes.

By integrating Adopt into your workflow, you ensure that every artifact in your project is ready for automation and skill-driven development-eliminating guesswork, reducing onboarding time, and minimizing the risk of silent failures in your delivery pipeline.