review-spec

Files (1)

• SKILL.md

SKILL.md (first lines)

# /pr-autopilot:review-spec

Pre-PR adapter dispatch on a markdown spec file. Idempotent and re-runnable.

Full algorithm + adapter inventory + cursor-cloud poll contract: `docs/superpowers/specs/2026-05-28-pr-autopilot-v0.5-pre-pr-lifecycle-design.md` (v2.2 §Pre-PR Adapter Layer + §`/review-spec`).
v0.5.1 changes (this version): `docs/superpowers/specs/2026-05-28-pr-autopilot-v0.5.1-review-spec-improvements.md`.

## Mode detection (READ FIRST — determines control flow)

If the invocation contains `--bootstrap` (either `--bootstrap=<path>` or `--bootstrap <path>`):

→ go to **Bootstrap mode** section. Do NOT proceed to "Pre-flight (normal mode)" or "Steps (normal mode)".

Otherwise (no `--bootstrap` argument):

→ go to **Pre-flight (normal mode)** section. Do NOT proceed to "Bootstrap mode".

Modes are mutually exclusive. Do not run both. If unclear which mode applies, refuse with:
`[pr-autopilot/review-spec] ambiguous invocation; expected either no args (normal mode) or --bootstrap <path>.`

## Argument parsing protocol

This skill is markdown that Claude interprets. There is no bash `getopts`. The contract for argument parsing:

- The invocation `/pr-autopilot:review-spec` with no arguments → **normal mode**.
- The invocation `/pr-autopilot:review-spec --bootstrap=<path>` → **bootstrap mode** with `<path>` as the spec file path. The path is the token immediately following the `=` sign.
- The invocation `/pr-autopilot:review-spec --bootstrap <path>` (whitespace-separated) → **bootstrap mode** with `<path>` as the spec file path. The path is the **first non-flag token** after `--bootstrap`.
- If the path token itself begins with `--`, Claude MUST treat it as a path (not a flag). E.g., `--bootstrap --weird-name.md` is a path of `--weird-name.md`. (Rare; documented for completeness.)
- If `--bootstrap` is followed by nothing (end of invocation), refuse with: `[pr-autopilot/review-spec] --bootstrap requires a path argument; got none.`
- If `--bootstrap` is specified TWICE in the same invocation, refuse with: `[pr-autopilot/review-spec] duplicate --bootstrap flag; only one path is supported per invocation.`
- Single-dash `-bootstrap` is NOT supported → refuse with `[pr-autopilot/review-spec] unknown flag '-bootstrap'; did you mean '--bootstrap'?`.
- An additional flag `--force` may appear AFTER the path in bootstrap mode (e.g., `--bootstrap path.md --force`). It disables the enforcement guard. See B-Pre-flight step 2 in `references/bootstrap.md`.
- Before running ANY dispatch, Claude MUST verify the path exists via Read tool. If the file does not exist, refuse with: `[pr-autopilot/review-spec] --bootstrap path not found: <path>.`

## Pre-flight (normal mode)

Required preconditions for normal mode:

- Inside a worktree with `.claude/assignment-claims/<id>.json` present.
- `subStatus` is `spec_drafting`, `spec_revising`, or `spec_review_complete` (re-run after manual paste).
- Spec file exists at `claimFile.specFile` or auto-detect newest `specs/*-<id>.md`.

If preconditions fail, refuse with the corresponding error. Do NOT silently fall through to bootstrap mode.

## Bootstrap mode (v0.5.1)

Standalone, advisory-only review with no claim file (a repo's first pr-autopilot PR, a draft spec, or a review without the lifecycle). Read `${CLAUDE_SKILL_DIR}/references/bootstrap.md` when the invocation contains `--bootstrap` and follow it (it reuses normal-mode Steps 1.5–4 but never writes a claim file); in that file `<skill-dir>` means `${CLAUDE_SKILL_DIR}`.

## Steps (normal mode)

### Step 1 — read claim file + start

Read `.claude/assignment-claims/<id>.json`. Update `subStatus: spec_review_requested`. Increment `reviewIteration` if existing, else set to 1. Commit:
```bash
git add .claude/assignment-claims/<id>.json
git commit -m "chore(pr-autopilot): review-spec start for <id> (iter <n>)"
```

### Step 1.5 — print initial status table (v0.5.1, Gap D.1)

Before any dispatch, print to chat:

```markdown
🔄 **Reviewing spec at `<absolute-path>` (iter <n>)** ...

Dispatching reviewers:

| Reviewer | Type | Status |
|---|---|---|
| code reviewer (feature-dev or general-purpose fallback) | Claude subagent (FREE, always) | ⏳ pending |
| general-purpose adversarial | Claude subagent (FREE, hostile) | ⏳ pending |
| codex-exec | <if env+CLI set: ⏳ pending; else: ⏭ skipped (no OPENAI_API_KEY / codex)> |
| cursor-cloud-agent | <after probe: ⏳ pending (Pro) OR ⏭ skipped (Free/invalid/network)> |
| composer-2.5 manual | FREE paste-back | 📋 prompt will print below |
```

Then write TodoWrite with a **single sentinel item** for the whole dispatch (NOT one per reviewer). This respects TodoWrite's hard constraint "Exactly ONE task must be in_progress at any time":

```typescript
TodoWrite([
  { content: "/review-spec dispatch (iter <n>) — N reviewers in parallel",
    activeForm: "Running N reviewers in parallel (iter <n>)",
    status: "in_progress" }
])
```

Where N is the count of channels actually dispatching (e.g., 2 for free-only, 3 with codex, 4 with cursor-cloud-agent on Pro). Per-channel status is shown in the chat status table above; TodoWrite is only the sticky sentinel.

In Step 4, this item flips to `completed` with `activeForm: "Done: N reviewers, X P0 / Y P1 / Z P2"`.

v0.5.1 limitation: status table updates atomically at Step 4 (since subagent dispatch via Agent tool is foreground/blocking — once a single Agent-call message dispatches multiple subagents in parallel, all complete before control returns). TRUE incremental per-reviewer status updates are v0.6+ (Gap D.2 — see ROADMAP for hooks-based vs MCP-server-based architecture choice). The chat status table above provides the visual map; the single TodoWrite sentinel provides sticky persistence.

### Step 2 — dispatch sync adapters in parallel

**Graphify dispatch-time filesystem check (v0.5.3+):** before dispatching adapters, check whether this repo has a graphify code knowledge graph at `graphify-out/graph.json`. /review-spec has NO per-PR state file (bootstrap mode has no PR; normal mode hasn't loaded claim state at this point), so the check is purely filesystem-based:

```bash
# PR #9 review P1 fix: also gate on `advisory != "off"` so the hint is NEVER injected
# when the user opted out at the config level, even if a graph happens to exist on disk.
# Matches the /step §0.6a contract: advisory=off means "skip entirely" everywhere.
if [ "${config_graphify_advisory:-auto}" != "off" ] \
  && [ -f "graphify-out/graph.json" ] \
  && [ "${config_graphify_promptHint:-true}" = "true" ]; then
  _graphifyHintEnabled="true"
else
  _graphifyHintEnabled="false"
fi
```

When `_graphifyHintEnabled == "true"`, the **claude-code-reviewer-subagent** and **claude-self-review** prompts (see "Adapter prompts" below) get a graphify hint prepended that tells the subagent to query the graph before grep'ing files.

For cursor-cloud-agent, run the **probe FIRST** to determine plan eligibility:
```bash
# Resolved from this skill's directory, so it works for any installed version
# (replaces the old fallback pinned to the 0.5.2 cache path).
bash "${CLAUDE_SKILL_DIR}/../../hooks/cursor-cloud-agent-probe.sh"
PROBE_EXIT=$?
```

From MarcinSufa/claude-pr-autopilot, MIT.

More from MarcinSufa/claude-pr-autopilot