flow

Field guide

What Flow
is

Mission, definition, the eight principles, success metrics, and the Flow ecosystem.

Source:
PRODUCT.md
Built from:
da88c48

From intent to verified software.

Mission

Velocity with intent: make product engineering with AI agents simpler, faster, and more reliable—without sacrificing product understanding, engineering quality, or human judgment.

Definition

Flow is a lightweight, human-directed, agent-executed product engineering methodology for building and evolving software with AI agents.

It combines shared product context, reusable engineering skills, and practical development conventions in a continuous workflow from exploration to verified delivery.

Flow is Claude Code first (decision 0062): it builds on Claude Code's built-ins and enforces must-hold rules with hooks, and stays portable where that is free. The Cursor plugin runs those same hooks (decision 0064). It is UI-agnostic and technology-agnostic. Its process is proportional to the work, not a mandatory sequence of ceremonies.

Flow is a documented way of working, not an agent router. Ordinary language should be the complete user interface to Flow; shortcuts and skills are optional conveniences.

Experience

Working with Flow should feel like one continuous conversation with a product-minded engineering partner.

Humans define direction and make consequential decisions. Agents do the work: explore, design, implement, review, verify, and operate, through the tools they can reach. Shared context preserves understanding as software evolves: product, design, architecture, decisions, and evidence stay current and discoverable.

Direct from any device. The same phrases behave the same in a local session and a cloud session, so delivery can be directed from a phone. Optionally, a repository writer's build-it label on an issue starts a cloud build that ends at a pull request; "ship it" stays a conversational approval (decision 0055, spec 046).

Principles

  1. Product before code. Build useful software, not just completed tasks.
  2. Preserve intent. Keep product, design, architecture, and significant decisions understandable and current.
  3. Human-directed, agent-executed. Agents carry out the work, including setup and operations; people decide, and handle only the steps that need them, such as sign-in and secrets (decision 0049).
  4. Minimal process. Use only the structure and skills the task requires; skills compose, and no sequence is mandatory. Humans say what and why; agents choose how.
  5. Evidence over claims. Verify outcomes through tests, reviews, and real-world checks in proportion to risk: agents judge what needs evidence, and project scripts run the checks.
  6. Claude Code first, portable where free. Use the host's built-ins instead of restating them; skills stay plain Markdown so other agents keep the method (decision 0062).
  7. Improve through use. Develop Flow using Flow, and simplify it through real experience.
  8. Agent-first, API-first. Build every product for agents and people; define consequential capabilities as contracts before interfaces.

Methodology practices that elaborate these principles live in docs/principles.md and docs/methodology.md as optional judgment, not enforcement.

Success

Reduce the time and effort between human intent and verified product value. Process should cost minutes, not rounds: checks run once, in build, and each delivery phrase ends with a light check that the change is live (spec 035). Remove ceremony, never the practice: keep good product, lean startup, and engineering practices, and cut any step that repeats them or records state no one reads.

Metric From To Target (hypothesis, low confidence)
Idea → prod (main) First prompt of the session where the work begins, local or cloud, or the authorizing build-it label on an issue Live: production deploy answers (apps), or merged to main (flow-skills) Small change < 15 min; feature < 2 h
Time to start First prompt to start Initial commit, pushed where authorized < 5 min
Time to close PR First commit on the branch Merge Median < 10 min (baseline 7.4 min, p90 60 min)
Delivery within appetite Increment accepted with an appetite Shipped Most increments ship within appetite with accepted scope intact; not yet measured (decision 0053)

Diagnostics explain where the time goes: scope added mid-flight, user turns and confirmations, local check runs, CI waits and failures, rework, skills invoked, cost, agent workers, and skill words loaded. What the logs cannot show is unknown, never zero (spec 041).

Measured only on the dogfood repositories (flow-skills, flow-next, flow-mono) by a maintainer script that joins host session logs, git, GitHub, and deployment data. Nothing ships to adopters. Each change is split by where it ran (local, cloud, or issue-triggered). Cloud cost comes from the host's OpenTelemetry export when configured, otherwise unknown; linking cloud runs to merges through the session link in the pull request body is a hypothesis (medium confidence).

Kill criterion: if session logs cannot link at least 80% of merged changes to their starting prompt, idea → prod falls back to first commit → live.

Alternatives and differentiation

A product engineer building with Claude Code would realistically choose one of these instead (research, 2026-11-08):

  1. Claude Code alone. Plan mode, /code-review, worktrees, and memory cover planning and verification (observed in its docs). In one small task, delivery without any skill was as good as with Flow (spec 059 comparison; one run per condition).
  2. Superpowers. Brainstorming with recon and alternative approaches to how something gets built, plans, TDD, and review (observed in its skills).
  3. Matt Pocock's skills. Grilling, to-spec, tickets, domain modeling, code review, and research notes (observed in its skills).

Why Flow (hypothesis). Flow helps decide what to build, reuse, defer, or stop from the project's own goals and constraints, and later judge that choice against the outcome its spec named. Evidence so far: no step for deciding whether to build, reuse, defer, or stop, or for judging outcomes after shipping, was found in the skills read (mostly their opening sections); Superpowers weighs alternatives, but for how to build. Hypothesis: the gap is real and explore and align close it well enough to change decisions; neither is measured. Flow's delivery chain alone is not a reason to choose it.

Strategic chain

Everything introduced into Flow should strengthen this chain or reduce friction along it:

Product thinking → Engineering discipline → Agent execution → Verified value

The methodology defines what good product engineering looks like. Reusable skills and conventions make that methodology convenient to practice.

Ecosystem

Piece Role
Flow The methodology (this document and related practice docs)
flow-skills (this repository) Reusable skills and conventions for agents
flow-next / flow-mono Independent application foundations (templates); interop contract (candidate; owned by the template repositories) (supersedes 003 for new work)
Flow website (site/) Public home for the ecosystem: methodology, skill catalog, starters, docs, capability pages, and articles rendered from this repository (spec 057), with a ⌘K palette for search and cited answers for people (spec 040), and llms.txt, Markdown, search, and MCP for agents (spec 032)
Flow Factory Optional hosted, issue-driven orchestration and automated execution built on Flow—not Flow itself. Flow mode is the in-session counterpart and does not depend on it.

Each piece has one job (who owns what). Adoption is flexible: take one skill or the whole practice in any repository, and shape the workflow to the work. The starters are deliberately opinionated: they choose the stack, tooling, and deployment so a project ships on day one; teams that want other choices keep the methodology and skip or fork a starter (spec 040).

Templates remain usable without Flow. Flow owns the methodology; flow-skills implements portable agent behavior; templates own their application foundations.

Dogfooding

Every meaningful improvement to Flow must be developed using Flow and validated against a realistic software development task.

That means maintaining relevant living documentation, using existing skills proportionally, and running retrospectives that can eliminate unnecessary complexity. The repeatable practice, including how to separate structural checks from live agent verification, is Dogfood.

Primary internal dogfooding targets: flow-skills first, then experience validation on flow-next and flow-mono.


This repository: flow-skills

Status: portable, voice-first catalog on main (0004, 0005, 0006, 0007, 0008, 0009, 0010, 0013, 0014, 0015, 0016, 0017, 0018, 0019, 0020, 0021, 0022, 0023, 0024, 0025, 0026, 0027, 0028, 0029, 0030, 0031, 0032, 0033, 0034, 0035, 0036, 0037, 0038, 0039, 0040, 0041, 0042, 0043, 0044, 0046, 0048, 0062); live verification in multiple agent hosts remains ongoing.

Problem

AI makes it easy to ship faster than teams establish what matters. Disparate skills and heavy methodology leave founders reconciling workflows, terminology, and documentation alone.

flow-skills offers a small catalog: context alignment (sync-docs) for root context and Flow setup, plus optional skills you reach by talking to your agent, typed or dictated. Optional template initialization is the start skill only — Flow setup plus a template bootstrap, not flow start, and not mandatory; it asks only what the request leaves open before writing (decision 0044). Templates work without Flow Skills. Skills may name the next skill and wait; the only automatic hand-off is start → explore, behind the user's yes. "Push it", "build it", and "ship it" are approvals: build ends with a reviewed, checked branch, ship merges it, and "push it" has ship push a branch with no pull request, each ending with a liveness check (decision 0048; 0024). Adopter AGENTS.md, CLAUDE.md, or equivalent files change only when you opt into Flow mode.

Adopter product context. In another repository, PRODUCT.md is that product. This file is Flow's identity only. sync-docs and build update an adopter's product docs when that product changes. They do not overwrite them with the mission, principles, or tagline above. Decision 0009.

Install and catalog

Install. Three ways, from the same skills/ tree (decision 0062, decision 0064):

Requirements. What a skill needs depends on its tier (decision 0037):

Tier Skills or features Needs
Thinking council, align, research (in chat), experience, domain-modeling, write-agents, design (directions and prototypes) Nothing: any folder, or none
Delivery chain sync-docs (the Flow block), research (notes), start, explore, design (recording), to-spec, to-tasks, build, review, ship A Git repository; outside one, the skill offers git init and stops on a no
GitHub mode Pull requests and CI; issues only on request GitHub access through gh, its REST API, or the host's GitHub tools, on top of Git (decision 0055)
Enforcement The guard hook and the SessionStart report Claude Code or Cursor with the Flow plugin. Cursor cloud agents run the shell guard and do not run the session report. npx skills add and other hosts run the same skills without the hooks

Local delivery needs only Git, so the whole chain works with GitLab, Bitbucket, or no remote. No skill asks the delivery mode; delivery skills infer it (decision 0044). Thinking skills may read Git when it exists.

Layer Skills
Context alignment sync-docs — align the current project's PRODUCT.md, DESIGN.md, GLOSSARY.md, ARCHITECTURE.md where hosts support discovery, and set up Flow: the opt-in Flow block, which can override the inferred delivery mode. Not always-on, and not template initialization.
Delivery explore (interviews and stress tests too), to-spec, to-tasks, build, review, ship (pushes too)
Advisory council
Experience experience (read-only walk of a running product)
Design design (prototypes too)
Shared language domain-modeling
Product discovery research, align
Writing write-agents
Project start start — Flow setup plus a verified bootstrap from flow-next or flow-mono, with explore alongside when the request describes a product; asks only what the request leaves open, and the initial commit is its done signal

Grouped descriptions and links: docs/skills.md. Say a skill's leading word ("interview me", "spec it", "ship it"); slash commands are optional. Every skill is reachable by phrase (0019); start asks only what the request leaves open before it writes anything (0022, amended by 0044). No skill enforces a sequence (/build does not require /to-spec).

Default durable docs in adopter projects: docs/specs/NNN-short-name.md and docs/decisions/NNN-short-name.md, plus root context files when useful. The spec file is the record in both modes; in GitHub mode the pull request links it, and issues open only on request (decision 0044, superseding the spec issue of 0029 and 0035).

Not shipped as skills: validation-board UI or a progress board (retired), OMTM automation or analytics services (read-only measurement assistance ships in align, decision 0046, spec 034), commercial discovery pipelines, or hosted orchestration (Flow Factory); the optional issue trigger runs on the host's own triggers, not a Flow service (decision 0055). Project initialization is the optional start skill only (not a router or mandatory pipeline). Validation judgment lives in methodology as practice; measurement never gates shipping.

Flow mode

Opt-in conversational delivery (decision 0020, spec 009). Saying "set up Flow here" has sync-docs write one removable Flow block into the project's tracked instruction file: a pointer to sync-docs and, when set, a Delivery: override; each skill's description carries its own phrases. Setup asks no delivery question: the delivery mode is inferred (GitHub when origin is a GitHub repository, stopping only when no route reaches GitHub; otherwise local), and local and GitHub are delivery options, not separate methodologies. explore asks in proportion to the change. When the project has no goals yet, sync-docs names explore next. build slices a multi-area change by disjoint area, and the host decides how to fan the slices out under its concurrency cap (Slices, decision 0062). After "break it down", to-tasks reports the ready set; "build it" ends with a reviewed, checked branch and reports any unfinished work with its branch; "ship it" builds when needed, lands, and checks liveness; "push it" pushes a branch (ship). With the plugin, the guard hook blocks force-pushes, pushes to the default branch, --no-verify, and admin merges whatever the model decides. Decisions 0028, 0030, 0031, 0032, 0042, and 0043 record the earlier shapes; 0044 amends them. build owns the delivery-mode rule.

Catalog alignment (evaluate before adding skills)

Chain stage How the current catalog supports it
Product thinking explore (with its interview, stress test, and how the problem is solved today), research, council, design (visual direction and prototypes before building); sync-docs keeps product intent in root docs
Engineering discipline to-spec, to-tasks, domain-modeling, write-agents; specs and decisions as flat durable artifacts
Agent execution build (outcomes and proofs for an implementation, in either delivery mode), ship; the plugin's guard hook; plain-Markdown packages with no mandatory router
Verified value review (the flow-reviewer agent on top of /code-review), ship, align; scenario verdicts, liveness, and a product-wide check against vision and metric evidence

Further catalog growth needs its own decision. 0013 restored council, ship, prototype, simplify, security, performance, and debug. 0014 adds handoff. 0015 renames to-tasks and restores domain-modeling. 0019 retires simplify, security, and performance in favor of host tools. 0027 adds board. 0041 adds align. 0046 adds measure. 0051 adds design. 0062 hands host-covered work to Claude Code: explore absorbs interview and grill, product merges align and measure, design absorbs prototype's UI variants, ship absorbs push, and handoff, tldr, debug, retro, and board leave the catalog (board stayed as a script until 2026-11-03, then was removed). Spec 059 removes jtbd, competitors, and write-humans, which tied with no skill in an on-trial comparison. 0068 adds experience. 0070 adds research and renames product to align and flow to sync-docs.

Open choices

Measurable learning may inform maintainer research. Idea → prod is Flow's main metric (Success); broader demand remains unvalidated.

Starting a project. Invoke the optional start skill when you want a verified new repository from flow-next or flow-mono. When the request describes the product, explore runs alongside (0022). It asks only what the request leaves open. The bootstrap covers renamed identity, template setup, QA, the identity scan, .gitignore, baseline PRODUCT.md / DESIGN.md / ARCHITECTURE.md, and an independent initial commit when checks pass; the initial commit is the done signal (decision 0067). There is no flow start command; sync-docs must not be treated as initialization (0010).

See documentation guide and AGENTS.md for maintenance.

Jump to, or try a question