development.md

Development

Flow is an ESM TypeScript package built and tested with Git and versions pinned in package.json.

Local setup

bun install --frozen-lockfile
bun run check

bun run check is the canonical deterministic gate. Use focused commands while iterating:

bun run typecheck
bun run lint
bun test tests/domain-transitions.test.ts
bun test tests/runtime-gates.test.ts tests/validation-capture.test.ts
bun test tests/workspace-persistence.test.ts
bun run build
bun run package:smoke

The opt-in real-host check launches the exact @opencode/cli host selected in evals/opencode-host.ts. It uses temporary configuration and local scripted provider responses. Registry access or a populated package cache is required. The user's installed OpenCode binary is not the smoke host.

bun run smoke:live

Bumping the pinned host

The plugin, client, schema, and Zod dependencies are deliberately pinned. Update their package and lockfile entries together when their contracts change. The host launcher and release policy have independent explicit pins. SDK package metadata does not choose the qualification host.

1. Probe the selected host's native registration, identity, permissions, output, prompt admission, compaction, and terminal behavior.
2. Update the ordinary host pin and the prospective release policy. Keep retained release pins and policy hashes unchanged.
3. Run frozen install, bun run check, replay, audit, and packed live smoke.
4. Qualify changed package bytes through the full release process.

The peer range permits installation on 2.x. Support claims cover tested hosts. The weekly workflow resolves the latest stable 2.x and reports compatibility outside the blocking pinned-host CI check.

Source layout

• src/domain/ owns Session v5 values, invariants, and transitions that use only JavaScript/Node standard-library primitives.
• src/application/ owns use cases and repository ports.
• src/infrastructure/ owns filesystem persistence and source fingerprinting: fs/workspace-paths.ts (workspace root validation, .flow layout), fs/managed-fs.ts (managed filesystem primitives), fs/session-lock.ts (cross-process session lock), fs/workspace.ts (session file protocol).
• src/platform/opencode/ owns OpenCode hooks, host schemas, commands, tools, validation capture, and the duplicate-runtime guard: command-hook.ts (native command registration), tool-guard.ts (leadership and auto-drive guard around the tools), auto-drive-decision.ts (pure idle-routing decision, decideOnIdle, run by auto-drive.ts), plugin.ts (wiring only).
• src/guidance/, skills/, and prompt surfaces own concise workflow judgment.
• tests/ prove state-machine, persistence, platform, package, and host contracts.

Dependencies point inward. Domain code does not import filesystem or host APIs; application code depends on domain; infrastructure implements application ports; the OpenCode platform composes outer layers.

There is no distribution/activation subsystem, cache inventory, repair journal, or Flow-owned installer: OpenCode installs and loads the npm package from its native plugin command and configuration. Flow model preferences live in a separate plugin-owned file and reload role transforms across instances.

Change discipline

• Keep Session v5 as one canonical run aggregate: derive status and progress, not parallel ledgers or cached counters.
• Every mutation needs a revision guard and stable operation ID. Exact replay is safe; conflicting reuse fails.
• Only the reserved reviewer may create a new completion; while the Session v5 workflow remains active, every other caller gets an exact accepted-completion replay through a read-only path that neither cancels validation nor writes session state.
• Keep validation host-observed and session-native: no caller-authored success, detached receipt stores, or clock requirements.
• Treat validation scope as a coverage claim: broad means the canonical repository gate, byte for byte, not a narrow command relabeled.
• Validation commands are persisted, never with inline secrets. Raw output is intentionally reduced to completeness and a digest rather than stored or projected.
• Keep one review per run. A final review requires broad validation and is not a second pass. The reviewer submits through flow_feature_complete; the manager never proxies its verdict.
• Prefer deletion when a test or document exists only for a removed concept, not a dual stack for pre-v6 active state.
• Use table-driven lifecycle and persistence tests, not registries that test the presence of other tests.

Documentation

Update the README, maintainer contract, ADR, and changelog when a public lifecycle or installation contract changes. Documentation must describe only the current product; Git history owns superseded plans and experiments.

Model-driven wave evidence

Deterministic CI validates schemas, permissions, prompts, and host integration without provider credentials. It does not claim a model overlaps workers, so wave-behavior changes need manual exercise with a real provider when available, with sanitized evidence of:

• worker start/end times with a positive common overlap;
• assigned versus changed paths and any scope drift;
• permission prompts or denials and worker Shell calls; and
• reviewer-owned flow_feature_complete submission.

Every wave-behavior change needs this evidence when marked verified, but it is not a deterministic release gate. Without a provider, mark the behavior unverified, record the review risk, and avoid performance or reliability claims. Do not persist prompts, secrets, raw provider payloads, or a wave ledger, or add provider credentials, a scheduler, or telemetry to CI.

Model-driven auto-continuation evidence

Deterministic tests exercise the coordinator through the real plugin hooks and the promptAsync client boundary, but not how a configured model behaves after delivery. When auto-continuation behavior changes and a provider is available, run one packed-plugin canary recording sanitized evidence of:

• idle ready delivery with the Flow token and compact revision;
• recommendation or clarification at a checkpoint remaining waiting, followed by a same-host accepted approval resuming exactly once while an other-host revision advance does not;
• compaction retaining the manager kernel and reserved Flow roles;
• one automatic fresh retry only at failedReviewCount === 1 without a scopeBlocker finding, with every higher count awaiting user direction;
• one reviewed retry preserving prior findingId values, refreshed baseline facts, prior dispositions, and its applicable transition matrix; and
• confirmed completed closure with the final conversational disposition map reconstructed from the existing concise workflowData.delivery.

Use the existing host transcript and Flow detail projection; add no telemetry or persisted continuation state. Keep credentials, raw provider payloads, and user content out of evidence. This is an opt-in provider canary, not a CI model evaluation. If unavailable, mark model behavior unverified while retaining the deterministic hook and lifecycle gates.

Release

Follow the frozen-candidate sequence: finish fixes and dependency updates, pass deterministic checks, approve paid evals. bun run qualify -- --campaign-dir <dir> --canary <record> seals the policy grid, canary and grader evidence. 10.0.0/10.0.1/10.0.2 pin openai/gpt-6.1-sol. See model policy for historical exceptions and later defaults. Commit the bundle before tagging; interrupted results cannot qualify.

Release tags use v<package-version>. Blocking release checks: the normal repository gate, package smoke, packed live OpenCode smoke, package integrity generation, npm publication, and GitHub release assets. There is no cross-version active-session gate; v6 is an explicit hard cutover.

Publication accepts both annotated and lightweight tags, but the freshly fetched tag, workflow event, checkout, and current remote main tip must identify the same commit immediately before npm publication. Network calls have explicit deadlines. npm publication reconciles the immutable package integrity after every result, including timeouts. GitHub publication builds an exact draft under the same ref proof. That draft recovers if npm succeeds and main advances. Finalization rechecks the remote tag, refuses conflicting metadata or assets, and publishes only after every asset digest matches. Reruns converge after partial success without replacing published bytes.

Preparing an already-published release is read-only and requires exact assets. Missing or pending assets fail preparation; use the github-publish recovery path with original inputs and tag proof to restore a missing asset.