How Superpowers Facilitates Automated Code Reviews: A Two-Stage Subagent Workflow

Superpowers automates code reviews through a mandatory two-stage subagent workflow that enforces spec compliance and code quality checks before marking any task complete.

The obra/superpowers repository implements a subagent-driven development system that embeds rigorous code review directly into the development loop. Unlike manual review processes that can be skipped or rushed, Superpowers facilitates code reviews through automated subagents that verify every change against specifications and quality standards before allowing task completion.

The Two-Stage Review Architecture

Superpowers builds automatic code reviews into every development iteration by wiring dedicated reviewer subagents into the subagent-driven-development skill. According to the workflow defined in skills/subagent-driven-development/SKILL.md, each task follows a strict sequence: after an implementer subagent finishes (including a self-review), the system automatically dispatches a spec-compliance reviewer, and only upon approval dispatches a code-quality reviewer. The process loops until both reviewers approve, then marks the task complete【https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/SKILL.md#L40-L78】.

Stage 1: Spec-Compliance Verification

The first review stage ensures the implementer built exactly what was requested—nothing more, nothing less. The spec-reviewer-prompt.md explicitly instructs the reviewer to ignore the implementer’s report and verify the code line-by-line against the task’s requirements. It forces the reviewer to identify missing features, extra functionality, or misunderstood requirements, producing a concise verdict of either “✅ Spec compliant” or “❌ Issues” with specific file and line references【https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/spec-reviewer-prompt.md#L5-L15】【https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/spec-reviewer-prompt.md#L58-L60】.

Stage 2: Code-Quality Assessment

Only after the spec reviewer returns a passing verdict does the workflow launch the code-quality reviewer using the requesting-code-review skill template. The code-reviewer.md template defines a comprehensive checklist covering architecture, testing, production readiness, and general code quality, along with a structured output format that categorizes issues by severity. This ensures that structural and maintainability concerns are evaluated separately from functional correctness, preventing quality issues from being overlooked when the code technically “works”【https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/code-quality-reviewer-prompt.md#L7-L12】【https://github.com/obra/superpowers/blob/main/skills/requesting-code-review/code-reviewer.md#L30-L78】.

Enforced Review Loops and Fix Cycles

Superpowers eliminates the possibility of skipping reviews through mandatory enforcement loops. If either the spec-compliance or code-quality reviewer reports issues, the implementer sub-agent is forced to fix the problems, and the reviewer is invoked again. This loop repeats until the reviewer returns an approving verdict, ensuring that no unchecked defects slip through to mark a task complete【https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/SKILL.md#L71-L77】.

System Integration and Automation

The review process integrates deeply into the Superpowers stack to operate without manual intervention. The requesting-code-review skill is listed as a required workflow step in the repository’s README, making the review stage a mandatory checkpoint between tasks【https://github.com/obra/superpowers/blob/main/README.md#L81-L84】. Additionally, the tool-mapping in .opencode/plugins/superpowers.js injects the review template into the system prompt, ensuring the agent automatically knows how to invoke the reviewer without requiring user prompts【https://github.com/obra/superpowers/blob/main/.opencode/plugins/superpowers.js#L58-L70】.

Key Implementation Files

File	Role in the Review Process
skills/subagent-driven-development/SKILL.md	Defines the core two-stage review workflow and enforcement loops【https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/SKILL.md】
skills/subagent-driven-development/spec-reviewer-prompt.md	Prompt template that mandates independent spec verification with ✅/❌ verdict format【https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/spec-reviewer-prompt.md】
skills/subagent-driven-development/code-quality-reviewer-prompt.md	Prompt that triggers the detailed code-quality review using the requesting-code-review template【https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/code-quality-reviewer-prompt.md】
skills/requesting-code-review/code-reviewer.md	Comprehensive review template with architecture, testing, and production-readiness checklists【https://github.com/obra/superpowers/blob/main/skills/requesting-code-review/code-reviewer.md】
README.md	Documents the requesting-code-review skill as a mandatory workflow checkpoint【https://github.com/obra/superpowers/blob/main/README.md】
.opencode/plugins/superpowers.js	Plugin that injects review tools into the system prompt for automatic invocation【https://github.com/obra/superpowers/blob/main/.opencode/plugins/superpowers.js】

Summary

Superpowers facilitates automated code reviews through a rigid, subagent-driven architecture that eliminates manual oversight gaps. The key mechanisms include:

• Two-stage verification: Every task undergoes sequential spec-compliance and code-quality reviews by independent subagents before completion.
• Enforced iteration: Review loops automatically force implementers to fix reported issues and re-submit until both reviewers return explicit approval verdicts.
• System integration: The requesting-code-review skill is hard-coded as a mandatory workflow step, with tool mappings injected via the Superpowers plugin to ensure zero-intervention execution.
• Structured output: Reviewers use strict ✅/❌ verdict formats and severity-categorized issue lists to produce actionable, consistent feedback.

Frequently Asked Questions

How does Superpowers prevent developers from skipping code reviews?

Superpowers prevents review bypass through mandatory enforcement loops defined in skills/subagent-driven-development/SKILL.md. If a reviewer reports issues, the implementer subagent must fix them and trigger a re-review. The task cannot be marked complete until both the spec-compliance and code-quality reviewers return explicit approval verdicts, making it impossible to merge unchecked changes.

What is the difference between the spec-compliance reviewer and the code-quality reviewer?

The spec-compliance reviewer verifies functional correctness by comparing the implementation line-by-line against the original task requirements, ignoring the implementer’s self-assessment to ensure objectivity. The code-quality reviewer evaluates non-functional attributes—such as architecture, test coverage, and production readiness—using a comprehensive checklist from skills/requesting-code-review/code-reviewer.md. These stages run sequentially, with quality review only commencing after spec compliance is confirmed.

Can the review templates be customized for specific project standards?

Yes, the review process is driven by markdown prompt templates that can be modified to enforce project-specific standards. The spec-reviewer-prompt.md and code-quality-reviewer-prompt.md files define the review instructions and output formats, while code-reviewer.md contains the detailed checklist. Teams can edit these files in the skills/ directory to add custom security checks, coding standards, or compliance requirements without altering the core workflow logic.

How does the Superpowers plugin automate reviewer invocation?

The .opencode/plugins/superpowers.js plugin automates reviewer invocation by injecting tool mappings into the system prompt. This injection makes the requesting-code-review skill available as a native tool that the agent can call without explicit user prompting. Consequently, when the subagent-driven-development workflow reaches the review stage, the system automatically dispatches the appropriate reviewer subagent using the pre-configured templates, ensuring zero-intervention execution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}