Flow

Measure twice, code once.

Flow is a unified toolkit for Context-Driven Development that works with Antigravity, Codex CLI, Claude Code, OpenCode, VS Code / Copilot, Cursor, and OpenClaw. It combines spec-first planning with a local, task-centric filesystem engine (OKF) to track task state and learnings, enabling AI-assisted development with deep, persistent project awareness.

Philosophy

Control your code. By treating context as a managed artifact alongside your code, you transform your repository into a single source of truth that drives every agent interaction. Flow ensures a consistent, high-quality lifecycle for every task:

Lifecycle: Context → Spec & Plan → Implement → Learn

Key Features

• Task-Centric Filesystem Engine (OKF): Persistent task files and specs that survive context compaction and are git-tracked
• Multi-Harness Support: Works with Antigravity, Codex CLI, Claude Code, OpenCode, VS Code / Copilot, Cursor, and OpenClaw
• Spec-First Development: Create specs and task lists before writing code
• Change-appropriate verification: TDD for behavior changes, with static, documentation, characterization, and integration strategies for other work
• Knowledge Flywheel: Capture and elevate patterns across flows (Ralph-style)
• Flow Management: Revise, archive, and revert with full audit trail
• Git-Aware Revert: Reverts logical units of work (tasks or phases), not just raw commits
• Parallel Execution: Phase-level task parallelism via sub-agents

Install

Use each harness's native plugin, marketplace, rules, or skills mechanism. The harness conformance matrix records exact invocations, capabilities, and reload behavior.

Antigravity

agy plugin install https://github.com/cofin/flow

This uses Antigravity's documented Plugins & Skills installer. Flow ships the plugin manifest at plugin.json, the model-decision rule under rules/, and the static PreInvocation routing manifest at hooks.json (hooks/hooks-agy.json).

After installing or updating the plugin, restart Antigravity so the plugin manifest, skills, agents, and hooks are reloaded.

Claude Code

claude plugin marketplace add cofin/flow
claude plugin install flow@flow-marketplace

This installs Flow at user scope (~/.claude/plugins/...). Run /reload-plugins or restart Claude Code after install. The plugin ships skills, commands, hooks, and all current Flow subagents, including the read-only quality reviewer.

Update commands

claude plugin marketplace update flow-marketplace
claude plugin update flow@flow-marketplace

Recommended Claude Code settings

Claude Code does not let plugin authors pre-declare a plan-artifact directory. To keep plan artifacts under Flow's canonical .agents/bundles/specs/ directory, set this in your project .claude/settings.json:

{
  "plansDirectory": ".agents/bundles/specs"
}

Optionally, force plan mode by default for Flow projects:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

Verify the keys against your Claude Code version's settings reference.

Codex CLI

codex plugin marketplace add cofin/flow

Then in a Codex session, run /plugins and enable Flow. Review and trust its hooks before expecting session routing. Update with codex plugin marketplace upgrade flow-marketplace.

Codex CLI 0.117+ supports first-class marketplace commands — add accepts owner/repo[@ref], HTTPS/SSH git URLs, or local paths, with optional --ref <REF> and --sparse <PATH>.

Codex plugins do not currently expose plugin-defined /flow:* slash commands. Use Flow through the installed Flow skill with natural-language requests such as Use Flow to set up this project.

Recommended Codex settings

Codex CLI has no plugin-author hook for a plan-artifact directory. The closest useful knob is reasoning effort for plan mode — set in your ~/.codex/config.toml:

plan_mode_reasoning_effort = "high"

OpenCode

OpenCode supports npm plugins and local plugin files. Flow currently ships OpenCode-compatible project files and skills, but does not advertise a global install until a package is published through OpenCode's npm plugin path.

OpenCode also discovers skills from .opencode/skills/, .claude/skills/, and .agents/skills/, so Flow-compatible project-local skills do not require a global plugin install.

OpenCode Flow slash commands require the project templates under templates/opencode/commands/. Without configured templates, invoke the discovered Flow skill in natural language.

Recommended OpenCode settings

OpenCode has no plugin-author hook for a plan-artifact directory. Set sensible defaults in your project opencode.json:

{
  "permission": { "edit": "ask", "bash": "ask" }
}

Other harnesses

Cursor IDE

Cursor consumes Flow through project rules and shared repository instructions:

• .cursor/rules/flow.mdc
• AGENTS.md
• project-local operational skills in .agents/skills/

Cursor now supports native .cursor-plugin/plugin.json packages with skills, commands, agents, rules, and hooks. Flow currently ships workspace integration, including .cursor/hooks.json; a Cursor plugin package is not yet shipped. See the Cursor plugin reference.

VS Code / Copilot

VS Code discovers Flow custom agents from .github/agents/*.agent.md and shared skills from .agents/skills/, .claude/skills/, or .github/skills/. Flow ships workspace agent definitions for the core lifecycle agents.

VS Code also supports marketplace and Git-source agent plugins through Chat: Install Plugin From Source. Flow's workspace agents remain the documented integration here; plugin-format compatibility is not a live installation test. See VS Code agent plugins.

OpenClaw

OpenClaw consumes Flow through runtime skill discovery and native sessions_spawn subagents. File-backed skills normally refresh on the next turn after watcher changes; managed library revisions remain pinned until explicitly refreshed. Flow does not ship an OpenClaw plugin manifest. See OpenClaw skills.

Quick Start

Initialize a project

# Claude Code
/flow-setup

# Antigravity / configured OpenCode command templates
/flow-setup

In Codex CLI, ask: Use Flow to set up this project

Flow will:

1. Create the Flow directory (defaults to .agents/)
2. Configure local ignores in .git/info/exclude to keep specifications local-only
3. Create core project context files (product.md, tech-stack.md, workflow.md); add evidence-backed knowledge/patterns/<topic>.md chapters lazily
4. Guide you through product vision, tech stack configuration, and repository-native workflow commands setup

Create a flow

# Claude Code
/flow-prd "Add user authentication"

# Antigravity / configured OpenCode command templates
/flow-prd "Add user authentication"

In Codex CLI, ask: Use Flow to create a PRD for add user authentication

This creates a new specification bundle under .agents/bundles/specs/<flow_id>/:

• spec.md (unified spec + implementation plan)
• learnings.md (per-flow discoveries log)
• tasks/ directory to store individual task markdown files

Flow uses a unified spec.md implementation plan. Task state lives in the individual tasks/*.md files. The active lifecycle owner applies the revision-guarded flow-state contract with ordinary file tools; no Flow executable or separate reconciler is installed.

Implement

# Claude Code
/flow-implement auth

# Antigravity / configured OpenCode command templates
/flow-implement auth

In Codex CLI, ask: Use Flow to implement auth

Flow follows a TDD workflow:

1. Select the next ready authoritative task worksheet
2. Claim it through a revision-guarded flow-state transaction applied by the lifecycle owner
3. Write failing tests (Red)
4. Implement code to pass tests (Green)
5. Refactor while tests pass
6. Commit the task changes: <type>(<scope>): <description>
7. Close the task through the direct lifecycle-owned state operation and record the commit
8. Record learnings inside the task file under ## Notes & Discoveries
9. Reconcile the derived checklist in the same task-first/spec-last transaction

Commands

Flow keeps command behavior aligned, but each harness exposes a different command surface.

Purpose	Claude Code	Antigravity	OpenCode	Codex CLI
Lifecycle commands	/flow-setup, /flow-prd, /flow-plan, etc. from commands/flow-*.md	Skill-derived slash commands from skills/ such as /flow, /flow-setup, and lifecycle skills	Project/native command files when configured; otherwise use the Flow skill/plugin context	Natural-language Flow skill requests
Canonical prompt source	commands/flow-*.md	skills/*/SKILL.md plus commands/flow/*.toml as shared prompt source material	templates/opencode/commands/*.md for project command installs	skills/*/SKILL.md in the generated plugin package
Subagents	agents/*.md	agents/*.md	.opencode/agents/*.md	.codex/agents/*.toml

Codex plugins do not currently expose plugin-defined /flow:* slash commands. OpenCode command names depend on whether the user installs project command files or uses the plugin context.

Reference

Directory structure

project/
├── .agents/
│   ├── index.md             # File resolution index
│   ├── bundles/
│   │   ├── product/         # Product identity and technology
│   │   ├── knowledge/       # Recursively nested current-state knowledge
│   │   ├── research/        # Pre-plan research
│   │   └── specs/
│   │       └── <flow_id>/   # e.g., user-auth/
│   │           ├── spec.md   # Unified spec + plan
│   │           ├── learnings.md
│   │           └── tasks/    # Task definitions
│   │               └── 1.1.md
│   └── skills/              # Sole project operational-skill root

Flow naming & status markers

Flows use format shortname — examples: user-auth, dark-mode, api-v2.

Marker	Status	Description
[ ]	Pending	Not started
[~]	In Progress	Currently working
[x]	Completed	Done with commit SHA
[!]	Blocked	Cannot proceed (status: blocked in task file)
[-]	Skipped	Intentionally bypassed (status: skipped in task file)

Local Specs ignore guidelines

By default, the .agents/ directory is checked into Git so that specifications, implementation plans, and task histories are version-controlled alongside your code.

If you prefer to keep all Flow specifications and task files local-only (e.g. to avoid committing agent metadata to your repository), you can ignore the .agents/ directory locally.

Local Ignore Configuration: To ignore the .agents/ directory only in your local clone without affecting other developers, append it to .git/info/exclude instead of .gitignore:

printf '\n# Flow specifications (local-only)\n.agents/\n' >> .git/info/exclude

Knowledge system (three-tier flywheel)

Per-flow learnings — each flow has learnings.md:

## [2026-01-24 14:30] - Phase 1 Task 2: Add auth middleware
- **Files changed:** src/auth/middleware.ts
- **Commit:** abc1234
- **Learning:** Codebase uses Zod for validation
- **Pattern:** Import order: external → internal → types

Project patterns — stored by topic under knowledge/patterns/:

<!-- knowledge/patterns/imports.md -->
# Import Conventions
- Import order: external → internal → types

# Gotchas
- Always update barrel exports

Persistent knowledge base — learnings synthesized into cohesive, logically organized chapters in knowledge/ during sync and archival. Content is integrated directly into existing chapters to describe the current state of the codebase.

Flywheel:

1. Capture — After each task, append learnings to learnings.md
2. Elevate — At phase/flow completion, write evidence-backed patterns to knowledge/patterns/<topic>.md
3. Synthesize — During sync and archive, integrate learnings directly into knowledge base chapters in knowledge/ (e.g., architecture.md, conventions.md). Update current state, do not outline history.
4. Inherit — New flows recursively read relevant knowledge/patterns/ and other knowledge chapters.

If .agents/skills/flow-memory-keeper/SKILL.md exists, use it at sync, archive, finish, revise, and failure checkpoints so spec cleanup, learnings capture, and refinement stay mandatory.

Skills library

Flow's skills/ tree is the canonical packaged skill source. In consumer projects, .agents/skills/ is the sole operational project-skill authority; .agents/bundles/ remains reserved for OKF product, knowledge, research, and specification documents.

Resources

• GitHub Issues — Report bugs or request features

License

Apache License 2.0