Existing Codebase Adoption

When to adopt

Use adoption when the repository already contains meaningful product code, shipped behavior, or established conventions. A fresh-project worksheet cannot safely infer which behavior is intentional and which files are historical accidents.

Install the overlay

Run the installer from the root of the application repository.

cd established-app
npx create-ai-blueprint@latest

Use the checkbox list to select one or more of Codex, Claude Code, GitHub Copilot, and OpenCode. The installer leaves the application’s root README intact.

Run the adoption survey

Run $adopt in Codex, /adopt in Claude Code, or ask GitHub Copilot or OpenCode to run the adopt skill. The skill reads the repository, identifies the stack, existing features, tests, Verify commands, and CI workflows, then asks about product intent that code cannot reveal. Existing automatic checks are preserved.

Adoption creates or updates:

• blueprint/project-plan.md with the product direction
• blueprint/build-plan.md with shipped features already checked
• blueprint/context/coding-standards.md with observed conventions

Review the generated plans carefully. Adoption can describe code, but only you can confirm product intent and future priorities.

Choose workflow visibility

Adoption asks whether Blueprint workflow files should be committed or kept local. Committed mode keeps plans, history, and skills portable. Local-only mode adds the workflow paths to .gitignore while keeping AGENTS.md as the public project guide. If those files are already tracked, adoption asks before untracking them and leaves the local files in place. See Local-Only Mode for the tradeoff.

Align automatic checks when needed

Adoption reports the current verification and CI state without replacing it. Run $ci in Codex or /ci in Claude Code when the project needs one shared Verify command and matching GitHub pull-request checks. When equivalent CI already exists, the skill reports it and avoids adding a duplicate.

Generate the overview

After reviewing the plans, run $overview or /overview. The generated project overview becomes the compact project context agents read in future sessions.

Audit before extending when needed

If the project grew through rapid AI-assisted development or needs cleanup before more features are added, run $audit full in Codex or /audit full in Claude Code. The audit is read-only. It reviews project-owned source, tests, and configuration, then produces a prioritized report with explicit coverage and exclusions.

Turn accepted findings into small fix specs. Address security, data integrity, broken behavior, validation, and unsafe types before broad cleanup. Avoid one large rewrite that changes behavior and structure at the same time.

Continue normally

The build loop is the same after adoption:

/feature -> review -> /implement -> /check -> /complete

The next feature comes from the first unchecked build-plan item. Existing features remain checked so the workflow does not try to rebuild them. If you ran a full audit, finish the accepted high-risk fixes before returning to feature work.