PRD Decomposition Workflow

Decompose a PRD and Tech Spec into parallel-executable tasks with contracts, dependency graphs, and agent prompts.

Workflow Overview

flowchart TB
    Start[("PRD + Tech Spec")]
    Dir["1. Determine Output Dir"]
    Analyze["2. Analyze Tech Spec"]
    Manifest["3. Create manifest.json"]
    Context["4. Create context.md"]
    Arch["5. Create architecture.md"]
    Contracts["6. Create contracts/"]
    Tasks["7. Generate task files"]
    Graph["8. Create task-graph.md"]
    Prompts["9. Generate prompts/"]
    Update["10. Update manifest"]
    Report["11. Report Results"]

    Start --> Dir
    Dir --> Analyze
    Analyze --> Manifest
    Manifest --> Context
    Context --> Arch
    Arch --> Contracts
    Contracts --> Tasks
    Tasks --> Graph
    Graph --> Prompts
    Prompts --> Update
    Update --> Report
    Report --> Done(["Ready for cpo run"])

Step 1: Determine Output Directory

PARALLEL_DIR="parallel/TS-0042-inventory-system"

• If Tech Spec provided: Extract ID and slug from Tech Spec file
• If --name provided: Use parallel/{slug}/

Step 2: Tech Spec Analysis

If a Tech Spec (TS-XXXX) is provided:

1. Read and validate Tech Spec:

   • Verify status is APPROVED or REFERENCE
   • Warn if DRAFT (not ready for decomposition)

2. Extract from Tech Spec:

   • Design Overview -> Use for architecture.md
   • Data Model -> Use for contracts/types.py
   • API Specification -> Use for contracts/api-schema.yaml
   • Component boundaries -> Use for task ownership

3. Skip redundant steps:

   • If Tech Spec has complete Data Model, skip generating types
   • If Tech Spec has complete API Spec, skip generating api-schema.yaml

If no Tech Spec provided: Generate contracts from PRD and display warning:

"Consider creating a Tech Spec first for better contract definitions"

Step 3: Create manifest.json

Use the cpo format:

{
  "tech_spec_id": "TS-0042",
  "name": "inventory-system",
  "technology": "python",
  "python_version": "3.11",
  "waves": [
    {
      "number": 1,
      "tasks": [
        { "id": "task-001", "agent": "python-experts:django-expert" },
        { "id": "task-002", "agent": "python-experts:django-expert" }
      ],
      "validation": "from apps.users.models import User; print('Wave 1 OK')"
    }
  ],
  "metadata": {
    "tech_spec": "tech-specs/approved/TS-0042-inventory.md",
    "generated_at": "2025-01-15T10:00:00Z",
    "total_tasks": 3,
    "max_parallel": 2,
    "critical_path": ["task-001", "task-003"]
  }
}

Step 4: Create context.md

Shared project context read once by all agents (token-efficient):

• Brief project overview from PRD
• Technology stack
• Project conventions (from CLAUDE.md)
• Key directories
• Contracts location

Step 5: Create Architecture Documentation

Create architecture.md with Mermaid component diagram:

graph TB
    Client["Client/Frontend"]
    Gateway["API Gateway"]

    subgraph Users["Users Service<br/>(task-001)"]
        UserAPI["User API<br/>/api/users/"]
        UserDB["User DB"]
    end

    subgraph Products["Products Service<br/>(task-002)"]
        ProductAPI["Product API<br/>/api/products/"]
        ProductDB["Product DB"]
    end

    Client --> Gateway
    Gateway --> UserAPI
    Gateway --> ProductAPI
    UserAPI --> UserDB
    ProductAPI --> ProductDB

Conventions:

• Use subgraph to group by service/task
• Include task number for ownership clarity
• Solid arrows (-->) for direct dependencies
• Dotted arrows (-.->) for weak dependencies

Step 6: Create Contracts

contracts/types.py

from dataclasses import dataclass
from typing import Optional
from datetime import datetime
from enum import Enum

class UserRole(str, Enum):
    ADMIN = "admin"
    USER = "user"

@dataclass
class User:
    id: int
    email: str
    username: str
    role: UserRole
    created_at: datetime

@dataclass
class UserCreateRequest:
    email: str
    username: str
    password: str

contracts/api-schema.yaml

openapi: 3.0.0
info:
  title: API
  version: 1.0.0

components:
  schemas:
    User:
      type: object
      required: [id, email, username]
      properties:
        id: {type: integer}
        email: {type: string, format: email}
        username: {type: string}

paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: User list

Step 7: Task Decomposition

Create task specs in tasks/ using compact YAML format.

See the parallel-task-format skill for the complete task specification format.

Decomposition Principles

• Contract-first: Define interfaces before implementation
• Maximize independence: Tasks should touch separate files/modules
• Explicit boundaries: Specify what each task CAN and CANNOT touch
• 2-4 hour granularity: Not too big, not too small
• Token efficiency: Compact YAML format, shared context.md

Step 8: Create task-graph.md

Dependency visualization with Mermaid:

flowchart TB
    subgraph W1[Wave 1 - parallel]
        t001[task-001-users<br/>django-expert]
        t002[task-002-products<br/>django-expert]
    end
    subgraph W2[Wave 2 - parallel]
        t003[task-003-orders<br/>django-expert]
    end
    t001 --> t003
    t002 --> t003

Include Gantt chart for timeline:

gantt
    title Parallel Task Execution
    dateFormat YYYY-MM-DD

    section Wave 1
    task-001-users :t001, 2025-01-01, 4h
    task-002-products :t002, 2025-01-01, 4h

    section Wave 2
    task-003-orders :crit, t003, after t001, 3h

Step 9: Generate Prompts

Use the parallel-prompt-generator skill to generate agent-ready prompts from the task files.

This creates:

• prompts/agent-prompts.md - Wave summary and launch commands
• prompts/task-NNN.txt - Individual agent prompts

See the parallel-prompt-generator skill for the complete prompt template and generation workflow.

Key points:

• Each prompt includes the full context.md content
• Contract files are referenced (agent reads them)
• Scope uses CREATE/MODIFY/BOUNDARY from task spec
• Output Format JSON block is included for structured completion reporting

Step 10-11: Update Manifest & Report

Update manifest.json with final task counts.

Report summary:

Decomposition Complete

Output: parallel/TS-0042-inventory-system/
Source: docs/prd.md
Tech Spec: TS-0042

Tasks: 6
Waves: 3
Max parallel: 3

Next: Run cpo run parallel/TS-0042-inventory-system/

Validation Checklist

Before finalizing:

• No circular dependencies
• Wave ordering valid
• 2-4 hour task granularity
• File independence between tasks
• BOUNDARY section in every task
• Output Format section in every task (see parallel-task-format skill)
• Agent assigned to every task
• Complete types.py and api-schema.yaml
• Architecture diagram with task ownership
• Task graph with Mermaid flowchart

Common Decomposition Patterns

Microservices

Wave 1: shared-models (contracts)
Wave 2: users-service, products-service, orders-service (parallel)
Wave 3: api-gateway
Wave 4: integration-tests

Django Feature

Wave 1: models-and-migrations
Wave 2: views-and-serializers, api-endpoints (parallel)
Wave 3: comprehensive-tests

React Feature

Wave 1: types-and-hooks
Wave 2: form-components, list-components (parallel)
Wave 3: pages (parallel)
Wave 4: routing-and-integration

Troubleshooting

Circular Dependencies

Split coupled tasks or create intermediate shared task.

Task Too Large (>4 hours)

Split by component (models, views, tests) or defer optional features.

Tech Spec Incomplete

Warn user, generate best-effort contracts with TODOs.

Contract-Task Mismatch

Update contracts first, then regenerate prompts.