# Brand New Project — Start Here

```
Status: Current
Owner: _null
Last reviewed: 2026-08-18
Governs: how a brand-new project adopts this template, first run
Review trigger: Any change to scaffold.sh's file list; any change to the tracker
  conventions, the labels, or what the Command Center needs on adoption
```

There are two of these documents. This one is for a repository with **nothing in
it yet**. If the project already has documents, a tracker, or conventions of its
own, stop and use [Existing Project — Start Here](START-HERE-Existing-Project.md)
instead — the two differ in the only way that matters, which is whether anything
can be destroyed on the way in.

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

## The prompt

```text
Adopt the project template at <TEMPLATE> into this repository.

FIRST: enter plan mode and change nothing until the plan is approved.

Your plan must name, specifically:
  - every file you will create
  - which scripts from the template this project will adopt, and which it will not
  - the first milestone's name, and every issue you will file, each with its Verify: line
  - anything you will delete
  - what you will deliberately leave undone, by name, and why

The last one is the point. An adoption that quietly skips the webhook, or the
branding issue, or half the status headers, looks identical to a complete one
from the outside. Say what you did not do.

Read <TEMPLATE>/README.md and <TEMPLATE>/docs/TOOLS.md before planning. Read
<TEMPLATE>/docs/WORK_CYCLE.md too: it is what happens at the end of every piece
of work from now on, and knowing it changes what you set up now.

Once the plan is approved:

1. SCAFFOLD. Never `cp -r` — that overwrites, and the whole safety property of
   the scaffold is that it does not:

     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 .

   Read the report. "created" is what you got; "kept" means a file was already
   there and was not touched; "skipped" is a failure, not a shrug.

2. FILL THE STATUS HEADERS. Every document opens with one. The four status words
   are exactly Current, Draft, Superseded and Archived — a checker reads them.
   `Review trigger` is the line that matters, because "Last reviewed" ages on its
   own and nothing notices.

   NEVER INVENT A DATE. An unfilled header keeps asking; an invented one stops.
   If you do not know when something was last reviewed, leave the placeholder.

3. CHOOSE THE SCRIPTS, one at a time, having read each. The scaffold deliberately
   copies none of them: an unconfigured release.sh landing in a new repository is
   a loaded gun, not a head start. Copy what this project will actually use into
   scripts/ and configure it before its first run.

   docs/TOOLS.md explains that the table in docs/architecture/README.md is a menu
   rather than an inventory. doc-claims will note the documents naming scripts you
   did not take; that is expected and not a failure.

   Record in your report which you took and which you declined.

4. THE TRACKER. The four labels, spelled exactly: P0, P1, P2, release-blocker.
   They are queried by name, and a mis-cased label reports the whole repository as
   "not adopted" rather than as zero defects.

   One milestone. Name it word-first with no comma — "Batch 01 — Foundations",
   not "0.1 Foundations". A leading version token makes the dashboard show only
   the version and drop the name, and a comma breaks the milestones filter so the
   project card shows the wrong next action.

   One issue per deliverable you can actually see ahead of you, each ending in a
   Verify: line stating the acceptance check. DO NOT PAD. Every open issue is a
   denominator, and invented future work makes every percentage wrong,
   permanently and in one direction.

   The template's own script enforces all of that and refuses malformed issues
   before they are filed:

     python3 <TEMPLATE>/docs/architecture/scripts/forgejo-issue.py --repo <owner/name> labels
     python3 <TEMPLATE>/docs/architecture/scripts/forgejo-issue.py --repo <owner/name> batch issues.json --dry-run
     python3 <TEMPLATE>/docs/architecture/scripts/forgejo-issue.py --repo <owner/name> check

5. THE HOOKS. They live in the repository because .git/hooks is not versioned:

     mkdir -p .githooks
     cp docs/architecture/githooks/{pre-commit,commit-msg,post-commit} .githooks/
     chmod +x .githooks/*
     git config core.hooksPath .githooks

   That last line is per clone, so every checkout runs it once. Say so in the
   project README. Note that post-commit pushes.

6. THE TWO AUDITS, before anything is trusted:

     bash scripts/check-env.sh          # what is not configured, before something reads it
     bash scripts/secrets.sh --tracked  # what is already committed

   If the second finds something real: rotate it first. Deleting the line does
   not remove it from a commit that already exists.

7. BRANDING. docs/data/img/ needs icon.webp, logo.webp and banner.webp, checked
   by magic bytes so a renamed PNG does not pass.

   DO NOT GENERATE PLACEHOLDERS. This is the one gap in the convention an agent
   cannot close. A placeholder that looks deliberate outlives the issue that
   would have replaced it — nobody files a ticket against an image that appears
   finished. File a P2 issue naming the three files and move on.

8. THE COMMAND CENTER. Map the repository on the project's edit screen, then
   press Pull. Then REGISTER THE REPOSITORY'S WEBHOOK and confirm a delivery
   arrives. That does not follow from mapping it and is silent when missing:
   without it the site sees this repository only through the periodic sweep, the
   counts arrive a day late, and an opened P0 raises no alert at all.

9. THE FIRST QA RUN-STATE. Fill docs/qa/ClaudeReport.md honestly. If no round has
   been run, say exactly that. Its overall sentence is quoted verbatim on the
   project screen, so write it as a sentence a stakeholder should read — not a
   status word, and not a claim about testing that has not happened.

10. FROM NOW ON, docs/WORK_CYCLE.md at the end of every piece of work: close what
    you finished with the evidence, close the milestone if the batch landed,
    update the documents the change triggered IN THE SAME COMMIT, push, log the
    entry with Next action and Blockers, then reconcile and write the summary and
    next action.

FINALLY: report what you did, and separately, what you left undone and why.
```

## What you will be asked to decide

Three things the agent cannot decide for you, and should stop and ask about:

- **Which scripts this project adopts.** The answer is usually fewer than you
  expect on day one, and more later.
- **The first milestone and its issues.** Only you know what is actually ahead.
- **The branding.** Three images somebody has to draw.