iteration-impl

# iteration-impl Build the next iteration on top of a freshly-scaffolded (or in-progress) project. **Speed matters.** This skill exists because a 1-hour interview / take-home / spike doesn't get to spend 30 minutes on DI plumbing, validation pipes, state-management ceremony, or LangSmith wiring. It builds the thing that matters and narrates the scope cuts. **TDD-first is structural, not optional.** When load-bearing logic exists in the iteration, the RED tests are authored in the main thread *before* agents are dispatched. The agents implement against tests they did not write, and the test result — not the agent's "done" claim — is the verdict at hand-off. This is what makes delegated agentic work safe at speed: the test is the evidence, the agent's confidence is the claim, and the structure is arranged so the evidence wins. Two modes, auto-detected: - **API mode** — domain entities, endpoints, business logic on NestJS. The original use case. - **Frontend mode** — Next.js/Vite UI built from HTML/Figma/image mockups that consumes the existing API. Activated when the user says "frontend", "UI", "nextjs", or references a mockup folder. It also knows iterations stack — v1 today, v2 tomorrow, v3 when something breaks. Phase 0 detects state and runs deltas instead of rewrites when called repeatedly. ## When to use vs not to use | Use this | Don't | |---|---| | Build a domain iteration (entities + CRUD + the real business logic) on a Nest scaffold | Initial scaffold — use `/launch-light` first | | Build a frontend iteration (pages + components + API client) from a mockup | Pure Figma-to-design-system (use `/design` or `/ui-styling`) | | 1-hour interview / take-home / weekend spike | Production code with real validation + auth + persistence | | Clear scope, one iteration at a time | Big multi-feature delivery (use `/launch` with features tracker) | | Problem statement given as natural-language prose | Pure refactor of existing code (use Agent directly) | If the user wants Docker, Postgres, Redis, queues, real persistence → STOP and recommend `/launch-scratch-project` first. This skill assumes the JSON-file DB pattern (API mode) or Vite/Next proxy (frontend mode) is enough. ## Composition ``` /launch-light → /iteration-impl v1 (api) → /iteration-impl v2 (frontend from mockup) → ... bootstrap (60s) API domain implementation UI built on top, consuming the API ``` For infra-heavy projects swap `/launch-light` → `/launch-scratch-project`. The iteration-impl half doesn't change. ## Phase 0 — Detect mode and iteration Two things to detect before planning anything: **which mode** (api / frontend / fullstack) and **which iteration** (v1 / v2+). ### 0.1 Detect mode Look at what's already in the repo: ``` Glob: apps/api/**/*.controller.ts → API exists Glob: apps/web/**/* OR web/**/* → Frontend exists Glob: src/main.ts → Standalone NestJS (older layout, no workspace) ``` Then look at the user's prompt for signals: | User says | Mode | |---|---| | "build the domain", "add entities", "implement v1 of <feature>", references to controllers/services | **api** | | "build the nextjs frontend", "implement the UI", "consume the api", "from <mockup>", references to .html/.png/figma/docs/ui/ | **frontend** | | "build everything", "fullstack" | **fullstack** (api first, frontend after) | | Ambiguous AND no apps/api exists | **api** (build the backbone first) | | Ambiguous AND apps/api exists | Ask: "API iteration or frontend iteration?" | **If frontend mode, additionally scan for mockup sources:** ``` Glob: docs/**/mockup*/**/*.html Glob: docs/**/mockup*/**/*.png OR *.jpg OR *.svg Glob: docs/**/ui/**/* Glob: any path or URL the user provided ``` **The mockup is the spec.** If multiple HTML files exist in the mockup folder, list them in the plan and ask which is the source of truth when they disagree. Never paraphrase the mockup; agents read the files directly. ### 0.2 Detect iteration ``` Glob: apps/api/src/**/*.entity.ts # existing api entities Glob: apps/api/src/**/*.controller.ts # existing endpoints Glob: apps/api/src/**/*.spec.ts # existing tests Glob: apps/web/app/**/*.tsx # existing pages (Next App Router) Glob: apps/web/src/**/*.tsx # existing pages/components (Vite/older layout) Glob: db/*.json, apps/api/db/*.json # data files Glob: http/*.http # http examples ``` State up front: - **Greenfield**: "No prior iteration detected. Starting v1 in `<mode>` mode." - **Existing**: "Detected v<N> `<mode>`: entities=[…], endpoints=[…], pages=[…], tests=[N]. Are we (a) adding to it, (b) modifying flow, (c) cutting v<N+1> from scratch?" On v2+, the plan becomes a **delta** — what's added, what's changed, what's removed — not a full rebuild. The build phase still fans out to subagents, but each agent gets the relevant pre-existing files as context. ## Phase 1 — Plan (the most important phase) Three things to produce, in order: ### 1.1 Extract the scope From the user's problem statement, pull: **API mode:** - **Entities** (typically 2-5 for a 1-hour exercise) - **Endpoints** (HTTP verb + path + 1-line purpose) - **The load-bearing logic** — the matching, the workflow transition, the calculation, the rule, the validation predicate. Everything else is plumbing. - **State / status semantics** — what states do entities pass through, what triggers transitions **Frontend mode:** - **Screens / routes** — one per mockup file (e.g. `/<route>/page.tsx`) - **Components** — the discrete reusable pieces visible in the mockup (cards, badges, tables, forms) - **API surface to consume** — read `apps/api/src/**/*.controller.ts` to derive the exact endpoints and return shapes. Don't guess. - **The load-bearing client logic** — the user flow that makes the UI non-trivial: state transitions, optimistic-update + rollback, derived state, form validation rule, routing decision. Display-only screens have none; non-trivial UIs always have some. - **Design tokens** — colors, fonts, spacing from the mockup's design-system folder if present ### 1.2 Lock 2-4 forced-choice ambiguities Read the problem statement adversarially. Where is meaning underspecified? Forced-choice (a)/(b)/(c) is faster than open questions. The cost of one clarifying round-trip is much smaller than the cost of rebuilding after a misread. **API ambiguity examples (generic shapes — substitute your domain):** - "Status `<X>` means: (a) committed assignment, (b) waiting pool, (c) fallback when auto-pick fails — which?" - "Multiple candidates + empty hint → (a) random, (b) highest-ranked, (c) leave pending — which?" - "Persistence: in-memory only, or JSON file (survives restart but not concurrent writes)?" - "<Entity> created on (a) initial event, (b) confirmation event — which?" - "Boundary value (e.g. zero, empty, max): which side of the predicate?" **Frontend ambiguity examples:** - "Two mockups disagree on <element> (compact vs expanded) — which is canonical?" - "Route shape: (a) `/<resource>/:id`, (b) `/<parent>/<resource>/:id`, (c) flat — what's the URL design?" - "After a successful mutation, do we (a) optimistic-update the row, (b) refetch the record, (c) refetch the whole list?" - "Empty state: (a) blank, (b) illustration + helper text, (c) skeleton placeholders — which?" - "Polling vs manual refresh vs SSE — does the view auto-update or only on user action?" - "Mockup shows desktop only — do we ship mobile breakpoints in v1 or skip them?" ### 1.3 Run the simplicity governor Print the block matching the current mode. **Defaults skewed toward NO.** Each YES needs a one-sentence justification. **API mode — defaults are NO (except where noted):** ``` [ ] @nestjs/config → NO (use `import 'dotenv/config'` in main.ts) [ ] @Inject tokens / DbModule → NO (inline JsonCollection in service constructor) [ ] Validation pipes → NO (controller @Body() is `any` or a plain type) [ ] Multiple test suites → NO (one critical-path spec on the business logic) [X] RED-first tests on load-bearing logic → YES (authored in Phase 1.5, BEFORE agents dispatch) [ ] Observability (LangSmith) → NO unless asked; narrate as scope-cut in README [ ] "Just in case" optional fields → NO [ ] Generic Repository pattern → NO (services own JsonCollection directly) [ ] Nest Logger → NO (console.warn is fine) [ ] OpenAPI / Swagger → NO (the .http files document the API) [ ] Auth / RBAC → NO unless asked [ ] Concurrent-write safety → NO (JSON files, single-process — narrate the limit) ``` **Frontend mode — defaults are NO (except where noted):** ``` [ ] State library (Redux, Zustand, Jotai) → NO (useState + useReducer cover v1) [ ] Data-fetching library (TanStack Query) → NO unless 3+ refetch/cache scenarios actually justify it [ ] CSS framework (Tailwind) → NO unless already in package.json (plain CSS + CSS modules) [ ] UI kit (shadcn/ui, MUI, Chakra) → NO (build the components the mockup shows; reach later) [ ] Form library (react-hook-form, Formik) → NO (controlled inputs + useState are fine for <5 fields) [ ] Animation library (Framer Motion) → NO (CSS transitions cover v1) [ ] i18n library (next-intl, react-i18next) → NO unless multi-language is in scope [ ] Auth client → NO (assume API is internal in v1) [ ] Error boundary library → NO (one inline ErrorBoundary if needed) [ ] Mobile breakpoints → NO unless the mockup explicitly shows them [ ] Storybook → NO (the mockup is the visual spec) [ ] Backend CORS changes → NO (use Vite/Next proxy, same-origin in dev) [ ] E2E tests (Playwright, Cypress) → NO (manual click-through + the http/ files cover v1) [~] RED-first tests on load-bearing client logic → YES IF non-trivial client logic exists (state machine, optimistic updates, form validation rule, derived state); NO if the iteration is pure display ``` ### 1.4 Print plan, wait for green light Bundle scope, ambiguity questions, and simplicity decisions into one screen. End with: > Lock the ambiguities and confirm — `go` to start Phase 1.5 (RED tests) followed by the parallel build. `change X` to redirect. **Do not write code or tests until the user types `go` (or equivalent).** ## Phase 1.5 — Author RED tests (you, not the agents) **Non-skippable when load-bearing logic exists in this iteration.** Load-bearing = the part where being wrong matters: the rule, the workflow transition, the calculation, the validation predicate, the state-machine guard, the derived state. CRUD plumbing and display surfaces don't qualify; the business rule does. The agents are about to write the implementation in parallel. They will report "done" regardless of correctness. The test written here is the verdict that survives the agent's confidence. ### Three properties this phase must guarantee 1. **You wrote the test, not an agent.** The test encodes *your* intent from the locked plan, not an agent's interpretation of it. Provenance is what makes the boundary load-bearing. 2. **The test fails for the right reason BEFORE Phase 2 dispatches.** A test you've never seen fail proves nothing. Run it. See the failure. Confirm the failure message reflects the *absence of the behavior* (e.g. `function not defined`, `expected X got undefined`), not an unrelated wiring problem (`module not found because of a typo`). 3. **The test is hard to game.** A single input/output pair is gameable with `if (input === <case>) return <answer>`. Three varied inputs covering the same underlying rule, plus one shape/edge-case check, is roughly as expensive to game as it is to actually implement. ### Mechanics - Author 2-4 tests in the appropriate spec file for the load-bearing module — wherever the code under test will live (`apps/api/src/<area>/<feature>.spec.ts`, `apps/web/src/lib/<feature>.spec.ts`, etc.). - **Per behavior under test, prefer 3 varied inputs over 1 representative pair.** Vary along the dimensions of the rule, not along irrelevant axes. - Include at least **1 shape/property/edge-case test** the agent can't trivially memorize. Generic patterns: - "Result must always be a member of the closed set { … }" — catches any case the agent didn't enumerate - "Given empty / null / zero / max input, the function takes the spec-defined path rather than throwing" - "At a boundary value, the predicate returns the spec-defined side (inclusive vs exclusive)" - "Side effects (writes, external calls, mutations) happen at most once per invocation" - "Invariants hold across the state transition (e.g. ids preserved, monotonic counters not regressed)" - Run the file (`pnpm --filter api test <file>`, or scoped equivalent). Confirm RED with a failure message that matches the *absence of the behavior*. - State out loud: "Tests are RED for the right reason — dispatching agents now." ### Three-layer guardrail summary Option A (show tests in agent prompts) is the practical choice on a 1-hour clock. What makes it safe enough: | Layer | What it prevents | |---|---| | **Provenance** — you wrote the test, the agent didn't | The agent can't quietly weaken the contract during authoring | | **Tamper-detect** — Phase 3 checks `git diff` against the test files | The agent can't quietly weaken the contract during implementation | | **Multi-input gaming cost** — 3+ varied cases + 1 shape check per behavior | Gaming the test letter costs roughly as much as implementing the rule | None of the three is sufficient alone. All three together are good enough for the interview clock. ### Agent prompt addition (carried into Phase 2) Every agent prompt that touches the load-bearing module includes: ``` EXISTING TEST FILES (human-authored, READ-ONLY — do not modify or delete): - <absolute path to spec file 1> - <absolute path to spec file 2> - … Your job is to make these tests go GREEN by writing the implementation. You MAY add NEW spec files alongside them for your own confidence. You MAY NOT modify, delete, or weaken any of the human-authored files above. If `git diff` shows any of these files changed in your output, that is a HARD FAIL. Also: the tests are sample probes of correctness, not the full spec. Implement the underlying rule from the locked plan — do not hard-code per-test-case branches. ``` ## Phase 2 — Parallel build ONE message. 3-4 Agent calls in parallel. The plan from Phase 1 + the RED tests from Phase 1.5 are the shared context. Each agent gets the locked plan + simplicity decisions + their slice + the read-only test file paths + a "report back in under 150 words" constraint. ### API agent split (when mode = api) **Agent A — Data layer** - Entity types (`apps/api/src/<area>/<entity>.entity.ts`) - `JsonCollection<T>` if not already present in `apps/api/src/db/` - Seed file(s) at `apps/api/db/<entity>.json` (or root `db/`) with realistic test data - Optional `db/seed.ts` reset script **Agent B — Services + Controllers + HTTP examples** - One service per entity (CRUD via JsonCollection, in-constructor) - One controller per entity (`GET /`, `GET /:id`, `POST /`, `PATCH /:id`, `DELETE /:id`) - One `http/<entity>.http` file per entity with concrete example requests - **No DTOs, no validation pipes** — `@Body() body: any` or a plain TS type **Agent C — Load-bearing logic implementation (make the RED tests green)** - Implements the load-bearing module so the human-authored RED tests in Phase 1.5 pass - MAY write additional tests alongside the human ones for own confidence - MAY NOT modify or delete the human-authored test files (hard fail if it does) - Must implement the *rule* from the locked plan, not memorize the test cases - Mocks external dependencies (LLM clients, network); never hits live APIs from tests **Agent D — Wiring + docs** - Update `apps/api/src/app.module.ts` to register new controllers + services - `apps/api/package.json` scripts (e.g., `db:seed`) if seed script exists - `README.md` update: endpoint table, status semantics table, **and a "Scope cuts" section** narrating every NO from the simplicity governor ### Frontend agent split (when mode = frontend) **Agent A — Routing + layout shell** - Top-level routing — Next App Router `apps/web/app/<route>/page.tsx`, OR React Router routes for Vite - Layout shell (header, nav, footer) matching the mockup - Page skeletons for each mockup screen with placeholder content + correct route params - Theme/typography setup if the mockup has a design-system folder **Agent B — Components from mockup** - One component per discrete UI element in the mockup (cards, badges, tables, forms, modals) - Plain CSS or CSS modules — match the mockup's visual exactly - Inline TypeScript types - No state logic yet — just structural JSX + styles **Agent C — API client + load-bearing client logic (make the RED tests green if any)** - Typed fetch wrapper at `apps/web/lib/api.ts` (or `src/lib/api.ts`) mirroring the existing API controllers — **read the API source, don't guess return shapes** - Hooks/utilities for each endpoint - Wire the pages from Agent A to use the hooks/client