Instrucciones de origen · Vista previa de solo lectura
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:
Analyze the failure — what went wrong?
Determine if it's a subagent error (bad code) or a design issue (spec is wrong)
For subagent errors: retry the step with additional context about the failure (max 2 retries)
For design issues: STOP and notify the user — do not attempt to fix design problems autonomously
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:
Identify which step(s) are affected
Determine the fix
Either fix directly or launch a targeted subagent
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
