From product brief to tested API in an afternoon.

Specwright reads your product brief, writes the OpenAPI spec, the handlers and the contract tests, then opens a pull request your team reviews like any other.

Start a spec
briefs/partial-refunds.md Hanne, Payments 13:00

Partial refunds for marketplace sellers

Hanne LindqvistProduct lead, Payments at Tillwood

Problem. Sellers can only refund a whole order. When one item of three arrives cracked, they refund all of it or open a ticket that support handles by hand.

Rules

  1. Refund any amount up to what is left on the payment.
  2. Item refunds restock the item unless the seller opts out.
  3. Our marketplace fee comes back pro rata; the card fee does not.
  4. A retry with the same Idempotency-Key returns the first result.
  5. No refunds later than 180 days after capture.
A seller in a plant-filled studio checks an order list beside packed cardboard boxes
Ines Duarte runs Moss & Clay on Tillwood. One of her terrariums cracked in transit last week.
api/refunds.openapi.yaml Valid OpenAPI 3.1 13:40
src/refunds/create-refund.ts Types check 14:30

Brief rules in code

1Up to what is leftline 25

2Restock unless opted outline 35

3Fee back pro rataline 28

4Retry returns first resultline 16

5180 day windowline 19

test/contract/refunds.contract.ts Run 3 of 3 15:20

0/48

Contract tests runningFixed since run 2: fee rounding, UTC window.

tillwood/seller-api pull/2214 Review 16:30

Partial refunds for marketplace sellers #2214

Approved

Specwright wants to merge 6 commits from spec/partial-refunds. 6 files, +412 and -18 lines. Linked to the brief.

  • Contract tests: 48 passed4.1 s
  • Spec diff: 1 new path, nothing breaking0.6 s
  • Types and lint9.8 s

Jonas Becker on line 28
Does proRata round half-even? The ledger does.

Specwright replied
Yes. The test fees: rounds half-even covers it.

Jonas approved these changes16:30

Two engineers point at code on a laptop screen
Amir and Theo walked the diff with Jonas before he approved.
deploys/seller-api Production 18:00

Rolling outDone before dinner.

  1. Jonas merges #2214 into main.
  2. Canary on 5% of sellers. No errors, p95 at 182 ms.
  3. Half of all sellers can refund part of an order.
  4. All 3,400 sellers. Ines refunds the cracked terrarium, and the buyer gets a notification.
  5. Hanne posts the changelog to the seller forum.

Brief to production in 4 hours 52 minutes. One afternoon.

Drag the dial, scroll on it, or use Left and Right.

How an afternoon goes

Three plain steps. You write the first one, Specwright does the middle, and your team approves the last.

An open grid notebook beside a laptop on a white desk
Grace and Amir sketch the refund states before lunch. A photo of the board goes into the brief, and Specwright reads it too.
  1. 13:00

    Write the brief you would write anyway.

    The problem, the rules, the edge cases and what is out of scope. Paste it from your doc tool or write it here. When a rule is vague, Specwright asks before it writes a line.

  2. 13:40 to 16:10

    Specwright writes the contract first.

    The OpenAPI spec, then handlers in your stack, then contract tests that call the real handlers. It copies your lint rules, error format and folder layout.

  3. 16:30

    Your team reviews a normal pull request.

    The brief is linked, each rule points to the line that enforces it, and Specwright answers review comments. It never merges on its own.

Priced by the afternoon

One spec is one afternoon: the spec, the handlers, the contract tests and the pull request. Seats are free on every plan.

Trial

£0

3 afternoons, then decide.

  • 1 repository
  • TypeScript handlers
  • Contract tests in Vitest
  • Pull requests on GitHub
Start a spec

TeamMost teams start here

£480a month

40 afternoons a month.

  • Unlimited repositories
  • TypeScript, Go and Kotlin
  • Answers review comments in the pull request
  • GitHub and GitLab
  • Brief templates for your team
Start a spec

Company

£24ka year

Every afternoon you have.

  • Runs in your own cloud account
  • SSO, SCIM and an audit log
  • EU or US data residency
  • A named engineer for the first month
Ask about Company

What the payments team asked

Jonas reviews every pull request that touches money. These were his questions before the first one.

Does Specwright merge anything on its own?

No. It opens a pull request, answers review comments and pushes fixes to that branch. Merging stays with your team and your branch rules.

Which stacks does it write?

TypeScript with Hono, Express or Fastify; Go with chi or net/http; Kotlin with Ktor or Spring. It reads your repository first and copies its conventions, from error format to folder layout.

What happens to the API we already have?

Specwright adds new paths or a versioned change. Anything breaking shows up in the spec diff before a single handler is written, and your existing contract tests run on every change.

Where does our code go?

On Company it runs in your own cloud account. On Trial and Team, code is processed in the region you pick, kept for 30 days and never used to train models.

What if the brief is vague?

It asks before it writes. This afternoon it asked Hanne whether the card fee comes back. She said no, and that answer is now in the spec and in a test.

Is one afternoon realistic?

For one endpoint with clear rules, it was, for our teams. Bigger features split into several specs, each with its own pull request and its own afternoon.

Write the brief after lunch.

Review a tested pull request before dinner. Your first three afternoons are free, and seats are free on every plan.

Start a spec