opencode-plugin-flow 6.0.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 +36 -0
  2. package/README.md +65 -113
  3. package/dist/index.js +174 -116
  4. package/dist/index.js.map +12 -11
  5. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -6,6 +6,42 @@ 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
+
31
+ ## [6.1.0] - 2026-07-21
32
+
33
+ Bounded intra-feature wave lore restores useful host-native parallel
34
+ contribution without restoring the former orchestration framework:
35
+
36
+ - A reusable hidden `flow-worker` can run as two or three concurrent instances
37
+ with exact, non-overlapping slices inside the one active run, followed by at
38
+ most one targeted follow-up cohort.
39
+ - The manager still owns integration, evidence acceptance, authoritative
40
+ validation, and review dispatch. No wave state, sidecar, admission profile,
41
+ telemetry, or concurrent feature lifecycle is added.
42
+ - This restores a capability; it does not claim a measured performance gain.
43
+ - Installation guidance now pins the exact `6.1.0` npm release.
44
+
9
45
  ## [6.0.0] - 2026-07-21
10
46
 
11
47
  Simplicity-first lifecycle lore turns Flow back into a small, durable serial
package/README.md CHANGED
@@ -1,46 +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 is
5
- serial by design:
4
+ that benefits from an approved plan and an independent review:
6
5
 
7
6
  ```text
8
- plan → approve → run one feature → validate → one independent review → close
7
+ plan → approve → run one feature → validate → review → repeat or close
9
8
  ```
10
9
 
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.
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.
15
13
 
16
14
  ## Install
17
15
 
18
16
  Install the exact npm release through OpenCode:
19
17
 
20
18
  ```bash
21
- opencode plugin opencode-plugin-flow@6.0.0 --global --force
19
+ opencode plugin opencode-plugin-flow@6.2.0 --global --force
22
20
  ```
23
21
 
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.
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.
28
29
 
29
30
  The equivalent manual project configuration is:
30
31
 
31
32
  ```json
32
33
  {
33
34
  "$schema": "https://opencode.ai/config.json",
34
- "plugin": ["opencode-plugin-flow@6.0.0"]
35
+ "plugin": ["opencode-plugin-flow@6.2.0"]
35
36
  }
36
37
  ```
37
38
 
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.
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.
44
44
 
45
45
  ## Quick start
46
46
 
@@ -50,118 +50,69 @@ Start a complete workflow:
50
50
  /flow-auto add rate limiting to the public API
51
51
  ```
52
52
 
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.
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.
58
57
 
59
- Use a narrower command when you want to control the phase:
58
+ For more control, plan first:
60
59
 
61
60
  ```text
62
61
  /flow-plan add rate limiting to the public API
63
- /flow-run
64
- /flow-status
65
62
  ```
66
63
 
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.
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
69
 
70
- ## Lifecycle
70
+ ## How Flow works
71
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.
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.
75
80
 
76
- For each run:
81
+ State lives in `.flow/session.json`, so `/flow-status` can recover the next
82
+ action after a restart or context change.
77
83
 
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.
84
+ ## Bounded parallelism
88
85
 
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.
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.
94
90
 
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.
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.
98
95
 
99
96
  ## Commands
100
97
 
101
98
  | Command | Purpose |
102
99
  | --- | --- |
103
- | `/flow-auto <goal>` | Drive the authorized lifecycle, stopping after planning when requested. |
104
- | `/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. |
105
102
  | `/flow-run` | Run or resume one approved feature. |
106
- | `/flow-review` | Dispatch the independent read-only reviewer. |
103
+ | `/flow-review` | Internal/recovery dispatch for a runtime-created reviewer assignment. |
107
104
  | `/flow-status` | Inspect the active session and next action. |
108
105
 
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.
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.
112
109
 
113
- ## Tools
110
+ ## Recovery
114
111
 
115
- The plugin exposes ten tools:
116
-
117
- | Tool | Purpose |
118
- | --- | --- |
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.
135
-
136
- ## What the runtime enforces
137
-
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.
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).
165
116
 
166
117
  ## Development
167
118
 
@@ -178,10 +129,11 @@ tests, and package smoke. Release CI also exercises the packed plugin in a real
178
129
  OpenCode host.
179
130
 
180
131
  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.
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.
185
137
 
186
138
  ## License
187
139