RFC: Multi-Stage Intent Compilation Pipeline (Proposal → PRD → Spec → Design → Tasks)

[rexhsu]

RFC: Multi-Stage Intent Compilation Pipeline (Proposal → PRD → Spec → Design → Tasks)

Summary

This RFC proposes introducing an explicit Human-Readable Spec (PRD) stage within the standard OpenSpec change lifecycle. By structuring the workflow into a multi-stage compilation pipeline (Proposal → PRD → Spec → Design → Tasks), OpenSpec can bridge the gap between non-technical domain owners (PMs/BAs) and technical execution agents (Coding Agents/RDs) while preserving a single source of truth in Git.

Problem Statement

OpenSpec excels at providing machine-readable precision for AI Coding Agents and technical reviewers (spec.md). However, adoption across cross-functional teams faces key friction points:

1. High Cognitive Load for Non-Technical Stakeholders: Business stakeholders (PMs, Product Owners) find reading and reviewing raw spec.md or technical schemas challenging.
   
   
2. Context Shift and Information Drift: When PMs maintain PRDs in external tools (e.g., Notion, Confluence, Jira) while developers/agents use OpenSpec in Git, the specification and implementation drift apart quickly.
   
   
3. Intent-to-Code Granularity Gap: Transitioning directly from a high-level proposal.md to a strict spec.md often causes LLM agents to invent technical boundaries or miss subtle domain rules before architecture is even considered.
   
   

Proposed Solution

Introduce a progressive, multi-stage intent compilation pipeline where each artifact targets a specific stakeholder role and level of abstraction within the change directory (/openspec/changes/<change-name>/):

Plaintext

[1-proposal.md]  --> PM/Business: "Why & High-level What"
       │
       ▼
[2-prd.md]       --> PM/RD Consensus: "Human-Readable UX & Business Rules" (Human-Centric)
       │
       ▼
[3-spec.md]      --> RD/Agent Review: "OpenSpec Rigorous Requirements & Constraints" (Machine-Centric)
       │
       ▼
[4-design.md]    --> RD/Agent Architecture: "API Schemas, DB Models, Sequence Diagrams"
       │
       ▼
[5-tasks.md]     --> Agent Execution: "Actionable Atomic Checklists"

Artifact Breakdown

Stage | File | Primary Owner | Target Audience | Focus Area -- | -- | -- | -- | -- 1. Proposal | 1-proposal.md | PM / Lead | Entire Team | Problem background, business motivation, scope boundaries. 2. PRD | 2-prd.md | PM | PM, UX, QA, RD | User stories, natural-language business logic, edge cases, acceptance criteria. 3. Spec | 3-spec.md | RD / Agent | AI Agent, RD | Strictly structured OpenSpec (SHALL, MUST NOT), constraints, invariants. 4. Design | 4-design.md | RD / Agent | RD, AI Agent | System architecture, Sequence diagrams (Mermaid), DB schemas, Error codes. 5. Tasks | 5-tasks.md | Agent / RD | AI Coding Agent | Atomic, testable micro-tasks for incremental PR implementation.

CLI & Workflow Integration

We propose extending the openspec change CLI or providing a first-class workflow adapter/profile:

Bash

# Initialize change directory
openspec change new <change-name>
# Step 1: Generate/Refine Human PRD from Proposal

openspec change prd <change-name>
# Step 2: Compile PRD into Machine-Readable OpenSpec

openspec change spec <change-name>
# Step 3: Generate Technical Design & Architecture

openspec change design <change-name>
# Step 4: Break down into Execution Checklist

openspec change tasks <change-name>

Review & Verification Strategy

• PM Review Gate: PMs review 2-prd.md in Pull Requests.
  
  
• RD Review Gate: Engineers review 3-spec.md and 4-design.md.
  
  
• Agent Execution: Coding Agents consume 3-spec.md, 4-design.md, and execute 5-tasks.md sequentially.
  
  

Benefits

1. Single Source of Truth: All artifacts—from business intent (2-prd.md) to technical spec (3-spec.md) and code tasks (5-tasks.md)—live together in /openspec/changes/<change-name>/.
   
   
2. Role-Clear Review Delegation: Stakeholders review only the artifacts meant for their cognitive domain, eliminating friction over reading machine-targeted Markdown formats.
   
   
3. Reduced AI Hallucination: Layering the prompt context step-by-step ensures that the AI Agent constructs architecture on verified domain logic.
   
   

Questions / Discussion for Maintainers

1. Should this multi-stage pipeline be built into the core openspec CLI profile, or provided as an official workflow extension/schema (e.g., @openspec/schema-prd-pipeline)?
   
   
2. How can we best customize prompt templates for transition steps (e.g., customizing how 2-prd.md compiles into 3-spec.md based on team conventions)?