What Is a Subagent-Driven Development Workflow with Superpowers?

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 or 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, 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 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 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.

# 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 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.

# 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. The orchestrator parses these blocks, merges them into a run.json record, and inlines necessary slices—such as seeded.stores—into downstream prompts.

{
  "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.

5. Error Handling and Rate-Limit Recovery

If a sub-agent hits a rate limit, the orchestrator follows the guidelines in 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, per 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, 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.

# 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 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, BUILD.md, and 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. The orchestrator parses these blocks, merges them into a central 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.

How does the workflow handle rate limits and partial failures?

Per 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 without crashing the entire pipeline.

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