# What Is a Subagent-Driven Development Workflow with Superpowers?

> Discover the subagent-driven development workflow with superpowers. Learn how orchestrator agents delegate tasks to parallel sub-agents with automatic retries and structured results.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: deep-dive
- Published: 2026-06-09

---

**A subagent-driven development workflow with superpowers is an orchestrated pattern where a parent orchestrator agent delegates isolated tasks to lightweight sub-agents—running in parallel or the background—while the Superpowers skillset provides scaffolding for dispatch loops, automatic retries, and structured result aggregation.**

In the `openai/plugins` repository, this pattern is codified through skill definitions, build specs, and return contracts that define how an orchestrator reads high-level plans and dispatches work to specialized sub-agents. The Superpowers layer adds reusable building blocks that enforce a "dispatch-review-dispatch" cycle, making the workflow reliable and scalable for complex, multi-phase tasks.

## Core Components of a Subagent-Driven Workflow

Every subagent-driven development workflow revolves around three primary entities defined in the source documentation.

### The Orchestrator

The orchestrator is the parent agent that reads the high-level plan—typically [`PLAN.md`](https://github.com/openai/plugins/blob/main/PLAN.md) or [`BUILD.md`](https://github.com/openai/plugins/blob/main/BUILD.md)—and decides which sub-agents to launch, when to wait, and how to merge their outputs. According to [`plugins/wix/skills/wix-headless/PLAN.md`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-headless/PLAN.md), the orchestrator owns the execution graph and maintains strict ordering between dependent phases.

### The Sub-Agent

A sub-agent is a lightweight, isolated model call that executes a self-contained task such as design system generation, data seeding, image generation, or page composition. Each sub-agent emits a structured JSON block upon completion, enabling the orchestrator to aggregate results without parsing raw prose.

### Foreground vs. Background Execution

The [`plugins/wix/skills/wix-headless/BUILD.md`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-headless/BUILD.md) spec distinguishes between two execution modes:

- **Foreground sub-agent**: The orchestrator pauses until the sub-agent finishes. Use this when downstream steps depend on the output.
- **Background sub-agent**: Launched with `run_in_background: true`; the orchestrator continues immediately and consumes the asynchronous result later via a handle.

## Six Phases of the Superpowers Workflow

The build spec in [`plugins/wix/skills/wix-headless/BUILD.md`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-headless/BUILD.md) outlines a strict six-phase pipeline.

### 1. Plan and Discovery

The orchestrator reads the user's intent and the high-level plan. It identifies independent workstreams—such as Designer, Composer, and Seeder—that can be parallelized safely.

### 2. Dispatch

For each independent piece, the orchestrator creates a sub-agent call. Background agents are preferred for work that is not immediately needed.

```yaml

# plugins/wix/skills/wix-headless/BUILD.md – excerpt

- type: Agent
  subagent_type: "general-purpose"
  instruction_file: "<SKILL_ROOT>/references/DESIGN_SYSTEM.md"
  run_in_background: true   # background designer sub-agent

  handle: designer_handle

```

This excerpt from [`BUILD.md`](https://github.com/openai/plugins/blob/main/BUILD.md) shows the Designer sub-agent running in the background so the orchestrator can launch other tasks concurrently.

### 3. Gate and Wait

When a later phase requires output from a background sub-agent—such as page generation needing seeded IDs—the orchestrator waits on the background handle rather than polling files. This eliminates busy-wait loops and reduces latency.

```python

# Pseudocode from BUILD.md – "Wait (gate)"

if not orchestrator.wait_for_handle(designer_handle):
    raise OrchestrationError("Designer sub-agent failed")

# Continue with Composer after designer data is ready

```

### 4. Result Aggregation

Each sub-agent finishes by emitting a fenced JSON block as defined in [`references/shared/RETURN_CONTRACT.md`](https://github.com/openai/plugins/blob/main/references/shared/RETURN_CONTRACT.md). The orchestrator parses these blocks, merges them into a [`run.json`](https://github.com/openai/plugins/blob/main/run.json) record, and inlines necessary slices—such as `seeded.stores`—into downstream prompts.

```json
{
  "status": "success",
  "data": {
    "designTokens": {"primary": "#0A84FF", "font": "Inter"},
    "shell": {"layout": "single-column"}
  }
}

```

Every sub-agent must end with a fenced JSON block as specified in [`plugins/wix/skills/wix-headless/references/shared/RETURN_CONTRACT.md`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-headless/references/shared/RETURN_CONTRACT.md).

### 5. Error Handling and Rate-Limit Recovery

If a sub-agent hits a rate limit, the orchestrator follows the guidelines in [`BUILD.md`](https://github.com/openai/plugins/blob/main/BUILD.md): perform a single retry, then mark the phase as `"partial"` with a structured error code. This prevents cascading failures and preserves partial state for debugging.

### 6. Finalization

After all phases complete, the orchestrator writes the silent observability file [`.wix/run.json`](https://github.com/openai/plugins/blob/main/.wix/run.json), per [`BUILD.md`](https://github.com/openai/plugins/blob/main/BUILD.md) § "Ordering is strict". This file serves as the canonical record of the run.

## The Superpowers Skill Layer

The Superpowers skillset transforms basic orchestration into a production-grade workflow.

### Sub-Agent-Driven-Development Skill

Defined in [`plugins/superpowers/skills/subagent-driven-development/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/subagent-driven-development/SKILL.md), this skill enforces a **dispatch → review → dispatch** loop. It automatically inserts a code-quality reviewer sub-agent between tasks, handling retries, rate-limit detection, and error aggregation.

```yaml

# plugins/superpowers/skills/subagent-driven-development/implementer-prompt.md

- dispatch:
    agent: subagent-driven-development
    task: "Generate component skeleton"
- review:
    agent: code-quality-reviewer
    input: previous_output
- dispatch:
    agent: subagent-driven-development
    task: "Write tests for component"

```

The above pattern is the canonical dispatch-review-dispatch loop promoted by the Superpowers skill.

### Supporting Skills

Reusable skills such as `writing-plans` and `testing-skills` embed the sub-agent pattern into higher-level planning and quality assurance. [`plugins/superpowers/skills/testing-skills/testing-anti-patterns.md`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/testing-skills/testing-anti-patterns.md) documents common pitfalls to avoid when pressure-testing pipelines.

## Summary

- A **subagent-driven development workflow with superpowers** pairs a parent orchestrator with lightweight, parallel sub-agents to execute complex, multi-phase projects.
- The `openai/plugins` repository defines this architecture in [`PLAN.md`](https://github.com/openai/plugins/blob/main/PLAN.md), [`BUILD.md`](https://github.com/openai/plugins/blob/main/BUILD.md), and [`RETURN_CONTRACT.md`](https://github.com/openai/plugins/blob/main/RETURN_CONTRACT.md), specifying strict ordering, background handles, and JSON return contracts.
- **Foreground sub-agents** block the orchestrator until completion; **background sub-agents** run asynchronously and are gated via handles.
- The **Superpowers** skill layer adds the **dispatch-review-dispatch** loop, automatic retries, and rate-limit recovery, making the pattern reliable at scale.

## Frequently Asked Questions

### What is the difference between a foreground and background sub-agent?

A foreground sub-agent forces the orchestrator to pause until it finishes, which is required when subsequent tasks depend on its output. A background sub-agent is launched with `run_in_background: true`, allowing the orchestrator to continue immediately and wait on its handle later when the result is actually needed.

### How does the orchestrator aggregate results from multiple sub-agents?

Each sub-agent terminates with a fenced JSON block defined by [`references/shared/RETURN_CONTRACT.md`](https://github.com/openai/plugins/blob/main/references/shared/RETURN_CONTRACT.md). The orchestrator parses these blocks, merges them into a central [`run.json`](https://github.com/openai/plugins/blob/main/run.json) record, and inlines specific slices—such as `data.designTokens` or `seeded.stores`—into downstream agent prompts.

### What is the dispatch-review-dispatch loop?

The dispatch-review-dispatch loop is a quality gate promoted by the `subagent-driven-development` Superpowers skill. After an initial task dispatch, a reviewer sub-agent inspects the output, and only then does the orchestrator dispatch the next dependent task. This pattern is codified in [`plugins/superpowers/skills/subagent-driven-development/implementer-prompt.md`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/subagent-driven-development/implementer-prompt.md).

### How does the workflow handle rate limits and partial failures?

Per [`plugins/wix/skills/wix-headless/BUILD.md`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-headless/BUILD.md), the orchestrator attempts a single retry on rate-limited sub-agents. If the retry fails, the phase is marked `"partial"` with a structured error code, preserving observability in [`.wix/run.json`](https://github.com/openai/plugins/blob/main/.wix/run.json) without crashing the entire pipeline.