/pdd-build

name: pdd-build
description: Execute a completed PDD implementation plan step-by-step with validation gates.
kind: sop

PDD Build

Overview

This SOP takes a completed PDD project (design doc + implementation plan) and executes the implementation plan step-by-step using subagents. Each step is built by a subagent, then verified against user-defined "done" criteria before advancing. The user defines how completion is validated — automated tests, manual testing via tmux, browser validation via Playwriter, visual inspection, or any combination.

Parameters

• **project_dir** (required): Path to the PDD project directory (e.g., `.agents/planning/2026-02-10-review-extension`)
• **validation_strategy** (required): How the agent should verify each step is done. The user must explain this in detail.
• **start_step** (optional, default: 1): Step number to start from (for resuming interrupted builds)

**Constraints for parameter acquisition:**

• You MUST ask for all required parameters upfront in a single prompt
• You MUST verify the project_dir contains the expected PDD artifacts before proceeding:
• `design/detailed-design.md` must exist
• `implementation/plan.md` must exist and contain a checklist
• You MUST ask the user to describe their validation strategy in detail — this is the critical input
• The user MUST explain how the agent should know a step is done. Examples:
• "Run `npm test` and all tests must pass"
• "Open a tmux session and test the CLI command as a user"
• "Use the playwriter skill to open the browser and verify the UI renders correctly"
• "Run the extension with `pi -e ./index.ts` in a tmux window and execute `/review test.md`"
• A combination: "Run unit tests, then use playwriter to check the browser UI"
• You MUST confirm you understand the validation strategy by summarizing it back
• You MUST NOT proceed without explicit user confirmation of the validation strategy
• You MUST check the implementation plan checklist for already-completed steps and offer to resume from the next incomplete step

Steps

1. Load and Parse the Implementation Plan

Read the PDD artifacts and prepare for execution.

**Constraints:**

• You MUST read the following files:
• `{project_dir}/design/detailed-design.md`
• `{project_dir}/implementation/plan.md`
• Any research files in `{project_dir}/research/`
• You MUST parse the checklist from `plan.md` to determine which steps are complete and which remain
• You MUST parse each step's details: objective, guidance, tests, integration notes, demo description
• You MUST present a summary to the user:
• Total steps, completed steps, remaining steps
• The validation strategy as understood
• Estimated scope of work
• You MUST ask for confirmation before starting execution
• You MUST NOT begin execution without explicit user go-ahead

2. Prepare the Build Context

Assemble the context documents that each subagent will need.

**Constraints:**

• You MUST create a build context file at `{project_dir}/implementation/build-context.md` containing:
• The full detailed design (or a focused summary if the design is very large)
• The validation strategy
• The current state of the implementation (which steps are done)
• Any relevant research findings
• You MUST identify file paths and directories the subagents will need to create or modify
• You MUST verify that prerequisites exist (e.g., `package.json`, directory structure, dependencies)
• You SHOULD create any prerequisite files or directories that don't exist yet
• You MUST load any skills referenced in the validation strategy (e.g., playwriter, clipboard, notification)

3. Execute Steps

Execute each implementation step using a subagent, then validate.

**Constraints:**

• You MUST execute steps sequentially unless the user explicitly approved parallel execution
• For each step, you MUST follow this exact process:

3a. Brief the Subagent

• You MUST construct a clear, self-contained prompt for the subagent that includes:
• The step objective and guidance from the implementation plan
• Relevant sections of the design doc (not the entire doc — only what's needed for this step)
• The current file state (what exists, what was built in previous steps)
• Explicit instructions on what files to create or modify
• The test/verification criteria for this step
• You MUST NOT include the entire design doc in every subagent prompt — extract only relevant sections
• You MUST include the project's file structure context so the subagent knows where things are

3b. Launch the Subagent

• You MUST use the `subagent` tool to execute the step
• You SHOULD use async mode for steps that are expected to take a long time
• You MUST monitor the subagent's progress if running async (check status periodically)
• You MUST capture the subagent's output for review

3c. Verify the Step

• You MUST verify the step is complete using the user-defined validation strategy
• You MUST NOT skip validation — this is the critical gate
• Validation methods (use whichever the user specified):

**Automated tests:**

• Run the test command (e.g., `npm test`, `pytest`, etc.)
• All tests must pass
• Check test output for failures

**Tmux manual testing:**

• Use `rho_subagent` to open a tmux window with the test scenario
• Or use `bash` to run commands in a tmux session
• Verify expected output or behavior

**Playwriter browser validation:**

• Load the playwriter skill
• Navigate to the relevant URL
• Verify UI elements render correctly
• Check for visual regressions or interaction issues

**File verification:**

• Read created/modified files to verify they match expectations
• Check that code compiles/parses correctly
• Verify file structure matches the design

**Combination:**

• Execute each validation method in sequence
• All must pass for the step to be considered done

3d. Handle Failures

• If validation fails, you MUST:

1. Ana