cofin · cofin · Jun 6, 2026 · Jun 6, 2026 · Jun 6, 2026 · Jun 6, 2026
diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json
@@ -15,7 +15,7 @@
     {
       "name": "flow",
       "description": "Unified toolkit for Context-Driven Development with spec-first planning, TDD workflow, and Beads integration",
-      "version": "0.20.5",
+      "version": "0.21.0",
       "source": { "source": "local", "path": "./plugins/flow" },
       "policy": { 
         "installation": "AVAILABLE",

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -11,7 +11,7 @@
     {
       "name": "flow",
       "description": "Unified toolkit for Context-Driven Development with spec-first planning, TDD workflow, and Beads integration",
-      "version": "0.20.5",
+      "version": "0.21.0",
       "source": "./",
       "author": {
         "name": "cofin"

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "flow",
   "description": "Unified toolkit for Context-Driven Development with spec-first planning, TDD workflow, and Beads integration",
-  "version": "0.20.5",
+  "version": "0.21.0",
   "author": {
     "name": "cofin"
   },

diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "flow",
-  "version": "0.20.5",
+  "version": "0.21.0",
   "description": "Unified toolkit for Context-Driven Development with spec-first planning, TDD workflow, and Beads integration",
   "author": { "name": "cofin" },
   "homepage": "https://github.com/cofin/flow",

diff --git a/.codex/hooks.json b/.codex/hooks.json
@@ -5,10 +5,11 @@
         "matcher": "*",
         "hooks": [
           {
+            "name": "flow-env-detection",
             "type": "command",
-            "command": "bash ./hooks/session-start.sh",
+            "command": "export FLOW_HOST=codex; r=\"${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}\"; bun \"$r/hooks/session-start.js\" || node \"$r/hooks/session-start.js\" || bash \"$r/hooks/session-start.sh\"",
             "timeout": 30,
-            "description": "Detects Beads backend and project root at session start (Codex CLI)."
+            "description": "Detects Beads backend and project root at session start (Codex CLI). Resolves the plugin root from $PLUGIN_ROOT (canonical) or $CLAUDE_PLUGIN_ROOT (alias), falling back to cwd for the in-repo project layer. FLOW_HOST=codex forces the Codex payload shape even when neither var is set."
           }
         ]
       }

diff --git a/.opencode/agents/code-reviewer.md b/.opencode/agents/code-reviewer.md
@@ -2,12 +2,10 @@
 name: code-reviewer
 description: Review Flow specs, plans, and implementation changes for correctness, risk, and missing verification.
 mode: subagent
-tools:
-  read: true
-  grep: true
-  glob: true
-  bash: true
-  webFetch: true
+permission:
+  edit: deny
+  bash: allow
+  webfetch: allow
 ---
 
 Review Flow work for behavioral bugs, invalid host schemas, stale setup commands, missing tests, and missing verification evidence. Lead with findings ordered by severity.
diff --git a/.opencode/agents/executor.md b/.opencode/agents/executor.md
@@ -2,14 +2,10 @@
 name: executor
 description: Execute Flow implementation tasks with TDD, Beads notes, verification, and sync discipline.
 mode: subagent
-tools:
-  read: true
-  grep: true
-  glob: true
-  bash: true
-  edit: true
-  write: true
-  webFetch: true
+permission:
+  edit: allow
+  bash: allow
+  webfetch: allow
 ---
 
 Execute the current Flow task with Beads notes, Red-Green-Refactor, and fresh verification before completion claims.
diff --git a/.opencode/agents/plan-generator.md b/.opencode/agents/plan-generator.md
@@ -2,14 +2,10 @@
 name: plan-generator
 description: Generate zero-ambiguity Flow specs and implementation worksheets after codebase analysis.
 mode: subagent
-tools:
-  read: true
-  grep: true
-  glob: true
-  bash: true
-  edit: true
-  write: true
-  webFetch: true
+permission:
+  edit: allow
+  bash: allow
+  webfetch: allow
 ---
 
 Create implementation-ready Flow specs with exact file targets, task order, test commands, and acceptance checks.
diff --git a/.opencode/agents/prd-orchestrator.md b/.opencode/agents/prd-orchestrator.md
@@ -2,14 +2,10 @@
 name: prd-orchestrator
 description: Analyze broad goals and produce Flow PRD roadmaps with implementation-ready child flows.
 mode: subagent
-tools:
-  read: true
-  grep: true
-  glob: true
-  bash: true
-  edit: true
-  write: true
-  webFetch: true
+permission:
+  edit: allow
+  bash: allow
+  webfetch: allow
 ---
 
 Analyze broad Flow goals, complete research up front, and produce PRD roadmaps split into implementation-ready flows.
diff --git a/AGENTS.md b/AGENTS.md
@@ -2,6 +2,8 @@
 
 This file provides guidance to AI coding agents working with code in this repository.
 
+> **Flow is a skill, not a CLI.** There is no `flow` executable. Never run `flow`, `flow sync`, `flow prd`, `flow status`, etc. as shell commands — they will fail. Invoke the Flow skill, or use the `/flow:*` slash commands (e.g. `/flow:sync`, `/flow:prd`).
+
 ## Overview
 
 **Flow** is a unified toolkit for **Context-Driven Development** combining:

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -2,6 +2,8 @@
 
 Use the Flow skill for context-driven development workflows in repos that use `.agents/`.
 
+> **Flow is a skill, not a CLI.** There is no `flow` executable. Never run `flow`, `flow sync`, `flow prd`, `flow status`, etc. as shell commands — they will fail. Invoke the Flow skill, or use the `/flow:*` slash commands (e.g. `/flow:sync`, `/flow:prd`).
+
 ## Defaults
 
 - Use official Beads (`bd`) when task persistence is needed.

diff --git a/GEMINI.md b/GEMINI.md
@@ -2,6 +2,8 @@
 
 Use the Flow skill for context-driven development workflows in repos that use `.agents/`.
 
+> **Flow is a skill, not a CLI.** There is no `flow` executable. Never run `flow`, `flow sync`, `flow prd`, `flow status`, etc. as shell commands — they will fail. Invoke the Flow skill, or use the `/flow:*` slash commands (e.g. `/flow:sync`, `/flow:prd`).
+
 ## Defaults
 
 - Prefer official Beads (`bd`) when task persistence is needed.

diff --git a/commands/flow-plan.md b/commands/flow-plan.md
@@ -6,6 +6,8 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion
 # Flow Plan
 
 > Lifecycle skill: use `flow-planning` through the `flow` router.
+>
+> **Grill before finalizing:** interrogate every open decision one question at a time (each with your recommended answer + trade-off), and explore the repo / `patterns.md` / `knowledge/` instead of asking when the answer is in the code. See `flow-planning` → "Interrogate Before Finalizing".
 
 ## The Planner Mandate
 

diff --git a/commands/flow-prd.md b/commands/flow-prd.md
@@ -8,6 +8,8 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion
 > **Beads mode:** Skip every `bd` invocation below when the SessionStart hook reports `Beads Backend: Missing (None)` or `Disabled via plugin config (useBeads=false)`. Treat `spec.md` markers as fallback source of truth and skip `/flow:sync`. Never halt for missing Beads. See `skills/flow/references/discipline.md`.
 >
 > Lifecycle skill: use `flow-planning` through the `flow` router.
+>
+> **Grill before finalizing:** interrogate every open decision one question at a time (each with your recommended answer + trade-off), and explore the repo / `patterns.md` / `knowledge/` instead of asking when the answer is in the code. Do not finish the roadmap while obvious research gaps remain. See `flow-planning` → "Interrogate Before Finalizing".
 
 ## The Orchestrator Mandate
 

diff --git a/commands/flow-refine.md b/commands/flow-refine.md
@@ -9,6 +9,8 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, WebSearch
 > **Beads mode:** Skip every `bd` invocation below when the SessionStart hook reports `Beads Backend: Missing (None)` or `Disabled via plugin config (useBeads=false)`. Treat `spec.md` markers as fallback source of truth and skip `/flow:sync`. Never halt for missing Beads. See `skills/flow/references/discipline.md`.
 >
 > Lifecycle skill: use `flow-planning` through the `flow` router.
+>
+> **Grill before finalizing:** interrogate every open decision one question at a time (each with your recommended answer + trade-off), and explore the repo / `patterns.md` / `knowledge/` instead of asking when the answer is in the code. Refinement is done only when a zero-context executor could implement from the worksheet alone. See `flow-planning` → "Interrogate Before Finalizing".
 
 Refining flow: **$ARGUMENTS**
 

diff --git a/commands/flow-revert.md b/commands/flow-revert.md
@@ -6,6 +6,8 @@ allowed-tools: Read, Write, Edit, Bash
 
 # Flow Revert
 
+> **Beads mode:** Skip every `bd` invocation below when the SessionStart hook reports `Beads Backend: Missing (None)` or `Disabled via plugin config (useBeads=false)`. Treat `spec.md` markers as fallback source of truth and skip `/flow:sync`. Never halt for missing Beads. See `skills/flow/references/discipline.md`.
+>
 > Lifecycle skill: use `flow-completion` through the `flow` router.
 
 Reverting: **$ARGUMENTS**

diff --git a/commands/flow-sync.md b/commands/flow-sync.md
@@ -14,6 +14,12 @@ Syncing active backend state to disk for flow: **$ARGUMENTS**
 
 **CRITICAL:** `/flow:sync` is the primary bridge between the **Beads Source of Truth** and the **Markdown View**. Default setup runs it after task completion, note addition, or status changes when `syncPolicy.flowSyncAfterMutation` is enabled.
 
+**What sync means here (and what it does NOT):**
+
+- `/flow:sync` **ALWAYS writes the reconciled markdown to disk** — updating **every markdown file in `.agents/specs/<flow_id>/`** (`spec.md`, `learnings.md`, and any other tracked markdown in the flow folder), not just `spec.md`, so they all match Beads exactly. This write is **mandatory**; sync is never read-only/dry-run and must never finish without persisting the markdown.
+- "Sync" / "export" in Flow means **making the markdown files and Beads reflect identical reality on disk** — nothing more.
+- It does **NOT** mean Dolt. **NEVER run `bd dolt` commands** (`bd dolt push`/`pull`/`export`) as part of sync, regardless of phrasing. Those are out of scope for `/flow:sync` and only run if the user explicitly and separately asks for Dolt operations.
+
 ---
 
 ## Phase 0: Environment Detection

diff --git a/commands/flow-validate.md b/commands/flow-validate.md
@@ -5,6 +5,8 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 
 # Flow Validate
 
+> **Beads mode:** Skip every `bd` invocation below when the SessionStart hook reports `Beads Backend: Missing (None)` or `Disabled via plugin config (useBeads=false)`. Treat `spec.md` markers as fallback source of truth and skip `/flow:sync`. Never halt for missing Beads. See `skills/flow/references/discipline.md`.
+>
 > Lifecycle skill: use `flow-setup` through the `flow` router.
 
 Validate Flow project integrity and optionally fix issues.

diff --git a/commands/flow/revert.toml b/commands/flow/revert.toml
@@ -3,6 +3,9 @@ prompt = """
 ## Lifecycle Skill
 Use the `flow-completion` lifecycle skill through the `flow` router before carrying out this command.
 
+## Beads Mode
+Skip every `bd` invocation below when the SessionStart hook reports `Beads Backend: Missing (None)` or `Disabled via plugin config (useBeads=false)`. Treat `spec.md` markers as fallback source of truth and skip `/flow:sync`. Never halt for missing Beads.
+
 ## 1.0 SYSTEM DIRECTIVE
 You are a **Git-aware revert assistant** for the Flow framework with Beads integration.
 

diff --git a/commands/flow/revise.toml b/commands/flow/revise.toml
@@ -3,6 +3,9 @@ prompt = """
 ## Lifecycle Skill
 Use the `flow-planning` lifecycle skill through the `flow` router before carrying out this command.
 
+## Beads Mode
+Skip every `bd` invocation below when the SessionStart hook reports `Beads Backend: Missing (None)` or `Disabled via plugin config (useBeads=false)`. Treat `spec.md` markers as fallback source of truth and skip `/flow:sync`. Never halt for missing Beads.
+
 ## SYSTEM DIRECTIVE
 You are revising a flow's spec or plan because implementation has revealed new information. All revisions must be documented.
 

diff --git a/commands/flow/sync.toml b/commands/flow/sync.toml
@@ -9,6 +9,8 @@ Skip every `bd` invocation below when the SessionStart hook reports `Beads Backe
 ## 1.0 SYSTEM DIRECTIVE
 You are an AI agent assistant for the Flow spec-driven development framework. Your task is to synchronize the current active backend task state back to the on-disk `spec.md` for a flow, refresh context documents based on the codebase, and optionally generate an export summary.
 
+MANDATORY: `/flow:sync` ALWAYS writes the reconciled markdown to disk so **every markdown file in `.agents/specs/<flow_id>/`** (`spec.md`, `learnings.md`, and any other tracked markdown in the flow folder) — not just `spec.md` — matches Beads exactly. The write is mandatory — never finish sync read-only/dry-run. "Sync"/"export" here means reconciling markdown ↔ Beads to identical reality on disk; it does NOT mean Dolt. NEVER run `bd dolt` commands (`push`/`pull`/`export`) as part of sync unless the user explicitly and separately asks for Dolt.
+
 CRITICAL: You must validate the success of every tool call. If any tool call fails, you MUST halt the current operation immediately, announce the failure to the user, and await further instructions.
 
 ---

diff --git a/commands/flow/task.toml b/commands/flow/task.toml
@@ -3,6 +3,9 @@ prompt = """
 ## Lifecycle Skill
 Use the `flow-planning` lifecycle skill through the `flow` router before carrying out this command.
 
+## Beads Mode
+Skip every `bd` invocation below when the SessionStart hook reports `Beads Backend: Missing (None)` or `Disabled via plugin config (useBeads=false)`. Treat `spec.md` markers as fallback source of truth and skip `/flow:sync`. Never halt for missing Beads.
+
 ## 1.0 SYSTEM DIRECTIVE
 You are an AI agent assistant for the Flow framework. Your goal is to create a "Task" - a lightweight, ephemeral track for quick tasks, explorations, or experiments that don't need a full PRD.
 

diff --git a/docs/antigravity.md b/docs/antigravity.md
@@ -0,0 +1,57 @@
+# Installing Flow for Antigravity CLI
+
+Google is transitioning **Gemini CLI** into **Antigravity CLI**. Consumer Gemini CLI
+tiers (free, AI Pro, AI Ultra) stop serving requests on **June 18, 2026**; enterprise
+Gemini Code Assist Standard/Enterprise tiers retain full Gemini CLI support. In
+Antigravity, "extensions" are renamed **plugins**, and Agent Skills, Hooks, and
+Subagents are preserved.
+
+Flow targets Antigravity by **reusing its Gemini extension assets** — no separate
+manifest is required as of June 2026.
+
+## What carries forward
+
+| Asset | File | Notes |
+|---|---|---|
+| Extension manifest | `gemini-extension.json` | Same schema; `${extensionPath}`/`${/}` tokens still valid |
+| SessionStart hook | `hooks/hooks.json` | Auto-discovered; `bun \|\| node \|\| bash` ladder |
+| Subagents | `agents/*.md` | Markdown + frontmatter |
+| Commands | `commands/flow/*.toml` | TOML slash commands |
+| Context | `GEMINI.md` / `AGENTS.md` | Antigravity reads both |
+| Skills | `skills/**/SKILL.md` | `.agents/skills/` is recognized as an alias |
+
+The config hub remains `~/.gemini` (conversations, MCP config, plugins, approved
+project folders, shared skills).
+
+## Install
+
+While Antigravity's marketplace/install flow stabilizes, install Flow the same way as
+the Gemini extension (Antigravity reads the same hub):
+
+```bash
+# Gemini CLI (still works on enterprise tiers and pre-cutover)
+gemini extensions install https://github.com/cofin/flow --auto-update
+```
+
+For Antigravity-native installation, follow Google's transition guide once published
+(`antigravity.google/docs`). The Flow assets above require no changes to register as
+an Antigravity plugin.
+
+## Verify at release
+
+The Antigravity plugin manifest filename/location is being finalized by Google
+("docs coming weeks" as of the transition announcement). At each Flow release:
+
+1. Check `antigravity.google/docs` and the
+   [Gemini → Antigravity CLI transition post](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/)
+   for a required manifest rename or new location.
+2. If a new manifest file is introduced, add it to the `[tool.bumpversion]` file list in
+   `pyproject.toml` so its version stays in sync, and add it to the conformance matrix.
+3. Confirm `${extensionPath}`/`${/}` hook tokens are still honored (they were as of June 2026).
+
+## Hook token note
+
+Antigravity uses the **Gemini** hook tokens (`${extensionPath}`, `${/}`) — NOT the
+Codex `${PLUGIN_ROOT}` form. Flow keeps these separate: `hooks/hooks.json` (Gemini /
+Antigravity) and `hooks/hooks-codex.json` (Codex). See
+[host-conformance-matrix.md](./host-conformance-matrix.md).