Skip to main content
PDD can read a GitHub issue and drive the full implementation cycle — from writing failing tests to creating a reviewed pull request — without manual intervention.

​
Prerequisites

1

Install GitHub CLI

PDD needs gh to read and comment on issues.
brew install gh && gh auth login
2

Install one agentic CLI

PDD delegates complex reasoning to an agentic CLI. Install at least one:
npm install -g @anthropic-ai/claude-code
Requires ANTHROPIC_API_KEY.

​
Method 1: Web interface

The easiest entry point. pdd connect launches a browser UI where you can run any agentic command and watch progress in real time. 
pdd connect
From the interface, run:
  • pdd change https://github.com/myorg/myrepo/issues/123 for features
  • pdd bug https://github.com/myorg/myrepo/issues/456 for bugs
PDD posts progress as GitHub issue comments and creates a draft PR automatically.

​
Method 2: Feature workflow (pdd change)

pdd change implements a feature request from a GitHub issue using a 12-step agentic workflow. 
pdd change https://github.com/myorg/myrepo/issues/123
  1. Duplicate check — Search for existing issues describing the same request
  2. Documentation check — Verify the feature is not already implemented
  3. Research — Web search for specifications and best practices
  4. Clarification — Ensure requirements are clear; posts questions to the issue if not (pauses until answered)
  5. Documentation changes — Identify required documentation updates
  6. Identify dev units — Find affected prompts, code, examples, and tests
  7. Architecture review — Surface architectural decisions; posts questions if needed (pauses until answered)
  8. Analyze changes — Design prompt modifications
  9. Implement changes — Modify prompts in an isolated git worktree
  10. Identify issues — Review changes for problems
  11. Fix issues — Iterative fix loop, up to 5 passes
  12. Create PR — Open a pull request linked to the issue

​
Handling clarifying questions

Steps 4 and 7 may pause the workflow to ask questions in the GitHub issue comments. When this happens:
  1. Answer the questions in the issue
  2. Re-run the same command — PDD resumes from the last completed step
# Resume after answering clarifying questions
pdd change https://github.com/myorg/myrepo/issues/123
Workflow state is stored in a hidden GitHub comment, so you can resume from any machine. Pass --no-github-state to keep state local only.
After the PR is created, it includes a sync_order.sh script. Run it after merge to regenerate code from modified prompts: 
./sync_order.sh

​
Method 3: Bug workflow (pdd bug + pdd fix)

Use this two-command pair to fix bugs from GitHub issues.

​
Step 1: Create failing tests

pdd bug analyzes the issue and creates failing tests that reproduce the bug. 
pdd bug https://github.com/myorg/myrepo/issues/456
The 10-step workflow posts findings as issue comments at each stage: duplicate check, documentation check, triage, reproduction, root cause analysis, prompt classification, test plan, test generation, detection verification, and finally a draft PR with the failing tests.
If pdd bug determines the bug is in the prompt specification rather than the code, it auto-fixes the prompt file and posts a comment explaining what was changed.

​
Step 2: Fix the failing tests

pdd fix iteratively fixes the code until all tests pass, then validates against CI. 
pdd fix https://github.com/myorg/myrepo/issues/456
If pdd bug created correct tests that you trust, use --protect-tests so the LLM only fixes code — not tests: 
pdd fix --protect-tests https://github.com/myorg/myrepo/issues/456
Additional fix options:
FlagDescription
--ci-retries INTMaximum post-push fix attempts (default: 3)
--skip-ciSkip CI validation entirely
--max-cycles INTMaximum outer loop iterations (default: 5)
--no-resumeStart fresh, ignoring saved state

​
pdd checkup: automated project health check

pdd checkup scans a project end-to-end, identifies problems, fixes them, writes regression tests, and creates a PR. 
pdd checkup https://github.com/myorg/myrepo/issues/42
  1. Discover — Scan project structure, tech stack, and module inventory
  2. Dependency audit — Check all imports resolve; detect missing packages and circular deps
  3. Build check — Run build/compile commands; check for syntax and type errors
  4. Interface check — Verify cross-module interfaces, nav reachability, API call consistency
  5. Test execution — Run the full test suite; identify failures
  6. Fix issues (3 sub-steps):
    • Fix discovered issues (missing deps, imports, interfaces, build errors, orphan pages)
    • Write regression tests for every fix
    • Write end-to-end tests for cross-module interactions
  7. Verify — Re-run build and tests to confirm all fixes work
  8. Create PR — Open a pull request with all fixes and tests
Steps 3–7 loop up to 3 times until step 7 reports “All Issues Fixed.”
Run in report-only mode to audit without making changes: 
pdd checkup --no-fix https://github.com/myorg/myrepo/issues/42

​
User story validation

PDD can validate that your prompts satisfy user stories stored as Markdown files. Stories live in user_stories/ and must match the pattern story__*.md. 
# Run the full validation suite
pdd detect --stories

# Generate a story file from prompt files
pdd test prompts/upload_python.prompt prompts/notify_python.prompt

# Apply a single story to prompts and re-validate
pdd fix user_stories/story__my_flow.md
Stories can include optional metadata to scope validation to a subset of prompts: 
<!-- pdd-story-prompts: prompts/upload_python.prompt, prompts/notify_python.prompt -->
Without this metadata, pdd detect --stories validates against the full prompt set.
pdd change automatically runs story validation after modifying prompts and fails if any story fails — keeping your feature implementations aligned with user intent.
Override directories with environment variables:
VariableDefaultDescription
PDD_USER_STORIES_DIRuser_stories/Directory containing story__*.md files
PDD_PROMPTS_DIRprompts/Directory containing .prompt files

Build docs developers (and LLMs) love

Get started for freeTalk to us