flow

Field guide

Get
started

Install Flow and use your existing agent. Phrases, delivery modes, and work without a spec.

Source:
README.md
Built from:
da88c48

From intent to verified software. Agent skills for Flow, a lightweight, human-directed, agent-executed product engineering methodology. Flow is built for Claude Code and ships as a plugin; the skills are plain Markdown, so other agents can use them too. You talk to your agent, typed or dictated: "explore this", "spec it", "ship it". Each phrase reaches one skill. Nothing runs unless you ask, and you can use one skill, all of them, or none.

Flow identity and catalog scope · Skill catalog · Methodology · Documentation guide

Install

Claude Code (recommended). Install Flow as a plugin. You get the skills, plus a guard hook that blocks force-pushes, pushes to the default branch, --no-verify, and admin merges, a report of work in flight when a session starts, and the flow-reviewer agent behind "review it". The repository is its own marketplace; installed at user scope, the plugin loads in the terminal, the desktop app, and IDE extensions:

bash
claude plugin marketplace add gaboesquivel/flow-skills
claude plugin install flow@flow-skills

Agent compatibility covers loading the plugin and the settings we recommend.

Cursor. Install the Cursor plugin from this repository (.cursor-plugin/plugin.json). It loads the same skills, the same guard and work-in-flight report, and flow-reviewer. Use that plugin or npx skills add, not both, and not also the Claude Code plugin. Cursor cloud agents run the shell guard and do not run the session report.

Any Agent Skills host. Install the skills alone, without the hooks:

bash
npx skills add gaboesquivel/flow-skills

To pin a release, install from its tag: npx skills add https://github.com/gaboesquivel/flow-skills/tree/<tag>. Choose your agent and install scope in the installer; for cloud sessions (Claude Code on the web or the phone), install at project scope and commit it, since those sessions load only the repository (agent compatibility). Agent compatibility covers other install paths and metadata limits. Flow needs no changes to your instruction files; setting up Flow mode adds one removable block, and only when you ask.

Flow is Git-based

Flow keeps its work in Git: specs, decision records, and the product brief are files committed on branches, and delivery is branches and merges. What you need depends on what you use (requirements, decision 0037):

You use You need
Thinking skills: council, align, research (in chat), experience, domain-modeling, and write-agents Nothing. Any folder works, with or without Git.
The delivery chain: sync-docs's setup, research notes, start, explore, to-spec, to-tasks, build, review, ship A Git repository. Outside one, the skill offers git init and stops if you say no.
GitHub mode GitHub access as well: pull requests and CI live there.

The rules Flow follows in a project live in Git too. "Set up Flow here" writes one Flow block into the instruction file Git tracks: AGENTS.md, or CLAUDE.md with an @AGENTS.md import when AGENTS.md is ignored. The block holds a pointer to sync-docs and, when you set one, a Delivery: override, and every agent and teammate who clones the repository reads the same rules. Delete the block to opt out.

Local or GitHub delivery

Local and GitHub are delivery options, not separate methodologies: the skills, phrases, and steps are the same, and only where the work lands differs. Flow never asks which one. It uses GitHub when origin is a GitHub repository, and reaches it through gh, the host's GitHub tools, or the REST API, stopping only when none works rather than falling back; local otherwise. A default branch that requires pull requests always gets GitHub (decisions 0044, 0048).

Local GitHub
Needs Git only. Works with GitLab, Bitbucket, or no remote at all. Git plus a GitHub repository and a route to it: gh, its REST API, or the host's GitHub tools.
Spec A file on its feature branch. The same file; the pull request links it.
Tasks A checklist in the spec's Tasks section. The same checklist.
"Push it" Commits and pushes the current or named branch. The same; no pull request.
"Build it" Ends with the work committed, reviewed, and checked on its branch. Ends with an open pull request, reviewed, with CI green.
"Ship it" Builds if needed, merges into main, and pushes when a remote exists. Builds if needed and merges the pull request.
Liveness Each phrase ends with a light check that its commit is on the remote and, for an app, deployed. The same.

Each phrase is the approval; nothing asks again after it. build has every change reviewed by a second agent in a fresh context, running Claude Code's /code-review at Quick, Standard, or Deep effort by risk, plus Flow's checks against the spec; CI, Git hook, auth, billing, and release changes ship only on your yes. To override the inferred mode, add a Delivery: line to the Flow block, or say so for one run: "ship it local" or "ship it with GitHub". The full rule lives in build; the glossary defines delivery mode.

Work without a spec

Specs are for work worth tracking, not a toll on every change. In either mode, nothing writes a spec or tasks unless you say "spec it" or "break it down" (decision 0039).

  • Say "build it". With no spec behind it, build treats the change as unspecced work and ends with a reviewed, checked branch: a committed branch, or an open pull request. Its size guard sets the review's effort from the change's risk; "ship it" lands it.
  • Explore, then build. After "explore this", "build it" builds the confirmed brief directly. The brief's branch is the work branch, so the brief lands with the code. For a new product, explore stops at the brief; spec 001 comes only when you ask. explore skips fixes and clearly small changes entirely: no questions, no writes.
  • Just ask your agent. Flow skills run when your request matches their phrases. A plain request ("rename this prop") is handled as your agent would without Flow.

How it works

Say a phrase and the matching skill runs. There is no required order: start anywhere, skip any step.

Flow's skills from a new project to shipped work
start can lead into explore; shaping runs through to-spec and to-tasks, or straight to build; delivery runs build, then ship, with review when the change is large or you ask.
Diagram source
flowchart LR
  accTitle: Flow's skills from a new project to shipped work
  accDescr: start can lead into explore; shaping runs through to-spec and to-tasks, or straight to build; delivery runs build, then ship, with review when the change is large or you ask.
  start["start<br/>new project"] -.-> explore
  subgraph shapeGroup [Shape]
    explore["explore<br/>'explore this'"]
    spec["to-spec<br/>'spec it'"]
    tasks["to-tasks<br/>'break it down'"]
  end
  subgraph deliverGroup [Deliver]
    build["build<br/>'build it'"]
    review["review<br/>large or asked"]
    ship["ship<br/>'ship it'"]
  end
  explore -.-> spec -.-> tasks -.-> build
  explore -.-> build
  build -.-> review -.-> ship
  classDef shapeNode fill:#EEEDFE,stroke:#534AB7,color:#3C3489
  classDef deliverNode fill:#E1F5EE,stroke:#0F6E56,color:#085041
  classDef startNode fill:#F1EFE8,stroke:#5F5E5A,color:#444441
  class explore,spec,tasks shapeNode
  class build,review,ship deliverNode
  class start startNode

Thick arrow: an automatic hand-off, behind your yes. Dashed arrow: you say the next phrase.

  • Skills suggest the next step and wait. The only automatic hand-off is start → explore, when the request describes the product and behind your yes (decision 0024). explore asks in proportion to the change: nothing for a fix, more for a new product, and for substantial work it asks how the problem is solved today, so reusing something or stopping is a valid answer. "Interview me" and "grill this" reach it too.
  • No spec required. "Build it" works on a plain request (decision 0039); see work without a spec.
  • ship lands in both modes. It builds first unless the branch is already verified, merges, then checks the shipped commit is live (decisions 0044 and 0048).
  • Context stays aligned. "Sync the docs" has sync-docs update PRODUCT.md, DESIGN.md, GLOSSARY.md, and ARCHITECTURE.md to accepted direction; "check alignment" has align report, read-only, whether the product still fits its goals and what the outcome evidence shows.
  • Research leaves a note. "Research X" or "competitors for X" writes a dated, sourced note another session can decide from; "just tell me here" keeps it in chat.
Path You say
Quick fix "build it" → "ship it", or just "ship it"
Shaped idea "explore this" → "build it" → "ship it"
Tracked work "explore this" → "spec it" → "break it down" → "build it" → "ship it"
New project "start a Next.js project" (explore alongside when you describe the product)

Every other skill (council, align, research, design, …) can run at any time and never blocks delivery.

Specs, tasks, and decisions

  • Spec: one independently deliverable increment; to-spec decides whether work needs one or several. "Spec it" writes a draft file; "build it" or "ship it" on the draft accepts it, or say "accept the spec" to approve it first.
  • Tasks: the slices inside a spec, each verifiable on its own.
  • Decision record: written only when a choice picked among real alternatives and reaches beyond one spec or is costly to reverse.

Details and links to every SKILL.md: docs/skills.md.

Catalog

Group Skills
Context alignment sync-docs
Delivery explore, to-spec, to-tasks, build, review, ship
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

The plugin adds a guard hook (hooks/guard.mjs), a SessionStart report (hooks/wip.mjs), and the flow-reviewer agent. Debugging, hand-offs, recaps, and retrospectives are Claude Code's own (decision 0062).

Default durable docs in adopter projects: docs/specs/NNN-short-name.md, docs/decisions/NNN-short-name.md (or existing conventions).

Influences and engineering philosophy

Flow builds on the work of engineers and teams who have advanced software engineering with AI agents. We study their methods, adapt what works, and maintain our own independent implementations.

Influence What we learn
Matt Pocock Clear agent instructions, leading words, progressive disclosure, and focused human alignment.
Lauren Tan (poteto) Rigorous engineering, root-cause prevention, blast-radius verification, architecture-first thinking, and independent adversarial review.
Addy Osmani Production engineering discipline, maintainable code, practical specifications, and evidence-based delivery.
Jesse Vincent (Superpowers) Test-driven skill development, systematic debugging, and regression testing of agent behavior.
Anthropic Agent Skills Portable skill conventions, realistic evaluations, and measuring whether instructions improve agent behavior.
Vercel Agent Skills Focused engineering guidance, prioritized rules, concrete examples, and efficient skill packaging.

How Flow differs

Flow combines product thinking, engineering discipline, and verified execution without imposing a fixed sequence or orchestration runtime.

  • Human-directed: People set direction and make consequential decisions; agents do the work.
  • Minimal: Use only the skills, documentation, and verification the work requires.
  • Claude Code first, portable where it's free: Flow uses Claude Code's built-ins and enforces must-hold rules with hooks; the skills stay plain Markdown for other agents.
  • Evidence-driven: Tests and observed behavior matter more than confident claims.
  • Locally owned: Flow maintains its own implementations, with attribution for adapted work.

We prefer preventing recurring mistakes through architecture, types, static checks, and tests before adding more instructions. We evaluate skills against realistic tasks, and simplify or remove instructions that do not improve outcomes.

Flow is not a fork of these methodologies. It is an independent, evolving approach shaped by practical use.

Maintain

bash
pnpm validate
pnpm test

Release checks · Attribution

Jump to, or try a question