Collaboration

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.

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. Spec completion review is the sole surface. It records met / violated / n/a per criterion in the ordinary review receipt, and reports every violation as a normal finding. No separate auditor pass, no per-task application, nothing new to watch.
The file is user content. /flow-next:setup offers to scaffold it once, and never touches an existing file. It lives in the repo, so a criteria change goes through the same PR review as code.
Absence costs nothing. No file means no criteria content in any review prompt and no criteria field in receipts. Adopt it when the team has rules worth enforcing, ignore it until then.

Grammar, receipt contract, and CLI: Standing Criteria.

Adoption ladder

Week 1: capture, plan, work
Month 1: add cross-model review and make-pr
Quarter 1: add Spec-as-PR, decision records, Ralph 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

Spec-as-PR

For high-impact changes, open a PR with only .flow/specs/<id>.md before implementation. Review the acceptance criteria, non-goals, constraints, and rollout plan. Once that PR is approved, implementation work has a frozen contract.

This pattern is especially useful for platform work, data migrations, billing, auth, enterprise controls, or anything where the cost of building the wrong thing is high.