Skip to content
Hands-on Coding Assistants

Part 1 — Start from a Repository Chapter 4

The Spec-First Workflow

In this chapter

The spec-first workflow

In the previous chapter, you sent 42 as the name in a registration request. The service returned 201, turned the number into the string "42", and stored it. Your repository map records what the code does today. Now you have a request to change that behavior. “Fix registration validation” leaves you with decisions about which inputs the endpoint should accept, what it should return when it rejects one, and what a rejection should do to the next registration.

A spec, short for specification, records the outcome you want from a change. It gives a reader the reason for the change, the behavior they can expect, and the limits of the work. Its acceptance criteria are conditions you can check before accepting the change. For an HTTP endpoint, a useful criterion tells you the starting state, which request to send, what response to expect, and what should happen to stored data.

Take the blank task title from the exploration chapter. “Validate task titles” leaves several decisions open. The one below is precise enough to run and check. It uses a behavior that already exists in the lab so you can compare each sentence with an actual request or test.

# Reject a blank task title

## Goal

Keep tasks with blank titles out of the task list.

## Scope

Use the existing POST /tasks endpoint and its error response format.

## Acceptance criteria

- On a fresh server, sending POST /tasks with {"title":" "} returns
  HTTP 400 and {"error":"invalid_task"}.
- A subsequent GET /tasks still returns only the seeded task.

## Verification

Run `node --test --test-name-pattern='a blank task title' test/app.test.ts`.
The test checks the error response and the list returned after the request.

The second criterion matters because the first one only checks the response. A handler could return 400 after adding the task. Reading the list gives you a way to catch that mistake from outside the handler.

Spec-driven development means writing and reviewing the intended behavior before implementation, then using that spec to guide the work. The spec tells you what result to check. The plan comes next and explains how to get there in this codebase. During implementation, the acceptance criteria tell you what to verify in the tests and the diff. If a review exposes a missing decision, settle it in the spec while the work is still small enough to change.

Prepare the registration exercise

You need the OpenCode setup and the repository map from the previous chapter. Start with a clean working tree in your lab fork. Bring the map over from read-task-api, or use the name you gave that branch.

git switch -c validate-registrations lab-start
mkdir -p notes
git show read-task-api:notes/repo-map.md > notes/repo-map.md
npm test

The three starter tests should pass. Read your map and the POST /registrations handler in src/app.ts. The starter requires a JSON object, converts the supplied fields to strings, and adds a registration to its in-memory list before responding. Use that description as the starting point for this request from the team that owns the signup form.

Accept a name and email as text. Trim surrounding whitespace, store the email in lowercase, and reject blank, missing, or malformed fields. Cap names at 100 characters. Keep the current success response and the service’s error format. The check should cover a simple email address shape. Email delivery, domain verification, and authentication are outside this change.

The form’s request tells you what the team wants. Your spec turns that request into something another engineer can implement and check.

Write the first draft by hand

Open your editor and write notes/registration-spec.md yourself. Use your map, the handler, and the request above. OpenCode comes in once you have a draft for it to review. Leave the lab’s reference spec and contract tests for the comparison after review.

Give the document a title and use the four headings from the task-title example. Work through them in order.

  1. Goal. Write one or two sentences about what a caller should gain. Start with the number that became "42" in the starter and explain why the signup form needs a clear rejection.
  2. Scope. Name the route and the fields it accepts. Record what callers can continue to rely on, including the id, name, and email keys in the success response. State the boundaries from the request.
  3. Acceptance criteria. Start with a valid request containing spaces and uppercase letters in the email. Write the response you expect after normalizing it. Then write criteria for a numeric name, a missing field, a blank name, a name at the length limit, and an email with the wrong shape. For each, give a concrete input, the HTTP status, and enough of the response or resulting state to check the outcome.
  4. Verification. Name the checks you would run. Use the HTTP tests in test/app.test.ts as a model for how to send a request and assert the result. Record which criteria you can verify with one request and which need a follow-up.

To start one criterion, write down the exact request you already know. Sending {"name":42,"email":"ada@example.test"} to POST /registrations should return 400 with {"error":"invalid_registration"}. For the success case, try {"name":" Ada Example ","email":" Ada@Dev.Example.test "} and work out what each field in the response should contain. If you need to interpret a phrase such as “simple email address shape,” write down your interpretation and an example. Keep questions you still need to settle in a short Open questions section.

Commit the draft while it still reflects your own decisions. The next commit will show what changed after review.

git add notes/repo-map.md notes/registration-spec.md
git diff --cached --check
git diff --cached --stat
git commit -m "Draft the registration spec"

Review the spec before planning

Run opencode from the root of your lab fork. Start a fresh session with /new if one is already open, then select Plan with /agents. Give the agent your saved draft and the current handler.

Read only notes/registration-spec.md and src/app.ts for this review.
Compare my draft with the POST /registrations handler. For each finding,
quote the criterion and give a request or request sequence that exposes
the gap. Point out any decision I still need to make. Return the review
in chat and leave the files as they are.

Read the findings against the request from the team. For example, a reviewer might point out that a handler could allocate an ID before rejecting a numeric name. A test that checks only for 400 would pass. You can close the gap with a criterion that a caller can verify on one fresh server.

Send a registration with a numeric name, then send a valid registration. The first request returns 400 with {"error":"invalid_registration"}. The second returns 201 with ID "1".

If your draft already covers that sequence, look for a different gap. Check whether it says when the name length is measured and whether it gives examples on both sides of the limit. Use the review to improve your file by hand. For every suggested change you keep, make sure you can name the request that demonstrates it.

Now open specs/registration-validation.md and contracts/registration.test.ts. These are the lab’s reference behavior and acceptance tests. Compare the decisions in your draft with the agreed rules. Check the name length after trimming, the email shape and normalization, both response shapes, and the effect of a rejected request on the next ID. Bring your spec into agreement with the reference and resolve the open questions that affect implementation.

git diff -- notes/registration-spec.md
git add notes/registration-spec.md
git diff --cached --check
git commit -m "Refine registration criteria after review"

Run both checks against the starter. The baseline should pass, and the two registration acceptance tests should fail. The first still gets the original spaces and email case. The second sees a blank name accepted with 201, so it stops before reaching the ID assertion. These failures give you two concrete results to compare after the change.

npm test
npm run test:registration

Read the plan before requesting a patch

Use Plan again with the revised spec. Have it explain how the requirements map to the handler and the existing checks.

Read the latest notes/registration-spec.md, contracts/registration.test.ts,
and src/app.ts. Propose a plan for POST /registrations. Map the acceptance
criteria to the checks that cover them. Show where you would validate and
normalize input, where an invalid request returns, and when a valid
request gets its ID. Return the plan for review.

Check the proposed order. The handler should check the types before calling string operations and apply the length and address rules to the normalized values. Rejections should return before the route assigns an ID or stores a registration. If the plan gives a different answer from your spec, resolve the difference before switching to Build.

Implement and review

Switch to Build in the same session so it has the plan you reviewed.

Implement the reviewed plan using notes/registration-spec.md. Change
src/app.ts and leave the supplied acceptance tests unchanged. Run
npm test and npm run test:registration as separate shell commands.
Report the observed result of each run.

Check the tool results and run the same commands yourself. Then inspect the patch.

git status --short
git diff --check
git diff -- src/app.ts
npm test
npm run test:registration

Expect both suites to pass, with three starter tests and two registration tests. Review the rejection path and the success path against your spec. Follow an invalid request to its return and check whether it can reach ID allocation. Follow the normalized values into the stored registration and the returned JSON. If a test fails, use its input and expected response to narrow the review to the relevant criterion.

When the patch matches the spec and only the intended file changed, commit it. The branch now contains the first draft, the revision after review, and the implementation you checked against it.

git add src/app.ts
git commit -m "Validate registrations before changing state"

Implement the task lookup with OpenCode

For a second exercise, start a separate branch from lab-start. A client needs to fetch a single task using GET /tasks/:id. Write the first spec in notes/task-lookup.md and ask Plan to review it. If your only success example fetches the seeded task at /tasks/1, a hard-coded response could satisfy it. Add a case that creates a task, takes the ID from the response, and fetches that task. Specify 404 with {"error":"not_found"} for an unknown ID and check that the list stays the same after each lookup. Keep the scope to literal IDs used by the service.

Review the revised spec, ask Plan how to implement it, then use Build and run npm test. Save your work on that branch so the next exercise can start from its named tag.

Carry the workflow forward

In the next chapter, a regression breaks the ID criterion even though both requests return the expected status. You’ll use a separate fixture to reproduce that gap and turn the same two requests into a focused regression test.

References