Spec-driven development

From agreed spec
to reviewed pull request.

Give agents more than a prompt. Turn intent into a grounded spec, a clear implementation plan, and code your team can review—with the reasoning still attached.

Book a demo

Explore the workflow

potpie/Waitlist feature

booking-platformmain

SPEC-028

SPEC-028 · Agreed direction

Waitlist for fully booked slots

Give people a place in line, and a clear way to claim a slot when it opens.

The requirement

When a slot opens, offer it to the first person in line with a claim link that expires in 30 minutes.

Decisions before development

PaymentOn claim, not on joining

Expired offerMove to the next person

ConcurrencyOnly one claim succeeds

Acceptance criteria

01Offer the slot in queue order.
02Reject a link after 30 minutes.
03Collect payment when claimed.
04Prevent a second booking.

Booking brief + repository context

SPEC-028 · Implementation plan

Turn the agreed spec into an executable plan.

Three ordered phases, with the files, dependencies, and checks attached to each task.

Phases03

Grounded in the approved spec

Phase 02Approved plan

Allow one successful claim per slot.

Offer the slot to the first person in line and validate the claim within a single transaction.

Depends onPhase 01 · Foundation

Files to change 2

src/waitlist/claim.tsUpdate

src/waitlist/offers.tsUpdate

Validation criteria 3

Claim link expires after 30 minutes
Payment is collected on claim
Concurrent requests cannot double-book

Selected phase: Claim flow

SPEC-028 · Code changes

Implementation follows the plan.

Review the diff with its requirement, implementation task, and validation in view.

src/waitlist/claim.ts+6

18 async function claimSlot(offerId: string) {19+  return db.$transaction(async (tx) => {20+    const offer = await lockOffer(tx, offerId);21+    assertNotExpired(offer, new Date());22+    await reserveAvailableSlot(tx, offer.slotId);23+    return markClaimed(tx, offer);24+  });25 }

Linked requirementAC-04 · Prevent double-booking

A slot is reserved within the same transaction as the claim.

VerificationConcurrent-claim test

Two requests. One claim succeeds; one is rejected.

SPEC-028 · Ready for review

A pull request with the why attached.

Bring the spec, code changes, and validation results into the team’s review.

Pull request preview

Add waitlist claims for fully booked slots

waitlist-claimsmain

Queue entries and time-limited offers
Payment collected when a slot is claimed
Atomic claims with regression tests

Human review required before merge

Validation against the spec

Passed

First-in-line offerAC-01 · queue.test.ts

Passed

30-minute expiryAC-02 · claim.test.ts

Passed

Payment on claimAC-03 · payment.test.ts

Passed

No double-bookingAC-04 · claim.test.ts

Showing plan view.

Agree on the what.
Make the how explicit.

A feature touches more than the file you’re editing. Business rules, existing services, edge cases, and dependencies all shape what needs to be built.

Potpie turns that context into an agreed spec and a reviewable plan. Agents carry out the work, validate it against the requirements, and bring the changes back to your team.

01Clarify
02Specify
03Plan
04Implement
05Review

Every step,
anchored to the spec.

Make the decisions explicit, give agents a plan, and keep your team in control of what ships.

Start with your code.
Not a blank slate.

Choose a repository and branch. Ground the work in the services, dependencies, and patterns you already have.

The right questions.
Before the first change.

Clarify business rules and technical tradeoffs with questions shaped by your code and the feature you want to build.

Turn intent into
an agreed specification.

Bring scope, decisions, constraints, and acceptance criteria into one grounded spec for your team and your agents.

A plan with the
implementation details.

Sequence the work into phases, with file changes, architectural dependencies, and validation for each task.

Agents build from
the plan you approved.

Potpie orchestrates code changes and checks, following the agreed plan and your codebase’s existing patterns.

Validated changes.
Your team’s final say.

Review the diff and create a pull request from the platform. Your team stays in control of approval and merge.

Decisions before code

A small question.
A different implementation.

Clarify the behavior before an agent has to guess. A business decision becomes an explicit requirement—and something the implementation can be checked against.

Potpie asks01 / Offer expiry

How long should the first person have to claim an open slot?

The existing booking flow holds a slot until its offer expires. Choose the window that fits your customers.

15 minutesMove the queue along sooner.30 minutesGive people time to respond.60 minutesAllow a longer decision window.

Try a different answer to see the requirement change.

waitlist.specSPEC-028

Your answer becomes part of the spec

A time-limited offer.

AC-02 · Offer expiry

The first person in line has 30 minutes to claim the slot. After that, the offer expires and the next person is notified.

And a check for the implementation

advanceClock(30 * MINUTE)

A claim at or after 30 minutes is rejected. The expired offer cannot create a booking.

Other decisions stay explicit

First in line · Pay on claim · One successful claim

The why travels with the code

Review the change.
Understand the reason.

A pull request shouldn’t make your team reconstruct the original conversation. Keep the requirement, the implementation task, and the validation connected.

From the first decision to the final diff, there’s a clear thread to follow.

Start with a shared specification Explore the context behind the code

SPEC-028 / AC-04Waitlist

One requirement, end to end

Only one person
can claim the slot.

01
Agreed in the spec
A second claim must not create another booking.
02
Planned and implemented
Reserve the slot atomically in claim.ts.
03
Checked before review
Two competing requests. One successful claim.

Spec + diff + checksReady for your review

Questions & answers

A little more context.

Do I need a finished spec to get started?

No. Choose a repository and branch, then describe the feature you want to build. Potpie uses that context to ask clarifying questions and shape a specification. You can also carry an agreed spec forward from collaborative spec creation.

What is in the implementation plan?

The plan breaks the spec into ordered phases and tasks. It identifies the files to change, architectural patterns to follow, dependencies between tasks, and the validation criteria for each step. Review and refine the plan before implementation starts.

How do agents work with our existing code?

Potpie grounds the spec and plan in the selected repository. Its agents use that context to follow existing patterns and make the planned changes. Your team can inspect the resulting diff and request changes before opening a pull request.

How is the implementation validated?

Agents run the checks called for by the plan, including tests tied to the spec’s acceptance criteria. The results are part of the review, not a replacement for it. Your team still evaluates the code, failed checks, and any remaining gaps before merging.

Does Potpie merge changes automatically?

The flow ends with a pull request for your team to review. Create it from the platform once you have reviewed the changes, then use your normal approval and merge process. Your team decides what ships.

From agreed spec
to reviewed pull request.

Waitlist for fully booked slots

Decisions before development

Acceptance criteria