# PDD treats prompt files as the source language, and its own package ships a web server only in the requirements file

> A prompt native development system whose CLI drives GitHub issues through fixed step workflows, with a routing rule that sends runtime symptoms down a bug path instead of a change path. The distribution requires Python 3.12 in prose while classifying 3.11, and the test tools are runtime dependencies.

**promptdriven/pdd** —  Prompt Driven Development (PDD): The Last Programming Language™. Prompt files are source; code is generated output.

- Repository: https://github.com/promptdriven/pdd
- Website: https://promptdriven.ai
- Stars: 884 · Forks: 79
- Language: Python
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/promptdriven-pdd

## Two releases two days apart, then a six week gap

The release record is three entries in the zero hundreds. The first two land two days apart in late July, and the third comes six weeks later in September. The repository was last pushed in late September, so the branch has moved past the newest tag again.

The version number itself is the story. A project at zero point three hundred and ten has shipped a lot of changes, and the metadata classifies it as alpha rather than beta. The version is not written in the file at all: the manifest marks it dynamic, and the build backend configuration lists a source control versioning plugin among the build requirements, so the number comes from a tag at build time.

There are two build paths in the tree and the older one says so itself. A compatibility setup script exists alongside the manifest, and it is five lines long: a docstring stating that native authority is runtime scoped, an import of setuptools, and a call to run it. In other words, the project deliberately keeps a thin shim for anyone still invoking a setup script, while the manifest is what actually decides anything. That is a reasonable arrangement, but it does mean an old install path still resolves dependencies through the shim rather than through the declared build backend.

## The guide requires Python 3.12 while the classifiers list 3.11

The installation prerequisites end with a short note that recent versions of macOS no longer ship with a pre-installed Python, followed by a statement of the floor: the tool requires Python 3.12 or higher. The suggested fix is a single Homebrew install, which brings the latest Python 3.

The project metadata disagrees with that note by one minor version. The interpreter classifiers name 3.11 and 3.12, with no 3.13 or 3.14 despite both existing and despite several dependencies in the same list being recent enough to require them. A project whose own guide says 3.12 and whose classifier says 3.11 has two different answers to the same question.

The macOS prerequisites are otherwise thorough, which is what makes the inconsistency stand out. There is a command line tools install for the compiler Python needs, a Homebrew bootstrap command, a line that adds the shell environment to a profile file and evaluates it, and a version check for Python. The system package manager itself is described as recommended rather than required, so a Linux or Windows user is expected to arrive with their own toolchain, and the tree carries a separate setup document for Windows to match.

## The requirements file splits three ways, and the manifest carries the test runner

The dependency story is told twice, and the two tellings do not line up. The requirements file is organised into three commented sections: production dependencies, server dependencies for the connect command, and development dependencies. The server section is a short list containing a web framework, an application server, a websocket library, a file watcher and a token counter. The development section is packaging and test tooling.

The manifest has no such structure. Its single dependency list runs past thirty entries and mixes categories freely: a model gateway, a graph library, four language chain packages, two cloud SDKs, an authentication library for the system keychain, a terminal rendering library, and the test runner with its coverage plugin, both pinned. Test tooling inside runtime dependencies means every install carries a test framework whether or not it will be used.

Two entries in the requirements file are worth a second look. A theorem prover solver is pinned as a production dependency, which implies the contract checking described in the documentation is enforced at runtime rather than only during development. Three syntax tree packages for two languages suggest the source files are parsed rather than treated as opaque text, which is consistent with a tool that claims to analyse generated code as well as author prompts.

## Six issue commands, four of them with a stated step count

The agentic surface is six commands, and four of them advertise a workflow length. The change command runs a thirteen step workflow for feature requests. The split command runs fifteen steps, and its description enumerates them: intent classification, diagnosis, phase extraction, a verify gate per child, and repair, which makes it the most specified of the six. The generate command runs eleven steps and takes a product requirements issue as input to produce an architecture file. The test command runs eighteen steps, covering exploratory testing, contract validation and accessibility audits.

The remaining two have no count because they are halves of a pair. The bug command creates failing tests, and the fix command makes them pass. The routing policy that pairs them is stated more forcefully than anything else in the document, and it is a correction of a common mistake: when an issue reports a current runtime symptom, use the bug path even if the issue text says the prompt or the spec should be updated. Stack traces, failing commands, wrong output, regressions and crashes all belong in reproduce then test, and the sequence is bug followed by fix.

The mirror image is the change path, which is for explicit source, spec or product changes with nothing currently broken, followed by a sync step once the change lands. The sync command is the one that automates the whole cycle rather than a single unit of work.

## Setup is deferred on purpose, and the reminder knows when to stay quiet

The setup step is described as a separate command rather than part of installation, and it does four things: detects installed agentic command line tools, scans for API keys, configures models, and seeds local configuration files. The first two are the interesting ones, because they mean the tool is meant to discover what you already have rather than ask you to declare it up front.

What happens if you skip it is spelled out with more precision than most tools manage. The command line detects the missing artifacts the first time you run anything else and shows a reminder banner, so the omission is recoverable rather than fatal. The banner then has two suppression conditions: it disappears once a specific file exists in the home directory, and it stays hidden if your project already supplies credentials through its own environment file or its own project directory.

That second condition is the useful one for a team. A project that manages its own keys does not get nagged, and the marker file it checks for is a per-user artefact, so two people working on the same repository can each be in a different setup state without either being wrong. The install itself is two commands:

```bash
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install PDD using uv tool install
uv tool install pdd-cli
```

The version check afterwards is a single flag, and a plain package install is offered as an alternative for people who already manage Python environments themselves.

## Three keys are required up front and several more are offered

The example environment file is the clearest statement of the provider surface. Three keys are marked as needed, with at least one required, covering the three largest model providers. A second block adds four more as optional, for a total of seven named providers, and a third block covers a cloud-hosted option for one of the three required ones with a project identifier and a region.

That cloud block is the most detailed part of the file, and it walks through two setup routes. The preferred one uses the provider's own command line to log in, to create application default credentials, and to set a project, with a comment telling you to leave the credentials path variable unset when you do that. The fallback is a service account key file, described as a key file fallback only, and the file also accepts two older variable names for the same project and region. So four variable names exist for two settings, with the pair marked legacy.

The dependency list explains the credentials story from the other side: two keychain libraries are required, one of which provides alternative backends. Combined with the setup marker file, that means the tool is built to keep API keys in the operating system's credential store rather than in a plaintext file in the repository, and the example file exists to document the variables rather than to be copied and filled in.

## Four agent instruction files, and a docs directory with a versioned schema

The root of the tree carries four files whose only job is to tell a coding agent how to work here: one general agents file, one for a specific assistant, one for a third, and a fourth that is a setup walkthrough for the third. Two more setup documents cover a platform and a hosted assistant. That is a lot of instruction surface for one repository, and it is a maintenance obligation, since each file drifts when the commands change.

The documentation directory is larger and better organised by topic. One document is the positioning essay behind the whole idea. One is a full whitepaper with benchmarks. One is a case study on specification drift in assistant coding workflows. Then come the working documents: a doctrine of core principles, a methodology for turning an issue into a verifiable user story, a prompt linter covering vague terms and vocabulary, a deterministic contract checker with a named rules element, a coverage matrix document, a bounded repair document, and a routing policy document.

Two of those carry enough detail to be interfaces rather than prose. The quality gate document defines a named versioned JSON schema for its report, with a per-finding signal for whether a prompt needs clarification and a reason field beside it. That naming convention means another tool could validate the output, which is what a schema name is for. The coverage document names a regression marker for the test framework and a per-story dimension that records whether a regression test exists, which turns story coverage into something a checkup command can report.

## The readme ends on an empty heading

The document stops mid-structure. After the alternative pip install, with a single command, the next line is a level two heading with no title and no body under it, and the text resumes in a later section. A reader scrolling to the end of what is visible reaches an empty section header.

The tree has a few similar asymmetries. There are two directories whose names differ only by a trailing letter, one for demos and one for another set of demos, and a prompts entry that has no extension while the code lives in its own package directory. An architecture file sits at the root as a generated artifact, which is the output of the generate command, and a project dependencies file sits beside it as a spreadsheet-shaped record of the same kind of thing.

A sync configuration file and a project ignore file are also at the root, alongside a directory that appears to hold accumulated context and another that holds user stories. That layout is consistent with the thesis: the source of truth is the prompt and story layer, and the generated code, the architecture file and the dependency record are all things that fall out of a sync. Whether a newcomer reads that as tidy or as cluttered probably depends on whether they have accepted the premise.

## Conclusion

PDD suits a team that has already accepted generated code and wants the intent, the constraints and the tests to be the things under review. The routing policy is the part worth borrowing regardless of whether you adopt the tool, since sending a runtime symptom through a spec change instead of a reproduction is a mistake most prompt workflows make. Four things to check before installing. The prose requires Python 3.12 or newer while the classifiers still list 3.11. The manifest lists the test runner among runtime dependencies, so a production install carries it. The web interface stack is named in the requirements file rather than in the manifest, so confirm what the connect command actually has available. And the version numbers sit at zero point three hundred with an alpha classification, so treat the tool as pre 1.0 and pin what you depend on.

## FAQ

### What is the difference between pdd bug and pdd change?

An issue reporting a current runtime symptom should go through pdd bug and then pdd fix, so the failure is reproduced and covered by a behavioural test, even when the issue text asks for the prompt or spec to change. pdd change is for explicit source, spec or product changes with nothing broken yet.

### Which Python version does pdd-cli require?

The installation guide states Python 3.12 or higher, while the project metadata classifies 3.11 and 3.12, so the documented floor and the declared classifiers disagree by one minor version.

### How many workflow steps does the pdd test command run?

Eighteen, covering exploratory testing, contract validation and accessibility audits. The split command runs fifteen, the change command thirteen and the generate command eleven.

### What does pdd setup do and can it be skipped?

It detects installed agentic command line tools, scans for API keys, configures models and seeds local configuration files. Skipping it is recoverable, since the CLI shows a reminder banner on the first other command, and the banner is suppressed once a marker file exists in your home directory or your project supplies its own credentials.

### How does pdd-cli expect API keys to be stored?

The dependency list includes two system keychain libraries, and the example environment file documents three required provider keys plus four optional ones, so the tool is built to keep credentials in the operating system store rather than in a committed file.

## Sources

- [License: MIT](https://github.com/promptdriven/pdd/blob/main/LICENSE)
- [Project website](https://promptdriven.ai)
- [promptdriven/pdd on GitHub](https://github.com/promptdriven/pdd)
- [README](https://github.com/promptdriven/pdd/blob/main/README.md)
- [Releases](https://github.com/promptdriven/pdd/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/promptdriven-pdd