review-local

Annai review — local-agent mode

Entry point for reviewing local agent work. No GitHub PR. Reviewer feedback lands as result.json for the agent to consume — there's nothing to push to a remote. The mode-specific steps are inlined below; for everything else (surface authoring rules, launch, watch, react, cleanup) load the annai:review skill — it owns the shared procedure. When the shared procedure says "this step is mode-specific", come back here.

Step 1 — Determine the diff source

In local-agent mode there is no GitHub PR. The diff comes from the working tree or a recent branch the agent (or human) has been working on. Decide which, in this precedence order:

1. The user told you which ("review my staged changes", "review the diff between main and HEAD", "review what I just changed in src/foo"). Follow that exactly.
2. There are uncommitted changes in the working tree. Use them. Run git status --porcelain inside the repo; if it shows any entries, capture the diff with git diff HEAD > /tmp/local.diff (this picks up both staged and unstaged work in one shot).
3. The branch has diverged from its base. Resolve the base ref: try git symbolic-ref --short refs/remotes/origin/HEAD to find the remote default branch; fall back to main (then master) if that fails. Capture the diff with git diff <base>...HEAD > /tmp/local.diff.
4. Ambiguous — e.g. there are uncommitted changes but they look unrelated to whatever the user asked you to review, or there's nothing diverged and no working-tree changes either. Don't guess: call AskUserQuestion with the candidate sources as options, and re-enter Step 1 with the answer.

Decide a short subject title (one phrase, ~60 chars) summarizing the change — e.g. "Wire up scheduler retry path" or "Agent draft: add JWT validation". You'll pass this as --title to the scaffold.

Step 3a — Scaffold

"${CLAUDE_PLUGIN_ROOT}/skills/review/scripts/annai.sh" surface scaffold-local \
  --repo <local-repo-path> \
  --diff /tmp/local.diff \
  --title "<your subject title>" \
  --base-ref "<base ref you diffed against, e.g. HEAD or main>" \
  --head-ref "<WORKTREE or HEAD — see below>" \
  --out <session-dir>/surface.json

--branch is optional and defaults to git rev-parse --abbrev-ref HEAD inside --repo. --base-ref defaults to HEAD when omitted (matches the git diff HEAD case); always pass it explicitly when you used a <base>...HEAD diff so the rendered header tells the reviewer what they're looking at.

--head-ref tells the scaffold where to read the post-change full file contents from so the reviewer can expand context up to the whole file:

• Pass WORKTREE (the default) when the diff was produced from git diff HEAD or git diff — the head side is your uncommitted working tree.
• Pass HEAD (or any ref) when the diff was produced from git diff <base>...HEAD — the head side is the committed branch tip, not the working tree.

If --head-ref is wrong, expand-context might show stale or missing surrounding lines; the diff itself still renders correctly from the parsed hunks.

The scaffold writes a schema-valid skeleton with subject: { kind: 'local', title, branch, baseRef, stats }, one unsorted supporting group containing every changed file, and empty tldr / reviewPrompts / diagrams / per-diff annotations / suggestions. Each diff gets a stable id like diff-src-foo-ts you'll reference in later commands.

scaffold-local does not shell out to gh. The agent owns the git invocation that produced the diff.

Step 5 — Finish-line message

When you tell the user the surface URL, end with:

Draft notes inline / per-file / at the top of the review, then hit Finish review to save your feedback or Dismiss session to throw it away. I'll pick up your notes once you finish.

There's no Approve button in this mode — the only positive action is Finish review, which persists the drafts as result.json for the agent to read back.

Step 7 — Read the result

On review-submitted:

"${CLAUDE_PLUGIN_ROOT}/skills/review/scripts/annai.sh" result \
  --session "<session-id>"

result dumps the result.json payload as JSON — the drafts (line, range, file-level, and the overall body) the reviewer left. Translate those into agent-actionable notes for whatever the downstream work is: apply the corrections, file follow-up tasks, ask the user clarifying questions, etc.

Do not call annai.sh submit in this mode — it's a PR-only command and will refuse with a "use annai.sh result instead" message if you do.