docs: two start-here documents, one per kind of adoption
Two kinds of project arrive at this template and neither had a document written
for it. A new repository needs a first act. An existing one -- which is most of
them, since eight were surveyed and one had adopted anything -- needs a merge,
with documents and conventions already in place that must survive it.
What existed was README's "Adopting it": seven steps aimed at a person reading
top to bottom, silent about existing projects, and opening with the one form
that destroys work:
cp -r Projects/Template/docs <your-project>/docs
cp -r overwrites. scaffold.sh exists precisely because that is unsafe, and its
header argues the case at length: a clobbered document is work nothing notices
is gone, silent when it happens and silent afterwards. An existing project
following step 1 literally replaced its own architecture notes with
placeholders. The instruction and the tool disagreed and the instruction was the
dangerous one.
Both documents hold one prompt each, written to be handed to an agent whole, and
both open by putting it in PLAN MODE with nothing changed until the plan is
approved. Each plan must name what will be created, what kept, what deleted,
which scripts the project adopts -- and what will be left undone, by name. That
last is the one that gets skipped: an adoption quietly missing the webhook or
half the status headers looks identical to a complete one from outside.
The existing-project prompt is the harder half. Its spine is survey, reconcile,
destroy nothing: the survey IS the plan phase and is entirely read-only; the
scaffold's "kept" list is the merge worklist; existing prose is the project's own
knowledge and the template supplies shape, not content; and any markdown backlog
moves into the tracker and is deleted in the same commit, because two records of
what is open is the failure the whole convention exists to prevent.
Verified rather than asserted, since the whole document rests on it: a scratch
project with three written documents, scaffolded into, reported 16 created and 3
kept, and all three pre-existing files were byte-identical afterwards with their
prose intact.
README's section becomes a pointer to the two, since three descriptions of
adoption in one repository is the two-records failure with an extra copy, and the
sentence about the Command Center's generated prompt now says which is the
source rather than leaving a reader to pick.
Also corrected: README's `Governs: Projects/Template/**` was true when this was a
folder inside Projects/ and matched nothing once it became a repository root.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-18 00:07:28 -05:00
|
|
|
# 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
|
feat(plan): six sections every plan must name, and the files an agent reads first
WORK_CYCLE.md covered only the end of the cycle. A cycle has two ends, and
the same six questions kept having to be asked out loud on every piece of
work. They are now mandatory in every plan, each justified by something this
household has actually paid for:
unified code eight copies of secrets.sh once existed here and five of
seven could not detect the most common secret shape --
INCLUDING THE TEMPLATE, so every project scaffolded from
it inherited a blind scanner
error handling the recurring fault is the silent pass, not the crash
logging an append-only log is unbounded by construction
blind spots named ones get fixed
landmine fixes the trap found while passing is cheapest to fix while
passing
hardcode little derive it, or justify the constant
GUARDS.md was five sections behind the project that has been learning; 11,
12 and 13 are backported, genericised to match the template's style. 13 is
the narrow form of the sixth rule, and WORK_CYCLE now cites it -- so
backporting it is what makes that citation true rather than a broken
reference.
Also adds the three files an agent reads BEFORE it reads docs/:
CLAUDE.md short, and it POINTS at DOC_TRUST_MAP rather than
repeating it -- a second copy of the map is the
failure that map exists to prevent. Carries the
exit-code table, the commit gates, and two standing
instructions: flag what looks wrong even when it is
not what you were asked about, and never print a
credential -- not from a file, not from a command's
output, not from a config subtree "with the secrets
filtered out", because that filter has failed before
by matching key NAMES while the secret sat inside an
object whose name was innocent
.claudeignore excludes artifacts and NEVER docs/. The Command
Center reads this repository's documents at a commit;
a generic ignore file that sweeps "documentation" or
"data" starves both the agent and the reconcile, and
everything still runs, just blind
.claude/settings.json deny rules in the double-slash absolute form. A
tilde-style rule looks right in review and silently
matches nothing. It closes the Read TOOL only -- a
shell reads a file a hundred ways -- so it catches
the accidental read, not the determined one
scaffold.sh gains a ROOT array for the three, kept apart from DOCS so the
H1-plus-status-block check stays meaningful rather than being loosened into
a warning that is always wrong (GUARDS.md 5).
Verified: scaffold --dry-run into a scratch repo creates 22 files including
all three, with no HEADERLESS warning; doc-claims passes with 124 claimed
paths, all present.
Does not touch docs/architecture/scripts/secrets.sh, which carries someone
else's uncommitted improvement.
2026-09-01 21:44:00 -05:00
|
|
|
- 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
|
docs: two start-here documents, one per kind of adoption
Two kinds of project arrive at this template and neither had a document written
for it. A new repository needs a first act. An existing one -- which is most of
them, since eight were surveyed and one had adopted anything -- needs a merge,
with documents and conventions already in place that must survive it.
What existed was README's "Adopting it": seven steps aimed at a person reading
top to bottom, silent about existing projects, and opening with the one form
that destroys work:
cp -r Projects/Template/docs <your-project>/docs
cp -r overwrites. scaffold.sh exists precisely because that is unsafe, and its
header argues the case at length: a clobbered document is work nothing notices
is gone, silent when it happens and silent afterwards. An existing project
following step 1 literally replaced its own architecture notes with
placeholders. The instruction and the tool disagreed and the instruction was the
dangerous one.
Both documents hold one prompt each, written to be handed to an agent whole, and
both open by putting it in PLAN MODE with nothing changed until the plan is
approved. Each plan must name what will be created, what kept, what deleted,
which scripts the project adopts -- and what will be left undone, by name. That
last is the one that gets skipped: an adoption quietly missing the webhook or
half the status headers looks identical to a complete one from outside.
The existing-project prompt is the harder half. Its spine is survey, reconcile,
destroy nothing: the survey IS the plan phase and is entirely read-only; the
scaffold's "kept" list is the merge worklist; existing prose is the project's own
knowledge and the template supplies shape, not content; and any markdown backlog
moves into the tracker and is deleted in the same commit, because two records of
what is open is the failure the whole convention exists to prevent.
Verified rather than asserted, since the whole document rests on it: a scratch
project with three written documents, scaffolded into, reported 16 created and 3
kept, and all three pre-existing files were byte-identical afterwards with their
prose intact.
README's section becomes a pointer to the two, since three descriptions of
adoption in one repository is the two-records failure with an extra copy, and the
sentence about the Command Center's generated prompt now says which is the
source rather than leaving a reader to pick.
Also corrected: README's `Governs: Projects/Template/**` was true when this was a
folder inside Projects/ and matched nothing once it became a repository root.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-18 00:07:28 -05:00
|
|
|
|
|
|
|
|
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.
|