opencode-plugin-flow 4.1.3 → 4.1.4

package/CHANGELOG.md

@@ -3,6 +3,10 @@
 One short line per release. For the full rationale behind each entry, see the
 commit history and review evidence.
 
+## [4.1.4] - 2026-06-16
+
+Make Flow skill loading restart-aware across every command, add manual sync repair, and treat missing optional helpers as explicit coverage gaps.
+
 ## [4.1.3] - 2026-06-16
 
 Sharpen Flow's skill/runtime contract with aligned final-review language, broader gate coverage, CLI smoke tests, and skill-aware preflight routing.

package/README.md

@@ -20,7 +20,7 @@ Add Flow to your OpenCode config:
 
 ```json
 {
-  "plugin": ["opencode-plugin-flow@4.1.3"]
+  "plugin": ["opencode-plugin-flow@4.1.4"]
 }
 ```
 
@@ -50,9 +50,23 @@ disk while still being unavailable to that process. Flow reports this through
 To inspect the installed skill set:
 
 ```bash
-npx -y opencode-plugin-flow@4.1.3 doctor
+npx -y opencode-plugin-flow@4.1.4 doctor
 ```
 
+If a command reports `Skill "flow-review" not found. Available skills...` or a
+similar Flow skill-loading error, run `/flow-status` or the doctor command above
+first. Missing, incomplete, or outdated managed skills can be repaired with:
+
+```bash
+npx -y opencode-plugin-flow@4.1.4 sync
+```
+
+Then restart OpenCode so the refreshed registry is loaded. `sync` manages all
+bundled Flow skills: `flow`, `flow-plan`, `flow-run`, `flow-review`,
+`flow-deslop`, and `flow-ui-quality`. If doctor reports a foreign or edited
+managed skill folder, Flow leaves it in place and asks for a user decision
+instead of overwriting local work.
+
 ## Commands
 
 Commands are thin pointers into skills:

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import{createHash as xe}from"node:crypto";import{mkdir as xa,readdir as K,readFile as _e,rm as Re,writeFile as _a}from"node:fs/promises";import{createRequire as Ie}from"node:module";import{dirname as Fa,join as l,normalize as Fe,sep as Ce}from"node:path";var F=`# Flow worker handoff contract
+import{createHash as Fe}from"node:crypto";import{mkdir as Ce,readdir as ee,readFile as Ue,rm as qe,writeFile as y}from"node:fs/promises";import{createRequire as Ae}from"node:module";import{dirname as Te,join as l,normalize as Pe,sep as De}from"node:path";var j=`# Flow worker handoff contract
 
 Flow managers merge only the worker's final response. Treat that response as the
 worker report of record: it must include the assigned scope, what was actually
@@ -118,7 +118,7 @@ live-verified | test-verified | type-check-only | not-verified
 
 The manager must inspect and validate any candidate patch before recording Flow
 completion.
-`;var C=`# Parallel orchestration
+`;var W=`# Parallel orchestration
 
 Use fan-out when Flow work is broad enough that independent workers can gather
 evidence faster than one linear pass. The manager still owns the Flow session:
@@ -247,7 +247,7 @@ Start a follow-up wave when first-wave handoffs reveal:
 
 Do not recurse by default. If a worker says it needs another worker, the manager
 decides whether that is a second wave and writes the next bounded prompt.
-`;var U='# Recovery playbook\n\nUse this when a Flow tool returns `status: "error"`, a blocker, or a `nextAction` that conflicts with memory.\n\n## First response\n\n1. Re-anchor with `flow_status`.\n2. Read the returned `summary`, `recovery`, `lastError`, and active feature.\n3. Fix the cause, then retry the smallest valid Flow action.\n\n## Common cases\n\n- `missing_session`: start with `flow_plan_save` using the user\'s goal.\n- `missing_goal`: ask for a concrete goal before planning.\n- `Approved plans cannot be changed`: use `flow_feature_reset` when only affected features need another pass; otherwise close and start a new goal.\n- `No feature is currently running`: call `flow_run_start` before completing.\n- `already in progress`: finish, reset, or block the active feature before starting another.\n- `Completion requires recorded validation evidence`: run real validation and include at least one passing `validationRun`.\n- `Completion requires all recorded validation to pass`: fix failures and rerun. Do not relabel failed checks as passed.\n- `Non-final feature completion requires targeted validation`: use `validationScope: "targeted"` for ordinary features.\n- `Final feature completion requires broad validation`: run the project-level gate and use `validationScope: "broad"`.\n- `Completion requires a passing featureReview`: run or request a real review and include a passing `featureReview` only when there are no blocking findings.\n- `Final feature completion requires a finalReview`: perform final review and include `finalReview`.\n- `Final review depth must match the plan policy`: use `reviewDepth` equal to the approved plan\'s `finalReviewPolicy`; valid final-review values are `broad` and `detailed`.\n- `Cannot close ... unfinished features`: complete, reset, defer, or abandon honestly. Do not mark completed while work remains.\n\n## Reset guidance\n\nUse `flow_feature_reset` when the active or completed work was built on the wrong assumption, validation revealed a design issue, dependencies need to be rerun, or dependent features must be invalidated. Resetting a feature also resets its dependents.\n\n## Closure guidance\n\nUse `flow_session_close`:\n\n- `completed`: only after all planned features are complete.\n- `deferred`: the user intentionally postpones unfinished work.\n- `abandoned`: the session should be archived without claiming delivery.\n\nAfter closure, the active `.flow/session.json` is removed and the archived JSON is stored under `.flow/history/`.\n';var A=`# Verification gates
+`;var z='# Recovery playbook\n\nUse this when a Flow tool returns `status: "error"`, a blocker, or a `nextAction` that conflicts with memory.\n\n## First response\n\n1. Re-anchor with `flow_status`.\n2. Read the returned `summary`, `recovery`, `lastError`, and active feature.\n3. Fix the cause, then retry the smallest valid Flow action.\n\n## Common cases\n\n- `missing_session`: start with `flow_plan_save` using the user\'s goal.\n- `missing_goal`: ask for a concrete goal before planning.\n- `Approved plans cannot be changed`: use `flow_feature_reset` when only affected features need another pass; otherwise close and start a new goal.\n- `No feature is currently running`: call `flow_run_start` before completing.\n- `already in progress`: finish, reset, or block the active feature before starting another.\n- `Completion requires recorded validation evidence`: run real validation and include at least one passing `validationRun`.\n- `Completion requires all recorded validation to pass`: fix failures and rerun. Do not relabel failed checks as passed.\n- `Non-final feature completion requires targeted validation`: use `validationScope: "targeted"` for ordinary features.\n- `Final feature completion requires broad validation`: run the project-level gate and use `validationScope: "broad"`.\n- `Completion requires a passing featureReview`: run or request a real review and include a passing `featureReview` only when there are no blocking findings.\n- `Final feature completion requires a finalReview`: perform final review and include `finalReview`.\n- `Final review depth must match the plan policy`: use `reviewDepth` equal to the approved plan\'s `finalReviewPolicy`; valid final-review values are `broad` and `detailed`.\n- `Cannot close ... unfinished features`: complete, reset, defer, or abandon honestly. Do not mark completed while work remains.\n\n## Reset guidance\n\nUse `flow_feature_reset` when the active or completed work was built on the wrong assumption, validation revealed a design issue, dependencies need to be rerun, or dependent features must be invalidated. Resetting a feature also resets its dependents.\n\n## Closure guidance\n\nUse `flow_session_close`:\n\n- `completed`: only after all planned features are complete.\n- `deferred`: the user intentionally postpones unfinished work.\n- `abandoned`: the session should be archived without claiming delivery.\n\nAfter closure, the active `.flow/session.json` is removed and the archived JSON is stored under `.flow/history/`.\n';var O=`# Verification gates
 
 Verification is how Flow keeps parallel work from turning into parallel
 guesswork. Worker handoffs are candidate evidence; the manager decides what can
@@ -337,7 +337,74 @@ Before presenting or recording the result:
 
 \`Status: success\` only says the worker believes its slice is done. The manager
 still checks coverage and evidence before trusting the result.
-`;var q="---\nname: flow\ndescription: Main Flow loop for skills-first OpenCode work. Use when a user asks for Flow-guided planning, autonomous execution, resumable implementation, session status, or end-to-end delivery with validation and review gates.\n---\n\n# Flow\n\nUse Flow as a minimal state ledger, not as a framework. Skills provide judgment; the runtime only records the approved plan, active feature, validation evidence, review evidence, and closure.\n\n## Loop\n\n1. Call `flow_status` first. Trust its active session and next action over conversation memory.\n2. If there is no active session and the user gave a goal, load `flow-plan`, save a plan with `flow_plan_save`, then approve it with `flow_plan_approve` only after explicit user approval or prior authorization for autonomous implementation. If there is no goal, ask for one.\n3. Load `flow-run`, call `flow_run_start`, implement exactly one feature, validate it, and prepare a `flow_feature_complete` payload.\n4. Load `flow-review` for the required feature review. The reviewer reports a `featureReview` payload; the manager records it inside `flow_feature_complete`.\n5. On the final feature, run broad validation and include `finalReview` in the same `flow_feature_complete` call. Its `reviewDepth` must match the plan's `finalReviewPolicy`.\n6. After all features are complete, archive the session with `flow_session_close` using `kind: \"completed\"`.\n\nUse `references/parallel-orchestration.md` for broad read-only discovery, audit, validation, review, verification, or candidate implementation waves. Hidden Flow workers are injected by plugin config; invoke the named worker when it is available. Its `references/handoff-format.md` and `references/verification-gates.md` companions define the worker contracts. The manager owns every `flow_*` state change.\n\n## Runtime Surface\n\n- `flow_status`: read the active session.\n- `flow_plan_save`: create a session and/or save a draft plan.\n- `flow_plan_approve`: lock the draft plan.\n- `flow_run_start`: start one runnable feature.\n- `flow_feature_complete`: record completion or a real blocker with validation and review evidence.\n- `flow_feature_reset`: reset one feature and its dependents.\n- `flow_session_close`: archive the active session as `completed`, `deferred`, or `abandoned`.\n\nThere is no `flow_context`, no separate review-record tool, and no multi-session activation surface. The single active source of truth is `.flow/session.json`; closed sessions are archived under `.flow/history/`.\n\nPlanning and running require loaded Flow tools; do not simulate plan approval or feature completion when the runtime is unavailable. Review may still return advisory output when tools or skills are stale or unavailable, but the manager must not record it as Flow-gated evidence.\n\n## Hard Gates\n\n- Approved plans are immutable. To change direction, reset affected features or close the session and start a new goal.\n- Only one feature can be active at a time.\n- Completion requires at least one passing `validationRun` entry.\n- Non-final completion requires `validationScope: \"targeted\"`.\n- Final completion requires `validationScope: \"broad\"` and a passing `finalReview`.\n- Every completed feature requires a passing `featureReview` with no blocking findings.\n- `flow_session_close` accepts `kind: \"completed\"` only after an approved plan has passed final completion.\n\n## Recovery\n\n- Confused state: call `flow_status` and follow `nextAction`.\n- Wrong assumption or failed implementation path: use `flow_feature_reset` for the feature and dependents, then rerun from the corrected plan.\n- Missing validation or review evidence: gather real evidence, then call `flow_feature_complete`.\n- Approved plan is materially wrong: reset the affected features, save a revised plan if the session is back in planning; otherwise close and start a new goal.\n- Unknown runtime error: read `summary` and `recovery`; see `references/recovery-playbook.md` for common cases.\n\nNever fabricate validation output, backfill review approval you did not perform, or close as `deferred`/`abandoned` merely to avoid an unfinished-work blocker.\n";var T=`# Safe refactor workflow
+`;var B=`---
+name: flow
+description: Main Flow loop for skills-first OpenCode work. Use when a user asks for Flow-guided planning, autonomous execution, resumable implementation, session status, or end-to-end delivery with validation and review gates.
+---
+
+# Flow
+
+Use Flow as a minimal state ledger, not as a framework. Skills provide judgment; the runtime only records the approved plan, active feature, validation evidence, review evidence, and closure.
+
+## Loop
+
+1. Call \`flow_status\` first. Trust its active session and next action over conversation memory.
+   If the result includes \`setup.skills\`, report that setup status and do not
+   load Flow skills in this startup. A just-synced skill can be on disk while
+   unavailable to the running OpenCode process.
+2. If there is no active session and the user gave a goal, load \`flow-plan\`, save a plan with \`flow_plan_save\`, then approve it with \`flow_plan_approve\` only after explicit user approval or prior authorization for autonomous implementation. If there is no goal, ask for one.
+3. Load \`flow-run\`, call \`flow_run_start\`, implement exactly one feature, validate it, and prepare a \`flow_feature_complete\` payload.
+4. Load \`flow-review\` for the required feature review. The reviewer reports a \`featureReview\` payload; the manager records it inside \`flow_feature_complete\`.
+5. On the final feature, run broad validation and include \`finalReview\` in the same \`flow_feature_complete\` call. Its \`reviewDepth\` must match the plan's \`finalReviewPolicy\`.
+6. After all features are complete, archive the session with \`flow_session_close\` using \`kind: "completed"\`.
+
+Use \`references/parallel-orchestration.md\` for broad read-only discovery, audit, validation, review, verification, or candidate implementation waves. Hidden Flow workers are injected by plugin config; invoke the named worker when it is available. Its \`references/handoff-format.md\` and \`references/verification-gates.md\` companions define the worker contracts. The manager owns every \`flow_*\` state change.
+
+## Skill Availability
+
+If \`flow_status\` returns \`setup.skills\`, report that setup status and stop
+loading Flow skills in the current OpenCode startup. Missing, incomplete, or
+outdated managed skills require a sync/restart cycle before their instructions
+can be trusted by the running process.
+
+If optional helper skills such as \`flow-deslop\` or \`flow-ui-quality\` are
+unavailable, continue only with explicit coverage gaps. Do not copy their
+rubrics into another skill and do not claim their quality checks were completed.
+
+## Runtime Surface
+
+- \`flow_status\`: read the active session.
+- \`flow_plan_save\`: create a session and/or save a draft plan.
+- \`flow_plan_approve\`: lock the draft plan.
+- \`flow_run_start\`: start one runnable feature.
+- \`flow_feature_complete\`: record completion or a real blocker with validation and review evidence.
+- \`flow_feature_reset\`: reset one feature and its dependents.
+- \`flow_session_close\`: archive the active session as \`completed\`, \`deferred\`, or \`abandoned\`.
+
+There is no \`flow_context\`, no separate review-record tool, and no multi-session activation surface. The single active source of truth is \`.flow/session.json\`; closed sessions are archived under \`.flow/history/\`.
+
+Planning and running require loaded Flow tools; do not simulate plan approval or feature completion when the runtime is unavailable. Review may still return advisory output when tools, skills, or references are stale or unavailable, but the manager must not record it as Flow-gated evidence.
+
+## Hard Gates
+
+- Approved plans are immutable. To change direction, reset affected features or close the session and start a new goal.
+- Only one feature can be active at a time.
+- Completion requires at least one passing \`validationRun\` entry.
+- Non-final completion requires \`validationScope: "targeted"\`.
+- Final completion requires \`validationScope: "broad"\` and a passing \`finalReview\`.
+- Every completed feature requires a passing \`featureReview\` with no blocking findings.
+- \`flow_session_close\` accepts \`kind: "completed"\` only after an approved plan has passed final completion.
+
+## Recovery
+
+- Confused state: call \`flow_status\` and follow \`nextAction\`.
+- Wrong assumption or failed implementation path: use \`flow_feature_reset\` for the feature and dependents, then rerun from the corrected plan.
+- Missing validation or review evidence: gather real evidence, then call \`flow_feature_complete\`.
+- Approved plan is materially wrong: reset the affected features, save a revised plan if the session is back in planning; otherwise close and start a new goal.
+- Unknown runtime error: read \`summary\` and \`recovery\`; see \`references/recovery-playbook.md\` for common cases.
+
+Never fabricate validation output, backfill review approval you did not perform, or close as \`deferred\`/\`abandoned\` merely to avoid an unfinished-work blocker.
+`;var N=`# Safe refactor workflow
 
 Refactoring is a behavior-preserving sequence of small changes. This workflow keeps cleanup from becoming an unreviewable rewrite.
 
@@ -379,7 +446,7 @@ Weak evidence includes:
 - Public contracts and compatibility shims remain intact or were explicitly planned.
 - Deleted code is actually unreachable or obsolete.
 - Validation can catch a realistic mistake in the refactor.
-`;var P=`# Deslop smell rubric
+`;var V=`# Deslop smell rubric
 
 Use this rubric to turn vague cleanup instincts into reviewable findings.
 
@@ -413,7 +480,7 @@ class; severity; location; evidence read; refutation checked; why it matters; sa
 \`\`\`
 
 Rate as blocking only when the smell materially raises defect risk, blocks planned work, hides behavior, or makes the success claim unverifiable. Style-only cleanup is advisory.
-`;var D=`---
+`;var E=`---
 name: flow-deslop
 description: Flow guidance for evidence-backed code smell cleanup, AI-slop removal, overengineering reduction, maintainability refactors, and behavior-preserving cleanup. Use when planning, executing, or reviewing broad cleanup/refactor work, code smell findings, duplicated or bloated code, speculative abstractions, dead code, or agent-introduced mess.
 ---
@@ -455,7 +522,7 @@ For each claimed smell removal, verify:
 - **blast radius** — public contracts and downstream callers still work.
 
 Never approve cleanup because it "looks cleaner" without evidence. Tests passing is necessary but not sufficient when the refactor changes structure across files.
-`;var j=`# Parallel discovery
+`;var S=`# Parallel discovery
 
 Use this only after a serial orientation pass has identified the repo shape and the likely slices. Workers are read-only evidence gatherers; the planner owns the plan.
 
@@ -521,7 +588,7 @@ Convert only evidence-backed work into plan fields:
 - feature \`validation\`: checks expected to prove the feature.
 
 If workers disagree, inspect the source artifact yourself. If a candidate finding lacks a concrete citation or refutation pass, make it a review-first deliverable rather than a fix feature.
-`;var W=`# Planning examples
+`;var G=`# Planning examples
 
 ## Rate limiting feature set
 
@@ -606,7 +673,7 @@ Better plan:
 - Validation that only says "manual testing".
 - Targets that name the entire repo.
 - Features with hidden dependencies instead of \`dependsOn\`.
-`;var z=`---
+`;var M=`---
 name: flow-plan
 description: Plan Flow work for the v4 skills-first runtime: inspect the repo, decompose a user goal into right-sized features, save a draft with flow_plan_save, and approve it with flow_plan_approve.
 ---
@@ -621,8 +688,11 @@ If \`flow_plan_save\` or \`flow_plan_approve\` is unavailable, stop and tell the
 
 - Read the files, docs, tests, package scripts, and local conventions that determine the work.
 - For broad discovery, read \`references/parallel-discovery.md\` after a serial orientation pass. Use \`../flow/references/parallel-orchestration.md\` when discovery needs multiple workers, and apply its coverage gate before fan-out.
-- For cleanup/refactor goals, load \`flow-deslop\`.
-- For UI/frontend goals, load \`flow-ui-quality\`.
+- For cleanup/refactor goals, load \`flow-deslop\`. If it is unavailable, record
+  a planning gap and keep cleanup claims conservative.
+- For UI/frontend goals, load \`flow-ui-quality\`. If it is unavailable, record a
+  planning gap and require next-best UI evidence rather than claiming visual
+  quality was reviewed.
 - Do not invent findings. Broad "review and fix" goals start with a review-first feature whose deliverable is evidence-backed findings.
 
 ## Plan shape
@@ -667,7 +737,7 @@ Use only \`finalReviewPolicy: "broad"\` or \`"detailed"\`. These are the canonic
 After saving, summarize the plan to the user. Call \`flow_plan_approve\` only after explicit user approval, unless the user already authorized autonomous implementation. Approved plans are immutable; changing them later requires reset/closure rather than silent edits.
 
 See \`references/planning-examples.md\` for payload examples and decomposition anti-patterns.
-`;var B=`# Review rubric
+`;var L=`# Review rubric
 
 Use this to decide whether a \`featureReview\` or \`finalReview\` payload may pass.
 
@@ -755,7 +825,7 @@ When reviewing a findings report, verify findings adversarially:
 - Downgrade or reject findings that do not survive refutation.
 
 Approve only on evidence actually inspected. A review is a claim of coverage, not a courtesy stamp.
-`;var O=`---
+`;var $=`---
 name: flow-review
 description: Review Flow work in the v4 runtime: inspect feature or final-session changes, classify findings, and return featureReview or finalReview payloads for flow_feature_complete.
 ---
@@ -764,7 +834,9 @@ description: Review Flow work in the v4 runtime: inspect feature or final-sessio
 
 Use this skill for review. The reviewer is usually read-only and does not mutate Flow state. The manager records the returned review payload inside \`flow_feature_complete\`.
 
-If Flow tools or required Flow skills are unavailable or stale, perform an advisory review and say that no Flow-gated review payload was recorded.
+If Flow tools, required Flow skills, or required references are unavailable or
+stale, perform an advisory review and say that no Flow-gated review payload was
+recorded.
 
 ## Start
 
@@ -809,8 +881,8 @@ Use \`status: "failed"\` when any blocking finding remains. Advisory findings ma
 
 ## Special cases
 
-- Cleanup/refactor: load \`flow-deslop\`; verify the smell was real, refutation paths were checked, and behavior was preserved.
-- UI/frontend: load \`flow-ui-quality\`; verify state coverage and visual evidence when a local target was available.
+- Cleanup/refactor: load \`flow-deslop\`; verify the smell was real, refutation paths were checked, and behavior was preserved. If unavailable, record a coverage gap instead of approving cleanup claims.
+- UI/frontend: load \`flow-ui-quality\`; verify state coverage and visual evidence when a local target was available. If unavailable, record a coverage gap and do not claim visual polish was verified.
 - Audit reports: use \`flow-run/references/audit-rubric.md\`; findings must survive refutation before they can drive fix features.
 - Large reviews: use \`../flow/references/parallel-orchestration.md\` for
   read-only slices by changed-file group, risk lens, or validation surface.
@@ -820,7 +892,7 @@ Use \`status: "failed"\` when any blocking finding remains. Advisory findings ma
   \`finalReview\` payload.
 
 Never approve to unblock completion, fix findings in the review pass, or vouch for validation you did not inspect.
-`;var N=`# Audit findings rubric
+`;var K=`# Audit findings rubric
 
 What counts as a valid finding when the feature's deliverable is a findings report: a codebase audit, a review-first feature, or any report whose findings a later feature will fix. The commands you run are still governed by \`validation-rubric.md\`; this rubric governs the findings themselves.
 
@@ -873,7 +945,7 @@ follow-up order — correctness and persisted/user-input surfaces first
 \`\`\`
 
 Never: promote a hypothesis to blocking severity; cite a line you did not read in context; rate severity against a deployment model the product does not have; pad the report to look thorough — six verified findings outrank nine where three die on first contact.
-`;var V=`# Validation evidence rubric
+`;var X=`# Validation evidence rubric
 
 Use this before recording \`flow_feature_complete\`.
 
@@ -930,7 +1002,84 @@ Broad validation usually means the repo's full check command, full relevant test
 - If validation needs external access, missing credentials, or ambiguous user input, record \`status: "needs_input"\` with an honest \`outcome\`.
 
 Never trim failing output, relabel a failed command as passed, or use "not run" as completion evidence.
-`;var E="---\nname: flow-run\ndescription: Execute one approved Flow feature in the v4 runtime: start a feature with flow_run_start, make scoped changes, gather real validation evidence, obtain review payloads, and complete with flow_feature_complete.\n---\n\n# Flow Run\n\nUse this skill for implementation after a Flow plan is approved. Work one feature at a time.\n\nIf `flow_run_start` is unavailable, stop and tell the user to check that `opencode-plugin-flow` is loaded in OpenCode.\n\n## Start\n\n- Call `flow_status`.\n- Call `flow_run_start` with no `featureId` unless the user or plan requires a specific runnable feature.\n- Treat the returned feature as the sole scope until it is completed, blocked, or reset.\n- Load `flow-deslop` for cleanup/refactor features.\n- Load `flow-ui-quality` for frontend, UX, responsive, accessibility, or visual work.\n\n## Implement\n\n- Read the feature `targets`, `summary`, `validation`, dependencies, and plan `requirements`/`decisions`.\n- Keep edits scoped to the active feature. If new scope appears, stop and replan or defer it to another feature.\n- Preserve unrelated user changes in the worktree.\n- When a wrong assumption invalidates the feature, use `flow_feature_reset`; do not pile patches onto a bad path.\n\n## Validate\n\n- Read `references/validation-rubric.md` before completing.\n- Run the strongest practical checks for the changed behavior.\n- Record concrete command names, status, and observed results. \"Tests pass\" is not evidence.\n- Non-final features complete with `validationScope: \"targeted\"`.\n- The final feature must run a broad project-level gate and use `validationScope: \"broad\"`.\n\nFor broad validation research, risky changes, or unclear coverage, use\n`../flow/references/parallel-orchestration.md` to fan out named Flow workers.\nUse the mode-to-agent mapping in that reference instead of generic subagents.\nWorkers must use the handoff format and verification gates from that reference.\nThey may report command output they actually ran or propose focused checks; the\nmanager decides what is strong enough to record.\n\nFor independent implementation attempts, use candidate workers only with\nexplicit user authorization plus isolated worktrees or exact non-overlapping\npath ownership. Treat their output as candidate patches. The manager inspects,\nmerges, validates, and records Flow state serially.\n\n## Review and complete\n\nBefore `flow_feature_complete`, obtain a `featureReview` payload. Load `flow-review`; for read-only subagent reviews, the manager receives the payload and records it.\n\nFor the final feature, also obtain a `finalReview` payload whose `reviewDepth` equals the approved plan's `finalReviewPolicy`.\n\nComplete with:\n\n```json\n{\n  \"status\": \"ok\",\n  \"featureId\": \"active-feature-id\",\n  \"summary\": \"what changed\",\n  \"artifactsChanged\": [{ \"path\": \"src/file.ts\" }],\n  \"validationRun\": [\n    { \"command\": \"bun test tests/foo.test.ts\", \"status\": \"passed\", \"summary\": \"3 pass, exercised foo behavior\" }\n  ],\n  \"validationScope\": \"targeted\",\n  \"featureReview\": { \"status\": \"passed\", \"summary\": \"review summary\", \"blockingFindings\": [] }\n}\n```\n\nIf genuinely blocked, call `flow_feature_complete` with `status: \"needs_input\"` and an `outcome` that explains the blocker and next step. Never fabricate validation or review evidence to force progress.\n";var G=`# UI quality rubric
+`;var Y=`---
+name: flow-run
+description: Execute one approved Flow feature in the v4 runtime: start a feature with flow_run_start, make scoped changes, gather real validation evidence, obtain review payloads, and complete with flow_feature_complete.
+---
+
+# Flow Run
+
+Use this skill for implementation after a Flow plan is approved. Work one feature at a time.
+
+If \`flow_run_start\` is unavailable, stop and tell the user to check that \`opencode-plugin-flow\` is loaded in OpenCode.
+
+## Start
+
+- Call \`flow_status\`.
+- Call \`flow_run_start\` with no \`featureId\` unless the user or plan requires a specific runnable feature.
+- Treat the returned feature as the sole scope until it is completed, blocked, or reset.
+- Load \`flow-deslop\` for cleanup/refactor features. If it is unavailable,
+  record the gap and do not overclaim cleanup quality.
+- Load \`flow-ui-quality\` for frontend, UX, responsive, accessibility, or visual work. If it is unavailable, record the gap and use next-best UI evidence.
+
+## Implement
+
+- Read the feature \`targets\`, \`summary\`, \`validation\`, dependencies, and plan \`requirements\`/\`decisions\`.
+- Keep edits scoped to the active feature. If new scope appears, stop and replan or defer it to another feature.
+- Preserve unrelated user changes in the worktree.
+- When a wrong assumption invalidates the feature, use \`flow_feature_reset\`; do not pile patches onto a bad path.
+
+## Validate
+
+- Read \`references/validation-rubric.md\` before completing.
+- Run the strongest practical checks for the changed behavior.
+- Record concrete command names, status, and observed results. "Tests pass" is not evidence.
+- Non-final features complete with \`validationScope: "targeted"\`.
+- The final feature must run a broad project-level gate and use \`validationScope: "broad"\`.
+
+For broad validation research, risky changes, or unclear coverage, use
+\`../flow/references/parallel-orchestration.md\` to fan out named Flow workers.
+Use the mode-to-agent mapping in that reference instead of generic subagents.
+Workers must use the handoff format and verification gates from that reference.
+They may report command output they actually ran or propose focused checks; the
+manager decides what is strong enough to record.
+
+For independent implementation attempts, use candidate workers only with
+explicit user authorization plus isolated worktrees or exact non-overlapping
+path ownership. Treat their output as candidate patches. The manager inspects,
+merges, validates, and records Flow state serially.
+
+## Review and complete
+
+Before \`flow_feature_complete\`, obtain a \`featureReview\` payload. Load
+\`flow-review\`; for read-only subagent reviews, the manager receives the payload
+and records it.
+
+If \`flow_status\` reports \`setup.skills\` or \`flow-review\` cannot be loaded, do
+not record a Flow-gated \`featureReview\` or \`finalReview\`. You may perform an
+advisory review using available context or bundled reviewer fallback text, then
+complete with \`status: "needs_input"\` if review evidence is required to proceed.
+
+For the final feature, also obtain a \`finalReview\` payload whose \`reviewDepth\` equals the approved plan's \`finalReviewPolicy\`.
+
+Complete with:
+
+\`\`\`json
+{
+  "status": "ok",
+  "featureId": "active-feature-id",
+  "summary": "what changed",
+  "artifactsChanged": [{ "path": "src/file.ts" }],
+  "validationRun": [
+    { "command": "bun test tests/foo.test.ts", "status": "passed", "summary": "3 pass, exercised foo behavior" }
+  ],
+  "validationScope": "targeted",
+  "featureReview": { "status": "passed", "summary": "review summary", "blockingFindings": [] }
+}
+\`\`\`
+
+If genuinely blocked, call \`flow_feature_complete\` with \`status: "needs_input"\` and an \`outcome\` that explains the blocker and next step. Never fabricate validation or review evidence to force progress.
+`;var J=`# UI quality rubric
 
 Use this rubric for frontend planning, implementation, and review.
 
@@ -974,7 +1123,7 @@ class; severity; location or screenshot area; evidence inspected; user impact; f
 \`\`\`
 
 Blocking UI findings are issues that prevent task completion, hide required information, break accessibility basics, create incoherent layout at supported sizes, or make the visual success claim unverifiable.
-`;var L=`# Visual verification workflow
+`;var Z=`# Visual verification workflow
 
 Use this workflow when UI changes can be run locally. Flow execution may create visual evidence; Flow review usually assesses recorded evidence because the reviewer is read-only.
 
@@ -1014,7 +1163,7 @@ Record the reason and use the strongest available substitute:
 - code inspection against existing component patterns.
 
 Do not claim visual polish was verified if no visual artifact was inspected.
-`;var M=`---
+`;var Q=`---
 name: flow-ui-quality
 description: Flow guidance for UX/UI design, frontend polish, visual quality review, responsive and accessible interfaces, and avoiding generic AI-generated UI. Use when planning, executing, or reviewing frontend pages, components, dashboards, visual redesigns, interaction states, screenshots, or browser-verified UI work.
 ---
@@ -1059,12 +1208,16 @@ Approve only when the interface is both useful and inspectable:
 - Screenshot/browser evidence supports the claim whenever feasible.
 
 Never approve a UI change based only on code shape. If users will judge it visually, Flow evidence should include visual inspection.
-`;var x=[{name:"flow",files:[{relativePath:"SKILL.md",content:q},{relativePath:"references/recovery-playbook.md",content:U},{relativePath:"references/parallel-orchestration.md",content:C},{relativePath:"references/handoff-format.md",content:F},{relativePath:"references/verification-gates.md",content:A}]},{name:"flow-plan",files:[{relativePath:"SKILL.md",content:z},{relativePath:"references/planning-examples.md",content:W},{relativePath:"references/parallel-discovery.md",content:j}]},{name:"flow-run",files:[{relativePath:"SKILL.md",content:E},{relativePath:"references/validation-rubric.md",content:V},{relativePath:"references/audit-rubric.md",content:N}]},{name:"flow-review",files:[{relativePath:"SKILL.md",content:O},{relativePath:"references/review-rubric.md",content:B}]},{name:"flow-deslop",files:[{relativePath:"SKILL.md",content:D},{relativePath:"references/smell-rubric.md",content:P},{relativePath:"references/refactor-workflow.md",content:T}]},{name:"flow-ui-quality",files:[{relativePath:"SKILL.md",content:M},{relativePath:"references/ui-rubric.md",content:G},{relativePath:"references/visual-verification.md",content:L}]}];var X=".flow-skill-version";function _(){return process.env.HOME??process.env.USERPROFILE??""}function $(e=_()){return l(e,".config","opencode","skills")}function R(e){return xe("sha256").update(e).digest("hex")}function Ue(e,t){return[`version=${t}`,...e.files.map((a)=>`file=${a.relativePath} sha256=${R(a.content)}`),""].join(`
-`)}async function p(e){try{return await _e(e,"utf8")}catch(t){if(t.code==="ENOENT")return null;throw t}}function Y(e){let t=new Map;if(!e)return t;for(let a of e.split(/\r?\n/)){let r=/^file=(.+) sha256=([a-f0-9]{64})$/.exec(a)??/^file=(.+)=sha256:([a-f0-9]{64})$/.exec(a);if(r?.[1]&&r[2])t.set(r[1],r[2]);let n=/^hash=sha256:([a-f0-9]{64})$/.exec(a);if(n?.[1]&&!t.has("SKILL.md"))t.set("SKILL.md",n[1])}return t}function Ae(e){if(!e)return null;for(let t of e.split(/\r?\n/)){let a=/^version=(.+)$/.exec(t);if(a?.[1])return a[1]}return null}function J(e,t){let a=Fe(l(e,...t.split("/")));if(a!==e&&a.startsWith(`${e}${Ce}`))return a;throw Error(`Unsafe skill file path '${t}'.`)}function qe(){return x.map((e)=>e.name)}function Te(e){return`npx -y opencode-plugin-flow@${e} doctor`}function Pe(){if(process.env.npm_package_version)return process.env.npm_package_version;try{let e=Ie(import.meta.url);for(let t of["../package.json","../../package.json"])try{let a=e(t);if(a.version)return a.version}catch{}}catch{}return"0.0.0"}async function Z(e=Pe(),t=_()){let a=$(t),r=new Set(qe()),n=await Promise.all(x.map(async(o)=>{let i=l(a,o.name),m=await p(l(i,X)),g=Ae(m),ee=Y(m);if(await p(l(i,"SKILL.md"))===null)return{name:o.name,path:i,status:"missing",markerVersion:g,missingFiles:o.files.map((d)=>d.relativePath),editedFiles:[],outdatedFiles:[]};if(m===null)return{name:o.name,path:i,status:"foreign",markerVersion:g,missingFiles:[],editedFiles:[],outdatedFiles:[]};let w=[],y=[],b=[];for(let d of o.files){let k=await p(J(i,d.relativePath));if(k===null){w.push(d.relativePath);continue}if(k===d.content)continue;let I=ee.get(d.relativePath);if(I&&R(k)!==I){y.push(d.relativePath);continue}b.push(d.relativePath)}let ae=m!==Ue(o,e),te=w.length>0?"incomplete":y.length>0?"edited":ae||b.length>0?"outdated":"ok";return{name:o.name,path:i,status:te,markerVersion:g,missingFiles:w,editedFiles:y,outdatedFiles:b}})),s=[];try{s=await K(a)}catch(o){if(o.code!=="ENOENT")throw o}let c=s.filter((o)=>(o==="flow"||o.startsWith("flow-"))&&!r.has(o)).map((o)=>l(a,o)),u=n.filter((o)=>["missing","incomplete","outdated"].includes(o.status)).map((o)=>o.name),h=n.filter((o)=>["foreign","edited"].includes(o.status)).map((o)=>o.name),f=h.length>0,v=u.length>0;return{status:f?"action_required":v?"sync_required":"ok",version:e,root:a,expectedSkills:[...r],skills:n,syncRequiredSkills:u,actionRequiredSkills:h,unmanagedFlowSkills:c}}function S(e,t,a){if(a.length===0)return;e.push(`- ${t}: ${a.join(", ")}`)}function Q(e){let t=["Flow doctor",`- status: ${e.status}`,`- plugin version: ${e.version}`,`- skills root: ${e.root}`,`- expected skills: ${e.expectedSkills.join(", ")}`];S(t,"startup sync can install/update",e.syncRequiredSkills),S(t,"needs user decision",e.actionRequiredSkills),t.push("","Skills:");for(let a of e.skills){if(t.push(`- ${a.name}: ${a.status} (${a.path})${a.markerVersion?` marker=${a.markerVersion}`:""}`),a.missingFiles.length>0)t.push(`  missing: ${a.missingFiles.join(", ")}`);if(a.editedFiles.length>0)t.push(`  edited: ${a.editedFiles.join(", ")}`);if(a.outdatedFiles.length>0)t.push(`  outdated: ${a.outdatedFiles.join(", ")}`)}if(e.unmanagedFlowSkills.length>0){t.push("","Unmanaged Flow-like skill folders:");for(let a of e.unmanagedFlowSkills)t.push(`- ${a}`)}if(t.push("","Recommendation:"),e.status==="ok")t.push("- Flow skills are present and current.");else if(e.status==="sync_required")t.push("- Start or restart OpenCode with opencode-plugin-flow enabled so startup sync can install or update the listed skills. If Flow then reports restart_required, restart OpenCode once more so the refreshed skill registry is used.");else t.push("- Resolve user-owned or edited managed skill folders, then restart OpenCode. Move a folder aside to let Flow recreate it, or keep it intentionally as a local override.");return t.push(`- Details command: ${Te(e.version)}`),`${t.join(`
+`;var w=[{name:"flow",files:[{relativePath:"SKILL.md",content:B},{relativePath:"references/recovery-playbook.md",content:z},{relativePath:"references/parallel-orchestration.md",content:W},{relativePath:"references/handoff-format.md",content:j},{relativePath:"references/verification-gates.md",content:O}]},{name:"flow-plan",files:[{relativePath:"SKILL.md",content:M},{relativePath:"references/planning-examples.md",content:G},{relativePath:"references/parallel-discovery.md",content:S}]},{name:"flow-run",files:[{relativePath:"SKILL.md",content:Y},{relativePath:"references/validation-rubric.md",content:X},{relativePath:"references/audit-rubric.md",content:K}]},{name:"flow-review",files:[{relativePath:"SKILL.md",content:$},{relativePath:"references/review-rubric.md",content:L}]},{name:"flow-deslop",files:[{relativePath:"SKILL.md",content:E},{relativePath:"references/smell-rubric.md",content:V},{relativePath:"references/refactor-workflow.md",content:N}]},{name:"flow-ui-quality",files:[{relativePath:"SKILL.md",content:Q},{relativePath:"references/ui-rubric.md",content:J},{relativePath:"references/visual-verification.md",content:Z}]}];var U=".flow-skill-version";function x(){return process.env.HOME??process.env.USERPROFILE??""}function q(e=x()){return l(e,".config","opencode","skills")}function _(e){return Fe("sha256").update(e).digest("hex")}function b(e,a){return[`version=${a}`,...e.files.map((t)=>`file=${t.relativePath} sha256=${_(t.content)}`),""].join(`
+`)}async function f(e){try{return await Ue(e,"utf8")}catch(a){if(a.code==="ENOENT")return null;throw a}}function A(e){let a=new Map;if(!e)return a;for(let t of e.split(/\r?\n/)){let r=/^file=(.+) sha256=([a-f0-9]{64})$/.exec(t)??/^file=(.+)=sha256:([a-f0-9]{64})$/.exec(t);if(r?.[1]&&r[2])a.set(r[1],r[2]);let n=/^hash=sha256:([a-f0-9]{64})$/.exec(t);if(n?.[1]&&!a.has("SKILL.md"))a.set("SKILL.md",n[1])}return a}function je(e){if(!e)return null;for(let a of e.split(/\r?\n/)){let t=/^version=(.+)$/.exec(a);if(t?.[1])return t[1]}return null}function k(e,a){let t=Pe(l(e,...a.split("/")));if(t!==e&&t.startsWith(`${e}${De}`))return t;throw Error(`Unsafe skill file path '${a}'.`)}async function We(e,a,t){let r=l(t,e.name),n=l(r,U),s=await f(n),d=A(s);if(await f(l(r,"SKILL.md"))!==null&&s===null)return{name:e.name,action:"skipped_foreign"};let p=!1,m=!1;for(let o of e.files){let i=k(r,o.relativePath),u=await f(i);if(u===o.content)continue;p=!0;let v=d.get(o.relativePath);if(u!==null&&(v?_(u)!==v:s!==null))await y(`${i}.backup`,u,"utf8"),m=!0}if(!p&&s===b(e,a))return{name:e.name,action:"unchanged"};if(!p)return await y(n,b(e,a),"utf8"),{name:e.name,action:"marker_updated"};let g=s!==null;for(let o of e.files){let i=k(r,o.relativePath);await Ce(Te(i),{recursive:!0}),await y(i,o.content,"utf8")}return await y(n,b(e,a),"utf8"),{name:e.name,action:m?"updated_with_backup":g?"updated":"installed"}}function ze(){return w.map((e)=>e.name)}function Oe(e){return`npx -y opencode-plugin-flow@${e} doctor`}function T(){if(process.env.npm_package_version)return process.env.npm_package_version;try{let e=Ae(import.meta.url);for(let a of["../package.json","../../package.json"])try{let t=e(a);if(t.version)return t.version}catch{}}catch{}return"0.0.0"}async function ae(e,a=x()){let t=q(a);return Promise.all(w.map((r)=>We(r,e,t)))}async function te(e=T(),a=x()){let t=q(a),r=new Set(ze()),n=await Promise.all(w.map(async(o)=>{let i=l(t,o.name),u=await f(l(i,U)),v=je(u),P=A(u);if(await f(l(i,"SKILL.md"))===null)return{name:o.name,path:i,status:"missing",markerVersion:v,missingFiles:o.files.map((h)=>h.relativePath),editedFiles:[],outdatedFiles:[]};if(u===null)return{name:o.name,path:i,status:"foreign",markerVersion:v,missingFiles:[],editedFiles:[],outdatedFiles:[]};let I=[],R=[],F=[];for(let h of o.files){let C=await f(k(i,h.relativePath));if(C===null){I.push(h.relativePath);continue}if(C===h.content)continue;let D=P.get(h.relativePath);if(D&&_(C)!==D){R.push(h.relativePath);continue}F.push(h.relativePath)}let ne=u!==b(o,e),se=I.length>0?"incomplete":R.length>0?"edited":ne||F.length>0?"outdated":"ok";return{name:o.name,path:i,status:se,markerVersion:v,missingFiles:I,editedFiles:R,outdatedFiles:F}})),s=[];try{s=await ee(t)}catch(o){if(o.code!=="ENOENT")throw o}let d=s.filter((o)=>(o==="flow"||o.startsWith("flow-"))&&!r.has(o)).map((o)=>l(t,o)),c=n.filter((o)=>["missing","incomplete","outdated"].includes(o.status)).map((o)=>o.name),p=n.filter((o)=>["foreign","edited"].includes(o.status)).map((o)=>o.name),m=p.length>0,g=c.length>0;return{status:m?"action_required":g?"sync_required":"ok",version:e,root:t,expectedSkills:[...r],skills:n,syncRequiredSkills:c,actionRequiredSkills:p,unmanagedFlowSkills:d}}function H(e,a,t){if(t.length===0)return;e.push(`- ${a}: ${t.join(", ")}`)}function oe(e){let a=["Flow doctor",`- status: ${e.status}`,`- plugin version: ${e.version}`,`- skills root: ${e.root}`,`- expected skills: ${e.expectedSkills.join(", ")}`];H(a,"startup sync can install/update",e.syncRequiredSkills),H(a,"needs user decision",e.actionRequiredSkills),a.push("","Skills:");for(let t of e.skills){if(a.push(`- ${t.name}: ${t.status} (${t.path})${t.markerVersion?` marker=${t.markerVersion}`:""}`),t.missingFiles.length>0)a.push(`  missing: ${t.missingFiles.join(", ")}`);if(t.editedFiles.length>0)a.push(`  edited: ${t.editedFiles.join(", ")}`);if(t.outdatedFiles.length>0)a.push(`  outdated: ${t.outdatedFiles.join(", ")}`)}if(e.unmanagedFlowSkills.length>0){a.push("","Unmanaged Flow-like skill folders:");for(let t of e.unmanagedFlowSkills)a.push(`- ${t}`)}if(a.push("","Recommendation:"),e.status==="ok")a.push("- Flow skills are present and current.");else if(e.status==="sync_required")a.push("- Start or restart OpenCode with opencode-plugin-flow enabled so startup sync can install or update the listed skills. If Flow then reports restart_required, restart OpenCode once more so the refreshed skill registry is used.");else a.push("- Resolve user-owned or edited managed skill folders, then restart OpenCode. Move a folder aside to let Flow recreate it, or keep it intentionally as a local override.");return a.push(`- Details command: ${Oe(e.version)}`),`${a.join(`
 `)}
-`}async function H(e=_()){let t=$(e),a=[],r=[],n;try{n=await K(t)}catch(s){if(s.code==="ENOENT")return{removed:a,kept:r};throw s}for(let s of n){if(s!=="flow"&&!s.startsWith("flow-"))continue;let c=l(t,s),u=await p(l(c,X));if(u===null){r.push(c);continue}let h=Y(u),f=!1;for(let[v,o]of h){let i=await p(J(c,v));if(i!==null&&R(i)!==o){f=!0;break}}if(f){r.push(c);continue}await Re(c,{recursive:!0,force:!0}),a.push(c)}return{removed:a,kept:r}}async function De(e){let t=e[2];if(t!=="uninstall"&&t!=="doctor"){process.stderr.write(`usage: opencode-plugin-flow <doctor|uninstall>
-`),process.exitCode=2;return}if(t==="doctor"){process.stdout.write(Q(await Z()));return}let a=await H();for(let r of a.removed)process.stdout.write(`Removed Flow skill: ${r}
-`);for(let r of a.kept)process.stdout.write(`Kept non-Flow or user-edited skill: ${r}
+`}async function re(e=x()){let a=q(e),t=[],r=[],n;try{n=await ee(a)}catch(s){if(s.code==="ENOENT")return{removed:t,kept:r};throw s}for(let s of n){if(s!=="flow"&&!s.startsWith("flow-"))continue;let d=l(a,s),c=await f(l(d,U));if(c===null){r.push(d);continue}let p=A(c),m=!1;for(let[g,o]of p){let i=await f(k(d,g));if(i!==null&&_(i)!==o){m=!0;break}}if(m){r.push(d);continue}await qe(d,{recursive:!0,force:!0}),t.push(d)}return{removed:t,kept:r}}async function Be(e){let a=e[2];if(a!=="uninstall"&&a!=="doctor"&&a!=="sync"){process.stderr.write(`usage: opencode-plugin-flow <doctor|sync|uninstall>
+`),process.exitCode=2;return}if(a==="doctor"){process.stdout.write(oe(await te()));return}if(a==="sync"){let r=T(),n=await ae(r),s=n.filter((c)=>["installed","updated","updated_with_backup"].includes(c.action)),d=n.filter((c)=>c.action==="skipped_foreign");process.stdout.write(`Flow skill sync (${r})
+`);for(let c of n)process.stdout.write(`- ${c.name}: ${c.action}
+`);if(s.length>0)process.stdout.write(`Restart OpenCode so the refreshed skill registry is used.
+`);if(d.length>0)process.stdout.write(`Some managed skill folders are user-owned or edited; run doctor for repair guidance.
+`);return}let t=await re();for(let r of t.removed)process.stdout.write(`Removed Flow skill: ${r}
+`);for(let r of t.kept)process.stdout.write(`Kept non-Flow or user-edited skill: ${r}
 `);process.stdout.write(`Remove "opencode-plugin-flow" from opencode.json and restart OpenCode.
-`)}De(process.argv).catch((e)=>{process.stderr.write(`${e instanceof Error?e.message:String(e)}
+`)}Be(process.argv).catch((e)=>{process.stderr.write(`${e instanceof Error?e.message:String(e)}
 `),process.exitCode=1});