Field guide
Get
started
Install Flow and use your existing agent. Phrases, delivery modes, and work without a spec.
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:
claude plugin marketplace add gaboesquivel/flow-skills
claude plugin install flow@flow-skillsAgent 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:
npx skills add gaboesquivel/flow-skillsTo 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,
buildtreats 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,
explorestops at the brief; spec 001 comes only when you ask.exploreskips 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.
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 startNodeThick 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).exploreasks 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.
shiplands 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-docsupdatePRODUCT.md,DESIGN.md,GLOSSARY.md, andARCHITECTURE.mdto accepted direction; "check alignment" hasalignreport, 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-specdecides 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
pnpm validate
pnpm test