For teams

Flow-Next maps agentic work to concrete handovers so teams can review each stage independently.

Try it on one team change

Choose one repository and one change the team already understands. Keep the normal board, reviewers, and merge policy.

Person	What they open	What they do
Product owner	The spec in the repository, tracker mirror, a /flow-next:visual digest, or an HTML page you ask the agent for	Review the goal, acceptance criteria, and non-goals
Engineer	The same spec	Add constraints, check the approach, and start the implementation
Implementing agent	The spec and the repository	Build and verify the change; leave evidence
Reviewer	The pull request	Follow acceptance coverage, inspect the important changes, and check the evidence

At the end, ask whether the spec surfaced a missed decision, whether review found useful defects, and whether the PR reduced investigation work. Use that result to decide what to keep for the next change.

In the field

Flow-Next is the framework at the heart of the engineering methodology used across the portfolio of one of the largest private-equity funds: 1,000+ developers, 100+ product owners and product managers, and 30+ QA engineers onboarded. Teams running that methodology report a 3x speed-up on average across the entire R&D organisation, from discovery to merged code, at a higher quality of output.

The estates it runs on: CAD and construction software, proptech, education. Modern monorepos and hundred-repo microservice estates beside a thirty-year-old legacy stack that was migrated on these rails. GitHub Enterprise, GitLab, Jira.

An hour-long structured discovery interview reliably produces 8 to 11 implementation-ready specs with numbered acceptance criteria, boundaries, and task breakdowns, so the edge cases surface in the interview instead of the sprint.

Windows is a first-class target, because the field runs Windows: CI covers Linux, macOS and Windows on every push, and the path, shell, and encoding handling is tested there rather than assumed.

Lifecycle

flowchart LR
  Idea["Idea, or 'what next?'"] --> Flow["flow<br/>routes from the shared matrix"]
  Flow --> Capture["capture or refine"]
  Flow -.->|"optional when unclear"| Chart["chart"]
  Chart -.-> Capture
  Capture -->|"one owner builds it:<br/>the usual case"| Work
  Capture -.->|"different people build parts,<br/>or staged PRs"| Plan["plan"]
  Plan --> Work["work"]
  Work --> Impl["impl-review"]
  Impl -->|"planned tasks"| Completion["spec-completion-review"]
  Impl -.->|"single task, SHIP covers every R-ID,<br/>completion review skipped(policy)"| QAGate
  Completion --> QAGate{"pipeline.qa"}
  QAGate -.->|"on, or auto with UI criteria<br/>+ drivable surface + startable target"| QA["qa (live-app)"]
  QAGate -->|"off, or auto with any absent:<br/>skipped(reason)"| PR["make-pr"]
  QA -.-> PR
  PR --> Handover(["PR<br/>flow stops here"])
  Handover -.->|"a later flow run<br/>on the open PR"| Feedback["offers land once:<br/>resolve-pr, CI fixes, re-review"]
  Feedback -.->|"your consent,<br/>or --until=merge"| Merge["merge"]

Most team specs go straight from capture to work --no-plan. One owner, usually an engineer driving an agent, builds the whole spec, and it gets the same reviews, evidence, and PR as a planned one. Having several people on the team doesn’t make a spec a plan candidate. Plan earns its place when different people will build parts of the same spec, when delivery is staged over several PRs, or when someone asks for one. A team member who is unsure what to run next hands the item to /flow-next:flow, which applies that rule and stops at the next decision that is theirs; flow --explain prints the route without running it.

Optional chart is pre-capture discovery for one oversized unclear idea. Attended decisions (prototype, interview) need a human - unattended drivers stop at NEEDS_HUMAN rather than inventing answers. Parallel chart work is one invocation per open unattended D-ID, never a batch claim.

Roles

• Product owner fills the business layer (and attends chart interview/prototype decisions when discovery is open).
• Tech lead fills technical constraints and validates the approach (and the plan, when there is one).
• Implementing agent builds the spec, or its tasks when there is a plan.
• Reviewer reads the PR briefing before the diff.
• Maintainer audits memory and decisions after merge.
• Platform/DevOps and Quality add their requirements to the same spec - standing scaffold sections plus a focused refine (interview) pass with --scope=<role>, with their own append-only R-IDs (how). Every role’s criteria flow through the same coverage table and review gates.

Role map

Role	Owns	Flow-Next surface
PO / PM	User problem, success criteria, non-goals; chart attended routes	/flow-next:chart (optional), /flow-next:refine --biz
Tech lead	Architecture, constraints, plan shape	/flow-next:refine --tech, /flow-next:plan-review
Implementer	Focused task execution and evidence	/flow-next:work fn-N
Reviewer	Risk, quality, merge confidence	/flow-next:impl-review, /flow-next:qa, /flow-next:make-pr
Maintainer	Memory, strategy, changelog, docs	/flow-next:audit, docs updates
Platform / DevOps	Deployment topology, IAM, cost, observability requirements	Standing SPEC.md sections + a focused refine (interview) pass with --scope=<role> (Additional role passes)
Quality / QA	Test environments, regression surface, release-gate criteria	Standing SPEC.md sections + /flow-next:refine --scope=qa; /flow-next:qa against the live app

One person can hold multiple roles. The point is to make which hat is active visible.

Visual aids by role

Every handover above has a visual surface matched to the reader’s time budget - the register is the choice, the content is the same grounded state:

Moment	Reader	Surface
Post-plan sign-off	PO / tech lead	/flow-next:visual fn-N - one screen: task tree, planned file layout, R-ID coverage. Approve the shape without reading seven task files.
Plan review	Tech lead	The same digest before /flow-next:plan-review - spot the wrong task boundary first, then let the cross-model review argue the details.
Pre-review orientation	Reviewer	/flow-next:visual main..HEAD - where the diff lands and what structure changed, before opening the real diff.
PR review	Reviewer	The make-pr briefing - review steps in reading order with the must-read files, requirement coverage, and a verification checklist that ticks only what passed.
Business / decision review	Stakeholder	Ask the agent for an HTML page of the spec or the plan, for readers who never open a terminal.
Standup / sync	Anyone	Ad-hoc: “show me” in conversation restates the current topic in the same shape vocabulary.

The digest is deliberately shareable: plain fenced markdown pastes intact into a PR comment, a tracker issue, or chat, and renders identically everywhere. A PO who scans the coverage line and asks “why is R5 uncovered?” is doing exactly the review the pipeline wants - at one-screen cost instead of spec-archaeology cost.

Recommended team workflow

/flow-next:capture
/flow-next:refine fn-1 --biz                     # only when a product decision is open
/flow-next:refine fn-1 --tech --strategy --docs  # only when a technical decision the code cannot settle is open
/flow-next:plan-review fn-1       # optional: design risk; reviews the spec before any tasks exist
/flow-next:work fn-1 --no-plan    # one owner builds the whole spec; the configured reviews run inside work
/flow-next:qa fn-1                # optional: live-app QA against a deploy (needs a driver)
/flow-next:make-pr fn-1

/flow-next:flow fn-1 picks the same route for you, and it routes to refine when it can name an open decision that would change what gets built (when to refine), or when you ask for the interview. Refine is one question pass that asks only those decisions, so a clear spec can finish a session with no questions. The scope only focuses it. The --biz session can be run by a product person with engineering present, the --tech session by an engineer who knows the codebase, each in their own session. The read-back before writing names every section a session changed, so each person sees any change outside their layer. Reviews should use a different model or review backend from the one doing the writing when possible.

For business analysts and product owners

You own the business layer; engineering adds the technical layer after you.

1. Start from what you have. Describe the change to /flow-next:flow, or paste your requirements document (or point flow at its file) and flow captures it as a spec. To work through the document before it becomes a spec, run /flow-next:refine <path> --biz on the file, then /flow-next:capture.
2. Ask for the business interview: /flow-next:flow fn-1 --biz, or say “I’m the product owner, interview me on fn-1”. Flow runs refine with the business lens, even on a spec already marked ready, and leaves data, contracts, interfaces and security to engineering.
3. Answer “not my call” to anything that belongs to engineering. It is recorded as an open question for them.
4. Send the spec link to the tech lead, who runs /flow-next:refine fn-1 --tech.

When different people will build parts of the same spec, or delivery is staged over several PRs, plan it first so the work splits into tasks:

/flow-next:plan fn-1
/flow-next:plan-review fn-1
/flow-next:work fn-1              # task by task; the configured reviews run inside work
/flow-next:make-pr fn-1

Product coordination

Flow-Next works best when product does not hand agents vague tickets. Product should give the spec enough shape that engineering can validate it:

• target user or operational actor
• observable behavior
• acceptance criteria
• non-goals
• risks or compliance constraints
• rollout expectations

Engineering then adds:

• architecture boundaries
• data and API contracts
• migration and compatibility notes
• test evidence
• known risky files

The shared artifact is still one spec. Product and engineering are editing different layers of the same thing.

For POs and PMs who would never open .flow/specs/*.md, run /flow-next:visual on the spec, or ask the agent for an HTML page of it when you want one. The markdown stays the record.

Optional tracker bridge

Teams that already live in Linear, GitHub Issues, GitLab, or Jira do not have to leave the tracker behind. The optional tracker bridge projects a spec onto a tracker issue and reconciles body, status, and comments two-way - so stakeholders keep their board while engineering drives the spec.

The bridge is projection, not coordination: the spec stays the single source of truth, and the tracker is a co-editable mirror that never drives flow state or spawns agents. It is off by default and stays off until the discovery ceremony confirms a destination. Once active, lifecycle skills compose semantic content and call the deterministic flowctl tracker sync facade; teams do not maintain provider API recipes in workflow prose.

It opens a second entry flow for product:

# Tracker-first: a PO files a vague issue WOR-17 in Linear; engineering pulls it in.
flowctl spec create --tracker-first --tracker-identifier WOR-17 --tracker-id <issue-id> --tracker-url <issue-url>
/flow-next:refine wor-17 --biz
/flow-next:work wor-17 --no-plan
/flow-next:make-pr wor-17

The spec is referenced by its tracker key (wor-17) throughout, and every lifecycle stage syncs status and comments back to the board once the bridge is hooked up (on by default, opt-out per event). See Spec & task ids for the id model and Tracker Sync for the lifecycle touchpoints.

Specs across branches

A spec is a file in .flow/specs/, so it lives on whichever branch it was committed to. That keeps the spec reviewable in a pull request and lets it change together with the code, but a spec on a teammate’s branch is invisible from yours until it is pushed and you fetch. flowctl specs --refs lists specs across your local branches and remote-tracking refs, and plan’s spec scout reads it, so a new plan sees overlapping work on other branches.

flowctl specs --refs            # offline: the refs you already have
flowctl specs --refs --fetch    # prune-fetch origin first

A branch’s copy is live when merging that branch would change the spec, and stale when it carries nothing new: an older copy, an already-merged copy, or a spec since deleted on main. A live copy whose merge would conflict is flagged, with the date of the branch’s last commit. Details: CLI reference.

Pick one shape per team

Shape	Where the spec starts	Edits during the build	Fits
Spec travels with code	the feature branch	the same branch, merged with the code	long-lived feature branches
Spec-as-PR first	a spec-only PR merged to main	the implementation branch	specs reviewed before any code
Separate spec repo	a planning repo	the planning repo	product-heavy teams, many code repos (below)

Hygiene that keeps the index honest

• Push to be visible. A spec on an unpushed branch exists only for you. Push the branch once the spec is worth discussing.

• Fetch to see others. Use --fetch, or your usual git fetch --prune, before you capture or plan.

• Delete merged branches. Old branches keep old copies of specs. Turn on the forge setting (GitHub: Automatically delete head branches; GitLab: Delete source branch) and prune local branches whose upstream is gone. The index lists those under local_branches_upstream_gone.

  git fetch --prune
  git branch -vv | grep ': gone]'

  A conflicting live copy on a branch whose pull request merged long ago is a cleanup hint, not a collision: delete the branch.

• Let the tracker be the board for people. With tracker sync on, every spec appears as an issue whatever branch it lives on, so product and stakeholders follow the work without thinking about branches. The spec file stays the source of truth.

Spec ids when several people create work

Two people - or two agents, or two worktrees - who create specs at the same time can both land on the same bare fn-N. That is structural, not unlucky: native allocation used to see only the local working tree, so parallel creates from the same base both took max+1. Allocation now also scans every registered git worktree and every ref, which closes most same-repo races. Separate clones that have not fetched each other can still collide.

A repeated number is cosmetic. The id is the full slug (fn-12-login-flow), so nothing is overwritten, and a bare flowctl show fn-12 refuses as ambiguous and names both specs; use the slug.

Unambiguous short keys when you have a tracker: mint new specs from the tracker issue key so the tracker is the distributed allocator.

flowctl config set tracker.specIds tracker

New specs become wor-17-slug (Linear/Jira), gh-123-slug (GitHub #123), or gl-N-slug (GitLab project-scoped iid) instead of racing on fn-N. Existing fn-* specs stay as they are - ids never change, and mixed stores are permanent and fine. /flow-next:setup asks once when a tracker is configured and the key is still unset. Full model: Tracker Sync.

One planning repo for several code repos

Estates with many code repos often keep their specs in a separate planning repo: a home base or brain repo that holds .flow/ and a map of the code repos it owns. That layout works as it is, and the route stays the same as in a single repo. Capture the story once, where it belongs, and go straight to work.

A few habits keep it fast:

• Capture once per owner. A story gets captured in the planning repo that owns the code it changes. When it crosses owners, capture can split it into one spec per owner, with the dependency between them written down. That split is already the decomposition, so each owner spec normally goes to work --no-plan without a plan run on top. Capturing the same story again at every level of a repo hierarchy repeats capture, and usually plan, without adding anything the first capture didn’t know.
• End custom wrappers at flow. Filing rules (which planning repo owns what, naming, tracker fields) fit well in a wrapper skill or the instruction file. Once the wrapper has placed the spec, hand it to /flow-next:flow <spec-id>. Flow applies the no-plan default and records the route. A wrapper that always ends in /flow-next:plan sends every story down the slowest path. For real design risk, run /flow-next:plan-review, which reviews a spec that has no tasks yet.
• Put the code repos’ checks in the planning repo’s instruction file. Work marks a task done when the checks it can run are green. If the planning repo’s AGENTS.md doesn’t say how to run each code repo’s tests (the end-to-end suite included) and where to read CI results, “done” only covers what the agent could see, and the rest turns up after the push. Anything a person does by hand to get a build going, like pinning repo versions or moving a ticket, needs a line there too.

Who owns what

Flow-Next does not replace team ownership. It makes ownership explicit.

Humans own product intent, scope decisions, risk tolerance, merge decisions, and production responsibility. Agents take first passes at codebase search, draft specs, task decomposition, implementation, initial review, and PR comment resolution. Reviewers read the handover object first, then the diff - the PR body gives the reading order, the must-read files, acceptance coverage, what was verified, tradeoffs, and open items.

Give agents enough access to inspect, edit, test, and document the work, and keep destructive actions explicit:

Permission area	Default stance
Read repo files	Allow
Edit scoped project files	Allow during /flow-next:work
Run tests and linters	Allow
Install new dependencies	Require human review
Push branches	Allow only when requested by team convention
Merge PRs	Human-owned; a chain of dependent PRs merges from the bottom layer up, from GitHub’s stack UI or through land
Delete state or reset git	Require explicit human approval

The exact policy depends on the host harness; the ownership model should be the same across Claude Code, Codex, Droid, Grok Build, Cursor, OpenCode, and Muse Code.

Spec-level dependencies chain, they do not wait. A spec whose parent (depends_on_epics) has every task done and its branch on origin builds as a chain: its branch forks from the parent’s tip and its PR targets the parent’s branch, so a reviewer sees only that layer’s diff; on GitHub the PR is also linked into the parent’s stack. Chains are linear (one open parent, one child at a time), and a parent reworked after the child branched may leave the child needing a rebase, which land handles for the merge case. Details: make-pr and land.

For production teams, make the gates explicit as policy: plan review before implementation on risky specs, implementation review before the PR, completion review before closing the spec, a human approval before merge, and a changelog or docs update when behavior changes.

Tighten review for sensitive work: authentication and authorization, billing and entitlements, migrations and data deletion, public APIs and config formats, plugin install and update behavior, and autonomous execution hooks. For these, prefer spec-as-PR and require a human to review the spec before /flow-next:work starts.

Delegate, review, own

Phase	Delegate	Review	Own
Spec	Agent drafts from conversation	PO reviews meaning	PO owns outcome
Plan	Agent maps to codebase	Tech lead reviews feasibility	Tech lead owns approach
Build	Agent builds the spec inline, or workers build its tasks	Review backend checks diff	Engineer owns quality
PR	Agent writes the PR briefing	Human reads focused diff	Maintainer owns merge

Agents can do first passes. Humans still own judgment.

Standing criteria

Teams accumulate acceptance criteria no single spec owns: “every route change regenerates the API contract”, “user-facing strings live in the i18n catalog”. Put them in .flow/criteria.md, one line-anchored bullet per criterion (- **G1:** <criterion prose>), and spec completion review judges each one against the whole implementation. Completion review runs on multi-task specs; a single-task spec skips it once its review reached SHIP, so run /flow-next:spec-completion-review <spec-id> yourself when you want the criteria judged there.

Three properties matter for a team: the spec is the unit of compliance (completion review is the sole surface and records met / violated / n/a per criterion in the ordinary receipt), the file is user content that goes through the same PR review as code, and absence costs nothing. Grammar, receipt contract, and CLI: Standing criteria.

Evaluate the handovers

Product and engineering should each judge the trial from the work they receive. Product needs a spec whose meaning they can verify. Engineering needs constraints and task boundaries that help implementation. Reviewers need evidence and a useful path through the diff.

Keep the stages that earn their time. A team can add tracker sync for stakeholders, a second review pass for a migration, or an unattended loop for ready work without adopting every stage on every change.

Adoption ladder

• Week 1: one shared spec, implementation, review, and a PR the team evaluates together
• Month 1: repeat on more changes and add tracker sync or QA where the team needs them
• Quarter 1: add spec-as-PR, decision records, and an autonomous loop for mechanical specs
• When the team must live in a tracker: turn on the optional tracker bridge for two-way Linear, GitHub, GitLab, or Jira projection