Spec-First Engineering & Directed Agent Workflows — Measure twice, code once.
Architecture & Lifecycle · Flow Studio · Install · Commands · Bundle Layout
Flow is a unified toolkit for Spec-Driven Development backed by Open Knowledge Format (OKF v0.2) bundles. It works natively from a single repository root across Google Antigravity (IDE & CLI), Claude Code, Codex CLI, Cursor, OpenCode V2, and VS Code / Copilot.
Flow separates planning and review from isolated task execution:
- Setup (
/flow:setup):- Runs Brownfield Alignment & Legacy Migration (
alignmode) to upgrade existing.agents/layouts without data loss, or initializes a new repository from scratch. - Probes host binaries (
uv,python3,cargo,go,bun,pnpm,npm,make,just,pwsh,powershell) and scaffolds core context chapters (product/product.md,product/product-guidelines.md,product/tech-stack.md,knowledge/workflow.md). Adds<= 40-line<!-- truth: start -->blocks and nestedknowledge/**chapters anchored topath/to/file::Symbol. - Seeds engineering disciplines (deep-module design, domain modeling, public-interface TDD, bug diagnosis, and first-time reader docs) alongside stack-specific
.agents/skills/<domain>/,.agents/skills/review-<domain>/, and.agents/agents/<domain>-{reviewer,specialist}.mdsubagents. - Configures Git tracking (
sharedteam mode vs.local-onlystealth mode via.git/info/exclude) and opt-in cross-harness settings.
- Runs Brownfield Alignment & Legacy Migration (
- Spec (
/flow:prd,/flow:spec,/flow:revise,/flow:research) — Upfront Chapter Plans:- Parallel Research & Questioning: Fans out read-only
@researchersubagents returning subsystem summaries, then resolves open decisions (1question for dependent forks;2–3batched independent questions with<Label> (Recommended)first). - Feature-Sized Specifications (
/flow:prd&/flow:spec): Defaults cohesive features to a single-chapterspec.md(has_chapters: false) and splits intochapters/ch01..chNN/only at real checkpoints or independent subsystems. Allowscompactworksheets for any size, runs parallel per-chapter planners for>= 2chapters, validatesOKF v0.2right after writing, and warns onplanning_quality: degraded. - Independent Spec Review & Revision (
/flow:revise): Runs independent reviewers (1combined reviewer up to4chapters) using only disk paths and decides on each finding (ADOPT,CONTEST,ESCALATE). Keeps rootspec.md,chapters/index.md, and chapter worksheets synced in present tense. - Research & Prototyping (
/flow:research, alias/flow:task): Runs primary-source@researcheraudits promoted intoresearch/*.mdwithsources:+[^id]:footnotes, or time-boxed prototypes in untracked.agents/scratch/<slug>/.
- Parallel Research & Questioning: Fans out read-only
- Implement (
/flow:implement,/flow:status) — Parallel Steps & Fast Chapter Check:- Resolves linked
git worktreecheckouts (symlinking.venv/node_modulesand routingsharedvs.local-only.agents/), runs preflight, and executes the active chapter (1..Ntasks; or ready chapters with--all). Runs parallel workers on separate files (small_swarmon Antigravity;parallel_taskson Claude Code, Codex CLI, Cursor, and OpenCode) or sequentialchapter_batchpasses. - Runs the
< 60schapter check once per chapter (reserving> 60sfull suites for/flow:finish), records commit SHAs before syncing.agents/bundles/knowledge/**,docs/**,chapters/index.md, and rootspec.mdin present tense. Passes independent review (@code-reviewer+@quality-reviewer), stampslast_reviewed_commit, and enforces completion checks in cross-harnessStophooks (hooks/stop-check.{sh,ps1}).
- Resolves linked
- Learn & Document (
/flow:learn,/flow:docs):/flow:learn(aliasesrefresh,sync): Runs anytime—across machines, mid-flow, or post-flow—to sync Git history with task worksheets and intersectgit diffagainstsources[].resource. Sharpens domain glossaries and ADRs (knowledge/decisions/adr-NNN-<slug>.md), updatesknowledge/**in present tense, and syncs.agents/skills/and.agents/agents/./flow:docs(write,validate,capture,sync,pr): Tool-agnostic documentation and agent-context discipline grounded in first-time reader clarity, file-checklist[k/N files documented]coverage, progressive disclosure (agent-context.md), and clean PR/commit/changelog hygiene (prs-commits-and-changelogs.md).
- Complete (
/flow:review,/flow:finish,/flow:archive,/flow:cleanup,/flow:revert,/flow:validate):- Runs independent code review covering spec conformance, repository standards, deep-module design, and debloat. Verifies release checks on the current branch, captures durable learnings into
.agents/bundles/knowledge/**+.agents/bundles/log.md, and removes completed spec directories.
- Runs independent code review covering spec conformance, repository standards, deep-module design, and debloat. Verifies release checks on the current branch, captures durable learnings into
Flow includes Flow Studio (studio.md) and cross-harness orchestration (orchestration.md). It runs across Google Antigravity (sidecars/studio/ + sidecars/studio/mcp-server.mjs), Claude Code (mods/claude-flow/), Codex CLI (CodexAppServerBridge), VS Code & Cursor (vscode-extension/), and OpenCode V2 (.opencode/plugins/flow.js):
- Studio Home, Multi-Branch Specs, & Review: Switch pinned or remote repositories from Studio Home and browse specs across branches. Record out-of-tree feedback under
<git-common-dir>/spec-feedback/<flow_id>/<author_slug>.json, publish spec PRs (flow spec pr), and send notes straight to/flow:revise. - Dynamic Model Routing &
flowCLI: Evaluate live model inventories across all six harnesses (flow models) while keeping planning and verification onstrongmodels. Install the unified CLI withflow install-clifor sync, branch specs, bundle linting, and agent helpers. - Federated Knowledge Catalog & Python Runner Auto-Detection: Searches local and sibling workspaces (
sidecars/studio/knowledge/catalog.mjsBM25 + graph links alongsideflow-catalogDuckDB RRF) and manages workspace permission allowlists. Dispatches tasks indirect-workspace,worktree-isolated, orread-onlymode (including loopback A2A/.well-known/agent-card.json+POST /a2a).
agy plugin install https://github.com/cofin/flowWhen running in Google Antigravity, Flow uses the run_workflow Python API (phase(), parallel(), pipeline(), agent(..., type_name="self", schema=..., model="inherit")) for parallel research, chapter spec authoring, independent reviews, and isolated single-chapter task runs.
claude plugin marketplace add cofin/flow
claude plugin install flow@flow-marketplaceUpdate commands:
claude plugin marketplace update flow-marketplace
claude plugin update flow@flow-marketplacecodex plugin marketplace add cofin/flowThen run /plugins inside a Codex session to enable flow, or update with codex plugin marketplace upgrade flow-marketplace. Invoke Flow through natural-language skill requests such as Use Flow to set up this project or Use Flow to plan user authentication.
- Agent Plugin (
.cursor-plugin/plugin.json): Install Flow as a Cursor plugin (https://github.com/cofin/flow) so skills, subagents, and lifecycle hooks (hooks/hooks-cursor.json) load automatically. - Flow Studio Extension (
vscode-extension/): Installed automatically into~/.cursor/extensionson your first session (hooks/session-start.{sh,ps1}), or run directly from GitHub without cloning the repository:
npx --yes --package github:cofin/flow flow-studio-vscode --target cursorInstall the packaged plugin. It registers Flow's skills and subagents and adds the live bundle summary to every model request:
opencode plugin add github:cofin/flowFor local development, add the checkout directory to the OpenCode plugins configuration instead.
If OpenCode reports Plugin must export a default definition with an id and an effect or setup function for ~/.config/opencode/plugins/flow.js, that file is a standalone copy from before Flow 0.26 that OpenCode V2 rejects. Delete it and install the package with the command above.
- Chat / Agent Plugin: Install Flow through Chat: Install Plugin From Source (or from a local checkout, where
make install-vscode/node ./vscode-extension/install.mjs --linkcan also be used for local development). - Flow Studio Extension (
vscode-extension/): Run the one-line installer from GitHub (no Git clone needed) to bundlevscode-extension/+sidecars/studio/and registercofin.flow-studiointo your editor'sextensions.json. Then reload the window (Developer: Reload Window):
# Auto-detect installed VS Code-compatible editors and install cofin.flow-studio
npx --yes --package github:cofin/flow flow-studio-vscode
# Or target a specific editor (vscode | vscode-insiders | cursor | windsurf | positron | all)
npx --yes --package github:cofin/flow flow-studio-vscode --target vscode| Command | Lifecycle Skill | Reference Procedure | Description |
|---|---|---|---|
/flow:setup |
flow-setup |
setup.md |
Align brownfield repos or bootstrap .agents/bundles/, .agents/skills/, and .agents/agents/ |
/flow:prd <goal> |
flow-planning |
prd.md |
Author multi-chapter roadmap (spec.md + chapters/ch01..chNN/) and upfront worksheets |
/flow:spec <goal> |
flow-planning |
spec.md |
Author high-detail specification (spec.md), chapters/, and tasks/*.md worksheets (alias: plan) |
/flow:revise <flow_id> |
flow-planning |
revise.md |
Rewrite root spec.md, chapters/, and tasks/*.md in place in present tense (alias: refine) |
/flow:research <topic> |
flow-planning |
research.md |
Primary-source research & time-boxed .agents/scratch/ spikes (alias: task) |
/flow:implement [flow_id] |
flow-execution |
implement.md |
Execute active chapter (1..N tasks, or --all chapters) with public-interface TDD, doc/OKF sync, and review |
/flow:status |
flow-execution |
status.md |
Inspect active flows, chapter progress, remaining plan, and ready tasks |
/flow:learn [scope] |
flow-learn |
learn.md |
Anytime catch-up (refresh), sync, OKF v0.2 knowledge update, and skill sync |
/flow:docs [mode] |
flow-docs |
prose-and-documentation.md |
Tool-agnostic user/developer docs, agent-context.md, changelogs, and clean PRs |
/flow:review [flow_id] |
flow-completion |
review.md |
Independent spec, Markdown-sync, standards, and debloat quality review |
/flow:finish [flow_id] |
flow-completion |
finish.md |
Verify release checks, chapter review stamps, ADR filter, and mark flow completed |
/flow:archive [flow_id] |
flow-completion |
archive.md |
Capture completed flow into .agents/bundles/knowledge/** and remove spec dir |
/flow:cleanup |
flow-completion |
cleanup.md |
Groundskeeping: sync specs, archive completed flows, and debloat touched files |
/flow:revert <scope> |
flow-completion |
revert.md |
Git-aware revert of a task, chapter, phase, or flow |
/flow:validate |
flow-completion |
validate.md |
Validate .agents/bundles/, .agents/skills/, .agents/agents/, and active specs |
.agents/
├── setup-state.json # Active bundle root, setup state & ignore_policy (shared | local-only)
├── scratch/ # Untracked throwaway prototypes & spikes
├── skills/ # Project-local domain & review skills (generated by /flow:setup & /flow:learn)
│ ├── index.md
│ ├── <domain>/{SKILL.md,references/*.md}
│ └── review-<domain>/{SKILL.md,references/{checklist,false-positive-suppressions}.md}
├── agents/ # Paired project-local subagents
│ ├── <domain>-reviewer.md
│ └── <domain>-specialist.md
└── bundles/
├── index.md # Root OKF v0.2 manifest
├── log.md # Append-only ISO-dated changelog
├── product/{index,product,product-guidelines,tech-stack}.md
├── knowledge/
│ ├── index.md
│ ├── workflow.md
│ ├── architecture/<area>.md
│ ├── patterns/<topic>.md
│ ├── domains/<domain>.md
│ ├── testing/<topic>.md
│ ├── gotchas/<area>.md
│ └── decisions/adr-NNN-<slug>.md
├── research/<topic>_<YYYYMMDD>.md
└── specs/
├── index.md # Frontmatter-free spec catalog
└── <flow_id>/
├── spec.md # Full-plan roadmap & present-tense state snapshot
├── learnings.md
├── research/<topic>_<YYYYMMDD>.md
├── tasks/<id>-<slug>.md # Single-chapter flows (1..N tasks)
└── chapters/ # Multi-chapter flows (ch01..chNN, zero upper cap)
├── index.md
└── ch01-<slug>/
├── spec.md
└── tasks/<id>-<slug>.md # Deliverable chapter task worksheets (1..N tasks)