Skip to main content
The pdd sync command automates the complete development cycle for a single module. Understanding what each step does — and when to run steps manually — gives you precise control over generation quality.

​
The 8-step sync cycle

When you run pdd sync <basename>, PDD executes these steps in order, skipping steps whose outputs are already up to date:
1

auto-deps

Scans example and documentation files to find relevant dependencies. Inserts <include> directives into the prompt and removes redundant inline content that duplicates what the included files already provide.
2

generate

Creates or updates the code module from the prompt. Uses git-based change detection to decide between incremental patching and full regeneration.
3

example

Generates a compact usage example for the module. This example acts as a lightweight interface reference for other prompts and as the runnable program for crash and verify.
4

crash

Runs the example program. If it crashes, iteratively fixes runtime errors in the code and example until the program executes without errors.
5

verify

Runs the example program and uses an LLM to judge whether the output matches the prompt’s intent. Iteratively fixes the code if the output diverges.
6

test

Generates comprehensive unit tests if they don’t exist yet, or augments existing ones when coverage is below target. Tests accumulate over time — they are never overwritten.
7

fix

Runs the test suite. Iteratively fixes failing tests through multiple attempts, with an agentic fallback for particularly difficult bugs.
8

update

Back-propagates any learnings from the fix process into the prompt file, keeping the prompt as the source of truth.

​
Running a full sync

# Recommended: force flag allows file overwrites without prompts
pdd --force sync factorial_calculator

# With custom budget and coverage target
pdd --force sync --budget 15.0 --target-coverage 95.0 data_processor

# Skip verify (faster for iteration)
pdd --force sync --skip-verify --budget 5.0 web_scraper
PDD shows a real-time progress animation with color-coded file status and running cost totals.

​
Inspect state without running

Use --dry-run to see what sync would do right now, without acquiring locks or executing operations: 
pdd sync --dry-run factorial_calculator

# Include LLM reasoning for complex scenarios
pdd --verbose sync --dry-run factorial_calculator
The dry-run output shows current file state, fingerprint comparisons, operation recommendations with confidence levels, and estimated costs.

​
Running steps manually

Every step in the sync cycle is also a standalone command. Run individual steps when you need surgical control: 
pdd auto-deps my_module_python.prompt "context/"

​
Workflow selection by development phase

Choose the right workflow based on what you’re trying to accomplish:

Creation

Initial Development workflowStart from a new prompt and run pdd sync to generate all artifacts. Sync detects that no outputs exist and runs every step.
pdd --force sync new_module

Maintenance

Code-to-Prompt Update (pdd update)When code changes outside of PDD (e.g., a manual edit), sync the prompt back to match. Run repository-wide or on a single file.
pdd update --git my_module_python.prompt src/my_module.py
# or repository-wide:
pdd update

Problem-solving

Debug workflows
Issue typeCommand
Runtime crashpdd crash
Test failurespdd fix
Wrong behaviorpdd verify
Locate bug in promptpdd trace

Restructuring

Refactoring workflow (pdd split)When a prompt grows too large, split it into a parent and sub-module with an explicit interface.
pdd split data_pipeline_python.prompt src/data_pipeline.py examples/pipeline_example.py

System design

Multi-Prompt ArchitectureGenerate architecture, .pddrc, and prompt files for an entire project from a GitHub PRD issue:
pdd generate https://github.com/myorg/myrepo/issues/42
# Produces: architecture.json, architecture_diagram.html, .pddrc, prompts/*.prompt
Then sync each module:
pdd sync my_module

​
Full example: syncing basename through the cycle

This walkthrough follows a module called basename (a Python file path utility) from prompt to passing tests.
1

Write the prompt

Create prompts/basename_python.prompt with role, requirements, and dependencies.
2

Run auto-deps

pdd auto-deps prompts/basename_python.prompt "context/"
PDD scans context/ for relevant examples and inserts <include> directives.
3

Generate code

pdd generate --output src/basename.py prompts/basename_python.prompt
Creates src/basename.py.
4

Generate example

pdd example --output examples/basename_example.py prompts/basename_python.prompt src/basename.py
Creates a minimal runnable usage example.
5

Fix crashes

pdd crash prompts/basename_python.prompt src/basename.py examples/basename_example.py crash_errors.log
If basename_example.py crashes, PDD fixes basename.py and the example until it runs.
6

Verify behavior

pdd verify prompts/basename_python.prompt src/basename.py examples/basename_example.py
Runs the example and judges the output against the prompt’s intent.
7

Generate and fix tests

pdd test --output tests/test_basename.py prompts/basename_python.prompt src/basename.py
pdd fix --manual --loop prompts/basename_python.prompt src/basename.py tests/test_basename.py errors.log
8

Back-propagate learnings

pdd update --git prompts/basename_python.prompt src/basename.py
Updates the prompt with any requirements clarified during fixing.
9

Or run everything at once

pdd --force sync basename
Sync detects what’s missing or outdated and runs only the necessary steps.

​
Agentic multi-module sync

Pass a GitHub issue URL instead of a basename to sync all modules affected by that issue in parallel: 
pdd sync https://github.com/myorg/myrepo/issues/100

# With extra timeout for large modules
pdd sync --timeout-adder 60 https://github.com/myorg/myrepo/issues/100
PDD identifies affected modules, validates architecture.json dependencies, and dispatches up to 4 concurrent sync workers. Progress is posted as a live GitHub issue comment.
State is stored in a hidden GitHub comment for cross-machine resume. Use --no-github-state to disable cloud state persistence.

Build docs developers (and LLMs) love

Get started for freeTalk to us