For teams

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

Lifecycle

flowchart LR
  Idea["Idea"] --> Capture["capture or interview"]
  Idea -.->|"optional when unclear"| Chart["chart"]
  Chart -.-> Capture
  Capture --> Plan["plan"]
  Plan --> Work["work"]
  Work --> Impl["impl-review"]
  Impl --> Completion["spec-completion-review"]
  Completion --> PR["make-pr"]
  Completion -.optional.-> QA["qa (live-app)"]
  QA -.-> PR
  PR --> Feedback["resolve-pr"]
  Feedback --> Merge["merge"]

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 plan.
• Implementing agent runs tasks.
• Reviewer reads PR cognitive aid before 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 interview pass, 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:interview --scope=business
Tech lead	Architecture, constraints, plan shape	/flow-next:interview --scope=technical, /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 interview pass (Additional role passes)
Quality / QA	Test environments, regression surface, release-gate criteria	Standing SPEC.md sections + a focused pass; /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 walkthrough body - R-ID coverage, risk-ranked review plan, and diff-fenced structural sketches where diagrams render worst.
Business / decision review	Stakeholder	The opt-in HTML render lenses - the full instrument, 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:interview fn-1 --scope=business
/flow-next:interview fn-1 --scope=technical --strategy --docs
/flow-next:plan-review fn-1
/flow-next:plan fn-1
/flow-next:work fn-1
/flow-next:impl-review fn-1
/flow-next:spec-completion-review fn-1
/flow-next:qa fn-1            # optional: live-app QA against a deploy (needs a driver)
/flow-next:make-pr fn-1

The business pass can be run by a product person with engineering present. The technical pass should be run by an engineer who knows the codebase. The plan and implementation reviews should use a different model or review backend from the one doing the writing when possible.

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 teams that opt into HTML artifact mode (2.0.0+), the spec also renders as a self-contained HTML page - a first-class review surface for POs and PMs who would never open .flow/specs/*.md, with optional in-browser annotation that flows back as edits to the markdown source of truth. Reviewers get the PR-side counterpart for diff review.

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
/flow-next:interview wor-17 --scope=business
/flow-next:plan wor-17
/flow-next:work wor-17
/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.

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.

Recommended team default 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.

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 points at acceptance coverage, critical changes, decisions, open items, and where to look.

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
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, and OpenCode.

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	Worker executes tasks	Review backend checks diff	Engineer owns quality
PR	Agent writes cognitive aid	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 the completion review already running on every spec judges each one against the whole implementation.

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.

The honest asymmetry

Adoption is not uniformly euphoric. The consistent pattern across engagements: product and delivery roles feel relief early (specs they can read, evidence they can audit, progress they can see), and senior developers feel friction early, because the pipeline formalizes judgment they already exercise implicitly and the ceremony reads as overhead until the first review gate catches something they would have missed. The friction fades with the first caught regression; the relief does not.

The throughput claim that goes with it, from the same engagements: a two-to-three-hour structured discovery interview reliably produces 8 to 11 implementation-ready specs with numbered acceptance criteria, boundaries, and task breakdowns.

Adoption ladder

• Week 1: capture, plan, work
• Month 1: add cross-model review and make-pr
• 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