review-spec

Files (1)

• SKILL.md

SKILL.md (first lines)

# review-spec

Process one or more **pending review batches** for specs in the global store:
reply inline to each comment thread and amend the spec per the comments. The
browser updates live (the spec file change triggers an SSE reload).

`${CLAUDE_PLUGIN_ROOT}` below denotes the installed plugin directory. Claude and
Pi export it; Codex provides the exact value in SpecForge SessionStart context.
Substitute that value in every path and shell command. Specs live in the
store at `~/.specforge/specs/<id>/spec.html`; you address them by spec **id**
(the hook message lists each batch's `specId` + `batchId`).

## 1. Load the threads + the spec path

For a batch's spec id:

```
node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" comments <id>
```

The payload is **batch-scoped**: only the threads named in the spec's pending
batches, plus the language contract. Resolved history and discussion threads are
excluded — exactly the threads this skill says to leave alone. The rare flow
that genuinely wants every thread (exporting a comment history, auditing)
passes `--all`.

**A batch is not every thread on the spec.** Only threads where a human wrote
`@agent` are submitted; the rest are discussion between people and are not yours
to answer. Work the `threadIds` on the pending batch, and leave the others alone
even when you can see them and have an opinion.

Threads can carry **several people**. Each comment has an `author` (a display
name) and a `kind` of `human` or `agent`. Reply to the thread, not to one person,
and never assume the person who opened it is the one who added the mention.

It prints `{ specId, htmlPath, language, threads, pending }`. `htmlPath` is the
spec file to edit; each thread has `anchor.block` (`{ index, tag, text }` —
`text` is the commented block's normalized text) and the human comment(s).

**`language` is the writing contract in force, and it is the whole of it.** Not a
note added to a contract you read somewhere else: it already contains SpecForge's
own rules, unless this store's owner edited or removed them. It applies to
everything you write here: replies, amendments, and asides alike, because a
register that changed between the spec body and the drafts written into it would
read as two authors. Follow what it says and nothing it does not.
Do not go looking for `references/spec-language.md` to supplement it: a rule the owner deleted is deleted.
They edit this in the Configuration pane, under Language.

## 1a. Read the batch's `origin` — it decides what you may do

Every pending batch carries `origin`, and it is the first thing to look at:

| `origin` | Who submitted | What you may do |
|---|---|---|
| `daemon` | The **owner**, from their own loopback page | Reply **and** amend the spec. The flow below, unchanged. |
| `share` | A **reviewer**, through a shared link or project | **Reply only.** Do not edit the spec. |

**On a `share` batch, `Edit` is not among your permitted actions.** Not on
`htmlPath`, not on any file in the store. You answer the question, and that is
the whole job. A reviewer holds a link, which says nothing about whose spec it
is; the owner decides what the document says.

That is not a limitation to apologise for in your reply, and not something to
mention at all unless asked. Answer the question on its merits. If the reviewer
proposed a change you think is right, say what you think and stop — do not
promise an edit, and do not say you are "unable" to make one.

**How a reviewer's suggestion becomes an edit:** the owner adds their own
`@agent` comment to the thread from their loopback page. That produces a
`daemon` batch carrying the *whole thread* — the reviewer's original, the
discussion, and the owner's instruction — and on that batch you amend the
document, reading everything as context and executing the owner's comment.
Nothing is lost by waiting, and nothing needs a queue: the thread is the queue.

A batch with no `origin` field predates it and is the owner's.

## 2. Get the spec MAP (don't read the whole file)

```
node "${CLAUDE_PLUGIN_ROOT}/lib/spec-nav-cli.mjs" map --spec "<htmlPath>"
```

This gives the whole shape (sections, plan, line ranges, token sizes) in a few
hundred tokens — most of the raw HTML is boilerplate. Pull only the sections you
touch.

## 3. Mark the batch in-progress, then process each thread

Before amending, signal you're actively on it — the browser's action button flips
from "Picked up comments" to "Working on comments":

```
node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" batch-working <id> <batchId>
```

Then, for each thread **listed in the batch** (not every thread on the spec).
**On a `share` batch, skip steps 1 to 3 entirely** — locating, cross-referencing
and amending are all edit work — and go straight to step 4, the reply:

1. **Locate** the commented block: grep a distinctive phrase from
   `anchor.block.text`, then open just that section (it reports the exact line
   range):

   ```
   node "${CLAUDE_PLUGIN_ROOT}/lib/spec-nav-cli.mjs" grep "<phrase>" --spec "<htmlPath>"
   node "${CLAUDE_PLUGIN_ROOT}/lib/spec-nav-cli.mjs" section <id> --spec "<htmlPath>"
   ```
2. **Find coupled sections before editing** — `xrefs <id>` and `grep "<old
   term>"` to find every place a changed term/number appears; open and edit those
   too.
3. **Amend** `htmlPath` with the Edit tool. **Preserve every `<section id="…">`
   and its id**; keep the theme CSS and the floating TOC (the review layer owns
   theme + width). After changing a term/number, re-run `grep "<old term>"` and
   expect **zero hits**. Re-run the lint if you changed structure:
   `node "${CLAUDE_PLUGIN_ROOT}/lib/lint-spec.mjs" "<htmlPath>" --project "${CLAUDE_PLUGIN_ROOT}"`.

   Prose you add is held to the same language contract as the original, which is
   the `language` from step 1 and not the file on disk. Read it there; no summary
   of it appears here, because a summary would go on stating a rule this store's

From NitinJ/specforge, MIT.

More from NitinJ/specforge