# Superpowers Core Development Workflow: The 7-Stage Mandatory Pipeline for AI Software Engineering > Discover the Superpowers core development workflow a 7-stage pipeline ensuring AI code quality through mandatory design approval, testing, and multi-stage reviews before production. - Repository: [Jesse Vincent/superpowers](https://github.com/obra/superpowers) - Tags: workflow - Published: 2026-02-16 --- **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 `` element in [`skills/brainstorming/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/brainstorming/SKILL.md) forces the agent to stop and wait for human or automated design validation. - **Source**: [`README.md`](https://github.com/obra/superpowers/blob/main/README.md) § Basic Workflow (lines 69-76) and [`skills/brainstorming/SKILL.md`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/README.md) § Basic Workflow (lines 73-74) and [`skills/using-git-worktrees/SKILL.md`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/README.md) § Basic Workflow (lines 75-77) and [`skills/writing-plans/SKILL.md`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/skills/executing-plans/SKILL.md) provides a batch mode that still respects the same review gates. - **Source**: [`README.md`](https://github.com/obra/superpowers/blob/main/README.md) § Basic Workflow (lines 77-78), [`skills/subagent-driven-development/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/SKILL.md), and [`skills/executing-plans/SKILL.md`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/README.md) § Basic Workflow (lines 79-80) and [`skills/test-driven-development/SKILL.md`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/README.md) § Basic Workflow (lines 81-82) and [`skills/requesting-code-review/SKILL.md`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/README.md) § Basic Workflow (lines 83-84) and [`skills/finishing-a-development-branch/SKILL.md`](https://github.com/obra/superpowers/blob/main/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 `` elements (visible in [`skills/brainstorming/SKILL.md`](https://github.com/obra/superpowers/blob/main/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 ```text 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`](https://github.com/obra/superpowers/blob/main/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 ```text 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 ```text User: "Create the plan." ``` The `writing-plans` skill produces [`docs/plans/2026-02-16-dark-mode-plan.md`](https://github.com/obra/superpowers/blob/main/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 ```text 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 ```text 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 ```text 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 ```text 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`](https://github.com/obra/superpowers/blob/main/README.md)** — High-level overview of the entire seven-stage pipeline (§ Basic Workflow, lines 69-84). - **[`skills/brainstorming/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/brainstorming/SKILL.md)** — Defines the mandatory design-first stage and its `` mechanism. - **[`skills/using-git-worktrees/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/using-git-worktrees/SKILL.md)** — Configures isolated branch creation and baseline testing. - **[`skills/writing-plans/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/writing-plans/SKILL.md)** — Specifies task granularity (2-5 minute chunks) with file paths and verification steps. - **[`skills/subagent-driven-development/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/SKILL.md)** — Orchestrates per-task sub-agents with two-stage reviews. - **[`skills/executing-plans/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/executing-plans/SKILL.md)** — Alternative batch execution mode respecting the same review gates. - **[`skills/test-driven-development/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/test-driven-development/SKILL.md)** — Enforces RED-GREEN-REFACTOR loops. - **[`skills/requesting-code-review/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/requesting-code-review/SKILL.md)** — Performs automatic spec-compliance and quality reviews with severity grading. - **[`skills/finishing-a-development-branch/SKILL.md`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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 `` 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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/SKILL.md) orchestrates individual sub-agents for each task, [`skills/executing-plans/SKILL.md`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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.