pdd: Instructions file for Codex

Working on PDD

Before you write or change a Story or a prompt, read the full Prompting guide in this conversation. Follow its method for module ownership, public behavior, what must not change, required dependencies and the edge cases that matter. A link or a Story template is not enough. If you lose the context, read the guide again before you write.

Read skills/pdd-prompting/SKILL.md for the core rules. Prompts are the source: change the prompt that owns the behavior before you change the code. Keep expected cases apart from what the code returns. Review changes to the contract with the person. Never invent their decision. skills/pdd-prompting/guide.md must stay the same as docs/prompting-guide.md, byte for byte. A test checks this, so change both together.

What this package contains:

• Nine skills in skills/: pdd-prompting, pdd-setup, pdd-small-change, pdd-bug, pdd-feature, pdd-product, and the Autopilot skills pdd-autopilot, pdd-check and pdd-merge. People install them with npx skills add promptdriven/pdd (-g for all projects). The order is: install the skills, then the pdd-setup skill once for each repo, then the pdd command only for runs with PRs and for pdd test, pdd lint, pdd simulate and pdd approve. The pdd command does not copy skills on each command: pdd setup copies them to the user skills folders (~/.agents/skills; ~/.claude/skills, or $CLAUDE_CONFIG_DIR/skills when it is set) only when they are missing, and replaces an older copy that has the .pdd-skill.json marker. It never touches a copy without the marker, or a symlink. pdd never copies them into the person's repo. Each SKILL.md has pdd-skills: VERSION under metadata: in its frontmatter: change it with the package version. Keep each workflow skill small and its step files short. Do not repeat a rule that SKILL.md already states. Write each description so that an agent picks the skill by itself.
• People open Codex or Claude Code as usual and call pdd-feature, pdd-bug, pdd-small-change or pdd-prompting. Call a skill with $pdd-feature in Codex or /pdd-feature in Claude Code (or ask for it by name). pdd setup and the pdd-setup skill add one short block (at most 10 lines, between <!-- pdd:start --> and <!-- pdd:end -->) to CLAUDE.md, else AGENTS.md. They never paste the guide.
• pdd workflow run makes a worktree and a branch for an issue, opens the area chats in Herdr (session pdd) and returns at once. pdd has four jobs: start, gates, PRs and status. There is no controller process, no polling loop and no time limit.
• feature and bug run the check and the simulation, and the person approves, before pdd opens PR 1 (prompt, Story and tests). Then the chat asks before the code area. PR 2 (code) is stacked on PR 1 while PR 1 is open. small-change makes one PR.
• A big feature request gets a plan first: user_stories/PLAN.md, many Stories, one test file for each Story, and one Prompt tests line for each Story. status shows Stories: N of M pass.
• Agents run the tests. A fresh subagent that did not write the code verifies it. pdd does not run tests or merge. Show the gate, then judge the person's later reply in any chat. Never approve a question, change request or earlier message. No exact phrase is needed. Record actual approval with the safe commands below. pdd records nonblank words without grading them; blank input is refused. Only explicit approve calls advance gates. Chat, steps and done never do. If a selected prompt changes, show the gate again. Terminal y/N covers the gate and its drafts once. Workflow strict mode comes from the main checkout (sourceRoot), outside the run worktree; standalone approval uses the current checkout's Git root. "strict_approvals": true in that root's pdd.json requires a person terminal. Never edit approval fields or decide expected values. See approval commands. Agents use pdd workflow done and pdd workflow ask.
• Main agents merge only on an explicit person request. Follow RUNBOOK §2.