Ss Code Review

Multi-Agent Code Review

Review a diff using independent, parallel subagents: one for general code quality, up to three for coding-standard compliance (global, stack, and project level), one for OpenSpec compliance when delta specs are present, and — in post-coding mode with enough scope — one cross-task integration reviewer. Each subagent reviews in isolation; none sees another's output. The confidence score each subagent reports is used to filter out false positives.

Core principle: several independent perspectives catch more than one comprehensive reviewer would, and isolation prevents anchoring bias.

Inputs

Supply one of:

• a pull request URL (what GitLab calls a merge request, or MR — same concept, detected automatically);
• an explicit SHA range (--base --head );
• nothing, to review the current branch against its upstream merge-base.

For the post-coding mode invoked by ss-coding, also supply --post-coding --plan .

If a URL is given, also fetch its title, description, and commit messages for context.

Iron Rules

1. Subagents are independent — each reviewer works in isolation; never share one subagent's findings with another.
2. Subagents score their own confidence — each assigns a 0-100 confidence score to every issue it reports. The orchestrator only filters by threshold; it never re-scores.
3. Don't trust self-assessment — "looks good" from a subagent that cited no file:line evidence gets one re-dispatch with an explicit instruction to look again. If the second attempt is still empty, accept it.
4. No false courtesy — don't soften or inflate findings; be direct, specific, and actionable.
5. The orchestrator doesn't review — you dispatch subagents, filter by threshold, consolidate results, and format the output. You never add your own opinion or judge code quality.
6. Only flag new issues — subagents flag issues only on lines modified in this diff. Pre-existing problems on untouched lines are not issues.

Input Handling

| Input | Detection | Method | |---|---|---| | GitLab MR URL | URL path contains /merge_requests/ | glab mr diff + glab mr view | | GitHub PR URL | URL path contains /pull/ | gh pr diff + gh pr view | | Explicit SHA range | --base --head | git diff .. | | Current branch, no args | no arguments given | auto-detect the upstream default branch, compute the merge-base, then git diff ..HEAD | | Post-coding mode | --post-coding --plan | same diff detection as above, plus reading the plan file for task context; enables Integration Review and the structured FIX_LIST output |

Edge cases:

• neither glab nor gh is available → fall back to git diff and ask the user for base/head SHAs;
• the diff is empty (base = head) → report "no changes to review" and stop;
• a subagent dispatch fails or times out → skip it, proceed with the rest, and note the gap in the report.

Specs Discovery

Before dispatching subagents, discover which specs apply:

1. Read CLAUDE.md/AGENTS.md at the project root.
2. Categorize the specs in play:

• Global specs — the shared guardrails at ../ss-guardrails/core.md (security, test standards, review standards, commit-message format).
• Stack specs — the guardrails file matching the project's stack: ../ss-guardrails/java.md, go.md, cpp.md, web.md, android.md, ios.md, or flutter.md.
• Project specs — project-level rules from CLAUDE.md/AGENTS.md content, or a project-specific rules directory if the project has one.

1. Dispatch rules:

• General CR → always dispatched.
• Global Compliance → always dispatched (../ss-guardrails/core.md always applies).
• Stack Compliance → only if a matching stack guardrails file exists.
• Project Compliance → only if CLAUDE.md/AGENTS.md contain project-specific rules, or a project-specific rules directory exists.
• OpenSpec Compliance → only if the diff includes openspec/specs/**/spec.md, openspec/changes/**/specs/**/spec.md, or active delta specs exist in the working tree.
• Integration Review → only in post-coding mode (plan context provided), and only when the change spans 3+ tasks or 5+ files.

Execution Process

digraph cr_process {
    rankdir=TB;

    "Fetch diff + context" [shape=box];
    "Discover specs" [shape=box];
    "Dispatch standard agents in parallel" [shape=box];
    "Post-coding mode?" [shape=diamond];
    "Dispatch Integration Review" [shape=box];
    "Collect results" [shape=box];
    "Filter by confidence threshold" [shape=box];
    "Deduplicate" [shape=box];
    "Consolidate report" [shape=box];

    "Fetch diff + context" -> "Discover specs";
    "Discover specs" -> "Dispatch standard agents in parallel";
    "Discover specs" -> "Post-coding mode?";
    "Post-coding mode?" -> "Dispatch Integration Review" [label="yes + 3+ tasks"];
    "Post-coding mode?" -> "Collect results" [label="no / small scope"];
    "Dispatch standard agents in parallel" -> "Collect results";
    "Dispatch Integration Review" -> "Collect results";
    "Collect results" -> "Filter by confidence threshold";
    "Filter by confidence threshold" -> "Deduplicate";
    "Deduplicate" -> "Consolidate report";
}

Step 1: Fetch the Diff & Context

git diff --name-only ..   # changed files
git diff ..               # full diff
git log --oneline ..      # commit messages

Also gather the PR title and description (if a URL was given) and the total lines changed.

Step 2: Dispatch Subagents in Parallel

Dispatch every applicable subagent at once. Each receives the full diff plus its own review instructions.

For large diffs (>2000 lines): split the General CR subagent's work by file group (~500 lines each) and dispatch several. Compliance subagents get the full diff regardless (rule-matching scales sub-linearly with code volume) unless the diff exceeds 5000 lines, in which case split them by file type too (e.g., source files vs. config files).

OpenSpec Compliance Agent

Dispatch this reviewer whenever OpenSpec source-of-truth or delta files are present — active deltas, archived deltas, and merged openspec/specs//spec.md changes created by the ss-archive skill.

Spawn a subagent:
  description: "OpenSpec compliance review"
  prompt: |
    You are an OpenSpec Compliance Reviewer. Review this diff against the
    repository's OpenSpec living specs and active delta specs.

    ## Diff

    [FULL DIFF]

    ## Active or Archived Delta Specs

    [PASTE openspec/changes/**/specs/*/spec.md relevant to this diff]

    ## Source-of-Truth Specs

    [PASTE relevant openspec/specs/*/spec.md]

    ## What to Check

    - Delta files use exact section headings: ADDED, MODIFIED, REMOVED, RENAMED Requirements.
    - Every Requirement has at least one `#### Scenario:`.
    - MODIFIED Requirements copy the original source-of-truth Requirement in full before showing the change.
    - REMOVED Requirements include both `**Reason:**` and `**Migration:**`.
    - RENAMED uses `FROM:  -> TO: `.
    - Archived deltas remain self-contained after archiving.
    - Source-of-truth files reflect the archived delta without dropping unrelated Requirements.
    - Requirement count is proportional to the code change — flag empty or inflated deltas.
    - Code and tests implement every Scenario's WHEN/THEN behavior.
    - Removed behavior has real migration coverage when callers are visible in the diff.

    Only flag issues introduced by this change. Include exact file:line evidence.

    Output each issue with:
    - tag: NEW | PRE-EXISTING
    - severity: CRITICAL | IMPORTANT | MINOR
    - file: exact path:line
    - description
    - reason
    - suggestion
    - confidence: 0-100

    Verdict: APPROVED | NEEDS_CHANGES

Step 3: Collect & Filter

After every subagent returns:

1. Filter by confidence — drop every issue scored below 75 by its reporting subagent.
2. Deduplicate — if multiple subagents flagged the same issue (same file:line, same problem type — bug/security/naming/pattern), keep the highest-confidence version and note how many subagents independently found it.
3. Determine the verdict:

• any CRITICAL-severity issue (confidence ≥ 90, functionality/security impact) → CRITICAL_ISSUES;
• any IMPORTANT-severity issue (confidence ≥ 75, quality impact) with no CRITICAL → NEEDS_CHANGES;
• only MINOR issues, or none → APPROVED.

Confidence Scoring Guide (for subagents)

| Score | Meaning | Criteria | |---|---|---| | 90-100 | Certain | an explicit spec rule is violated and the code clearly violates it, or it's a definite bug with evidence | | 75-89 | Highly confident | the spec implies this rule and the code likely violates it, or it's very likely a bug given the context | | 50-74 | Moderately confident | ambiguous — the spec could be read either way, or this might be intentional | | 25-49 | Somewhat confident | might be real, might be pre-existing or a stylistic preference | | 0-24 | Not confident | doesn't hold up to scrutiny, likely a false positive |

Every subagent also tags each issue NEW (introduced by this change, on a modified line) or PRE-EXISTING (already there, on an untouched line). Only NEW issues make it into the final report.

False Positives — Do Not Flag

All subagents must avoid:

• pre-existing issues on lines not modified in this diff;
• issues a linter, typecheck, or CI would already catch (imports, types, formatting);
• intentional functionality changes that are the point of the PR;
• issues already silenced in code (lint-ignore, nolint, @SuppressWarnings).

Compliance subagents must also avoid general code-quality opinions not tied to their assigned spec rules, and style preferences not documented in those specs.

The General CR subagent must also avoid nitpicks a senior engineer wouldn't flag, and "while you're at it" suggestions unrelated to the change.

Subagent Prompt Templates

General CR Agent

Spawn a subagent:
  description: "General code review"
  prompt: |
    You are a Senior Code Reviewer. Review this diff for bugs, architecture
    issues, test quality, and production readiness.

    ## Diff

    [FULL DIFF]

    ## PR Context

    [Title, description, commit messages]

    ## What to Check

    **Bugs & Correctness:**
    - Logic errors, off-by-one, race conditions, null derefs
    - Error handling complete (not just the happy path)
    - Resource leaks, unclosed connections
    - Inputs validated at system boundaries
    - Security: injection, auth bypass, data exposure

    **Functional Completeness:**
    - Does the change achieve what the PR description claims?
    - Are there requirements mentioned but not implemented?
    - Unauthorized scope reduction: stubs or placeholder logic presented as
      finished work, hardcoded/mock data standing in for real behavior,
      "simplified for now" / "will be wired later" comments, or requirements
      quietly deferred to a later phase, MVP, or v2. Flag as CRITICAL unless
      an explicit user decision to cut or defer that scope is recorded in the
      plan file's "User-Confirmed Scope Adjustments" section (post-coding mode)
      or in the PR description (standalone mode).
    - Are there extra features added but not described? (scope creep)
    - If a plan or task list is provided, does every task appear fulfilled?

    **Architecture & Design:**
    - Sound design decisions for the scope
    - No unnecessary coupling or complexity
    - Integrates cleanly with surrounding code
    - Each file has one clear responsibility
    - Complexity proportional to the problem (no over-engineering)

    **Test Quality:**
    - New behavior has corresponding tests
    - Tests verify behavior, not implementation details
    - Tests are independent (no shared state, no order dependency)
    - Edge cases covered for critical paths
    - No test hacks (modifying tests to pass instead of fixing code)

    **Production Readiness:**
    - Backward compatibility considered
    - Performance: no N+1 queries, no unbounded operations
    - No sensitive data logged or exposed
    - No dead code, commented-out code, or debug artifacts

    ## Critical Rules

    Only flag issues on lines modified in this diff.
    Tag each issue NEW (on a modified line) or PRE-EXISTING (on an untouched line).

    Do NOT flag:
    - Pre-existing issues on unmodified lines
    - Issues a linter/typecheck/CI would catch
    - Nitpicks a senior engineer wouldn't mention
    - Intentional behavior changes that are the point of the PR

    ## Output Format

    For each issue:
    - tag: NEW | PRE-EXISTING
    - severity: CRITICAL | IMPORTANT | MINOR
    - file: exact path:line
    - description: what's wrong
    - reason: why it matters
    - suggestion: how to fix it
    - confidence: 0-100

    Strengths: 1-3 specific things done well (with file:line).
    Verdict: APPROVED | NEEDS_CHANGES

Global Compliance Agent

Spawn a subagent:
  description: "Global spec compliance review"
  prompt: |
    You are a Global Spec Compliance Reviewer. Check this diff against the
    GLOBAL guardrails: security, unit-test standards, review standards, and
    commit-message format.

    ## Diff

    [FULL DIFF]

    ## Global Guardrails

    [PASTE the full content of ../ss-guardrails/core.md]

    ## Your Scope

    Only check against the guardrails provided above. Focus areas:
    - Security rules (input validation, auth, data protection, injection)
    - Unit test standards (coverage, structure, naming, patterns)
    - Commit-message format (conventional commits, message length, type)
    - Review standards, if defined

    ## Critical Rules

    Only flag violations on lines modified in this diff.
    Tag each issue NEW or PRE-EXISTING.
    Only flag violations of rules explicitly stated in the provided guardrails.
    Don't add opinions beyond what the guardrails document.

    ## Output Format

    For each violation:
    - tag: NEW | PRE-EXISTING
    - spec_rule: "[guardrails file] section X, rule Y" (exact reference)
    - file: exact path:line
    - violation: what the code does
    - expected: what the guardrails require
    - confidence: 0-100
    - severity: CRITICAL | IMPORTANT | MINOR

    Verdict: COMPLIANT | HAS_VIOLATIONS | NOT_APPLICABLE

Stack Compliance Agent

Spawn a subagent:
  description: "Stack spec compliance review"
  prompt: |
    You are a Stack Spec Compliance Reviewer. Check this diff against the
    TECHNOLOGY STACK guardrails: naming conventions, API patterns, error
    handling, logging, and language-specific rules.

    ## Diff

    [FULL DIFF]

    ## Stack Guardrails

    [PASTE the full content of the guardrails file matching this repo's stack —
     ../ss-guardrails/java.md, go.md, cpp.md, web.md, android.md, ios.md, or flutter.md]

    ## Your Scope

    Only check against the guardrails provided above. Focus areas:
    - Naming conventions (classes, methods, variables, constants)
    - API design patterns (request/response structure, error codes)
    - Error/exception handling patterns
    - Logging patterns and levels
    - Language-specific idioms defined in the guardrails

    ## Critical Rules

    Only flag violations on lines modified in this diff.
    Tag each issue NEW or PRE-EXISTING.
    Only flag violations of rules explicitly stated in the provided guardrails.
    Don't flag style preferences the guardrails don't cover.

    ## Output Format

    For each violation:
    - tag: NEW | PRE-EXISTING
    - spec_rule: "[guardrails file] section X, rule Y" (exact reference)
    - file: exact path:line
    - violation: what the code does
    - expected: what the guardrails require
    - confidence: 0-100
    - severity: CRITICAL | IMPORTANT | MINOR

    Verdict: COMPLIANT | HAS_VIOLATIONS | NOT_APPLICABLE

Project Compliance Agent

Spawn a subagent:
  description: "Project spec compliance review"
  prompt

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [lbk-open](https://github.com/lbk-open)
- **Source:** [lbk-open/super-spec](https://github.com/lbk-open/super-spec)
- **License:** Apache-2.0
- **Homepage:** https://www.npmjs.com/package/@lbk-open/super-spec

Install and usage instructions live in the source repository linked above.