Adopting an existing project

This project already works. Somebody has been maintaining its instructions by hand, writing its decisions down somewhere, and running its tests for months or years. Your job is to find out which of the conventions this plugin encodes are already covered by something here, propose only what is genuinely missing, and be willing to conclude that the answer is nothing.

The destructive failure mode is generating over work that already exists. Not overwriting a file — that is prevented mechanically. Creating a parallel structure beside a working one: an empty kb/decisions/ next to thirty ADRs in docs/adr/, a product-manager agent next to a planner that does the same job, a second roadmap. From that point on nobody can tell which one is authoritative, and the project is worse off than before you arrived.

So the bar for adding anything is: it does work nothing here already does.

Order of work

1. Inventory — read what is here. Nothing is decided and nothing is written.
2. Preflight — the environment and the language-gated tooling.
3. Map — line each convention up against what already covers it.
4. Interview — only the questions the inventory could not answer.
5. Propose — the smallest useful addition, with explicit confirmation.
6. Generate — the allowlist, and nothing outside it.
7. Wire in — one line linking the conventions from the existing instructions.

1. Inventory

uv run ${CLAUDE_PLUGIN_ROOT}/scripts/inventory.py

Read the whole report before forming an opinion. What it tells you, and what to do with each part:

• .bootstrap/manifest.json present — this repository was founded by this tool. Stop; use bootstrap-doctor instead. The script exits 2 and says so.
• More than one instruction file — CLAUDE.md and AGENTS.md both present, say. Ask which is authoritative. Do not infer it from precedence.
• Decision records found — note the folder, the naming pattern, and whether they carry frontmatter. Anything you write into that folder follows its conventions, not this plugin's.
• Subagents found — the report maps them onto the catalog where the names match and marks the rest custom. A custom agent has no kind, because a kind is a judgement about what an agent is for and reading it off a filename is how a project ends up believing it has verification when it does not. Ask.
• The activity comparison — how stale the documentation is relative to the code. This is the finding that decides whether adoption is the right answer at all. Read the next section before proposing anything.

The finding that outranks the others

If documentation has not been written to in months while the code moved every week, this project does not have a missing-structure problem. Adding conventions there produces overhead with the appearance of rigour, and the honest recommendation is less structure rather than more.

Say that plainly, first, before any proposal. Then let the user overrule you — they may have a reason you cannot see from the git log, and it is their project. But they get to hear it.

A skill that cannot say "your project does not need me" is not trustworthy on the projects that do.

2. Preflight

uv run ${CLAUDE_PLUGIN_ROOT}/scripts/preflight.py

Same rules as a founding, with one that matters more here because there is real code to look at: a tool reported uncovered is out of scope on language grounds, not timing. It will not become applicable later. Read references/tooling.md on the difference between deferred and uncovered, and record an uncovered tool as a decision rather than a roadmap item.

3. Map what exists onto the conventions

Build this table before you ask anything, and show it to the user as the basis of the proposal. One row per convention.

"Covered elsewhere" is a real verdict and usually the right one. A roadmap in an issue tracker the team actually uses beats a kb/roadmap.md nobody opens, and generating the second one creates the two-roadmaps failure directly.

Only rows marked missing become candidates. Not every candidate gets built.

4. Interview

Most of project-bootstrap's interview is already answered by the repository. Ask only what the inventory could not determine:

1. Which instruction file is authoritative, if more than one was found.
2. Do decision records stay where they are? Default yes. Moving thirty ADRs is a migration with no payoff, and leaving them creates no ambiguity as long as nothing else claims to be the decisions folder.
3. What is each custom subagent for — scope, execution or verification? This is the only way the composition rule can be checked without replacing agents that work.
4. Is there a gap in the team no existing agent covers? If yes, one role. Not a set.
5. The differentiator, if the project has an active roadmap. For an established project this may honestly be "not applicable", and that is an acceptable answer here — unlike in a founding, where it decides the first spec.
6. Which of the missing rows are worth adding, from the table in step 3.
7. Tooling — with the language-coverage numbers from preflight stated as numbers, not as a recommendation.

Do not re-ask what the repository already answered. An interview that asks a two-year-old project what its stack is has not read it.

5. Propose

Build the config, and show it before running anything:

uv run ${CLAUDE_PLUGIN_ROOT}/scripts/scaffold.py --example-adopt-config
uv run ${CLAUDE_PLUGIN_ROOT}/scripts/scaffold.py --config bootstrap.yaml --list-targets

--list-targets prints every path this generator could write given the config. adopt.generate is the subset it will. Everything else is reported as withheld rather than silently skipped, because "left out on purpose" and "the tool does not know about it" look identical in a directory listing.

Then the dry run:

uv run ${CLAUDE_PLUGIN_ROOT}/scripts/scaffold.py --config bootstrap.yaml --dry-run

Present in one message: the mapping table with verdicts, the allowlist with a reason per entry, what is being left alone, the tooling recorded as out of scope with the reason each one lost, and the one-line edit you will propose for the existing instruction file. Then ask.

Rules that hold here even under pressure:

• Never --force. A conflict means a file exists that this tool did not write. In an adoption that is the normal case, and it is exactly what must not be overwritten.
• The allowlist is the agreement. Do not add an entry after confirmation because it seemed obviously useful.
• Declining everything is a valid outcome. Write the mapping table into the conversation and stop. The user now knows what they have; that was worth the time on its own.

6. Generate

uv run ${CLAUDE_PLUGIN_ROOT}/scripts/scaffold.py --config bootstrap.yaml
uv run ${CLAUDE_PLUGIN_ROOT}/scripts/verify.py

verify.py reads the adopt: block and holds an adoption to the adoption standard: it checks only the notes this tool generated, allows a missing kb/, and takes the team's composition from adopt.existing.agents. A warning about a pre-existing instruction file being over the line limit is a real finding — raise it, do not fix it.

If the adoption note landed in a folder with its own naming convention (0031-title.md rather than a date prefix), rename it to match and update the links in the index. The convention that was already there wins.

7. Wire it in

The conventions are useless if nothing points an agent at them. Propose one line near the top of the existing instruction file:

Working conventions and context budget: [kb/conventions.md](kb/conventions.md).

Use Edit, show the diff, get a yes. Then stop.

Do not paste the conventions into that file. That would defeat the first rule the conventions state — the file read every session is the file a line added to is paid for forever — and it would be a non-idempotent edit that the next run cannot recognise as its own.

Afterwards

• The adoption note in the decisions folder is the record of what happened. Read it and correct anything the interview settled differently. It states what was found, what was added, and what was ruled out with the reason; the last part is the part that stops the question being re-opened in six months with less information.
• Mention /doctor: from now on it is the right entry point, because .bootstrap/manifest.json exists and this tool can tell what it wrote from what it did not.
• If spec-kit was out of scope, say so once and leave it. Introducing a build loop to a team that has one is a bigger change than this skill is for.