PDD - Patch-Driven Development

Safe changes in real systems.

PDD is a CLI-first framework for bugfix and feature work in existing codebases.
It standardizes how teams investigate, plan, validate, and document changes.

Language versions: English | Português (Brasil)

Why PDD

• Worktree-first execution for safer parallel development
• Structured change artifacts (delta-spec, patch-plan, verification-report)
• Consistent workflow for Cursor, Claude Code, and GitHub Copilot
• Built-in quality gates (doctor, validation, baseline CI checks)

Install

Requirements:

• Node.js >= 18
• Git available in PATH

Run without global install (recommended):

npx @pcoliveira90/pdd --version

Optional global install:

npm install -g @pcoliveira90/pdd
pdd --version

Download and Update

Download PDD (without global install):

npx @pcoliveira90/pdd@latest --version

Update global CLI to latest:

npm install -g @pcoliveira90/pdd@latest
pdd --version

Update PDD templates/version inside your repository:

pdd init --here --upgrade
pdd doctor

If you maintain this repository locally, update source code too:

git pull origin main

Quick Start

# 1) Initialize PDD in the current repository
npx @pcoliveira90/pdd init --here

# 2) Run a fix workflow
npx @pcoliveira90/pdd fix "login not saving incomeStatus"

Core Commands

pdd init --here
pdd doctor
pdd status
pdd fix "bug description" [--dry-run] [--no-validate] [--open-pr]
pdd version

AI analysis command:

pdd-ai --provider=openai --task=analysis "bug description"

Workflow Summary

1. Understand current behavior and root cause
2. Generate change artifacts under changes/<change-id>/
3. Validate tests/lint/build
4. Prepare PR artifacts and review in IDE

IDE Alignment

PDD keeps equivalent intents across tools:

• Cursor: .cursor/commands/pdd-*.md
• Claude Code: .claude/commands/pdd-*.md
• GitHub Copilot: .github/prompts/pdd-*.prompt.md

Documentation

• docs/getting-started.md
• docs/installation-and-setup.md
• docs/fix-workflow.md
• docs/manifesto.md

Goal

Reliable execution engine for safe software changes.