How Subagents Power the Superpowers Development Workflow: A Complete Guide

Subagents in the Superpowers development workflow act as specialized, autonomous workers—Implementer, Spec-Compliance Reviewer, and Code-Quality Reviewer—that execute tasks in isolated contexts to enforce test-driven development and rigorous code review without bloating the main session context.

The obra/superpowers repository treats every implementation plan as a pipeline of autonomous subagents rather than a monolithic script. According to the source code in skills/subagent-driven-development/SKILL.md, this architecture ensures that each task receives a fresh, isolated context and undergoes mandatory two-stage review before completion.

The Three Core Subagent Roles in Superpowers

The subagent-driven development skill defines three distinct roles that collaborate sequentially on every task. Each role is instantiated via a dedicated prompt template to ensure consistent behavior.

Implementer

The Implementer subagent owns the full development lifecycle for a single task. As defined in skills/subagent-driven-development/implementer-prompt.md, this agent writes the code, adds tests, performs a self-review, and commits the change. The Implementer operates in complete isolation from the main controller session—receiving only the curated task description and context—preventing the main session from accumulating implementation details that could pollute subsequent tasks (see SKILL.md lines 45–50).

Spec-Compliance Reviewer

The Spec-Compliance Reviewer acts as an independent auditor that verifies the implementation matches the exact specification without trusting the Implementer’s report. According to skills/subagent-driven-development/spec-reviewer-prompt.md (lines 21–31), this subagent inspects the code against the full task requirements and returns a binary verdict: ✅ for compliant or ❌ with a concrete issue list. This ensures nothing more, nothing less is built, preventing scope creep and gold-plating.

Code-Quality Reviewer

The Code-Quality Reviewer provides a second quality gate focused on architectural health. After spec compliance is confirmed, this subagent—defined in skills/subagent-driven-development/code-quality-reviewer-prompt.md—evaluates naming conventions, code structure, maintainability, and test coverage. This separation of concerns allows the Spec-Compliance Reviewer to focus strictly on functional correctness while the Code-Quality Reviewer catches structural problems that might otherwise pass to production.

The Subagent-Driven Development Workflow Architecture

The orchestration of these roles follows a strict state machine defined in SKILL.md (lines 40–83). The workflow ensures that no task proceeds to the next stage without explicit approval from the appropriate reviewer.

Architectural Flow

1. Plan Parsing: The controller reads the implementation plan, extracts independent tasks, and creates TodoWrite entries for each.
2. Implementer Dispatch: The controller spawns an Implementer subagent using ./implementer-prompt.md (diagram line 46). The Implementer may ask clarifying questions (line 47) before writing code, tests, and committing.
3. Spec Review Dispatch: Upon completion, the controller dispatches a Spec-Compliance Reviewer (line 50). This subagent independently inspects the code against the full specification (prompt lines 13–34) and returns a verdict.
4. Fix Loop: If the reviewer finds issues, the Implementer fixes the gaps and the spec reviewer re-reviews (line 71) until compliance is achieved.
5. Quality Review Dispatch: Once spec-compliant, the Code-Quality Reviewer checks style and architecture (line 53).
6. Resolution Loop: The Implementer resolves quality issues, looping back until approval (line 76).
7. Task Completion: The controller marks the task complete in TodoWrite (line 56) and repeats for the next task.
8. Final Validation: After all tasks, a final code-reviewer subagent validates the entire branch before handing off to finishing-a-development-branch (lines 81–82).

Implementation Example

The following excerpt from SKILL.md illustrates how the controller dispatches the Implementer subagent:

# Example of dispatching an implementer subagent (excerpt from SKILL.md)

- Read plan, extract all tasks with full text, note context, create TodoWrite
- Dispatch implementer subagent (./implementer-prompt.md)

The Implementer receives a curated prompt that isolates it from the main session context:

# Implementer Subagent Prompt (./implementer-prompt.md)

Task tool (general‑purpose):
  description: "Implement Task N: Hook installation script"
  prompt: |
    You are implementing Task N: Hook installation script

    ## Task Description

    [FULL TEXT of task from plan - paste it here, don't make subagent read file]

    ## Context

    [Scene‑setting: where this fits, dependencies, architectural context]

    ## Before You Begin

    **Ask them now.** Raise any concerns before starting work.
    ...

Similarly, the Spec-Compliance Reviewer operates under strict instructions not to trust the Implementer’s self-report:

# Spec‑Compliance Reviewer Prompt (./spec-reviewer-prompt.md)

Task tool (general‑purpose):
  description: "Review spec compliance for Task N"
  prompt: |
    You are reviewing whether an implementation matches its specification.

    ## What Was Requested

    [FULL TEXT of task requirements]

    ## What Implementer Claims They Built

    [From implementer's report]

    ## CRITICAL: Do Not Trust the Report

    ...
    Report:
    - ✅ Spec compliant (if everything matches after code inspection)
    - ❌ Issues found: [...]

Key Benefits of the Subagent Pattern

The obra/superpowers codebase emphasizes three architectural advantages that emerge from the fresh-subagent-per-task design.

Context Isolation

Each subagent receives a curated, full-text task description (see implementer prompt line 13) and never reads the plan file directly. This prevents accidental context leakage between tasks and ensures the main controller session remains lean. As noted in SKILL.md, the main session "never pollutes its context" by offloading implementation work to isolated workers (lines 45–50).

Iterative Quality Enforcement

The two-stage review process (spec first, quality second) ensures functional correctness before architectural polish. The Spec-Compliance Reviewer guarantees that nothing more, nothing less is built, while the Code-Quality Reviewer catches structural problems that might pass functional tests. This sequential gating prevents premature optimization of incorrect code.

Fast, Parallel-Safe Iteration

Because subagents are stateless and ephemeral, they can run concurrently without stepping on each other’s toes (see SKILL.md line 172). The controller can dispatch multiple Implementers for independent tasks simultaneously, or run spec reviews in parallel, accelerating the development pipeline while maintaining strict quality controls.

Summary

• Subagents in the Superpowers development workflow function as specialized autonomous workers—Implementer, Spec-Compliance Reviewer, and Code-Quality Reviewer—that collaborate to deliver production-ready code.
• The architecture enforces context isolation by giving each subagent a curated task description rather than direct plan file access, preventing pollution of the main session.
• A two-stage review process (spec compliance followed by code quality) ensures functional correctness before architectural refinement, with explicit instructions to reviewers not to trust implementer self-reports.
• The stateless nature of subagents enables parallel execution of independent tasks, accelerating development while maintaining rigorous quality gates as defined in skills/subagent-driven-development/SKILL.md.

Frequently Asked Questions

What are the three main subagent roles in Superpowers?

The three main subagent roles are the Implementer, who writes code and tests; the Spec-Compliance Reviewer, who independently verifies the implementation matches the exact specification; and the Code-Quality Reviewer, who evaluates style, architecture, and maintainability after spec compliance is confirmed.

How does Superpowers prevent context pollution between tasks?

Superpowers prevents context pollution by dispatching a fresh subagent for every task and providing each with a curated, full-text task description rather than allowing direct access to the plan file. This ensures the main controller session never accumulates implementation details from previous tasks, as documented in skills/subagent-driven-development/SKILL.md lines 45–50.

Why does the Spec-Compliance Reviewer not trust the Implementer's report?

The Spec-Compliance Reviewer is explicitly instructed not to trust the Implementer's self-report to prevent "trust-the-report" shortcuts that could allow deviations from the specification to go unnoticed. This independent verification ensures that nothing more, nothing less is built, catching scope creep or incomplete implementations that might otherwise pass to production.

Can subagents run in parallel, and if so, how is quality maintained?

Yes, subagents can run concurrently because they are stateless and ephemeral, allowing the controller to dispatch multiple Implementers for independent tasks simultaneously or run reviews in parallel. Quality is maintained through the two-stage review pipeline (spec compliance followed by code quality) and the requirement that each subagent receives a complete, isolated task context, ensuring parallel execution does not introduce race conditions or context leakage.

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