Skip to main content

​
Overview

pdd generate produces the full implementation code that fulfills all requirements in a prompt. When changes are detected between the current prompt and its last committed version, it automatically performs incremental updates rather than full regeneration. Passing a GitHub issue URL instead of a prompt file activates agentic architecture mode, which runs an 11-step workflow to generate architecture.json, .pddrc, and prompt files from a PRD.

​
Usage

pdd [GLOBAL OPTIONS] generate [OPTIONS] PROMPT_FILE
Arguments:
  • PROMPT_FILE — Path to the prompt file, or a GitHub issue URL for agentic architecture mode. Required unless --template is used.

​
Options

​
--output
string
Where to save the generated code. Supports $VAR and ${VAR} expansion from -e/--env values. Defaults to <basename>.<language_extension> in the current directory, or to PDD_GENERATE_OUTPUT_PATH if that environment variable is set.
​
--original-prompt
string
The original prompt file used to generate the existing code. When omitted, the command automatically retrieves the last committed version of the prompt file from git.
​
--incremental
flag
Force incremental patching even if changes are significant. Only valid when --output points to an existing file.
​
--unit-test
string
Path to a unit test file. When provided, automatic test discovery is disabled and only this file’s content is included in the prompt, instructing the model to generate code that passes the specified tests.
​
--exclude-tests
flag
Do not automatically include test files found in the default tests directory.
​
--template
string
Use a built-in or project template instead of a prompt file. Cannot be combined with PROMPT_FILE.
​
-e / --env
string
Set parameter variables as KEY=VALUE pairs (repeatable). Used for prompt templating and --output path expansion. See Parameter variables below.
​
--output-dir
string
Target subdirectory for the new project (agentic architecture mode only).
​
--skip-prompts
flag
In agentic architecture mode, skip prompt file generation (steps 8–11) and only generate architecture.json and .pddrc.
​
--force-single
flag
In agentic architecture mode, force single-project generation even if the PRD describes a complex multi-app system (skips the complexity check).

​
Parameter variables

Use -e KEY=VALUE (or -e KEY to read VALUE from the current shell environment) to parameterize a prompt so that one prompt can generate multiple files with different values. 
# Generate an orders module
pdd generate -e MODULE=orders --output 'src/${MODULE}.py' prompts/module_python.prompt

# Generate multiple modules from the same prompt
pdd generate -e MODULE=orders    --output 'src/${MODULE}.py' prompts/module_python.prompt
pdd generate -e MODULE=payments  --output 'src/${MODULE}.py' prompts/module_python.prompt
pdd generate -e MODULE=customers --output 'src/${MODULE}.py' prompts/module_python.prompt

# Multiple variables
pdd generate -e MODULE=orders -e PACKAGE=core --output 'src/${PACKAGE}/${MODULE}.py' prompts/module_python.prompt

# Docker-style env fallback (reads MODULE from the shell)
export MODULE=orders
pdd generate -e MODULE --output 'src/${MODULE}.py' prompts/module_python.prompt
Templating rules:
  • In prompt content: $VAR and ${VAR} are replaced only when VAR was explicitly provided via -e.
  • In --output: the same variable set is used for path expansion.
  • Unknowns: placeholders without a provided value are left unchanged — no escaping required.
  • Precedence: -e/--env values override same-named OS environment variables during expansion for this command.
Shell quoting:
  • Quote values with spaces: -e "DISPLAY_NAME=Order Processor".
  • Use single quotes to let PDD expand --output rather than the shell: --output 'src/${MODULE}.py'.

​
Git integration

Generate uses git to determine the scope of changes:
  • When the output file exists and the prompt has changed since the last commit, generate automatically considers incremental patching.
  • After incremental generation, both the prompt and code file are staged with git add to ensure rollback is possible.
  • Full regeneration always occurs for new files (no existing output file) or when the output file has been deleted.
# Incremental if output file exists; full generation if it doesn't
pdd generate --output src/calculator.py calculator_python.prompt

​
Agentic architecture mode

When the positional argument is a GitHub issue URL, generate enters agentic architecture mode. The issue body serves as the PRD (Product Requirements Document), and an 11-step workflow produces architecture.json, .pddrc, and prompt files. 
pdd generate https://github.com/myorg/myrepo/issues/42
# Generates: architecture.json, architecture_diagram.html, .pddrc, prompts/*.prompt

# Skip prompt file generation (architecture and .pddrc only)
pdd generate --skip-prompts https://github.com/myorg/myrepo/issues/42
1

Analyze PRD

Extract features, tech stack, and requirements from the issue content.
2

Deep analysis

Feature decomposition, module boundaries, and shared concerns.
3

Research

Web search for tech stack documentation and best practices.
4

Design

Module breakdown with dependency graph and priority ordering. Auth modules are separated into dedicated concerns with low priority numbers.
5

Research dependencies

Find relevant API docs and code examples per module.
6

Generate

Produce complete architecture.json and scaffolding files.
7

Generate .pddrc

Create project configuration with context-specific paths.
8

Generate prompts

Create prompt files for each module in architecture.json.
9

Completeness validation

Verify all modules have prompts and dependencies.
10

Sync validation

Run pdd sync --dry-run on each module to catch path issues.
11

Dependency validation

Preprocess prompts to verify &lt;include&gt; tags resolve correctly.
Each validation step (9–11) retries up to 3 times with automatic fixes before proceeding. Prerequisites for agentic mode:
  • gh CLI must be installed and authenticated.
  • The issue must contain a PRD describing the project scope.
Workflow resumption: Re-running pdd generate <issue-url> resumes from the last completed step. State is persisted to GitHub issue comments for cross-machine resume. Hard stops: The workflow halts if the PRD is insufficient, the tech stack is ambiguous, or clarification is needed. Answer any questions in the issue and re-run to continue.

​
Templates

Templates are reusable prompt files with YAML front matter metadata. Use --template instead of a prompt file path: 
# Generate architecture from a PRD file using the built-in template
pdd generate --template architecture/architecture_json \
  -e PRD_FILE=docs/specs.md \
  -e APP_NAME=MyApp \
  --output architecture.json
# Produces: architecture.json + architecture_diagram.html

# Post-processing only (skip LLM, regenerate HTML from existing JSON)
pdd generate --template architecture/architecture_json \
  -e APP_NAME=MyApp \
  -e llm=false \
  --output architecture.json
Template commands: 
pdd templates list [--json] [--filter tag=frontend]
pdd templates show <name>
pdd templates copy <name> --to prompts/

​
Examples

# Generate from a basic prompt
pdd generate calculator_python.prompt

# Specify output location
pdd generate --output src/calculator.py calculator_python.prompt

# Parameterized generation
pdd generate -e MODULE=orders --output 'src/${MODULE}.py' prompts/module_python.prompt

# Generate with a specific unit test to guide generation (TDD)
pdd generate --unit-test tests/test_calculator.py calculator_python.prompt

# Generate architecture from a GitHub PRD issue
pdd generate https://github.com/myorg/myrepo/issues/42

Build docs developers (and LLMs) love

Get started for freeTalk to us