mikeyobrien/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

3d. Handle Failures

• If validation fails, you MUST:
  1. Analyze the failure — what went wrong?
  2. Determine if it's a subagent error (bad code) or a design issue (spec is wrong)
  3. For subagent errors: retry the step with additional context about the failure (max 2 retries)
  4. For design issues: STOP and notify the user — do not attempt to fix design problems autonomously
  5. Include the failure details and any error output in the retry prompt
• You MUST NOT retry more than 2 times per step without user intervention
• You MUST NOT silently skip failed validation
• After 2 failed retries, you MUST stop and present the situation to the user with:
  • What was attempted
  • What failed and why
  • The subagent's output
  • Your recommendation for how to proceed

3e. Update the Checklist

• On successful validation, you MUST update the checklist in plan.md to mark the step as complete ([x])
• You MUST write a brief status note to {project_dir}/implementation/build-log.md with:
  • Step number and name
  • Timestamp
  • Validation result
  • Any notable decisions or deviations
• You MUST notify the user of progress (e.g., "Step 3/12 complete: Web UI shell")

4. Integration Validation

After all steps are complete, validate the full system.

Constraints:

• You MUST run the complete validation strategy against the finished implementation
• You MUST verify that all checklist items are marked complete
• You MUST test the end-to-end flow described in the design doc
• You SHOULD run any additional integration tests that span multiple steps
• If integration issues are found, you MUST:
  1. Identify which step(s) are affected
  2. Determine the fix
  3. Either fix directly or launch a targeted subagent
  4. Re-validate after fixing

5. Report Results

Present a final summary to the user.

Constraints:

• You MUST create a build report at {project_dir}/implementation/build-report.md containing:
  • Total steps executed
  • Steps that passed on first attempt vs. required retries
  • Any deviations from the original design
  • Known issues or limitations discovered during build
  • Validation results summary
• You MUST present the report to the user in conversation
• You MUST highlight any areas that need manual attention
• You MUST suggest next steps (e.g., "TUI mode follow-up", "deploy to global extensions", etc.)

Examples

Example 1: CLI Extension with Tests

Project dir: .agents/planning/2026-02-10-review-extension
Validation strategy: Run `npm test` in the extension directory after each step.
For steps that add UI, also run `pi -e ./index.ts` in a tmux window and
execute the /review command to verify it works interactively.

Example 2: Browser UI with Playwriter

Project dir: .agents/planning/2026-02-10-review-extension
Validation strategy: After each step that changes the UI, use the playwriter
skill to open http://localhost:<port> and verify:
- The page loads without console errors
- Key elements are visible (sidebar, code viewer, buttons)
- Interactions work (click file, click line number, type comment)
For non-UI steps, verify files exist and code parses without errors.

Example 3: Full Manual Testing

Project dir: .agents/planning/2026-02-10-review-extension
Validation strategy: After each step, open a tmux split and run the
extension. Test it as a user would — try the happy path, try edge cases,
try to break it. Report what works and what doesn't. Use the notification
skill to alert me if a step fails after retries.

Example 4: Hybrid

Project dir: .agents/planning/2026-02-10-review-extension
Validation strategy:
- Steps 1-2: verify files exist and `npm install` succeeds
- Steps 3-6: use playwriter to check the browser UI renders
- Steps 7-8: use playwriter to test submit/cancel WebSocket flow
- Steps 9-10: run `pi -e ./index.ts` in tmux and test /review command
- Steps 11-12: full playwriter mobile viewport test + manual tmux test

Troubleshooting

Subagent Produces Wrong Code

• Include more design context in the retry prompt
• Reference specific sections of the design doc
• Include the error output verbatim
• If the subagent consistently misunderstands, break the step into smaller sub-steps

Validation Is Flaky

• Add retries with delays for timing-sensitive checks (e.g., server startup)
• For browser validation, add explicit waits for elements
• For tmux testing, allow time for commands to complete

Step Dependencies Are Wrong

• If a step fails because a previous step's output is wrong, fix the earlier step first
• Update the build log to note the dependency issue
• Re-run both steps in order

Design Doc Has Gaps

• STOP — do not guess at missing requirements
• Note the gap in the build log
• Ask the user for clarification
• Resume after the gap is resolved