The Flow field guide
Decisions,
on the record.
Numbered records of significant choices behind Flow, with their context, decision, and consequences. Newest first.
Browse docs/decisions on GitHub
70 decisions shown
- 0070A research skill, clearer names, and an outcome in every initiative specFlow should help a person discover that something already solves the problem, decline work against the product, or test cheaply before building. Three gaps stand in the way.Accepted
- 0069Direction changes gate at adoption, not discussion0038 made explore stop at any goal that contradicts an Accepted decision, spec, or PRODUCT.md fact.Accepted
- 0068The experience skill and the new-skill testFlow verifies correctness (review) and liveness (ship), and judges fit and metrics (product). Nothing observes a running product the way its user meets it.Accepted
- 0067Flow boundaries: plugin, starters, scripts, hoststart grew into the assumed front door: it waits for a green deployment and always opens discovery. Since 0062, most users meet Flow as a global plugin in a repository that never touched a starter.Accepted
- 0066Specs sized by delivery, not lengthSpec 061 stopped specs growing past 3,000 words with a guideline and a deterministic failure. 0022 required the first slice to test the riskiest assumption.Accepted
- 0065Verification proportional to risk0056 made contracts test-first because agents shipped MCP tools whose errors and permissions were never exercised. 0058 tied review effort to risk.Accepted
- 0064Cursor plugin0062 ships Flow as a Claude Code plugin and leaves other hosts with the skills and without the guard or the work-in-flight report.Accepted
- 0063Decision-record thresholdflow-skills wrote about 60 decision records in its first 10 days, and several reversed each other within days (0031, 0043, 0053, 0060).Accepted
- 0062Claude Code firstFlow is written to be portable to any agent host, so its skills restate what the host should do.Accepted
- 0061Eve as the default agent runtime in Flow startersFlow's agent-first principle (0023) requires typed contracts and durable agent behavior in product templates.Accepted
- 0060Build slices by areabuild delegated work only in its Task set, and only "when it pays" (write-agents Workers, after 0053). A spec with no Tasks list gave no splitting guidance, so the agent judged alone.Accepted
- 0059Vercel CI vs GitHub Actions: staying on GitHub Actions for nowFlow's repositories (flow-skills, flow-next, flow-mono, flow-factory, and the projects built from them) run their pull request checks on GitHub Actions standard runners.Accepted
- 0058Fresh-context review, effort by riskbuild gave small changes a self-check by the authoring agent and escalated risky ones to an independent review, with two fix rounds. Findings were labeled confirmed, plausible risk, or preference.Accepted
- 0057Draft workspace, checks on readybuild opens a ready pull request and waits on CI. Pull request workflows run on every push, drafts included. Vercel builds a preview for every branch push. The starters install a pre-commit hook.Accepted
- 0056Contract-first tests, no UI tests by defaultPrinciple 8, "Agent-first, API-first", has products define capabilities as contracts before interfaces, and to-spec writes API shapes and MCP tool definitions before any UI.Accepted
- 0055Capability-based GitHub and host-triggered buildsThe maintainer wants to direct delivery from a phone, with the same Flow behavior whether the agent runs locally or in a Claude Code cloud session.Accepted
- 0054Native capabilities before Flow machineryIndependent sessions already have isolation and ownership rules.Accepted
- 0053Delivery appetite and scope protectionThe retrospective reports a three-hour target expanding into a full-day effort.Accepted
- 0052Git-first, best-effort coordinationThe maintainer's retrospective reports collisions and stranded work across independent sessions. Existing worker rules primarily describe a main thread and its delegated workers.Accepted
- 0051Design skill for visual directionFlow names design as agent work in the products built with it (PRODUCT.md) and keeps DESIGN.md as a root context file, but no skill owns choosing a visual direction.Accepted
- 0050GitHub governance presetFlow's repositories and the projects start creates had no consistent GitHub settings. Before this record, none of gaboesquivel.com, flow-next, flow-mono, or meta-cto protected main.Accepted
- 0049The agent does the workFlow's main metric is idea → prod, and user turns and confirmations are a named source of delay (PRODUCT.md).Accepted
- 0048Delivery phrases are approvalsQuestions and acceptance belong to planning. After that, the user wants one phrase per delivery depth, each one a full approval, with no overlap that dictation could blur.Accepted
- 0047Trusted LLM review, record checks in validatecontext-review checked out the pull request and ran the pull request's own scripts/run-context-review.mjs with FLOW_REVIEW_API_KEY in its environment, reading the review contract from the same checkout.Accepted
- 0046Portable measurement assistanceThe methodology defines good measurement and explore asks for main-metric instrumentation, but nothing evaluates collected evidence or tells collection, access, tooling, and sample-size gaps apart.Accepted
- 0045Templates pin flow-skills; one owner per workflowflow-next and flow-mono ship a .agents/skills-lock.json of technical skills that pnpm setup installs.Accepted
- 0044Fast delivery: checks once, liveness only, review when it paysPRODUCT.md now makes idea → prod Flow's main metric, with time to start and time to close PR beside it.Accepted
- 0043Workers when they pay, checks once per head0042 made workers, worktrees, and scheduling a choice for build, ship, and review, and left every other skill on 0031's "parallel is the default." In practice that rule still makes to-spec and to-tasks spawn read-only workers to re-read a repository the conversation, usually right after explore, already holds.Accepted
- 0042Outcome-first build and shipbuild and ship are short files whose bodies mostly tell the agent how to run: start every unblocked task at once, one worktree each, prepare that worktree, post a checkpoint, write a failing test first, and review with one worker per axis plus a verifier.Accepted
- 0041Product alignment skillFlow checks alignment at three scopes already: tldr checks a session against its goal, review checks a change against its spec, and flow keeps root docs current with the code.Accepted
- 0040Ship verifies liveness, not the journeyDecision 0032 had ship run the spec's acceptance scenario in a browser twice in GitHub mode: on the preview before the merge, as a gate, and on production after it, with screenshots, a local dev server when no deployment appears, and scratch worktrees to clean up.Accepted
- 0039Build never requires a specDecision 0034 let small unspecced work land with the suite and one self-check, and made a size guard stop everything else and send it to to-spec.Accepted
- 0038Direction changes are confirmed and recordedA goal stated in explore can contradict an accepted decision, an accepted or implemented spec, or a PRODUCT.md fact.Accepted
- 0037Git for delivery, GitHub for GitHub modeFlow never states what it needs from the environment.Accepted
- 0036One explore depth, deeper research on requestDecision 0026 records a Lite or Full process depth once per project, on the Flow block's Process: line, and asks for it at setup.Accepted
- 0035Open the spec issue at acceptanceDecision 0029 opens a public spec issue as part of "spec it", so teammates can read and comment on a draft without opening the repository.Superseded
- 0034No ceremony without a specSpec 020 made local build land every change through the spec gate and the full per-axis review before merging into main, including work with no spec or task.Accepted
- 0033Shared files do not move the reviewed headbuild (local mode) and ship (pull-request mode) merge only the head the review covered. Some projects require every session to append to a shared file, such as a prompt log, after every prompt.Superseded
- 0032Local build lands on main; ship publishes and verifiesFlow's last step checks CI and a code review, then stops.Accepted
- 0031Fan out by defaultFlow's skills are mostly written as sequences.Accepted
- 0030Asked delivery mode and local mode without a remoteFlow has two delivery modes.Accepted
- 0029Spec issues and fast parallel buildsIn pull-request mode a spec lands through its own pull request before any work, and its task issues have no parent.Accepted
- 0028Build opens the pull request; ship lands accepted work"Ship it" stops twice, for a plan confirmation and a main gate, although users say it once they have decided.Accepted
- 0027Progress board skillFlow has no view of where a project's specs stand.Accepted
- 0026Process depth, one setup path, and the spec–decision boundarystart and "set up Flow here" define different things.Accepted
- 0025Wave checkpoints and visual reviewship on a task set runs every task to the end and opens the pull request last, so the user sees nothing reviewable until the run is over.Accepted
- 0024Gated hand-offs and outward writes0019 made skills speakable on the premise that a skill matched from a description does not chain into others.Accepted
- 0023Agent-first, API-first principledocs/principles.md already describes an optional "Agentic" theme: build for agents and humans, API-first, with MCP where appropriate.Accepted
- 0022Start runs explore alongside the bootstrapstart produces a verified repository but forbids product discovery and must be invoked by name.Accepted
- 0021Autonomous explore and ship: GitHub issues, grouped pull requestsDogfooding spec 010 showed two frictions. The work shipped as five pull requests for small, coupled skill edits, and every step stopped for confirmation or a permission prompt.Accepted
- 0020Flow mode: conversational delivery and in-session task orchestration0019 made every skill except start reachable by plain or dictated language.Accepted
- 0019Voice-first invocationPRODUCT.md says ordinary language should be the complete user interface to Flow and that skills are optional conveniences. The catalog does the opposite.Accepted
- 0018Interview extracts the user's intentinterview shipped as a customer discovery skill: plan an interview guide for end users and synthesize transcripts. In practice the useful interview is with the person asking for the work.Accepted
- 0017Coexist with Claude Code built-in skillsClaude Code ships its own skills and commands alongside any installed Flow skills. Several overlap with the Flow catalog: Flow skill Claude Code counterpart Difference simplify /simplify Same name.Accepted
- 0016Start bootstraps in place and reads the template from the requestThe recommended sequence is install Flow Skills, then invoke start. Installing skills, or adding AGENTS.md and CLAUDE.md first, leaves the project root nonempty.Accepted
- 0015Rename to-tasks and restore domain-modelingThe portable catalog kept to-tickets from upstream naming while the skill already produces tasks and publishes tracker issues only when asked.Accepted
- 0014Handoff skill0003 retired handoff because it sat outside the intended catalog. 0013 restored seven other skills and left handoff out. The maintainer asked to add it.Accepted
- 0013Restore selected engineering skills0004 cut the catalog to a portable, manually invoked set and retired quality skills and delivery helpers.Accepted
- 0012Start bootstrap library modulesThe start skill needed executable helpers for template rename, git safety, baseline docs, and commit gates so agents do not improvise destructive git or leave Flow identity in adopter repos.Accepted
- 0011Replaceable homepage and GenUI playground routesSpec 005 PRD-2 describes a Studio-first public website. Before that UX migration ships, flow-next and flow-mono need a stable, shared route contract for manual dogfooding and template adoption.Accepted
- 0010Optional start skill authorized0009-adopter-product-context.md (accepted, immutable) states that an adopter's PRODUCT.md is that product's identity, that flow is not project initialization, and that this repository must not ship flow start or adopter instruction-file edits in that change.Accepted
- 0009Adopter product context is not Flow's identity0007 puts Flow's methodology identity in this repository's PRODUCT.md. Flow Lite then tells agents to align PRODUCT.md.Accepted
- 0008Leading words and visual summariesReaders need a visual grasp of technical material, and skills need compact anchors so behavior stays recognizable. Matt Pocock's writing-for-agents skill calls those anchors leading words.Accepted
- 0007Official Flow product identity in PRODUCT.mdEarlier product copy centered flow-skills as a skill collection.Accepted
- 0006Flow Lite skill and flat documentationDecision 0004 retired the flow workflow router and kept the catalog fully manual.Accepted
- 0005Misc group and tldr skillUsers need a lightweight way to recap a long session and confirm the agent still shares their goal.Accepted
- 0004Portable skill catalog and distributionThe repository previously shipped twenty-five skills, a flow workflow router, and an optional flow-skills-init bootstrap that merged AGENTS.md markers.Accepted
- 0003Skill naming and catalog shapeFlow consolidated upstream skills into a self-contained skills/ directory. Legacy names were verbose, metaphor-heavy, or duplicated behavior.Superseded
- 0002Maintain Flow skills as local sourceThe user directed Flow to own copied skill implementations without upstream skill dependencies and remain agent/UI agnostic.Accepted
- 0001Curated Flow Skills distributionFlow Skills needs a standalone, versioned skill distribution that combines attributed upstream skills with Flow methodology, unified decision handling, explicit manual invocation, and controlled upstream updates—without depending on Flow Factory or a fixed technology stack.Superseded