new-feature

name	new-feature
description	The delivery loop for a feature in this repository — scope it from the issue and the code, build it, verify it yourself, then run the full agent fleet over the diff and open a PR. Use when starting a feature, taking a GitHub issue into work, implementing something that crosses layers, or when the work is finished and needs reviewing before it ships.

Delivering a feature

One loop, six steps, in order. The fleet in step 4 is not optional and not a judgement call — every agent in this repository exists because something got through without it.

Step 1 — Scope

Gather before writing anything.

• If there is an issue, read it whole: gh issue view <n>. The specs in this repository carry a "The decision this issue encodes" section — that is the part that binds. Deviating from it is a decision to state out loud, not a detail to quietly reinterpret.
• Read the code the change lands in, not just the code it calls. Trace one existing example of the same shape end to end: storage → service → api/mcp → frontend.
• Check the constraints in CLAUDE.md that the change touches — route registration, access control, the pure-Go/no-CGo build, the MCP tool contract.
• Ask the user only where two readings would produce materially different work. Everything else is a judgement call you make and state.

Done when you can name every layer the change touches and every file you expect to create.

Step 2 — Plan the work, and start the designer

Create tasks with TaskCreate, one per layer or per shippable slice, and keep them current as you go. A feature here reliably spans six or more files across four layers; the list is what keeps the last layer from being forgotten.

If the feature has any user-facing surface, dispatch ui-designer now, in the background, before you write a line of storage code. It convenes a UX/UI panel over the feature and returns a build-ready specification: screens, states, which components to reuse versus create, interaction rules, and any field the UI needs that the API does not yet return.

The point is the overlap — it designs while you build the backend, so the specification is waiting when you reach the frontend instead of being invented at the keyboard. Give it the issue number, the surface it covers, and the endpoints the feature will expose.

Read its data-contract gaps as soon as they arrive: a field the design needs and the API does not return is backend work, and you are still in the backend.

Step 3 — Build

Work bottom-up: migration and storage, then service, then API and MCP, then frontend, then docs. Each layer compiles and its tests pass before the next one starts.

Build the frontend from the designer's specification. Where you deviate from it, say which part and why — in the PR body, not silently.

• New migration: take the next free number in internal/storage/migrations/.
• New MCP tool: register it in internal/mcp/tools.go, optional fields are pointers, never return a Go error.
• New route: wrap for writes, wrapRead for reads.

Step 4 — Verify it yourself

Before any agent looks at it:

• make test — the whole suite, not the package you touched.
• npx nuxt typecheck in frontend/ when the frontend changed. Pre-existing errors are noise; filter to your own files.
• node frontend/scripts/css-consistency.mjs when the frontend changed. It fails on the two CSS mistakes that are invisible in a diff and obvious on screen: a page-height calc(100dvh - <number>), and a button whose height is left to emerge from its padding. If you added a control, also compute its height and the height of everything it will stand next to — a row of buttons that are 30, 30 and 26 pixels tall is a bug users see immediately and nobody writes down.
• Run it for real. The local-api-testing skill drives the live API; use it to exercise the new paths, the error codes, and — when there is a migration — an upgrade of a database that already holds data.
• Then stand it up for the user with the preview-feature skill: a fresh build, a throwaway database, one seeded research per branch of what you built, and a map of URLs. Anything with a visible surface gets this before the fleet runs — an agent reviewing a screen nobody has looked at reviews the code, not the product.

Report what you ran and what it said. A test you did not run is a test that failed.

Step 5 — Run the fleet

Dispatch every agent in the table below in one message so they run in parallel, each with: the branch, that changes are uncommitted, the issue number, the list of new and modified files, and the specific risks you already know about. A vague brief gets a vague review.

Agent	Reviews	Skip only when
code-reviewer	Correctness of the diff, across layers	never
access-auditor	Every read and write path for cross-user leaks	never
llms-docs	llms.txt and internal/docs/ against the code	never
readme-keeper	README.md — the page a person reads before running anything	nothing user-visible, no new entity, no route/flag/default changed
usability-reviewer	Whether the feature is workable end to end, and what it still cannot do	never
ux-tester	UI states, keyboard, focus, responsiveness, edge-case data	no frontend change
story-writer	Storybook stories for new and changed components	no component added or changed
component-curator	Duplication against the existing component library	no component added

ui-designer is not in this table — it runs in step 2, before the code exists. Reviewing a design after the UI is built is how a redesign gets scheduled.

The four conditional rows are skipped only when their subject genuinely is not in the diff, and the skip is stated in your report with the reason. Everything else runs on every feature.

Then: read every finding and act on it. Fix what is real. For anything you reject, say which finding and why — a dismissed finding that is never mentioned is indistinguishable from one you never read.

Agents that write (story-writer, llms-docs) change files. Re-run make test and the typecheck after the fleet lands.

Step 6 — Ship

Use the committing-and-creating-prs skill: branch, commit, push, PR. The PR body states what the feature does, what the fleet found, and what you decided not to do.

If the frontend changed, run make frontend-embed before committing so the embedded assets match the source.

What makes this loop fail

• Reviewing before verifying. An agent finding a bug your own test run would have caught is a wasted review cycle.
• A brief with no risks in it. You know where the change is thin; say so in the dispatch and the review lands there.
• Asking whether to run the fleet. It runs. This document is the answer.