/init-context

name: init-context
description: 'Set a project up with the surfaces manifest-dev works from — a North Star, a glossary, ADR conventions, and the context-file wiring that makes every session use them — seeding them from the project''s own history where there is any. Use when a repository has no CONTEXT.md or decision records, when adopting manifest-dev in an existing codebase, when starting a new project, or when the user asks to initialize project context, 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.

Two 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. This runs on every project, including one with no history at all.
• **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.

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.

Compare, then offer

A conventions file this skill emitted is a copy the project owns, so nothing overwrites it — which makes it a fork that no later improvement reaches on its own. Re-running here is the moment someone is deliberately asking whether their setup is current, so compare rather than skip, for each surface already present: the ADR conventions, the North Star conventions, and the surfaces section in the project context file.

Compare the project's copy against **what this skill's own recipe would emit today** — steps 2, 3, and 5 below — never against the raw reference. A correct copy already differs from its reference wherever the recipe changed something on the way out: a retitled heading, whatever that surface's recipe replaces, any chapter it drops, and for the context file's section, the adaptation to what the project actually has. Comparing against the raw file reports every one of those on every run and buries the real difference. **Both reference files mark the spans a copy reproduces verbatim with a fixed-boundary comment** naming what the recipe replaces or drops at that point; read those to derive what a correct copy looks like rather than reconstructing it from prose. Compare section by section and by meaning rather than line by line — a project that reworded or reflowed its copy has not fallen behind.

An installed project holds no record of what the reference said when its copy was written, so a difference cannot be attributed: the reference may have gained something, or the project may have removed it deliberately. Present each difference as what the current default says, each accepted or declined on its own, for the user to take or leave — never as a defect, a staleness, or a non-conformance, and never as a single take-it-all offer, since one accepted batch can quietly overwrite a rule the project ruled for itself. Write only what the user accepts. A project is entitled to keep its own wording permanently, and its copy governs whether or not it matches.

Porting a conventions file is rarely a one-file edit: it governs the documents written under it, so when an accepted difference changes what something is called or how it is written, say which of those documents now read as out of step.

The run

1. **Resolve the project context file.**