opencode-plugin-flow 6.8.0 → 7.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 (5) hide show
  1. package/CHANGELOG.md +134 -0
  2. package/README.md +92 -201
  3. package/dist/index.js +388 -278
  4. package/dist/index.js.map +24 -21
  5. package/package.json +3 -2
package/CHANGELOG.md CHANGED
@@ -6,6 +6,140 @@ One short entry per release, written for users deciding whether to upgrade.
6
6
 
7
7
  No changes yet.
8
8
 
9
+ ## [7.0.0] - 2026-07-27
10
+
11
+ A `broad` validation claim now has to be one, and the two review-finding fields
12
+ 6.9.0 introduced are reachable for the first time:
13
+
14
+ - **Breaking.** A command recorded at `broad` scope is refused when it selects
15
+ which tests it runs, either by naming a test file or by filtering with `-t`,
16
+ `--test-name-pattern`, `--testNamePattern`, `-k`, `-run`, `--grep` or
17
+ `--filter`. 6.9.0 accepted all of these. A repository whose canonical gate is a
18
+ filtered command must record that command as `focused` and arm the whole suite
19
+ for the broad observation a final review requires.
20
+ - **Breaking.** A failing broad observation now blocks its own feature's review
21
+ until that exact command passes again for the current workspace content.
22
+ Previously a red repository gate was discharged by arming something smaller
23
+ under the same label: every field of the resulting record true, and the gate
24
+ itself never passing.
25
+ - `reviewFinding` in the host tool schema was `.strict()` without `scopeBlocker`
26
+ or `findingId`, so every submission the review skill instructs was rejected at
27
+ the boundary even though the durable schema accepts both and `nextAction`
28
+ already reads `scopeBlocker`. Both fields now pass, with a parity test holding
29
+ the host schema to the durable one.
30
+ - An explicit grant of authority over already-planned work reads as continuation
31
+ rather than a goal change. A session planned with "do not implement anything
32
+ yet" and then told "you have my approval to implement it end to end" no longer
33
+ refuses the authorization it was just given. New or different outcomes are
34
+ still refused.
35
+ - Three architecture gates make the layering enforceable rather than described:
36
+ every `src` export must be imported outside its declaring file, every
37
+ `@opencode-ai/*` import must route through `src/platform/opencode/sdk.ts`, and
38
+ the source and documentation budgets report their remaining headroom instead of
39
+ speaking up only once they are exceeded.
40
+
41
+ The durable-invariant checker moved out of `transitions.ts` into
42
+ `src/domain/session-invariants.ts`, with its rule families explained and eleven
43
+ tests covering them; it previously had no direct coverage at all. The README is
44
+ half its former size. ADR 0009 now records what the model-driven harness measured
45
+ rather than what its guards were expected to do, including one escape left
46
+ deliberately open: a `broad` command that cannot fail, such as `git diff --check`,
47
+ is still accepted, because refusing it means deciding which commands count as
48
+ tests.
49
+
50
+ The Session v5 schema is unchanged, and no durable document written by a 6.x
51
+ build is rejected on load. Both refusals above apply when new evidence is
52
+ recorded, so a session carrying a filtered broad observation from 6.9.0 keeps it
53
+ and needs a whole-suite pass before its final review.
54
+
55
+ Install or update:
56
+
57
+ ```bash
58
+ opencode plugin opencode-plugin-flow@7.0.0 --global --force
59
+ ```
60
+
61
+ ## [6.9.0] - 2026-07-26
62
+
63
+ Rules the prompts used to restate are now enforced by the runtime, and Flow no
64
+ longer assumes an OpenCode-shaped host:
65
+
66
+ - Review findings carry two typed fields instead of prose conventions. An
67
+ optional `scopeBlocker` boolean surfaces as `blockedFeature.scopeBlocker` and
68
+ is accounted for by `nextAction`, so a scope blocker checkpoints for user
69
+ direction at the first failed review rather than depending on the manager
70
+ noticing a `[scope-blocker]` marker; the marker is gone everywhere. A
71
+ `findingId` is set to a prior id for a recurrence and omitted for a new issue,
72
+ which the runtime numbers as `<feature-id>.R<revision>-<NN>` and supplies back
73
+ as `priorFindings` with `nextFindingIdPrefix`. A failed result that drops a
74
+ live prior id is rejected instead of silently losing that history.
75
+ - The reviewer is asked to report every problem it finds and to use severity
76
+ purely for routing, replacing guidance that reserved `blocking` for issues
77
+ invalidating the outcome. Published guidance for current models indicates that
78
+ conservative review instructions suppress findings.
79
+ - The delivery projection carries a runtime-rendered `report`, so every surface
80
+ relays one formatted handoff verbatim instead of restating the same field list
81
+ four times.
82
+ - Validation on a host that reports no structured Bash exit code, or no
83
+ output-truncation flag, records a durable observation marked
84
+ `exit-code-unavailable` or `output-completeness-unknown` rather than failing the
85
+ capture. Such an observation never satisfies a gate, so the limitation is
86
+ visible instead of blocking. Worker-wave dispatch no longer instructs a single
87
+ assistant tool-use turn; a host that runs tasks serially is expected and
88
+ reported as serial.
89
+ - A tool call rejected by the runtime guard returns the same
90
+ `workflowData.failure.recovery` envelope every other Flow failure uses, which is
91
+ what the prompts already told the model to read. `flow_guidance` answers in
92
+ markdown, so its rejection is markdown rather than a JSON blob.
93
+ - `/flow-auto` on a host that reports no assistant message parentage now says so.
94
+ Continuation anchors on the assistant message owning the lease, so such a host
95
+ can never continue and correctly stops after each feature; previously that was
96
+ indistinguishable from a Flow defect. The warning now names the host limitation
97
+ and points at `/flow-run`.
98
+
99
+ Prompt text is now measured rather than argued about. Total shipped prompt bytes
100
+ drop from 42,466 to 38,495 and cross-surface near-duplicate rule statements from
101
+ 18 pairs to 12, with every removed instruction either replaced by an enforced
102
+ guard or a runtime-rendered value, or verified against the model. `flow-run`, the
103
+ dominant surface, loses 2,422 bytes: the elaborate revision-token protocol
104
+ collapses to the one rule that routes (`passed: false` never arms review), the
105
+ manager no longer reconstructs which prior findings are still live or tracks
106
+ their disposition in prose now that the runtime supplies `priorFindings` with
107
+ each finding's current severity and wording, and the prose describing internals
108
+ Flow already enforces — the strict review-start schema, the derived review kind,
109
+ the auto-continuation gate, and several statements that Flow persists no ledger —
110
+ is gone. Absolute-rule markers in `flow-run` fall from 62 to 51, which both
111
+ vendors' guidance treats as a compliance gain rather than a loss. `tests/prompt-quality.test.ts` and
112
+ `tests/documentation-contract.test.ts` no longer pin ordered prose phrases; they
113
+ assert structure, source-derived inventories, and budgets that ratchet down, so
114
+ tightening prompts is cheap and growth is what fails. Model behaviour is measured
115
+ by the new opt-in `evals/` harness, which drives the real slash commands against
116
+ a real model in a throwaway OpenCode host and asserts durable session state.
117
+
118
+ The harness arrived part-way through this release, so the cuts are not all
119
+ evidenced equally. The last one — the manager-side prior-finding reconstruction,
120
+ replaced by runtime `priorFindings` — was validated directly: `happy-path`,
121
+ `plan-only-stops` and `goal-change-refused` each passed three of three attempts
122
+ at the reduced footprint. Earlier cuts predate the harness and rest on the guards
123
+ and rendered values that replaced them, checked against a repeat-3 baseline
124
+ recorded once the harness existed. A fourth scenario, `failing-gate-blocks`,
125
+ passes at roughly even odds; it was measured to be equally unreliable at 6.8.0,
126
+ so it is reported but carries no signal about these prompts either way. Its cause
127
+ is a pre-existing gap rather than a prompt defect: `exitCode` and `scope` on a
128
+ validation observation are supplied by the model and never executed by Flow, so a
129
+ model that misreports a red gate as green is accepted by every predicate. Treat a
130
+ passing gate as a claim the model made, not one Flow verified.
131
+
132
+ The Session v5 schema adds two optional finding fields and widens `exitCode` to
133
+ allow `null`. Earlier v6 builds read the added fields as absent, but reject a
134
+ document containing a `null` exit code, so finish or close active work before
135
+ downgrading.
136
+
137
+ Install or update:
138
+
139
+ ```bash
140
+ opencode plugin opencode-plugin-flow@6.9.0 --global --force
141
+ ```
142
+
9
143
  ## [6.8.0] - 2026-07-24
10
144
 
11
145
  Checkpoint-safe continuation and leaner review convergence:
package/README.md CHANGED
@@ -1,262 +1,154 @@
1
1
  # Flow Plugin for OpenCode
2
2
 
3
- `opencode-plugin-flow` gives OpenCode a small, durable workflow for coding work
4
- that benefits from an approved plan and an independent review:
3
+ `opencode-plugin-flow` gives OpenCode a durable workflow for coding work that
4
+ benefits from an approved plan and an independent review:
5
5
 
6
6
  ```text
7
7
  plan → approve → run one feature → validate → review → repeat or close
8
8
  ```
9
9
 
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.
10
+ Flow keeps one durable active feature run at a time. Once a session starts it
11
+ stays the workflow for that goal until Flow records completed, deferred, or
12
+ abandoned closure. It never silently falls back to ordinary coding, and it does
13
+ not fold a materially different request into the active goal.
13
14
 
14
- Once a Flow session starts, it remains the workflow for that goal until Flow
15
- records completed, deferred, or abandoned closure. It never silently falls back
16
- to ordinary non-Flow coding, and it does not fold a materially different request
17
- into the active goal.
15
+ State lives in `.flow/session.json`, so the workflow survives a restart, a
16
+ context change, or a lost transcript.
18
17
 
19
18
  ## Install
20
19
 
21
20
  Install the exact npm release through OpenCode:
22
21
 
23
22
  ```bash
24
- opencode plugin opencode-plugin-flow@6.8.0 --global --force
23
+ opencode plugin opencode-plugin-flow@7.0.0 --global --force
25
24
  ```
26
25
 
27
- Omit `--global` for project scope. Exact version pins do not update
28
- automatically. To update, replace `6.8.0` with the new release and rerun the
29
- command.
30
-
31
- Before upgrading from Flow v5 or earlier, finish or explicitly close any active
32
- session with its original Flow version. Flow v6 opens only Session v5 active
33
- state; older archives remain inert history.
34
-
35
- Do not roll an active session back to an older Flow build after a newer build
36
- has written it. Newer v6 builds read earlier Session v5 state, but Session v5 is
37
- not a promise that older readers understand later widened safety bounds. Finish
38
- or close the active session before downgrading; Flow adds no capability or
39
- migration layer for rollback.
26
+ Omit `--global` for project scope. Version pins are exact and never update on
27
+ their own; to update, rerun the command with the new version.
40
28
 
41
29
  The equivalent manual project configuration is:
42
30
 
43
31
  ```json
44
32
  {
45
33
  "$schema": "https://opencode.ai/config.json",
46
- "plugin": ["opencode-plugin-flow@6.8.0"]
34
+ "plugin": ["opencode-plugin-flow@7.0.0"]
47
35
  }
48
36
  ```
49
37
 
50
- Restart OpenCode after changing configuration. OpenCode owns package
51
- installation and configuration; see its
38
+ Restart OpenCode after changing configuration. OpenCode owns installation and
39
+ configuration; see its
52
40
  [plugin documentation](https://opencode.ai/docs/plugins/). Flow has no installer
53
- or activation CLI. Removing the plugin entry disables it. If two Flow copies
41
+ or activation CLI, and removing the plugin entry disables it. If two Flow copies
54
42
  load for one project, both fail closed until the duplicate is removed.
55
43
 
56
- ## Quick start
44
+ **Changing versions.** Finish or explicitly close any active session first, in
45
+ either direction. Flow v6 opens only Session v5 active state, and an older build
46
+ cannot be trusted to read state a newer one has already written. Older archives
47
+ remain inert history, and there is no migration or rollback layer.
57
48
 
58
- Start a complete workflow:
49
+ ## Quick start
59
50
 
60
51
  ```text
61
52
  /flow-auto add rate limiting to the public API
62
53
  ```
63
54
 
64
- Flow inspects the worktree, proposes a feature plan, and asks for approval
65
- unless your request already authorized implementation. It then runs one
66
- runnable feature at a time, validates the actual workspace, obtains an
67
- independent review, and repeats until it can close the session. While
68
- implementation remains authorized, `ready` and `completed` are internal loop
69
- states: `/flow-auto` does not hand back “ready for the next feature” or wait for
70
- another command between passing features. From idle, auto-routing first requires
71
- a same-host accepted non-replayed `flow_plan_save` for the created Flow session;
72
- an active baseline that already has a pending reviewer retains a narrow temporal
73
- exception for that completion.
55
+ `/flow-auto` is the ordinary end-to-end driver. It inspects the worktree,
56
+ proposes a feature plan, and asks for approval unless your request already
57
+ authorized implementation. It then runs one feature at a time — implement,
58
+ validate against the real workspace, obtain an independent review — and keeps
59
+ going through every runnable feature without handing back between them, until it
60
+ can close the session.
74
61
 
75
62
  Send `/flow-auto stop` or `/flow-auto cancel` in the same OpenCode session to
76
- revoke only the process-local continuation lease. This does not close, defer,
77
- abandon, or otherwise mutate the durable Flow session.
78
-
79
- Before every manager-owned Flow mutation, including direct `/flow-plan` and
80
- `/flow-run` use, the manager compares the current request with the active goal.
81
- A projected `archiveRetry` is the one exception: it finishes an already-accepted
82
- close before that comparison and grants no authority for new work.
83
- A continuation or compatible narrowing may proceed. A materially new or
84
- expanded request does not start or mutate the active session; Flow offers to
85
- continue, defer, or abandon the active work. If that work is completed but not
86
- closed, Flow closes it as completed before starting the new request.
87
-
88
- Existing implementation authority carries across approval and feature outcomes.
89
- Only when `failedReviewCount === 1` and no `[scope-blocker]` is present may Flow
90
- automatically reset and atomically start one fresh full retry. A
91
- feature whose latest relevant reviewed outcome remains failed is never selected
92
- implicitly. `/flow-auto` may continue untouched, dependency-independent
93
- features, but when only retry-required candidates remain it projects
94
- `await-user-direction`. Flow then reports the blocker and waits for an explicit
95
- retry or independent-feature choice. While the failed run is still blocked, the
96
- chosen feature is attached to `flow_feature_reset` as `nextFeatureId`, so reset
97
- and the next run are one operation. If independent work later finishes and only
98
- the superseded failed feature remains, status is ready with
99
- `await-user-direction`; explicit retry then uses `flow_run_start` with that
100
- feature's exact `featureId`, because there is no blocked run left to reset. The
101
- active session remains authoritative while it waits. Ordinary blocking findings
102
- are in-scope by default; a reviewer uses `[scope-blocker]` only when the required
103
- repair would materially exceed the approved plan. After a user checkpoint, the
104
- process-local continuation resumes only after that same OpenCode session observes
105
- an accepted non-replayed Flow mutation whose tool assistant ID resolves, through
106
- the cached `message.updated` `parentID`, to the authoritative user reply. A
107
- missing or mismatched origin fails closed. Another host cannot establish that
108
- authority. The mechanical projection must match the credited revision exactly;
109
- the sole successor allowance is one revision after an authenticated
110
- `flow_review_start`, where the state machine admits the reserved reviewer result.
111
- Compaction transfers the reply authority only across an authenticated trigger
112
- assistant, automatic compaction marker, summary assistant, and successor user
113
- lineage while the authority is unchanged; an incomplete or unrelated lineage
114
- fails closed.
115
-
116
- Before coding each feature, Flow inventories required evidence and its
117
- environment, then applies an adversarial risk checklist covering failure
118
- ordering, repeated and interrupted operations, adjacent state transitions,
119
- overlapping invariants, and relevant file-mode or platform risks. While required
120
- behavior or environment evidence is knowingly skipped, manager policy forbids
121
- requesting review; the reviewer treats proof required to approve the outcome as
122
- blocking if it is missing from the packet. Flow persists no skipped-evidence
123
- ledger. Asking the user remains the default when external evidence or authority
124
- is missing. At a blocked checkpoint, atomic reset-and-start can discard that
125
- attempt and continue the
126
- exact authorized retry or dependency-independent feature. At a ready retry
127
- checkpoint, explicit feature start resumes the already superseded failure.
128
- Neither route adds a hold or second blocker ledger.
129
-
130
- Flow guidance represents the checklist for concurrency and state-machine work
131
- as one compact transition matrix shared by workers and the reviewer. Review
132
- packets reuse a refreshed run baseline, carry only feature-relevant file facts
133
- until final review, and preserve source IDs, current-source evidence, risk
134
- coverage, and prior finding dispositions in existing text fields—no new audit
135
- schema.
136
-
137
- For plan-only or advanced use, plan first:
63
+ revoke only the in-process continuation. That does not close, defer, abandon, or
64
+ otherwise change the durable Flow session.
65
+
66
+ Before any Flow mutation, Flow compares your request against the active goal. A
67
+ continuation or a compatible narrowing proceeds. A materially new or expanded
68
+ request does not start or mutate the active session: Flow offers to continue,
69
+ defer, or abandon the active work first, and closes work that is already
70
+ complete before starting something new.
71
+
72
+ To plan without implementing:
138
73
 
139
74
  ```text
140
75
  /flow-plan add rate limiting to the public API
141
76
  ```
142
77
 
143
- Review the proposed plan and approve it conversationally. `/flow-plan` does not
144
- silently grant permission to implement, commit, push, or publish. After
145
- approval of a plan-only request, `/flow-run` can run or recover one feature.
146
- Repeating a same-goal plan-only request after approval reports the immutable plan
147
- and current progress, then stops without rewriting the plan or starting work.
148
-
149
- `/flow-run` and `/flow-status` are advanced/recovery controls. At any point,
150
- `/flow-status` reports the durable state and next action. After `/flow-auto` has
151
- run in the current plugin process, status also reports a non-authoritative timer
152
- for the latest invocation. `activeMs` is process-local wall time classified as
153
- active by the coordinator, not CPU time or pure coding time.
154
- `waitingForUserMs` counts only projected `flow_plan_approve` and
155
- `await-user-direction` checkpoints. Plugin restart resets the timer; paused,
156
- inactive, errored, and unprojected waits are excluded.
78
+ Review the plan and approve it conversationally. `/flow-plan` never grants
79
+ permission to implement, commit, push, or publish. After approval, `/flow-run`
80
+ executes or recovers one approved feature. Repeating the same plan-only request
81
+ reports the immutable plan and current progress instead of rewriting it.
82
+
83
+ `/flow-status` reports durable state and the next action at any point. That next
84
+ action is the default workflow direction, not permission to exceed the authority
85
+ you granted.
157
86
 
158
87
  ## How Flow works
159
88
 
160
89
  1. Planning saves a small feature DAG. Approval locks it.
161
- 2. `/flow-run` starts one feature whose dependencies are complete.
162
- 3. Before editing, the manager preflights required evidence and gives any
163
- bounded workers an explicit adversarial acceptance and risk checklist.
164
- 4. The manager implements it serially or integrates an optional bounded worker
165
- wave.
90
+ 2. One feature starts, chosen only from those whose dependencies are complete.
91
+ 3. Before editing, the manager gathers the evidence the feature needs and works
92
+ through an adversarial risk checklist: failure ordering, repeated and
93
+ interrupted operations, adjacent state transitions, overlapping invariants,
94
+ and file-mode or platform risk.
95
+ 4. The manager implements the feature, serially or by integrating a bounded
96
+ worker wave.
166
97
  5. Flow observes the exact armed validation command against the current
167
- workspace, then creates one independent review assignment. At new review
168
- admission, a relevant failure or source-drift observation invalidates older
169
- passes; the qualifying pass must be newer and match current source. Separately,
170
- the manager must not call `flow_review_start` while known required behavior or
171
- environment evidence is skipped; this is workflow policy, not persisted
172
- admission state. Already accepted Session v5 pending or completed reviews are
173
- not reopened or vetoed later at close.
174
- 6. The reviewer inspects adjacent and repeated state transitions, overlapping
175
- feature invariants, the changed artifacts, and the packet's base-diff and
176
- file-mode inventory. Stable finding IDs survive retries; reviewer guidance
177
- requires checking prior dispositions and completing the supplied risk
178
- checklist, represented as a bounded matrix when applicable. Missing proof is
179
- a precise blocker only when it is required to approve the outcome.
180
- 7. A passing feature advances the plan. A failed feature is not selected again
181
- by default. From blocked status, reset atomically starts the exact authorized
182
- retry or independent feature through optional `nextFeatureId`. From ready
183
- `await-user-direction`, the failed run is already superseded and explicit
184
- `flow_run_start(featureId)` begins its retry. The final passing feature allows
185
- explicit closure. Every accepted close returns a concise delivery summary
186
- with each feature's attempt count, latest outcome, and terminal findings,
187
- derived from Flow's recorded state. Ordinary reviewer summaries carry IDs
188
- mapped to the active feature or explicitly supplied in its packet; final
189
- review carries every approved requirement or feature ID. Both carry each
190
- still-live prior finding with its severity and disposition into the latest
191
- `outcomeSummary`. Terminal
192
- `fixed` requires a later passing review and current evidence. If a failed
193
- retry proves one repair but finds another blocker, it carries that ID and a
194
- concise evidence reference forward as terminal fixed pending pass; it cannot
195
- drop the ID or call it fixed. Unproven fixes stay unverified, `recurring`
196
- confirms recurrence, and `residual` requires a confirmed nonblocker. Only a
197
- passing review may remove fixed history from the live carry-forward set.
198
- Terminal findings retain unresolved blockers and the handoff stays bounded.
199
-
200
- State lives in `.flow/session.json`, so `/flow-status` can recover the next
201
- action after a restart or context change.
98
+ workspace, then opens one independent review assignment. A newer relevant
99
+ failure or a source change invalidates an older pass, and review cannot be
100
+ requested while evidence the outcome depends on is knowingly missing.
101
+ 6. A passing review advances the plan. A failed feature is never picked up again
102
+ implicitly — Flow reports the blocker and waits for an explicit retry or an
103
+ independent-feature choice. The last passing feature allows closure, and every
104
+ accepted close returns a delivery summary derived from recorded state: each
105
+ feature's attempts, latest outcome, and terminal findings.
106
+
107
+ Findings keep stable ids across retries, and a failed review must carry every
108
+ still-live finding forward — the runtime rejects a submission that drops one. A
109
+ reviewer marks a finding as out of scope only when the repair would materially
110
+ exceed the approved plan.
202
111
 
203
112
  ## Bounded parallelism
204
113
 
205
- Parallel contribution is optional and local to one active feature. The manager
206
- may launch two or three `flow-worker` instances only for exact,
207
- non-overlapping slices, then inspect and integrate their work. At most one
208
- targeted follow-up wave may address a concrete gap. Once implementation is
209
- authorized, a qualifying wave needs no separate approval.
114
+ Parallel work is optional and confined to one active feature. The manager may
115
+ launch two or three `flow-worker` instances for exact, non-overlapping slices,
116
+ then inspect and integrate the result, with at most one follow-up wave for a
117
+ concrete gap. Once implementation is authorized, a qualifying wave needs no
118
+ separate approval.
210
119
 
211
- Workers cannot delegate, call Flow lifecycle tools, or approve their own work.
212
- Generic or general-purpose agents are not used for active Flow work: bounded
213
- implementation uses `flow-worker`, and independent review uses
214
- `flow-reviewer`.
215
- Flow persists no wave state: the manager remains responsible for the combined
216
- diff, authoritative validation, and the one independent review. Small or
217
- integration-heavy tasks stay serial.
120
+ Workers cannot delegate, call Flow lifecycle tools, or approve their own work,
121
+ and general-purpose agents are never used for active Flow work: implementation
122
+ uses `flow-worker`, independent review uses `flow-reviewer`. Flow persists no
123
+ wave state, so the manager stays responsible for the combined diff, the
124
+ authoritative validation, and the one independent review. Small or
125
+ integration-heavy features stay serial.
218
126
 
219
127
  ## Commands
220
128
 
221
129
  | Command | Purpose |
222
130
  | --- | --- |
223
- | `/flow-auto <goal>` | Normal end-to-end driver; it stops after planning without implementation authority, otherwise loops through every runnable feature and closure without an intermediate handoff. |
224
- | `/flow-plan <goal>` | Plan-only/advanced creation, revision, and approval. |
131
+ | `/flow-auto <goal>` | Normal end-to-end driver. Stops after planning without implementation authority; otherwise loops through every runnable feature and closure. |
132
+ | `/flow-plan <goal>` | Plan-only creation, revision, and approval. |
225
133
  | `/flow-run` | Advanced/recovery execution of one approved feature. |
226
134
  | `/flow-review` | Internal/recovery dispatch for a runtime-created reviewer assignment. |
227
135
  | `/flow-status` | Advanced/recovery inspection of the active session and next action. |
228
136
 
229
- Use `/flow-auto` for the ordinary end-to-end workflow. The other commands expose
230
- plan-only, advanced, internal, or recovery controls.
137
+ Use `/flow-auto` for ordinary work. The rest expose plan-only, advanced,
138
+ internal, or recovery controls.
231
139
 
232
140
  ## Recovery
233
141
 
234
- Start with `/flow-status`; its next action is durable default workflow
235
- direction, not permission to exceed the user's authority. For a first failed
236
- review, read detail once before reset because scope-blocker findings refine the
237
- compact default. Pass the exact retry or dependency-independent choice as
238
- `nextFeatureId` so reset and run start are atomic; do not reset and then rely on
239
- default selection. If status is ready with `await-user-direction`, read detail
240
- once and pass the explicitly authorized retry's exact `featureId` to
241
- `flow_run_start`; reset is invalid because the failed run was already
242
- superseded. Environment-sensitive transition guards remain authoritative when a
243
- mutation is attempted. Do not hand-edit
244
- `.flow/session.json` to bypass a gate. If validation, review, locking,
245
- fingerprinting, or archive publication fails, follow the focused steps in
246
- [troubleshooting](docs/troubleshooting.md).
247
-
248
- For an interrupted accepted close, compact `/flow-status` supplies
249
- `archiveRetry.request`. Replay that request exactly once before any additional
250
- or detail recovery read. Flow confirms the existing bytes without rewriting
251
- Session v5, re-confirms archive cleanup, and returns the existing concise
252
- `workflowData.delivery`. Reconstruct only the plan-bounded, terminal disposition
253
- map from its latest `outcomeSummary` and terminal findings. If delivery is absent,
254
- report the exact recovery and claim no map. On a close revision conflict,
255
- refresh compact status and retry only after confirming the same session and goal
256
- and that status still permits the selected
257
- closure kind; never close a replacement. A real archive collision removes the
258
- automatic retry instruction and requires manual inspection; preserve both
259
- documents and do not overwrite, delete, or loop the request.
142
+ Start with `/flow-status`. After a failed review, read detail once to see the
143
+ findings a retry must fix, then pass the exact retry or independent-feature
144
+ choice so that reset and the next run are one operation rather than relying on
145
+ default selection.
146
+
147
+ If an accepted close was interrupted, compact status supplies
148
+ `archiveRetry.request`; replay it exactly once, before any other recovery read.
149
+ Never close a replacement session, and never hand-edit `.flow/session.json` to
150
+ get past a gate. For a validation, review, locking, fingerprinting, or archive
151
+ failure, follow [troubleshooting](docs/troubleshooting.md).
260
152
 
261
153
  ## Development
262
154
 
@@ -268,11 +160,10 @@ bun install --frozen-lockfile
268
160
  bun run check
269
161
  ```
270
162
 
271
- The normal check runs typechecking, formatting/lint checks, build verification,
272
- tests, and package smoke. Release CI also exercises the packed plugin in a real
273
- OpenCode host.
163
+ `bun run check` runs typechecking, lint, build verification, tests, and package
164
+ smoke. Release CI also exercises the packed plugin in a real OpenCode host.
274
165
 
275
- Maintained documentation starts at [docs/index.md](docs/index.md). See
166
+ Maintained documentation starts at [docs/index.md](docs/index.md):
276
167
  [development](docs/development.md) for repository structure,
277
168
  [troubleshooting](docs/troubleshooting.md) for recovery,
278
169
  [the maintainer contract](docs/maintainer-contract.md) for tools and runtime