Pipeline V3 Architecture

Pipeline V3 is Reeve's multi-agent orchestration system for complex software development. It implements a PM (Project Manager) pattern where a coordinator agent orchestrates specialized agents through a structured workflow.

Overview

Pipeline V3 transforms natural language task descriptions into working software through:

1. Automated PRD generation — Task → Product Requirements Document
2. Parallel design review — Architecture, Security, QA review in parallel
3. Contract-driven development — Shared API specs, DB schemas, types
4. Task graph execution — Dependency-aware task scheduling
5. Multi-agent implementation — Specialized agents for each domain
6. Visual validation — Headless browser verification

Agent Roles

Pipeline V3 uses a team of specialized agents, each with a defined role and model tier:

Pipeline Phases

Phase 1: Planning

Task Description → Architect → PRD
                           → Task Graph
                           → Contract Registry

The Architect agent:

1. Analyzes the task description
2. Generates a PRD with features, tech stack, acceptance criteria
3. Creates a dependency graph of tasks
4. Establishes contracts (API specs, DB schemas, shared types)

Phase 2: Design Review

PRD + Contracts → [Architect, Security, QA] → Review Results
                       (parallel)

Three reviewers evaluate the design simultaneously:

• Architect: Validates technical decisions
• Security: Identifies security concerns
• QA: Ensures testability

Review verdicts:

• APPROVE — Proceed
• SUGGEST — Proceed with recommendations
• BLOCKER — Stop and revise

Phase 3: Execution (Parallel)

Task Graph → Ready Tasks → [Backend/Frontend Devs] → Code
                               (truly parallel via asyncio)

The PM orchestrates task execution with full parallelism:

1. Identifies tasks with satisfied dependencies (get_ready())
2. Launches all ready tasks concurrently via asyncio.gather
3. Bounds concurrency with a semaphore (default: 8 simultaneous tasks)
4. Each agent call is an async subprocess (asyncio.create_subprocess_exec)
5. Collects results, updates task graph status
6. Writes progress to .pipeline/progress.json after each completion
7. Retries failed tasks (up to 2 attempts) before marking blocked
8. Detects deadlocks (no ready tasks but graph incomplete) and fails gracefully

Phase 4: Validation

Completed Tasks → QA + UI/UX → Validation Results
                                → Visual Tests (browser)

Validation includes:

• Build verification
• API endpoint testing
• Integration smoke tests
• Visual regression testing

Parallel Execution Model

Pipeline V3 is fully async. Every agent call, every phase, and every task runs as a non-blocking coroutine.

How It Works

Agent calls use asyncio.create_subprocess_exec to spawn Reeve agent sessions. The pipeline never blocks waiting for a single agent — multiple agents run simultaneously.

Design review runs all three reviewers (Architect, Security, QA) in parallel via asyncio.gather. Results are collected when all three finish.

Task execution uses a semaphore-bounded parallel loop:

sem = asyncio.Semaphore(max_concurrency)  # default: 8

async def _run_one(task):
    async with sem:
        success = await self.execute_task(task)
        self._write_progress(task.id, status, completed, total)

# All ready tasks launch in parallel
await asyncio.gather(*[_run_one(t) for t in ready_tasks])

Tasks whose dependencies are satisfied run concurrently. When a task completes, newly unblocked tasks become ready and join the next parallel batch.

Progress Monitoring

The pipeline writes .pipeline/progress.json after each task completion:

{
  "timestamp": "2025-07-13T14:30:00",
  "completed": 5,
  "total": 12,
  "last_task": "backend-auth-api",
  "last_status": "completed",
  "phase": "EXECUTION"
}

External tools (supervisors, heartbeats, dashboards) can poll this file for real-time pipeline status.

Failure Handling

• Retry: Failed tasks retry up to 2 times before being marked BLOCKED
• Deadlock detection: If no tasks are ready but the graph isn't complete, the pipeline detects the deadlock and fails with a clear error
• Graceful degradation: Progress logging never crashes the pipeline — write failures are silently caught

Contract Registry

The Contract Registry is the critical glue between agents. It stores:

API Contracts

registry.add_endpoint(
    method="POST",
    path="/api/users",
    summary="Create a new user",
    request_body={"type": "object", "properties": {...}},
    response={"type": "object", "properties": {...}},
    auth_required=True,
    tags=["users"]
)

Database Contracts

registry.add_table(
    name="users",
    columns={
        "id": "UUID PRIMARY KEY",
        "email": "VARCHAR(255) UNIQUE NOT NULL",
        "created_at": "TIMESTAMP DEFAULT NOW()"
    },
    indexes=["email"]
)

Environment Contracts

registry.set_backend_env("DATABASE_URL", "PostgreSQL connection string")
registry.set_frontend_env("NEXT_PUBLIC_API_URL", "Backend API base URL")

Shared Types

registry.add_type("User", {
    "properties": {
        "id": {"type": "string"},
        "email": {"type": "string"},
        "name": {"type": "string"}
    },
    "required": ["id", "email"]
})

The registry can export to:

• OpenAPI 3.0 spec
• SQL schema
• TypeScript interfaces
• JSON for persistence

Task Graph

Tasks are organized in a dependency graph:

           ┌─────────────────┐
           │ Backend Scaffold │
           └────────┬────────┘
                    │
           ┌────────▼────────┐
           │   DB Schema     │
           └────────┬────────┘
                    │
    ┌───────────────┴───────────────┐
    │                               │
┌───▼───────┐               ┌───────▼───┐
│ Auth API  │               │ User API  │
└───────────┘               └───────────┘

Task states:

• PENDING — Waiting for dependencies
• READY — Dependencies satisfied, can run
• RUNNING — Currently executing
• DONE — Completed successfully
• FAILED — Execution failed
• BLOCKED — Blocked by failed dependency

Usage Example

from src.pipeline.pm import PipelinePM

async def my_llm_caller(agent, prompt):
    """Adapter to your LLM client."""
    return await your_llm.call(
        model=agent.model,
        system=agent.system_prompt,
        prompt=prompt
    )

# Create and run pipeline
pm = PipelinePM(
    task="Build a todo list API with user auth and React frontend",
    repo="/path/to/repo",
    output_dir="./pipeline-output",
    llm_caller=my_llm_caller
)

# Run full pipeline
state = await pm.run()

# Or run phases individually
await pm.create_prd()
await pm.create_task_graph()
reviews = await pm.design_review()

if no_blockers(reviews):
    await pm.execute_all()
    await pm.validate()

Relationship to Coordinator Model

Pipeline V3 is an extension of the Coordinator Model:

The PM never writes code directly—it coordinates the specialized agents who do.

Configuration

Pipeline V3 can be configured via:

{
  "pipeline": {
    "maxRetries": 2,
    "parallelTasks": 3,
    "models": {
      "architect": "anthropic/claude-opus-4-5",
      "developer": "anthropic/claude-sonnet-4",
      "reviewer": "anthropic/claude-sonnet-4",
      "performance": "anthropic/claude-haiku"
    },
    "validation": {
      "runVisualTests": true,
      "screenshotDir": "./pipeline-output/screenshots"
    }
  }
}

Output Artifacts

After pipeline completion:

pipeline-output/
├── prd.json              # Product Requirements Document
├── task-graph.json       # Task dependency graph
├── contracts/
│   ├── api-spec.json     # OpenAPI spec
│   ├── schema.sql        # Database schema
│   ├── env-contract.json # Environment variables
│   └── types.ts          # TypeScript interfaces
├── logs/
│   └── pipeline.jsonl    # Full execution log
└── screenshots/          # Visual test captures

Best Practices

1. Clear task descriptions — The better the input, the better the PRD
2. Review contracts early — Most bugs come from mismatched contracts
3. Check blocker reviews — Don't proceed past design review blockers
4. Monitor the task graph — Watch for deadlocks or stuck tasks
5. Validate visually — Automated visual tests catch UI regressions

CLI Tools

Pipeline V3 includes several command-line tools for different workflows:

See Pipeline V3 Tools Reference for detailed usage.

Quick Start

# Run a pipeline from spec
./bin/run-pipeline-v3.py --spec docs/design.md --repo ./my-app

# Audit codebase for issues
./bin/run-audit-v3.py --repo ./my-app --min-severity high

# Verify features match docs
./bin/run-logic-audit-v3.py --frontend ./frontend --backend ./backend

Pipeline V3.5: Multi-Repo Coordination

Pipeline V3.5 extends V3 with multi-repository awareness. If your project spans multiple repos (e.g. backend + frontend), V3.5 adds:

• Multi-repo support — --repos backend:./api frontend:./web
• Cross-repo contract registry — endpoints and tables track which repo defines them and who consumes them
• Task routing per repo — each task executes in the correct repo's working directory
• Cascading task generation — auto-generates client integration tasks when a backend endpoint has frontend consumers
• Cross-repo dependency tracking — frontend tasks wait for backend tasks they depend on

V3.5 is fully backward compatible — --repo and all single-repo workflows work exactly as before.

See Pipeline V3.5 — Multi-Repo Coordination for full documentation.

See Also

• Pipeline V3.5 — Multi-Repo Coordination — Cross-repo orchestration
• Pipeline V3 Tools Reference — CLI tool documentation
• Coordinator Model — Foundation philosophy
• Spawning Sub-Agents — Manual sub-agent patterns
• Multi-Agent Routing — Agent isolation and routing
• Role Enforcer Plugin — Three-tier enforcement (supersedes coordinator-enforcer)
• Coordinator Enforcer Plugin — Legacy single-tier enforcement