opencode-plugin-flow 6.1.0 → 6.2.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 (5) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +71 -157
  3. package/dist/index.js +98 -129
  4. package/dist/index.js.map +12 -11
  5. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -6,6 +6,28 @@ One short entry per release, written for users deciding whether to upgrade.
6
6
 
7
7
  No changes yet.
8
8
 
9
+ ## [6.2.0] - 2026-07-21
10
+
11
+ Low-friction bounded-wave lore keeps Flow small while making parallel
12
+ contribution practical:
13
+
14
+ - Ordinary worker edits no longer stop for approval. Bash, `.flow` and `.git`
15
+ metadata paths, external-directory access, skills, delegation, and Flow
16
+ lifecycle tools stay denied; the manager runs every executable check and
17
+ audits assigned versus changed paths.
18
+ - `flow-run` now instructs the manager to issue every cohort task in one
19
+ tool-use turn and report a serialized host/model execution honestly. Serial,
20
+ two-worker, three-worker, and one-follow-up canaries exercised failure,
21
+ convergence, validation, review, and closure; a final candidate canary also
22
+ completed an overlapping two-worker run with zero approval prompts. None of
23
+ this adds a scheduler or durable wave state.
24
+ - An exact validation command that has started remains eligible for its
25
+ after-hook; only a command that never starts expires after 15 minutes.
26
+ - Review-result semantics now have one domain-owned rule set, and the duplicate
27
+ runtime guard exposes only its operational result, reason, and message.
28
+ - Operator documentation is shorter and leads with exact install/update,
29
+ approval, status, and recovery behavior. Installation now pins `6.2.0`.
30
+
9
31
  ## [6.1.0] - 2026-07-21
10
32
 
11
33
  Bounded intra-feature wave lore restores useful host-native parallel
package/README.md CHANGED
@@ -1,47 +1,46 @@
1
1
  # Flow Plugin for OpenCode
2
2
 
3
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 keeps
5
- its durable lifecycle serial while allowing bounded parallel implementation
6
- inside one active feature:
4
+ that benefits from an approved plan and an independent review:
7
5
 
8
6
  ```text
9
- plan → approve → one active feature → optional worker wave → integrate → validate → independent review → next or close
7
+ plan → approve → run one feature → validate → review → repeat or close
10
8
  ```
11
9
 
12
- For multi-feature plans, the run/validate/review step repeats one feature at a
13
- time. Only the implementation work inside that run may fan out. State lives in
14
- `.flow/session.json`, so the workflow can resume after a restart or context
15
- change without turning Flow into a general orchestration framework.
10
+ Flow keeps one durable active feature run at a time. When implementation divides
11
+ cleanly, the manager may ask a small host-native worker cohort to contribute in
12
+ parallel before it validates and reviews the combined result.
16
13
 
17
14
  ## Install
18
15
 
19
16
  Install the exact npm release through OpenCode:
20
17
 
21
18
  ```bash
22
- opencode plugin opencode-plugin-flow@6.1.0 --global --force
19
+ opencode plugin opencode-plugin-flow@6.2.0 --global --force
23
20
  ```
24
21
 
25
- Omit `--global` for project scope. To update, replace `6.1.0` with the new exact
26
- release and rerun the command. OpenCode owns package installation and config
27
- mutation; Flow does not scan projects, delete caches, elect versions, or repair
28
- configuration.
22
+ Omit `--global` for project scope. Exact version pins do not update
23
+ automatically. To update, replace `6.2.0` with the new release and rerun the
24
+ command.
25
+
26
+ Before upgrading from Flow v5 or earlier, finish or explicitly close any active
27
+ session with its original Flow version. Flow v6 opens only Session v5 active
28
+ state; older archives remain inert history.
29
29
 
30
30
  The equivalent manual project configuration is:
31
31
 
32
32
  ```json
33
33
  {
34
34
  "$schema": "https://opencode.ai/config.json",
35
- "plugin": ["opencode-plugin-flow@6.1.0"]
35
+ "plugin": ["opencode-plugin-flow@6.2.0"]
36
36
  }
37
37
  ```
38
38
 
39
- Then restart OpenCode. OpenCode resolves npm plugins from this configuration;
40
- see the official [OpenCode plugin documentation](https://opencode.ai/docs/plugins/).
41
-
42
- Flow has no installer or activation CLI. Removing the configuration entry
43
- disables Flow. If two Flow copies load for the same project, both fail closed
44
- until the duplicate is removed.
39
+ Restart OpenCode after changing configuration. OpenCode owns package
40
+ installation and configuration; see its
41
+ [plugin documentation](https://opencode.ai/docs/plugins/). Flow has no installer
42
+ or activation CLI. Removing the plugin entry disables it. If two Flow copies
43
+ load for one project, both fail closed until the duplicate is removed.
45
44
 
46
45
  ## Quick start
47
46
 
@@ -51,154 +50,69 @@ Start a complete workflow:
51
50
  /flow-auto add rate limiting to the public API
52
51
  ```
53
52
 
54
- Flow inspects the Git worktree, saves a feature DAG, and asks for approval unless
55
- the request already grants that authority. It then starts one runnable feature,
56
- arms the exact validation command, creates one independent review assignment,
57
- and records the result. `/flow-status` reports the durable next action at any
58
- time.
53
+ Flow inspects the worktree, proposes a feature plan, and asks for approval
54
+ unless your request already authorized implementation. It then runs one
55
+ runnable feature at a time, validates the actual workspace, obtains an
56
+ independent review, and repeats until it can close the session.
59
57
 
60
- Use a narrower command when you want to control the phase:
58
+ For more control, plan first:
61
59
 
62
60
  ```text
63
61
  /flow-plan add rate limiting to the public API
64
- /flow-run
65
- /flow-status
66
62
  ```
67
63
 
68
- Asking for a plan only stops after planning. Flow does not infer permission to
69
- implement, commit, push, or publish from a planning request.
70
-
71
- ## Lifecycle
72
-
73
- An approved plan is immutable and contains a directed acyclic graph of
74
- features. The runtime starts only a feature whose dependencies are complete,
75
- and only one run may be active.
76
-
77
- For each run:
78
-
79
- 1. The manager implements the feature serially by default. Flow guidance permits
80
- an ephemeral worker cohort only when it can name two or three genuinely
81
- independent slices with exact, non-overlapping ownership.
82
- 2. Each `flow-worker` instance returns its bounded contribution and evidence to
83
- the manager. Workers cannot delegate, operate outside the project, call Flow
84
- tools, or approve their own work. One targeted follow-up cohort may address a
85
- concrete gap, retry, or consequential verification; automatic further waves
86
- are not allowed.
87
- 3. The manager inspects and integrates the combined work, accepts or rejects
88
- worker evidence, and remains the only owner of lifecycle mutations. Shared
89
- contracts and integration files stay manager-owned.
90
- 4. `flow_validation_start` binds the current run and workspace-content digest
91
- to the exact next Bash command.
92
- 5. OpenCode observes that command's structured exit status and output
93
- completeness, then records the observation directly in Session v5.
94
- 6. `flow_review_start` records the changed artifact paths, selects applicable
95
- passing validation, and creates one durable assignment for the hidden
96
- `flow-reviewer`.
97
- 7. `flow_feature_complete` records the review result and marks the run complete
98
- or blocked.
99
-
100
- The worker wave is an execution convenience, not another lifecycle. Flow writes
101
- no wave ledger, manifest, or sidecar file. If execution is interrupted, the
102
- manager recovers from ordinary Flow status and worktree inspection, then reruns
103
- or finishes uncovered work. The manager always performs combined authoritative
104
- validation before the one independent review. The cohort limit is a guidance
105
- contract, not a scheduler or admission gate; the runtime enforces worker
106
- permissions and the existing one-run validation/review boundary.
107
-
108
- The final runnable feature derives a `final` review instead of adding a second
109
- review pass. It requires broad passing validation for current workspace
110
- content. Every other run derives a feature review. A failed review blocks the
111
- feature; `flow_feature_reset` supersedes the failed run and creates a fresh full
112
- attempt with no carried validation or review.
113
-
114
- After every feature passes, `flow_session_close` records the terminal
115
- disposition and archives the session. A session may also be closed explicitly
116
- as deferred or abandoned.
64
+ Review the proposed plan and approve it conversationally. `/flow-plan` does not
65
+ silently grant permission to implement, commit, push, or publish. After
66
+ approval, use `/flow-run` to run or resume one feature.
67
+
68
+ At any point, `/flow-status` reports the durable state and next action.
69
+
70
+ ## How Flow works
71
+
72
+ 1. Planning saves a small feature DAG. Approval locks it.
73
+ 2. `/flow-run` starts one feature whose dependencies are complete.
74
+ 3. The manager implements it serially or integrates an optional bounded worker
75
+ wave.
76
+ 4. Flow observes the exact armed validation command against the current
77
+ workspace, then creates one independent review assignment.
78
+ 5. A passing feature advances the plan. A blocked feature is reset as a fresh
79
+ full attempt. The final passing feature allows explicit closure.
80
+
81
+ State lives in `.flow/session.json`, so `/flow-status` can recover the next
82
+ action after a restart or context change.
83
+
84
+ ## Bounded parallelism
85
+
86
+ Parallel contribution is optional and local to one active feature. The manager
87
+ may launch two or three `flow-worker` instances only for exact,
88
+ non-overlapping slices, then inspect and integrate their work. At most one
89
+ targeted follow-up wave may address a concrete gap.
90
+
91
+ Workers cannot delegate, call Flow lifecycle tools, or approve their own work.
92
+ Flow persists no wave state: the manager remains responsible for the combined
93
+ diff, authoritative validation, and the one independent review. Small or
94
+ integration-heavy tasks stay serial.
117
95
 
118
96
  ## Commands
119
97
 
120
98
  | Command | Purpose |
121
99
  | --- | --- |
122
- | `/flow-auto <goal>` | Drive the authorized lifecycle, stopping after planning when requested. |
123
- | `/flow-plan <goal>` | Create or approve a plan. |
100
+ | `/flow-auto <goal>` | Drive the authorized lifecycle; stop after planning if implementation was not authorized. |
101
+ | `/flow-plan <goal>` | Create, revise, or approve a plan through conversation. |
124
102
  | `/flow-run` | Run or resume one approved feature. |
125
- | `/flow-review` | Dispatch the independent read-only reviewer. |
103
+ | `/flow-review` | Internal/recovery dispatch for a runtime-created reviewer assignment. |
126
104
  | `/flow-status` | Inspect the active session and next action. |
127
105
 
128
- Flow registers exactly two hidden subagents: `flow-worker` and
129
- `flow-reviewer`. The implementation worker is reusable across a bounded wave;
130
- edits and Bash require host approval, while external-directory access, skill
131
- loading, delegation, and every Flow tool are denied. The reviewer remains
132
- read-only and can read reviewer status, but cannot edit files, run Bash, load
133
- skills, delegate work, or call state-changing Flow tools. The root manager owns
134
- the lifecycle, integration, and evidence acceptance.
106
+ Ordinary workflows start with `/flow-auto`, `/flow-plan`, `/flow-run`, or
107
+ `/flow-status`. `/flow-review` remains public for runtime dispatch and recovery,
108
+ but it is not an ordinary starting point.
135
109
 
136
- ## Tools
110
+ ## Recovery
137
111
 
138
- The plugin exposes ten tools:
139
-
140
- | Tool | Purpose |
141
- | --- | --- |
142
- | `flow_guidance` | Load one concise package-owned guide. |
143
- | `flow_status` | Read compact, execution, detail, or reviewer state. |
144
- | `flow_plan_save` | Create or replace the active draft plan. |
145
- | `flow_plan_approve` | Approve and lock the current plan. |
146
- | `flow_run_start` | Start one runnable approved feature. |
147
- | `flow_validation_start` | Arm observation for the exact next Bash command. |
148
- | `flow_review_start` | Create the run's one independent review assignment. |
149
- | `flow_feature_complete` | Record the review result and feature outcome atomically. |
150
- | `flow_feature_reset` | Reset a feature and its dependents for a fresh full retry. |
151
- | `flow_session_close` | Close and archive a session in one operation. |
152
-
153
- The nine lifecycle tools use a strict nested `request` object and return state
154
- under `workflowData`. Mutations require the current session revision and a
155
- stable operation ID. Repeating the exact accepted operation is idempotent;
156
- reusing its ID for different input fails. `flow_guidance` is the one exception:
157
- it accepts `{ "id": "..." }` and returns the guide as Markdown.
158
-
159
- ## Guides
160
-
161
- Flow exposes exactly four concise guides through `flow_guidance`:
162
-
163
- | Guide | Purpose |
164
- | --- | --- |
165
- | `flow` | Orient the manager to the complete lifecycle and authority boundary. |
166
- | `flow-plan` | Create a small approved feature DAG. |
167
- | `flow-run` | Execute one feature, optionally using a bounded worker wave. |
168
- | `flow-review` | Perform the run's independent review assignment. |
169
-
170
- ## What the runtime enforces
171
-
172
- - Session v5 is the only active document format supported by Flow v6. Finish or
173
- close older active sessions before upgrading; old archives are inert history.
174
- - Lifecycle order is carried by revisions and durable record order, not UTC
175
- timestamps or caller clocks.
176
- - Plans are immutable after approval, dependencies must be acyclic, and only one
177
- durable run can be active. An ephemeral worker wave does not create additional
178
- runs or concurrent Flow state.
179
- - Validation must be observed from the exact armed Bash command. Failed,
180
- incomplete, stale-source, or mismatched observations cannot authorize review.
181
- - Each run has one review. Final-feature review requires broad validation;
182
- there is no targeted-then-broad dual pass.
183
- - Completion fails if workspace content changed after review started.
184
- - Failed review retries are full resets, not correction modes or delta-scoped
185
- review protocols.
186
- - Every blocking review finding carries concrete artifact, missing-evidence, or
187
- unmet-requirement evidence.
188
- - `.flow/session.json` is written under a project lock with schema validation,
189
- atomic replacement, quarantine for unreadable state, and no-follow path
190
- checks. Closed state is archived beneath `.flow/history/`.
191
- - Source binding requires a readable Git worktree. Git submodules are rejected
192
- explicitly; Flow does not claim to fingerprint work split across repositories.
193
- - Duplicate runtime copies for one project fail closed. This is a safety guard,
194
- not version election or automatic configuration repair.
195
-
196
- Flow deliberately does not include orchestration profiles, worker admission,
197
- wave telemetry or ledgers, audit-ledger rendering, replay reports, detached
198
- validation receipts, or automatic activation and cache repair. Bounded waves
199
- restore useful host-native parallel contribution without reviving that
200
- machinery. They are a capability boundary, not a claim of measured performance
201
- improvement.
112
+ Start with `/flow-status`; its next action is authoritative. Do not hand-edit
113
+ `.flow/session.json` to bypass a gate. If validation, review, locking,
114
+ fingerprinting, or archive publication fails, follow the focused steps in
115
+ [troubleshooting](docs/troubleshooting.md).
202
116
 
203
117
  ## Development
204
118
 
@@ -215,11 +129,11 @@ tests, and package smoke. Release CI also exercises the packed plugin in a real
215
129
  OpenCode host.
216
130
 
217
131
  Maintained documentation starts at [docs/index.md](docs/index.md). See
218
- [development](docs/development.md) for repository structure and focused checks,
219
- [troubleshooting](docs/troubleshooting.md) for recovery, and
220
- [ADR 0005](docs/adr/0005-flow-v6-session-v5-simplicity-first.md) for the v6
221
- tradeoffs. [ADR 0006](docs/adr/0006-bounded-intra-feature-waves.md) defines the
222
- bounded intra-feature wave amendment.
132
+ [development](docs/development.md) for repository structure,
133
+ [troubleshooting](docs/troubleshooting.md) for recovery,
134
+ [the maintainer contract](docs/maintainer-contract.md) for tools and runtime
135
+ invariants, and [ADR 0006](docs/adr/0006-bounded-intra-feature-waves.md) for the
136
+ bounded-wave rationale.
223
137
 
224
138
  ## License
225
139