Founding a development environment

You are going to found the development structure of this repository: methodology, agent team, knowledge base, token-budget rules, and tooling. The generation itself is deterministic and done by a script — your job is the part a script cannot do: finding out what this project actually is, and refusing to write a plausible default when the answer would have been different.

Write nothing until the interview is complete and the user has confirmed the plan. That gate is not a formality. Everything generated here is read by every future session, so a wrong assumption becomes permanent furniture.

Order of work

1. Preflight — detect the environment. Nothing is decided here.
2. Interview — seven blocks, in order. See references/interview.md.
3. Proactive skill search — between blocks B and C, once the stack is known.
4. Plan — show what will be written and ask for explicit confirmation.
5. Generate — run the scaffold script with the confirmed config.
6. First cycle — constitution, first spec, and the deferred tooling.

1. Preflight

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

Read the output before asking anything, and adapt to it rather than reciting it:

• Not a git repository — ask whether to run git init before continuing.
• Already bootstrapped (.bootstrap/manifest.json exists) — this is an upgrade, not a founding. Stop this skill and use bootstrap-doctor instead.
• Existing CLAUDE.md, kb/, docs/adr/, .claude/agents/ or specs/ without a manifest — this is not empty ground. Stop this skill and use project-adopt, which inventories what is there and proposes the smallest useful addition. Founding over an existing structure creates a parallel one beside a working one, and that is worse than either arrangement alone: from then on nobody can tell which is authoritative.
• spec-kit not installed — install it, do not merely report it. Show the command from registry/tools.yaml, get confirmation, run it in the repository root, then confirm .specify/memory/ and .specify/templates/ exist and the speckit-* skills are listed. Everything downstream depends on this working; if it does not, stop here rather than generating a structure with no workflow.
• uv missing — stop. It is the one hard dependency, and the scaffold cannot run without it.
• Tools reported blocked — say so plainly, once, and continue. A missing npm is a reason to skip a tool and record it in the roadmap, not a reason to abandon the bootstrap.
• Tools reported deferred or uncovered — these look similar and are recorded differently. deferred means "nothing to work on yet" and belongs in kb/roadmap.md with the trigger that brings it back. uncovered means the tool does not handle the languages this project is written in, so it will not apply later either: put it in tooling.excluded with the reason, which lands it in the bootstrap decision record. See references/tooling.md.

Baseline tooling, what each piece is for, and the trust rules live in references/tooling.md. Read it before proposing any install.

2. Interview

references/interview.md has the blocks and the questions. Ask them in order, adapting the format to what your question tool supports; covering the content matters, the exact wording does not. Do not skip a block because the answer seems obvious from the repository name.

3. Proactive skill search

Once the stack (Block A) and the differentiator (Block B) are known, and before proposing the team in Block C, invoke the skill-discovery skill.

The ordering is the point. Discovery run after the team is decided produces a list of things to install alongside roles that already do the same work; run before, it changes which roles get created. Findings feed Block C directly: a skill that covers a responsibility well means that role gets leaner, or does not get created at all.

Install nothing without explicit confirmation.

4. Plan and confirmation

Write the answers to bootstrap.yaml in the repository root, then show the plan:

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

Present, in one message: the profile, the roles with their pinned models and why each role is there, the knowledge base layout, the tooling that will be installed versus deferred, and the skills the user chose from the search. Then ask for explicit confirmation.

If the dry run reports conflicts or drift, resolve them with the user before generating. Never reach for --force to make a report go away — a conflict means a file exists that this tool did not write, and overwriting it silently is the worst thing this skill could do.

5. Generate

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

Both must come back clean. Report what was written, and what was left alone and why.

If Graphify is in tooling.enabled and preflight reported it neither deferred nor uncovered, add its MCP server to .mcp.json by merging into any existing file — never by writing a fresh one over it.

6. First cycle

In this order, because each step depends on the one before:

1. speckit-constitution — formalise .specify/memory/constitution.md from the Block F principles, seeded by the profile's constitution_seeds. This is what the verification role checks against, so it comes first.
2. speckit-specify — the first feature: the smallest slice that already delivers the differentiator from Block B. Not the easiest slice, the smallest one that actually demonstrates the point of the project.
3. speckit-clarify — only if there is genuine ambiguity. Skip it when there is not; running it on a clear spec teaches the user that the gates are theatre.
4. speckit-plan, then speckit-tasks. Run speckit-implement only when the user authorises it.
5. Confirm the tooling actually works: headroom stats responds, the plugins are listed, graph.json exists if Graphify was in scope. Record anything deferred in kb/roadmap.md rather than leaving it implied — and check that anything ruled out on language grounds went to the decision record instead, where a closed question belongs.
6. If the repository was greenfield and Claude Code Setup was deferred, run its analysis now that a first feature exists, and bring the recommendations back under the same confirmation rule.
7. Mention /dashboard to the user: once there is at least one spec, it renders a local, self-contained HTML view of feature timelines, kb/ bug counts and Claude Code token usage — read-only, no hook, nothing new to write. It ships with the plugin, so it is already available; there is nothing to generate for it here.

The bootstrap ADR is already generated as the first note in kb/decisions/. Read it and correct anything the interview settled differently — it is the foundation the rest of the knowledge base refers back to.

Rules that hold throughout

• Never Write a whole file without reading the existing one first.
• Every touch to kb/index.md is surgical and confirmed with the user.
• Nothing is installed without showing the exact command and getting a yes.
• No placeholders in generated content. If an answer is missing, ask for it.

Further reading, loaded only when needed: references/interview.md, references/tooling.md, references/kb-methodology.md, references/token-budget.md.