Project-Template/START-HERE-Existing-Project.md

# Existing Project — Start Here

```
Status: Current
Owner: _null
Last reviewed: 2026-08-18
Governs: how a project that already has documents and a tracker merges this template in
Review trigger: Any change to scaffold.sh's never-overwrite behaviour; any change
  to the tracker conventions, the labels, or the status header fields
```

There are two of these documents. This one is for a repository that **already has
work in it** — documents, a tracker, conventions of its own, however partial. If
the repository is empty, use [Brand New Project — Start
Here](START-HERE-New-Project.md), which is a shorter and easier job.

The difference is not cosmetic. Adopting into an existing project is a **merge**,
and the failure it must not commit is destroying writing that nothing would
notice was gone: no test fails for an architecture note that used to say more,
there is no build to break, and if the file was never committed there is not even
a diff to read. It is silent when it happens and silent afterwards.

Hand the block below to an agent. It is written to be pasted whole.

## The prompt

```text
Merge the project template at <TEMPLATE> into this repository, which already has
work in it.

FIRST: enter plan mode. Survey, and change NOTHING until the plan is approved.
The survey is the plan — every step of it is read-only, and a merge proposed is a
conversation while a merge performed is a diff somebody has to audit.

THE SURVEY. Report what is actually here, changing nothing:

  - Which of the template's documents already exist, under any name. A project
    with ARCHITECTURE.md has an architecture document; it is not missing one.
  - Whether a markdown backlog exists — TODO.md, ROADMAP.md, a batch ledger, a
    checklist in the README. Name every file that lists work.
  - The tracker: are the four labels present and spelled EXACTLY P0, P1, P2,
    release-blocker? Any near-misses like p1 or "P1 - high"? How are milestones
    named? How many issues sit outside any milestone?
  - Which scripts already exist, and whether they overlap the template's.
  - What README.md already claims about how this project works.

Read <TEMPLATE>/docs/DOC_TRUST_MAP.md and <TEMPLATE>/docs/TOOLS.md before
planning, so you know which document is supposed to own which answer.

Your plan must name, separately:
  - every file you will CREATE
  - every existing file you will KEEP AND RECONCILE — a different risk, listed apart
  - anything you will DELETE, and a migrated backlog above all
  - which scripts this project will adopt, and which it will not
  - what you will deliberately leave undone, by name, and why
  - the six mandatory sections from <TEMPLATE>/docs/WORK_CYCLE.md: unified code,
    error handling, logging, blind spots, rolled-in landmine fixes, and
    hardcode-as-little-as-possible. Read them there rather than from this line —
    a second copy of a list about not keeping second copies would be its own
    punchline

Once the plan is approved:

1. SCAFFOLD, AND READ WHAT IT KEPT. The scaffold is the merge tool. It fills gaps
   and reports every file that already exists as "kept", untouched, always:

     SCAFFOLD_TEMPLATE_ROOT=<TEMPLATE> bash <TEMPLATE>/docs/architecture/scripts/scaffold.sh --dry-run --into .
     SCAFFOLD_TEMPLATE_ROOT=<TEMPLATE> bash <TEMPLATE>/docs/architecture/scripts/scaffold.sh --into .

   NEVER --force ON A PROJECT WITH REAL WRITING IN IT. That flag exists for a
   tree scaffolded from a stale template and not yet written into. Here it
   overwrites documents nothing will notice were lost.

   NEVER `cp -r`. It has no such protection.

   The "kept" list IS THE MERGE WORKLIST. Those files are the ones only a person
   or a careful agent can reconcile.

2. RECONCILE, DO NOT REPLACE. For each kept document: the existing prose is this
   project's own knowledge and the template supplies shape, not content. Add the
   status header — Status, Owner, Last reviewed, Governs, Review trigger, and
   Fires on where it applies — to what is already written. Move content to the
   document the trust map says owns it, and say in your report where each thing
   went.

   If an existing document says something that contradicts the template's version
   of the same document, the EXISTING one is probably right about this project.
   Ask rather than overwriting.

3. MIGRATE ANY MARKDOWN BACKLOG INTO THE TRACKER, THEN DELETE THE MARKDOWN. This
   is the single most valuable thing this merge does.

   A list of open work in markdown beside a tracker holding the same work is two
   records that will disagree, and nothing will say which is right. That has
   already happened here: a tasks file drifted from the batch ledger and four
   documents inherited a wrong batch number from it.

   For each item: file an issue with a Verify: line, in a milestone. Then delete
   the file IN THE SAME COMMIT as the issues being filed — a migration that
   leaves the old copy in place has created the problem it was meant to solve.
   Keep any reasoning worth keeping as narrative in docs/history/, which is a
   record of then and cannot compete with a record of now.

4. THE LABELS. Rename near-misses rather than adding duplicates — a repository
   with both "P1" and "p1" has its defects split across two queries and reports
   as not adopted. Exactly: P0, P1, P2, release-blocker.

5. THE MILESTONES. Rename to the word-first form as you touch each one, not in a
   sweep: "Batch 07 — Payments", not "0.7 Payments". A leading version token makes
   the dashboard show only the version, and a comma in the title breaks the
   milestones filter. Do not renumber history to make it tidy.

6. WRITE docs/DOC_TRUST_MAP.md LAST, once everything else is settled, and describe
   what is ACTUALLY HERE rather than what the template says should be. Its whole
   value is being accurate about the others.

   Where this project deliberately keeps a document out of git, declare it there
   with an Exempt: line naming the real path. Note that those lines are read by a
   checker: outside a code fence, an Exempt: line naming a real document is a live
   declaration, not an example.

7. THE REST OF ADOPTION is the same as a new project, and
   START-HERE-New-Project.md has it in full: the hooks, check-env.sh,
   secrets.sh --tracked, the branding issue rather than invented placeholders,
   mapping on the Command Center and registering the webhook, and the first QA
   run-state. Do not re-derive them from memory.

FINALLY: report what you merged, where each thing went, and — separately and
explicitly — WHAT YOU DID NOT MERGE AND WHY. A merge that silently drops
something is worse than one that stops and asks, because the second is a question
and the first is a loss nobody will discover.
```

## The three questions this usually raises

- **"This project already has a document that does this job."** Keep it. Add the
  header, and record in the trust map that it is the one that owns the subject.
- **"There is a backlog in markdown."** It moves to the tracker and the file goes.
  That is the whole point of the convention, and the one step people skip.
- **"Some of the template does not apply."** Then delete it. A document that never
  applied is noise; entries marked *(only for a deployed service)* and
  *(only where money moves)* are there to be removed by projects they do not fit.