opencode-plugin-flow 4.1.1 → 4.1.3

package/dist/cli.js

@@ -1,7 +1,1070 @@
 #!/usr/bin/env node
-import{createHash as g}from"node:crypto";import{mkdir as aa,readdir as w,readFile as y,rm as b,writeFile as ta}from"node:fs/promises";import{dirname as ra,join as i,normalize as k,sep as x}from"node:path";var _=".flow-skill-version";function h(){return process.env.HOME??process.env.USERPROFILE??""}function F(e=h()){return i(e,".config","opencode","skills")}function R(e){return g("sha256").update(e).digest("hex")}async function u(e){try{return await y(e,"utf8")}catch(a){if(a.code==="ENOENT")return null;throw a}}function I(e){let a=new Map;if(!e)return a;for(let t of e.split(/\r?\n/)){let o=/^file=(.+) sha256=([a-f0-9]{64})$/.exec(t)??/^file=(.+)=sha256:([a-f0-9]{64})$/.exec(t);if(o?.[1]&&o[2])a.set(o[1],o[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 C(e,a){let t=k(i(e,...a.split("/")));if(t!==e&&t.startsWith(`${e}${x}`))return t;throw Error(`Unsafe skill file path '${a}'.`)}async function p(e=h()){let a=F(e),t=[],o=[],n;try{n=await w(a)}catch(r){if(r.code==="ENOENT")return{removed:t,kept:o};throw r}for(let r of n){if(r!=="flow"&&!r.startsWith("flow-"))continue;let s=i(a,r),c=await u(i(s,_));if(c===null){o.push(s);continue}let f=I(c),l=!1;for(let[m,v]of f){let d=await u(C(s,m));if(d!==null&&R(d)!==v){l=!0;break}}if(l){o.push(s);continue}await b(s,{recursive:!0,force:!0}),t.push(s)}return{removed:t,kept:o}}async function U(e){if(e[2]!=="uninstall"){process.stderr.write(`usage: opencode-plugin-flow uninstall
-`),process.exitCode=2;return}let t=await p();for(let o of t.removed)process.stdout.write(`Removed Flow skill: ${o}
-`);for(let o of t.kept)process.stdout.write(`Kept non-Flow or user-edited skill: ${o}
+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
+
+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
+covered, the evidence for each useful claim, and the remaining gaps. End worker
+prompts with "Return only this Flow handoff."
+
+## Evidence, review, validation, or audit worker report
+
+Use this for \`flow-evidence-worker\`, \`flow-reviewer\`,
+\`flow-validation-worker\`, and \`flow-audit-worker\`.
+
+\`\`\`markdown
+## Status
+success | partial | blocked
+
+## Scope
+<owned slice: path set, module, command, risk lens, route, data range, or question set>
+
+## Coverage
+- Expected: <files, ranges, questions, commands, or findings assigned>
+- Checked: <actual coverage, for example "12/12 files" or "command not run">
+- Not checked: <items skipped with reason, or "none">
+
+## Findings or facts
+- [high|med|low] <claim>; evidence: <file:line | command summary | screenshot path | URL | metric>; corroboration: <N sources or "single source">
+- [high|med|low] <claim>; evidence: <...>; corroboration: <...>
+
+## Sources
+- <paths read, commands run, docs fetched, data ranges covered, screenshots inspected>
+
+## Confidence and verification
+- Verified: <claims directly re-run, recounted, traced, or cross-checked>
+- Single-source: <claims with exactly one supporting source>
+- Inferred: <claims derived from surrounding evidence rather than directly observed>
+- Unsettled: <claims, sources, or citations that could not be resolved>
+- Falsifier or missing input: <what would overturn or materially change the result>
+
+## Open questions / gaps
+- <ambiguity, missing source, contradiction, skipped item, or out-of-scope dependency>
+
+## Manager follow-ups
+- <concrete next tasks, verifier claims, validation commands, or Flow plan targets>
+\`\`\`
+
+Validation workers must include exact command names and raw outcome summaries
+for commands they actually ran. Audit workers must include guards checked for
+any blocking-severity candidate. Review workers must separate blocking findings
+from advisory notes.
+
+## Verifier worker report
+
+Use this for \`flow-verifier-worker\`. Give it atomic claims and the cited sources
+or commands. Do not include the generator's reasoning unless that reasoning is
+the thing being verified.
+
+\`\`\`markdown
+## Status
+success | partial | blocked
+
+## Scope
+<claim ids, sources or commands checked, and the acceptance question>
+
+## Verdict per claim
+- <claim id>: verdict=<supported | partly-supported | unsupported | source-not-found>
+  - claim: <claim text>
+  - evidence: <supporting snippet, path plus line, measured value, command result, or "none">
+  - source resolution: <URL, path, or command plus whether it resolved>
+  - confidence level: high | med | low
+  - recommended action: <keep, narrow, rewrite, or remove>
+
+## Overall
+<accept | revise | reject> because <brief reason>
+
+## Gaps
+- <unavailable source, ambiguous claim wording, missing oracle, or check not run>
+
+## Manager follow-ups
+- <narrow recheck, plan adjustment, review finding, or none>
+\`\`\`
+
+## Candidate implementation worker report
+
+Use this only for isolated worktrees or exact non-overlapping path ownership
+authorized by the manager.
+
+\`\`\`markdown
+## Status
+success | partial | blocked
+
+## Scope
+<isolated worktree or exact path-owned slice>
+
+## Changed or proposed patch
+- <path>: <what changed and why>
+
+## Coverage
+- Assigned: <owned files/modules>
+- Touched: <files changed or proposed>
+- Skipped: <anything assigned but not changed and why, or "none">
+
+## Verification
+live-verified | test-verified | type-check-only | not-verified
+- <command, observed outcome, pass/fail counts, or manual check>
+
+## Confidence and risk
+- Checked directly: <behavior, files, or commands verified by the worker>
+- Still open: <tests, review paths, or integration points the manager must cover>
+- Risk: low | medium | high -- <why>
+
+## Merge notes
+- <conflicts, nearby user changes, assumptions, or deviations>
+
+## Manager follow-ups
+- <merge, reject, rerun check, verifier pass, or replan task>
+\`\`\`
+
+The manager must inspect and validate any candidate patch before recording Flow
+completion.
+`;var C=`# 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:
+only the manager calls state-changing Flow tools, approves plans, completes
+features, records reviews, or closes sessions.
+
+Read these companion references before a broad wave:
+
+- \`handoff-format.md\` for the exact worker response shapes.
+- \`verification-gates.md\` for coverage checks, handoff acceptance, verifier
+  triggers, and synthesis rules.
+
+## Manager sequence
+
+1. Call \`flow_status\` if a Flow session may already exist.
+2. Do a serial orientation pass. Read enough files, schemas, docs, tests,
+   commands, or artifacts to identify real slices.
+3. Define the local manager task. Do not delegate the immediate blocker that
+   determines whether fan-out is even valid.
+4. Build a pre-fan-out coverage gate:
+   - total files, modules, routes, commands, findings, rows, or claims in scope.
+   - one line per slice with path/range/lens and expected count.
+   - partition check showing slices add back to the total when the work is
+     countable.
+   - overlap/gap check showing no duplicate ownership, empty slices, or missing
+     target areas.
+5. Spawn only named Flow workers. Use exact slices and the required handoff
+   shape. Keep each prompt self-contained.
+6. Continue non-overlapping manager work while workers run.
+7. Read every handoff. Keep only claims that have evidence, match the assigned
+   scope, and carry confidence labels.
+8. Send important low-confidence, single-source, contested, or citation-heavy
+   claims to \`flow-verifier-worker\`.
+9. Run second waves only for material gaps, conflicts, narrowed scope, or
+   verification needs.
+10. Synthesize one Flow artifact: plan fields, completion evidence, review
+    payload, audit report, or candidate patch decision. Do not paste worker
+    handoffs as the user-facing result.
+
+## Modes
+
+When fanning out Flow work, select the matching hidden Flow agent by name. These
+workers are injected by the plugin config; invoke the named worker when it is
+available. Do not use generic subagents for Flow slices because Flow workers
+carry the permission boundaries for each mode.
+
+| Mode | Use agent | Worker output | Write access | Flow tools |
+| --- | --- | --- | --- | --- |
+| \`evidence\` | \`flow-evidence-worker\` | Coverage, facts, files inspected, confidence, gaps, suggested plan targets | No | \`flow_status\` only if needed |
+| \`review\` | \`flow-reviewer\` | Coverage, candidate findings or review slice summary, confidence, gaps | No | \`flow_status\` only if needed |
+| \`validation\` | \`flow-validation-worker\` | Command options or manager-authorized raw output, coverage, confidence, gaps | No code edits; commands only when explicitly allowed | \`flow_status\` only if needed |
+| \`audit\` | \`flow-audit-worker\` | Refuted or surviving finding candidates, guards checked, confidence, gaps | No | \`flow_status\` only if needed |
+| \`verifier\` | \`flow-verifier-worker\` | Per-claim verdicts against cited evidence or commands | No | \`flow_status\` only if needed |
+| \`candidate-implementation\` | \`flow-candidate-worker\` | Candidate patch summary from an isolated worktree or exact path-owned slice | Only with explicit user authorization plus isolation or exact non-overlapping path ownership | No state-changing Flow tools |
+
+Do not fan out parallel \`flow_plan_save\`, \`flow_plan_approve\`,
+\`flow_run_start\`, \`flow_feature_complete\`, \`flow_feature_reset\`, or
+\`flow_session_close\` calls. Runtime locking protects files, but Flow accepts only
+one active feature result at a time.
+
+## Worker rules
+
+Workers may read files, inspect docs, run authorized read-only commands, and
+summarize evidence. Candidate implementation workers may edit only when the
+manager assigned an isolated worktree or exact path ownership that does not
+overlap sibling workers or manager edits.
+
+Workers must not edit \`.flow/**\` and must not call:
+
+- \`flow_plan_save\`
+- \`flow_plan_approve\`
+- \`flow_run_start\`
+- \`flow_feature_complete\`
+- \`flow_feature_reset\`
+- \`flow_session_close\`
+
+Workers also must not approve work, close sessions, record Flow validation, or
+claim validation they did not run. A worker may report raw validation output it
+actually ran; the manager decides whether it is strong enough to record.
+
+## Prompt contract
+
+Every worker prompt includes:
+
+\`\`\`text
+Overall goal, context only: <goal>
+Mode: evidence | review | validation | audit | verifier | candidate-implementation
+Your exact slice: <paths, modules, command, claim ids, risk lens, or worktree>
+Expected coverage: <count, paths, range, or complete question set>
+Do: <bounded actions>
+Do not: call Flow state tools, edit .flow/**, own sibling slices, or make the final Flow verdict.
+Return exactly the matching handoff shape from handoff-format.md.
+\`\`\`
+
+For research or current-doc slices, require source checks for versioned or
+time-sensitive facts. For implementation candidates, remind workers that other
+work may be active and that they must not revert unrelated changes.
+
+## Where handoffs go
+
+- Planning evidence becomes \`requirements\`, \`decisions\`, feature \`targets\`,
+  feature \`validation\`, or plan notes in prose fields.
+- Execution evidence informs the active feature, but \`flow_feature_complete\` is
+  manager-owned.
+- Validation evidence may become \`validationRun\` only when the command, status,
+  and raw outcome are concrete enough to trust.
+- Review evidence informs \`featureReview\` or \`finalReview\`, but the manager owns
+  the pass/fail verdict.
+- Audit evidence becomes findings only after refutation and verification rules
+  in \`verification-gates.md\`.
+- Candidate patches are inspected, merged, and validated by the manager before
+  any Flow completion call.
+
+When worker results conflict, inspect the underlying artifact directly and rerun
+the smallest check that can settle the disagreement.
+
+## Second waves
+
+Start a follow-up wave when first-wave handoffs reveal:
+
+- missing coverage in the original slice map.
+- conflicting findings that matter to the Flow decision.
+- a specialized follow-up that was intentionally out of scope.
+- high-stakes, low-confidence, or single-source claims needing verification.
+- bounded implementation candidates after research converges.
+
+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
+
+Verification is how Flow keeps parallel work from turning into parallel
+guesswork. Worker handoffs are candidate evidence; the manager decides what can
+enter the plan, validation record, review payload, audit report, or final
+answer.
+
+## Before fan-out
+
+Run a pre-fan-out gate after serial orientation and before spawning workers:
+
+- Count the total work items when countable: files, modules, routes, commands,
+  rows, findings, screenshots, or claims.
+- List every slice with path/range/lens and expected count.
+- Check that countable slices add back to the total.
+- Check for overlapping ownership, missing areas, empty slices, and ambiguous
+  shared contracts.
+- Fix the slice map centrally before spawning if the gate does not reconcile.
+
+If the scope cannot be counted, state the completeness rule instead, such as
+"all changed files plus callers" or "all public commands plus release docs."
+
+## Every handoff
+
+Accept a handoff only after a cheap manager-side pass:
+
+- \`Status\` is terminal: \`success\`, \`partial\`, or \`blocked\`.
+- Coverage matches the assigned slice, or skips are explicit.
+- Important claims have concrete evidence and confidence tags.
+- Cited paths, commands, screenshots, URLs, or metrics resolve.
+- The evidence supports the claim, not just the topic.
+- Findings stay inside the worker's slice.
+- Headline counts can be recounted or traced.
+- Contradictions between workers are either resolved or explicitly marked as
+  contested.
+
+Demote, drop, re-task, or verify claims that fail this pass.
+
+## Verifier triggers
+
+Use \`flow-verifier-worker\` when a claim is:
+
+- blocking or release-sensitive.
+- high-stakes for user data, security, persistence, permissions, or public API
+  behavior.
+- low-confidence, inferred, surprising, or single-sourced.
+- citation-heavy enough that source drift would change the conclusion.
+- contradicted by another worker or by manager inspection.
+- a count, benchmark, command result, or pass/fail claim that a Flow payload will
+  rely on.
+
+Give the verifier atomic claims, cited sources or commands, and the acceptance
+question. Do not ask it to redesign the work or review the whole feature.
+
+## Flow payload acceptance
+
+Planning fields may use worker evidence only when the source and scope are clear.
+Unverified broad findings should become a review-first feature, not a fix plan.
+
+\`validationRun\` entries may use worker-reported commands only when the worker
+was explicitly authorized to run the command and reported the exact command,
+status, and raw outcome summary.
+
+\`featureReview\` and \`finalReview\` may use worker review slices, but the manager
+owns the pass/fail decision and must resolve blockers, contradictions, and
+coverage gaps before returning the payload.
+
+Audit reports may include only findings that survived refutation. Blocking audit
+findings need guards checked, deployment context, and evidence that the current
+code exhibits the behavior.
+
+Candidate implementation patches are not Flow evidence until the manager
+inspects, merges or rejects them, and runs suitable validation in the main
+Flow-managed workspace.
+
+## Final synthesis
+
+Before presenting or recording the result:
+
+- Preserve confidence: verified, single-sourced, inferred, and unresolved claims
+  stay distinct when it matters.
+- When workers disagree, inspect the cited artifact or rerun the cited command
+  instead of arbitrating from summaries.
+- Run the strongest practical local check for the deliverable.
+- Re-read critical files or docs that will be cited in the final decision.
+- Record gaps honestly instead of converting missing evidence into success
+  language.
+
+\`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
+
+Refactoring is a behavior-preserving sequence of small changes. This workflow keeps cleanup from becoming an unreviewable rewrite.
+
+## Before editing
+
+- Define the invariant: what behavior, API, schema, command, state path, or visual output must remain unchanged.
+- Locate callers and tests before changing the target. If there is no test coverage, add or run the narrowest check that proves current behavior.
+- Identify the smallest reversible move: remove dead code, rename, extract, inline, move, consolidate, or split phase.
+- Choose a validation command that can fail for the behavior you might break.
+
+## During editing
+
+- Make one structural move at a time, then re-run the relevant check when risk is non-trivial.
+- Prefer deleting or inlining a useless layer before introducing a new one.
+- Keep names domain-specific. Generic names like \`manager\`, \`processor\`, \`utils\`, and \`helper\` are suspect unless the repo already owns that vocabulary.
+- Avoid mixed commits inside a feature: no unrelated formatting, package churn, comment rewrites, or style sweeps.
+- If the refactor uncovers a behavior bug, stop and replan unless the approved feature already includes fixing that bug.
+
+## Validation evidence
+
+Good cleanup evidence includes:
+
+- focused tests for behavior touched by the refactor.
+- typecheck/lint/build output for mechanical structure changes.
+- before/after references for deleted exports, commands, generated files, and docs when static search is not enough.
+- broad validation when shared abstractions, public APIs, persistence, or cross-feature integration changed.
+
+Weak evidence includes:
+
+- "No tests needed" for behavior-adjacent refactors.
+- tests that were edited to match the new shape but do not prove the old behavior.
+- scanner metrics without human inspection.
+- green tests after changing unrelated surfaces not covered by those tests.
+
+## Review checklist
+
+- Every changed artifact maps to the approved cleanup scope.
+- The new structure has fewer reasons to change, not just fewer lines.
+- 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
+
+Use this rubric to turn vague cleanup instincts into reviewable findings.
+
+## Actionable smell classes
+
+- **duplication** — repeated logic or conditionals that must change together. Confirm whether small repetition is clearer than abstraction.
+- **bloat** — long function, large class/module, or oversized component whose responsibilities are mixed enough to hide behavior.
+- **speculative generality** — unused extension points, factories, options, interfaces, or configuration added for imagined futures.
+- **dead code** — unreachable branches, unused exports, stale flags, abandoned helpers, obsolete tests, or comments describing code that no longer exists.
+- **primitive obsession** — stringly typed modes, loosely shaped objects, or magic literals that obscure a domain constraint already present elsewhere.
+- **shotgun surgery** — one conceptual change requires scattered edits across unrelated modules.
+- **feature envy / misplaced responsibility** — code repeatedly reaches into another module's internals instead of using the owning boundary.
+- **message chains / excessive delegation** — call chains or wrappers that add no policy and make behavior harder to locate.
+- **agent slop** — verbose scaffolding, duplicate defensive branches, generic helper layers, temporary flags, commented-out code, debug output, or invented patterns that do not match the repo.
+- **test-oracle slop** — tests that assert implementation trivia, snapshots of noisy markup, or mocks that make broken behavior pass.
+
+## Non-smells until proven
+
+- Repetition that makes two workflows intentionally independent.
+- Framework-required shape, generated code, migration history, compatibility shims, or public API affordances.
+- Verbose guards protecting data loss, security, lifecycle ordering, or error observability.
+- Logging/metrics that operators or tests rely on.
+- Local style differences already accepted by the repo and not hurting changeability.
+
+## Finding shape
+
+Each blocking cleanup finding should carry:
+
+\`\`\`text
+class; severity; location; evidence read; refutation checked; why it matters; safe fix shape; validation command
+\`\`\`
+
+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=`---
+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.
+---
+
+# Flow deslop
+
+Use this skill when the Flow work is about improving code quality rather than adding a new user-visible feature. The job is to make the code easier to change without changing behavior unless the approved plan explicitly says behavior changes.
+
+## Ground the cleanup
+
+- Start from concrete evidence: duplicated code, unnecessary abstraction, long or tangled functions, dead branches, confusing ownership, repeated conditionals, excessive coupling, or validation gaps that hide maintainability risk.
+- Load \`references/smell-rubric.md\` when classifying findings or deciding what is worth fixing.
+- Load \`references/refactor-workflow.md\` before implementing or reviewing non-trivial cleanup.
+- Treat scanner output, metrics, and model impressions as candidates only. A smell becomes actionable after reading the surrounding code, callers, tests, and relevant contracts.
+- Record cleanup context in existing Flow plan fields: \`requirements\`, \`decisions\`, feature \`targets\`, and feature \`validation\`. Do not invent new Flow payload fields.
+
+## Plan cleanup work
+
+- Prefer one feature per validated cleanup theme with a clear validation story. "Clean the whole repo" starts with a review-first feature that produces evidence-backed findings, then fix features for confirmed clusters.
+- Keep refactors small and behavior-preserving. If a cleanup requires behavior change, surface it as product scope and replan.
+- State what will not be cleaned. Broad cleanup without boundaries invites churn and makes review impossible.
+- Choose validation before editing: focused tests for affected behavior, typecheck/lint for mechanical changes, and a broad gate when cleanup spans shared abstractions.
+
+## Execute cleanup safely
+
+- Preserve public APIs, persisted data, command names, tool names, and observable behavior unless the approved plan explicitly changes them.
+- Prefer removal, consolidation, naming, and local extraction before new abstractions. New abstractions must reduce real duplication or clarify an existing boundary.
+- Delete dead code only after checking references, exports, generated entrypoints, docs, tests, and runtime/distribution paths that static search may miss.
+- Keep every change tied to a finding or plan target. Opportunistic style edits are out of scope.
+
+## Review cleanup claims
+
+For each claimed smell removal, verify:
+
+- **location** — the changed code and the original smell were actually read.
+- **impact** — the change reduces duplication, coupling, complexity, or future-change risk in a concrete way.
+- **refutation checked** — apparent smell was not intentional compatibility, performance, generated code, framework convention, or a safety guard.
+- **behavior preserved** — tests or other evidence cover the behavior touched.
+- **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
+
+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.
+
+For broad waves, also load \`../../flow/references/parallel-orchestration.md\`.
+Use its pre-fan-out coverage gate and
+\`../../flow/references/handoff-format.md\` response shapes.
+
+## Good slices
+
+- Independent modules or packages.
+- Frontend route and backend endpoint pairs.
+- Test, CI, and release surfaces.
+- Risk lenses such as security, persistence, accessibility, migration, or performance.
+- Documentation and operator-contract checks.
+
+## Flow repo default slices
+
+For this repository, good first-wave slices are:
+
+- Runtime gates: \`src/runtime/schema.ts\`, \`src/runtime/transitions.ts\`,
+  \`src/runtime/api.ts\`, and \`tests/runtime-gates.test.ts\`.
+- Workspace persistence: \`src/runtime/workspace.ts\`,
+  \`src/runtime/json/strict-object.ts\`, and
+  \`tests/workspace-persistence.test.ts\`.
+- OpenCode adapter surface: \`src/adapters/opencode/**\`, \`src/config-shared.ts\`,
+  \`src/config.ts\`, \`src/index.ts\`, and surface tests.
+- Distribution and synced skills: \`src/distribution/**\`, \`src/cli.ts\`,
+  \`skills/**\`, and distribution tests.
+- CI, package, and release contract: \`.github/workflows/**\`, \`package.json\`,
+  \`bun.lock\`, \`README.md\`, and \`CHANGELOG.md\`.
+- Docs and operator contract: \`docs/**\`, \`README.md\`, and skill references.
+
+## Coverage gate
+
+Before spawning workers, state the total discovery scope and one line per slice.
+For countable scopes, confirm that slice counts add back to the total and that
+there are no overlaps, gaps, or empty slices. If the scope is not countable,
+state the completeness rule, such as "all changed files plus callers."
+
+## Worker prompt
+
+\`\`\`text
+Inspect <slice> for <goal>. Read-only. Do not edit files or call Flow tools.
+Return the evidence/review/validation/audit handoff shape from ../../flow/references/handoff-format.md.
+\`\`\`
+
+For validation-oriented discovery:
+
+\`\`\`text
+Inspect <slice> for validation risk. Read-only. Do not edit files or call Flow
+tools. You may report commands that should be run, and include raw output only
+for commands you actually ran. Return the evidence/review/validation/audit
+handoff shape from ../../flow/references/handoff-format.md.
+\`\`\`
+
+## Synthesis
+
+Convert only evidence-backed work into plan fields:
+
+- \`requirements\`: user promises and externally visible acceptance criteria.
+- \`decisions\`: architecture boundaries, rejected approaches, and scope cuts.
+- feature \`targets\`: files, modules, routes, commands, docs, or workflows the feature owns.
+- 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
+
+## Rate limiting feature set
+
+Human summary:
+
+1. **In-memory rate limit middleware** - add request counting and response headers for one-process deployments.
+2. **Redis-backed limiter** - add shared store adapter for multi-instance deployments.
+3. **Operator docs** - document configuration and rollout notes.
+
+Payload:
+
+\`\`\`json
+{
+  "goal": "Add API rate limiting with local and Redis-backed stores",
+  "plan": {
+    "summary": "Add configurable rate limiting for API routes.",
+    "overview": "Implement middleware first, then a Redis store, then document rollout.",
+    "requirements": [
+      "Preserve existing route behavior except rate-limit responses.",
+      "Expose deterministic headers for limit, remaining, and reset time."
+    ],
+    "decisions": [
+      "Start with an in-memory store for single-process deployments.",
+      "Keep Redis behind a store interface so tests can use a mock."
+    ],
+    "finalReviewPolicy": "detailed",
+    "features": [
+      {
+        "id": "rate-limit-middleware",
+        "title": "In-memory limiter",
+        "summary": "Add middleware, config, and tests for single-process rate limiting.",
+        "targets": ["src/middleware/rate-limit.ts", "src/app.ts", "src/config.ts"],
+        "validation": ["route tests for limit/reset/header behavior", "typecheck"],
+        "dependsOn": []
+      },
+      {
+        "id": "redis-store",
+        "title": "Redis store",
+        "summary": "Add a Redis-backed rate limit store without changing middleware behavior.",
+        "targets": ["src/middleware/stores/redis.ts", "src/middleware/rate-limit.ts"],
+        "validation": ["store tests with Redis mock", "manual two-process recipe if practical"],
+        "dependsOn": ["rate-limit-middleware"]
+      },
+      {
+        "id": "operator-docs",
+        "title": "Operator docs",
+        "summary": "Document configuration, headers, and rollout guidance.",
+        "targets": ["README.md", "docs/operations.md"],
+        "validation": ["lint docs if available", "review examples against implemented config"],
+        "dependsOn": ["redis-store"]
+      }
+    ]
+  }
+}
+\`\`\`
+
+## Review-first cleanup
+
+Bad plan:
+
+\`\`\`text
+1. Simplify services
+2. Remove duplication
+3. Improve tests
+\`\`\`
+
+Why it is bad: no evidence names which services are actually tangled, what duplication exists, or which behavior needs test coverage.
+
+Better plan:
+
+\`\`\`text
+1. Audit service layer - produce evidence-backed findings with file:line citations, guards checked, and follow-up order.
+2. Consolidate confirmed config parsing duplication - only if the audit proves the duplication exists and is safe to merge.
+3. Add behavior-preservation tests for the changed service paths.
+\`\`\`
+
+## Decomposition anti-patterns
+
+- Feature per file when behavior crosses files.
+- Feature per implementation step with no user-visible or reviewable outcome.
+- Plan fixes for findings not yet verified.
+- Validation that only says "manual testing".
+- Targets that name the entire repo.
+- Features with hidden dependencies instead of \`dependsOn\`.
+`;var z=`---
+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.
+---
+
+# Flow Plan
+
+Use this skill before implementation. The output is a compact plan the runtime can enforce and future agents can execute without rediscovering the goal.
+
+If \`flow_plan_save\` or \`flow_plan_approve\` is unavailable, stop and tell the user to check that \`opencode-plugin-flow\` is loaded in OpenCode. Planning requires the loaded Flow runtime.
+
+## Inspect first
+
+- 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\`.
+- Do not invent findings. Broad "review and fix" goals start with a review-first feature whose deliverable is evidence-backed findings.
+
+## Plan shape
+
+Call \`flow_plan_save\` with:
+
+\`\`\`json
+{
+  "goal": "user-visible goal",
+  "plan": {
+    "summary": "one-sentence outcome",
+    "overview": "implementation strategy and boundaries",
+    "requirements": ["constraints, acceptance criteria, user promises"],
+    "decisions": ["architecture or scope decisions already made"],
+    "finalReviewPolicy": "detailed",
+    "features": [
+      {
+        "id": "lowercase-kebab-case",
+        "title": "Short title",
+        "summary": "Outcome this feature delivers",
+        "targets": ["files, modules, routes, commands, or docs in scope"],
+        "validation": ["focused checks expected before completion"],
+        "dependsOn": []
+      }
+    ]
+  }
+}
+\`\`\`
+
+Use only \`finalReviewPolicy: "broad"\` or \`"detailed"\`. These are the canonical final-review policy and \`reviewDepth\` enum values. Use \`"broad"\` only for low-risk, narrow work. Use \`"detailed"\` for behavioral changes, cross-module edits, migrations, releases, security-sensitive code, or large refactors.
+
+## Feature sizing
+
+- Each feature should have one owner, one coherent outcome, and a validation story.
+- Split by dependency order: foundations before callers, schema before consumers, implementation before docs when docs depend on behavior.
+- Avoid "misc cleanup" features. Tie cleanup to evidence and targets.
+- Keep feature ids stable once the plan is approved.
+- Put scope boundaries in \`targets\` and expected checks in \`validation\`.
+
+## Approval
+
+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
+
+Use this to decide whether a \`featureReview\` or \`finalReview\` payload may pass.
+
+## Finding classes
+
+- **correctness**: wrong result, broken state transition, bad edge case, race, data loss, or crash.
+- **contract**: public API, CLI, config, persisted data, or documented behavior changed without plan approval.
+- **security/privacy**: unsafe input handling, secret exposure, permission bypass, or insecure default.
+- **test-coverage**: behavioral change lacks a check strong enough for the risk.
+- **maintainability**: complexity or coupling creates concrete future-change risk.
+- **ui/accessibility**: user cannot complete the workflow, layout breaks, accessibility basics fail, or visual claims lack evidence.
+
+## Severity
+
+- **blocking**: must fail the review. Includes incorrect behavior, data loss, security risk, unverifiable completion claims, missing validation for behavioral work, or unresolved scope drift.
+- **advisory**: worth noting but does not block the current goal.
+
+If unsure whether a finding is real, read more or downgrade it. Do not promote guesses to blockers.
+
+## Feature review checklist
+
+- The work matches the active feature's \`summary\`, \`targets\`, and dependencies.
+- Plan \`requirements\` and \`decisions\` are still honored.
+- Changed files were read, not just summarized.
+- Validation evidence covers the behavior touched.
+- New tests or manual checks would fail or visibly differ without the change where practical.
+- No unrelated scope slipped in.
+- Public contracts and downstream callers still work.
+
+## Final review checklist
+
+- Every feature is complete and together they satisfy the original goal.
+- Broad validation ran and passed.
+- The final \`reviewDepth\` equals the approved \`finalReviewPolicy\`; the only final-review enum values are \`broad\` and \`detailed\`.
+- Feature-level reviews have no unresolved blocking findings.
+- Docs, commands, package metadata, and release surfaces match the delivered behavior.
+- Remaining gaps are explicit and do not contradict \`kind: "completed"\`.
+
+## Payloads
+
+Feature review:
+
+\`\`\`json
+{
+  "status": "passed",
+  "summary": "Reviewed changed runtime files and focused tests; validation covers the new gate.",
+  "blockingFindings": []
+}
+\`\`\`
+
+Failed feature review:
+
+\`\`\`json
+{
+  "status": "failed",
+  "summary": "Validation does not exercise the changed persistence path.",
+  "blockingFindings": [
+    {
+      "summary": "No test covers archive removal of .flow/session.json after close.",
+      "severity": "blocking"
+    }
+  ]
+}
+\`\`\`
+
+Final review:
+
+\`\`\`json
+{
+  "status": "passed",
+  "summary": "Reviewed plan scope, all changed files, broad validation, and release metadata.",
+  "blockingFindings": [],
+  "reviewDepth": "detailed"
+}
+\`\`\`
+
+## Audit report reviews
+
+When reviewing a findings report, verify findings adversarially:
+
+- Check the cited file and surrounding code.
+- Trace mitigating paths before accepting blocking severity.
+- Confirm the deployment model used for severity.
+- Dedupe overlapping findings.
+- 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=`---
+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.
+---
+
+# Flow Review
+
+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.
+
+## Start
+
+- Call \`flow_status\` when available.
+- Identify whether this is a feature review or final review.
+- Read the approved plan fields relevant to the work: \`requirements\`, \`decisions\`, feature \`targets\`, feature \`validation\`, and dependencies.
+- Inspect the actual diff, changed files, tests, and validation output. Do not review only the completion summary.
+- Load \`references/review-rubric.md\` for severity, depth, and payload shape.
+
+## Feature Review Depth
+
+- **quick**: docs, comments, config-only changes, or mechanical changes fully covered by tooling.
+- **standard**: default feature review. Read every changed file and relevant tests.
+- **detailed**: risky behavior, persistence, security, cross-module refactors, migrations, releases, or weak validation.
+
+\`quick\` and \`standard\` are feature-review depth descriptions only. Final reviews use \`reviewDepth: "broad"\` or \`"detailed"\` to match the plan's \`finalReviewPolicy\`; these runtime enum values are the canonical final-review terms. Claim only the depth actually performed. Missing evidence is a finding, not a nuisance.
+
+## Output
+
+For a feature review, return:
+
+\`\`\`json
+{
+  "status": "passed",
+  "summary": "what was reviewed and why it is acceptable",
+  "blockingFindings": []
+}
+\`\`\`
+
+For a final review, return:
+
+\`\`\`json
+{
+  "status": "passed",
+  "summary": "session-level review summary",
+  "blockingFindings": [],
+  "reviewDepth": "detailed"
+}
+\`\`\`
+
+Use \`status: "failed"\` when any blocking finding remains. Advisory findings may be included in the prose summary, but \`blockingFindings\` contains only blockers.
+
+## 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.
+- 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.
+  Use the named review, audit, evidence, or validation agents from that
+  reference instead of generic subagents. Apply its handoff format and
+  verification gates; only the manager returns the final \`featureReview\` or
+  \`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
+
+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.
+
+A findings report is a set of claims about code you did not write. Its failure mode is not "missed something" — it is the confident, accurately-cited finding that is wrong because the mitigating code path was never read. Accurate citations are necessary, never sufficient: a citation proves you found the suspicious site, not that the suspicion survives contact with the rest of the codebase.
+
+## Refute before you report
+
+Before any finding earns blocking severity (P1/P2 or equivalent), actively try to kill it:
+
+- **Trace the mitigating paths.** Read the callers of the suspicious site and the code it delegates to. The question is never "could this line misbehave?" but "does anything between input and this line already prevent that?"
+- **Cross the layer boundary.** In a multi-layer repo, a finding in one layer is unverified until you have read its counterpart in the other. A frontend finding requires reading the backend handler it calls (it may already validate or dedupe); a library-internals finding requires checking what validation real callers pass through; an API finding requires checking what the client can actually send.
+- **Check the surrounding lifecycle.** State that "leaks" or "goes stale" may already be reset by an effect, a guard clause, or an invalidation a few lines away from where you stopped reading.
+
+A finding that survives this pass is worth reporting. A finding you did not try to refute is a guess with a citation.
+
+## Parallel audit slices
+
+For broad audits, use \`../../flow/references/parallel-orchestration.md\` to split
+read-only slices by module, data flow, or risk lens. Workers surface candidates;
+the audit author owns the report. Apply its handoff format and verification
+gates. Before blocking severity, dedupe, trace guards, fill cross-layer checks,
+verify contested or high-stakes claims, and downgrade missing context.
+
+## Every blocking finding records "guards checked"
+
+In addition to evidence, why-it-matters, and fix shape, every blocking finding names the mitigating paths you traced and why they do not cover this case ("\`suggest_mappings()\` enforces one-to-one via \`used_a\`/\`used_b\` — but nothing dedupes after the frontend re-sorts" reads very differently from silence). No guards-checked line means the finding is unverified: downgrade it to advisory and say what you did not trace.
+
+## Observed, not hypothesized
+
+- A blocking finding describes behavior the current code exhibits, with the input that triggers it. "If the backend ever returns X" is a hypothesis about code you chose not to read — either read it and confirm, or record the item as a defense-in-depth note (advisory at most).
+- Uncertainty after tracing is honest — state it and rate by the realistic worst case. Uncertainty instead of tracing is padding.
+
+## Severity is rated in deployment context
+
+- The report header states the deployment model the product actually has: desktop app, shared server, library consumed by others, CLI, and so on.
+- Rate impact within that model. Unbounded memory in a single-user desktop process whose lifetime is one window is not the severity it would be in a long-running shared service. When a finding only matters under a deployment the product does not have, say so explicitly ("becomes blocking if this ships as a shared service") instead of rating for the imagined deployment.
+
+## Report shape
+
+\`\`\`
+header: scope audited; deployment context; validation commands actually run
+findings, strongest first, each with:
+  - class and severity
+  - evidence — file:line actually read
+  - guards checked — mitigating paths traced and why they fall short (blocking findings)
+  - why it matters — the concrete failure, with triggering input
+  - fix shape — one sentence, not an implementation
+positive findings — what is genuinely solid, so fixes do not regress it
+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
+
+Use this before recording \`flow_feature_complete\`.
+
+## Evidence tiers
+
+1. **Behavioral automated test**: a targeted unit/integration/e2e test exercises the changed behavior and fails without the change.
+2. **Manual reproducible check**: you ran the app, CLI, endpoint, or workflow and recorded exact steps plus observed result.
+3. **Indirect automated check**: typecheck, lint, build, or compile proves shape but not behavior. Acceptable alone only for docs, comments, renames fully covered by tooling, or purely mechanical changes.
+4. **Static inspection**: reading code without running anything. This is a gap, not completion evidence for behavioral work.
+
+Use the strongest practical tier. For risky work, combine tiers.
+
+## Recording rules
+
+- Each \`validationRun\` entry has \`command\`, \`status\`, and \`summary\`.
+- Completion accepts only passing entries. Failed or skipped checks belong in the summary/notes and must be resolved or explained as blockers.
+- Do not claim a command was run unless it was run in this session or directly reported by a trusted worker with raw output.
+- Worker-reported command output must satisfy \`../../flow/references/verification-gates.md\`: exact command, status, raw outcome summary, coverage, and manager acceptance.
+- Include scope in the summary: what behavior, files, routes, or states the check covered.
+- UI work should include browser or screenshot evidence when the app can run locally.
+- Cleanup/refactor work should show behavior preservation, not only formatting success.
+
+## Scope
+
+- Use \`validationScope: "targeted"\` for ordinary feature completion.
+- Use \`validationScope: "broad"\` only when the session is on its final feature and the project-level gate was run.
+
+Broad validation usually means the repo's full check command, full relevant test suite, build, or equivalent release gate. If the broad gate cannot run, do not mark the final feature complete; report \`needs_input\` or fix the blocker.
+
+## Good payload fragment
+
+\`\`\`json
+{
+  "validationRun": [
+    {
+      "command": "bun test tests/runtime-gates.test.ts",
+      "status": "passed",
+      "summary": "12 pass; covered approval immutability, active feature, and completion gates"
+    },
+    {
+      "command": "bun run typecheck",
+      "status": "passed",
+      "summary": "TypeScript accepted runtime and adapter changes"
+    }
+  ],
+  "validationScope": "broad"
+}
+\`\`\`
+
+## Blockers and resets
+
+- If validation fails due to a code bug, fix it and rerun.
+- If validation reveals a wrong design or interface assumption, call \`flow_feature_reset\` and rerun from the corrected approach.
+- 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
+
+Use this rubric for frontend planning, implementation, and review.
+
+## Product fit
+
+- The screen solves the user's actual task, not a generic demo of components.
+- The first viewport shows the product, data, object, or workflow the user came for.
+- The information density matches use: operational tools favor scannable, compact structure; expressive pages need stronger visual identity and media.
+- Navigation and primary actions are obvious without explanatory helper text.
+
+## Visual design
+
+- **Typography**: hierarchy is clear; font choices fit the product; body text remains readable; compact surfaces do not use hero-scale type.
+- **Color**: palette has a coherent role system; contrast is sufficient; accent colors guide attention; avoid one-note palettes and generic purple-blue gradients unless the brand requires them.
+- **Composition**: alignment, spacing, and grouping make comparison easy; repeated items are consistent; page sections are not nested decorative cards.
+- **Controls**: use familiar controls for the job: icons for common tools, toggles for binary settings, segmented controls for modes, sliders/inputs for numbers, menus for option sets.
+- **Motion**: animation clarifies state or creates a focused moment; it does not hide latency, distract from work, or ignore reduced-motion needs.
+- **Imagery/media**: when the subject matters, show the actual product/place/object/state rather than atmospheric filler.
+
+## Interaction and states
+
+- Loading, empty, error, disabled, hover, focus, selected, and validation states exist for the changed workflow.
+- Long strings, missing data, large numbers, and small screens do not break layout.
+- Destructive actions have appropriate confirmation or undo patterns.
+- Form errors are close to the field and clear enough to fix.
+- Async state cannot double-submit, lose edits, or leave stale UI behind.
+
+## Accessibility baseline
+
+- Interactive elements are semantic or have correct roles and labels.
+- Keyboard users can reach and operate controls in a logical order.
+- Focus indicators are visible.
+- Text and essential UI meet contrast expectations.
+- Status, error, and progress messages are not conveyed by color alone.
+- Motion respects reduced-motion preferences when substantial.
+
+## Review finding shape
+
+\`\`\`text
+class; severity; location or screenshot area; evidence inspected; user impact; fix shape; visual/validation evidence needed
+\`\`\`
+
+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
+
+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.
+
+## Execution lane
+
+- Identify the target route, state, viewport sizes, and any required seed data.
+- Start the repo's normal dev server or storybook command from the recorded repo profile.
+- Prefer existing browser or Playwright tooling when available. Do not add heavy visual tooling just to inspect a small change.
+- Capture at least one desktop viewport and one mobile viewport for user-facing layout changes.
+- Exercise the primary interaction changed by the feature.
+- Inspect loading, empty, and error states when they are part of the changed workflow or easy to reach.
+- Check browser console output when the tooling exposes it.
+- For canvas/3D/media-heavy UI, verify rendered pixels are nonblank and the subject is framed.
+
+## Review lane
+
+- Inspect the screenshots, browser notes, console output, or visual artifacts recorded by execution.
+- Compare recorded evidence against the plan's design intent, supported viewports, state coverage, and the UI rubric.
+- If the current reviewer has browser/shell tools and permissions, it may perform additional read-only visual checks.
+- If the reviewer is read-only without browser or shell access, do not try to recreate evidence. Treat missing or insufficient visual evidence as a finding or coverage gap.
+
+## What to look for
+
+- Text overlap, clipped labels, unintended wrapping, and controls resizing on hover.
+- Incoherent spacing, nested cards, generic placeholder visuals, and decorative elements that compete with the task.
+- Missing focus states, low contrast, unreachable controls, and color-only status.
+- Broken responsive behavior: horizontal scroll, collapsed controls, hidden primary actions, or unreadable tables.
+- State bugs: stale loading indicators, duplicate submissions, lost input, or errors that cannot be recovered.
+
+## If visual verification is unavailable
+
+Record the reason and use the strongest available substitute:
+
+- build/typecheck/lint for changed frontend code.
+- component or interaction tests.
+- Storybook/static render output.
+- code inspection against existing component patterns.
+
+Do not claim visual polish was verified if no visual artifact was inspected.
+`;var M=`---
+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.
+---
+
+# Flow UI quality
+
+Use this skill when Flow work changes what a user sees or how they interact with an interface. The goal is production UI quality: useful, coherent, accessible, responsive, and visually intentional.
+
+## Establish the interface intent
+
+- Identify the user, job-to-be-done, primary workflow, density needs, device constraints, and brand/product tone before choosing visuals.
+- Choose a clear design direction that fits the product context. Distinctive does not mean decorative; utilitarian tools can be excellent through restraint, hierarchy, and speed.
+- Load \`references/ui-rubric.md\` for design and UX review criteria.
+- Load \`references/visual-verification.md\` before completing meaningful UI changes to capture visual evidence. During review, use it to assess recorded evidence; only run browser checks yourself if the current agent and tools permit it.
+- Record design constraints and verification expectations in Flow plan fields: \`requirements\`, \`decisions\`, feature \`targets\`, and feature \`validation\`. Do not add new Flow payload fields.
+
+## Build with visual intent
+
+- Use existing design systems, component libraries, tokens, icons, and layout conventions before inventing new primitives.
+- Make typography, spacing, color, motion, and hierarchy deliberate. Avoid default-looking AI output: centered everything, purple gradients, generic cards, uniform oversized radii, stock SaaS layouts, and unexamined Inter/system-font sameness.
+- Match composition to domain: operational apps need scanability, alignment, predictable controls, efficient density, and clear states; marketing or editorial surfaces can carry more expressive imagery and motion.
+- Include states a real user will hit: loading, empty, error, disabled, hover, focus, selected, validation, and long content.
+- Protect accessibility: semantic controls, labels, focus order, keyboard reachability, contrast, reduced-motion behavior, and non-color-only status.
+
+## Verify visually
+
+- For meaningful UI changes, run the app and capture screenshots when a local browser target is available.
+- Check desktop and mobile breakpoints, not only the viewport you developed in.
+- Verify text does not overlap, truncate unintentionally, or escape controls; long labels and empty/error states must fit.
+- Compare against provided screenshots, design references, or the stated product intent. List meaningful differences and fix the ones that violate the goal.
+- If browser verification cannot run, record the gap and the next-best evidence such as component tests, Storybook snapshots, build output, or static inspection.
+
+## Review UI work
+
+Approve only when the interface is both useful and inspectable:
+
+- The main workflow is visible and efficient.
+- Visual hierarchy makes the next action obvious.
+- Responsive behavior is deliberate.
+- Accessibility basics are covered.
+- State coverage is present or the gaps are explicit.
+- 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(`
+`)}
+`}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}
 `);process.stdout.write(`Remove "opencode-plugin-flow" from opencode.json and restart OpenCode.
-`)}U(process.argv).catch((e)=>{process.stderr.write(`${e instanceof Error?e.message:String(e)}
+`)}De(process.argv).catch((e)=>{process.stderr.write(`${e instanceof Error?e.message:String(e)}
 `),process.exitCode=1});