OpenSpec Extension: Review Plan

Review an OpenSpec change and produce a concrete, thread-friendly review report.

Output: Write to CHANGE_DIR/review/review-YYYYMMDD-HHMMSS.md (create review/ if missing).

Prerequisites

No external agent is required by default.

Run the review directly in the current agent unless the user explicitly asks to use an external reviewer.

If (and only if) the user explicitly requests external review:

• claude, claude code, and claude-<suffix> require $claude-code-invoke-once
• copilot and copilot-<suffix> require $copilot-invoke-once

Treat claude-<suffix> as Claude Code with wrapper handling, and treat copilot-<suffix> as Copilot with wrapper handling.

If the requested external dependency (after normalization to Claude or Copilot family) is missing, report a clear error listing the missing skill and do not attempt an ad-hoc fallback command.

Workflow

1) Select The Change To Review

• If the user specifies a change name, use it.

• Otherwise, infer the “current” change from conversation context (the change the user is already discussing/implementing).

• If you still cannot determine it, list available changes and ask the user to pick one:

  openspec list --sort recent --json

  Show the most recent 3-6 changes with their task counts/status, mark the most recent as “(Recommended)”, then ask which to review.
  If your harness has an “AskUserQuestion” tool, use it; otherwise ask in plain text.

2) Load Change Artifacts (And Locate CHANGE_DIR)

1. Check schema + artifact status:

   openspec status --change "<change-name>" --json

2. Get change directory + context files:

   openspec instructions apply --change "<change-name>" --json

   Parse:

   • changeDir (this is CHANGE_DIR)
   • contextFiles (proposal/specs/design/tasks, depending on schema)

3. Read all available artifacts listed by contextFiles.
   If any entry is a glob (example: specs/**/*.md), expand it by listing files on disk.

3) Perform The Review

Cover at least:

• Completeness: Are required artifacts present for the schema? Are tasks concrete and ordered?
• Internal coherence: Do specs match design? Does design justify tasks? Any contradictions or missing invariants?
• Design alignment with the existing system:
  • Identify the impacted modules and existing architectural patterns in the repo.
  • Check whether the proposed design follows those patterns (naming, layering, config, error semantics, boundaries).
  • Call out mismatches with concrete file/path references and suggest a more “native” approach.
• Risk and testability: What could break? What needs unit vs integration tests?

When uncertain, be explicit about uncertainty and turn it into an open question or a suggested validation step.

4) Write The Review Report

Create CHANGE_DIR/review/ if missing, then write review-YYYYMMDD-HHMMSS.md using a UTC timestamp.
Include an ISO-8601 timestamp in the header for machine readability.

Review Report Template

Use this header (and keep it stable so reviews are easy to diff/scan):

# OpenSpec Change Review: <change-name>

- Change: `<change-name>`
- Schema: `<schema-name>`
- Timestamp: `<YYYY-MM-DDTHH:MM:SSZ>`
- Artifacts reviewed:
  - <path>
  - <path>
  - ...

## Response Format (Decision Contract)

When responding to open questions in this review, use a `DECISION` blockquote immediately after each question's final `Pros / Cons (Proposal)` subsection:

```markdown
> **DECISION: <one-line decision summary>.**
> Rationale: <codebase-grounded justification with concrete evidence>.

Rationale contract:

• Ground decisions in repository evidence (specific paths, symbols, and line numbers when possible).
• Explain why the chosen option fits existing architecture/patterns better than alternatives.
• Call out implementation implications (new fields/errors/tests/migrations) when applicable.
• When useful, include concise Markdown fenced code blocks to show the exact branch, API shape, or state transition under discussion.
• Keep rationale concise and concrete (typically 2-5 sentences).

Placement contract:

• Insert the DECISION blockquote directly after Pros / Cons (Proposal) for that question.
• Keep any follow-ups after the decision block so outcomes remain easy to scan.

Summary

• <2-6 bullets: what’s solid + what’s risky>

Findings

Must Fix / Blocking

• ...

Should Fix / Important

• ...

Nice To Have

• ...

Design Alignment With Existing System

• Existing pattern(s) observed: <paths / modules>
• Proposed design alignment: <aligns/mismatches + concrete suggestions>

Open Questions (With Proposed Defaults)

Q1)

• Decision: Blocking | Deferrable

Why this matters

• ...

Examples

• <concrete scenario showing ambiguity in behavior/output>

Why this question arises in code

• <where ambiguity appears: files/modules/code paths>
• <which branch/condition/state transition is currently undecided>

Options

Option A: ...

• Code impact:
  • <how this maps to code paths/data flow; include short pseudo code in a fenced Markdown code block when helpful>
• User-facing difference:
  • <observable UX/output/error/ops difference>
• Pros:
  • ...
• Cons:
  • ...

Option B: ...

• Code impact:
  • <how this maps to code paths/data flow; include short pseudo code in a fenced Markdown code block when helpful>
• User-facing difference:
  • <observable UX/output/error/ops difference>
• Pros:
  • ...
• Cons:
  • ...

Proposal (Recommended)

Pros / Cons (Proposal)

• Pros:
  • ...
• Cons:
  • ...

DECISION: .
Rationale: .

Suggested Next Steps

## External Review Agent Support

Use external review agents only when the user explicitly requests them.

Supported external reviewer commands:

- `claude` / `claude code`
- `copilot`
- `claude-<suffix>` (alias of Claude Code with wrapper handling)
- `copilot-<suffix>` (alias of Copilot with wrapper handling)

If the user does not specify an external reviewer, perform the review directly in the current agent.

Agent-specific requirements (only when explicitly requested):

- For Claude (`claude`, `claude code`, or `claude-<suffix>`), use Claude Code with an Opus model.
- Invocation details for Claude Code are delegated to `$claude-code-invoke-once`; follow that skill for exact command/session/flag handling.
- For Copilot (`copilot` or `copilot-<suffix>`), use the latest Opus model with high reasoning effort.
- Invocation details for `copilot` are delegated to `$copilot-invoke-once`; follow that skill for exact command/config composition.
- For wrapper-style reviewer names (for example, `claude-<suffix>` / `copilot-<suffix>`), rely on the underlying invocation skill to resolve and handle wrapper-specific command details.

## Guardrails

- Do not silently switch changes; always confirm the chosen change when selection was ambiguous.
- Prefer actionable feedback over vague opinions; cite concrete artifacts/paths.
- Keep “Open Questions” as a separate section and include a proposed default for each question.
- Default behavior is in-agent review (no external reviewer) unless the user explicitly requests an external reviewer.
- Normalize reviewer aliases before dispatch: `claude-<suffix>` -> Claude Code family; `copilot-<suffix>` -> Copilot family.
- If the user requests Claude (`claude`, `claude code`, or `claude-<suffix>`), require Claude Code + Opus model, and defer exact invocation mechanics to `$claude-code-invoke-once`.
- If the user requests Copilot (`copilot` or `copilot-<suffix>`), require latest Opus model + high reasoning effort, and defer exact invocation mechanics to `$copilot-invoke-once`.
- For wrapper-style reviewer names, let the underlying invocation skill handle wrapper-specific execution details.
- If the requested external invocation skill is unavailable for the normalized family, refuse that external path and report the missing dependency instead of attempting ad-hoc fallback commands.
- Do NOT assume an external agent has this skill installed or can read files from this repo.
  - Construct a plain prompt that includes all instructions from this skill (paste the contents of this `SKILL.md`), plus the selected change name (if known), and ask the other agent to execute the workflow and produce the review report at the specified output path.