Subagent-Driven Development Workflow: Multi-Agent Architecture for Complex Implementations

Subagent-driven development orchestrates a pipeline of isolated AI subagents—implementers, reviewers, and fixers—to execute implementation plans with strict spec compliance, bounded iteration loops, and durable ledger bookkeeping.

This workflow is codified in the openai/plugins repository as a core "Superpowers" skill. Unlike monolithic code generation, it dispatches fresh subagents for each task, ensuring minimal context bleed while maintaining rigorous quality gates through automated review cycles.

Core Principles of Subagent-Driven Development

The methodology rests on five architectural pillars defined in SKILL.md:

• Fresh subagent per task: Each implementation task receives a dedicated subagent with a clean context window, preventing pollution from previous task attempts.
• Two-stage review pipeline: First, a task reviewer validates spec compliance; later, a final reviewer evaluates the entire branch for holistic quality.
• Ledger-driven bookkeeping: All decisions, rulings, and progress persist in <workspace>/progress.md, creating a durable audit trail independent of session state.
• Model selection hierarchy: Mechanical tasks use cheaper, faster models; integration and judgment tasks escalate to more capable models only when necessary.
• Bounded fix loops: A maximum of five fix rounds per task prevents infinite iteration, with automatic model escalation in rounds four and five.

When to Apply This Workflow

According to the source documentation, subagent-driven development is appropriate when three conditions align:

1. A formal implementation plan exists with discrete, largely independent tasks.
2. Work remains within the current session boundary (for cross-session plans, the parallel-session "executing-plans" skill is recommended instead).
3. Tasks exhibit minimal cross-coupling, allowing isolated implementation without heavy coordination overhead.

The SKILL.md file contains a decision graph visualizing these constraints.

The Step-by-Step Subagent-Driven Development Process

Setup and Initialization

The workflow begins by creating an isolated workspace via superpowers:using-git-worktrees. The controller reads the implementation plan once, extracts global constraints, and generates a todo entry for every task. This initialization ensures that subagents operate in clean git worktrees with no residual state from previous operations.

Task Implementation Loop

For each discrete task, the controller executes a four-phase loop:

1. Dispatch implementer: The scripts/task-brief utility generates a task-specific brief file. The controller then launches a subagent using the implementer-prompt.md template, injecting only the relevant context.

2. Interactive implementation: The implementer subagent writes code, runs tests, and produces a report at <workspace>/task-{n}-report.md. The controller answers clarifying questions but does not alter the subagent's isolation boundary.

3. Generate review package: The scripts/review-package script creates a diff package capturing all changes introduced by the implementer.

4. Task review: A dedicated reviewer subagent—prompted via task-reviewer-prompt.md—validates spec compliance and code quality against the original brief.

Review and Fix Cycles

When the task reviewer identifies issues, the workflow enters a bounded fix loop:

• Rounds 1-3: The original implementer subagent receives the findings and produces a revised implementation.
• Round 4-5: The controller automatically escalates to a more capable model tier for the implementer, acknowledging increasing complexity.
• Re-review: Each fix round triggers a scoped re-review using re-review-prompt.md, focusing only on changed files.

After five rounds, the controller adjudicates any remaining findings rather than continuing iteration.

Final Whole-Branch Review

Once all tasks reach "complete" status in the ledger, a final reviewer subagent evaluates the entire branch diff. This holistic review catches integration issues missed by per-task checks. Critical findings trigger a single additional fix wave followed by a final re-review before the workspace is destroyed.

Model Selection and Escalation

The workflow implements a cost-optimization strategy:

• Mechanical tasks (single-file edits, clear specs): Use the cheapest capable model (e.g., GPT-4o-mini).
• Integration tasks (multi-file coordination, pattern matching): Use standard-tier models.
• Architecture tasks (system design, complex refactoring): Reserve the most capable models.

During fix loops, rounds four and five automatically escalate to higher-tier models, as unresolved issues likely indicate subtle complexity requiring stronger reasoning capabilities.

The Ledger and Workspace Architecture

The <workspace>/progress.md ledger serves as the single source of truth. It records:

• Task completion status with specific commit ranges (e.g., commits a1b2c3d..d4e5f6a)
• Review rulings and fix round counts
• Model selections and escalation events

Because the ledger persists on disk while session context may compact, it enables full state reconstruction even after interruptions. The git history and ledger together provide an authoritative, auditable record of all implementation decisions.

Code Examples

Dispatching an Implementer Subagent

The controller dispatches work using structured directives that reference task-specific briefs:

# Example dispatch configuration

short_description: "Implement task 3 – add API endpoint"
agent: generalist
prompt: |
  Read this file first — it is your requirements:
  {{ read("{{workspace}}/task-3-brief.md") }}
  Write your implementation to the repository, run tests, and produce a
  report at {{workspace}}/task-3-report.md.
model: gpt-4o-mini

The scripts/task-brief utility generates the brief file from the master plan, while the report path is consumed by subsequent review stages.

Ledger Entry Format

Typical ledger entries follow a structured format tracking task state:

# SDD ledger — plan: docs/superpowers/plans/feature-plan.md

Task 3: complete (commits a1b2c3d..d4e5f6a, review clean)
Task 4: in-progress (round 2/5, awaiting re-review)

Key Files and Implementation

The subagent-driven development workflow relies on the following components in the openai/plugins repository:

File	Purpose
SKILL.md	Complete workflow specification and decision graphs
implementer-prompt.md	Template for launching implementation subagents
task-reviewer-prompt.md	Template for per-task compliance and quality review
re-review-prompt.md	Template for scoped reviews after fix iterations
scripts/task-brief	CLI utility extracting task descriptions into brief files
scripts/review-package	Diff generator producing review artifacts
superpowers/README.md	Overview of the Superpowers skill ecosystem

Summary

• Subagent-driven development isolates each implementation task in a fresh subagent context to prevent pollution and maintain focus.
• The workflow enforces two-stage quality gates: task-level reviews for spec compliance and final branch reviews for integration integrity.
• Bounded fix loops (maximum five rounds) with automatic model escalation prevent infinite iteration while preserving quality.
• A durable ledger (progress.md) and git history provide complete auditability independent of session state.
• The system optimizes compute costs through hierarchical model selection, using cheaper models for mechanical tasks and reserving powerful models for complex judgment calls.

Frequently Asked Questions

How does subagent-driven development prevent context window limitations?

By dispatching a fresh subagent for each task via the implementer-prompt.md template, the workflow ensures that no single context window accumulates cruft from previous implementation attempts. Each subagent receives only the task brief and necessary files, keeping the working set minimal and focused.

What happens when a task fails review after five fix rounds?

After the fifth fix round, the controller intervenes directly to adjudicate remaining findings rather than spawning additional implementer subagents. This hard boundary prevents infinite loops on intractable tasks while ensuring human-readable documentation of the unresolved issues persists in the ledger.

How does the ledger maintain state across session interruptions?

The <workspace>/progress.md file is written to disk immediately after every state transition, recording task statuses, commit hashes, and review rulings. Unlike transient session context that may be compacted or lost, the ledger persists in the git worktree, allowing complete workflow reconstruction by reading the file and examining the git history.

Can I use subagent-driven development for plans spanning multiple sessions?

No. According to the SKILL.md specification, this workflow is designed for single-session execution. For multi-session plans, the repository provides a separate "executing-plans" skill that supports parallel session coordination and checkpointing across longer time horizons.

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