flows

Files (10)

• README.md
• SKILL.md
• README.md · example/
• deps.ts · example/
• index.ts · example/
• kit.ts · example/
• reset-password.test.ts · example/
• service.ts · example/
• steps.ts · example/
• types.ts · example/

SKILL.md (first lines)

# Flows

A **flow** is one business operation written as a readable list of steps: the
authoritative statement of a business rule, in an order a reviewer can audit
in seconds. Flows exist because much of a modern codebase is written with
agent assistance, and the cheapest way to trust generated logic is to make it
readable rather than to run it.

A flow does no I/O itself. It receives its effects as a `deps` argument and
returns a `Result`, so the network boundary (a controller) stays the only
place that knows about transport, and unit tests need no database.

A complete worked example ships with this skill in `example/` — a
password-reset flow showing the folder layout, a branded value, the error
union, the controller mapping, and fake-deps tests. Read it before writing
your first flow. `example/kit.ts` is the entire shared runtime (~40 lines:
`Result`, `ok()`, `err()`, `BaseDeps`); copy it into your project as
`src/flows/kit/` once.

## The two rules

1. **A flow body contains calls and early returns only.** No loops, no nested
   conditionals, no inline logic, no `try`/`catch`. Logic a reviewer finds in
   a flow body belongs in a step. This is what keeps the body skimmable.
2. **A step takes `(deps, ctx)` and RETURNS its new data. A step never
   mutates `ctx`.** The flow accumulates results into the context it passes
   onward, so a later step that needs an earlier step's output cannot compile
   unless the earlier step ran. Step order is checked by the compiler, not by
   a comment.

Rule 2 is the point of the whole pattern. Where an invariant is security
relevant, brand the value that proves it so only the producing step can make
one (in the example: `VerifiedReset`, minted only by the token-check step).
An agent that reorders the steps then gets a type error instead of a
vulnerability.

## Flows own business logic; services own implementation

Flows decide WHAT may happen and in which order. Shared implementation —
crypto, DB reads/writes, outbound dials, provider integrations — stays in
your service layer and enters the flow as deps. Steps are thin wrappers: a
step that does more than call deps, translate errors, and shape data is
absorbing implementation that belongs in a service.

A multi-effect persist helper keeps its compensation IN the service: the
flow step wraps it thinly, and the atomicity/cleanup machinery stays testable
as implementation. Likewise a database transaction is ONE step wrapping one
service function — splitting transactional writes across steps would break
the atomicity the transaction exists to provide.

Business rules that DO belong in steps: precondition checks, policy
decisions (ceilings, subset checks, version pins), the ordering of effects,
and which failures map to which error variants.

**One business decision per step.** A step that strings together several
fallible dep calls is hiding steps: each decision the operation makes (load
the target, validate a selection, resolve a dependency, check a policy)
deserves its own body line, its own error arm, and its own diagram node.
Composite "resolve everything" steps defeat the body's purpose as the
auditable list.

When an operation genuinely branches:

- Arms that differ materially (different decisions, different error unions)
  become SEPARATE flows, with the controller dispatching on the wire shape it
  already parses.
- Arms that share their whole prefix and differ only in a short tail can be
  one flow with early SUCCESS returns per arm — each arm still a visible
  step and diagram node. Never hide an asymmetric arm's decisions inside a
  dispatch step.

## Layout

One folder per flow. Steps live beside the flow that uses them, so the whole
story is in one directory. No query logic moves into flow folders.

```
src/flows/<flow-name>/
  README.md         REQUIRED (see template below).
  index.ts          The flow body, and the folder's ONLY public exports:
                    the flow, its production deps builder, the error type,
                    and any input types the controller builds.
  steps.ts          One function per step, in call order. Steps are exported
                    only for index.ts's import — nothing outside the flow
                    folder imports a step, a helper called only within
                    steps.ts stays unexported, and tests drive the flow
                    through index.ts with fake deps.
  types.ts          Input, Output, the error union, any branded types.
  deps.ts           This flow's own Deps type + its production wiring.
  <flow-name>.test.ts   Unit tests with fake deps. No DB.
```

Anything else a flow needs is a plain module in the same folder (an
in-process rate budget, a pure normalizer). Flows never import each other's
types or steps; if two flows need the same helper, it is a service both wire
as a dep.

Name steps as business decisions (`grantRequestedPermissions`,
`consumeResetToken`), not as operations — operation names collide with the
service layer.

Avoid import cycles between the service layer and flows: when a service
entry point needs to CALL a flow (a thin public wrapper), put that entry in
its own module so imports stay one-directional
(entry → flow → implementation).

## Deps

Each flow declares its OWN `Deps` type, intersected with `BaseDeps`. Never
grow one shared `FlowDeps`: the per-flow type is the least-privilege list of
effects that flow may perform, and that list is part of what a reviewer
reads.

Type a pass-through dep as `typeof serviceFn` and wire it by reference.
Write a signature by hand only when the flow needs a NARROWER shape than the
service exposes (note why in one line: "Narrower than the service: …"). The
privilege boundary is the list of deps, not re-typed signatures —
re-declaring what the service already declares is scaffolding with no
reader.

From erikreppel/skills, MIT.

More from erikreppel/skills