iteration-impl

name	iteration-impl
description	Implement an iteration on top of a /launch-light scaffold (or any minimal NestJS / Next.js project). Two modes auto-detected: API iteration (domain layer on Nest) and FRONTEND iteration (Next.js/Vite UI built from HTML/Figma/image mockups, consuming an existing API). Reads the problem statement, locks 2-4 ambiguities, runs a simplicity governor that aggressively cuts ceremony, AUTHORS RED tests on the load-bearing logic IN THE MAIN THREAD (not the agents — provenance matters), then fans the implementation build across 3-4 parallel subagents in one message. The RED tests are the verdict; agent "done" claims are not. Iteration-aware: detects existing state and runs deltas on v2+. Use when the user says "/iteration-impl", "build the iteration", "implement v1 / v2 / v3 of <feature>", "add the domain", "build the nextjs frontend", "implement the UI from <mockup>", or hands you a problem statement after /launch-light. Defaults skewed toward NO ceremony. Common typos handled: "/implement-impl", "/impl", "/iter-impl".
author	DevOtts
author_url	https://github.com/DevOtts

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 ", references to controllers/services	api
"build the nextjs frontend", "implement the UI", "consume the api", "from ", 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 <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)?"
• " 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 (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