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:

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:

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:

  # 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.