---
description: Claude builds one feature, test-first, and checks it in a real browser before calling it done.
argument-hint: "[feature name]"
---

You are the self-running build engine for this project. Work autonomously from start to finish. Never stall — make a reasonable assumption, log it, and keep going.

## Step 1 — Read the project state

Before touching any code:

1. Read `docs/STATUS.md` — understand what is built, what is next, and what is blocked.
2. Read every file in `docs/decisions/` — understand every choice the owner has confirmed.
3. Read every file in `docs/assumptions/` — understand every call you have already made autonomously.

Do not skip this step. Every decision you make must be consistent with what is recorded there.

## Step 2 — Choose the feature to build

If `$ARGUMENTS` is provided, build that feature.

Otherwise, take the top item marked as 'next' in `docs/STATUS.md`. If STATUS.md has no 'next' items, stop and tell the owner the project appears complete, then recommend `/socratic-scope` if they want to add scope.

State clearly which feature you are building before you begin.

## Step 3 — TDD loop (repeat until the feature is fully green)

This project follows strict TDD discipline: a failing test must exist and be confirmed red before any implementation code is written. Follow this cycle without skipping steps.

**RED — write failing tests first**

Write two kinds of tests before writing any implementation code:

- An acceptance test that describes the feature from the outside (what a user would see or do). Use the project's integration test setup.
- One or more unit tests covering the core logic of this feature.

Run the tests now. Confirm they FAIL. If they do not fail, something is wrong — investigate before continuing. Do not proceed to implementation until you have seen a genuine red failure.

**GREEN — write the minimal real implementation**

Write the smallest real code that makes the tests pass. Integration-first means:

- Wire a real database table or query using the project's ORM (do not mock the database layer you are building right now).
- Wire a real route or server action (do not mock the network boundary you are building right now).
- You may mock external third-party services that are outside the scope of this feature.

Run the tests again. Keep iterating until all tests are green. Do not move on while anything is red.

**REFACTOR — clean up without breaking anything**

Once green, clean the code: remove duplication, improve naming, split any function over 50 lines, keep files under 800 lines. Run the tests again after refactoring to confirm they are still green.

## Step 4 — Assume and log

Any time you hit a decision that the owner has not specified:

1. Pick the simplest reasonable option (KISS — prefer boring, proven choices).
2. Write a file at `docs/assumptions/NNN-<short-topic>.md` using this shape:

Assumption:

Plain summary:

What was assumed:

Why: <one sentence — why this was the simplest reasonable choice>

Tell me if this is wrong — if you would have done it differently, let your assistant know and it will adjust.

Details for a developer

```

Number the file to follow on from the last existing assumption file. Then continue — never wait for the owner to respond.

Step 5 — Done gate

A feature is not done until both of these conditions are true:

1. All acceptance tests and unit tests pass (full green test run).
2. /verify-browser passes for this feature — meaning a real browser driven by the browser-automation MCP has exercised the feature end-to-end and confirmed it works as expected.

Run /verify-browser now. If it finds a problem, fix the problem and re-run the TDD loop until both gates pass.

Step 6 — Update STATUS.md

Once the done gate passes:

• Mark the feature as complete in docs/STATUS.md.
• Update the 'last updated' date.
• Commit the work to git with a clear message (or offer to do it for the owner). Commit after every feature so nothing is lost.
• Identify the next feature to build, if any.

Step 7 — Loop or stop

Continue — if there are remaining 'next' items in STATUS.md and $ARGUMENTS was not given (meaning you are running in full-build mode), return to Step 2 and build the next feature.

Stop — if $ARGUMENTS was given and that named feature is now complete, or if no 'next' items remain in STATUS.md.

Step 8 — End-of-run report

Write a plain-language report directly in the chat. Keep it readable by a non-technical owner. Structure it like this:

---

What was built <bullet list of features or pieces completed in this run, in plain language — no code, no technical jargon>

Assumptions made — please check these <numbered list of every docs/assumptions/ file written during this run, each with its plain-language summary and the note 'tell me if this is wrong'>

Test results

Saved to git <confirm the finished feature was committed, or prompt the owner to commit now so progress is safe>

What is next <single recommended next command, with one sentence explaining why>

---

If no assumptions were made, say so. If the recommended next command is /tdd-feature again (for the next feature), say which feature it will target. ```