diff --git a/README.md b/README.md index 9b58abb..15d6c85 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ create the labels and the first milestone in the repository's issue tracker. Status: Current Owner: _null Last reviewed: 2026-08-12 -Governs: Projects/Template/** +Governs: README.md, START-HERE-New-Project.md, START-HERE-Existing-Project.md Review trigger: Any change to the tracker conventions or the QA run-state grammar in the Privacy LLC Command Center's src/lib/; any change to which project fields the agent API can write, or to @@ -272,26 +272,28 @@ passes — is the one that costs thirty seconds and catches the rest. ## Adopting it -1. `cp -r Projects/Template/docs /docs` -2. Fill in the status header on each file — especially **Review trigger**, which - is the line that keeps a document from going quietly stale. -3. Create the four labels, one milestone, and an issue per deliverable you can - actually see ahead of you — in the tracker named above, not whichever one the - host happens to offer. -4. Point git at the hooks: `cp docs/architecture/githooks/{pre-commit,commit-msg,post-commit} .githooks/ && chmod +x .githooks/* && git config core.hooksPath .githooks`. It is per-clone, so every checkout runs it once. -5. Run `bash docs/architecture/scripts/check-env.sh` and `bash docs/architecture/scripts/secrets.sh --tracked` — the first says what is not configured, the second is the one-time audit for what is already committed. -6. Map the repository on the project's edit screen in the Command Center, then - press **Pull**. One thing does not follow from mapping it and is silent when - missing: **register the repository's webhook** and confirm a delivery - arrives. Without one the site sees this repository only through the periodic - sweep — the counts still arrive, a day late, and an opened `P0` raises no - alert at all. -7. Skim `docs/TOOLS.md` — the fixed path every project has, saying which - scripts can stop you and where to start in a fresh clone. Then read - `docs/WORK_CYCLE.md` once, now rather than at the end of the first - session. It is what happens every time a piece of work finishes, and the two - steps it exists for — recording the next action and the blockers, and telling - the site what changed — are the two that are invisible when they are skipped. +Two documents, because the two jobs are different in the only way that matters — +whether anything can be destroyed on the way in. Each holds one prompt, written +to be handed to an agent whole: -There is also a generated prompt for doing all of this with an agent, on the -Docs template screen of the Command Center — editable before you copy it. +| Starting from | Read | +| --- | --- | +| an empty repository | **[Brand New Project — Start Here](START-HERE-New-Project.md)** | +| a repository that already has documents, a tracker, or conventions | **[Existing Project — Start Here](START-HERE-Existing-Project.md)** | + +Both begin by putting the agent in plan mode and require it to say what it will +create, what it will keep, what it will delete and **what it will leave undone**, +before it touches anything. An adoption that quietly skips the webhook or half +the status headers looks identical to a complete one from outside. + +The mechanism in both is `docs/architecture/scripts/scaffold.sh`, and the +important thing about it is what it refuses to do: it never overwrites a file +that is already there. Do not adopt this template with `cp -r` — a scaffold that +clobbers a written document destroys work nothing would notice was gone, and +`cp -r` has no such protection. + +The Command Center's Docs template screen also generates an adoption prompt, +editable before you copy it. **These two documents are the source.** That screen +is a convenience and a separate copy, so where the two disagree the files here +are the ones kept in step with the scripts they invoke — and a difference between +them is worth reporting rather than picking a side. diff --git a/START-HERE-Existing-Project.md b/START-HERE-Existing-Project.md new file mode 100644 index 0000000..c87082d --- /dev/null +++ b/START-HERE-Existing-Project.md @@ -0,0 +1,137 @@ +# 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