tools/spec-loop/PROMPT_update.md - magpie - Git at Google

 <!-- SPDX-License-Identifier: Apache-2.0
      https://www.apache.org/licenses/LICENSE-2.0 -->

 You are running the **update** beat of the spec-driven loop. Specs can
 fall behind the code when contributors land functionality the normal
 way (a regular PR, not through this loop). This beat brings the specs
 back in sync with reality. It is the inverse of `plan`: `plan` finds code
 missing against specs; `update` finds **functionality missing against
 specs** and back-fills the specs.

 Context to load first:

 - `tools/spec-loop/AGENTS.md` and the repo-wide `/AGENTS.md`.
 - `tools/spec-loop/specs/*` — the current functional description.
 - The actual code: `.claude/skills/`, `tools/`, `docs/`, `docs/modes.md`.
 - The appended **Compact repository inventory** block from the runner —
   use it as the first routing map before opening full files.

 Steps:

 1. **Check the `## Incremental scope` section appended below by the
    runner.** If it names a previous sync commit, run the `git diff
    --name-only` command it provides and treat that file list as the
    *only* surface to re-audit — everything else is already in sync as of
    that commit. If the diff is empty, exit without creating a branch or
    commit (print "specs already in sync as of <SHA>"). If no previous
    sync commit is recorded, fall through to a full inventory.
 2. Read the appended **Compact repository inventory**. Use it to identify
    likely spec/source relationships and validation commands before opening
    full files. The inventory is a routing aid, not proof; confirm with a
    code search before recording something as present or absent.
 3. **Create a uniquely-named sync branch off the integration base**, then
    switch to it: `git checkout -b "sync-specs-$(date +%Y%m%d-%H%M%S)"`. A
    fresh branch every run keeps each sync as its own reviewable PR and
    never collides with or commits on top of a previous `sync-specs*`
    branch. Note the exact name you created — you will print it in the
    human-run commands below. Never commit the sync to the integration
    branch.
 4. Inventory the code with parallel subagents (full inventory only if
    step 1 did not narrow the surface):
    - every `.claude/skills/*/SKILL.md` (name, mode, what it does);
    - every `tools/*` project (what it does, its tests);
    - the mode/status table in `docs/modes.md`.
 5. Diff that inventory against `tools/spec-loop/specs/`:
    - **New functionality with no spec** → author a new topic-named spec
      (no number prefix) following the format in
      [`specs/README.md`](specs/README.md), grounded in the real code it
      describes.
    - **Drifted spec** → a spec whose *Where it lives*, *Behaviour &
      contract*, or `status` no longer matches the code → update it to
      match reality (e.g. a `proposed` area that now has a shipped skill
      becomes `experimental`/`stable`; skill counts in `docs/modes.md`
      are reflected).
    - **Removed functionality** → mark the spec or move it to a `Known
      gaps`/retired note; do not silently delete history.
 6. Update `specs/overview.md` and `specs/README.md` indexes if areas were
    added or renamed.
 7. `git add -A` then `git commit` with subject
    `docs(spec-loop): sync specs with contributed functionality` and a
    `Generated-by: <agent> (<model>)` trailer, where `<agent>` and
    `<model>` are the actual agent and model you are running as (e.g.
    `Claude (Opus 4.8)`, `OpenCode (Big Pickle)`) — do not hardcode
    either. **Do NOT touch
    `tools/spec-loop/.last-sync` yourself** — `loop.sh` amends the marker
    into this commit after you finish, so the next `update` run knows to
    scope from `$BASE_HEAD`. Leaving it alone avoids merge conflicts with
    that amendment.

 Then STOP. Do NOT push, do NOT open a PR. Print the human-run commands:

 (substitute `<sync-branch>` with the exact branch name you created in
 step 2)

 ```text
 git push -u origin <sync-branch>
 gh pr create --web --base <integration-base> --head <sync-branch> \
   --title "Sync specs with contributed functionality" --body-file <body>
 ```

 Rules:

 - **Edit specs only.** This beat changes `tools/spec-loop/specs/` and
   the spec indexes. It must NOT change any skill, tool, or doc outside the
   spec directory — it documents reality, it does not alter it. The marker
   file `.last-sync` is owned by `loop.sh`; do not touch it.
 - Confirm with a code search before recording something as present or
   absent. Do not invent behaviour the code does not have.
 - Keep the RFCs untouched — they are a separate governance layer.
	<!-- SPDX-License-Identifier: Apache-2.0
	https://www.apache.org/licenses/LICENSE-2.0 -->

	You are running the update beat of the spec-driven loop. Specs can
	fall behind the code when contributors land functionality the normal
	way (a regular PR, not through this loop). This beat brings the specs
	back in sync with reality. It is the inverse of `plan`: `plan` finds code
	missing against specs; `update` finds **functionality missing against
	specs** and back-fills the specs.

	Context to load first:

	- `tools/spec-loop/AGENTS.md` and the repo-wide `/AGENTS.md`.
	- `tools/spec-loop/specs/*` — the current functional description.
	- The actual code: `.claude/skills/`, `tools/`, `docs/`, `docs/modes.md`.
	- The appended Compact repository inventory block from the runner —
	use it as the first routing map before opening full files.

	Steps:

	1. **Check the `## Incremental scope` section appended below by the
	runner.** If it names a previous sync commit, run the `git diff
	--name-only` command it provides and treat that file list as the
	only surface to re-audit — everything else is already in sync as of
	that commit. If the diff is empty, exit without creating a branch or
	commit (print "specs already in sync as of <SHA>"). If no previous
	sync commit is recorded, fall through to a full inventory.
	2. Read the appended Compact repository inventory. Use it to identify
	likely spec/source relationships and validation commands before opening
	full files. The inventory is a routing aid, not proof; confirm with a
	code search before recording something as present or absent.
	3. Create a uniquely-named sync branch off the integration base, then
	switch to it: `git checkout -b "sync-specs-$(date +%Y%m%d-%H%M%S)"`. A
	fresh branch every run keeps each sync as its own reviewable PR and
	never collides with or commits on top of a previous `sync-specs*`
	branch. Note the exact name you created — you will print it in the
	human-run commands below. Never commit the sync to the integration
	branch.
	4. Inventory the code with parallel subagents (full inventory only if
	step 1 did not narrow the surface):
	- every `.claude/skills/*/SKILL.md` (name, mode, what it does);
	- every `tools/*` project (what it does, its tests);
	- the mode/status table in `docs/modes.md`.
	5. Diff that inventory against `tools/spec-loop/specs/`:
	- New functionality with no spec → author a new topic-named spec
	(no number prefix) following the format in
	[`specs/README.md`](specs/README.md), grounded in the real code it
	describes.
	- Drifted spec → a spec whose Where it lives, *Behaviour &
	contract*, or `status` no longer matches the code → update it to
	match reality (e.g. a `proposed` area that now has a shipped skill
	becomes `experimental`/`stable`; skill counts in `docs/modes.md`
	are reflected).
	- Removed functionality → mark the spec or move it to a `Known
	gaps`/retired note; do not silently delete history.
	6. Update `specs/overview.md` and `specs/README.md` indexes if areas were
	added or renamed.
	7. `git add -A` then `git commit` with subject
	`docs(spec-loop): sync specs with contributed functionality` and a
	`Generated-by: <agent> (<model>)` trailer, where `<agent>` and
	`<model>` are the actual agent and model you are running as (e.g.
	`Claude (Opus 4.8)`, `OpenCode (Big Pickle)`) — do not hardcode
	either. **Do NOT touch
	`tools/spec-loop/.last-sync` yourself** — `loop.sh` amends the marker
	into this commit after you finish, so the next `update` run knows to
	scope from `$BASE_HEAD`. Leaving it alone avoids merge conflicts with
	that amendment.

	Then STOP. Do NOT push, do NOT open a PR. Print the human-run commands:

	(substitute `<sync-branch>` with the exact branch name you created in
	step 2)

	```text
	git push -u origin <sync-branch>
	gh pr create --web --base <integration-base> --head <sync-branch> \
	--title "Sync specs with contributed functionality" --body-file <body>
	```

	Rules:

	- Edit specs only. This beat changes `tools/spec-loop/specs/` and
	the spec indexes. It must NOT change any skill, tool, or doc outside the
	spec directory — it documents reality, it does not alter it. The marker
	file `.last-sync` is owned by `loop.sh`; do not touch it.
	- Confirm with a code search before recording something as present or
	absent. Do not invent behaviour the code does not have.
	- Keep the RFCs untouched — they are a separate governance layer.