Pdd Build

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