Skip to main content

​
Overview

pdd sync is the primary command for prompt-based workflows. It implements the full synchronized development cycle from the PDD whitepaper, intelligently determining which steps are needed and executing them in order with real-time visual feedback and state management.
Run sync with --force in most real workflows to allow file overwrites without interactive confirmation.

​
Usage

pdd [GLOBAL OPTIONS] sync [OPTIONS] BASENAME
Arguments:
  • BASENAME — Base name of the prompt file. For example, use factorial_calculator for factorial_calculator_python.prompt. In agentic mode, pass a GitHub issue URL instead.

​
The 8-step workflow

When given a basename, sync runs these steps in order, skipping any that are unnecessary based on current file state:
1

auto-deps

Find and inject relevant dependencies into the prompt — both code examples and documentation files (schema docs, API docs, etc.). Removes redundant inline content that duplicates included documents.
2

generate

Create or update the code module from the prompt. Uses incremental patching when only minor changes are detected; falls back to full regeneration for new files or large diffs.
3

example

Generate a compact usage example if none exists or the existing one is outdated. The example serves as the runnable program for subsequent crash and verify steps.
4

crash

Run the example and fix any runtime errors, making the code executable.
5

verify

Execute the example program and use an LLM to judge its output against the prompt intent. Skipped when --skip-verify is set.
6

test

Generate comprehensive unit tests if they don’t exist yet. Auth modules receive auth-specific test patterns (mock OAuth servers, JWT fixtures, token lifecycle testing). Skipped when --skip-tests is set.
7

fix

Resolve any failures found by unit tests.
8

update

Back-propagate learnings from the run to the prompt file.

​
Options

​
--max-attempts
integer
default:"3"
Maximum number of fix attempts in any iterative loop within the sync run.
​
--budget
float
default:"20.0"
Maximum total cost in USD allowed for the entire sync process.
​
--skip-verify
flag
Skip the functional verification step (step 5).
​
--skip-tests
flag
Skip unit test generation and fixing (steps 6–7).
​
--target-coverage
float
default:"90.0"
Desired code coverage percentage for generated unit tests.
​
--dry-run
flag
Display real-time sync state analysis without executing operations. Performs the same state analysis as a normal run but without acquiring locks or running any steps. Safe to use even while another sync process is active.
​
--no-steer
flag
Disable interactive steering prompts during sync.
​
--steer-timeout
float
default:"8.0"
Timeout in seconds for steering prompts.

​
Agentic mode options

These options apply when passing a GitHub issue URL instead of a basename.
​
--timeout-adder
float
default:"0.0"
Additional seconds to add to each module’s timeout.
​
--no-github-state
flag
Disable GitHub comment-based state persistence and use local-only state. By default, state is stored in a hidden GitHub comment for cross-machine resume.

​
Language detection

sync automatically detects the programming language by scanning for existing prompt files matching {basename}_{language}.prompt. For example:
Prompt fileGenerated file
factorial_calculator_python.promptfactorial_calculator.py
factorial_calculator_typescript.promptfactorial_calculator.ts
factorial_calculator_javascript.promptfactorial_calculator.js
If multiple development-language prompt files share the same basename, sync processes all of them. Files ending in _llm.prompt are excluded — they are used for internal processing only and have no associated code, examples, or tests.

​
Real-time progress

Sync shows live visual feedback throughout the run:
  • Current operation (auto-deps, generate, example, crash, verify, test, fix, update)
  • File status indicators: green (up-to-date), yellow (processing), red (error or missing), blue (analysis in progress)
  • Running cost totals and elapsed time

​
Fingerprint-based change detection

Sync uses content hashes and timestamps stored in .pdd/meta/{basename}_{language}.json to detect exactly what changed. This allows it to skip unnecessary steps — for example, it won’t regenerate code if the prompt hasn’t changed since the last run.

​
The .pdd directory

PDD stores metadata in a .pdd directory at your project root: 
.pdd/
├── meta/       # Fingerprint files, run reports, sync logs
├── locks/      # Lock files to prevent concurrent operations
└── llm_model.csv  # Optional project-specific model config
Commit .pdd/meta/ and .pdd/llm_model.csv to version control. Exclude .pdd/locks/.

​
State management

  • Lock management — Prevents concurrent sync operations with automatic stale lock cleanup.
  • Run reports — Tracks test results, coverage, and execution status.
  • Git integration — Uses version control for change detection and rollback safety.
  • Test accumulation — Appends new tests to a single test file per target rather than replacing existing tests.

​
Dry-run analysis

Use --dry-run to inspect sync state without making any changes: 
# Inspect current state
pdd sync --dry-run factorial_calculator

# Include LLM reasoning for complex scenarios
pdd --verbose sync --dry-run factorial_calculator
Dry-run output includes:
  • Current file state and fingerprint comparisons
  • Decision reasoning (heuristic vs LLM-powered)
  • Operation recommendations with confidence levels
  • Estimated costs
  • Lock status

​
Agentic multi-module sync

When passed a GitHub issue URL, sync enters agentic mode:
  1. Module identification — Fetches issue content and uses an LLM to identify which modules need syncing.
  2. Dependency validation — Validates architecture.json dependencies and applies corrections.
  3. Parallel execution — Dispatches parallel sync via AsyncSyncRunner with dependency-aware scheduling (up to 4 concurrent workers).
  4. Live progress — Posts and updates a GitHub comment with real-time module sync status.
Workflow state is stored in a hidden GitHub comment, enabling resume from any machine. Use --no-github-state to disable.

​
Examples

# Basic sync with progress animation
pdd --force sync factorial_calculator

# Higher budget, custom coverage target
pdd --force sync --budget 15.0 --target-coverage 95.0 data_processor

# Skip verification for speed
pdd --force sync --skip-verify --budget 5.0 web_scraper

# Inspect state without running anything
pdd sync --dry-run factorial_calculator

# Sync using backend context from .pddrc
pdd --context backend --force sync calculator

# Sync modules from a GitHub issue (parallel, dependency-aware)
pdd sync https://github.com/myorg/myrepo/issues/100

# Agentic sync with extra timeout for large modules
pdd sync --timeout-adder 60 https://github.com/myorg/myrepo/issues/100
Sync is the recommended starting point for most PDD workflows. It embodies the PDD philosophy by treating development as a batch process — launch it and come back when it’s done.

Build docs developers (and LLMs) love

Get started for freeTalk to us