# For teams

Source: https://flow-next.dev/guides/for-teams/

Try Flow-Next on one team change. Product reviews intent, engineering shapes the approach, and reviewers follow the PR evidence. Keep your existing board.

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

```mermaid
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`](https://flow-next.dev/skills/flow/), which applies that rule and stops at the next decision that is theirs; `flow --explain` prints the route without running it.

Optional [chart](https://flow-next.dev/skills/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](https://flow-next.dev/guides/writing-specs/#additional-role-passes)). 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](https://flow-next.dev/guides/writing-specs/#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`](https://flow-next.dev/skills/visual/) - 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`](https://flow-next.dev/skills/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](https://flow-next.dev/skills/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

```bash
/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](https://flow-next.dev/skills/refine/#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:

```bash
/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`](https://flow-next.dev/skills/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](https://flow-next.dev/integrations/tracker-sync/) 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:

```bash
# 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](https://flow-next.dev/reference/spec-schema/#spec-and-task-ids) for the id model and [Tracker Sync](https://flow-next.dev/integrations/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.

```bash
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](https://flow-next.dev/flowctl/cli-reference/#specs-across-branches).

### 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](https://flow-next.dev/guides/for-teams/#one-planning-repo-for-several-code-repos)) |

### 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`.

  ```bash
  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](https://flow-next.dev/integrations/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.

```bash
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](https://flow-next.dev/integrations/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](https://flow-next.dev/skills/flow/#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`](https://flow-next.dev/skills/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](https://flow-next.dev/autonomy/land/#chains-and-stacks) |
| 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](https://flow-next.dev/skills/make-pr/#dependent-specs-chains-and-stacks) and [land](https://flow-next.dev/autonomy/land/#chains-and-stacks).

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](https://flow-next.dev/guides/writing-specs/#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](https://flow-next.dev/reference/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](https://flow-next.dev/guides/writing-specs/#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](https://flow-next.dev/integrations/tracker-sync/) for two-way Linear, GitHub, GitLab, or Jira projection