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.