# The implement-feature algorithm The algorithm takes a boolean flag, **`tddMode`**, and runs one of two variants — written out separately below so each reads top-to-bottom on its own: - **Algorithm 1 (`tddMode: true`)** — strict outside-in ATDD/TDD. Every test is written FIRST, executed, and observed RED before any production code exists; then the implementation is written and the same test observed GREEN. The acceptance test opens each slice by failing for the right reason. - **Algorithm 2 (`tddMode: false`)** — basic development. Tests are written in the same step as the feature code and only ever asserted green. The acceptance test is authored as the slice's specification but never observed red; it first runs at hand-off. Accepted trade: nothing proves any test *can* fail. What IS proven, at slice end once the UI exists, is that the acceptance DRIVER executes (dry-run): a wrong selector or broken Given step is fixed by the algorithm, not discovered by the user. The flag can be refined with **`tddModeOverrides`**, at two grains (a level's own key wins over its participant's key, which wins over the global flag — `resolveTestFirst` in types.ts): - **Per participant** (a client platform or `backend`): swaps every inner feature loop of that participant. Deliberately does NOT reach the acceptance level — outer discipline changes only when named explicitly. - **Per test level** (`-acceptance`, `-e2e`, `use-case-unit`, `event-handler-unit`): swaps exactly that loop. At the acceptance level the two disciplines are: test-first = red-check at slice open; tests-with-code = specification now, driver dry-run at slice end — each platform gets whichever its resolution says, in either variant. The verification loops (`domain-unit`, `repo-equivalence`, `-fake-vs-real-contract`) have NO override key: writing the test is itself the deliverable there, both modes are the same act. The canonical use: `tddMode: true` with `{ "mobile-app": false, "mobile-app-acceptance": false }` — strict test-first everywhere except the client whose test executions are expensive, including its per-slice acceptance red-check on the runner hardware. Both variants share the same skeleton (orient → slices → contract → fan-out → join → real API → smoke → pre-commit gates → commit → hand-off), integrate CONTINUOUSLY inside each slice — a CHECKPOINT commit (gated, pushed, pipeline not awaited) lands at every point the tree is green by construction: the freshly authored acceptance spec (marked @wip in its test titles, which the CI acceptance jobs exclude — the specification integrates on day zero without reddening the pipeline), the additive contract, the join barrier, and the wired real API — and follow these standing rules: - **Logging lives at the edges, never in the core.** Interactors and domain objects NEVER log — the application core stays pure. Logging happens in controllers, presenters, repositories and the other edges, and EVERY log line carries the x-request-id and x-visit-id tracing headers, so any request can be followed end to end across the layers. The ids are carried by the request-bound logger (or the request context), never hand-attached per log line — a hand-built `{ requestId, visitId }` object next to a logger that already binds them is duplication that drifts. - **Request-scoped values travel in one context object, required by the compiler.** Everything about the request being served — the tracing ids, the user's chosen language, the observed device locale — is built ONCE per request at the route layer into a RequestContext and injected through the use case to the presenter. No production default exists anywhere on that path: a call site that forgets the context is a COMPILE error, and a route whose mandatory headers are missing fails loudly (400 from the enforcement hook, or a throw naming the header), never silently as `unknown-request` in the default language. Tests pass an explicit `fakeRequestContext(overrides)` — a test double named `fake-*` like the other fakes, so a double that ever leaks into a real log identifies itself at a glance. The general form of this rule: cross-cutting inputs are REQUIRED-BY-COMPILER, never defaulted — when a batch rewrite adds such a parameter, the missed call sites surface as compile errors instead of sleeping bugs. - **User-facing strings live in co-located localization catalogs, never in code.** Every presenter and every UI component with user-facing text owns a `localization/` directory next to it holding a single data-only catalog (English as the reference; every other language carries exactly its keys, enforced by the type system; the required languages per module come from the global configuration). Presenters select the catalog by the request context's language; components read theirs through the client's catalog hook. A hardcoded user-facing string is a convention violation the reviewer reports. Each use case with user-facing messages carries one checklist item proving language selection works (resolve with a non-default language, assert the message equals that language's catalog entry — imported, never retyped). The repository's localization VERIFIER is a pre-commit gate: together with the whole-repo typecheck it runs after the suites and before every slice commit, so an incomplete catalog can never reach the trunk. - **Every backend call goes through the client's central API client.** The api-server makes four headers mandatory on every business request — the two tracing ids, the chosen language, and the observed locale — and each client stamps them in exactly ONE place (its central API client). Generated client code therefore never hand-rolls a fetch: a new endpoint is reached by extending the central client, which is what keeps the header contract unforgeable. - **Event-triggered work lives in `event-handlers/`, and a query owns its projection.** The backend has three use-case shapes. Request-driven use cases share one anatomy (Input/Output/Interactor/Presenter/UseCase/localization) and live under `commands/usecases/` or `queries/usecases/` in CQRS contexts, or a flat `usecases/` in contexts without the split. Work triggered by a domain event that serves NO request — a policy ("whenever X happens, do Y") or a notification — lives in the context's `event-handlers/` directory with its own anatomy: EventListener (an outbox Subscriber registered on the relay) + Handler (the reaction's logic, ignorant of outbox and payload parsing) + OutcomeRecorder (the event-side analog of a Presenter). It runs on the outbox worker, never in the request path, under at-least-once delivery — so a Handler is either idempotent or its non-idempotence is an accepted, documented trade. Third shape: a query use case whose read model is MAINTAINED as its own table, built from domain events. A query earns this hybrid shape for either of two reasons: the state exists only as an event history (a statement, an audit trail), or serving the read live off the write-side tables would be COMPLEX in the database — too many joins, a heavy projection — so a dedicated, denormalized read-model table is maintained instead. The hybrid keeps the read side at its top level and carries an `event-handler/` subdirectory holding that same three-file anatomy; `Projection.ts` at the top level is the seam between the halves — the interactor reads through it, and its write methods (insert for an append-only model, update for a maintained one) are reserved for the event handler. The presence of `event-handler/` inside a query use case is the marker that its read model is event-built; its absence means the query reads existing state directly, which is correct only while that read stays simple. - **Test state is created through the front door, never through backdoors.** Every test, at every layer, sets up its state through the system's NORMAL input ports: use-case tests execute the command use cases that create the state (resolved from a whole Application instance) and read back through query use cases; acceptance and e2e tests establish every Given by driving the real UI; and third-party processes the app owns (the database, the cache) are populated through the app itself — never by direct inserts, raw SQL, or fixture loading. Two reasons: a direct insert can fabricate a state the application can never produce, so the test proves behavior for a world that cannot exist; and when the real creation path changes, a backdoored test keeps passing while the app is broken. Backdoors are permitted ONLY where the logic under test requires them: the repo-equivalence tests drive repositories directly because the repository IS the unit under test, and the in-memory error seams (withError()) are deliberately built test controls, not backdoors. Everything else goes through the front door — a reviewer finding a test that bypasses the input ports reports it as a defect. - **Snapshots are a wire format, never a query API.** `snapshot()` exists so an aggregate can be REPRESENTED where a representation must leave the process: persisted by a repository, rendered by a presenter, sent down the wire. Production logic never reads a snapshot to make a decision — an interactor (or another domain object) peeking into a snapshot for a fact is business logic that belongs ON the aggregate as an intention-revealing method: tell the aggregate, don't ask for its insides. Tests are the one other sanctioned consumer: asserting an entity's resulting state through its snapshot is exactly what the representation is for. - **Error messages are asserted by identity, never by wording.** When a UI test verifies that an error (or any notice) is shown, it locates the message element by its shared selector id and asserts two things: the element is PRESENT, and its text is NON-EMPTY (a rendered-but- blank error element is a bug, not a pass). It never asserts the message's actual wording — that may change freely without breaking a single test: the words belong to the backend and the product, not to the test suite. This applies to every layer that drives a UI — client e2e tests, acceptance protocol drivers, smoke flows. - **Minimal code, always.** Every step writes and commits ONLY the code the current step needs: the minimum that makes the present test pass, the field the present scenario reads, the endpoint the present slice calls. Never code for an anticipated future — no speculative methods, parameters, endpoints, or error branches "we'll surely need." A new aggregate starts with exactly the methods the current move requires and grows move by move, each demanded by the outer loop's current step. What counts as "needed" is defined by the artifacts, not by judgment: the current checklist item, the slice's scenarios, the contract draft. If a later slice needs more, the later slice adds it. - **Budgets.** Every loop has a maximum number of iterations. When a budget runs out, the run STOPS AND FLAGS the situation to the user — it never spins forever and never papers over the problem. Budgets are phase-accurate (a TDD item's test REWRITES and its implementation FIXES are counted separately, so escalations name the actual problem) and route-aware (remote batched loops get a shorter per-item leash than local loops — expensive executions should escalate sooner, not burn runner time). - **Every run is resumable.** Finished slices are durable in git; the working tree carries intra-phase progress (checklists are rebuilt by inspecting what exists); and a JOURNAL records each slice's completed phases with their results. On restart: completed slices are skipped, the in-flight slice resumes after its last recorded phase — crucially, an already-observed red-check is never re-run against a half-built slice (which would wrongly report a violation), and the fan-out resumes against the recorded contract draft. - **Concrete exit conditions.** No loop exits on the working agent's own judgment that it is "done". Each checklist loop runs against an explicit CHECKLIST derived from the scenarios plus the mandated cases, and an INDEPENDENT REVIEWER must find no missing cases before the loop may close. - **All paths come from configuration.** The algorithm takes a REPO LAYOUT object naming where everything lives: the api-server and its bounded contexts, the database layer (in-memory, Postgres, equivalence tests), the OpenAPI specs per client, each client's package with its fake backend, real backend, API models, integration tests, e2e tests and selectors, the behavior package (features, DSLs, protocol drivers, acceptance tests per client), the smoke flows, and the infra entry points (local-development stacks, Taskfile, CI config, global configuration). No role hardcodes a path — which is what makes the algorithm portable across projects sharing the architecture. Alongside it sits a COMMAND CATALOG: the list of known commands (migration diff/apply/status, query-code generation, OpenAPI generation, whole suites AND single-test runners for the per-item cycles, quality gates — typecheck, lint, format — production builds, stack up/down, database REPL and data reset, emulator boot) that the tool may run. The algorithm never invents shell commands — it executes catalog entries, and a failed catalog command stops and flags rather than being improvised around. - **Models are tiered by difficulty.** Every leaf step is executed by Claude Code, but not on the same model: a MODEL ROSTER names a backend per tier — hard (Fable), intermediate (Opus), easy (Claude Code over a DeepSeek backend via a router) — and a MODEL POLICY maps each kind of work to a tier. Defaults: domain design, aggregate sizing, and the distillation review on the hard tier; use cases, tests, UI code, contract drafts, and reviews on the intermediate tier; repositories, the persistence ripple, controller wiring, and suite-output reading on the easy tier. Both roster and policy are configuration — swap models or re-tier a work kind without touching the algorithm. Alongside them sits a PROMPT CATALOG: one instruction text per work kind (test conventions, guardrails, minimal-code rules). For every model-performing step, the orchestrator resolves prompt + model into a WORK ORDER and passes it INTO the role call as its first argument — instructions are runtime values the step demonstrably received, not comments an implementation might ignore. The algorithm also takes as INPUT the path to an EXAMPLE PROJECT — a repository with the same architecture where every pattern already exists, done right — and every work order carries it. The prompts teach by example: they cite concrete exemplar files under an {example}/ placeholder (substituted by the orchestrator when it resolves the work order — the prompt reaches the step with absolute paths) — the deposit-money vertical is the reference slice, from acceptance spec and protocol driver through interactor, aggregate, repositories with error seams, SQL queries, and equivalence tests — and say "study these; produce the same shape". The example path is a REQUIRED input — the run fails without it. Working on the boilerplate itself, pass its own root; a client project passes its copy of the boilerplate. - **Every step gets the narrowest context that can do the job.** Sessions PULL context by reading files, and every read is re-sent on every later turn of that session — so scope is the main token lever. Each work kind carries a CONTEXT SCOPE (context-scope.ts, derived from the repo layout): the workplace directory, the paths the step needs, and guidance naming what is out of scope. The orchestrator resolves it into the work order and the leaf executor appends it to the session prompt. The scale, narrowest to broadest: suite-output reading and failure judgment get NO repository access (the output in the task is the input); domain unit tests get one object plus one exemplar test; the persistence ripple gets the slice's aggregates plus the db/ tree; repo equivalence gets the two implementations and their interface; controller wiring gets the routes and the resolver; each unit-building kind gets its unit's directory, its bounded context, core/, and the cited exemplar; each client kind gets that client's subtree (client-bound scopes narrow per platform once the role knows it); contract design gets the spec files; acceptance authoring gets the behavior package and selectors; and only the kinds that are broad by nature — slice planning and classification (directory listings, not deep reads), the bootstrap sweep, project identity — see the whole tree. Two limits hold: when the compiler points outside the scope, FOLLOWING it is correct (surveying is not), and the exemplar citations are never trimmed — they are the cheapest quality lever there is. - **Instructions travel.** The run-specific extra instructions (after guardrail filtering) are handed to every role at the start, not read once and dropped. - **Gherkin tags decide which clients a slice targets.** Scenario-level tags (`@web`, `@mobile`, `@feature-flags-admin` — the operator console is its own client) override feature-level tags; run instructions may only NARROW the result, never widen it; no tags at either level means ALL clients — and genuine ambiguity is a stop-and-flag, not a guess. Every per-client phase of a slice (acceptance red-check, client fan-out, client join suites, real-API wiring, mobile smoke) runs ONLY for the slice's targeted clients: a web-only slice never touches the mobile pipeline, a mobile-only slice never busies the web agent. - **Emulator-bound tests execute directly on the runner hardware — never through git.** Backend and browser-client tests run on the developer machine. Every test that needs an emulator — mobile acceptance, mobile Detox e2e, mobile smoke flows — is AUTHORED locally and EXECUTED remotely: the working tree is synced to the runner box and the corresponding CI job's own definition (same docker image, same script) runs there directly, with a warm emulator kept between runs and the full test output streamed back. No commit, no push, no pipeline entry — a deliberately-red run is just a command result. Git receives ONLY finished slices; each slice commit's real pipeline is the final arbiter (red there means environment drift → stop and flag). The mobile fake-vs-real contract tests are pure Node and stay local. One remote attempt is a DETERMINISTIC COMPOSITION of the command catalog's remote group — acquire the runner lock → pre-flight probe → sync the tree → ensure a warm device (one kill-and-boot recovery) → install dependencies → build the job's binary → run the job → fetch results → release the lock (always, per attempt: the warm device survives between attempts without holding the box against its real CI jobs). The vocabulary is farketari's own; what actually runs behind each command name is per-project configuration filled in at implementation time. Because a remote execution runs the whole suite, remote-tested clients work in BATCHES: author every pending item, then ONE suite run serves them all — per-item verdicts are read from its output, and already-covered tests re-run for free, so regressions surface immediately. Two suite runs per batch round replace two runs per item. (Batch test-first is marginally weaker than per-item test-first — tests in a batch are authored before each other's implementations exist — a negligible cost for independent e2e items.) - **Green work is preserved the moment it is green.** The fan-out lanes run for hours between barriers, and an uncommitted tree is one reset away from losing all of it. So every checklist item a lane proves green becomes a work-preservation commit scoped to THAT lane's paths (`git add -- `): a sibling lane's mid-TDD red state never rides along, which is exactly why these cannot be `git add -A`. They commit --no-verify under the mid-work "slice: —