Superpowers Core Development Workflow: The 7-Stage Mandatory Pipeline for AI Software Engineering

The Superpowers core development workflow enforces a strict, ordered pipeline of seven mandatory stages—from initial brainstorming to branch finalization—that prevents AI agents from writing production code until design approval, test planning, and multi-stage review gates are satisfied.

The obra/superpowers repository defines a rigid, skill-based architecture that transforms how AI agents approach software development. Unlike conventional coding assistants that jump directly to implementation, Superpowers imposes a core development workflow that mandates design documentation, isolated environments, and continuous verification before any code reaches the main branch.

The Seven Stages of the Superpowers Core Development Workflow

The workflow is hard-wired in the repository’s documentation and individual skill definitions. Each phase declares a hard-gate that blocks progression until specific criteria are met.

1. Brainstorming

Before any code is written, the agent must explore context, ask clarifying questions, propose alternatives, and produce a vetted design document. The brainstorming skill explicitly forbids invoking any implementation skill until the design receives explicit approval.

• Key constraint: The <HARD-GATE> element in skills/brainstorming/SKILL.md forces the agent to stop and wait for human or automated design validation.
• Source: README.md § Basic Workflow (lines 69-76) and skills/brainstorming/SKILL.md.

2. Using Git Worktrees

After design approval, the agent creates an isolated Git worktree on a new branch, runs the project’s setup commands, and records a clean test baseline. This guarantees that implementation work never happens on main and that the environment is reproducible.

• Source: README.md § Basic Workflow (lines 73-74) and skills/using-git-worktrees/SKILL.md.

3. Writing Plans

The agent breaks the approved design into bite-size tasks (2-5 minutes each), with each task specifying exact file paths, complete code snippets, and verification steps. This transforms high-level design into executable, measurable units of work.

• Source: README.md § Basic Workflow (lines 75-77) and skills/writing-plans/SKILL.md.

4. Sub-Agent-Driven Development (or Executing Plans)

The workflow dispatches a fresh sub-agent for each task (or runs the plan in batch mode). Every task undergoes a two-stage review: first for specification compliance, then for code quality. The pipeline halts if either review fails.

• Alternative execution: skills/executing-plans/SKILL.md provides a batch mode that still respects the same review gates.
• Source: README.md § Basic Workflow (lines 77-78), skills/subagent-driven-development/SKILL.md, and skills/executing-plans/SKILL.md.

5. Test-Driven Development

Every code change must follow the classic RED-GREEN-REFACTOR loop: write a failing test, watch it fail, write minimal production code to make it pass, then refactor. The test must exist before any production code is written.

• Source: README.md § Basic Workflow (lines 79-80) and skills/test-driven-development/SKILL.md.

6. Requesting Code Review

After each task (or logical group of tasks), the agent automatically triggers a code-review skill that checks the implementation against the plan and reports severity-graded issues. Critical issues block progress until resolved.

• Source: README.md § Basic Workflow (lines 81-82) and skills/requesting-code-review/SKILL.md.

7. Finishing a Development Branch

When all tasks are complete, the agent verifies the full test suite, presents merge or pull-request options, and cleans up the temporary worktree. This ensures the branch is in a production-ready state before integration.

• Source: README.md § Basic Workflow (lines 83-84) and skills/finishing-a-development-branch/SKILL.md.

Mandatory Enforcement Through Hard-Gates and Meta-Skills

The core development workflow is not optional. Two mechanisms enforce strict compliance:

1. Hard-Gates: Individual skills declare <HARD-GATE> elements (visible in skills/brainstorming/SKILL.md) that force the agent to pause and await explicit approval before proceeding to the next stage.

2. Meta-Skill Validation: The using-superpowers meta-skill forces the agent to check for required skills before any action. If a required skill is missing, the session aborts immediately with a clear error message.

This architecture ensures that an agent cannot bypass brainstorming to start coding, cannot commit without review, and cannot merge without final verification.

Real-World Workflow Example

The following interaction demonstrates how the core development workflow progresses through all seven stages when adding a feature:

Stage 1: Brainstorming

User: "I want to add a dark-mode toggle to the dashboard."

The agent detects the need for brainstorming and launches the brainstorming skill. It asks contextual questions, proposes UI approaches, and creates docs/plans/2026-02-16-dark-mode-design.md. The agent cannot proceed to implementation until the user approves this document.

Stage 2: Using Git Worktrees

User: "The design looks good, go ahead."

The agent invokes using-git-worktrees. It creates a fresh worktree on branch feature/dark-mode, runs setup commands, and establishes a clean test baseline. Work is now isolated from main.

Stage 3: Writing Plans

User: "Create the plan."

The writing-plans skill produces docs/plans/2026-02-16-dark-mode-plan.md with granular tasks such as "Add CSS variable for background" and "Update ThemeContext", each specifying exact file paths and verification steps.

Stage 4: Sub-Agent-Driven Development

User: "Execute the first task."

The subagent-driven-development skill dispatches a sub-agent that:

1. Writes the code for the task.
2. Runs the spec-compliance review.
3. Runs the code-quality review.
4. Commits the change only if both reviews pass.

Stage 5: Test-Driven Development

User: "Add a unit test for the new toggle."

The agent creates a failing test, watches it fail, writes minimal production code to make it pass, then refactors—enforcing the RED-GREEN-REFACTOR loop.

Stage 6: Requesting Code Review

User: "Run a code review now."

The requesting-code-review skill checks the current diff against the plan, flags deviations, and blocks progress if a critical issue is found.

Stage 7: Finishing a Development Branch

User: "All done – finish the branch."

The finishing-a-development-branch skill runs the full test suite, offers to open a PR, and cleans up the temporary worktree.

Key Files Defining the Core Development Workflow

The core development workflow is codified in the following files:

• README.md — High-level overview of the entire seven-stage pipeline (§ Basic Workflow, lines 69-84).
• skills/brainstorming/SKILL.md — Defines the mandatory design-first stage and its <HARD-GATE> mechanism.
• skills/using-git-worktrees/SKILL.md — Configures isolated branch creation and baseline testing.
• skills/writing-plans/SKILL.md — Specifies task granularity (2-5 minute chunks) with file paths and verification steps.
• skills/subagent-driven-development/SKILL.md — Orchestrates per-task sub-agents with two-stage reviews.
• skills/executing-plans/SKILL.md — Alternative batch execution mode respecting the same review gates.
• skills/test-driven-development/SKILL.md — Enforces RED-GREEN-REFACTOR loops.
• skills/requesting-code-review/SKILL.md — Performs automatic spec-compliance and quality reviews with severity grading.
• skills/finishing-a-development-branch/SKILL.md — Handles final verification, PR creation, and worktree cleanup.

Summary

The core development workflow in Superpowers transforms AI-assisted coding from ad-hoc generation into a disciplined, review-heavy engineering process:

• Seven mandatory stages enforce design-before-code, isolation, planning, and verification.
• Hard-gates in skills/brainstorming/SKILL.md and the using-superpowers meta-skill prevent stage skipping.
• Two-stage reviews (spec-compliance and code-quality) run automatically during sub-agent execution.
• Test-driven development mandates RED-GREEN-REFACTOR cycles for every production change.
• Severity-graded code reviews block progress on critical issues while allowing minor issues to proceed.

Frequently Asked Questions

What happens if an agent tries to skip the brainstorming stage?

The session aborts immediately. The brainstorming skill declares a <HARD-GATE> that forces the agent to pause and await explicit design approval. Additionally, the using-superpowers meta-skill validates that required skills are present before any action; if the agent attempts to invoke an implementation skill without completing brainstorming, the workflow halts with a clear error message.

How does Superpowers ensure code quality during the execution phase?

Quality is enforced through a two-stage review process defined in skills/subagent-driven-development/SKILL.md. First, a spec-compliance review verifies that the implementation matches the task definition from the planning stage. Second, a code-quality review checks for bugs, style violations, and architectural consistency. Both reviews must pass before the sub-agent commits the change; critical issues block the pipeline entirely.

Can the workflow accommodate batch execution instead of per-task sub-agents?

Yes. While skills/subagent-driven-development/SKILL.md orchestrates individual sub-agents for each task, skills/executing-plans/SKILL.md provides an alternative batch-execution mode. This mode still respects the same mandatory reviews and test-driven development requirements but processes multiple tasks in a single session. Both execution paths enforce the same hard-gates and quality checks.

What is the role of Git worktrees in the Superpowers workflow?

Git worktrees provide environmental isolation during the development process. The skills/using-git-worktrees/SKILL.md stage creates a fresh worktree on a new feature branch immediately after design approval. This ensures that implementation work never occurs on main, establishes a clean test baseline before changes begin, and allows the agent to maintain multiple isolated development contexts. The worktree is automatically cleaned up during the final "finishing a development branch" stage.

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