/setup-project

name: setup-project
description: 'Set a project up with the surfaces manifest-dev works from — a North Star, a glossary, ADR conventions, a recommended verification harness the user may opt out of, and the context-file wiring that makes every session use them — seeding them from the project''s own history where there is any, and keep a set-up project sound by auditing it against the setup the references describe and offering each gap, marking what changed since the surfaces version it records. Use when a repository has no CONTEXT.md or decision records, when adopting manifest-dev in an existing codebase, when starting a new project, when a set-up project records no surfaces version or an older one, or when the user asks to set up the project, re-run the setup to check it is sound, bootstrap ADRs, or reconstruct decisions from history.'

Install the project surfaces a repository needs so that every future session — and every teammate, with or without manifest-dev — works from the same direction, the same vocabulary, and the same decision record.

Three things get installed, and only the first is essential:

• **The wiring** — an ADR conventions file the project owns, a glossary, a North Star (the project's standing strategy surface: who it is for, what it promises, what winning means), and a project-context-file section that makes sessions read and maintain all three and records the surfaces version the project carries. This runs on every project, including one with no history at all.
• **A verification harness, recommended and installed by default** — the project's one command for checking that what future runs will change still does its job, with a recipe per thing it checks, seeded from what the project already has, per `references/VERIFICATION_HARNESS.md`. A project that verifies its own way may opt out; the context file then records that way instead.
• **A seed** — vocabulary and decision records reconstructed from the project's own history. This runs wherever there is history to read, and it is enrichment on top of the wiring, never a substitute for it.

All of this is for a project: a repository or working folder holding, or about to hold, work later sessions will change — a new or empty one the user is starting counts, as *Empty input* below says. When this skill runs where there is none — a chat with no workspace, a home or scratch folder, a folder holding one finished artifact, or a question that does not concern the folder the session runs in — say so, ask which folder to set up, and write nothing until one is named.

Aim for a good starting point rather than a complete record. Most of a project's past reasoning is genuinely unrecoverable; a seed that is honest about what it could not recover is worth far more than one that reads complete and isn't.

Flags

`--no-mine` skips the seed and installs the wiring alone. Mining otherwise runs wherever there is history — a project with no commits, no docs and no code simply has nothing to seed from, which needs no flag to express.

Interpret only top-level options as flags; quoted or code-formatted mentions of them are topic text.

What already exists governs

Read before writing, and never overwrite a surface the project already maintains:

• **`docs/adr/CONVENTIONS.md` exists** → the project has its own ADR convention. It governs. Do not replace it, and follow it for anything written this run — then compare it, per *Compare, then offer* below, which covers this file, `docs/NORTH_STAR_CONVENTIONS.md`, and the context file's surfaces section alike.
• **`CONTEXT.md` exists** (or the context named by a root `CONTEXT-MAP.md`) → load it. Mined vocabulary is proposed as additions to it, never as a replacement.
• **`NORTH_STAR.md` exists** → load it. Seeded content is proposed as additions or as evidence for positions it already carries — never as a rewrite: its positions change only by the owner's ruling, per the maintenance rules in `references/NORTH_STAR_FORMAT.md`.
• **`docs/adr/` holds records but there is no `CONVENTIONS.md`** → the project has an unwritten convention, and the records are the evidence of it. Infer it from them — naming scheme, which sections they carry, how they cross-reference, what the index looks like — and write the conventions file to describe *that*, adapting the shipped default rather than replacing it. Installing the default unchanged here would declare an existing corpus non-conforming, which is both wrong and the fastest way to get the file ignored. Where the corpus is inconsistent, or where following it would leave the index un-rebuildable, say so and let the user choose; never silently pick.
• **A project context file already carries some of this wiring** → add the wiring it lacks and leave the rest alone; where its surfaces section is present but differs from the template, compare and offer rather than rewrite, per *Compare, then offer* below.

The surfaces version

The project-surfaces section in the context file records one surfaces version, as the comment the template carries. Read it from the file on disk: a host that loads the context file into the session may strip HTML comments, so the copy already in context can show no version where the file records one. `references/CHANGES.md` lists each version in one line, the last being the newest, and `references/changes/vN.md` holds what version N gives an installed project; read only the files after the recorded version. Only this skill writes that line — when it installs, and when it finishes an update — plus figure-out when the user declines a whole update offer. Content written under the surfaces — a new record, a glossary entry, a recipe — never changes it.

Where the project records a version, a difference in a copy the project owns can be attributed: content the shipped text gained since that version is new and is offered, and any other difference is the project's own choice and stays. Where the project records no version, compare as