# Adopt > Adopt Blueprint into an existing brownfield codebase by surveying shipped behavior and generating plans, standards, commands, adapter choices, and visibility setup. Use for /adopt or requests to bootstrap Blueprint into an established app. Use onboard for a fresh scaffold. - Skill: `aiblueprinthq/adopt` (Agent Skill) - Install (CLI): `npx skillmds@latest add aiblueprinthq/adopt` - Raw SKILL.md: https://api.skillmd.com/api/skills/aiblueprinthq/adopt/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: aiblueprinthq (https://skillmd.com/u/aiblueprinthq) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/aiblueprinthq/adopt --- # adopt - bootstrap the blueprint from an existing codebase **Context reuse:** Reuse any required file already loaded in project instructions or the current session. Read it again only if absent, changed, or exact current bytes or line references are needed. **First action:** Before project inspection, preflight, or any other tool call, publish `running` to `blueprint/.state/run.json` using the dashboard activity contract in `AGENTS.md`. Where this sits in the workflow: existing codebase -> [adopt] -> project-plan + build-plan + coding-standards -> /overview -> normal loop (already has code) (survey + (seeded from the real code; shipped (project- (/feature, interview) features already checked off) overview.md) /implement, ...) The standard onboarding assumes a freshly scaffolded, near-empty app: you write the two plans from scratch and build forward. That doesn't fit a project that already has thousands of lines of working code. `/adopt` is the brownfield on-ramp: it reads what's already there, asks you only for what the code can't tell it (the *why* and the *roadmap*), and produces the same input files the rest of the workflow expects - so an existing project joins the loop without you hand-writing everything. It generates the inputs; it does not generate `project-overview.md`. That stays `/overview`'s job. `/adopt` ends by telling you to run `/overview`. ## Input A description of what the project is, if the user offers one. Otherwise just the repository itself. No argument is required. ## Step 0 - confirm it's brownfield and safe Look at `blueprint/project-plan.md` and `blueprint/build-plan.md`. - If they're missing or still the empty worksheet/placeholder, proceed. - If they already hold real content, this project is already adopted. Stop and say so; offer to refresh a specific file instead of overwriting work the user owns. Never overwrite a filled-in plan without explicit confirmation. Never run a framework scaffolder (the blueprint is an overlay, never a generator). Protect the project README: - If the root `README.md` already looks like a real project README, leave it alone. - If the root `README.md` is the copied Blueprint workflow doc (for example it starts with `# AI Coding Blueprint`), report it as obsolete overlay content and ask before replacing or removing it. Do not move it into `blueprint/`. - Do not create or overwrite a root project README for a brownfield app unless the user explicitly asks. The existing project face belongs to the app, not the workflow. ## Step 1 - survey the codebase (read-only) Read the repo to establish the facts. Change nothing in this step. Establish: - **Stack and tooling** - language(s), framework(s), and versions, from the real manifest (`package.json`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Gemfile`, `Cargo.toml`, etc.). Note the package manager actually in use (lockfile). - **Commands** - the real dev / build / test / lint scripts. These feed the Commands section of `AGENTS.md` and, per the testing opt-in switch, decide whether a testing gate even applies. - **Conventions in practice** - directory layout, component/file naming, styling approach, state management, data-fetching pattern, error handling. Read what the code *does*, not what a default template prescribes. - **Testing reality** - is a runner configured and are there tests, or none? Be honest; don't describe a gate the project doesn't have. - **Verification and CI** - note any combined verification command, GitHub remote, `.github/workflows/`, or external CI. Preserve what already exists. - **What the app already does** - the shipped features, inferred from routes, pages, entry points, and modules. This becomes the *checked* part of the build plan. Keep notes; you'll turn them into the files in Step 3. ## Step 2 - interview for intent The code reveals *what* and *how*, never *why* or *what next*. Ask the user a short set of questions (aim for three to five, not an interrogation) to fill the gaps: - What is this project for, and who uses it? (the problem and the users) - Is the stack and structure you found intentional, or are there parts they'd call legacy / want to change? - What do you want to build next? (the unchecked items in the build plan) - Anything the survey got wrong or missed? If the user already gave intent up front, skip what they've answered. Don't ask what you can read from the code. ## Step 3 - generate the inputs Write these, drawn from the survey (facts) and the interview (intent). Mark every inference you're unsure of with a clear `> TODO (confirm)` so the user can correct it rather than inherit a wrong guess. - **`blueprint/project-plan.md`** - the what & why, following the existing worksheet structure (problem, users, features, data, tech, monetization, UI/UX). The "features" and "tech" sections describe what *already exists*; the rest comes from the interview. - **`blueprint/build-plan.md`** - the ordered feature list as a checklist. **Mark shipped features `- [x]`** (this is the brownfield difference: the build plan reflects reality, so most of an existing app starts checked) and the roadmap items from the interview as `- [ ]`. This makes `/status` and `/feature` work immediately - the next unchecked item is genuinely what's next. - **`blueprint/context/coding-standards.md`** - rewrite the default to match the project's *actual* conventions from Step 1, not the shipped Next.js/Prisma defaults. Keep the Writing and Comments sections; replace the stack-specific ones with what the code really does. Its Testing section must reflect the real testing state (the opt-in switch is a `test` command in `AGENTS.md`). - **`AGENTS.md` Commands section** - fill in the real dev / build / test / lint commands you found, so the rest of the workflow (and the testing gate) uses the project's actual scripts. Include `Verify` when a real combined command exists. Do not write `project-overview.md`; that's `/overview`'s job, downstream of these. ## Step 4 - point to optional CI setup Do not create or change Verify commands or GitHub workflows during adoption. Report any verification command or CI already present. When equivalent automatic pull-request checks are absent, mention the optional standalone setup: ```text Run /ci or $ci when you want automatic GitHub checks. ``` Explain that CI is not required to finish adoption. The `/ci` skill owns project-specific Verify and GitHub workflow setup. ## Step 5 - ask about Blueprint visibility Ask how the Blueprint workflow files should be handled in git, unless the user already gave a preference: ```text Blueprint visibility? 1. Commit Blueprint workflow files Portable. Best for teams and working across machines. 2. Keep Blueprint workflow files local Adds .agents/, .claude/, blueprint/, and CLAUDE.md to .gitignore. Keeps AGENTS.md public as the lightweight project agent guide. ``` Recommend option 1 by default. If the user chooses option 2: - Add this block to `.gitignore`, preserving existing entries: ```gitignore # AI Blueprint local workflow files .agents/ .claude/ blueprint/ CLAUDE.md ``` - Keep `AGENTS.md` tracked. It remains the lightweight public project guide for commands and conventions. - Make `AGENTS.md` public-safe: keep project description, commands, testing gate, and coding conventions, but remove or avoid Blueprint workflow explanations, hidden adapter paths, workflow-document pointers, and core skill lists that would expose the local-only workflow. - Explain that local-only mode hides the workflow contents from the repo, but the `.gitignore` names still reveal the ignored paths. - Explain that Blueprint state, specs, findings, and history will not travel with the repo; another machine needs the Blueprint reinstalled or restored locally. - Because adoption runs right after the Blueprint files were added to an existing repository, they are more likely to already be staged or committed than in a fresh install. If any of `.agents/`, `.claude/`, `blueprint/`, or `CLAUDE.md` are already tracked, say `.gitignore` will not hide tracked files. Ask before running `git rm --cached -r .agents .claude blueprint CLAUDE.md`, and only run it if the user explicitly approves. Never delete the local files. ## Step 6 - review gate, then hand off Stop and show the user what you generated, calling out: - the **build-plan split** - what you marked shipped vs not, since that's the judgment most worth their eyes, - every `> TODO (confirm)` you left, - anything the survey and the interview disagreed on, - verification command and GitHub checks status, - Blueprint visibility choice, and a tracked-file warning if local-only mode was chosen after files were already tracked. These files are the ones the user *owns*. Have them review and adjust, then tell them to run `/overview` to distill the plans into `project-overview.md` and start the normal loop. ## Rules - **Read-only until Step 3.** The survey changes nothing; only generation writes. - **Reflect reality, don't prescribe.** `coding-standards.md` must match the code that exists. A project using Zustand and REST routes should not be handed standards about Server Actions and Prisma just because that's the default. - Follow and preserve the proportional-engineering contract in `AGENTS.md`; record only established usage or trust constraints and leave unknowns blank. - **Never invent intent.** Ask for the why and the roadmap; mark anything inferred with `> TODO (confirm)`. Silent guesses about purpose are the main failure mode. - **Don't clobber owned work.** If the plans already have real content, confirm before touching them. Never run a scaffolder. - **Be honest about testing.** If there's no runner, say testing is opt-in and not yet set up; don't describe a gate the project hasn't adopted. - Keep `AGENTS.md` public in local-only mode unless the user explicitly asks for a more advanced setup. - Do not untrack Blueprint files with `git rm --cached` without a separate explicit approval. ## Formatting Format the output to match the project's conventions in `blueprint/context/ai-interaction.md`: concise, scannable markdown, with lists for enumerations and tables for matrices rather than dense paragraphs.