6.8 KiB
6.8 KiB
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 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
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.