This document defines Flow's invariants.
Flow is in preview. Positioning defines its audience and limits. What Flow guarantees classifies claims by enforcement and labels claims without tests or scheduled evals as unmeasured.
Tools, commands, guides, agents, and Session v5 stay frozen while those guarantees
are measured. Optional fields may be added. Removal or rename requires a major
announced one release ahead.
A new required-at-save plan declaration is a major. evidence entries own
scope, platform, and assertions; named commands bind .flow/results.xml.
scope: "gate-observe" records inspect-only audit outcomes; gate still requires pass.
Release qualification owns the thresholds and cadence.
Flow owns a serial durable lifecycle with planning, one active run, observed
validation, one independent review, reset, and closure. Implementation may use a
bounded, ephemeral host-native worker wave. Flow exposes eleven tools, five commands,
four guides, and three hidden subagents. flow-planner is disabled unless selected.
Active work uses the manager and reserved planner, worker, and reviewer roles.
An active Flow session is authoritative for its goal until an explicit close
records completed, deferred, or abandoned disposition. The manager must not
silently continue that goal through an ordinary non-Flow workflow. Runtime
nextAction is durable default workflow direction, not a new permission grant.
Environment-sensitive transition guards remain authoritative when a mutation is
attempted.
Prerequisite repairs have no amendment count limit. Each needs a current, complete failed canonical gate and reversible same-goal targets before review. Later amendments need a canonical failure recorded after the preceding amendment. The plan, gate, tests, and review stay fixed. Repair handoffs occur once per accepted amendment boundary, not per capture.
Before manager mutations, compare the compact goal with the request. Exact recovery of an accepted close runs first and grants no new authority. The manager judges alignment: continuation or compatible narrowing proceeds; new or expanded work makes no mutation and offers continue, defer, or abandon. Close completed work before a new request. Same-goal approved plan-only requests report plan and progress without mutation.
Within existing implementation authority, /flow-auto continues through runnable
features and closure. An accepted non-replayed manager mutation must establish
progress in the same Flow session before idle can enqueue another prompt. An
unchanged ready baseline, replacement session, unknown attribution, or stale
source fails closed. A dispatched reviewer may contribute only the expected
state-constrained successor revision after flow_review_start.
Planning awaiting approval and await-user-direction remain checkpoints.
Shadow advice grants no mutation. A reply resumes only after its accepted
manager mutation advances the same session into a mechanical state. An unchanged
recognized checkpoint returns to waiting. Native assistant and call identities
must match the frozen inputs consumed by that model request. Later input cannot
relabel an older assistant or supply authority from another host.
Automatic compaction retains the epoch through its checked native control. Its user-role checkpoint grants no approval. Steer or consumed input, manual compaction of automatic work, user interruption, or event-stream loss revokes the interval. Consumer cancellation ends only its captured HTTP request. Queued prompts preserve the running request. Stale callbacks cannot revoke a fresh source. Summary-only ordinary history grants no checkpoint execution. These checks add no Session v5 field. See ADR 0018.
/flow-auto stop and /flow-auto cancel revoke only the process-local lease in
that OpenCode session. They do not mutate or close the durable Flow session.
Initial auto/run prompts, compaction context, and synthetic continuations share
a manager kernel covering mutation ownership, reviewer-owned submission,
reserved roles, the failedReviewCount === 1 retry gate, and current-source and
relevant base-diff evidence. The kernel adds no role registry or durable policy.
Retry selection follows the Session v5 convergence rules. The session remains authoritative while waiting. Other pauses require a material product or scope choice, missing external Git or release authority, a hard operational failure, or user-chosen deferred or abandoned closure. Only the user may select those non-completed dispositions.
Flow does not own plugin installation, automatic activation, cache cleanup, configuration repair, optional worker admission, audit schemas, benchmark promotion, replay reporting, narrow correction protocols, durable wave state, worker recovery, concurrent active features, or cross-version active-state migration. It also owns no persisted request-intent classifier, retry counter, or delivery document.
- Session v5 is the only active schema. Older documents never hydrate as active state and old archives never authorize work.
- Session v5 compatibility runs from older writer to newer reader. Older builds cannot read values beyond historical bounds, including more than three amendments or 64 planned gates plus a separate broad observation. Finish or close before downgrade; Flow adds no rollback layer.
- Approval locks a bounded DAG and optional per-feature pass or observe checks.
New plans declare one
evidencegate, orgate-observefor all-inspect work. Older documents hydrate withoutevidenceorchecks; retiredgateandexternalEvidencefields stay unread. - Stable finding, issue, and requirement IDs supplied by the source request remain verbatim in saved feature summary or validation prose so each ID is traceable to an immutable outcome and its evidence.
- If implementation would require material scope outside an approved plan, stop editing. Finish the approved plan or explicitly close it before creating a different plan; never replan the active approved session in place.
- A feature run aggregates validation, review, result, and artifacts. Optional baseline and packet references point to managed hashed sidecars.
- Runs remain in strictly increasing durable start-revision order, so derived latest-attempt delivery cannot disagree with canonical progress.
- At most one run is active. Dependencies must be complete before a run starts.
- New failed reviews block either run kind. Inspection repairs cover approved
report/evidence targets, not product defects. Legacy completed inspections with
failed reviews retain unsupported assurance. Reset supersedes the selected feature
and its dependent runs. An optional exact
nextFeatureIdstarts the chosen runnable feature in the same transaction, and its new run starts empty. A failed feature is excluded from implicit selection while its latest relevant reviewed outcome remains failed; untouched dependency-independent features remain eligible. Automatic convergence is bounded by recorded failed review results: onlyfailedReviewCount === 1without ascopeBlockerfinding permits one fresh full automatic retry. Every scope blocker or count of two or greater projectsawait-user-directionbefore a directed or qualified host-authorized attempt. When all runnable candidates require an explicit retry, status isreadyand projectsawait-user-direction. This includes a blocked run superseded by reset to independent work once that work finishes. Detail identifies the failed feature from durable runs. Explicitflow_run_start(featureId)begins that retry without reset. Pre-review resets and rejected stale-source submissions do not increment the derived count. - Completed close is allowed only after every feature has a completed current run. Inspections may complete with negative findings. Full completion assurance still requires passing current reviews and the declared evidence. Deferred and abandoned close explicitly supersede active work.
New nonterminal mutations reserve one operation, 197,632 compact JSON bytes, and the last safe revision for close. Exact replays bypass admission. Legacy open v5 limits remain 4,096 operations and 4 MiB. A final matching close at the session revision may reach 4,097 operations and 4,391,936 bytes. Removing terminal material must leave at most 4,096 operations and 4 MiB plus four bytes for run supersession. Closure digests and all session invariants still apply. No operation is pruned. Open files retain their physical 4 MiB limit. Extended archives require a newer reader, including after downgrade. Legacy MAX_SAFE_INTEGER revisions stay readable but have no successor. See terminal recovery.
Every accepted mutation advances one nonnegative revision. Mutation requests carry the expected revision and a stable operation ID. An exact previously accepted request resolves to the same durable entity at its current projection without another mutation. Reusing the ID for another kind or payload fails. Rejected work does not consume the operation ID.
Revision and durable record order are authoritative. Session correctness must not depend on UTC time, model-provided time, elapsed duration, or timestamp repair.
flow_status adds process-local host capability, activity, and detail timing.
Automatic continuation defines these fields and
source-bound progress. They add no Session v5 state or authority.
Every successful status read also derives statusReport from its typed
projection. The report owns human lifecycle and recovery text and is not stored.
At await-user-direction, the manager renders the complete detail report,
including defer/abandon choices and retry authority. A matching failed required
gate may supply its declared command and environment as historical facts; this
does not establish a current failure or convert an observed gate into a repair.
Validation and review defines check and closure
rules. Optional feature checks freeze pass or observe intent at approval.
Flow stores a bounded source-bound packet before assignment. Reviewers page
through it in flow_status without shell access. Missing or stale packets
consume no failed review.
Serial means one durable active feature run and one authoritative combined
validation/review chain. The manager works serially by default, but may delegate
two or three exact, non-overlapping slices to one initial flow-worker cohort
when parallel work has clear benefit, and at most one targeted follow-up cohort.
Existing implementation authority covers a qualifying wave; workers need no
separate user approval.
Workers contribute only inside their assigned boundary. The manager owns shared
files, integration, evidence acceptance, the combined diff, authoritative
validation, and review dispatch. Ordinary worker edits are allowed so a cohort
can run without approval interruptions; Shell, .flow and .git metadata
paths, nested delegation, and Flow-state tools are denied. Exact per-assignment
paths remain a prompt contract because one static reusable agent cannot express
a dynamic file ACL; the manager audits assigned versus changed paths after
every cohort. Every assignment includes the manager's preflighted adversarial
acceptance and risk checklist. Generic agents may not substitute for a
flow-worker or the reserved reviewer. No wave state is persisted; after
interruption, ordinary status and worktree inspection remain authoritative.
ADR 0006 records the rationale and
rejected heavier designs; the package's flow-run guidance is the executable
manager contract.
- Workspace resolution is canonical and project-scoped.
.flowand managed files are not followed through symbolic links.- One cross-process project lock protects transactions.
- Session writes validate the complete schema and use atomic replacement with durability sync where supported.
- Unreadable active state is quarantined instead of overwritten.
- Close first records the terminal state durably, then publishes a no-overwrite archive and clears active state; compact status projects the exact retry request needed to converge after interruption.
- Exact active close replay confirms that the canonical active bytes still
match, synchronizes the file and
.flowdurability boundary, and does not rewrite the Session. Exact archived replay re-synchronizes no-overwrite publication and active cleanup, including when cleanup is already absent. A delayed replay must not clear a different active session. - An archive or active-state collision preserves both documents and returns
manualRecoveryRequiredwith noarchiveRetry; callers stop automatic retry rather than overwrite or delete either side. Closed status re-derives an archive collision from the existing history document, so interruption cannot restore automatic retry. This behavior adds no persisted recovery state. - Every durably accepted close returns identical derived
workflowData.deliveryon success, archive-pending recovery, exact retry, and delayed history replay.handoffdeclaresformatVersion: 1andexternalActionAuthority: "not-granted". Delivery contains goal, closure, progress, each feature's attempts, outcome, terminal findings, reported artifact groups, and tiered assurance limits. Copysummary.linesunchanged. Closure kind, exact unmet commands and declared platforms infer no availability.closure.summary,reportand blockedstatusReportstay unchanged. - Delivery derives from the closed Session or archive. Session v5 and archive JSON store neither projection nor report. A report artifact needs a user request.
- Source identity hashes sorted effective workspace path/type/content tuples;
.gitand.floware excluded. It is a content fingerprint, not a Git audit chain. - Source identity requires a readable Git worktree and rejects tracked submodules explicitly.
- Lock timeout fails closed. Reclamation requires an absent local PID, an exclusive claim, and a matching owner token. Live or unreadable owners are untouched; age grants no ownership. Shared-host or cross-PID-namespace workspaces are unsupported.
Compact flow_status includes the goal and derived findingsDigest, empty as
[]. Blocked state adds featureId, attempt and failedReviewCount. No intent,
hold or retry budget is persisted. At blocked or ready await-user-direction,
read detail once and report findings. Reset-only compatibility never restores
implicit selection. See Session v5.
options.typesafeApiKeyEnv names the server variable (default TYPESAFE_API_KEY).
Names match [A-Za-z_][A-Za-z0-9_]*; invalid names warn and disable the source.
Custom names never fall back. Missing/blank values disable defaults; others are
trimmed at runtime. The key goes only in auth headers, never options, logs or
telemetry. Restart after environment changes. A key enables shadow defaults
(six attempts, $0.02); plugin recovery: { "mode": "off" } disables the source.
--recovery=off disables advice, not retry limits. First retry stays automatic;
fresh direction permits one retry/start. Shadow grants nothing; release
delegation is disabled. recoveryStatus.last adds process-local assessment duration,
transport attempts, reservation deltas, scores, and threshold checks. reservedUsd
is an upper-bound reservation, not billed cost. responseUsage counts only the
final validated response, excluding failed attempts. Without validated usage it
is null. Custom providers may leave transport facts null. See
ADR 0016.
| Command | Contract |
|---|---|
flow-auto |
Normal end-to-end driver for the authorized lifecycle. |
flow-plan |
Plan-only/advanced creation, revision, and approval; same-goal approved plans are reported without mutation. |
flow-run |
Advanced/recovery execution of one approved feature after request alignment. |
flow-review |
Internal/recovery dispatch for a runtime-created reviewer assignment. |
flow-status |
Advanced/recovery projection of compact durable state and the next action. |
flow-review stays in the public inventory because OpenCode dispatches the
reserved reviewer through it and recovery may need it. It is not an ordinary
user starting point.
| Tool | Contract |
|---|---|
flow_guidance |
Load one package-owned guide. |
flow_status |
Read compact, execution, detail, reviewer, or paged reviewer-evidence state. |
flow_plan_save |
Create or replace the active draft plan. |
flow_plan_amend |
Record a bounded prerequisite repair after a failed canonical gate. |
flow_plan_approve |
Approve and lock the draft plan. |
flow_run_start |
Start one runnable approved feature. |
flow_validation_start |
Arm observation of the exact next Shell command. |
flow_review_start |
Create the run's independent review assignment. |
flow_feature_complete |
Reviewer-only result submission; exact accepted requests replay read-only. |
flow_feature_reset |
Supersede a failed attempt and optionally atomically start the exact authorized retry or dependency-independent feature through nextFeatureId. |
flow_session_close |
Close and archive the session, returning the same concise derived delivery and tiered assurance on every durably accepted close path. |
Tools accept nested request and return state under workflowData; mutations
require a current revision and stable operation ID. Closure adds derived delivery.
flow_guidance instead takes an ID and returns Markdown; see authoring.
| Guide | Contract |
|---|---|
flow |
Manager orientation and authority boundary. |
flow-plan |
Planning and conversational approval. |
flow-run |
Serial execution and optional bounded waves. |
flow-review |
Independent review of one runtime assignment. |
Hidden agents
| Agent | Boundary |
|---|---|
flow-planner |
Draft advice using read, glob, and grep. The manager saves and approves. |
flow-worker |
Bounded implementation contribution; ordinary edits are allowed, while Shell, .flow and .git metadata paths, external-directory access, skills, delegation, and Flow tools are denied. |
flow-reviewer |
Independent workspace-read-only inspection; only flow_status and its exact flow_feature_complete lifecycle submission are allowed among Flow tools. |
Project modelPreferences options take precedence over global picker choices.
Global choices override reviewer options and environment defaults. A role reset
restores its base configuration. Explicit picker selections clear that role's
reasoning variant.
Status reports requested roles and the latest observed coding model. These are
process-local observations. Manager variants survive continuation. Configuration
does not confirm provider execution.
Duplicate plugin instances for the same canonical project fail closed through a small process-global guard. Instances for different projects do not conflict. The guard does not elect a winning version or modify configuration.
The public package is loaded through OpenCode's ordinary npm plugin configuration and native plugin command. Flow ships no installer CLI and performs no startup activation, cache cleanup, inventory, version election, or automatic repair.
The deterministic local gate is bun run check. CI keeps a normal Linux check,
targeted platform persistence coverage, dependency and workflow checks, a real
OpenCode live smoke, package smoke, and release publication. Removed lifecycle
soaks, harness promotion, replay, and cross-version active session gates must not
return without a new ADR that removes an equal or larger amount of product
machinery.
Model evals are the one exception, admitted by
ADR 0010 against the prompt prose the
declared gate replaced. They run weekly and on demand in one workflow, never in a
gate a contributor waits on, and skip themselves without a configured matrix or
credentials. bun run qualify seals a complete campaign and exact canary. A
scenario without a threshold, or a required scenario the report omitted, fails.
Bounded-wave coverage should test the real agent permissions, manager guidance, and host-visible configuration without adding a scheduler or tests-of-tests.
See Model-driven wave evidence for the manual canary policy.
The optional ./tui export provides /flow-models. It saves role preferences
after confirmation and adds no lifecycle tool.