# Flow — full content > Flow is a way to build software with AI agents: you decide what to build, agents do the work. Portable skills for the agent you use, opinionated Next.js starters, and docs that people and agents can search. Source: https://github.com/gaboesquivel/flow-skills · version 0.3.0 · commit da88c48271c0dd0f7fbd191a3a705fe77273aa48 · generated 2026-11-08T15:42:15.107Z Index: https://flow-skills-md.vercel.app/llms.txt --- # Guides --- ## Get started URL: https://flow-skills-md.vercel.app/docs/get-started Source: https://github.com/gaboesquivel/flow-skills/blob/main/README.md (`README.md`) **From intent to verified software.** [Agent skills](https://agentskills.io) for [Flow](https://flow-skills-md.vercel.app/docs/product), 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](https://flow-skills-md.vercel.app/docs/product) · **[Skill catalog](https://flow-skills-md.vercel.app/docs/skill-catalog)** · [Methodology](https://flow-skills-md.vercel.app/docs/methodology) · [Documentation guide](https://github.com/gaboesquivel/flow-skills/blob/main/docs/README.md) ### 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](https://flow-skills-md.vercel.app/docs/agent-compatibility#claude-code) covers loading the plugin and the settings we recommend. **Cursor.** Install the Cursor plugin from this repository ([`.cursor-plugin/plugin.json`](https://github.com/gaboesquivel/flow-skills/blob/main/.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/`. 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](https://flow-skills-md.vercel.app/docs/agent-compatibility#claude-code-cloud)). [Agent compatibility](https://flow-skills-md.vercel.app/docs/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](https://flow-skills-md.vercel.app/docs/product#install-and-catalog), [decision 0037](https://flow-skills-md.vercel.app/docs/decisions/0037-git-for-delivery-github-for-github-mode)): | 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](https://flow-skills-md.vercel.app/docs/glossary#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](https://flow-skills-md.vercel.app/docs/decisions/0044-fast-delivery), [0048](https://flow-skills-md.vercel.app/docs/decisions/0048-delivery-phrases-are-approvals)). | | 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](https://flow-skills-md.vercel.app/docs/glossary#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`](https://flow-skills-md.vercel.app/skills/build#delivery-mode); the glossary defines [delivery mode](https://flow-skills-md.vercel.app/docs/glossary#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](https://flow-skills-md.vercel.app/docs/decisions/0039-build-never-requires-a-spec)). - **Say "build it".** With no spec behind it, `build` treats the change as [unspecced work](https://flow-skills-md.vercel.app/docs/glossary#unspecced-work) and ends with a reviewed, checked branch: a committed branch, or an open pull request. Its [size guard](https://flow-skills-md.vercel.app/skills/build#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. ```mermaid 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
new project"] -.-> explore subgraph shapeGroup [Shape] explore["explore
'explore this'"] spec["to-spec
'spec it'"] tasks["to-tasks
'break it down'"] end subgraph deliverGroup [Deliver] build["build
'build it'"] review["review
large or asked"] ship["ship
'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](https://flow-skills-md.vercel.app/docs/decisions/0024-gated-hand-offs)). `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](https://flow-skills-md.vercel.app/docs/decisions/0039-build-never-requires-a-spec)); see [work without a spec](#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](https://flow-skills-md.vercel.app/docs/decisions/0044-fast-delivery) and [0048](https://flow-skills-md.vercel.app/docs/decisions/0048-delivery-phrases-are-approvals)). - **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](https://flow-skills-md.vercel.app/docs/skill-catalog)**. ### 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`](https://github.com/gaboesquivel/flow-skills/blob/main/hooks/guard.mjs)), a SessionStart report ([`hooks/wip.mjs`](https://github.com/gaboesquivel/flow-skills/blob/main/hooks/wip.mjs)), and the [`flow-reviewer`](https://github.com/gaboesquivel/flow-skills/blob/main/agents/flow-reviewer.md) agent. Debugging, hand-offs, recaps, and retrospectives are Claude Code's own ([decision 0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first)). 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](https://github.com/mattpocock/skills) | Clear agent instructions, leading words, progressive disclosure, and focused human alignment. | | [Lauren Tan (poteto)](https://github.com/cursor/plugins/tree/main/pstack) | Rigorous engineering, root-cause prevention, blast-radius verification, architecture-first thinking, and independent adversarial review. | | [Addy Osmani](https://github.com/addyosmani/agent-skills) | Production engineering discipline, maintainable code, practical specifications, and evidence-based delivery. | | [Jesse Vincent (Superpowers)](https://github.com/obra/superpowers) | Test-driven skill development, systematic debugging, and regression testing of agent behavior. | | [Anthropic Agent Skills](https://github.com/anthropics/skills) | Portable skill conventions, realistic evaluations, and measuring whether instructions improve agent behavior. | | [Vercel Agent Skills](https://github.com/vercel-labs/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](https://github.com/gaboesquivel/flow-skills/blob/main/docs/RELEASE.md) · [Attribution](https://github.com/gaboesquivel/flow-skills/blob/main/ATTRIBUTION.md) --- ## A flexible working practice URL: https://flow-skills-md.vercel.app/docs/methodology Source: https://github.com/gaboesquivel/flow-skills/blob/main/docs/methodology.md (`docs/methodology.md`) Current practices. Official identity and the eight principles live in [PRODUCT.md](https://flow-skills-md.vercel.app/docs/product). The [principles](https://flow-skills-md.vercel.app/docs/principles) draft elaborates optional themes; this document describes application, not a mandatory sequence or skill pipeline. ### Who owns what Flow's value does not depend on a starter, `start`, a hosting provider, or the whole delivery sequence ([decision 0067](https://flow-skills-md.vercel.app/docs/decisions/0067-flow-boundaries)). | Owner | Owns | |---|---| | Flow plugin | Intent, judgment, specs, delivery principles, reusable skills | | Starters | Optional, opinionated technology foundations | | Project scripts | The authoritative verification commands | | Native host | Sessions, worktrees, delegation, built-in review | `start` ends at the initial commit; discovery and deployment are separate work. Skills work alone and compose when useful: `explore` without `start`, `build` without a spec, `to-spec` without `to-tasks`, or `review` on any change. ### Keep people able to judge Agent speed creates costs that green checks do not show: code no one understands ([comprehension debt](https://addyosmani.com/blog/comprehension-debt/)), rationale no one wrote down ([intent debt](https://addyosmani.com/blog/intent-debt/)), and a review queue that grows with each agent ([orchestration tax](https://addyosmani.com/blog/orchestration-tax/)). Answer them selectively, not with a new phase or document: stop for direction changes and consequential uncertainty, record why in the specs and decisions the work already warrants, say what a person should understand before consequential work ships, and run only as much in parallel as someone can judge. Small, clear work proceeds without any of this. [Research note](https://github.com/gaboesquivel/flow-skills/blob/main/docs/research/2026-11-03-velocity-with-intent.md). ### Clarify intent Work backwards from the user outcome, keep doing nothing as an alternative, and offer the smallest investigation when one uncertainty blocks a choice. Before building something substantial, ask how the problem is solved today: an existing product, open-source tool, host feature, or manual workaround may already answer it, and adopting, integrating, deferring, or stopping are outcomes as valid as building; [`experience`](https://flow-skills-md.vercel.app/skills/experience) observes the finished journey. Sources: [research note](https://github.com/gaboesquivel/flow-skills/blob/main/docs/research/2026-11-04-judgment-and-experience.md). Combine focused questions, research, suggested directions, and exploration of alternatives. Reuse known context. Establish the intended outcome, consequential assumptions, existing evidence, and how the next test will inform a decision. When commercial context affects the decision, use the known customer, buyer, business model, distribution, and evidence of maturity to guide refinement. Ask only for missing context that matters to the current uncertainty. Optional product-discovery skills do not block delivery work. For a new product, keep the vision and core journeys broad while the active work stays bounded: the vision lives in `PRODUCT.md`, the [first useful release](https://flow-skills-md.vercel.app/docs/glossary#first-useful-release) bounds it, specs are independently deliverable increments, and tasks are their executable slices. [`to-spec`](https://flow-skills-md.vercel.app/skills/to-spec) decides how many specs the work needs ([decision 0066](https://flow-skills-md.vercel.app/docs/decisions/0066-specs-sized-by-delivery)). Specs say what and why; how is the agent's. Record bounded increments in `docs/specs/` when durable scope helps; record significant rationale in `docs/decisions/`. Small clear changes may need only conversation and code. ### Defend the delivery boundary For a new product or substantial feature, settle the delivery appetite early: a time target (and a cost limit when model, evaluation, or infrastructure spend is material), the first verifiable increment, and non-goals. Recover what is known and ask only for what is missing, with a suggested default. A small, understood change gets none of this. During delivery, new scope gets a [scope trade-off](https://flow-skills-md.vercel.app/docs/glossary#scope-trade-off) whether the user or an agent proposed it: defer, replace, reject, or expand the appetite, naming what changes. Review flags both unrequested additions and accepted behavior that went missing. Blockers to correctness, security, or required checks are never traded away to meet a target. Parallel work pays only when it saves more elapsed time than it costs to brief, start, and integrate. Elapsed time and cost are reported when observed and marked "not measured" otherwise. [`explore`](https://flow-skills-md.vercel.app/skills/explore#conversation) and [`to-spec`](https://flow-skills-md.vercel.app/skills/to-spec) capture the appetite, [`build`'s Scope guard](https://flow-skills-md.vercel.app/skills/build#scope-guard) defends it, ([decision 0053](https://flow-skills-md.vercel.app/docs/decisions/0053-delivery-appetite-and-scope)); `build` slices work with several outcomes and the host decides the fan-out ([Slices](https://flow-skills-md.vercel.app/skills/build#slices), decisions [0060](https://flow-skills-md.vercel.app/docs/decisions/0060-slice-by-area), [0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first), and [0066](https://flow-skills-md.vercel.app/docs/decisions/0066-specs-sized-by-delivery)). ### Observe and revisit Use One Metric That Matters (OMTM) when a measurable focus can guide the current product decision. Explain the uncertainty it addresses, define the population, calculation, time window, and data source, and establish a baseline or mark it unknown. Set a justified target and review point with the intended decision response; retain supporting evidence and guardrails. Early discovery may need qualitative evidence before a useful metric can be selected. [`align`](https://flow-skills-md.vercel.app/skills/align) evaluates evidence against these definitions and names what blocks a conclusion. Identify relevant product and system signals while planning the work. Assess findings against the intended outcome, record limitations, and decide whether to continue, change direction, or stop. Update affected context when a decision changes. Keep implementation correctness and evidence of customer value distinct. A working feature does not establish that it improved the intended outcome. An initiative's spec says, in one sentence, what should change for whom, what evidence will be looked at, and which decision it informs; delivery proves the evidence can be obtained, and the judgment comes after shipping, when unknowns stay unknown. A typo or internal cleanup needs none of this. Specific growth frameworks remain [proposals under assessment](https://github.com/gaboesquivel/flow-skills/blob/main/docs/research/2026-10-19-productskills-and-lean.md#business-context-growth-and-skill-boundaries). ### Design for the purpose Choose design priorities from what people need to do on each page or screen: decide and act, complete a task, understand information, or explore an experience. Keep shared visual decisions in DESIGN.md and page-specific intent in a small brief when needed. When the look is not settled, the [`design`](https://flow-skills-md.vercel.app/skills/design) skill compares rendered directions and records the one the user chooses. These practices are adapted from [Impeccable](https://github.com/gaboesquivel/flow-skills/blob/main/docs/research/2026-10-19-impeccable.md). ### Maintain connected context Keep product intent, experience design, and architecture distinct while allowing findings in one to inform the others. Use the [documentation guide](https://github.com/gaboesquivel/flow-skills/blob/main/docs/README.md) for ownership and [AGENTS.md](https://github.com/gaboesquivel/flow-skills/blob/main/AGENTS.md) for maintenance rules. Source assessments live in [research](https://github.com/gaboesquivel/flow-skills/tree/main/docs/research), indexed in [references](https://github.com/gaboesquivel/flow-skills/blob/main/docs/references.md). After meaningful changes, align root documents with [`sync-docs`](https://flow-skills-md.vercel.app/skills/sync-docs) or equivalent manual edits. Implementation work may update owning docs per [build](https://flow-skills-md.vercel.app/skills/build). ### Coordinate independent sessions Several sessions, in one host or several, can work on one repository without a coordinator. Discussion and single-writer work stay in the current checkout; Claude Code isolates genuinely concurrent writers in their own worktrees (`claude -w`, subagent worktree isolation) and sizes the fan-out; with the Flow plugin, a SessionStart report lists kept worktrees, unmerged branches, and open pull requests, and a guard hook blocks the destructive Git cases. Two rules stay with Flow: give parallel writers their own instance of any runtime state they would share (a database, port, or test account), and report sibling work you cannot see as unknown. This is best-effort: Git shows evidence, not locks, and two sessions can still race. The rules live in [`write-agents` Sessions](https://flow-skills-md.vercel.app/skills/write-agents#sessions) (decisions [0052](https://flow-skills-md.vercel.app/docs/decisions/0052-git-first-coordination) and [0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first)). ### Write context for agents and humans Use progressive disclosure: short routing in adopter instruction files when the project chooses to have them; root documents summarize their own concern; specs and decisions hold durable detail. Documentation should preserve intent, constraints, and information that is difficult to rediscover. Avoid exhaustive trees and descriptions that duplicate readily discoverable code. Shared documents must remain readable by humans. Keep a document's status apart from where it sits: a draft on `main` is still a draft, and an accepted change on a branch has not shipped. Sessions refresh only the owner sections and branch changes their work touches ([`write-agents` Context freshness](https://flow-skills-md.vercel.app/skills/write-agents#context-freshness)). At major handoffs, lead with a short digest of outcome, scope, verification, and the next action, and link the full spec or diff rather than pasting it. Assess documentation impact during implementation and review. Code establishes observed behavior; accepted documentation establishes intended behavior and constraints. When they diverge, identify which needs correction rather than silently treating either as justification to change the other. ### Documentation responsibilities These apply to manual work and skill use. They are not a fixed sequence. | Activity | Documentation responsibility | |---|---| | Exploration | Preserve worthwhile possibilities; link evidence when saving artifacts. | | Planning | Capture bounded scope in a spec file when the work warrants it; it is accepted before shipping ("build it" or "ship it" on a draft accepts it). Work without a spec is always allowed, in either delivery mode ([unspecced work](https://flow-skills-md.vercel.app/docs/glossary#unspecced-work)). The file is the record; in GitHub mode the pull request links it ([decision 0044](https://flow-skills-md.vercel.app/docs/decisions/0044-fast-delivery)). | | Execution | Update root context and specs when behavior or accepted intent changes. | | Review | Repair confirmed defects with evidence, record what stays open, and update decisions or root docs when conclusions matter ([`review` Repair](https://flow-skills-md.vercel.app/skills/review#repair); [understandable change](https://flow-skills-md.vercel.app/docs/principles#understandable-change)). | Create only the artifacts the work needs. ### Dogfood Use this when changing Flow. Apply the skills already in the catalog, in proportion to the work, on a realistic task. Prefer this repository first. Record the run next to the other smoke notes: the task, which skills were actually followed, what happened, and what was not run. Keep the two kinds of evidence apart: - **Structural checks** — `pnpm validate`, `pnpm test`, and smoke contracts, run in CI on ready pull requests ([decision 0057](https://flow-skills-md.vercel.app/docs/decisions/0057-draft-workspace-ready-checks)). They show that links, package metadata, and documentation path rules match the catalog; smoke contracts check safety rules by keyword, not skill wording ([decision 0044](https://flow-skills-md.vercel.app/docs/decisions/0044-fast-delivery)). - **Live agent verification** — a person or agent used a skill in a host. Name the host, the date, and what was observed. A structural pass is not a live run. One agent is not an independent review. CI makes no model calls; the optional LLM context review runs on request under the [pr-review-contract](https://github.com/gaboesquivel/flow-skills/blob/main/docs/pr-review-contract.md) and is not a substitute for human judgment on consequential changes. Do not add a dogfood skill, a required pipeline, or a second copy of the product statement for the record. Latest recorded run: [2026-10-27 start bootstrap](https://github.com/gaboesquivel/flow-skills/blob/main/tests/smoke/2026-10-27-start-bootstrap.md). ### Maintain shared language Use [GLOSSARY.md](https://flow-skills-md.vercel.app/docs/glossary) for project-specific meanings. Apply discipline through discussion and examples, informed by [domain language research](https://github.com/gaboesquivel/flow-skills/blob/main/docs/research/2026-10-20-domain-language.md). Every skill names things with resolved glossary terms, in specs, interfaces, code, and tests ([`domain-modeling` Shared language](https://flow-skills-md.vercel.app/skills/domain-modeling#shared-language)). When terms or consequential naming choices need active refinement, invoke the [`domain-modeling`](https://flow-skills-md.vercel.app/skills/domain-modeling) skill explicitly. Add a term when local meaning or ambiguity cannot be safely inferred. Record a meaning when resolved and update affected documentation and skill instructions when present. Loading the glossary does not require editing it; routine clarification does not require a decision record. --- ## Principles URL: https://flow-skills-md.vercel.app/docs/principles Source: https://github.com/gaboesquivel/flow-skills/blob/main/docs/principles.md (`docs/principles.md`) Status: elaboration, updated 2026-10-31. The eight official principles live in [PRODUCT.md](https://flow-skills-md.vercel.app/docs/product#principles). The themes below are optional methodology judgment; they do not replace that list. ### Validation Make assumptions explicit and use evidence to decide whether to continue, change direction, or stop. Measurement supports validation rather than standing as a separate principle. Identify the consequential uncertainty, the smallest useful test, and how its results will inform the next decision before increasing investment. Combine quantitative and qualitative evidence as appropriate; distinguish what was observed from what was inferred. ### Observability Make product and system behavior understandable from day one. Plan the signals needed to see what people and agents attempt, where they succeed or struggle, and how the system behaves. Connect technical diagnostics to product feedback so failures, delays, and usage patterns can inform product decisions. Collect evidence in context; technical health alone does not establish customer value. ### Agentic Elaborates the official **Agent-first, API-first** principle ([decision 0023](https://flow-skills-md.vercel.app/docs/decisions/0023-agent-first)). Build for agents and humans, with an API-first approach. Treat agent use as a first-class product interaction. Make relevant capabilities discoverable and usable through clear interfaces, including APIs, CLIs, and MCP where appropriate, alongside useful human experiences. Design permissions, errors, and results so an agent can act within the user's authority and understand the outcome. Contracts are tested first and UI is checked in the preview ([`build`](https://flow-skills-md.vercel.app/skills/build#tests) Tests, [decision 0056](https://flow-skills-md.vercel.app/docs/decisions/0056-contract-first-tests)). Flow's own agent works the same way: it uses those interfaces first and hands people only what needs them ([`write-agents`](https://flow-skills-md.vercel.app/skills/write-agents#tools) Tools). ### Understandable change Make software easy to understand and safe to change; require evidence proportional to what can go wrong. Work backward from the experience: decisions serve a meaningful user journey. Make quality observable: judge consequential experience through what was actually seen, not assumed from the implementation. Agent output does not establish understanding. Know what the code actually does, through shared domain language, contracts, and checks, and weigh what a change costs later: who depends on it, how hard it is to replace, what breaks if it fails. Small, contained work stays light; consequential work earns more evidence. A responding deployment is liveness, not verified behavior, and verified behavior is not customer value; "did it land" is a later question for [`align`](https://flow-skills-md.vercel.app/skills/align). ### Lean Use the least effort needed to learn or deliver something worthwhile. Test consequential uncertainty, limit concurrent scope, and prefer small experiments to speculative feature accumulation. Keep documentation and process proportionate. Reuse capabilities where they fit; avoid adding tools, interfaces, or ceremonies without a clear purpose. ### Velocity Move quickly with intent, and use feedback to correct direction. Shorten the path from an assumption to useful evidence and a decision. Progress may mean shipping, narrowing scope, changing direction, or stopping. Challenge purpose and evidence when it matters; let small tasks proceed with minimal ceremony. ### Critical thinking Direct agents without surrendering judgment. Say what and why, and let agents choose how. Keep enough understanding of what ships to decide, correct, and explain it. Architecture follows the same rule: the agent offers alternatives, trade-offs, and its reasoning so the person decides, and a sketch exists to answer one question. Apply this where a wrong answer is costly, never as a step every task must pass ([Keep people able to judge](https://flow-skills-md.vercel.app/docs/methodology#keep-people-able-to-judge)). ### Room for exploration Open exploration may begin with curiosity rather than a formal hypothesis. When it becomes a product commitment, make its intent and validation approach explicit. Apply these themes with judgment rather than as a checklist for every action. The [methodology](https://flow-skills-md.vercel.app/docs/methodology) describes optional practices. [References](https://github.com/gaboesquivel/flow-skills/blob/main/docs/references.md) preserve influences and research. Shipped [skills](https://flow-skills-md.vercel.app/skills) are reached by talking to the agent; none enforce these themes as a mandatory workflow. --- ## What Flow is URL: https://flow-skills-md.vercel.app/docs/product Source: https://github.com/gaboesquivel/flow-skills/blob/main/PRODUCT.md (`PRODUCT.md`) **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](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first)): 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](https://flow-skills-md.vercel.app/docs/decisions/0064-cursor-plugin)). 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](https://flow-skills-md.vercel.app/docs/decisions/0055-capability-based-github-and-host-triggered-builds), [spec 046](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/046-cloud-delivery.md)). ### 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](https://flow-skills-md.vercel.app/docs/decisions/0049-agent-does-the-work)). 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](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first)). 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](https://flow-skills-md.vercel.app/docs/principles) and [docs/methodology.md](https://flow-skills-md.vercel.app/docs/methodology) 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](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/035-delivery-phrases.md)). 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](https://flow-skills-md.vercel.app/docs/decisions/0053-delivery-appetite-and-scope)) | 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](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/041-skill-evaluation.md)). 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](https://github.com/gaboesquivel/flow-skills/blob/main/docs/research/2026-11-08-flow-alternatives.md)): 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](https://github.com/gaboesquivel/flow-skills/blob/main/tests/evals/records/2026-11-03-build-vs-no-skills.md); 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](https://github.com/gaboesquivel/flow-next)** / **[flow-mono](https://github.com/gaboesquivel/flow-mono)** | Independent application foundations (templates); [interop contract](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/005-flow-templates-interop.md) (candidate; owned by the template repositories) (supersedes [003](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/003-flow-templates-baseline-v2.md) for new work) | | **Flow website** ([`site/`](https://github.com/gaboesquivel/flow-skills/blob/main/site/README.md)) | Public home for the ecosystem: methodology, skill catalog, starters, docs, capability pages, and articles rendered from this repository ([spec 057](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/057-content-architecture.md)), with a `⌘K` palette for search and cited answers for people ([spec 040](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/040-site-refinement.md)), and `llms.txt`, Markdown, search, and MCP for agents ([spec 032](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/032-prism-website.md)) | | **[Flow Factory](https://github.com/gaboesquivel/flow-factory)** | Optional hosted, issue-driven orchestration and automated execution built on Flow—not Flow itself. [Flow mode](#flow-mode) is the in-session counterpart and does not depend on it. | Each piece has one job ([who owns what](https://flow-skills-md.vercel.app/docs/methodology#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](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/040-site-refinement.md)). 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](https://flow-skills-md.vercel.app/docs/methodology#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](https://flow-skills-md.vercel.app/docs/decisions/0004-portable-skill-catalog), [0005](https://flow-skills-md.vercel.app/docs/decisions/0005-misc-tldr-skill), [0006](https://flow-skills-md.vercel.app/docs/decisions/0006-flow-lite-and-flat-docs), [0007](https://flow-skills-md.vercel.app/docs/decisions/0007-flow-product-identity), [0008](https://flow-skills-md.vercel.app/docs/decisions/0008-leading-words-and-visual-summaries), [0009](https://flow-skills-md.vercel.app/docs/decisions/0009-adopter-product-context), [0010](https://flow-skills-md.vercel.app/docs/decisions/0010-optional-start-skill), [0013](https://flow-skills-md.vercel.app/docs/decisions/0013-restore-engineering-skills), [0014](https://flow-skills-md.vercel.app/docs/decisions/0014-handoff-skill), [0015](https://flow-skills-md.vercel.app/docs/decisions/0015-tasks-and-domain-modeling), [0016](https://flow-skills-md.vercel.app/docs/decisions/0016-start-in-place), [0017](https://flow-skills-md.vercel.app/docs/decisions/0017-claude-code-skill-coexistence), [0018](https://flow-skills-md.vercel.app/docs/decisions/0018-interview-extracts-intent), [0019](https://flow-skills-md.vercel.app/docs/decisions/0019-voice-first-invocation), [0020](https://flow-skills-md.vercel.app/docs/decisions/0020-flow-mode), [0021](https://flow-skills-md.vercel.app/docs/decisions/0021-autonomous-explore-and-ship), [0022](https://flow-skills-md.vercel.app/docs/decisions/0022-start-runs-explore), [0023](https://flow-skills-md.vercel.app/docs/decisions/0023-agent-first), [0024](https://flow-skills-md.vercel.app/docs/decisions/0024-gated-hand-offs), [0025](https://flow-skills-md.vercel.app/docs/decisions/0025-wave-checkpoints), [0026](https://flow-skills-md.vercel.app/docs/decisions/0026-process-depth), [0027](https://flow-skills-md.vercel.app/docs/decisions/0027-progress-board-skill), [0028](https://flow-skills-md.vercel.app/docs/decisions/0028-build-and-ship), [0029](https://flow-skills-md.vercel.app/docs/decisions/0029-spec-issues), [0030](https://flow-skills-md.vercel.app/docs/decisions/0030-asked-delivery-and-local-mode), [0031](https://flow-skills-md.vercel.app/docs/decisions/0031-fan-out-by-default), [0032](https://flow-skills-md.vercel.app/docs/decisions/0032-local-build-lands-ship-verifies), [0033](https://flow-skills-md.vercel.app/docs/decisions/0033-shared-files-and-reviewed-head), [0034](https://flow-skills-md.vercel.app/docs/decisions/0034-no-ceremony-without-a-spec), [0035](https://flow-skills-md.vercel.app/docs/decisions/0035-spec-issue-on-acceptance), [0036](https://flow-skills-md.vercel.app/docs/decisions/0036-one-explore-depth), [0037](https://flow-skills-md.vercel.app/docs/decisions/0037-git-for-delivery-github-for-github-mode), [0038](https://flow-skills-md.vercel.app/docs/decisions/0038-direction-changes-are-confirmed-and-recorded), [0039](https://flow-skills-md.vercel.app/docs/decisions/0039-build-never-requires-a-spec), [0040](https://flow-skills-md.vercel.app/docs/decisions/0040-ship-verifies-liveness), [0041](https://flow-skills-md.vercel.app/docs/decisions/0041-align-skill), [0042](https://flow-skills-md.vercel.app/docs/decisions/0042-outcome-build-and-ship), [0043](https://flow-skills-md.vercel.app/docs/decisions/0043-workers-when-they-pay), [0044](https://flow-skills-md.vercel.app/docs/decisions/0044-fast-delivery), [0046](https://flow-skills-md.vercel.app/docs/decisions/0046-measurement-assistance), [0048](https://flow-skills-md.vercel.app/docs/decisions/0048-delivery-phrases-are-approvals), [0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first)); 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`](https://flow-skills-md.vercel.app/skills/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](https://flow-skills-md.vercel.app/docs/decisions/0044-fast-delivery)). 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](https://flow-skills-md.vercel.app/docs/glossary#liveness) check ([decision 0048](https://flow-skills-md.vercel.app/docs/decisions/0048-delivery-phrases-are-approvals); [0024](https://flow-skills-md.vercel.app/docs/decisions/0024-gated-hand-offs)). Adopter `AGENTS.md`, `CLAUDE.md`, or equivalent files change only when you opt into [Flow mode](#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](https://flow-skills-md.vercel.app/docs/decisions/0009-adopter-product-context). #### Install and catalog **Install.** Three ways, from the same `skills/` tree ([decision 0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first), [decision 0064](https://flow-skills-md.vercel.app/docs/decisions/0064-cursor-plugin)): - **Claude Code plugin:** the skills plus the [guard hook](https://github.com/gaboesquivel/flow-skills/blob/main/hooks/guard.mjs) that blocks unsafe Git and merge operations, the [SessionStart report](https://github.com/gaboesquivel/flow-skills/blob/main/hooks/wip.mjs) of work in flight, and the [`flow-reviewer`](https://github.com/gaboesquivel/flow-skills/blob/main/agents/flow-reviewer.md) agent. The manifest is [`.claude-plugin/plugin.json`](https://github.com/gaboesquivel/flow-skills/blob/main/.claude-plugin/plugin.json); [agent compatibility](https://flow-skills-md.vercel.app/docs/agent-compatibility#claude-code) covers loading it and the recommended settings. - **Cursor plugin:** the same skills, guard, work-in-flight report, and reviewer. The manifest is [`.cursor-plugin/plugin.json`](https://github.com/gaboesquivel/flow-skills/blob/main/.cursor-plugin/plugin.json). Install this or the skills CLI, not both, and not also the Claude Code plugin. - **Any Agent Skills host:** `npx skills add gaboesquivel/flow-skills` via the [Agent Skills ecosystem](https://github.com/vercel-labs/skills). You get the skills and the method, without the hooks' enforcement. **Requirements.** What a skill needs depends on its tier ([decision 0037](https://flow-skills-md.vercel.app/docs/decisions/0037-git-for-delivery-github-for-github-mode)): | 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](https://flow-skills-md.vercel.app/docs/decisions/0055-capability-based-github-and-host-triggered-builds)) | | 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](https://flow-skills-md.vercel.app/docs/decisions/0044-fast-delivery)). Thinking skills may read Git when it exists. | Layer | Skills | | --- | --- | | Context alignment | [`sync-docs`](https://flow-skills-md.vercel.app/skills/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](https://flow-skills-md.vercel.app/docs/glossary#flow-block), which can override the inferred [delivery mode](https://flow-skills-md.vercel.app/docs/glossary#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`](https://flow-skills-md.vercel.app/skills/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](https://flow-skills-md.vercel.app/docs/skill-catalog)**. Say a skill's leading word ("interview me", "spec it", "ship it"); slash commands are optional. Every skill is reachable by phrase ([0019](https://flow-skills-md.vercel.app/docs/decisions/0019-voice-first-invocation)); `start` asks only what the request leaves open before it writes anything ([0022](https://flow-skills-md.vercel.app/docs/decisions/0022-start-runs-explore), amended by [0044](https://flow-skills-md.vercel.app/docs/decisions/0044-fast-delivery)). 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](https://flow-skills-md.vercel.app/docs/decisions/0044-fast-delivery), superseding the spec issue of [0029](https://flow-skills-md.vercel.app/docs/decisions/0029-spec-issues) and [0035](https://flow-skills-md.vercel.app/docs/decisions/0035-spec-issue-on-acceptance)). **Not shipped as skills:** validation-board UI or a progress board ([retired](https://flow-skills-md.vercel.app/docs/glossary#progress-board)), OMTM automation or analytics services (read-only measurement assistance ships in `align`, [decision 0046](https://flow-skills-md.vercel.app/docs/decisions/0046-measurement-assistance), [spec 034](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/034-measurement-support.md)), commercial discovery pipelines, or hosted orchestration (Flow Factory); the optional [issue trigger](https://flow-skills-md.vercel.app/docs/glossary#issue-trigger) runs on the host's own triggers, not a Flow service ([decision 0055](https://flow-skills-md.vercel.app/docs/decisions/0055-capability-based-github-and-host-triggered-builds)). Project initialization is the optional [`start`](https://flow-skills-md.vercel.app/skills/start) skill only (not a router or mandatory pipeline). Validation judgment lives in [methodology](https://flow-skills-md.vercel.app/docs/methodology) as practice; measurement never gates shipping. #### Flow mode Opt-in conversational delivery ([decision 0020](https://flow-skills-md.vercel.app/docs/decisions/0020-flow-mode), [spec 009](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/009-flow-mode.md)). Saying "set up Flow here" has `sync-docs` write one removable [Flow block](https://flow-skills-md.vercel.app/docs/glossary#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](https://flow-skills-md.vercel.app/docs/glossary#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](https://flow-skills-md.vercel.app/skills/build#slices), [decision 0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first)). 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](https://flow-skills-md.vercel.app/docs/glossary#liveness); "push it" pushes a branch ([`ship`](https://flow-skills-md.vercel.app/skills/ship)). With the plugin, the [guard hook](https://github.com/gaboesquivel/flow-skills/blob/main/hooks/guard.mjs) blocks force-pushes, pushes to the default branch, `--no-verify`, and admin merges whatever the model decides. Decisions [0028](https://flow-skills-md.vercel.app/docs/decisions/0028-build-and-ship), [0030](https://flow-skills-md.vercel.app/docs/decisions/0030-asked-delivery-and-local-mode), [0031](https://flow-skills-md.vercel.app/docs/decisions/0031-fan-out-by-default), [0032](https://flow-skills-md.vercel.app/docs/decisions/0032-local-build-lands-ship-verifies), [0042](https://flow-skills-md.vercel.app/docs/decisions/0042-outcome-build-and-ship), and [0043](https://flow-skills-md.vercel.app/docs/decisions/0043-workers-when-they-pay) record the earlier shapes; [0044](https://flow-skills-md.vercel.app/docs/decisions/0044-fast-delivery) amends them. [`build`](https://flow-skills-md.vercel.app/skills/build#delivery-mode) 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](https://flow-skills-md.vercel.app/docs/decisions/0013-restore-engineering-skills) restored `council`, `ship`, `prototype`, `simplify`, `security`, `performance`, and `debug`. [0014](https://flow-skills-md.vercel.app/docs/decisions/0014-handoff-skill) adds `handoff`. [0015](https://flow-skills-md.vercel.app/docs/decisions/0015-tasks-and-domain-modeling) renames `to-tasks` and restores `domain-modeling`. [0019](https://flow-skills-md.vercel.app/docs/decisions/0019-voice-first-invocation) retires `simplify`, `security`, and `performance` in favor of host tools. [0027](https://flow-skills-md.vercel.app/docs/decisions/0027-progress-board-skill) adds `board`. [0041](https://flow-skills-md.vercel.app/docs/decisions/0041-align-skill) adds `align`. [0046](https://flow-skills-md.vercel.app/docs/decisions/0046-measurement-assistance) adds `measure`. [0051](https://flow-skills-md.vercel.app/docs/decisions/0051-design-skill) adds `design`. [0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first) 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](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/059-claude-code-first.md) removes `jtbd`, `competitors`, and `write-humans`, which tied with no skill in an on-trial comparison. [0068](https://flow-skills-md.vercel.app/docs/decisions/0068-experience-skill) adds `experience`. [0070](https://flow-skills-md.vercel.app/docs/decisions/0070-research-and-clearer-names) 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](#success)); broader demand remains unvalidated. **Starting a project.** Invoke the optional [`start`](https://flow-skills-md.vercel.app/skills/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](https://flow-skills-md.vercel.app/docs/decisions/0022-start-runs-explore)). 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](https://flow-skills-md.vercel.app/docs/decisions/0067-flow-boundaries)). There is no `flow start` command; `sync-docs` must not be treated as initialization ([0010](https://flow-skills-md.vercel.app/docs/decisions/0010-optional-start-skill)). See [documentation guide](https://github.com/gaboesquivel/flow-skills/blob/main/docs/README.md) and [AGENTS.md](https://github.com/gaboesquivel/flow-skills/blob/main/AGENTS.md) for maintenance. --- ## Skill catalog reference URL: https://flow-skills-md.vercel.app/docs/skill-catalog Source: https://github.com/gaboesquivel/flow-skills/blob/main/docs/skills.md (`docs/skills.md`) Skills live in [`skills/`](https://flow-skills-md.vercel.app/skills); `scripts/validate.mjs` holds the authoritative list. Flow is Claude Code first ([decision 0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first), [decision 0064](https://flow-skills-md.vercel.app/docs/decisions/0064-cursor-plugin)): install it as a Claude Code plugin or a Cursor plugin to get the skills plus the guard hook, the session report of work in flight, and the `flow-reviewer` agent, or run `npx skills add gaboesquivel/flow-skills` on any Agent Skills host for the skills alone ([agent compatibility](https://flow-skills-md.vercel.app/docs/agent-compatibility#installation)). No mandatory sequence. Skills may name the next skill and wait; the only automatic hand-off is `start` → `explore`, when the request describes the product and behind the user's yes. Plugin, starters, project scripts, and host each [own one job](https://flow-skills-md.vercel.app/docs/methodology#who-owns-what). `build` slices work with several outcomes, and the host sizes the fan-out under its concurrency cap ([Slices](https://flow-skills-md.vercel.app/skills/build#slices), [decision 0060](https://flow-skills-md.vercel.app/docs/decisions/0060-slice-by-area) as amended by [0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first)). Substantial work names its [delivery appetite](https://flow-skills-md.vercel.app/docs/glossary#delivery-appetite), and new scope mid-flight gets a [scope trade-off](https://flow-skills-md.vercel.app/docs/glossary#scope-trade-off). "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; each ends with a [liveness](https://flow-skills-md.vercel.app/docs/glossary#liveness) check ([decision 0048](https://flow-skills-md.vercel.app/docs/decisions/0048-delivery-phrases-are-approvals), amending [0044](https://flow-skills-md.vercel.app/docs/decisions/0044-fast-delivery); [decision 0024](https://flow-skills-md.vercel.app/docs/decisions/0024-gated-hand-offs)). [Agent compatibility](https://flow-skills-md.vercel.app/docs/agent-compatibility) · [Decision 0006](https://flow-skills-md.vercel.app/docs/decisions/0006-flow-lite-and-flat-docs) · [Decision 0009](https://flow-skills-md.vercel.app/docs/decisions/0009-adopter-product-context) · [Decision 0015](https://flow-skills-md.vercel.app/docs/decisions/0015-tasks-and-domain-modeling) · [Decision 0019](https://flow-skills-md.vercel.app/docs/decisions/0019-voice-first-invocation) · [Decision 0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first) · [Spec 002](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/002-flow-lite-and-flat-docs.md) · [Spec 059](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/059-claude-code-first.md) Talk to your agent, by typing or dictation. Each skill has a [leading word](https://flow-skills-md.vercel.app/docs/glossary#leading-word): the phrase you say to reach it. Each row below gives that phrase, what you get, and what it writes; the skill link has the procedure. Most descriptions carry two or more variants, while "build it" keeps one so dictation cannot blur it. Slash commands (`/explore`, `/ship`, …) remain optional shortcuts. No skill must be named explicitly. ### Process 1. **Install** — the Claude Code plugin, the Cursor plugin, or the Agent Skills CLI, which copies this repository's `skills/` tree into the agent you choose. One of those, not several. 2. **Work** — Build your product and say what you want; "sync the docs" updates root context with **`sync-docs`**. Work needs no spec unless you want one: say "build it" for [unspecced work](https://flow-skills-md.vercel.app/docs/glossary#unspecced-work), or just ask your agent ([work without a spec](https://flow-skills-md.vercel.app/docs/get-started#work-without-a-spec)). 3. **Document** — When saving artifacts, default to `docs/specs/NNN-short-name.md` and `docs/decisions/NNN-short-name.md` unless the project already uses something else. The delivery skills and the paths between them are drawn in the README: [how it works](https://flow-skills-md.vercel.app/docs/get-started#how-it-works). Every step is skippable; there is no required order. Product discovery, writing, advisory, experience, and design skills are optional and do not block delivery. ### Which one? | You say | You get | Writes | | --- | --- | --- | | Native Plan (Shift+Tab, `/plan`) | A plan for how to implement a change you already chose | Nothing until you approve | | "Explore this" | A partner that knows your goals and constraints, asks how the problem is solved today, and helps decide whether and what to build and how you'll know | Nothing; an agreed brief on request | | "Research X", "competitors for X" | A dated, sourced note another session can decide from | The note and an existing index; "just tell me here" stays in chat | | "Check alignment" | Whether the product still fits its goals and what the outcome evidence shows | Nothing | | "Sync the docs" | Root docs updated to match accepted direction | The affected root docs | ### Context alignment | Skill | Say | What happens | | --- | --- | --- | | [sync-docs](https://flow-skills-md.vercel.app/skills/sync-docs) | "sync the docs" | Updates `PRODUCT.md`, `DESIGN.md`, `GLOSSARY.md`, and `ARCHITECTURE.md` to accepted direction after meaningful changes; drafts and Proposed records stay labeled as proposals. "Set up Flow here" writes the opt-in [Flow block](https://flow-skills-md.vercel.app/docs/glossary#flow-block), touching no adopter text outside it, and refreshes an older block in place, keeping its `Delivery:` line. **Writes** those files. Not template initialization ([decision 0070](https://flow-skills-md.vercel.app/docs/decisions/0070-research-and-clearer-names)). | ### Delivery | Skill | Say | What happens | | --- | --- | --- | | [explore](https://flow-skills-md.vercel.app/skills/explore) | "explore this" | A product-engineering conversation that reads the project's goals, commitments, and constraints first; for substantial work asks how the problem is solved today and can recommend adopting, integrating, testing, deferring, stopping, or a differentiated slice; names a diverging commitment and asks whether it is an experiment or a pivot; settles the outcome sentence when an idea becomes an initiative. "Interview me" and "grill this" change the style. **Writes nothing**; an agreed new-product brief goes to `PRODUCT.md` on request ([decision 0069](https://flow-skills-md.vercel.app/docs/decisions/0069-direction-changes-at-adoption)). | | [to-spec](https://flow-skills-md.vercel.app/skills/to-spec) | "spec it" | A numbered draft spec: what and why, an Outcome sentence for initiatives, [Exposure](https://flow-skills-md.vercel.app/docs/glossary#exposure), and an [acceptance scenario](https://flow-skills-md.vercel.app/docs/glossary#acceptance-scenario); decides one spec or several. "Accept the spec", or "build it" or "ship it" on a draft, accepts it and only the records it links ([the rule](https://flow-skills-md.vercel.app/skills/to-spec#status-and-acceptance)). **Writes** the spec and any Proposed record on the work's branch; no issue unless asked. | | [to-tasks](https://flow-skills-md.vercel.app/skills/to-tasks) | "break it down" | Vertical-slice tasks with blockers and an [area](https://flow-skills-md.vercel.app/docs/glossary#area) each, and the ready set. **Writes** the spec's Tasks checklist. | | [build](https://flow-skills-md.vercel.app/skills/build) | "build it" | The identified work implemented, reviewed at its risk tier, checked once, and [live](https://flow-skills-md.vercel.app/docs/glossary#liveness) on its branch, never merged. **Writes** a branch: a ready pull request (GitHub mode) or a commit (local mode). [Unspecced work](https://flow-skills-md.vercel.app/docs/glossary#unspecced-work) needs no spec. | | [review](https://flow-skills-md.vercel.app/skills/review) | "review it" | A fresh-context review through [`flow-reviewer`](https://github.com/gaboesquivel/flow-skills/blob/main/agents/flow-reviewer.md) on top of `/code-review`, with [requirement verdicts](https://flow-skills-md.vercel.app/docs/glossary#requirement-verdict), scope, glossary, and `DESIGN.md` checks. **Writes** fixes for confirmed defects; "review only" writes nothing. | | [ship](https://flow-skills-md.vercel.app/skills/ship) | "ship it" | The work landed on the default branch with no confirmation, built first when needed, and the shipped commit's [liveness](https://flow-skills-md.vercel.app/docs/glossary#liveness). "Push it" pushes a branch with no pull request. **Writes** the default branch ([0048](https://flow-skills-md.vercel.app/docs/decisions/0048-delivery-phrases-are-approvals)). | ### Product discovery | Skill | Say | What happens | | --- | --- | --- | | [research](https://flow-skills-md.vercel.app/skills/research) | "research X" | A sourced note answering the question, or a competitive brief for "competitors for X": the decision it serves, findings marked observed, claimed, or inferred, limits, and implications, updating a current note instead of duplicating it. **Writes** the note and an existing index; "just tell me here" answers in chat, and "should we research…?" is discussion ([decision 0070](https://flow-skills-md.vercel.app/docs/decisions/0070-research-and-clearer-names)). | | [align](https://flow-skills-md.vercel.app/skills/align) | "check alignment" | The product compared with its goals, problems, and metrics, and each outcome with the evidence ("did it land", "are we building the right thing"); shipped with impact unknown is a valid answer. **Writes nothing** (decisions [0041](https://flow-skills-md.vercel.app/docs/decisions/0041-align-skill), [0046](https://flow-skills-md.vercel.app/docs/decisions/0046-measurement-assistance), [0070](https://flow-skills-md.vercel.app/docs/decisions/0070-research-and-clearer-names)). | ### Shared language | Skill | Say | What happens | | --- | --- | --- | | [domain-modeling](https://flow-skills-md.vercel.app/skills/domain-modeling) | "what do we call this" | Settled project terms. **Writes** `GLOSSARY.md`; decision records sparingly. | ### Advisory | Skill | Say | What happens | | --- | --- | --- | | [council](https://flow-skills-md.vercel.app/skills/council) | "ask the council" | Independent perspectives on a consequential decision. **Writes nothing**. | | [experience](https://flow-skills-md.vercel.app/skills/experience) | "walk the experience" | A walk of a running product as its user, with reproduction steps, impact, and confidence for each friction found ([decision 0068](https://flow-skills-md.vercel.app/docs/decisions/0068-experience-skill)). **Writes nothing**. | ### Design | Skill | Say | What happens | | --- | --- | --- | | [design](https://flow-skills-md.vercel.app/skills/design) | "design this" | Two to four rendered visual directions; you choose. **Writes** the chosen direction to `DESIGN.md` with its assets ([decision 0051](https://flow-skills-md.vercel.app/docs/decisions/0051-design-skill)). "Prototype this" or "spike it" builds a throwaway. | Debugging, code simplification, security audits, and performance work belong to the host ([0019](https://flow-skills-md.vercel.app/docs/decisions/0019-voice-first-invocation), [0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first)). ### Writing | Skill | Say | What happens | | --- | --- | --- | | [write-agents](https://flow-skills-md.vercel.app/skills/write-agents) | "write agent instructions" | Agent instructions with one home per fact; owns the shared Sessions, Context freshness, and Tools rules. **Writes** the instruction files you name. | ### Project start | Skill | Say | What happens | | --- | --- | --- | | [start](https://flow-skills-md.vercel.app/skills/start) | "start a Next.js project" | A verified project from flow-next or flow-mono, with `explore` alongside when the request describes a product; asks only what the request leaves open ([spec 033](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/033-template-fast-start.md)). **Writes** the renamed project, baseline root docs, the Flow block, and one initial commit, its done signal ([0067](https://flow-skills-md.vercel.app/docs/decisions/0067-flow-boundaries)). | ### Retired [Decision 0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first) moved these to Claude Code or into other skills: `interview` and `grill` (now `explore`), `align` and `measure` (merged as `product`, renamed `align` by [decision 0070](https://flow-skills-md.vercel.app/docs/decisions/0070-research-and-clearer-names)), `prototype` (now `design`), `push` (now `ship`), `handoff` and `tldr` (the host's sessions, transcripts, and recaps), `debug` and `retro` (the host), and `board` (a maintainer script until 2026-11-03, then removed; spec status lines, pull requests, and the SessionStart work-in-flight report cover it). [Spec 059](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/059-claude-code-first.md) removed `jtbd`, `competitors`, and `write-humans`: each tied with no skill in an on-trial comparison; competitive briefs return through `research` ([spec 070](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/070-product-engineering-partner.md)). **Renamed in [decision 0070](https://flow-skills-md.vercel.app/docs/decisions/0070-research-and-clearer-names):** `product` is `align` and `flow` is `sync-docs`. Natural phrases still reach them; explicit paths move (`/flow:product` → `/flow:align`, `/flow:flow` → `/flow:sync-docs`, or `/align` and `/sync-docs` on Agent Skills hosts). An existing Flow block that names `flow` is refreshed on the next "set up Flow here" or "sync the docs". An Agent Skills install from before the rename can leave `flow/` and `product/` beside the new folders, both answering the same phrases: remove the old two (`pnpm context` reports the drift). `flow` remains the plugin and project name. ### Maintain (this repository) ```bash pnpm validate pnpm test ``` Edit skill source under `skills/` directly. [Attribution](https://github.com/gaboesquivel/flow-skills/blob/main/ATTRIBUTION.md) and per-skill notices apply where material was adapted. --- ## Agent and host compatibility URL: https://flow-skills-md.vercel.app/docs/agent-compatibility Source: https://github.com/gaboesquivel/flow-skills/blob/main/docs/agent-compatibility.md (`docs/agent-compatibility.md`) Flow skills target the [Agent Skills](https://agentskills.io) package layout: `skills//SKILL.md` with YAML frontmatter. The [skill catalog](https://flow-skills-md.vercel.app/docs/skill-catalog) lists every package, the leading word for each, and when to use each. ### Installation | Mechanism | Notes | | --- | --- | | Claude Code plugin | Primary path ([decision 0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first)). The repository root is the plugin: [`.claude-plugin/plugin.json`](https://github.com/gaboesquivel/flow-skills/blob/main/.claude-plugin/plugin.json), `skills/`, [`hooks/hooks.json`](https://github.com/gaboesquivel/flow-skills/blob/main/hooks/hooks.json), and [`agents/`](https://github.com/gaboesquivel/flow-skills/blob/main/agents/flow-reviewer.md). [`.claude-plugin/marketplace.json`](https://github.com/gaboesquivel/flow-skills/blob/main/.claude-plugin/marketplace.json) makes the repository its own marketplace: `claude plugin marketplace add gaboesquivel/flow-skills`, then `claude plugin install flow@flow-skills`. A user-scope install reaches the terminal, the desktop app, and IDE extensions, not cloud sessions. Added from a local clone path instead, the plugin loads in place: edits apply at the next session or `/reload-plugins`. `claude --plugin-dir ` loads a clone for one session. Adds the [plugin hooks](#claude-code) and the `flow-reviewer` agent. | | Cursor plugin | [`.cursor-plugin/plugin.json`](https://github.com/gaboesquivel/flow-skills/blob/main/.cursor-plugin/plugin.json) discovers the same `skills/`, `agents/`, and the hooks in [`hooks/cursor-hooks.json`](https://github.com/gaboesquivel/flow-skills/blob/main/hooks/cursor-hooks.json). The scripts are the Claude Code ones; the events are `beforeShellExecution` and `sessionStart`. Install this or `npx skills add`, not both, and not also the Claude Code plugin. Cursor cloud agents run the shell guard and do not run `sessionStart` ([decision 0064](https://flow-skills-md.vercel.app/docs/decisions/0064-cursor-plugin)). **Local testing:** copy the tree into `~/.cursor/plugins/local/flow` (symlinks to a checkout elsewhere are skipped). From a clone, run `node scripts/sync-cursor-local-plugin.mjs [ref]` (default `origin/main`), then **Developer: Reload Window** and confirm the plugin under Customize. On Enterprise, an admin must allow local plugin imports. | | `npx skills add gaboesquivel/flow-skills` | Skills only, no hooks or reviewer agent, wherever the [skills CLI](https://github.com/vercel-labs/skills) is supported. Choose agent and scope in the installer; Flow does not default to one product. | | Host skill UI | Some IDEs import a Git URL or local folder directly; behavior matches that host's skill loader. | | Manual copy | Copy `skills/*` into the host's expected skills directory. You are responsible for paths and updates. | Flow does not modify adopter `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, or similar files, except the opt-in Flow block below. ### Invocation | Host style | How users run Flow | | --- | --- | | Talking or dictation | Say a skill's [leading word](https://flow-skills-md.vercel.app/docs/glossary#leading-word) ("interview me", "spec it", "ship it"); hosts that honor descriptions match the skill. This is the primary interface ([decision 0019](https://flow-skills-md.vercel.app/docs/decisions/0019-voice-first-invocation)). | | Slash commands | `/flow`, `/to-spec`, `/build`, … when the host maps skill names to commands | | Skill picker | Explicit selection by skill name | Every skill is model-invocable. Matching a phrase to a skill is probabilistic: hosts choose from descriptions, and dictation can mishear. For that reason `start` asks what the request leaves open before writing ([decision 0022](https://flow-skills-md.vercel.app/docs/decisions/0022-start-runs-explore), amended by [0044](https://flow-skills-md.vercel.app/docs/decisions/0044-fast-delivery)), each delivery skill keeps one narrow trigger set ("build it"; "ship it", "push it", or "deploy it"; [decision 0048](https://flow-skills-md.vercel.app/docs/decisions/0048-delivery-phrases-are-approvals)), `build` never merges or writes to the default branch and has every change reviewed by a second agent in a fresh context at the effort its risk tier sets, "push it" touches the default branch only when it is current or named, the plugin's guard hook blocks force-pushes and pushes to the default branch regardless, and a draft that `to-spec` cannot accept stops "build it" or "ship it", so a misheard phrase cannot land an unaccepted spec or an unreviewed risky change; neither asks for a confirmation (decisions [0028](https://flow-skills-md.vercel.app/docs/decisions/0028-build-and-ship), [0039](https://flow-skills-md.vercel.app/docs/decisions/0039-build-never-requires-a-spec), and [0044](https://flow-skills-md.vercel.app/docs/decisions/0044-fast-delivery)). Skills may name the next skill and wait; the only automatic hand-off is `start` → `explore`, behind the user's yes ([decision 0024](https://flow-skills-md.vercel.app/docs/decisions/0024-gated-hand-offs)). **Root context alignment** is not guaranteed by implicit `sync-docs` invocation alone. Hosts may skip alignment on ordinary implementation work. The portable contract is: `build` and `review` remind agents to align the current project's `PRODUCT.md`, `DESIGN.md`, `GLOSSARY.md`, and `ARCHITECTURE.md` when meaningful changes warrant it; adopters can also say "sync the docs". **Pull request automation** (optional, per repository): [pr-review-contract.md](https://github.com/gaboesquivel/flow-skills/blob/main/docs/pr-review-contract.md) is agent-agnostic — any IDE or model can follow it before opening a PR. This repository runs it on request with an OpenAI-compatible API, never in CI; `main` requires a pull request plus passing `validate` and `pr-title` checks. Flow skills do not install workflows or edit adopter instruction files beyond the opt-in Flow block; copy the contract and script when adopting the pattern. That alignment updates the **current project's** product context. It does not copy this repository's Flow identity into an adopter `PRODUCT.md`. [Decision 0009](https://flow-skills-md.vercel.app/docs/decisions/0009-adopter-product-context). `sync-docs` is not a project-start command. Only a `start` request authorizes scaffolding. The optional [`start`](https://flow-skills-md.vercel.app/skills/start) skill initializes from flow-next or flow-mono, asking only what the request leaves open; the initial commit is its done signal ([decision 0067](https://flow-skills-md.vercel.app/docs/decisions/0067-flow-boundaries)). When the request describes the product, a worker runs the bootstrap while the main session runs `explore`; hosts without workers bootstrap first, then explore. It does not invoke `sync-docs` automatically. Metadata and contract tests show the intended invocation split. They do not show that a host matched a spoken phrase to the right skill. Claude Code is recorded as a second agent product for read-only runs; see [smoke scenario status](https://github.com/gaboesquivel/flow-skills/blob/main/tests/smoke/2026-10-27-scenario-status.md). ### Flow mode "Set up Flow here" writes one Flow block between `` and `` in the instruction file Git tracks: `AGENTS.md` when tracked, otherwise `CLAUDE.md`, which then imports `@AGENTS.md` so Claude Code sees both ([decision 0020](https://flow-skills-md.vercel.app/docs/decisions/0020-flow-mode); the [`sync-docs`](https://flow-skills-md.vercel.app/skills/sync-docs#flow-block) skill owns the layout). Every host that reads the file sees the block; on hosts without the plugin's SessionStart report, it is the portable stand-in for one. Re-running updates the block in place, including a block from before [decision 0070](https://flow-skills-md.vercel.app/docs/decisions/0070-research-and-clearer-names) that names the `flow` skill (its `Delivery:` line is kept); deleting it opts out. `build` slices work with several outcomes, and the host decides whether each slice runs as a subagent, a `/batch` unit, or inline under its concurrency cap ([Slices](https://flow-skills-md.vercel.app/skills/build#slices), [decision 0060](https://flow-skills-md.vercel.app/docs/decisions/0060-slice-by-area) as amended by [0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first)); the rules for parallel writers live in [`write-agents`](https://flow-skills-md.vercel.app/skills/write-agents#sessions). Hosts without workers run the same steps in sequence. The [delivery mode](https://flow-skills-md.vercel.app/docs/glossary#delivery-mode) is inferred, never asked; the block's `Delivery:` line or the request overrides it. The rule lives in [`build`](https://flow-skills-md.vercel.app/skills/build#delivery-mode). `build` ends with a reviewed, checked branch in both modes and [`ship`](https://flow-skills-md.vercel.app/skills/ship) lands it. Issues open only on request. [Liveness](https://flow-skills-md.vercel.app/docs/glossary#liveness) needs only Git, the host's deployment status, and one HTTP request; no browser tool. **Dogfooding in this repository.** `.claude/skills` is a symlink to `skills/`, so Claude Code sessions here load the working-tree skills; `pnpm validate` fails if the link breaks. Other hosts read the source tree directly or install it with the skills CLI. ### Metadata Policy ([decision 0019](https://flow-skills-md.vercel.app/docs/decisions/0019-voice-first-invocation), amended by [0022](https://flow-skills-md.vercel.app/docs/decisions/0022-start-runs-explore)): | Skill | `disable-model-invocation` | `allow_implicit_invocation` (adapter) | | --- | --- | --- | | All skills | `false` | `true` | Each model-invocable description ends with `Use when the user says "…"` and two or three trigger phrases; the validator enforces the form. **Observed support varies.** Confirm behavior in your host's skill documentation. Hosts that ignore adapter files rely on frontmatter and user invocation only. Core skill bodies avoid naming a single vendor tool, subagent API, or filesystem layout. Hosts may still expose different tools; skills describe outcomes and fallbacks in generic terms. ### Claude Code Claude Code ships built-ins that overlap with parts of the method. Flow delegates to them and keeps only what they lack: intent, durable artifacts, spec verdicts, and the delivery gotchas ([decision 0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first), amending [0017](https://flow-skills-md.vercel.app/docs/decisions/0017-claude-code-skill-coexistence)). | Flow | Built-in | Use Flow when | | --- | --- | --- | | `review` | `/code-review` | Always: the `flow-reviewer` agent runs `/code-review` at the size guard's tier and adds scenario verdicts, scope, glossary, and `DESIGN.md` checks. | | `explore` | Plan mode | Plan mode plans how to implement a change already chosen; Flow does not claim "plan". Say "explore this" to decide whether and what to build, and "spec it" or "break it down" when the plan should last. | | `sync-docs`, `start` | `/init`, memory | Product facts belong in root context files. Keep `CLAUDE.md` and memory as pointers, not copies. | | — | Sessions, worktrees (`claude -w`), `/fork`, compaction, transcripts | Flow retired `handoff`, `tldr`, and `retro`; the host owns hand-offs, recaps, and session history. | | — | Debugging | Flow retired `debug`; ask the agent directly. | | `to-tasks` | Session task list | Work needs durable vertical slices or tracker issues. | Flow retired `simplify`, `security`, and `performance` in favor of `/simplify`, `/security-review`, and host tooling ([decision 0019](https://flow-skills-md.vercel.app/docs/decisions/0019-voice-first-invocation)). "Review the code" reaches `/code-review` alone; "review it" or "check it against the spec" reaches Flow `review`, which runs `/code-review` too. #### Recommended Claude Code settings Documented, not forced; set them in your own `settings.json` ([spec 059](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/059-claude-code-first.md), [decision 0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first)): - **`worktree.baseRef: "head"`.** Host worktrees (`claude -w`, subagent `isolation: worktree`) start from the current branch's head, so a slice starts from the delivery branch instead of the default branch ([worktrees](https://code.claude.com/docs/en/worktrees.md)). - **`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` between 4 and 6.** `build` slices work with several outcomes and lets the host size the fan-out; the cap keeps parallel writers, and the runtime state they share, within what one machine and review can absorb ([sub-agents](https://code.claude.com/docs/en/sub-agents.md)). **Plugin hooks.** Installed as a plugin, Flow registers two hooks from [`hooks/hooks.json`](https://github.com/gaboesquivel/flow-skills/blob/main/hooks/hooks.json) ([hooks](https://code.claude.com/docs/en/hooks.md)). The PreToolUse guard on `Bash` ([`guard.mjs`](https://github.com/gaboesquivel/flow-skills/blob/main/hooks/guard.mjs)) denies force-pushes, pushes to the default branch, `--no-verify`, `gh pr merge --admin`, destructive worktree commands outside the session's directory, and merges whose required checks are not green. The SessionStart report ([`wip.mjs`](https://github.com/gaboesquivel/flow-skills/blob/main/hooks/wip.mjs)) adds kept worktrees, local branches with commits not on the default branch, and open pull requests (when `gh` works) to the new session's context, and prints nothing when there are none or on any error. Both only read; neither writes. They run with your Git and `gh` credentials, and branch protection stays the server-side backstop. The Cursor plugin runs the same scripts from [`hooks/cursor-hooks.json`](https://github.com/gaboesquivel/flow-skills/blob/main/hooks/cursor-hooks.json): `guard.mjs` answers `beforeShellExecution`, and `wip.mjs` answers `sessionStart` in the IDE. Cursor cloud agents run the shell guard only. `npx skills add` installs the skills without the hooks. Hosts offer no portable skill priority. Each skill's description carries its phrases, and the [skill catalog](https://flow-skills-md.vercel.app/docs/skill-catalog) lists them; you may copy the ones you rely on into your own user-level instructions (for example `~/.claude/CLAUDE.md`). Flow never writes user-level files. ### Native sessions Since [decision 0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first), Flow leaves sessions and worktrees to the host and keeps only two rules in [`write-agents`](https://flow-skills-md.vercel.app/skills/write-agents#sessions): isolate shared runtime state, and report sibling work you cannot see. This table is historical context from [decision 0054](https://flow-skills-md.vercel.app/docs/decisions/0054-native-capability-first-sessions) and [spec 045](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/045-native-observable-sessions.md). What each host exposed, as of 2026-10-31 ([research](https://github.com/gaboesquivel/flow-skills/blob/main/docs/research/2026-10-31-native-sessions.md)): | Host and surface | Exposed to the agent | Limits | | --- | --- | --- | | Claude Code Desktop | Start a session (fresh or forked, own worktree or shared), list sessions it started, message one by ID, hand its own task off. The parent is woken when its linked sessions end a turn, with each child's latest report quoted to 400 characters. Bind a pull request so the app wakes the session on checks, conflicts, and comments. `sync_with_base_branch` merges the base into an app-made worktree. | The app's guidance sends pieces of one task to subagents unless the user asks for sessions; after the user accepts a plan, the agent proposes each independent step as a session card (at most four) and starts its own step. Merging a session's branch needs the user's word, asked with full refs ([spec 052](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/052-native-session-integration.md)); the app forbids polling CI. A session started from a plain checkout does not start at the delivery head. Desktop does not list every CLI or cloud session. A parent-child tree is not verified. | | Claude Code CLI | Resume by ID or name; `--fork-session`; `claude agents` monitors background sessions. | Agent-driven creation and UI linkage depend on the installed version. | | Cursor | CLI `/fork` and `/resume`. | No agent-callable session API, transcript access, or tree established; IDE agent surfaces not inspected. Work in sequence or subagents. | | Other hosts | — | Portable floor: isolated writers, honest limits, sequential fallback. | No host run has yet started, inspected, interrupted, and resumed a child session under these rules; the [spec's acceptance scenario](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/045-native-observable-sessions.md#testing-decisions) remains open. Re-check the host's tools and version before relying on a row. ### Claude Code cloud Cloud sessions (Claude Code on the web, the mobile app, `claude --cloud`) run Flow with the same phrases ([decision 0055](https://flow-skills-md.vercel.app/docs/decisions/0055-capability-based-github-and-host-triggered-builds), [spec 046](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/046-cloud-delivery.md)). Host facts from Claude Code's [cloud environment](https://code.claude.com/docs/en/cloud-environments.md), [routines](https://code.claude.com/docs/en/routines.md), and [usage monitoring](https://code.claude.com/docs/en/monitoring-usage.md) docs, read 2026-10-31: - **GitHub through a proxy.** `gh` is installed and its token is proxy-injected; GraphQL is blocked, so `gh pr` and `gh issue` return 403 while `gh api` REST calls and the host's GitHub tools work. `ship`'s `gh-route.mjs` script picks the working route, falling back to REST when GraphQL is refused. The proxy refuses branch deletion; branch protection on GitHub still governs `main`. - **Only repository context loads.** `CLAUDE.md`, `.claude/settings.json`, and `.claude/skills` come from the clone; `~/.claude` (user instructions, user-scope skills and hooks) does not. Install Flow at project scope and commit it; a user-scope install never reaches a cloud session. Whether a symlinked `.claude/skills` loads is checked by the spec's live run. - **Setup.** An environment's setup script or a repository `SessionStart` hook installs dependencies; repository hooks do not run in multi-repository sessions. Flow itself needs nothing beyond Git and the skills. - **Moving between local and cloud.** `claude --teleport` continues a cloud session locally (clean tree, branch pushed); `claude --cloud "task"` starts one from the terminal. The SessionStart report lists the branch and pull request either way. - **Cost.** Cloud sessions keep no local transcript; per-session cost comes only from OpenTelemetry (`claude_code.cost.usage`, keyed by session) set on the environment. `pnpm metrics --usage ` reads an export of it; otherwise cloud cost is unknown. **Issue trigger (optional).** A routine starts a cloud `build` when a repository writer adds the `build-it` label to an issue ([`build` Issue trigger](https://flow-skills-md.vercel.app/skills/build#issue-trigger)). Ask the agent to create it with the host's scheduling tools (`/schedule`, or the remote-trigger API); the sign-in and the GitHub App consent are yours. Its settings: the repository; no connectors; a GitHub app trigger on `issues.labeled` (the webhook API takes no label filter, and the session receives the issue number in its trigger context); and a stored prompt such as: `A GitHub issues.labeled event fired. If the added label is not exactly build-it, write nothing and stop. Otherwise: build it: that issue, started by the build-it label. First run the build skill's issue-trigger script; if it exits non-zero, comment its reason and stop.` The routine runs as your account and pushes work branches. Its docs do not say who may fire the trigger, so `build`'s gate script (`skills/build/scripts/issue-trigger.mjs`) decides: the labeler and the issue's author need `write` or `admin`. The proxy refuses `collaborators/{user}/permission`; the script treats a user-owned repository's owner as admin, falls back to the collaborators list, and fails closed when neither answers. A live run on 2026-10-31 found that skill text alone did not stop a session when that read failed ([record](https://github.com/gaboesquivel/flow-skills/blob/main/tests/smoke/2026-10-31-cloud-delivery-live.md)). Routines are a research preview with hourly caps. ### Cloud starter setup Flow starters set up both cloud hosts for [spec 048](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/048-delivery-lifecycle.md): the draft pull request is the shared workspace, and no git hooks are installed. As of 2026-10-31: - **Cursor cloud agents** read `AGENTS.md` and the committed `.agents/skills` and `.claude/skills`. The Cursor plugin's shell guard runs once the agent can write; `sessionStart` does not run there. Starters commit `.cursor/environment.json` with an idempotent `install` (`corepack enable && pnpm install --frozen-lockfile`), tracked through a `.gitignore` exception; an environment saved in Cursor's settings or set up by its agent may take precedence over the file. Unverified live (model usage was rate limited on 2026-10-31). - **Claude Code cloud** loads the repository's `CLAUDE.md`, `.claude/skills`, and `.claude/settings.json` hooks. Starters install dependencies from a `SessionStart` hook that runs only when `CLAUDE_CODE_REMOTE=true`. Whether a symlinked `.claude/skills` loads in cloud remains to be confirmed live. - **Worktree isolation.** Claude Code's subagent worktree isolation is tied to the session's own repository; a session working in another repository creates the worker's worktree itself under that repository's ignored `.worktrees/` (observed 2026-10-31). ### Verification status Structural checks (`pnpm validate`, which includes the eval schema check, and `pnpm test`) run in CI on every pull request and on `main`; the npm-pack and Agent Skills CLI listing checks (`pnpm test:release`, in `tests/release/`) run on release tags. Headless slash-command runs in Claude Code are recorded; interactive skill-picker runs and write paths remain open; see [smoke scenario status](https://github.com/gaboesquivel/flow-skills/blob/main/tests/smoke/2026-10-27-scenario-status.md) and [evaluation scenario status](https://github.com/gaboesquivel/flow-skills/blob/main/tests/evals/scenario-status.md). --- ## Glossary URL: https://flow-skills-md.vercel.app/docs/glossary Source: https://github.com/gaboesquivel/flow-skills/blob/main/GLOSSARY.md (`GLOSSARY.md`) Project-specific distinctions that change decisions. A term earns an entry when a capable contributor could reasonably get it wrong without it; procedure lives with the owner each entry links ([the methodology](https://flow-skills-md.vercel.app/docs/methodology#maintain-shared-language) describes how this evolves). ### Flow The human-directed, agent-executed product engineering methodology defined in this repository's [PRODUCT.md](https://flow-skills-md.vercel.app/docs/product). Not the flow-skills distribution, Flow Factory orchestration, the application templates (flow-next, flow-mono), or an adopter project's own product. ### Agentic product engineering Combining product judgment, design, and engineering to direct AI agents across discovery, delivery, and learning, with people accountable for decisions, quality, and outcomes. It describes how a product is developed; the product need not contain agents. The **Agentic Product Engineer** is the practitioner who decides what is worth building, directs the agents, and evaluates whether it created value. ### Product context An adopter project's own product identity, normally its `PRODUCT.md`, with design, architecture, and glossary beside it when they earn a file. [Context alignment](#context-alignment) keeps it current and never copies Flow's mission into it ([decision 0009](https://flow-skills-md.vercel.app/docs/decisions/0009-adopter-product-context)). ### Context alignment The [`sync-docs`](https://flow-skills-md.vercel.app/skills/sync-docs) skill ("sync the docs"): update a project's root files to accepted direction after meaningful changes, and set up Flow there. It writes; [product alignment](#product-alignment) only reports. Not template initialization, and it runs no other skill. Records before [decision 0070](https://flow-skills-md.vercel.app/docs/decisions/0070-research-and-clearer-names) call it `flow`, and earlier ones **Flow Lite**. ### Product alignment The [`align`](https://flow-skills-md.vercel.app/skills/align) skill ("check alignment"): a read-only check of the product as built against its goals, users' problems, and [outcome evidence](#outcome-evidence). Distinct from [context alignment](#context-alignment) (docs follow accepted direction) and from `review` (one change against its spec). Records from [0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first) to [0070](https://flow-skills-md.vercel.app/docs/decisions/0070-research-and-clearer-names) call it `product`. ### Spec One independently deliverable increment: a numbered document stating the outcome, acceptance boundary, and what is out of scope, with tasks as the slices inside it. Work that should wait on what another spec teaches is a [candidate spec](#candidate-spec). The file is the record in both delivery modes; an issue opens only on request. Status runs `candidate → draft → accepted → implemented` (or `dropped` at the user's request); acceptance is "accept the spec", or "build it" or "ship it" on a draft. [`to-spec`](https://flow-skills-md.vercel.app/skills/to-spec) owns the rules. ### Exposure A spec's line saying where deployable behavior runs, who can reach it, and how writes behave without authentication; writes fail closed. [`to-spec`](https://flow-skills-md.vercel.app/skills/to-spec) owns the template. ### Decision record A numbered document under `docs/decisions/` for a choice among real alternatives that reaches beyond one spec or is costly to reverse; other choices live in the spec. Accepted records are historical evidence: change of direction adds a new record and back-pointers on the old one's Status line, while current documents state the accepted position. [`to-spec`](https://flow-skills-md.vercel.app/skills/to-spec) owns the test. ### Flow skill A portable `skills//SKILL.md` package. Users reach it by talking (its [leading word](#leading-word)); slash commands are optional shortcuts, and the [catalog](https://flow-skills-md.vercel.app/docs/skill-catalog) groups skills without ordering them. ### Delivery mode Where `ship` lands work: **local** (Git only; merged into `main`) or **GitHub** (a pull request linking the spec). Never asked: GitHub when `origin` is a GitHub repository, otherwise local; a `Delivery:` line in the [Flow block](#flow-block) or the request overrides. The routing and fallback rules live in [`build`](https://flow-skills-md.vercel.app/skills/build#delivery-mode). ### Issue trigger The optional `build-it` label from a repository writer: that issue's "build it", run by the host's trigger, ending at a pull request and never shipping. [`build`](https://flow-skills-md.vercel.app/skills/build#issue-trigger) owns it ([decision 0055](https://flow-skills-md.vercel.app/docs/decisions/0055-capability-based-github-and-host-triggered-builds)). ### Flow block The removable section between `` and `` that opts a project into Flow mode: an optional `Delivery:` line and a pointer to `sync-docs`, in the instruction file Git tracks. [`sync-docs`](https://flow-skills-md.vercel.app/skills/sync-docs#flow-block) owns the rules; a block naming the older `flow` skill is refreshed on its next write. ### Unspecced work Work with no spec or task, from a one-line fix to a feature built from a settled conversation or brief. "Build it" still ends in a reviewed, checked branch; a size guard sets the review tier and never stops the work. [`build`](https://flow-skills-md.vercel.app/skills/build#size-guard) owns the guard. ### Area A task's `Area:` line: the packages or directories it changes, never a file path. [`to-tasks`](https://flow-skills-md.vercel.app/skills/to-tasks) assigns it, and [`build`](https://flow-skills-md.vercel.app/skills/build#task-set) uses it to keep tasks that touch the same files from running as if independent. ### Frontier The tasks of a spec whose blockers have all integrated. There are no waves ([`build` Slices](https://flow-skills-md.vercel.app/skills/build#slices)). ### Work in flight Work started but not on the default branch: kept worktrees, branches with commits not on it, and open pull requests. The SessionStart report ([`hooks/wip.mjs`](https://github.com/gaboesquivel/flow-skills/blob/main/hooks/wip.mjs)) lists it and writes nothing. ### First useful release The outcome that makes a new product worth using; it bounds active work while the vision in `PRODUCT.md` stays broad. A statement in the brief, not a document. [`explore`](https://flow-skills-md.vercel.app/skills/explore) names it; [`to-spec`](https://flow-skills-md.vercel.app/skills/to-spec) delivers it through one spec or several ([decision 0066](https://flow-skills-md.vercel.app/docs/decisions/0066-specs-sized-by-delivery)). ### Delivery appetite How much time (and material model, evaluation, or infrastructure cost) an increment is worth, with its first verifiable slice and non-goals. A target, not a guarantee, recorded in the increment's spec or pull request and never in `PRODUCT.md`. ### Scope trade-off The response to new scope that changes an accepted boundary: defer, replace, reject, or expand the appetite, naming what changes. A correctness, security, or required-check blocker is not scope. [`build`](https://flow-skills-md.vercel.app/skills/build#scope-guard) owns it. ### Delivery branch The one remote branch of a delivery (`spec/-`, else a short descriptive name) and its one pull request, a draft until verified. [`build`](https://flow-skills-md.vercel.app/skills/build#pull-request) owns it. ### Vertical slice One verifiable outcome cut through every layer it needs: a `to-tasks` task, or a group of small tasks that must land together. Never one technical layer. The host decides the fan-out ([`build` Slices](https://flow-skills-md.vercel.app/skills/build#slices)). ### Acceptance scenario The one representative journey a spec's Acceptance names: actor, realistic starting state, and numbered steps with observable results (also through the agent interface when the spec names agent users). A draft without one is not accepted. [`to-spec`](https://flow-skills-md.vercel.app/skills/to-spec) owns the rule. ### Focused check The smallest test that proves one behavior: it fails without the change and runs alone with one command. Consequential contracts get theirs first; UI gets none by default. [`build`](https://flow-skills-md.vercel.app/skills/build#tests) owns the rule. ### Requirement verdict The status `review` gives each step of an acceptance scenario: **satisfied**, **unmet**, or **unresolved**, with cited evidence. No evidence means unresolved; unmet blocks. [`review`](https://flow-skills-md.vercel.app/skills/review#inspect) owns it. ### Liveness The light check that ends "push it", "build it", and "ship it": the remote has the commit and, when the host reports a deployment for it, that deployment answers. It reports a state and never gates; it is not a test or a behavior check (`review`'s). The states are defined by [`liveness.mjs`](https://github.com/gaboesquivel/flow-skills/blob/main/skills/ship/scripts/liveness.mjs) ([decision 0048](https://flow-skills-md.vercel.app/docs/decisions/0048-delivery-phrases-are-approvals)). ### Candidate spec A stub for later work worth remembering: the problem and what it waits on, status `candidate`. `to-spec` completes the same file when its turn comes. ### Leading word The short phrase a user says, typed or dictated, to reach a Flow skill, such as "explore this" or "ship it". A description names one or a few dictation-safe variants (one for the delivery skills, so dictation cannot blur them), and the [catalog](https://flow-skills-md.vercel.app/docs/skill-catalog) lists the first. Prefer familiar words; avoid generic host verbs like "plan". `flow start` is neither a leading word nor a skill; `start` is the optional template bootstrap. [Decisions 0019](https://flow-skills-md.vercel.app/docs/decisions/0019-voice-first-invocation) and [0048](https://flow-skills-md.vercel.app/docs/decisions/0048-delivery-phrases-are-approvals); source limits in the [writing research](https://github.com/gaboesquivel/flow-skills/blob/main/docs/research/2026-10-19-writing.md#matt-pocock-writing-for-agents). ### Exploration Opening possibilities without a bounded question: references, alternatives, sketches, prototypes. Run by [`explore`](https://flow-skills-md.vercel.app/skills/explore); it adopts nothing until the user does, and research it does for the conversation stays in chat. ### Research note A dated, sourced file another session can decide from, written by [`research`](https://flow-skills-md.vercel.app/skills/research) on an explicit request ("research X", "competitors for X"). It separates observed capability, vendor claim, and inference, and proposes rather than adopts. Distinct from research done inside an [exploration](#exploration), which stays in chat. ### Outcome evidence What shows whether shipped work changed the outcome it was for, named in the spec's **Outcome** sentence with the decision it informs. Distinct from delivery proof (the behavior works and the evidence can be obtained), which `build` checks before shipping; [product alignment](#product-alignment) judges outcome evidence afterwards, and unknown stays unknown. ### Validation board A possible practice, not a Flow product or required folder: a shared view of hypotheses, risky assumptions, experiments, and evidence. ### Capability page A website page, sourced from `docs/capabilities/`, explaining what Flow contributes in one area; it links to the owners of each rule and defines none. Distinct from a host's capabilities ([decision 0055](https://flow-skills-md.vercel.app/docs/decisions/0055-capability-based-github-and-host-triggered-builds)). Contract: [`docs/capabilities/README.md`](https://flow-skills-md.vercel.app/capabilities). ### Retired Kept for older records and links. - **Discovery depth** (earlier **process depth**): a Lite or Full setting in the Flow block. `explore` now asks in proportion to the change. Decisions [0036](https://flow-skills-md.vercel.app/docs/decisions/0036-one-explore-depth) and [0044](https://flow-skills-md.vercel.app/docs/decisions/0044-fast-delivery). - **Spec issue**: a GitHub issue per spec. Specs live only in files; issues open on request. [Decision 0044](https://flow-skills-md.vercel.app/docs/decisions/0044-fast-delivery). - **Integration owner**: one session per delivery that merged contributed branches. Claude Code owns sessions now ([decision 0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first)). - **Progress board**: a kanban of specs by stage, removed 2026-11-03. Spec status lines, pull requests, and the [work-in-flight](#work-in-flight) report replace it; unrelated to a [validation board](#validation-board). - **Verification**: former name for [liveness](#liveness). - **Human summary** (a `tldr` skill output): replaced by the host's recaps ([decision 0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first)). --- # Capabilities --- ## Intent-to-verified delivery URL: https://flow-skills-md.vercel.app/capabilities/verified-delivery - Group: Delivery & Execution - Published: 2026-11-02 - Source: https://github.com/gaboesquivel/flow-skills/blob/main/docs/capabilities/verified-delivery.md - Status: an explanation that links to the skills, docs, and decisions owning each rule; it defines none itself. ### The problem A coding agent can produce a plausible change in minutes. Knowing whether that change does what you meant, passed the checks you rely on, and actually reached production is slower and easier to get wrong. "Done" can mean the code compiles, the tests passed on some earlier commit, a deployment exists, or users got value. Those are different claims, and agents tend to report the most optimistic one. ### What Flow contributes Flow connects the steps of a delivery so that each one leaves evidence the next one can check: - **Intent.** `explore` clarifies the problem and, for substantial work, the appetite. `to-spec` writes a numbered spec with an acceptance scenario: a concrete journey that review later judges step by step. - **Implementation.** `build` works on one branch, with one draft pull request per spec in GitHub mode. Drafts run no CI and get no automatic preview in repositories that follow this lifecycle; focused checks run locally while the work moves. - **Review.** A second agent in a fresh context reviews the final head. It gives each acceptance step a verdict of `satisfied`, `unmet`, or `unresolved`, and labels findings Important, Nit, or Pre-existing. An open Important finding blocks. - **Checks.** `build` marks the pull request ready, which runs the repository's required checks once on that head. `ship` merges only when a script confirms every required check succeeded on the head it merges; a skipped, pending, or missing check never counts. - **Liveness.** After pushing, building, or shipping, a light check reports whether the commit is on the remote and whether the host's deployment for it answers. It never gates and never claims the feature works. The point is not more ceremony. It is that each claim in the final report names the head and the evidence behind it. ### How to start Talk to your agent in ordinary language. "Explore this" when the problem is still fuzzy. "Spec it" to write the draft spec. "Build it" to implement, review, check, and hand back a verified branch. "Check it against the spec" for a standalone review. "Ship it" to land the work. "Build it" and "ship it" are approvals: the agent does not ask again before the steps they cover. ### Example Spec 048 changed this repository's own delivery lifecycle. While its pull request ([#208](https://github.com/gaboesquivel/flow-skills/pull/208)) was a draft, four pushes reported CI and title checks as `skipped` with no runner and no branch deployment. A fresh-context review found two blocking issues, which were fixed before landing. A follow-up ([#211](https://github.com/gaboesquivel/flow-skills/pull/211)) fixed a case seen in another repository where a skipped draft run hid the real result on the same head. The article [What counts as verified delivery?](https://flow-skills-md.vercel.app/blog/intent-to-verified-delivery) walks through it. ### Evidence and owners - Lifecycle, review step, and checks: [`build`](https://flow-skills-md.vercel.app/skills/build) (Pull request, Verify, Size guard). - Review passes and verdicts: [`review`](https://flow-skills-md.vercel.app/skills/review); [decision 0058](https://flow-skills-md.vercel.app/docs/decisions/0058-review-passes-and-risk-tiers). - Merge gate and liveness: [`ship`](https://flow-skills-md.vercel.app/skills/ship) and its [`required-checks.mjs`](https://github.com/gaboesquivel/flow-skills/blob/main/skills/ship/scripts/required-checks.mjs). - Draft workspace and checks on ready: [decision 0057](https://flow-skills-md.vercel.app/docs/decisions/0057-draft-workspace-ready-checks), [spec 048](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/048-delivery-lifecycle.md). - Delivery phrases as approvals: [decision 0048](https://flow-skills-md.vercel.app/docs/decisions/0048-delivery-phrases-are-approvals). - Terms: [liveness](https://flow-skills-md.vercel.app/docs/glossary#liveness); spec and review flow in [`to-spec`](https://flow-skills-md.vercel.app/skills/to-spec) and [`explore`](https://flow-skills-md.vercel.app/skills/explore). ### Limitations and trade-offs - **Liveness is not verified behavior, and verified behavior is not customer value.** A `live` report means a deployment answered; review verdicts mean the change matched its spec. Neither shows the change improved the outcome it aimed at. - **Checks prove only what they test.** Green CI on the right head is necessary evidence, not proof of correctness. - **Host-dependent.** A fresh-context reviewer needs a host that can run a separate agent; without one, the review is labelled single-agent. GitHub mode needs a working route to GitHub. Deployment status depends on the host reporting it. - **Repository configuration matters.** Draft-skipping CI and disabled branch previews are this repository's configuration, described in spec 048. An adopting project has to configure its own workflows and hosting for the same behavior. - **Cost.** Every build now runs a reviewer, which spends a little more on low-risk changes. Savings from skipping draft CI are not measured. --- ## Scope and cost control URL: https://flow-skills-md.vercel.app/capabilities/scope-cost-control - Group: Delivery & Execution - Published: 2026-11-02 - Source: https://github.com/gaboesquivel/flow-skills/blob/main/docs/capabilities/scope-cost-control.md - Status: an explanation that links to the skills, docs, and decisions owning each rule; it defines none itself. ### The problem Agents make additions cheap to start. A dashboard here, a refactor there, a new dependency because it was nearby: each looks small, and together they turn a three-hour change into a full day. The same applies to spend. A live model evaluation or a paid external run can be the right call, or it can be habit. Without an explicit boundary, nobody decides; the work just grows. ### What Flow contributes Flow makes the boundary explicit and asks for a decision when it moves: - **Appetite.** For substantial work, `explore` recovers and `to-spec` records how much time the increment is worth, plus a model, evaluation, or infrastructure cost limit when that spend is material. It also records the first verifiable slice and the non-goals. Small, understood changes skip this. - **Scope guard.** During `build`, any new scope, whether the user or the agent proposed it, gets a recommendation before it starts: defer, replace (naming what it displaces), reject, or expand the appetite. A consequential change waits for your decision while unaffected work continues. - **Blockers are not scope.** Correctness, security, and required-check failures are fixed or reported as the reason the work cannot ship on time. They are never cut to meet the target. - **Review checks both directions.** `review` flags additions nobody asked for and accepted behavior that went missing. - **Spend.** Prefer cheap fixtures and offline checks. A paid operation runs only when its result changes a decision, with its expected cost named and your yes for new consequential spend. - **Honest reporting.** Elapsed time and cost are reported when observed and marked "not measured" otherwise. ### How to start Say "explore this" or "spec it" for substantial work, and the agent will ask for an appetite only if it cannot recover one, with a suggested default. During "build it", answer its scope recommendations when they come. If an increment is no longer worth it, "drop the spec" abandons it cleanly. ### Example Spec 057, which introduced this page, sets a proposed appetite of two focused implementation days for its first phase. It names what gives way first (later capability pages, older drafts, and video), what may not be cut to fit (claim checks, trust boundaries, accessibility), and states that start, end, and cost are not measured. It also authorizes no paid model or evaluation budget. See its [Appetite section](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/057-content-architecture.md#appetite-risks-and-open-assumptions). ### Evidence and owners - Appetite capture: [`explore`](https://flow-skills-md.vercel.app/skills/explore) (Proportion) and [`to-spec`](https://flow-skills-md.vercel.app/skills/to-spec) (Appetite). - Scope trade-offs and spend: [`build` Scope guard](https://flow-skills-md.vercel.app/skills/build#scope-guard). - Scope findings in review: [`review`](https://flow-skills-md.vercel.app/skills/review). - How parallel work is sliced: [`build` Slices](https://flow-skills-md.vercel.app/skills/build#slices); the host sizes the fan-out ([decision 0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first)). - Rationale: [decision 0053](https://flow-skills-md.vercel.app/docs/decisions/0053-delivery-appetite-and-scope); practice in [methodology](https://flow-skills-md.vercel.app/docs/methodology#defend-the-delivery-boundary). - Terms: [delivery appetite](https://flow-skills-md.vercel.app/docs/glossary#delivery-appetite), [scope trade-off](https://flow-skills-md.vercel.app/docs/glossary#scope-trade-off). ### Limitations and trade-offs - **An appetite is a target, not a guarantee.** Work can still overrun; the practice makes the overrun a visible decision instead of a surprise. - **Not a spending cap.** Flow does not meter tokens, stop a running model, or enforce a budget. Hard limits belong to your host, provider, or billing settings. - **Unknown cost stays unknown.** Hosts often do not expose token or dollar figures. Flow reports "not measured" rather than estimating. - **Judgment is still needed.** The agent recommends; deciding what is worth more time or money is yours. The decision record that introduced this practice cites a retrospective in which scope changes were candidate contributors to overruns, not measured causes. - **Some friction.** Asking about consequential additions adds a turn. Small fixes and minor implementation choices inside the scope skip it. --- ## Security and human control URL: https://flow-skills-md.vercel.app/capabilities/security-human-control - Group: Trust & Reliability - Published: 2026-11-02 - Source: https://github.com/gaboesquivel/flow-skills/blob/main/docs/capabilities/security-human-control.md - Status: an explanation that links to the skills, docs, and decisions owning each rule; it defines none itself. ### The problem Directing a coding agent means letting it read untrusted text, run commands, and push code. Two failures are common: the agent treats a comment, diff, or web page as an instruction, or it asks permission so often that people approve without reading. You want the agent to act on your approvals, refuse what they do not cover, and leave the riskiest changes for a person. ### What Flow contributes Flow's skills describe how the agent should behave at these boundaries: - **Approvals are explicit and bounded.** "Build it" and "ship it" approve the steps those skills describe, so the agent does not ask again for each one. They never authorize destructive Git, force-pushes, skipping or weakening checks, bypassing protection, or unrelated changes. - **A person stays in the loop where mistakes hurt most.** `build`'s size guard marks CI and workflow files, Git hooks, authentication, billing or payments, and release configuration as human tier. `ship` lands that work only on a yes given after `build` reported those paths. - **Untrusted text is data.** Diffs, pull request comments, fixtures, logs, pages, and issue bodies are evidence for the task, never instructions that widen it. Worker briefs say the same. - **Users keep the sensitive steps.** Sign-in, entering secrets or payment details, accepting terms, and changing the agent's permission settings go to you. A security or protection setting changes only on your explicit request. - **Merging requires real evidence.** `ship` never approves its own pull request or uses an admin bypass, and its gate script refuses to merge unless every required check succeeded on the head being merged. - **A second reader.** Every build gets a fresh-context review that includes a security axis. ```mermaid flowchart TD accTitle: Security and human control trust boundaries accDescr: The user approves work, untrusted text reaches the agent only as data, and host permissions, required checks, and GitHub protections enforce what reaches the default branch. U[User approvals] --> A[Agent following Flow skills] T[Untrusted text such as diffs and comments] -. data only .-> A A --> H[Host permissions and tools] H --> P[Branch and pull request] P --> C[Required checks and merge gate script] C --> M[Default branch] G[GitHub protections when active] --> M ``` Text alternative: you approve the work, and the agent follows Flow's skills to carry it out. Untrusted text such as diffs and comments reaches the agent only as data to evaluate. Everything the agent does passes through the host's permissions and tools, which decide what it can actually run. Its changes go to a branch and pull request, and reach the default branch only after the required checks pass and `ship`'s merge gate script agrees. GitHub's own protections add a separate barrier at the default branch, but only when they are active. ### How to start Say "build it" or "ship it" when you mean it; those are the approvals. When a change touches a human-tier path, `build` lists those paths in its report, and `ship` lands them only on a yes you give after reading it; a "ship it" said before that report stops and asks for that one yes. Say "deep review" to raise a review to its deepest tier. ### Example Spec 048 changed this repository's CI workflows. When it landed, GitHub's "Flow main" ruleset was disabled, so GitHub itself would not block a failing merge. The pull request ([#208](https://github.com/gaboesquivel/flow-skills/pull/208)) said so and listed it as unresolved; `ship`'s gate script held the line instead. That ruleset was still disabled when this page was written. Under the current rules, a change to workflow files like this one is human tier. ### Evidence and owners - Approvals, size guard, and human tier: [`build`](https://flow-skills-md.vercel.app/skills/build#size-guard); [decision 0048](https://flow-skills-md.vercel.app/docs/decisions/0048-delivery-phrases-are-approvals); [decision 0058](https://flow-skills-md.vercel.app/docs/decisions/0058-review-passes-and-risk-tiers). - Untrusted input and the security axis: [`review`](https://flow-skills-md.vercel.app/skills/review) (Inspect). - Merge gate: [`ship`](https://flow-skills-md.vercel.app/skills/ship) and [`required-checks.mjs`](https://github.com/gaboesquivel/flow-skills/blob/main/skills/ship/scripts/required-checks.mjs); [decision 0057](https://flow-skills-md.vercel.app/docs/decisions/0057-draft-workspace-ready-checks). - Steps reserved for people: [`write-agents` Tools](https://flow-skills-md.vercel.app/skills/write-agents#tools); parallel writers in [Sessions](https://flow-skills-md.vercel.app/skills/write-agents#sessions). ### Limitations and trade-offs - **Guidance is not a sandbox or a permission engine.** Skills shape what a well-behaved agent tries. What it can actually do is set by your host's permissions and tools, GitHub protections, and the checks you configure. Configure those as if the guidance could fail. - **Not injection-proof.** Treating untrusted text as data reduces risk; it does not eliminate it. - **The gate script is not protection.** It stops `ship`, but not a person or another tool merging directly. Decision 0057 notes that GitHub-side blocking depends on an active ruleset. - **Reviewers can be wrong together.** A fresh-context reviewer may run on the same model as the author and share its blind spots. Separate execution reduces anchoring on the author's context; it does not guarantee correctness. Without separate execution the review is labelled single-agent. - **Human tier relies on judgment.** The size guard is applied by the agent from the change. When uncertain it picks the higher tier, but it can misclassify. --- # Articles --- ## What counts as verified delivery? URL: https://flow-skills-md.vercel.app/blog/intent-to-verified-delivery - Capability: [Intent-to-verified delivery](https://flow-skills-md.vercel.app/capabilities/verified-delivery) - Published: 2026-11-02 - Source: https://github.com/gaboesquivel/flow-skills/blob/main/docs/blog/intent-to-verified-delivery.md - Status: an explanation that links to the skills, docs, and decisions owning each rule; it defines none itself. When a coding agent says a change is done, it could mean several things. The code compiles. The tests passed, on some commit. A deployment exists. The feature does what was asked. Users are better off. These are different claims with different evidence, and an agent's summary tends to blur them into one confident sentence. Flow's answer is to make each step of a delivery leave evidence that names the commit it applies to, and to keep the claims separate in the report. This article follows one real change through those steps: [spec 048](https://github.com/gaboesquivel/flow-skills/blob/main/docs/specs/048-delivery-lifecycle.md), which changed how this repository runs checks on pull requests. The rules themselves live in the skills and decisions linked throughout; this article explains them and defines nothing new. The capability page [Intent-to-verified delivery](https://flow-skills-md.vercel.app/capabilities/verified-delivery) summarizes the practice. ### The intent: stop paying for checks nobody uses The problem spec 048 set out to fix was cost without evidence. Every push to a pull request ran the full check suite, drafts included, and Vercel built a preview for every branch push. The spec counted 39 of 54 recent deployments of this repository as previews. Most of those runs verified commits nobody would ever merge. The intended outcome was specific: one draft pull request per spec as the shared workspace, no CI and no automatic preview while it is a draft, the required checks run once when it is marked ready, and a merge only when those checks actually ran and passed on the head being merged. The rationale is recorded in [decision 0057](https://flow-skills-md.vercel.app/docs/decisions/0057-draft-workspace-ready-checks). The spec also wrote an acceptance scenario: ten numbered steps, each with an observable result, such as "the CI and `pr-title` jobs report `skipped` with no runner time." Those steps are what review later judges. **Appetite.** Spec 048 did not record an appetite. The practice of recording one for substantial work ([decision 0053](https://flow-skills-md.vercel.app/docs/decisions/0053-delivery-appetite-and-scope)) was accepted on 2026-10-31, the day this change merged, and the spec itself states that savings stay "not yet measured" until a comparable window has passed. *Illustrative extension, not part of the record:* under current guidance, a spec like this would record an appetite: a time target, its first verifiable slice (for example, draft runs skipping in this repository alone), and what gives way if it overruns, such as the starter repositories. [Scope and cost control](https://flow-skills-md.vercel.app/capabilities/scope-cost-control) explains why that is a target and not a cap. ### Implementation: a draft workspace "Build it" opened one draft pull request, [#208](https://github.com/gaboesquivel/flow-skills/pull/208), on the branch `spec/048-delivery-lifecycle`. The configuration it introduced is small: - [`ci.yml`](https://github.com/gaboesquivel/flow-skills/blob/main/.github/workflows/ci.yml) and [`pr-title.yml`](https://github.com/gaboesquivel/flow-skills/blob/main/.github/workflows/pr-title.yml) trigger on `ready_for_review` as well as the usual pull request events, and skip their jobs while the pull request is a draft. - [`site/vercel.json`](https://github.com/gaboesquivel/flow-skills/blob/main/site/vercel.json) turns off branch deployments except `main`, so production still deploys from the default branch and previews become an explicit request. The pull request records what happened next. The first commit, made before the configuration changed, ran CI and built a preview. The four commits pushed after it reported CI and title checks as `skipped`, with no runner and no deployment. One commit came from a worker in a separate worktree and local branch; the integration owner merged it into the delivery branch, so no extra remote branch or pull request appeared. The rules for that were in [`build`](https://flow-skills-md.vercel.app/skills/build) and [`write-agents` Sessions](https://flow-skills-md.vercel.app/skills/write-agents#sessions) at the time; Claude Code now manages worktrees and sessions ([decision 0062](https://flow-skills-md.vercel.app/docs/decisions/0062-claude-code-first)). While the work is a draft, the only signal is local. `build` runs focused checks as it goes and leaves the full suite for the final head. ### Review: a second reader on the head you hand over Before marking the pull request ready, a reviewer in a fresh context read the change against the spec. It found two blocking problems: the REST API cannot mark a pull request ready, and, without active branch protection, the merge gate could pass a workflow that never ran. Both were fixed in one round, in the commit that became the final head. Review rules have since tightened. [Decision 0058](https://flow-skills-md.vercel.app/docs/decisions/0058-review-passes-and-risk-tiers) makes a fresh-context review part of every build, sets its effort by risk, and caps the loop at three rounds. A change to workflow files like this one is now human tier: `ship` lands it only after you say yes to a report that lists those paths. See [`review`](https://flow-skills-md.vercel.app/skills/review) and `build`'s [Size guard](https://flow-skills-md.vercel.app/skills/build#size-guard). ### Checks: only results that actually ran Marking the pull request ready ran the repository's two pull request checks on its final head, and both succeeded: `validate (ubuntu-latest, 22)` and `pr-title`. That head also carries `skipped` results from the draft-time runs. This is the subtle part. GitHub records a job skipped by a condition as a check run with conclusion `skipped`, and branch protection can count that as passing. So `ship` does not rely on the summary. It runs [`required-checks.mjs`](https://github.com/gaboesquivel/flow-skills/blob/main/skills/ship/scripts/required-checks.mjs), which reads the required checks for the pull request and their latest results on its head, and exits 0 only when the pull request is not a draft and each one succeeded. Skipped, neutral, cancelled, pending, missing, and stale results all stop the merge. The gate needed one more fix after it shipped. In the `flow-next` starter repository, marking a pull request ready straight after opening it fired both events together, and the skipped draft run got the newer id, so the gate reported a check as skipped even though a real run had passed. [#211](https://github.com/gaboesquivel/flow-skills/pull/211) changed the script so a skipped run never hides a real result on the same head, with a test written first. A gate that fails closed is annoying in that moment; it is still the right direction to fail. ```mermaid sequenceDiagram accTitle: Draft to ready delivery in spec 048 accDescr: The maintainer approves the build, commits land on a draft that runs no checks, a fresh reviewer reads the final head, marking it ready runs the required checks, and ship merges only after its gate passes. participant M as Maintainer participant A as Build agent participant R as Fresh reviewer participant G as GitHub participant V as Vercel M->>A: build it A->>G: push commits to draft PR G-->>A: checks skipped, no runner A->>R: final head and spec R-->>A: findings to fix A->>G: mark ready G-->>A: required checks pass on head M->>A: ship it A->>G: gate script, then merge G->>V: main deploys production A-->>M: liveness report ``` The sequence above shows the hand-offs in order. You approve the build. The agent pushes commits to a draft pull request, and GitHub skips the checks without using a runner. A fresh reviewer reads the final head against the spec and returns findings, which the agent fixes. Marking the pull request ready makes GitHub run the required checks on that head. When you say "ship it", the agent runs the gate script and merges only if every required check succeeded on that head. The merge to `main` triggers Vercel's production deployment, and the agent reports liveness back to you. ### Liveness: a report, not a verdict After landing, [liveness](https://flow-skills-md.vercel.app/docs/glossary#liveness) answers a narrow question: is the commit on the remote, and did the host's deployment for it come up and answer? It reports one of `live`, `pushed, no deployment reported`, `reachable, commit unconfirmed`, `not live`, or `unverified`. It never gates, rolls back, or runs the acceptance scenario. Behavior is review's job; [`ship`](https://flow-skills-md.vercel.app/skills/ship) owns the rule. Pull request #208 merged on 2026-10-31 and noted that the production deployment would be checked at ship time. Its record and the follow-up [#213](https://github.com/gaboesquivel/flow-skills/pull/213), which marked the spec implemented, do not state the liveness result for this repository's merge, so this article does not claim one. #213 does record that a production deploy in the `flow-next` starter was rate limited. ### Where scope and human control fit Two boundaries ran through this delivery without much ceremony. Scope: spec 048 named what it would not do, including re-enabling GitHub rulesets and changing a repository that needs its own work first. Those stayed out. Human control: "build it" and "ship it" were the approvals. Steps they cover did not prompt again, while what they never cover (force-pushes, weakened checks, protection bypasses) stayed off the table. One limit was stated openly: the repository's "Flow main" ruleset was disabled, so GitHub itself would not block a failing merge. The pull request listed it as unresolved, and `ship`'s script held the line instead. A script that stops one agent is not branch protection. [Security and human control](https://flow-skills-md.vercel.app/capabilities/security-human-control) covers where real enforcement comes from. ### What this does and does not prove Put together, the delivery left three kinds of evidence, each tied to a commit: acceptance steps judged in review, findings fixed and answered, and required checks that ran and passed on the merged head. A liveness report is the fourth kind Flow expects after landing; this record does not contain one, as noted above. Together they are what Flow means by verified delivery. It does not prove the change was worth making. Whether skipping draft CI saved meaningful time or money was not measured; the spec says so. Checks prove only what they test, and a reviewer can miss what the author missed. The draft-skipping workflows and disabled previews are this repository's configuration, not something Flow does for every adopter. A project that wants the same behavior configures its own workflows and hosting. The value of the practice is that each of those limits is written down next to the evidence, instead of disappearing into "done." --- # Skills --- ## sync-docs URL: https://flow-skills-md.vercel.app/skills/sync-docs Source path: `skills/sync-docs/SKILL.md` > Update the project's PRODUCT.md, DESIGN.md, GLOSSARY.md, and ARCHITECTURE.md to match accepted direction, and write the Flow block on request. - Group: Context alignment - Say: "sync the docs", "update the docs", "set up Flow here" - Install all skills: `npx skills add gaboesquivel/flow-skills` - Install this skill: `npx skills add gaboesquivel/flow-skills -s sync-docs` - Source: https://github.com/gaboesquivel/flow-skills/blob/main/skills/sync-docs/SKILL.md **When:** Updates `PRODUCT.md`, `DESIGN.md`, `GLOSSARY.md`, and `ARCHITECTURE.md` to accepted direction after meaningful changes; drafts and Proposed records stay labeled as proposals. "Set up Flow here" writes the opt-in [Flow block](https://flow-skills-md.vercel.app/docs/glossary#flow-block), touching no adopter text outside it, and refreshes an older block in place, keeping its `Delivery:` line. **Writes** those files. Not template initialization ([decision 0070](https://flow-skills-md.vercel.app/docs/decisions/0070-research-and-clearer-names)). **Preserve intent** for the project you are in. "Sync the docs" updates its root context when accepted work changes what that product is, how it behaves, how it is built, or how the team names important concepts. Judging whether the product fits its goals is `align`, read-only; this skill writes. A bare "sync" (Git, data) is not this skill. It runs no other skill, authorizes no implementation, and is not project initialization (`start` is). ### Whose product - **Adopter project:** `PRODUCT.md` is that project's product identity. Update only the sections the change affected. - **This flow-skills repository:** `PRODUCT.md` is Flow's methodology identity. Do not copy it into another repository. Never replace a project's product identity with Flow's tagline, mission, principles, or strategic chain, or scaffold starter trees or a Flow-branded `PRODUCT.md`. ### Process 1. Read `PRODUCT.md`, `DESIGN.md`, `GLOSSARY.md`, and `ARCHITECTURE.md` when present. Read `docs/specs/` and `docs/decisions/` records only when they clarify the area. Align root files to accepted intent only; a draft spec or Proposed decision is labeled as a proposal, never written in as current (`write-agents` Context freshness). 2. Update only affected sections, one writer per root file. Keep `DESIGN.md` consistent with what shipped; choosing a new visual direction is `design`'s. Keep one home per fact; link instead of duplicating. 3. Create a root file only when it would hold meaningful content, by `write-agents` Context freshness's owner test. No empty trees, methodology boilerplate, or parallel trackers (no PRD/PDR/ADR folders). **Goals.** When `PRODUCT.md` is missing or has no brief (problem, who, riskiest assumption, main metric and kill criterion, core journeys), align what exists and name `explore` once as the next step. ### Flow block "Set up Flow here" opts the project into Flow mode; deleting the block opts out. The block needs Git: outside a repository, offer `git init` and stop on a no. **Delivery.** The mode is inferred (`build`'s Delivery mode), so the block's `Delivery:` line is an optional override: write it only when the user names `local` or `github`, and keep a recorded one unless the user names another. Never ask for it. **Write** with [`lib/flow-block.mjs`](https://github.com/gaboesquivel/flow-skills/blob/main/skills/sync-docs/lib/flow-block.mjs): `node /lib/flow-block.mjs [local|github]`. The helper owns the layout: which file holds the block, the `@AGENTS.md` import, markers, the pointer, keeping the recorded value, and refusing malformed markers or symlinked, out-of-project, or shared instruction files. Never touch text outside the markers and that import line. A block from an earlier release (one naming the `flow` skill) is refreshed by the helper on setup or on "sync the docs", rewriting only the block and keeping its `Delivery:` value. Report its output and relay any warning. ### Boundaries - Edit adopter instruction files only for the Flow block and the `@AGENTS.md` import, and write the block only when the user asks, `start` runs, or a sync refreshes an existing block. - Alignment edits are not permission to implement unrelated code; that is `build`. - Never write a session registry, live roster, or shared progress log; coordination is Git evidence. - Create no `docs/specs/` or `docs/decisions/` records here; that is `to-spec` or explicit decision work. ### Completion State which root files changed and whose product they now reflect. Note unresolved assumptions and whether a spec or decision record may be wanted. --- ## explore URL: https://flow-skills-md.vercel.app/skills/explore Source path: `skills/explore/SKILL.md` > Talk through a product, feature, or plan as a product-engineering partner who knows the project's goals and constraints, weighs what already exists, and helps decide what is worth building and how you will know. - Group: Delivery - Say: "explore this", "interview me", "grill this" - Install all skills: `npx skills add gaboesquivel/flow-skills` - Install this skill: `npx skills add gaboesquivel/flow-skills -s explore` - Source: https://github.com/gaboesquivel/flow-skills/blob/main/skills/explore/SKILL.md **When:** A product-engineering conversation that reads the project's goals, commitments, and constraints first; for substantial work asks how the problem is solved today and can recommend adopting, integrating, testing, deferring, stopping, or a differentiated slice; names a diverging commitment and asks whether it is an experiment or a pivot; settles the outcome sentence when an idea becomes an initiative. "Interview me" and "grill this" change the style. **Writes nothing**; an agreed new-product brief goes to `PRODUCT.md` on request ([decision 0069](https://flow-skills-md.vercel.app/docs/decisions/0069-direction-changes-at-adoption)). Think the idea through as a partner who knows the product, test whether it holds up, and record only what the user adopts. "Explore this" is the phrase; "interview me" or "grill this" changes the style, not the scope. Recover facts with tools; ask only about intent you cannot infer. Subagents never ask the user. ### Know the project Before the first substantive recommendation, establish the product's goals, experience commitments, and architectural constraints. Read `PRODUCT.md`, `DESIGN.md`, and `ARCHITECTURE.md` when present: short ones whole, long ones by goals, commitments, boundaries, and the sections the idea touches. Consult `GLOSSARY.md` when a project meaning could change the decision, and referenced specs, decisions, or research selectively, labeled by status (`write-agents` Context freshness). Carry this through the conversation; do not reread every turn. A missing document is normal and never a documentation task. **When a proposal diverges from accepted direction**, name the commitment (file and statement), explain the consequence in product terms, and ask the question that separates an experiment from a pivot: "Today the submitter chooses whether to upvote a match; automatic merging moves that choice to the system. Do you want to change who decides, or test how well we can predict their choice?" Let the hypothetical or experiment proceed. Drafts, candidates, and Proposed records are not commitments. Adopting a change is `to-spec`'s direction-change gate; a prototype or code never changes a commitment. ### How it is solved today For a new product, substantial feature, pivot, or build-versus-buy choice, establish how people solve the problem today before recommending implementation. Start with project evidence and existing research; look externally when that is missing, stale, or too weak. Compare what the user or team could realistically choose: current behavior, a manual workaround, or nothing; direct products or services; open-source projects, libraries, host features, APIs, MCP servers, integrations, or capabilities already in the project. Judge them on what this decision needs, and include the strongest alternative even when the user named others. Valid conclusions: adopt or integrate, test an assumption, defer, stop, or build a differentiated slice. A copy fix needs none of this. Present this in chat; a durable note is `research`'s, on request. ### Conversation - Start from the outcome and who has the problem, and scale to what is established. A fix needs no questions. A feature needs its journeys, agent users or "none", and its delivery constraint (appetite, first verifiable increment, non-goals, material cost limits). A new product also needs who has the problem, what makes a first release useful, the riskiest assumption, and how success is judged. For a hard first-release cut, name the basic expectation without which it is unusable even if its differentiator works. - Weak evidence of need: find one actual occurrence (when it last happened, what the person did, what it cost) and name the continuing responsibility each materially different alternative introduces. Asking queued attendees about facial recognition tests the pitch; seeing where the line stalls makes parallel check-in credible, without storing faces. - Ask only when the answer would change the recommendation: one open question at a time, or a few closed ones in the host's question UI. A delegated judgment is yours to make; say why. - Resolve a blocking uncertainty with the smallest investigation or experiment and report what it showed. A prototype request authorizes that experiment, in its named scope, only. - When the user asks to grill or challenge a plan, or a new product rests on risky assumptions, run a short pre-mortem on the riskiest claims, gather evidence for each, recommend an answer with its trade-off, and name the observation that would end the work. Never re-approve settled decisions. When a new surface's look is not settled by `DESIGN.md`, suggest `design` in one line. - Leave room for disagreement, a prototype, and stopping. Label an untested claim a hypothesis; never invent confidence. A user who asked only to be interviewed gets their intent restated in their words; "sounds good" is not a yes. ### Outcome When an idea becomes an initiative, settle: "We want this outcome to change for these users. We'll look at this evidence, and it will help us make this decision." Reuse an existing metric definition, else name what counts, population, window, source, and baseline (or "unknown"); an unevidenced target is a hypothesis. Prefer an existing observation, benchmark, manual sample, or query (for technical work, perhaps latency, error recurrence, or an invariant); add instrumentation only when the decision depends on it, and a dashboard only when someone needs it to act. A typo never needs it. ### Writes Discussion alone writes nothing and creates no file, branch, worktree, issue, or pull request. Explore never runs `start`, opens a spec, or requires a handoff. **Brief.** When a new product's direction is settled and the user wants it recorded, you own its initial `PRODUCT.md`: problem, who (agent users or "none"), why now, riskiest assumptions as hypotheses, main metric and kill criterion, core journeys (one line each), first useful release, alternatives and differentiation, out of scope. **Alternatives** names what this user would realistically choose today (aim for three where they exist; a workaround or native capability counts; fewer, with the limit stated, beats padding), why they might choose this product for the job, and which part is supported versus hypothesis, linking dated detail in research. An explicit request to write an agreed brief authorizes the write; otherwise show the text once and ask once. With no repository, keep it in chat. Write on one non-default branch named for the work in the current checkout (`write-agents` Sessions), commit only these writes, and report branch and commit; after `start`, only once its initial commit exists. **Feature.** Update `PRODUCT.md` only for a durable change the user adopts to audience, goals, commitments, or positioning, shown as a diff and confirmed like a brief. Feature-specific findings belong in research or the spec. ### Ending Exploration may end in a clearer question, a stop, reuse, an experiment, a brief, or a first slice; do not recite these. Toward delivery, say in a sentence the first useful release, the slice worth implementing, its outcome sentence, and any decision waiting on its result; if what the first slice teaches could change later investment, that slice is the spec. Never push a handoff into an open conversation. "Spec it" (`to-spec`) sizes the work; "build it" can build a settled, bounded conversation under the same gate. Discussion and experiments do not authorize implementation. --- ## to-spec URL: https://flow-skills-md.vercel.app/skills/to-spec Source path: `skills/to-spec/SKILL.md` > Turn the conversation into a numbered draft spec using project conventions, and accept it when approved. - Group: Delivery - Say: "spec it", "write a spec", "share the draft", "accept the spec" - Install all skills: `npx skills add gaboesquivel/flow-skills` - Install this skill: `npx skills add gaboesquivel/flow-skills -s to-spec` - Source: https://github.com/gaboesquivel/flow-skills/blob/main/skills/to-spec/SKILL.md **When:** A numbered draft spec: what and why, an Outcome sentence for initiatives, [Exposure](https://flow-skills-md.vercel.app/docs/glossary#exposure), and an [acceptance scenario](https://flow-skills-md.vercel.app/docs/glossary#acceptance-scenario); decides one spec or several. "Accept the spec", or "build it" or "ship it" on a draft, accepts it and only the records it links ([the rule](https://flow-skills-md.vercel.app/skills/to-spec#status-and-acceptance)). **Writes** the spec and any Proposed record on the work's branch; no issue unless asked. Turn the conversation into a proportionate spec, labelling assumptions instead of inventing decisions. Use the project's spec location, else `docs/specs/NNN-short-name.md`, numbered by `node /scripts/next-number.mjs` (fetch first). Commit on the work's branch (else a new `spec/-`), never the default branch. **What, not how.** Name outcomes, constraints, and consequential decisions. Components, file layout, and implementation are `build`'s unless an established constraint or Program design fixes them. **How many specs.** Decide this yourself and report why, never asking. For a new product, name the first useful release in the Solution, proposing one as an assumption when the brief has none; the vision (`PRODUCT.md`) may stay broad. Default to one spec; several vertical tasks in one spec is valid, and a large update to an existing product is sized the same way. "Spec it" covers the outcome under discussion. When a first slice is independently useful, or what it teaches could change later investment, write that slice in full and keep a later one as a **candidate** stub (the problem and what it waits on) only when the later problem and its dependency are worth remembering. When several pieces form one useful release, can be accepted together, and the user means to deliver them together, one MVP spec holds them. Never split for length or task count. Each spec states its acceptance boundary and Out of Scope; name a dependency only when real. Report which scope "build it" will build. A choice gets a decision record (`docs/decisions/NNNN-short-name.md`) only when it chose among real alternatives **and** reaches beyond this spec or is costly to reverse; otherwise it is a Decisions bullet. Records never hold scope or tasks. Changing an Accepted decision always gets one, with `Supersedes [NNNN]` or `Amends [NNNN]` (and scope) on its Status line; a conflict only with a spec or owner document gets one only by the test above. Write a needed record as **Proposed** and link it. **Length.** As short as complete, with no word limit: link records, glossary, and code instead of restating them. Open no issues unless asked; the pull request closes an issue the user named (`Closes #N`). ### Status and acceptance The status line is `Status: (YYYY-MM-DD).`, with an optional `Appetite: