Build with PDD | Prompt Driven Hackathon Participant Field Guide

01 / Choose your route

Start in sixty seconds

Both routes use a GitHub issue as the durable task record and produce a reviewable pull request.

A

Best when

Your team wants shared, issue-based progress

You need GitHub access, the installed PDD App, and available PDD Cloud credits.

Install the GitHub App

01
Install the App
Configure it on the hackathon repository.
02
Write one issue
State the goal and observable acceptance criteria.
03
Apply pdd-generate
Generate the architecture and prompt scaffolding first.
04
Review the generated foundation
Confirm the architecture reflects the issue before implementation.
05
Apply pdd-issue
Follow live progress and answer questions on the issue.
06
Review the linked PR
Require green tests and run the final checkup gate.

B

Best when

Your team wants local control and terminal visibility

You need PDD, GitHub CLI, and one supported agentic CLI.

Terminal

uv tool install pdd-cli
pdd setup
pdd auth login
gh auth login

pdd change https://github.com/OWNER/REPO/issues/123

02 / How PDD works

Move the source of truth up one level

Preserve the specification and constraints that make regeneration reliable, not every manual implementation edit.

01

Define

State intended behavior in an issue or module prompt.

02

Constrain

Add interfaces, MUST and MUST NOT rules, examples, and tests.

03

Generate

Let PDD create or update the conventional code artifact.

04

Verify

Run tests, negative cases, and normal project checks.

05

Review

Confirm that prompt, code, tests, and docs agree.

06

Back-propagate

Record new intent in the prompt before completion.

Generated code is an artifact. Prompts, acceptance criteria, and tests are the durable source.

03 / Before you build

Establish a clean starting point

Ten minutes of preflight keeps access, credential, and baseline failures from consuming build time.

Participant preflight

Ready to start

Clone, branch, push, and open a PR Identify install, run, and test commands Run the baseline test command once Confirm required environment variables are documented Write one issue with one demonstrable outcome Choose the GitHub App or CLI route

0 / 6 complete

A practical rhythm

Start

Prove the baseline

Pick one visible outcome and record the initial test result.

First run

Answer quickly

Leave live progress, a branch, and initial tests.

Midpoint

Exercise the real path

Reduce scope and preserve a working vertical slice.

Final hour

Stop expanding

Run the full ladder and rehearse the exact demo.

04 / GitHub App workflow

The issue is your control surface

Labels choose the workflow, issue comments steer it, and the resulting pull request is the review artifact.

Foundation loop

Turn the issue into prompt-owned source

Inspect and refine the generated source before handing work to an execution label.

flowchart LR
  A["1. Define
PRD issue"] --> B["2. APPLY
pdd-generate"]
  B --> C["3. Inspect
architecture.json"]
  C --> D["4. Inspect
prompt scaffolding"]
  D --> E{"Foundation
ready?"}
  E -- "Refine" --> F["Tighten issue,
architecture, or prompts"]
  F --> C
  E -- "Ready" --> G["5. Choose one
execution label"]
  classDef command fill:#0A0A23,color:#FFFFFF,stroke:#00D8FF,stroke-width:2px
  classDef review fill:#F5F7FA,color:#0A0A23,stroke:#00D8FF,stroke-width:1px
  classDef decision fill:#FFC43D,color:#0A0A23,stroke:#0A0A23,stroke-width:2px
  class B,G command
  class C,D,F review
  class E decision

flowchart TD
  A["1. Define PRD issue"] --> B["2. APPLY pdd-generate"]
  B --> C["3. Inspect architecture.json"]
  C --> D["4. Inspect prompt scaffolding"]
  D --> E{"Foundation ready?"}
  E -- "Refine" --> F["Tighten issue, architecture, or prompts"]
  F --> C
  E -- "Ready" --> G["5. Choose one execution label"]
  classDef command fill:#0A0A23,color:#FFFFFF,stroke:#00D8FF,stroke-width:2px
  classDef review fill:#F5F7FA,color:#0A0A23,stroke:#00D8FF,stroke-width:1px
  classDef decision fill:#FFC43D,color:#0A0A23,stroke:#0A0A23,stroke-width:2px
  class B,G command
  class C,D,F review
  class E decision

Generation exit: proceed only when the architecture and prompts describe the intended behavior, constraints, and validation. Re-run pdd-generate only when the foundation itself must be rebuilt.

Command order

Choose the lane that matches the work

Apply one primary workflow label at a time.

New foundation

pdd-generateReview sourcepdd-issueor pdd-changeVerifypdd-checkup

Feature change

pdd-changeReview PRpdd-sync / pdd-test as neededVerifypdd-checkup

Bug repair

pdd-bugConfirm failing testpdd-fixVerifypdd-checkup

pdd-checkup is the final linked-PR gate. Use pdd-checkup-nofix only when you want findings without automated repair.

Recommended run

1
Create one issue for one demonstrable outcome.
2
Include criteria, forbidden outcomes, evidence, and validation.
3
Apply pdd-generate to create architecture.json, configuration, and prompt scaffolding.
4
Inspect the generated source. Refine the issue, architecture, or prompts until the foundation is ready.
5
Choose one execution label: pdd-issue for autonomous solving, pdd-change for a scoped feature, or pdd-bug to reproduce a defect.
6
For bugs, confirm the failing regression before applying pdd-fix. Use pdd-sync or pdd-test only where needed.
7
Review the PR, run the validation ladder, then apply pdd-checkup.

Hosted commands

Purpose and next action

Command	Use it for	Then
`pdd-generate`	New PRD foundation	Review architecture and prompts
`pdd-issue`	End-to-end autonomous solving	Follow progress and review the PR
`pdd-change`	Scoped feature or behavior change	Review the PR; sync or test if needed
`pdd-bug`	Reproduce and analyze a defect	Validate the regression, then fix
`pdd-fix`	Repair a reproduced defect	Run tests and inspect the repair
`pdd-test`	Generate UI or E2E tests	Run and review the generated tests
`pdd-sync`	Reconcile source and artifacts	Verify the synchronized diff
`pdd-connect`	Start an interactive hosted session	Choose the next workflow explicitly
`pdd-checkup`	Final linked-PR gate with repair	Merge only on a clean verdict
`pdd-checkup-nofix`	Report-only PR review	Resolve findings, then run the gate

Run controls and advanced labels

/pdd settingsInspect run, spend, effective budget, and strength.

/pdd budget 30Set a USD budget cap for a standard command run.

/pdd stopStop active work and remove the trigger when appropriate.

/pdd continue codexSwitch provider and resume a waiting run.

/pdd note textLeave a note that PDD ignores for steering.

/pdd checkup --pr PR_URLSelect the exact pull request for checkup.

pdd-decomposeSplit a large task before applying pdd-issue.

pdd-clean-restartRestart a supported execution workflow from clean state.

pdd-checkup-promptRun the final gate for prompt-focused work.

pdd-checkup-prompt-nofixReport prompt-focused findings without repair.

05 / CLI workflow

Keep terminal visibility and local control

Run setup once, verify authentication, then use an issue URL as the durable workflow anchor.

One-time setup

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install pdd-cli
pdd --version
pdd setup
pdd auth login
gh auth login
gh auth status

Feature workflow

ISSUE=https://github.com/OWNER/REPO/issues/123
pdd change "$ISSUE"

Two-stage bug workflow

ISSUE=https://github.com/OWNER/REPO/issues/456
pdd bug "$ISSUE"
pdd fix --protect-tests "$ISSUE"

Final CLI gate

pdd checkup \
  --pr https://github.com/OWNER/REPO/pull/123 \
  --issue https://github.com/OWNER/REPO/issues/456 \
  --final-gate

06 / Write an effective issue

Define observable behavior

PDD can research implementation details. It should not have to invent a product decision.

Copyable GitHub issue template

## Goal
<One sentence describing the user-visible outcome.>

## Acceptance criteria
1. Given <starting state>, when <action>, then <observable result>.
2. <Required error, state change, output, API shape, or UI behavior.>
3. Existing <named behavior/test> still passes.

## Must not
- Must not expose secrets or personal data.
- Must not change <out-of-scope interface or behavior>.

## Evidence
- Reproduction steps, logs, screenshot, or failing test:
- Relevant files/routes/docs:
- Expected result:
- Actual result:

## Validation
- Install/build command:
- Targeted test command:
- Manual demo path:

## Done when
- Tests cover the positive case and important forbidden outcome.
- The issue, generated code, tests, and docs agree.
- The linked PR passes CI and PDD checkup.

Quality test

Before you start the run

Can a reviewer observe every acceptance criterion?
Are forbidden outcomes stated with MUST NOT?
Is the intended interface or output shape explicit?
Does the issue separate expected and actual behavior?
Are logs and screenshots redacted?
Is the task narrow enough for one coherent PR?

Weak

"Build team registration."

Stronger

"A signed-in participant can create one team, invite up to three members, and see the same membership after refresh."

07 / Verify and review

Treat output like compiler output

Inspect it, test it, and reject it when the source-to-artifact contract is not satisfied.

7

Final gate

Run PDD checkup against the linked issue and PR.

6

Manual demo

Execute the exact flow your team will present.

5

Regression

Run the normal suite and approved stories.

4

Integration

Exercise cross-module interfaces and persistence.

3

Negative behavior

Prove invalid paths and forbidden side effects.

2

Targeted behavior

Run tests for the changed development unit.

1

Static sanity

Format, lint, type-check, and build.

Pull request review

PR closes or clearly links the correct issue.
Every criterion maps to test or manual evidence.
Important MUST NOT behavior has a negative test.
Public interfaces and callers were reviewed.
Diff and logs contain no secrets or private data.

Do not accept alone

The code looks plausible.
The agent says the work is complete.
One happy-path test passes.
The PR exists but CI is failing.
A test was weakened to force a pass.

08 / Security, credentials, and cost

Move quickly without widening access

Hackathon speed does not justify leaked credentials or unbounded automation.

Keep secrets out

Never paste API keys, OAuth tokens, JWTs, private logs, or .env contents into issues, prompts, screenshots, or commits.

Redact evidence

Redact secrets before attaching execution logs or core dumps. Revoke anything that may have entered Git history.

Limit installation

Install the GitHub App only on repositories it needs. Use approved login flows, environment variables, or secret managers.

Bound spend

Use /pdd settings to inspect spend and /pdd budget N to bound a hosted command run.

09 / Troubleshooting

Start with the exact failure

Resolve the reported access, credential, credit, or state problem before retrying the workflow.

pdd: command not found

Open a new shell or add the uv tool bin directory to PATH, then run uv tool upgrade pdd-cli.

CLI says unauthenticated

Run pdd auth login, then verify with pdd auth status --verify.

CLI cannot read the issue

Run gh auth status and confirm that account has access to the repository.

App labels are missing

Confirm the App is installed on that repository, then check repository health in PDD Cloud.

The workflow asks a question

Answer on the issue, then rerun the same CLI command or follow the App's re-label instruction.

Wrong state keeps resuming

Use the CLI --clean-restart option or apply the pdd-clean-restart modifier with the command label.

Correct tests were weakened

Restore and review the tests, then run pdd fix --protect-tests ISSUE_URL.

CI fails after local success

Inspect the current PR head, environment differences, and CI logs before retrying PDD.

10 / Keep nearby

Participant cheat sheet

The shortest path from a defined issue to a reviewed pull request.

CLI feature

pdd change ISSUE_URL

CLI bug

pdd bug ISSUE_URL pdd fix --protect-tests ISSUE_URL

GitHub App

issue -> pdd-generate -> review -> pdd-issue -> PR ->
                pdd-checkup

Definition of done

Ship when all seven are true

Acceptance criteria are observable and satisfied.
Positive and important negative paths are tested.
The issue, code, tests, and docs agree.
No secrets or private data appear in the diff or logs.
Project tests and CI pass on the current PR head.
The exact demo flow works manually.
The linked PR passes PDD checkup.

When in doubt: improve the issue, add a test, rerun the workflow, and verify the result.