opencode-plugin-flow 5.3.3 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/CHANGELOG.md +41 -0
  2. package/README.md +143 -309
  3. package/dist/index.js +2790 -13955
  4. package/dist/index.js.map +27 -41
  5. package/package.json +4 -20
  6. package/dist/cli.js +0 -2925
  7. package/dist/cli.js.map +0 -15
package/CHANGELOG.md CHANGED
@@ -2,6 +2,47 @@
2
2
 
3
3
  One short entry per release, written for users deciding whether to upgrade.
4
4
 
5
+ ## [Unreleased]
6
+
7
+ No changes yet.
8
+
9
+ ## [6.0.0] - 2026-07-21
10
+
11
+ Simplicity-first lifecycle lore turns Flow back into a small, durable serial
12
+ workflow:
13
+
14
+ - Session v5 replaces Session v4 with one canonical feature-run aggregate,
15
+ revision/operation-ID idempotency, session-native validation, derived status,
16
+ and no wall-clock correctness fields.
17
+ - Every run receives one independent review. The final feature derives one
18
+ final review requiring broad validation; failed reviews reset to a fresh full
19
+ run instead of entering correction modes, and blocking findings require
20
+ concrete evidence.
21
+ - The public surface is reduced to ten tools, five commands, and one hidden
22
+ read-only `flow-reviewer`.
23
+ - Orchestration profiles and admission, audit-ledger rendering, replay and
24
+ prompt-evaluation systems, detached validation receipts, and activation/cache
25
+ repair are removed.
26
+ - Installation uses OpenCode's own plugin command with an exact npm version.
27
+ Flow ships no installer, cache inventory, or automatic configuration repair.
28
+
29
+ Breaking changes: Flow v6 does not migrate active pre-v6 sessions or replay
30
+ their operations. Finish or close them before upgrading. Old archives remain
31
+ inert history. Validation interrupted before Session v5 persistence must be
32
+ rerun, and plugin configuration conflicts require manual repair.
33
+
34
+ ## [5.3.4] - 2026-07-20
35
+
36
+ Retry-safe release publishing lore makes partial registry or GitHub outages
37
+ recoverable without moving a tag or weakening package integrity:
38
+
39
+ - A rerun skips an existing npm version only when the registry SHA-512 exactly
40
+ matches the freshly packed tarball; conflicting bytes fail closed.
41
+ - GitHub release metadata is created independently from tarball and checksum
42
+ uploads, so one failed asset no longer rolls back the release transaction.
43
+ - Idempotent release edits and asset uploads use bounded retries, while release
44
+ lookup distinguishes a missing release from an unavailable GitHub API.
45
+
5
46
  ## [5.3.3] - 2026-07-20
6
47
 
7
48
  Project-scoped runtime leadership lore restores global Flow activation in the
package/README.md CHANGED
@@ -1,354 +1,188 @@
1
1
  # Flow Plugin for OpenCode
2
2
 
3
- `opencode-plugin-flow` gives OpenCode a durable, resumable planning-and-execution
4
- loop for larger coding work: plan a goal as discrete features, approve the plan,
5
- then implement one feature at a time with enforced validation and review
6
- evidence. State lives in `.flow/session.json`, so a session survives restarts,
7
- model switches, and context loss.
3
+ `opencode-plugin-flow` gives OpenCode a small, durable workflow for coding work
4
+ that benefits from an approved plan and an independent review. Flow v6 is
5
+ serial by design:
8
6
 
9
- The design is guidance-first: package-owned Markdown carries planning,
10
- execution, validation, review, and orchestration judgment, while the plugin
11
- runtime stays bounded and policy-focused — it keeps the session ledger and
12
- enforces the hard gates prompts should not be trusted to remember.
7
+ ```text
8
+ plan → approve → run one feature → validate → one independent review → close
9
+ ```
13
10
 
14
- The maintained documentation starts at [docs/index.md](docs/index.md). The
15
- tracked `droid-wiki/` tree is an archived generated snapshot and is not a
16
- current product or contributor contract.
11
+ For multi-feature plans, the run/validate/review step repeats one feature at a
12
+ time. State lives in `.flow/session.json`, so the workflow can resume after a
13
+ restart or context change without turning Flow into a general orchestration
14
+ framework.
17
15
 
18
- ## Quick start
16
+ ## Install
17
+
18
+ Install the exact npm release through OpenCode:
19
19
 
20
20
  ```bash
21
- npx -y opencode-plugin-flow@latest install \
22
- --project "$PWD" --scope global
21
+ opencode plugin opencode-plugin-flow@6.0.0 --global --force
23
22
  ```
24
23
 
25
- `install` resolves npm's current release before it starts, writes that package's
26
- embedded exact version as the sole Flow activation, and permanently removes
27
- positively identified older Flow wrappers and OpenCode cache artifacts. It
28
- refuses a downgrade when a newer installed version is detected. The final check
29
- performed by that same fetched CLI must report exactly one active Flow source at
30
- the installed exact version and no proven inactive Flow cache artifacts. Do not
31
- resolve `@latest` a second time for post-install verification. Inventory covers
32
- global sources plus the selected `--project`; it does not scan unrelated project
33
- trees. Run the installer from each project that has its own OpenCode config. Use
34
- `--scope project` when the canonical pin should live with that selected project
35
- instead of global config.
36
-
37
- For a read-only preview, run `activation-apply` without `--apply` using an exact
38
- package version. Flow refuses ambiguous local wrappers, cache entries, unsafe
39
- links, and config it cannot change conservatively rather than guessing which
40
- copy is authoritative.
41
-
42
- Start or restart OpenCode, then give Flow a goal:
24
+ Omit `--global` for project scope. To update, replace `6.0.0` with the new exact
25
+ release and rerun the command. OpenCode owns package installation and config
26
+ mutation; Flow does not scan projects, delete caches, elect versions, or repair
27
+ configuration.
28
+
29
+ The equivalent manual project configuration is:
30
+
31
+ ```json
32
+ {
33
+ "$schema": "https://opencode.ai/config.json",
34
+ "plugin": ["opencode-plugin-flow@6.0.0"]
35
+ }
36
+ ```
37
+
38
+ Then restart OpenCode. OpenCode resolves npm plugins from this configuration;
39
+ see the official [OpenCode plugin documentation](https://opencode.ai/docs/plugins/).
40
+
41
+ Flow has no installer or activation CLI. Removing the configuration entry
42
+ disables Flow. If two Flow copies load for the same project, both fail closed
43
+ until the duplicate is removed.
44
+
45
+ ## Quick start
46
+
47
+ Start a complete workflow:
43
48
 
44
49
  ```text
45
50
  /flow-auto add rate limiting to the public API
46
51
  ```
47
52
 
48
- Flow inspects the repo, saves a plan of features, asks for approval (or
49
- proceeds if you already authorized autonomous work), then runs the loop:
50
- implement one feature → validate it → review it → record evidence → next
51
- feature. `/flow-status` shows where you are at any point, including after a
52
- restart.
53
-
54
- `/flow-auto` still respects the scope of the request. If you ask for a plan
55
- only or explicitly say not to implement, it saves and summarizes the plan and
56
- stops before `flow_run_start`.
53
+ Flow inspects the Git worktree, saves a feature DAG, and asks for approval unless
54
+ the request already grants that authority. It then starts one runnable feature,
55
+ arms the exact validation command, creates one independent review assignment,
56
+ and records the result. `/flow-status` reports the durable next action at any
57
+ time.
57
58
 
58
- ## What a session looks like
59
+ Use a narrower command when you want to control the phase:
59
60
 
60
61
  ```text
61
- > /flow-auto add rate limiting to the public API
62
-
63
- flow_plan_save goal: "add rate limiting to the public API"
64
- features: rate-limit-middleware, per-route-config, docs-update
65
- (you approve the plan)
66
- flow_plan_approve plan locked — features are now immutable
67
- flow_run_start mutation acknowledged
68
- flow_status request.view: execution, feature: rate-limit-middleware
69
- ... implementation, tests ...
70
- flow_validation_start
71
- command: exact next Bash command
72
- coverageScope: focused
73
- bash exact armed command
74
- [flow-validation-receipt] immutable receipt reference
75
- flow_review_start request.validationRefs: [receipt reference]
76
- request.reviewKind: feature
77
- request.validationScope: targeted
78
- assignmentId: review-assignment:runtime-id
79
- flow_status request.view: reviewer
80
- request.assignmentId: review-assignment:runtime-id
81
- ... independent review ...
82
- flow_feature_complete
83
- request.result.kind: completed
84
- request.result.validationScope: targeted
85
- request.result.featureReview.assignmentId: review-assignment:runtime-id
86
- request.result.featureReview.verdict: passed
87
- flow_run_start mutation acknowledged
88
- flow_status request.view: execution, feature: per-route-config
89
- ...
90
-
91
- > /flow-status
92
- status: ok
93
- workflowData.projection.view: compact
94
- workflowData.projection.status: running
95
- workflowData.projection.progress: { completed: 1, total: 3, remaining: 2 }
96
-
97
- > /flow-run
98
- flow_status request.view: execution
99
- workflowData.projection: full active-feature scope
62
+ /flow-plan add rate limiting to the public API
63
+ /flow-run
64
+ /flow-status
100
65
  ```
101
66
 
102
- `flow_status` returns workflow state under `workflowData.projection`: compact is
103
- routing-only, execution is the full active-feature working scope, detail is
104
- diagnostic, and reviewer is narrow assignment context. State-changing tools
105
- return `workflowData.receipt` acknowledgements; a receipt never replaces a
106
- fresh status projection. Rejected mutations explicitly report
107
- `operationAccepted: false` and `operationIdConsumed: false`; accepted results,
108
- including durable review blockers, report the corresponding accepted receipt.
67
+ Asking for a plan only stops after planning. Flow does not infer permission to
68
+ implement, commit, push, or publish from a planning request.
109
69
 
110
- Interrupt at any point; `/flow-run` resumes the next approved feature. On the
111
- final feature Flow requires broad project-level validation and a final review
112
- whose depth matches the approved plan before the session can close as
113
- completed.
70
+ ## Lifecycle
71
+
72
+ An approved plan is immutable and contains a directed acyclic graph of
73
+ features. The runtime starts only a feature whose dependencies are complete,
74
+ and only one run may be active.
75
+
76
+ For each run:
77
+
78
+ 1. The manager implements the feature.
79
+ 2. `flow_validation_start` binds the current run and workspace-content digest
80
+ to the exact next Bash command.
81
+ 3. OpenCode observes that command's structured exit status and output
82
+ completeness, then records the observation directly in Session v5.
83
+ 4. `flow_review_start` records the changed artifact paths, selects applicable
84
+ passing validation, and creates one durable assignment for the hidden
85
+ `flow-reviewer`.
86
+ 5. `flow_feature_complete` records the review result and marks the run complete
87
+ or blocked.
88
+
89
+ The final runnable feature derives a `final` review instead of adding a second
90
+ review pass. It requires broad passing validation for current workspace
91
+ content. Every other run derives a feature review. A failed review blocks the
92
+ feature; `flow_feature_reset` supersedes the failed run and creates a fresh full
93
+ attempt with no carried validation or review.
94
+
95
+ After every feature passes, `flow_session_close` records the terminal
96
+ disposition and archives the session. A session may also be closed explicitly
97
+ as deferred or abandoned.
114
98
 
115
99
  ## Commands
116
100
 
117
101
  | Command | Purpose |
118
102
  | --- | --- |
119
- | `/flow-auto <goal>` | Drive the authorized loop; stop after planning when requested. |
103
+ | `/flow-auto <goal>` | Drive the authorized lifecycle, stopping after planning when requested. |
120
104
  | `/flow-plan <goal>` | Create or approve a plan. |
121
- | `/flow-run` | Execute one approved feature. |
122
- | `/flow-review` | Run a read-only review. |
123
- | `/flow-status` | Show the active session and next action. |
124
-
125
- Commands are compiled entrypoints: manager commands carry only their applicable
126
- core instructions, while `/flow-review` runs against the reserved reviewer's
127
- role-specific agent contract. Flow does not install files into OpenCode's
128
- global skill registry and does not depend on native skill discovery.
105
+ | `/flow-run` | Run or resume one approved feature. |
106
+ | `/flow-review` | Dispatch the independent read-only reviewer. |
107
+ | `/flow-status` | Inspect the active session and next action. |
129
108
 
130
- `flow-test`, `flow-deslop`, `flow-ui-quality`, and `flow-commit` are optional
131
- package-owned guides loaded on demand through `flow_guidance`, not public
132
- commands. `flow-commit` is user-triggered only and stays outside the autonomous
133
- loop.
109
+ Flow registers exactly one hidden worker: `flow-reviewer`. It can read reviewer
110
+ status but cannot edit files, run Bash, load skills, delegate work, or call
111
+ state-changing Flow tools. The root manager owns every mutation.
134
112
 
135
113
  ## Tools
136
114
 
137
- The plugin exposes 12 tools. Nine own the durable lifecycle; three add bounded
138
- harness admission, runtime-attested validation, and deterministic audit
139
- rendering:
115
+ The plugin exposes ten tools:
140
116
 
141
117
  | Tool | Purpose |
142
118
  | --- | --- |
143
- | `flow_guidance` | Load exact package-owned guidance by stable id. |
144
- | `flow_status` | Read the active session and next action. |
145
- | `flow_plan_save` | Create a session or update its active same-goal draft. |
146
- | `flow_plan_approve` | Approve the draft plan. |
147
- | `flow_run_start` | Start the next runnable feature. |
148
- | `flow_review_start` | Bind validation to current source and create a runtime-owned reviewer assignment; final review also binds the passing feature result. |
149
- | `flow_feature_complete` | Atomically record a completed or blocked assignment result. |
150
- | `flow_feature_reset` | Reset one feature and its dependents. |
151
- | `flow_session_close` | Archive the active session as completed, deferred, or abandoned. |
152
- | `flow_orchestration_admit` | Evaluate and arm one bounded optional-worker proposal for the active harness profile. |
153
- | `flow_validation_start` | Arm capture for the exact next Bash command against current causal guards, feature run, and source. |
154
- | `flow_audit_render` | Validate `AuditLedgerV1` and render its reconciled Markdown deterministically. |
155
-
156
- Only the root manager calls `flow_review_start`. Reviewers recover the exact
157
- assignment with
158
- `flow_status { request: { view: "reviewer", assignmentId } }` and return only
159
- the assignment id, verdict, typed findings, reported time, and terminal
160
- disposition. The runtime derives all attempt, pass, source, packet, run,
161
- start-time, and required-depth identity. Final assignment creation durably binds
162
- the exact passing feature-assignment result. The final feature outcome submits
163
- only the final-assignment result; Flow records both results atomically from the
164
- durable binding.
165
-
166
- Validation input is no longer a caller-authored success claim. Immediately
167
- before a check, call `flow_validation_start` with the exact command and current
168
- guards, execute that exact command as the next Bash call, and copy the emitted
169
- immutable receipt reference into `flow_review_start.request.validationRefs`.
170
- Flow verifies receipt bytes, run, feature, current source, host-observed exit,
171
- output completeness, and scope before materializing Session v4 evidence. A
172
- failed, truncated, missing, stale, altered, or duplicate receipt is rejected
173
- without consuming the review-start operation id.
174
-
175
- The first final assignment pins that binding for every same-source final-review
176
- retry. A manager recovering context loads detail status and copies
177
- `workflowData.projection.finalReviewRetry.prerequisite.result` unchanged into
178
- the new final review start's `request.featureReview`. Compact and reviewer views
179
- omit the aggregate. A mismatch records nothing and leaves its operation id
180
- reusable; a source edit requires a new targeted feature-review sequence.
119
+ | `flow_guidance` | Load one concise package-owned guide. |
120
+ | `flow_status` | Read compact, execution, detail, or reviewer state. |
121
+ | `flow_plan_save` | Create or replace the active draft plan. |
122
+ | `flow_plan_approve` | Approve and lock the current plan. |
123
+ | `flow_run_start` | Start one runnable approved feature. |
124
+ | `flow_validation_start` | Arm observation for the exact next Bash command. |
125
+ | `flow_review_start` | Create the run's one independent review assignment. |
126
+ | `flow_feature_complete` | Record the review result and feature outcome atomically. |
127
+ | `flow_feature_reset` | Reset a feature and its dependents for a fresh full retry. |
128
+ | `flow_session_close` | Close and archive a session in one operation. |
129
+
130
+ The nine lifecycle tools use a strict nested `request` object and return state
131
+ under `workflowData`. Mutations require the current session revision and a
132
+ stable operation ID. Repeating the exact accepted operation is idempotent;
133
+ reusing its ID for different input fails. `flow_guidance` is the one exception:
134
+ it accepts `{ "id": "..." }` and returns the guide as Markdown.
181
135
 
182
136
  ## What the runtime enforces
183
137
 
184
- The runtime owns only safety; judgment lives in package-owned guidance:
185
-
186
- - `.flow/session.json` is the single source of truth; writes are locked and
187
- atomic, and closed sessions are archived under `.flow/history/`.
188
- - Plans cannot be changed after approval.
189
- - A different-goal plan save cannot replace an unclosed session, including an
190
- unapproved draft. Close it explicitly as `deferred` or `abandoned` and finish
191
- archive publication before saving the new goal.
192
- - Only one feature run can be active at a time; reset preserves its audit
193
- history but the next start receives a fresh run id.
194
- - Reviewer assignment requires source-bound passing validation: `targeted` for
195
- feature review and `broad` for final review. A source edit invalidates stale
196
- pending review work when its replacement is created.
197
- - Validation receipts are host-attested from the exact next Bash execution.
198
- Callers cannot supply validation timestamps, exit status, command class, or
199
- output digest to `flow_review_start`.
200
- - Feature outcome uses a nested `completed` or `blocked` result. Invalid or stale
201
- input records nothing and does not consume its operation id.
202
- - Each OpenCode handler validates the registered nested schema again at entry;
203
- invalid host invocations fail as tool errors before Flow state I/O.
204
- - The runtime derives review depth from the approved plan and owns assignment,
205
- attempt, logical-pass, packet, source, and start-time identity.
206
- - Failed reviews are bounded: an accepted blocker returns operation status
207
- `ok`, and autonomous repair is limited to one repair plus one retry before
208
- the feature blocks.
209
- - Review exhaustion uses the ordinary blocked-feature state; continuing requires
210
- an explicit `flow_feature_reset`, not a second checkpoint protocol.
211
- - A passing final feature outcome marks progress completed but leaves closure null;
212
- `flow_session_close` exclusively records and archives it.
213
- - Once a closure is recorded, the session is archive-only. If publication fails,
214
- compact status supplies `closure.retryOperationId`; retry only with
215
- `flow_session_close { request: { mode: "retry", operationId } }`. No new
216
- close, run, reset, approval, or replan can reopen or adopt it.
217
- - A new close operation id must be absent from the active causal chain and every
218
- mutation in canonical Session v4 workspace history. Any archived match is a
219
- collision; malformed or ambiguous canonical history fails closed before
220
- active state changes.
221
- - Archive publication requires explicit non-null closure. Closureless Session
222
- v4 state may remain active, but it is rejected as canonical history and makes
223
- canonical lookup fail closed if found there.
224
- - Every closure is quiescent: no active execution or pending review assignment
225
- remains. A session can close as `completed` only after the final feature
226
- outcome has passed.
227
- - Host-observed validation times and reviewer-reported result times must follow
228
- run, validation, and assignment order and cannot postdate runtime acceptance.
229
- - Session locks fail closed: Flow never guesses that an old lock is abandoned,
230
- and only the unique owner may release it. Only a valid Session v4 document can
231
- become active state; canonical history additionally requires explicit
232
- non-null closure.
233
- - Flow writes `.flow/.gitignore` so session state stays out of Git by default.
234
- - `.flow/session.json` is the only active-state representation. Canonical Flow
235
- commands call `flow_status` before acting; plugin configuration does not read,
236
- refresh, or project workspace state.
237
- - Exactly one Flow runtime instance may operate in an OpenCode process. If
238
- duplicate copies load, every copy fails closed; the highest semantic version
239
- is named only as a diagnostic leader and does not become operational.
240
-
241
- ## Hidden workers
242
-
243
- For broad work, Flow's manager can fan out isolated hidden workers
244
- (`flow-evidence-worker`, `flow-validation-worker`, `flow-audit-worker`,
245
- `flow-candidate-worker`, `flow-verifier-worker`, and the `flow-reviewer`) with
246
- locked-down permissions. Workers gather evidence; they never approve plans,
247
- complete features, or close sessions. Flow reserves those agent ids and the
248
- public command ids while the plugin is enabled, and warns if they collide with
249
- your own config.
250
-
251
- Each hidden worker receives only its applicable handoff schema. The manager
252
- contract treats empty or malformed handoffs as coverage gaps instead of
253
- success. The offline handoff validator detects missing headings, empty sections,
254
- unresolved placeholders, and invalid statuses; current OpenCode worker output
255
- remains plain text, so runtime acceptance still depends on the manager applying
256
- that contract. Inspect rendered surfaces and static contracts with
257
- `bun run prompt:quality`; run opt-in model decisions with
258
- `bun run prompt:model-eval -- --model <provider/model> --timeout-ms 300000`;
259
- see
260
- [docs/prompt-quality.md](docs/prompt-quality.md).
261
-
262
- The trusted command footer selects one harness profile with
263
- `OPENCODE_FLOW_HARNESS_PROFILE=control|standard|assurance` (default
264
- `standard`) and one admission rollout with
265
- `OPENCODE_FLOW_ROLLOUT_MODE=control|observe|enforce` (default `observe`).
266
- `control` preserves discretionary optional-worker behavior without admission
267
- ceremony. `standard` admits a small bounded discovery/challenge path;
268
- `assurance` permits broader bounded evidence and audit coverage when risk
269
- justifies it. In `observe`, a policy violation is reported but does not block;
270
- in `enforce`, the exact admitted optional worker class and count must be
271
- dispatched. Lifecycle-required reviewer and validation workers are not optional
272
- passes and do not use orchestration admission. Validation receipts remain
273
- mandatory in every profile.
274
-
275
- Hidden worker routing can be tuned without changing the domain contract. Set
276
- `OPENCODE_FLOW_READONLY_WORKER_MODEL`,
277
- `OPENCODE_FLOW_REVIEW_WORKER_MODEL`, or
278
- `OPENCODE_FLOW_CANDIDATE_WORKER_MODEL`, with
279
- `OPENCODE_FLOW_WORKER_MODEL` as the fallback. Matching `*_WORKER_STEPS`
280
- variables set OpenCode's current `steps` limit; values must be integers from 1
281
- through 1000.
282
-
283
- For broad implementation, the manager records whether work stayed serial,
284
- used exact-path candidate workers, used isolated worktrees, ran a tournament, or
285
- skipped eligible candidates. Feature completion can carry bounded
286
- `result.orchestrationPasses` with candidate eligibility, decision, and structured
287
- factors. Bounded projections report the relevant aggregate while full worker
288
- handoffs remain outside `.flow/**`.
289
-
290
- ## Install details and legacy cleanup
291
-
292
- See [docs/troubleshooting.md](docs/troubleshooting.md) for updates,
293
- activation refusal and duplicate-runtime recovery, stuck session recovery, and
294
- removal of global Flow skill folders left by v4.
295
-
296
- To update, run the same `@latest install` command. The installer inventories
297
- OpenCode's global sources plus the selected project's project, `.opencode`,
298
- custom, inline, and readable managed configuration; singular and plural plugin
299
- directories; and the Flow package cache. Other project trees are deliberately
300
- not discovered; run the command from each project with project-local OpenCode
301
- configuration. It preserves unrelated plugins, removes recognized Flow config
302
- entries outside the selected canonical scope, and permanently removes only
303
- marker-proven wrappers, the exact known legacy wrapper format, and
304
- manifest-proven inactive cache artifacts. Applied changes receive config
305
- backups and a recovery journal. Obsolete artifacts are staged reversibly while
306
- activation changes are verified, restored if activation fails, and deleted
307
- before installation reports success.
308
- Sources that cannot be proved safe—including unknown wrappers, ambiguous cache
309
- artifacts, JSONC that would require a lossy rewrite, inline config, and
310
- administrator-managed config—produce manual remediation instead of mutation.
311
- If an applied multi-source change fails, Flow attempts exact safe rollback and
312
- records either `rolled-back` or `rollback-failed` in the recovery journal;
313
- concurrent or unsafe state is preserved for manual recovery. Remote and
314
- managed-preference sources that cannot be decoded offline remain covered by
315
- fail-closed runtime leadership within each OpenCode project context. A later
316
- install reconciles interrupted v2 journals before planning: pre-commit work is
317
- rolled back, while committed removal work finishes verified deletion.
318
-
319
- To preview recoverable migration of pristine v4 global skill folders:
320
-
321
- ```bash
322
- npx -y opencode-plugin-flow@5.3.3 legacy-cleanup --dry-run
323
- ```
138
+ - Session v5 is the only active document format supported by Flow v6. Finish or
139
+ close older active sessions before upgrading; old archives are inert history.
140
+ - Lifecycle order is carried by revisions and durable record order, not UTC
141
+ timestamps or caller clocks.
142
+ - Plans are immutable after approval, dependencies must be acyclic, and only one
143
+ run can be active.
144
+ - Validation must be observed from the exact armed Bash command. Failed,
145
+ incomplete, stale-source, or mismatched observations cannot authorize review.
146
+ - Each run has one review. Final-feature review requires broad validation;
147
+ there is no targeted-then-broad dual pass.
148
+ - Completion fails if workspace content changed after review started.
149
+ - Failed review retries are full resets, not correction modes or delta-scoped
150
+ review protocols.
151
+ - Every blocking review finding carries concrete artifact, missing-evidence, or
152
+ unmet-requirement evidence.
153
+ - `.flow/session.json` is written under a project lock with schema validation,
154
+ atomic replacement, quarantine for unreadable state, and no-follow path
155
+ checks. Closed state is archived beneath `.flow/history/`.
156
+ - Source binding requires a readable Git worktree. Git submodules are rejected
157
+ explicitly; Flow does not claim to fingerprint work split across repositories.
158
+ - Duplicate runtime copies for one project fail closed. This is a safety guard,
159
+ not version election or automatic configuration repair.
160
+
161
+ Flow deliberately does not include orchestration profiles, optional-worker
162
+ admission, audit-ledger rendering, replay reports, detached validation receipts,
163
+ or automatic activation and cache repair. Those systems increased protocol
164
+ surface without improving the core serial workflow.
324
165
 
325
166
  ## Development
326
167
 
327
- ```bash
328
- bun install
329
- bun run check # typecheck + lint + release metadata + prompt quality + build + tests
330
- bun run harness:report # sanitized control/candidate resource and quality status
331
- bun run smoke:live # boots a real OpenCode server against the packed tarball
332
- ```
333
-
334
- The package exports only the OpenCode plugin entrypoint:
168
+ Requirements: Git, Node.js 24 or newer, Bun 1.3.14, and the versions pinned in
169
+ `package.json`.
335
170
 
336
- ```ts
337
- import flowPlugin from "opencode-plugin-flow";
171
+ ```bash
172
+ bun install --frozen-lockfile
173
+ bun run check
338
174
  ```
339
175
 
340
- See [docs/development.md](docs/development.md) and
341
- [docs/maintainer-contract.md](docs/maintainer-contract.md) for the
342
- v5 domain/application/infrastructure/platform boundaries, guidance split, and
343
- release process.
176
+ The normal check runs typechecking, formatting/lint checks, build verification,
177
+ tests, and package smoke. Release CI also exercises the packed plugin in a real
178
+ OpenCode host.
344
179
 
345
- ## Credits
180
+ Maintained documentation starts at [docs/index.md](docs/index.md). See
181
+ [development](docs/development.md) for repository structure and focused checks,
182
+ [troubleshooting](docs/troubleshooting.md) for recovery, and
183
+ [ADR 0005](docs/adr/0005-flow-v6-session-v5-simplicity-first.md) for the v6
184
+ tradeoffs.
346
185
 
347
- Flow's parallel orchestration guidance was inspired by Ray Fernando's skill
348
- work on parallel agent workflows. Flow also draws conceptual inspiration from
349
- [RepoPrompt CE](https://github.com/repoprompt/repoprompt-ce), especially its
350
- emphasis on codebase orientation, context engineering, agent orchestration,
351
- and reviewable handoffs.
186
+ ## License
352
187
 
353
- The Flow version is its own OpenCode-native design: package-owned guidance,
354
- manager-owned state, hidden workers, and no extra runtime ledger.
188
+ MIT