review

<objective>

Spawn specialized sub-agents in parallel. Consolidate findings into structured feedback with severity levels.

NOT for local file review or current git diff — use /develop:review (requires develop plugin). NOT for non-Python source PRs (TypeScript, Go, Rust, etc.) unless they include Python files — docs-only and CI/CD-only PRs are in scope. NOT for standalone GitHub issue analysis or thread summarization — use oss:analyse. Note: oss:review performs inline linked-issue analysis (root-cause alignment check in Step 1) as part of PR review — within scope, no conflict.

</objective>

<inputs>

• $ARGUMENTS: PR number or report path.
• Number given (e.g. 42 or #42): review PR diff
• --reply: spawn oss:shepherd to draft contributor-facing PR comment. Path ending in .md → spawn oss:shepherd from that report, skip new review.
• Scope: Python source only. Non-Python file → state out of scope, suggest tool, no findings.
• Local files: use /develop:review (requires develop plugin) for local files or current git diff.
• --codemap: enable structural context from codemap index (off by default; requires codemap plugin installed)
• --semble: enable semble semantic search companion (off by default; requires semble MCP server configured)
• --plan handoff not supported — skill does not accept plan-mode output from /develop:plan (requires develop plugin).

</inputs>

<constants>

CHALLENGE_ENABLED=true # set to false via --no-challenge CODEMAP_ENABLED=false # set to true via --codemap SEMBLE_ENABLED=false # set to true via --semble <!-- Background agent health monitoring (CLAUDE.md §6) — applies to Step 3 parallel agent spawns --> MONITOR_INTERVAL=300 # 5 minutes between polls HARD_CUTOFF=900 # 15 minutes of no file activity → declare timed out EXTENSION=300 # one +5 min extension if output file explains delay

</constants>

<workflow>

<!-- Agent resolution: see _OSS_SHARED/agent-resolution.md -->

Agent Resolution

loads: oss-shared-resolver.md

Cold-start fallback (sets $_OSS_SHARED — run this first):

_OSS_SHARED=$(python "${CLAUDE_PLUGIN_ROOT:-plugins/oss}/bin/resolve_shared_path.py" oss skills/_shared 2>/dev/null) # timeout: 5000

Then: Read $_OSS_SHARED/oss-shared-resolver.md and execute its contents

$_OSS_SHARED is required by --reply mode (Step 8 reads shepherd-reply-protocol.md). For non-reply

flows the helpers are nice-to-have but not load-bearing — degrade gracefully instead of exiting.

if [ ! -d "$_OSS_SHARED" ]; then if [[ "$ARGUMENTS" == --reply ]]; then echo "⛔ _OSS_SHARED resolved to '$_OSS_SHARED' but dir absent — --reply requires oss plugin shared dir; verify oss plugin installed" exit 1 else echo "⚠ _OSS_SHARED resolved to '$_OSS_SHARED' but dir absent — continuing with degraded functionality (oss skill-specific shared helpers unavailable; --reply mode will not work in this run)" fi fi

Read $_OSS_SHARED/agent-resolution.md. Agents: foundry:sw-engineer, foundry:qa-specialist, foundry:perf-optimizer, foundry:doc-scribe, foundry:linting-expert, foundry:solution-architect, foundry:challenger, oss:cicd-steward.

<!-- Inline fallback (if agent-resolution.md unreadable): foundry:sw-engineer → general-purpose, foundry:qa-specialist → general-purpose, foundry:perf-optimizer → general-purpose, foundry:doc-scribe → general-purpose, foundry:linting-expert → general-purpose, foundry:solution-architect → general-purpose, foundry:challenger → general-purpose. -->

Task hygiene: Before creating tasks, call TaskList. Each found task:

• completed if work done
• deleted if orphaned / irrelevant
• in_progress only if genuinely continuing

Task tracking: TaskCreate each major phase. Mark in_progress/completed throughout. Loop retry or scope change → new task.

Step 1: Identify scope and context (run in parallel for PR mode)

Parse $ARGUMENTS flags (applied directly — no subprocess):

| Flag | Variable | Present | Absent | | --- | --- | --- | --- | | --reply | REPLY_MODE | true | false | | --no-challenge | CHALLENGE_ENABLED | false | true | | --codemap | CODEMAP_ENABLED | true | false | | --semble | SEMBLE_ENABLED | true | false |

CLEAN_ARGS: $ARGUMENTS with matched flags removed, leading whitespace stripped, leading # stripped.

# Preflight: fail early if requested tool not available
if [ "$CODEMAP_ENABLED" = "true" ]; then
    if ! command -v scan-query >/dev/null 2>&1; then
        printf "! --codemap requested but codemap plugin not installed.\n  Install: claude plugin install codemap@borda-ai-rig\n"; exit 1
    fi
    _PROJ=$(git rev-parse --show-toplevel 2>/dev/null | xargs basename)  # timeout: 3000
    if [ ! -f ".cache/scan/${_PROJ}.json" ]; then
        printf "! --codemap requested but no index found for project '%s'.\n  Build index: /codemap:scan-codebase\n" "$_PROJ"; exit 1
    fi
fi

If SEMBLE_ENABLED=true: proceed — semble MCP tool availability verified at first use. If mcp__semble__search is unavailable when called, it fails with a clear error; do not preemptively exit here.

Unsupported flag check — after all supported flags extracted, scan $ARGUMENTS for remaining --<token> tokens. Found: print ! Unknown flag(s): \--<token>\. Supported: \--reply\, \--no-challenge\, \--codemap\, \--semble\. then invoke AskUserQuestion — (a) Abort (stop, re-invoke with correct flags) · (b) Continue ignoring (skip unknown flags, proceed). On Abort: stop.

DIRECT_PATH_MODE=false
if [[ "$CLEAN_ARGS" == *.md ]]; then
    # Guard: reject plan files — shepherd must not draft replies from plan content
    if [[ "$CLEAN_ARGS" == .plans/* ]] || [[ "$CLEAN_ARGS" == *todo_*.md ]]; then
        echo "Error: plan files cannot be used as review report input. Pass a review report from .reports/review/<timestamp>/review-report.md or a PR number."
        exit 1
    fi
    # Validate file looks like a review report — guards against vitality reports, research reports,
    # arbitrary markdown. Required markers: at least one of `## Summary`, `verdict:`, or a
    # `APPROVED|NEEDS_WORK|REQUEST_CHANGES` token in the header region. If validation fails, warn
    # and fall back to normal review path (treat $CLEAN_ARGS as PR number — will fail the numeric
    # check below with a clear error if it isn't one).
    if [ -f "$CLEAN_ARGS" ] && grep -qE '(^## Summary|^verdict:|APPROVED|NEEDS_WORK|REQUEST_CHANGES)' "$CLEAN_ARGS" 2>/dev/null; then  # timeout: 5000
        DIRECT_PATH_MODE=true
        REVIEW_FILE="$CLEAN_ARGS"
    else
        echo "⚠ $CLEAN_ARGS is a .md file but lacks review-report markers (## Summary | verdict: | APPROVED|NEEDS_WORK|REQUEST_CHANGES) — refusing direct-path fast-path; continuing with normal review path which expects a PR number."
    fi
fi

FOUNDRY_SHARED=$(python "${CLAUDE_PLUGIN_ROOT:-plugins/foundry}/bin/resolve_shared_path.py" foundry skills/_shared 2>/dev/null)  # timeout: 5000
if [ -z "$FOUNDRY_SHARED" ]; then
    # Fallback to bare path so downstream Steps 5/7/consolidator don't fail on un-expanded variable;
    # they degrade gracefully when the file actually missing on disk via per-read guards.
    FOUNDRY_SHARED="plugins/foundry/skills/_shared"
    echo "⚠ Could not resolve FOUNDRY_SHARED via cache lookup — using bare fallback path '$FOUNDRY_SHARED'; foundry plugin may be absent — Steps 5/7/consolidator will degrade (per-file guards still fire)"
fi

if [ "$DIRECT_PATH_MODE" = "false" ]; then
    # $CLEAN_ARGS must be a non-empty numeric PR number:
    if [ -z "$CLEAN_ARGS" ] || ! [[ "$CLEAN_ARGS" =~ ^[0-9]+$ ]]; then
        echo "Error: PR number required. Usage: /oss:review <PR number> [--reply] [--no-challenge]"
        exit 1
    fi
    # Run all four in parallel:
    CHANGED_FILES=$(gh pr diff $CLEAN_ARGS --name-only 2>/dev/null)  # cache for reuse in codemap b