> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackra.figentra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 0503 — Figentra Flow runs the development workflow

> Accepted · 2026-11-01

> [!NOTE]
>
> Vellum is now Figentra Flow (renamed 2026-11-01).

> [!NOTE]
>
> Accepted by the owner on 2026-11-01 (STA-1729); the direction was approved on 2026-10-31
> (`vellum-complete` plan). Amends
> [0282](https://docs.stackra.figentra.com/adr/0282-developer-experience-skills-cli-mcp-and-vellum-as-the-sdlc.md) (Vellum, now Figentra
> Flow, is the SDLC) and [0502](https://docs.stackra.figentra.com/adr/0502-spec-tiers-and-approval-stops.md) (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).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.