Overview
flow is an AI-native planning and implementation toolchain built by Emergent Company. It bridges three systems — GitHub, a Memory knowledge graph, and OpenCode AI sessions — into a single structured software development lifecycle.
Instead of tickets in Jira, docs in Notion, and code in GitHub living as disconnected artefacts, flow stores every planning decision as a queryable, verifiable node in a knowledge graph. AI agents read the graph to understand what to build, write code against it, and the graph is updated when code ships.
flow is not a task manager. It is a structured contract between your planning intent and your codebase. Every component in the graph must be implemented — or it blocks promotion.
The core loop is: Plan a Scenario in the graph → Implement it with an AI agent in an isolated worktree → Verify every component against the real codebase → Promote to main.
Installation
Install the flow binary with the one-line installer:
Or build from source (requires Go 1.22+):
Verify installation:
flow v0.1.0
Configuration
Each project repo needs a .flow.yml at the root:
plan_branch_name: plan/next-gen
plan_branch_id: 87b21b07-90cf-4738-b0c3-e2a0698bbcf0
main_branch_id: <uuid>
github_owner: emergent-company
github_repo: legalplant-api
Environment variables (loaded from .env.local or shell):
| Variable | Purpose |
|---|---|
| MEMORY_SERVER_URL | Base URL of the Memory API server |
| MEMORY_PROJECT_ID | Project UUID for journal and search |
| MEMORY_API_KEY | Authentication token |
| OPENCODE_URL | OpenCode ACP server URL (default: http://localhost:4096) |
| FLOW_DEBUG=1 | Enable debug logging (also: --debug flag) |
Graph Object Model
All planning data lives in the Memory knowledge graph as typed nodes connected by typed relationships. This is the full object model:
Scenario
├── has ──────────► ScenarioStep (ordered by step_order)
├── acted_by ──────► Actor
└── belongs_to ────► Domain
ScenarioStep
├── occurs_in ─────► Context (which screen)
└── has_action ────► Action (what the user does)
Context (central fan-out node)
├── requires ──────► UIComponent
└── requires ──────► APIEndpoint
APIEndpoint
└── calls ─────────► ServiceMethod
ServiceMethod
└── uses ──────────► SQLQuery
SQLQuery
└── uses ──────────► SourceFile (migration)
All relationship types: has, belongs_to, acted_by, occurs_in, has_action, contains, navigates_to, requires, calls, uses, tested_by.
Three-Branch Model
flow keeps three distinct layers in sync:
| Branch | Purpose |
|---|---|
| Memory: main | Verified reality — matches shipped code |
| Memory: plan/next-gen | Planning workspace — all components status: not_existing |
| Memory: execute/<key> | Per-scenario execution tracking — status advances here |
| Git: master | Production code |
| Git: scenario/<key> | Implementation branch per scenario |
| Worktree: /tmp/lp-work/<key> | Isolated checkout for parallel AI sessions |
Memory branches are not git branches. They are logical branches inside the knowledge graph, used to namespace planning vs. reality without coupling to git state.
Scenario Lifecycle
Every scenario moves through a fixed set of statuses. Each transition is guarded:
| Status | What it means |
|---|---|
| NEEDS KEY | Scenario exists but has no key set |
| NEEDS STEPS | No ScenarioStep objects linked via has |
| NEEDS CONTEXT | Steps exist but no occurs_in → Context wired |
| NEEDS COMPONENTS | Contexts exist but no requires → APIEndpoint / UIComponent |
| READY | Fully planned — audit can run, branch can be opened |
| IN EXECUTION | execute/<key> Memory branch + scenario/<key> git branch exist |
| PROMOTED | Execute branch merged to Memory main, git PR opened |
--init-branch is gated: the Scenario must have user_value set AND a non-stale, non-failing constitution audit. Fix audit failures before branching.
Component Types & Verification
flow verify checks each component against the real codebase. Here is how each type is verified:
| Type | Verified when |
|---|---|
| SourceFile | File path exists on disk |
| SQLQuery | .sql file exists AND func (q *Queries) Name( found in sqlcdb/ |
| ServiceMethod | File exists and signature/name string found in file |
| APIEndpoint | File exists and handler func name found in file |
| UIComponent | .templ or _templ.go file exists |
| ScenarioStep | UI keyword → templ file; API keyword → route; else git commit fallback |
Key Naming Conventions
All graph object keys follow strict conventions enforced by flow audit:
| Type | Key pattern |
|---|---|
| Scenario | s-<domain>-<slug> e.g. s-cases-archive-restore |
| ScenarioStep | <scenario-key>-step-<slug> e.g. s-cases-archive-restore-step-attorney-clicks |
| Context | ctx-<domain>-<slug> e.g. ctx-cases-list |
| Action | act-<domain>-<verb>-<slug> e.g. act-cases-click-archive |
| APIEndpoint | ep-<domain>-<verb> e.g. ep-cases-archive |
| ServiceMethod | sm-<domain>-<verb> e.g. sm-cases-archive |
| SQLQuery | sq-<verb>-<entity> e.g. sq-soft-delete-case |
| SourceFile | sf-migration-<slug> e.g. sf-migration-archive-cases |
| UIComponent | ui-<domain>-<slug> e.g. ui-cases-list-page |
flow-operator Reference
flow-operator is the human-facing orchestration tool. Operators use it to schedule AI sessions, review results, sync session data into the graph, and track findings across projects — without needing to know the internals of the agent toolchain.
flow-operator session start
Schedule an AI session for a scenario at a given stage. The operator triggers the session; the agent receives the appropriate skill and executes autonomously.
session ses_abc123 started
stage: implement → dispatched skill
flow-operator sessions / session status / session logs
Review the history of AI sessions synced to the operator graph, check live status, or read message logs.
flow-operator sync
Pull recent sessions from the OpenCode API and upsert them as AgentSession objects in the operator Memory graph. Also links open PRs to their scenarios.
upserted AgentSession asa-cases-archive-implement
linked PR #142 → s-cases-archive
flow-operator analyze
Record an AgentSessionAnalysis for a session — either manually with notes and pipe-separated findings, or automatically via --auto which spins up a smooth-operator sub-session to read the transcript.
flow-operator projects
Register a project repo with the operator graph so its sessions are included in cross-project syncs and analyses.
flow CLI Reference
The flow CLI is the per-project, agent-facing tool. It runs from inside a project repo and is primarily invoked by AI agents during planning and implementation sessions. Operators interact with it indirectly — via flow-operator session commands that dispatch agents.
flow next
Find the next scenario to plan or implement.
Output signals: NEEDS STEPS, NEEDS CONTEXT, NEEDS COMPONENTS, NEEDS KEY, READY.
flow verify
View, verify, and promote scenario implementations.
flow audit
Run a constitution audit on a scenario.
pass key naming: s-<domain>-<slug>
pass user_value property set
warn step count < 2
flow graph
CRUD operations on the knowledge graph.
flow session
Manage OpenCode AI sessions via the ACP API.
flow query
Semantic/hybrid search across the knowledge graph.
flow journal
Append and list durable session notes in the graph.
flow worktree
Manage isolated git worktrees for scenario implementation.
flow spec
Show the Swagger/OpenAPI contract for a planned APIEndpoint.
AI Sessions
flow launches and manages OpenCode AI sessions via the ACP API. Operators schedule sessions using flow-operator session start. Each session is scoped to a specific scenario and stage, and receives a purpose-built skill pack that instructs the agent on what to do.
Plan stage
Dispatches the flow-plan-scenario skill. The agent researches the codebase, consults the graph, and creates the full component blueprint: Scenario → Steps → Contexts → Actions → all required components with relationships wired.
Implement stage
Creates a git worktree at /tmp/lp-work/<key> and dispatches the flow-implement-scenario skill. The agent reads the component graph and writes code bottom-up: migration → SQL → service → API → UI. It calls flow verify continuously to check progress.
Audit stage
Runs flow audit --key <key> inside an OpenCode session, allowing the agent to fix any failing rules before branching.
Constitution & Patterns
The constitution is a set of Rule objects in the graph wired to a ConstitutionAudit object. Rules encode your team's conventions — naming patterns, required properties, and planning-phase constraints.
A scenario cannot have --init-branch run until flow audit passes or warns. Failing rules block branching entirely.
Patterns
Pattern objects document recurring implementation approaches — UI patterns, DB patterns, API patterns, service patterns. They are referenced by agents during planning to ensure consistency.