Skip to main content
Spec-Driven Development. One legacy module → three commands you run in order. You drive and validate at every gate; agents do the heavy reading and writing. When that sequence is done, the module is shipped.

​
The three commands

/port-domain

Co-build the module’s domain/ (fields + business rules) from the legacy + your product calls. Interactive.

/port-routes

A drafter writes routes.md (the build contract); you edit it. Draft + review.

/port-build

Autonomously builds every route + its tests from routes.md. A Workflow.
Utilities: /qa (typecheck · lint · test · build) and /audit-module (conformity check).

​
High-level pipeline

⛔ GATE = you stop and validate. Anything ambiguous → the agent asks you (multiple-choice), never guesses.

​
FLOW 1 — /port-domain (interactive, pair)

Build the domain/ — the source of truth for the module. There is no intermediate spec file; the implemented domain is the spec.
1

Analyze (delegated, read-only)

legacy-analyst reads the legacy module; in parallel the new Prisma model is mapped.
2

⛔ GATE 1 — design review

A real design review (not a rubber-stamp): for every questionable point, keep vs change — fields, code-enums, scoping, soft-delete, operations. Driven by multiple-choice questions.
3

Implement (fields first)

Prisma schema (if needed) → @db/fields/<entity> → domain/. /qa until green.
4

⛔ GATE 2 — validate the domain

Facade shape, errors, code-enums, scoping. Iterate on your feedback.
Out: domain/ code (green). Next: /port-routes.

​
FLOW 2 — /port-routes (draft + you edit)

Produce routes.md — the contract the autonomous build consumes.
1

Draft

routes-drafter reads the legacy routes + the built domain and fills one block per operation: maps each route to an archetype, fills 12 fixed keys (method/path · scope · auth · input · output · domain calls · audit · errors · tests …).
2

Mark, never guess

Anything ambiguous → [NEEDS CLARIFICATION: …]. Anything that doesn’t fit an archetype (custom auth, aggregation, async, mobile) → build: human + a reason.
3

⛔ GATE — you edit the contract

You add/remove/rename ops, adjust I/O, and resolve every [NEEDS CLARIFICATION].
After /port-build, the code is the source of truth — routes.md is the one-time contract, never re-generated from. (Avoids the “spec drifts from code” trap.)
Out: routes.md. Next: /port-build.

​
FLOW 3 — /port-build (autonomous Workflow)

Reads routes.md and builds every build: auto route. This is where the conditional branching lives. What each route-builder reads (so it never invents): the archetype ref + the shape exemplar (template) + the auth exemplar (user) + the constitution + the domain facade + @db/fields. It writes only its own folder and the tests first. Out: routes + tests wired, QA green. Next: the few build: human routes, in pair.

​
Branching & side-effects — the rules

⛔ Human gates

GATE 1 (design) · GATE 2 (domain) · contract gate · final report. You never get skipped.

[NEEDS CLARIFICATION]

Hard stop. The build refuses any route that still has one. Zero guessing.

build: human

Off-archetype routes (custom auth, aggregation, async, mobile) → done in pair, not auto.

verify FAIL → retry → build:human

Bounded retries; if still failing, auto-flag build: human and continue — one bad route never blocks the batch.

Idempotent

A folder that already exists is skipped — /port-build is safely re-runnable.

No worktrees · serial wiring

Each route writes its own folder (no conflict). Shared files (routes/index, module index, app.ts, action-keys, messages) are touched only by the integrator, in series.
Integration tests run exactly once, by the orchestrator, after wiring — never concurrently (the global setup recreates the per-worker DBs; two runs destroy each other). Build agents write tests, never run them.

​
Conventions baked in

​
The cast

Skills (knowledge)

CONSTITUTION · porting-system · routes-spec · code-enum · route-tests · api-conventions / api-routes / api-parse-query / api-module-anatomy / api-layers / adapter-and-facade · legacy-api

Agents (workers)

legacy-analyst (read legacy) · routes-drafter (draft routes.md) · route-builder (1 builder + 7 archetype refs) · route-verifier (enforce coverage) · integrator (wire, serial) · module-auditor (final gate) · qa-runner

References (templates)

routes.template.md · 7 archetype guides · exemplar-registry · domain-review-checklist

Shared helpers (built)

codeEnum (@kit/fields) · rsFixture / boFixture / rs-auth (@tests/helpers)