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"]
  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"]

Roles

• Product owner fills the business layer.
• 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.

Role map

Role	Owns	Flow-Next surface
PO / PM	User problem, success criteria, non-goals	/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

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

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 transport — the no-tracker workflow shown above is the documented default and is unaffected.

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.

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.

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.