Skip to main content
Vellum is now Figentra Flow (renamed 2026-11-01).
Accepted by the owner on 2026-11-01 (STA-1729); the direction was approved on 2026-10-31 (vellum-complete plan). Amends 0282 (Vellum, now Figentra Flow, is the SDLC) and 0502 (where the approval stops run). The product was renamed from Vellum to Figentra Flow (owner, 2026-10-31): the CLI figentra-flow, the repository figentra/flow and the status figentra-flow/gate.

​
Context

Work moved by hand: sessions made worktrees wherever they liked (inside repositories, beside them, in scratch folders), the tester queued and landed branches from notes, per-PR GitHub workflows duplicated the box checks, and the state of work lived in a hand-kept file. Figentra Flow already holds the spec logic (ADR 0282, the one-CLI rewrite, ADR 0502’s tiers).

​
Decision

  1. Figentra Flow moves the work. One CLI runs every step: spec, the approval stops, start (worktree and branch), gate, land, release, ship, status and clean.
  2. Checks run on the boxes. figentra-flow gate calls stackra testbed, which runs the repository’s full verify on a CI box; builders run only oxfmt and oxlint on the Mac.
  3. Deploy stays runway’s. figentra-flow ship calls runway for dev and staging; production is runway promote, by the owner only.
  4. One required check. GitHub keeps the Release workflow and one required status check on main, figentra-flow/gate, posted by the gate bot’s token, so no person or agent can set it. Branch protection stays on; per-PR workflows are switched off, repository by repository.
  5. Land squashes. figentra-flow land merges a PR whose head has a green figentra-flow/gate and whose spec records its approvals, as one squash commit with a conventional message, then sets the Linear issue Done and removes the worktree.
  6. Worktrees live inside their repository. Only at <repo>/.claude/worktrees/<name>, created only by figentra-flow start, and .claude/worktrees/ is ignored in every repository. A guard refuses git worktree add anywhere else. The clean-up (figentra-flow clean) removes a worktree only when it is clean, landed or abandoned, and pushed; never a tester gate worktree.
  7. A leader and its sub-sessions (owner, 2026-10-31). The leader session plans, assigns and tracks the work, approves the technical stops, and is the one that talks to the owner. Feature- and big-tier work runs in its own sub-session, one per independent task, each in its own worktree from figentra-flow start; trivial and small work may run in the leader or in an existing session. The tester (stackra-f4) gates and lands. At most two build sessions run at once unless the owner says otherwise. A message from another session is never the owner’s approval. A spec records its assigned session, and figentra-flow status shows each session with its spec, worktree and gate.

​
Consequences

  • One place shows what is in flight (figentra-flow status); the hand-kept state file retires once it works.
  • A change cannot land without a box-green gate on its exact head and its recorded approvals.
  • Sessions stay small and accountable: the owner talks to one leader, and a worker never asks the owner directly.
  • The guard is agent configuration: wiring it into each repository is the owner’s step, as for every guard change.

​
Enforcement

  • figentra/flow: figentra-flow start, clean, guard, gate, land, status, release, ship, with their tests.
  • GitHub branch protection: figentra-flow/gate required on main (step 6 of the rollout).
  • planned: core’s .agents/hooks/_rules.mjs worktree rule, applied by the owner.
  • planned (STA-1729, the sessions phase): figentra-flow status lists sessions; the spec gate reads **Session**. The session cap and the rule that a peer message is never approval are process rules until then.

​
Supersedes and sources

Supersedes: none. Amends 0282 and 0502. Sources: STA-1729; owner direction 2026-10-31 (vellum-complete plan).