opencode-plugin-flow 4.1.17 → 4.2.0

package/dist/cli.js

@@ -1,11 +1,23 @@
 #!/usr/bin/env node
-import{createHash as ze}from"node:crypto";import{mkdir as Ee,readdir as ne,readFile as Be,rm as ie,writeFile as x}from"node:fs/promises";import{createRequire as Ve}from"node:module";import{dirname as Ne,join as h,normalize as Ge,sep as Me}from"node:path";var S=`# Flow worker handoff contract
+
+// src/distribution/sync.ts
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { dirname, join, normalize, sep } from "node:path";
+
+// skills/flow/references/handoff-format.md
+var handoff_format_default = `# 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."
 
+Sections: evidence/review/validation/audit worker report, verifier worker report,
+and candidate implementation worker report.
+
 Status meanings:
 
 - \`success\`: the assigned scope was covered, or any skipped items are explicitly
@@ -137,22 +149,29 @@ live-verified | test-verified | type-check-only | not-verified
 
 The manager must inspect and validate any candidate patch before recording Flow
 completion.
-`;var W=`# Parallel orchestration
+`;
+
+// skills/flow/references/parallel-orchestration.md
+var parallel_orchestration_default = `# 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.
 
+Sections: quick path, operational defaults, manager sequence, modes, permission
+contract, worker rules, prompt contract, handoff location, and follow-up passes.
+
 Read these companion references before a broad parallel pass:
 
 - \`parallel-pass-patterns.md\` for pass selection, effort defaults, and stop or
   follow-up rules.
 - \`handoff-format.md\` for the exact worker response shapes.
-- \`verification-gates.md\` for coverage checks, handoff acceptance, verifier
-  triggers, and synthesis rules.
+- \`verification-gates.md\` for the pre-fan-out coverage gate, handoff
+  acceptance, verifier triggers, and the manager synthesis barrier. Those
+  definitions are canonical; this file only points at them.
 - \`parallel-pass-example.md\` for a concrete end-to-end pass after the rules
-  below are clear.
+  below are clear (synced with the \`flow\` skill; not bundled into commands).
 
 ## Quick path
 
@@ -195,13 +214,9 @@ Skip fan-out when:
    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.
+4. Build the pre-fan-out coverage gate defined in \`verification-gates.md\`
+   ("Before fan-out"): total scope, one line per slice with expected count,
+   partition check, and overlap/gap check.
 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.
@@ -211,10 +226,9 @@ Skip fan-out when:
    claims to \`flow-verifier-worker\`.
 9. Run follow-up passes only for material gaps, conflicts, narrowed scope, or
    verification needs.
-10. Apply the manager synthesis barrier: keep only distilled, evidence-backed
-    claims and synthesize one Flow artifact, such as plan fields, completion
-    evidence, review payload, audit report, or candidate patch decision. Do not
-    paste worker handoffs as the user-facing result.
+10. Apply the manager synthesis barrier from \`verification-gates.md\`: keep
+    only distilled, evidence-backed claims and synthesize one Flow artifact.
+    Do not paste worker handoffs as the user-facing result.
 
 ## Modes
 
@@ -298,9 +312,14 @@ 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 state-changing Flow tools, edit .flow/**, own sibling slices, or make the final Flow verdict.
-Return only the matching Flow handoff from handoff-format.md.
+Return only the Flow handoff in this exact shape:
+<matching handoff template copied verbatim from handoff-format.md>
 \`\`\`
 
+Hidden workers cannot load skills or read \`handoff-format.md\` themselves. The
+manager copies the matching handoff template into every worker prompt; a bare
+filename reference is not enough.
+
 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.
@@ -321,11 +340,8 @@ work may be active and that they must not revert unrelated changes.
   any Flow completion call.
 
 When worker results conflict, inspect the underlying artifact directly and rerun
-the smallest check that can settle the disagreement.
-
-The manager synthesis barrier means raw handoffs do not move forward by default.
-Only claims that survived coverage, evidence, confidence, and verifier checks may
-enter the next pass, Flow payload, patch decision, or user-facing answer.
+the smallest check that can settle the disagreement. The manager synthesis
+barrier in \`verification-gates.md\` applies before anything moves forward.
 
 ## Follow-up passes
 
@@ -339,74 +355,84 @@ Start a follow-up pass when first-pass handoffs reveal:
 
 Do not recurse by default. If a worker says it needs another worker, the manager
 decides whether that is a follow-up pass and writes the next bounded prompt.
-`;var O=`# Parallel pass example
+`;
+
+// skills/flow/references/parallel-pass-example.md
+var parallel_pass_example_default = `# Parallel pass example
 
 Use this example after \`parallel-orchestration.md\` when a broad Flow task needs a
-concrete pass shape.
+concrete pass shape. The project below is illustrative; derive your own slices
+from the actual repo during serial orientation.
 
-Goal: review whether bundled Flow command guidance is self-contained and aligned
-with hidden worker permissions.
+Goal: review whether a web app's API error handling is consistent before
+planning a refactor.
 
-Serial orientation: the manager reads \`src/config-shared.ts\` enough to identify
-five public command templates and six hidden worker configs. The manager keeps
-\`flow-status\` local because it is one line and does not need a worker.
+Serial orientation: the manager reads the router entry point enough to identify
+twelve API route modules, one shared error middleware, and an integration test
+directory. The manager keeps the middleware local because it is one file and
+anchors every other judgment.
 
-Coverage gate: ten countable items remain after the local check.
+Coverage gate: twelve countable route modules remain after the local check.
 
-- Slice A: \`flow-auto\`, \`flow-plan\`, and \`flow-run\` templates, expected 3/10.
-- Slice B: \`flow-review\` template plus \`flow-reviewer\` config, expected 2/10.
-- Slice C: remaining hidden worker permission blocks, expected 5/10 after
-  excluding the reviewer already covered by Slice B.
+- Slice A: auth and account routes, expected 4/12.
+- Slice B: billing and subscription routes, expected 3/12.
+- Slice C: remaining content and admin routes, expected 5/12.
 
 Worker prompts:
 
 \`\`\`text
-Overall goal, context only: confirm Flow public commands are self-contained.
+Overall goal, context only: confirm API error handling is consistent.
 Mode: evidence
-Your exact slice: flow-auto, flow-plan, and flow-run templates in src/config-shared.ts.
-Expected coverage: 3/3 templates.
-Do: report bundled sections, setup preflight coverage, and any gaps with file:line evidence.
+Your exact slice: the four auth and account route modules under src/routes/.
+Expected coverage: 4/4 modules.
+Do: report each route's error paths, status codes, and middleware usage with file:line evidence.
 Do not: call state-changing Flow tools, edit .flow/**, own sibling slices, or make the final Flow verdict.
-Return only the matching Flow handoff from handoff-format.md.
+Return only the Flow handoff in this exact shape:
+<matching handoff template copied verbatim from handoff-format.md>
 \`\`\`
 
 \`\`\`text
-Overall goal, context only: confirm Flow review command and hidden reviewer behavior.
+Overall goal, context only: confirm API error handling is consistent.
 Mode: review
-Your exact slice: flow-review command template and flow-reviewer config in src/config-shared.ts.
-Expected coverage: 2/2 surfaces.
+Your exact slice: the three billing and subscription route modules under src/routes/.
+Expected coverage: 3/3 modules.
 Do: separate blocking findings from advisory notes and cite file:line evidence.
 Do not: call state-changing Flow tools, edit .flow/**, own sibling slices, or make the final Flow verdict.
-Return only the matching Flow handoff from handoff-format.md.
+Return only the Flow handoff in this exact shape:
+<matching handoff template copied verbatim from handoff-format.md>
 \`\`\`
 
 \`\`\`text
-Overall goal, context only: confirm hidden worker permissions match the orchestration model.
+Overall goal, context only: confirm API error handling is consistent.
 Mode: audit
-Your exact slice: flow-evidence-worker, flow-validation-worker, flow-audit-worker, flow-candidate-worker, and flow-verifier-worker permissions in src/config-shared.ts.
-Expected coverage: 5/5 worker permission blocks.
-Do: report edit, bash, task, skill, flow_*, and flow_status permissions with evidence.
+Your exact slice: the five content and admin route modules under src/routes/.
+Expected coverage: 5/5 modules.
+Do: check each claimed error path against the shared middleware contract and report divergences with evidence.
 Do not: call state-changing Flow tools, edit .flow/**, own sibling slices, or make the final Flow verdict.
-Return only the matching Flow handoff from handoff-format.md.
+Return only the Flow handoff in this exact shape:
+<matching handoff template copied verbatim from handoff-format.md>
 \`\`\`
 
 Handoff checks: the manager accepts only reports with terminal status, matching
 coverage counts, concrete file:line evidence, confidence tags, and claims inside
-the assigned slice. A claim such as \`[high] validation workers may run commands;
-evidence: src/config-shared.ts:307-320; corroboration: single source\` is usable.
-A claim such as \`[high] permissions look safe; evidence: config reviewed\` is
-dropped or retasked.
+the assigned slice. A claim such as \`[high] billing routes bypass the error
+middleware; evidence: src/routes/billing.ts:88-104; corroboration: single
+source\` is usable. A claim such as \`[high] error handling looks fine; evidence:
+routes reviewed\` is dropped or retasked.
 
 Verifier pass: the manager sends any single-source claim that will enter the
-Flow payload to \`flow-verifier-worker\`, for example: \`C1: validation, audit,
-candidate, and verifier workers have bash ask while evidence and review workers
-have bash deny; sources: src/config-shared.ts worker permission blocks\`.
+Flow payload to \`flow-verifier-worker\`, for example: \`C1: billing and
+subscription routes return raw exceptions while all other routes use the shared
+error envelope; sources: src/routes/billing.ts, src/routes/subscription.ts\`.
 
-Final synthesis: the manager re-reads the relevant config lines, keeps only
-verified or clearly labeled claims, and records one artifact such as a plan
-decision, review payload, or docs patch. Raw handoffs and unverified suggestions
-do not move into the next pass or user-facing answer.
-`;var z=`# Parallel pass patterns
+Final synthesis: the manager re-reads the relevant route and middleware lines,
+keeps only verified or clearly labeled claims, and records one artifact such as
+a plan decision, review payload, or docs patch. Raw handoffs and unverified
+suggestions do not move into the next pass or user-facing answer.
+`;
+
+// skills/flow/references/parallel-pass-patterns.md
+var parallel_pass_patterns_default = `# Parallel pass patterns
 
 Flow uses parallel workers to reduce uncertainty, not to delegate decisions.
 Each pass has a bounded purpose, an explicit coverage rule, and one
@@ -495,16 +521,24 @@ Start a bounded follow-up pass only when:
 - a first pass exposes a narrower implementation or validation slice worth
   isolating.
 
-The manager synthesis barrier applies after every pass: raw handoffs remain
-candidate evidence until the manager checks coverage, resolves conflicts,
-preserves confidence, and records one Flow-owned artifact.
-`;var E='# 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 B=`# Verification gates
+After every pass, the manager synthesis barrier from \`verification-gates.md\`
+applies before any handoff content moves forward.
+`;
+
+// skills/flow/references/recovery-playbook.md
+var recovery_playbook_default = '# 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';
+
+// skills/flow/references/verification-gates.md
+var verification_gates_default = `# 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.
 
+Sections: before fan-out, every handoff, verifier triggers, verification tiers,
+Flow payload acceptance, and manager synthesis barrier.
+
 ## Before fan-out
 
 Run a pre-fan-out gate after serial orientation and before spawning workers:
@@ -609,7 +643,10 @@ 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 V=`---
+`;
+
+// skills/flow/SKILL.md
+var SKILL_default = `---
 name: flow
 description: Run the end-to-end Flow loop for skills-first OpenCode work. Use when a user asks for Flow-guided planning through implementation, resumable autonomous delivery, session status, or completion with validation and review gates.
 ---
@@ -621,10 +658,8 @@ Use Flow as a minimal state ledger, not as a framework. Skills provide judgment;
 ## 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
-   native-load Flow skills in this startup. Public bundled Flow commands may
-   continue with their embedded instructions, but a just-synced native skill can
-   be on disk while unavailable to the running OpenCode process.
+   If the result includes \`setup.skills\`, follow the Skill Availability rules
+   below before loading any Flow skill.
 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. For validation-heavy, regression-sensitive, browser QA, route QA, or failure-prone work, use \`flow-test\` to choose and summarize evidence before completion.
 4. Load \`flow-review\` for the required feature review. The reviewer reports a \`featureReview\` payload; the manager records it inside \`flow_feature_complete\`.
@@ -684,7 +719,10 @@ Planning and running require loaded Flow tools; do not simulate plan approval or
 - 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=`---
+`;
+
+// skills/flow-commit/SKILL.md
+var SKILL_default2 = `---
 name: flow-commit
 description: Prepare safe Git commits and commit messages. Use only when the user asks to inspect, stage, validate, write a commit message, or create a commit; preserves unrelated work and never pushes, amends, rebases, or publishes without explicit authorization.
 ---
@@ -756,18 +794,12 @@ Before commit creation, check the staged diff for:
 - Generated artifacts that are not normally versioned.
 - Package or version metadata drift unrelated to the requested change.
 
-When this repository-local contribution preflight exists, defer to it for staged
-or outgoing validation instead of duplicating its checks:
-
-\`\`\`bash
-.agents/skills/flow-contribution-check/scripts/preflight.sh commit
-\`\`\`
-
-Run it after staging and rerun it after any staging change. Commit mode validates
-the staged boundary for diff hygiene, staged review, and staged secret screening;
-it does not run a whole-worktree gate, choose commit boundaries, or write commit
-messages. If the script is absent, use the repository's documented commit
-preflight from package scripts, AGENTS/docs, or CI guidance.
+If the repository documents its own commit preflight (a package script, a
+repo-local preflight script, or guidance in AGENTS/docs or CI config), defer to
+it for staged validation instead of duplicating its checks. Run it after
+staging and rerun it after any staging change. A staged-boundary preflight
+validates diff hygiene and staged secret screening; it does not run a
+whole-worktree gate, choose commit boundaries, or write commit messages.
 
 Use the repository's documented broad validation gate when a full local check is
 appropriate, such as package scripts, AGENTS/docs, or CI guidance. Treat broad
@@ -800,7 +832,10 @@ Before running \`git commit\`, report:
 
 After a successful commit, report the commit hash and leave push or release
 actions for a separate explicit request.
-`;var G=`# Safe refactor workflow
+`;
+
+// skills/flow-deslop/references/refactor-workflow.md
+var refactor_workflow_default = `# Safe refactor workflow
 
 Refactoring is a behavior-preserving sequence of small changes. This workflow keeps cleanup from becoming an unreviewable rewrite.
 
@@ -842,7 +877,10 @@ 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 M=`# Deslop smell rubric
+`;
+
+// skills/flow-deslop/references/smell-rubric.md
+var smell_rubric_default = `# Deslop smell rubric
 
 Use this rubric to turn vague cleanup instincts into reviewable findings.
 
@@ -876,7 +914,10 @@ 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 L=`---
+`;
+
+// skills/flow-deslop/SKILL.md
+var SKILL_default3 = `---
 name: flow-deslop
 description: Clean up and refactor code with evidence-backed code-smell analysis. Use for AI-slop removal, overengineering reduction, maintainability refactors, behavior-preserving cleanup, duplicated or bloated code, speculative abstractions, dead code, or broad cleanup/refactor review.
 ---
@@ -918,7 +959,10 @@ 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 $=`# Parallel discovery
+`;
+
+// skills/flow-plan/references/parallel-discovery.md
+var parallel_discovery_default = `# 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.
 
@@ -934,26 +978,17 @@ Use its pre-fan-out coverage gate and
 - Risk lenses such as security, persistence, accessibility, migration, or performance.
 - Documentation and operator-contract checks.
 
-## Flow repo default slices
-
-For this repository, good first-pass slices are:
+## Deriving first-pass slices
 
-- 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.
+Derive slices from the repo shape found during the serial orientation pass:
+top-level packages or source directories, the test tree, CI and release
+config, and docs. Name each slice by the paths it owns, for example "runtime:
+\`src/core/**\` plus its tests" or "release contract: CI workflows,
+\`package.json\`, and the changelog".
 
-Treat these as starting points, not a simultaneous coverage map. Before fan-out,
-choose the relevant entries and de-overlap shared docs, skills, or release
-surfaces in the coverage gate.
+Treat derived slices as starting points, not a simultaneous coverage map.
+Before fan-out, choose the relevant entries and de-overlap shared docs,
+config, or release surfaces in the coverage gate.
 
 ## Coverage gate
 
@@ -966,8 +1001,8 @@ state the completeness rule, such as "all changed files plus callers."
 
 \`\`\`text
 Inspect <slice> for <goal>. Read-only. Do not edit files or call
-state-changing Flow tools. Return the evidence/review/validation/audit handoff
-shape from ../../flow/references/handoff-format.md.
+state-changing Flow tools. Return only the Flow handoff in this exact shape:
+<matching handoff template copied verbatim from handoff-format.md>
 \`\`\`
 
 For validation-oriented discovery:
@@ -975,11 +1010,14 @@ For validation-oriented discovery:
 \`\`\`text
 Inspect <slice> for validation risk. Read-only. Do not edit files or call
 state-changing 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.
+include raw output only for commands you actually ran. Return only the Flow
+handoff in this exact shape:
+<matching handoff template copied verbatim from handoff-format.md>
 \`\`\`
 
+Workers cannot read reference files themselves; paste the matching handoff
+template from \`../../flow/references/handoff-format.md\` into the prompt.
+
 ## Synthesis
 
 Convert only evidence-backed work into plan fields:
@@ -994,7 +1032,10 @@ If workers disagree, inspect the source artifact yourself. If a candidate findin
 Apply the manager synthesis barrier from
 \`../../flow/references/verification-gates.md\`: only distilled, evidence-backed
 claims become plan fields.
-`;var Q=`# Planning examples
+`;
+
+// skills/flow-plan/references/planning-examples.md
+var planning_examples_default = `# Planning examples
 
 ## Rate limiting feature set
 
@@ -1079,7 +1120,10 @@ Better plan:
 - Validation that only says "manual testing".
 - Targets that name the entire repo.
 - Features with hidden dependencies instead of \`dependsOn\`.
-`;var K=`---
+`;
+
+// skills/flow-plan/SKILL.md
+var SKILL_default4 = `---
 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."
 ---
@@ -1094,14 +1138,13 @@ 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.
+- Helper rule: when a named helper skill is unavailable, record a planning gap
+  and keep the corresponding claims conservative instead of simulating its
+  checks.
 - For complex validation, regression-sensitive changes, browser QA, route QA,
-  failure-prone checks, or uncertain test strategy, load \`flow-test\`. If it is
-  unavailable, record a planning gap and keep validation claims conservative.
-- 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.
+  failure-prone checks, or uncertain test strategy, load \`flow-test\`.
+- 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
@@ -1149,7 +1192,10 @@ 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 Y=`# Review rubric
+`;
+
+// skills/flow-review/references/review-rubric.md
+var review_rubric_default = `# Review rubric
 
 Use this to decide whether a \`featureReview\` or \`finalReview\` payload may pass.
 
@@ -1237,7 +1283,10 @@ 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 X=`---
+`;
+
+// skills/flow-review/SKILL.md
+var SKILL_default5 = `---
 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."
 ---
@@ -1250,15 +1299,30 @@ 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.
 
+## Execution contexts
+
+These instructions run in two contexts, and only one of them can load helpers:
+
+- **Manager context**: the manager reviews inside \`flow-run\` or \`flow-auto\`
+  before recording evidence. The manager may load helper skills and fan out
+  read-only workers.
+- **Hidden reviewer context**: \`/flow-review\` runs as the \`flow-reviewer\`
+  subagent, whose permissions deny skill loading, shell commands, and
+  subagents. In this context, skip every "load" and "fan out" instruction
+  below: judge from the diff, the plan fields, and the recorded validation
+  evidence, and record a coverage gap for any judgment that would have needed
+  a helper skill or a command run.
+
 ## 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 \`flow-test\` for validation-heavy, regression-sensitive, browser QA, or
-  unclear coverage reviews. If it is unavailable, record a coverage gap and
-  treat missing validation evidence as a gap or blocker based on user impact.
+- In manager context, load \`flow-test\` for validation-heavy,
+  regression-sensitive, browser QA, or unclear coverage reviews. If it is
+  unavailable or you are the hidden reviewer, record a coverage gap and treat
+  missing validation evidence as a gap or blocker based on user impact.
 - Load \`references/review-rubric.md\` for severity, depth, and payload shape.
 
 ## Feature Review Depth
@@ -1296,18 +1360,23 @@ 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. 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.
+- Cleanup/refactor: in manager context, load \`flow-deslop\`; verify the smell was real, refutation paths were checked, and behavior was preserved. If it is unavailable or you are the hidden reviewer, record a coverage gap instead of approving cleanup claims.
+- UI/frontend: in manager context, load \`flow-ui-quality\`; verify state coverage and visual evidence when a local target was available. If it is unavailable or you are the hidden reviewer, 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.
-  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.
+- Large reviews (manager context only): 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. The hidden
+  reviewer cannot spawn workers; it reviews its assigned scope directly and
+  reports coverage gaps for the rest.
 
 Never approve to unblock completion, fix findings in the review pass, or vouch for validation you did not inspect.
-`;var J=`# Audit findings rubric
+`;
+
+// skills/flow-run/references/audit-rubric.md
+var audit_rubric_default = `# 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.
 
@@ -1360,7 +1429,10 @@ 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 Z=`# Validation evidence rubric
+`;
+
+// skills/flow-run/references/validation-rubric.md
+var validation_rubric_default = `# Validation evidence rubric
 
 Use this before recording \`flow_feature_complete\`.
 
@@ -1417,7 +1489,10 @@ 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 H=`---
+`;
+
+// skills/flow-run/SKILL.md
+var SKILL_default6 = `---
 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."
 ---
@@ -1433,9 +1508,10 @@ If \`flow_run_start\` is unavailable, stop and tell the user to check that \`ope
 - 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.
+- Helper rule: when a named helper skill is unavailable, record the gap and
+  keep the corresponding claims conservative instead of simulating its checks.
+- Load \`flow-deslop\` for cleanup/refactor features.
+- Load \`flow-ui-quality\` for frontend, UX, responsive, accessibility, or visual work.
 
 ## Implement
 
@@ -1453,8 +1529,7 @@ If \`flow_run_start\` is unavailable, stop and tell the user to check that \`ope
 
 - For complex validation, regression-sensitive changes, browser QA, route QA,
   failure-prone checks, unclear coverage, exploratory QA, or
-  \`validationRun\` summarization, load \`flow-test\`. If it is unavailable, record
-  the coverage gap and keep validation claims conservative.
+  \`validationRun\` summarization, load \`flow-test\` (helper rule applies).
 - 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.
@@ -1504,7 +1579,10 @@ Complete with:
 \`\`\`
 
 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 ee=`---
+`;
+
+// skills/flow-test/SKILL.md
+var SKILL_default7 = `---
 name: flow-test
 description: Test, validate, make test plans, triage failures, and gather Flow validation evidence. Use when selecting checks, running tests, running browser QA for UI changes, classifying failures, or preparing validationRun evidence for flow_feature_complete.
 ---
@@ -1628,7 +1706,10 @@ covered. Static inspection alone is a gap for behavioral changes.
 
 Never relabel a failed command as passed, invent output, or use "not run" as
 completion evidence.
-`;var ae=`# UI quality rubric
+`;
+
+// skills/flow-ui-quality/references/ui-rubric.md
+var ui_rubric_default = `# UI quality rubric
 
 Use this rubric for frontend planning, implementation, and review.
 
@@ -1672,7 +1753,10 @@ 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 te=`# Visual verification workflow
+`;
+
+// skills/flow-ui-quality/references/visual-verification.md
+var visual_verification_default = `# 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.
 
@@ -1712,7 +1796,10 @@ 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 oe=`---
+`;
+
+// skills/flow-ui-quality/SKILL.md
+var SKILL_default8 = `---
 name: flow-ui-quality
 description: Review and improve frontend UI quality for Flow work. Use for UX/UI design, frontend polish, visual quality review, responsive and accessible interfaces, interaction states, screenshots, browser-verified UI work, and avoiding generic AI-generated UI.
 ---
@@ -1760,23 +1847,580 @@ 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 k=[{name:"flow",files:[{relativePath:"SKILL.md",content:V},{relativePath:"references/recovery-playbook.md",content:E},{relativePath:"references/parallel-orchestration.md",content:W},{relativePath:"references/parallel-pass-patterns.md",content:z},{relativePath:"references/parallel-pass-example.md",content:O},{relativePath:"references/handoff-format.md",content:S},{relativePath:"references/verification-gates.md",content:B}]},{name:"flow-plan",files:[{relativePath:"SKILL.md",content:K},{relativePath:"references/planning-examples.md",content:Q},{relativePath:"references/parallel-discovery.md",content:$}]},{name:"flow-run",files:[{relativePath:"SKILL.md",content:H},{relativePath:"references/validation-rubric.md",content:Z},{relativePath:"references/audit-rubric.md",content:J}]},{name:"flow-test",files:[{relativePath:"SKILL.md",content:ee}]},{name:"flow-review",files:[{relativePath:"SKILL.md",content:X},{relativePath:"references/review-rubric.md",content:Y}]},{name:"flow-deslop",files:[{relativePath:"SKILL.md",content:L},{relativePath:"references/smell-rubric.md",content:M},{relativePath:"references/refactor-workflow.md",content:G}]},{name:"flow-ui-quality",files:[{relativePath:"SKILL.md",content:oe},{relativePath:"references/ui-rubric.md",content:ae},{relativePath:"references/visual-verification.md",content:te}]},{name:"flow-commit",files:[{relativePath:"SKILL.md",content:N}]}];var D=".flow-skill-version";function _(){return process.env.HOME??process.env.USERPROFILE??""}function T(e=_()){return h(e,".config","opencode","skills")}function v(e){return ze("sha256").update(e).digest("hex")}function F(e,a){return[`version=${a}`,...e.files.map((t)=>`file=${t.relativePath} sha256=${v(t.content)}`),""].join(`
-`)}async function f(e){try{return await Be(e,"utf8")}catch(a){if(a.code==="ENOENT")return null;throw a}}function P(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 Le(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 b(e,a){let t=Ge(h(e,...a.split("/")));if(t!==e&&t.startsWith(`${e}${Me}`))return t;throw Error(`Unsafe skill file path '${a}'.`)}async function re(e,a){let t=`${e}.backup.${v(a).slice(0,12)}`;for(let r=0;;r+=1){let n=r===0?t:`${t}.${r}`;try{return await x(n,a,{encoding:"utf8",flag:"wx"}),n}catch(s){if(s.code==="EEXIST")continue;throw s}}}async function $e(e,a,t){let r=h(t,e.name),n=h(r,D),s=await f(n),d=P(s);if(await f(h(r,"SKILL.md"))!==null&&s===null)return{name:e.name,action:"skipped_foreign"};let c=!1,l=[],y=new Set(e.files.map((i)=>i.relativePath));for(let i of e.files){let u=b(r,i.relativePath),p=await f(u);if(p===i.content)continue;c=!0;let g=d.get(i.relativePath);if(p!==null&&(g?v(p)!==g:s!==null))l.push(await re(u,p))}for(let[i,u]of d){if(y.has(i))continue;let p=b(r,i),g=await f(p);if(g===null)continue;if(c=!0,v(g)!==u)l.push(await re(p,g));await ie(p,{force:!0})}if(!c&&s===F(e,a))return{name:e.name,action:"unchanged"};if(!c)return await x(n,F(e,a),"utf8"),{name:e.name,action:"marker_updated"};let o=s!==null;for(let i of e.files){let u=b(r,i.relativePath);await Ee(Ne(u),{recursive:!0}),await x(u,i.content,"utf8")}return await x(n,F(e,a),"utf8"),{name:e.name,action:l.length>0?"updated_with_backup":o?"updated":"installed",...l.length>0?{backupPaths:l}:{}}}function Qe(){return k.map((e)=>e.name)}function Ke(e){return`npx -y opencode-plugin-flow@${e} doctor`}function I(){if(process.env.npm_package_version)return process.env.npm_package_version;try{let e=Ve(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 ce(e,a=_()){let t=T(a);return Promise.all(k.map((r)=>$e(r,e,t)))}async function de(e=I(),a=_()){let t=T(a),r=new Set(Qe()),n=await Promise.all(k.map(async(o)=>{let i=h(t,o.name),u=await f(h(i,D)),p=Le(u),g=P(u);if(await f(h(i,"SKILL.md"))===null)return{name:o.name,path:i,status:"missing",markerVersion:p,missingFiles:o.files.map((w)=>w.relativePath),editedFiles:[],outdatedFiles:[]};if(u===null)return{name:o.name,path:i,status:"foreign",markerVersion:p,missingFiles:[],editedFiles:[],outdatedFiles:[]};let U=[],A=[],C=[];for(let w of o.files){let q=await f(b(i,w.relativePath));if(q===null){U.push(w.relativePath);continue}if(q===w.content)continue;let j=g.get(w.relativePath);if(j&&v(q)!==j){A.push(w.relativePath);continue}C.push(w.relativePath)}let he=u!==F(o,e),fe=U.length>0?"incomplete":A.length>0?"edited":he||C.length>0?"outdated":"ok";return{name:o.name,path:i,status:fe,markerVersion:p,missingFiles:U,editedFiles:A,outdatedFiles:C}})),s=[];try{s=await ne(t)}catch(o){if(o.code!=="ENOENT")throw o}let d=s.filter((o)=>(o==="flow"||o.startsWith("flow-"))&&!r.has(o)).map((o)=>h(t,o)),m=n.filter((o)=>["missing","incomplete","outdated"].includes(o.status)).map((o)=>o.name),c=n.filter((o)=>["foreign","edited"].includes(o.status)).map((o)=>o.name),l=c.length>0,y=m.length>0;return{status:l?"action_required":y?"sync_required":"ok",version:e,root:t,expectedSkills:[...r],skills:n,syncRequiredSkills:m,actionRequiredSkills:c,unmanagedFlowSkills:d}}function se(e,a,t){if(t.length===0)return;e.push(`- ${a}: ${t.join(", ")}`)}function le(e){let a=["Flow doctor",`- status: ${e.status}`,`- plugin version: ${e.version}`,`- skills root: ${e.root}`,`- expected skills: ${e.expectedSkills.join(", ")}`];se(a,"startup sync can install/update",e.syncRequiredSkills),se(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: ${Ke(e.version)}`),`${a.join(`
+`;
+
+// src/distribution/flow-skill-definitions.ts
+var FLOW_SKILL_DEFINITIONS = [
+  {
+    name: "flow",
+    files: [
+      { relativePath: "SKILL.md", content: SKILL_default },
+      {
+        relativePath: "references/recovery-playbook.md",
+        content: recovery_playbook_default
+      },
+      {
+        relativePath: "references/parallel-orchestration.md",
+        content: parallel_orchestration_default
+      },
+      {
+        relativePath: "references/parallel-pass-patterns.md",
+        content: parallel_pass_patterns_default
+      },
+      {
+        relativePath: "references/parallel-pass-example.md",
+        content: parallel_pass_example_default
+      },
+      {
+        relativePath: "references/handoff-format.md",
+        content: handoff_format_default
+      },
+      {
+        relativePath: "references/verification-gates.md",
+        content: verification_gates_default
+      }
+    ]
+  },
+  {
+    name: "flow-plan",
+    files: [
+      { relativePath: "SKILL.md", content: SKILL_default4 },
+      {
+        relativePath: "references/planning-examples.md",
+        content: planning_examples_default
+      },
+      {
+        relativePath: "references/parallel-discovery.md",
+        content: parallel_discovery_default
+      }
+    ]
+  },
+  {
+    name: "flow-run",
+    files: [
+      { relativePath: "SKILL.md", content: SKILL_default6 },
+      {
+        relativePath: "references/validation-rubric.md",
+        content: validation_rubric_default
+      },
+      {
+        relativePath: "references/audit-rubric.md",
+        content: audit_rubric_default
+      }
+    ]
+  },
+  {
+    name: "flow-test",
+    files: [{ relativePath: "SKILL.md", content: SKILL_default7 }]
+  },
+  {
+    name: "flow-review",
+    files: [
+      { relativePath: "SKILL.md", content: SKILL_default5 },
+      {
+        relativePath: "references/review-rubric.md",
+        content: review_rubric_default
+      }
+    ]
+  },
+  {
+    name: "flow-deslop",
+    files: [
+      { relativePath: "SKILL.md", content: SKILL_default3 },
+      {
+        relativePath: "references/smell-rubric.md",
+        content: smell_rubric_default
+      },
+      {
+        relativePath: "references/refactor-workflow.md",
+        content: refactor_workflow_default
+      }
+    ]
+  },
+  {
+    name: "flow-ui-quality",
+    files: [
+      { relativePath: "SKILL.md", content: SKILL_default8 },
+      {
+        relativePath: "references/ui-rubric.md",
+        content: ui_rubric_default
+      },
+      {
+        relativePath: "references/visual-verification.md",
+        content: visual_verification_default
+      }
+    ]
+  },
+  {
+    name: "flow-commit",
+    files: [{ relativePath: "SKILL.md", content: SKILL_default2 }]
+  }
+];
+
+// src/distribution/sync.ts
+var MARKER_FILENAME = ".flow-skill-version";
+function homeDir() {
+  return process.env.HOME ?? process.env.USERPROFILE ?? homedir();
+}
+function resolveFlowSkillsRoot(home = homeDir()) {
+  return join(home, ".config", "opencode", "skills");
+}
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+function markerFor(definition, version) {
+  return [
+    `version=${version}`,
+    ...definition.files.map((file) => `file=${file.relativePath} sha256=${sha256(file.content)}`),
+    ""
+  ].join(`
+`);
+}
+async function optionalRead(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return null;
+    throw error;
+  }
+}
+function parseMarkerFiles(content) {
+  const files = new Map;
+  if (!content)
+    return files;
+  for (const line of content.split(/\r?\n/)) {
+    const match = /^file=(.+) sha256=([a-f0-9]{64})$/.exec(line) ?? /^file=(.+)=sha256:([a-f0-9]{64})$/.exec(line);
+    if (match?.[1] && match[2])
+      files.set(match[1], match[2]);
+    const topLevelHash = /^hash=sha256:([a-f0-9]{64})$/.exec(line);
+    if (topLevelHash?.[1] && !files.has("SKILL.md")) {
+      files.set("SKILL.md", topLevelHash[1]);
+    }
+  }
+  return files;
+}
+function parseMarkerVersion(content) {
+  if (!content)
+    return null;
+  for (const line of content.split(/\r?\n/)) {
+    const match = /^version=(.+)$/.exec(line);
+    if (match?.[1])
+      return match[1];
+  }
+  return null;
+}
+function resolveSkillFile(folder, relativePath) {
+  const resolved = normalize(join(folder, ...relativePath.split("/")));
+  if (resolved !== folder && resolved.startsWith(`${folder}${sep}`)) {
+    return resolved;
+  }
+  throw new Error(`Unsafe skill file path '${relativePath}'.`);
+}
+async function writeBackup(path, content) {
+  const basePath = `${path}.backup.${sha256(content).slice(0, 12)}`;
+  for (let index = 0;; index += 1) {
+    const backupPath = index === 0 ? basePath : `${basePath}.${index}`;
+    try {
+      await writeFile(backupPath, content, { encoding: "utf8", flag: "wx" });
+      return backupPath;
+    } catch (error) {
+      if (error.code === "EEXIST")
+        continue;
+      throw error;
+    }
+  }
+}
+async function syncSkill(definition, version, root) {
+  const folder = join(root, definition.name);
+  const markerPath = join(folder, MARKER_FILENAME);
+  const markerContent = await optionalRead(markerPath);
+  const existingMarkerHashes = parseMarkerFiles(markerContent);
+  const existingSkill = await optionalRead(join(folder, "SKILL.md"));
+  if (existingSkill !== null && markerContent === null) {
+    return { name: definition.name, action: "skipped_foreign" };
+  }
+  let changed = false;
+  const backupPaths = [];
+  const currentRelativePaths = new Set(definition.files.map((file) => file.relativePath));
+  for (const file of definition.files) {
+    const path = resolveSkillFile(folder, file.relativePath);
+    const existing = await optionalRead(path);
+    if (existing === file.content)
+      continue;
+    changed = true;
+    const recordedHash = existingMarkerHashes.get(file.relativePath);
+    const userEdited = existing !== null && (recordedHash ? sha256(existing) !== recordedHash : markerContent !== null);
+    if (userEdited) {
+      backupPaths.push(await writeBackup(path, existing));
+    }
+  }
+  for (const [relativePath, recordedHash] of existingMarkerHashes) {
+    if (currentRelativePaths.has(relativePath))
+      continue;
+    const path = resolveSkillFile(folder, relativePath);
+    const existing = await optionalRead(path);
+    if (existing === null)
+      continue;
+    changed = true;
+    if (sha256(existing) !== recordedHash) {
+      backupPaths.push(await writeBackup(path, existing));
+    }
+    await rm(path, { force: true });
+  }
+  if (!changed && markerContent === markerFor(definition, version)) {
+    return { name: definition.name, action: "unchanged" };
+  }
+  if (!changed) {
+    await writeFile(markerPath, markerFor(definition, version), "utf8");
+    return { name: definition.name, action: "marker_updated" };
+  }
+  const managedSkillExists = markerContent !== null;
+  for (const file of definition.files) {
+    const path = resolveSkillFile(folder, file.relativePath);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, file.content, "utf8");
+  }
+  await writeFile(markerPath, markerFor(definition, version), "utf8");
+  return {
+    name: definition.name,
+    action: backupPaths.length > 0 ? "updated_with_backup" : managedSkillExists ? "updated" : "installed",
+    ...backupPaths.length > 0 ? { backupPaths } : {}
+  };
+}
+function expectedSkillNames() {
+  return FLOW_SKILL_DEFINITIONS.map((definition) => definition.name);
+}
+function formatFlowDoctorCommand(version) {
+  const pin = version === "0.0.0" ? "latest" : version;
+  return `npx -y opencode-plugin-flow@${pin} doctor`;
+}
+function resolveFlowPluginVersion() {
+  if (process.env.npm_package_version)
+    return process.env.npm_package_version;
+  try {
+    const require2 = createRequire(import.meta.url);
+    for (const path of ["../package.json", "../../package.json"]) {
+      try {
+        const manifest = require2(path);
+        if (manifest.version)
+          return manifest.version;
+      } catch {}
+    }
+  } catch {}
+  return "0.0.0";
+}
+async function syncFlowSkills(version, home = homeDir()) {
+  const root = resolveFlowSkillsRoot(home);
+  return Promise.all(FLOW_SKILL_DEFINITIONS.map((definition) => syncSkill(definition, version, root)));
+}
+async function inspectFlowSkillInstall(version = resolveFlowPluginVersion(), home = homeDir()) {
+  const root = resolveFlowSkillsRoot(home);
+  const expected = new Set(expectedSkillNames());
+  const skills = await Promise.all(FLOW_SKILL_DEFINITIONS.map(async (definition) => {
+    const folder = join(root, definition.name);
+    const markerContent = await optionalRead(join(folder, MARKER_FILENAME));
+    const markerVersion = parseMarkerVersion(markerContent);
+    const markerHashes = parseMarkerFiles(markerContent);
+    const existingSkill = await optionalRead(join(folder, "SKILL.md"));
+    if (existingSkill === null) {
+      return {
+        name: definition.name,
+        path: folder,
+        status: "missing",
+        markerVersion,
+        missingFiles: definition.files.map((file) => file.relativePath),
+        editedFiles: [],
+        outdatedFiles: []
+      };
+    }
+    if (markerContent === null) {
+      return {
+        name: definition.name,
+        path: folder,
+        status: "foreign",
+        markerVersion,
+        missingFiles: [],
+        editedFiles: [],
+        outdatedFiles: []
+      };
+    }
+    const missingFiles = [];
+    const editedFiles = [];
+    const outdatedFiles = [];
+    for (const file of definition.files) {
+      const existing = await optionalRead(resolveSkillFile(folder, file.relativePath));
+      if (existing === null) {
+        missingFiles.push(file.relativePath);
+        continue;
+      }
+      if (existing === file.content)
+        continue;
+      const recordedHash = markerHashes.get(file.relativePath);
+      if (recordedHash && sha256(existing) !== recordedHash) {
+        editedFiles.push(file.relativePath);
+        continue;
+      }
+      outdatedFiles.push(file.relativePath);
+    }
+    const markerDrift = markerContent !== markerFor(definition, version);
+    const status = missingFiles.length > 0 ? "incomplete" : editedFiles.length > 0 ? "edited" : markerDrift || outdatedFiles.length > 0 ? "outdated" : "ok";
+    return {
+      name: definition.name,
+      path: folder,
+      status,
+      markerVersion,
+      missingFiles,
+      editedFiles,
+      outdatedFiles
+    };
+  }));
+  let entries = [];
+  try {
+    entries = await readdir(root);
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+  }
+  const unmanagedFlowSkills = entries.filter((name) => (name === "flow" || name.startsWith("flow-")) && !expected.has(name)).map((name) => join(root, name));
+  const syncRequiredSkills = skills.filter((skill) => ["missing", "incomplete", "outdated"].includes(skill.status)).map((skill) => skill.name);
+  const actionRequiredSkills = skills.filter((skill) => ["foreign", "edited"].includes(skill.status)).map((skill) => skill.name);
+  const actionRequired = actionRequiredSkills.length > 0;
+  const syncRequired = syncRequiredSkills.length > 0;
+  return {
+    status: actionRequired ? "action_required" : syncRequired ? "sync_required" : "ok",
+    version,
+    root,
+    expectedSkills: [...expected],
+    skills,
+    syncRequiredSkills,
+    actionRequiredSkills,
+    unmanagedFlowSkills
+  };
+}
+function appendSkillList(lines, label, skills) {
+  if (skills.length === 0)
+    return;
+  lines.push(`- ${label}: ${skills.join(", ")}`);
+}
+function formatFlowSkillDoctor(report) {
+  const lines = [
+    "Flow doctor",
+    `- status: ${report.status}`,
+    `- plugin version: ${report.version}`,
+    `- skills root: ${report.root}`,
+    `- expected skills: ${report.expectedSkills.join(", ")}`
+  ];
+  appendSkillList(lines, "startup sync can install/update", report.syncRequiredSkills);
+  appendSkillList(lines, "needs user decision", report.actionRequiredSkills);
+  lines.push("", "Skills:");
+  for (const skill of report.skills) {
+    lines.push(`- ${skill.name}: ${skill.status} (${skill.path})${skill.markerVersion ? ` marker=${skill.markerVersion}` : ""}`);
+    if (skill.missingFiles.length > 0) {
+      lines.push(`  missing: ${skill.missingFiles.join(", ")}`);
+    }
+    if (skill.editedFiles.length > 0) {
+      lines.push(`  edited: ${skill.editedFiles.join(", ")}`);
+    }
+    if (skill.outdatedFiles.length > 0) {
+      lines.push(`  outdated: ${skill.outdatedFiles.join(", ")}`);
+    }
+  }
+  if (report.unmanagedFlowSkills.length > 0) {
+    lines.push("", "Unmanaged Flow-like skill folders:");
+    for (const path of report.unmanagedFlowSkills)
+      lines.push(`- ${path}`);
+  }
+  lines.push("", "Recommendation:");
+  if (report.status === "ok") {
+    lines.push("- Flow skills are present and current.");
+  } else if (report.status === "sync_required") {
+    lines.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 {
+    lines.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.");
+  }
+  lines.push(`- Details command: ${formatFlowDoctorCommand(report.version)}`);
+  return `${lines.join(`
 `)}
-`}async function ue(e=_()){let a=T(e),t=[],r=[],n;try{n=await ne(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=h(a,s),m=await f(h(d,D));if(m===null){r.push(d);continue}let c=P(m),l=!1;for(let[y,o]of c){let i=await f(b(d,y));if(i!==null&&v(i)!==o){l=!0;break}}if(l){r.push(d);continue}await ie(d,{recursive:!0,force:!0}),t.push(d)}return{removed:t,kept:r}}function R(){return["usage: opencode-plugin-flow <doctor|sync|uninstall> [options]","","commands:","  doctor              Inspect managed Flow skills","  sync                Install or refresh managed Flow skills","  uninstall           Remove pristine Flow-owned managed skills","","doctor options:","  --json              Write the doctor report as JSON","  --check, --strict   Exit nonzero when doctor status is not ok","","global options:","  --help              Show this help","  --version           Print the plugin version"].join(`
-`)}function Ye(e,a){return e.every((t)=>a.has(t))}function Xe(e,a){if(a.json){process.stdout.write(`${JSON.stringify(e,null,2)}
-`);return}process.stdout.write(le(e))}async function Je(e){let a=e[2],t=e.slice(3);if(a==="--help"||a==="-h"){process.stdout.write(`${R()}
-`);return}if(a==="--version"||a==="-v"){process.stdout.write(`${I()}
-`);return}if(a!=="uninstall"&&a!=="doctor"&&a!=="sync"){process.stderr.write(`${R()}
-`),process.exitCode=2;return}if(a==="doctor"){if(!Ye(t,new Set(["--json","--check","--strict"]))){process.stderr.write(`${R()}
-`),process.exitCode=2;return}let s=await de();if(Xe(s,{json:t.includes("--json")}),(s.status==="sync_required"||s.status==="action_required")&&(t.includes("--check")||t.includes("--strict")))process.exitCode=1;return}if(t.length>0){process.stderr.write(`${R()}
-`),process.exitCode=2;return}if(a==="sync"){let n=I(),s=await ce(n),d=s.filter((c)=>["installed","updated","updated_with_backup"].includes(c.action)),m=s.filter((c)=>c.action==="skipped_foreign");process.stdout.write(`Flow skill sync (${n})
-`);for(let c of s){process.stdout.write(`- ${c.name}: ${c.action}
-`);for(let l of c.backupPaths??[])process.stdout.write(`  backup: ${l}
-`)}if(d.length>0)process.stdout.write(`Restart OpenCode so the refreshed skill registry is used.
-`);if(m.length>0)process.stdout.write(`Some managed skill folders are user-owned or edited; run doctor for repair guidance.
-`);return}let r=await ue();for(let n of r.removed)process.stdout.write(`Removed Flow skill: ${n}
-`);for(let n of r.kept)process.stdout.write(`Kept non-Flow or user-edited skill: ${n}
-`);process.stdout.write(`Remove opencode-plugin-flow from your OpenCode plugin config and restart OpenCode.
-`)}Je(process.argv).catch((e)=>{process.stderr.write(`${e instanceof Error?e.message:String(e)}
-`),process.exitCode=1});
+`;
+}
+async function listSkillFolderFiles(folder) {
+  const entries = await readdir(folder, {
+    recursive: true,
+    withFileTypes: true
+  });
+  return entries.filter((entry) => entry.isFile()).map((entry) => join(entry.parentPath, entry.name).slice(folder.length + 1).split(sep).join("/"));
+}
+async function isPristineManagedFolder(folder, markerContent) {
+  const hashes = parseMarkerFiles(markerContent);
+  if (hashes.size === 0)
+    return false;
+  for (const relativePath of await listSkillFolderFiles(folder)) {
+    if (relativePath === MARKER_FILENAME)
+      continue;
+    const recordedHash = hashes.get(relativePath);
+    if (recordedHash === undefined)
+      return false;
+    const content = await optionalRead(resolveSkillFile(folder, relativePath));
+    if (content === null || sha256(content) !== recordedHash)
+      return false;
+  }
+  return true;
+}
+async function uninstallFlowSkills(home = homeDir(), options = {}) {
+  const root = resolveFlowSkillsRoot(home);
+  const removed = [];
+  const kept = [];
+  let entries;
+  try {
+    entries = await readdir(root);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { removed, kept };
+    }
+    throw error;
+  }
+  for (const name of entries) {
+    if (name !== "flow" && !name.startsWith("flow-"))
+      continue;
+    const folder = join(root, name);
+    const markerContent = await optionalRead(join(folder, MARKER_FILENAME));
+    if (markerContent === null || !await isPristineManagedFolder(folder, markerContent)) {
+      kept.push(folder);
+      continue;
+    }
+    if (!options.dryRun) {
+      await rm(folder, { recursive: true, force: true });
+    }
+    removed.push(folder);
+  }
+  return { removed, kept };
+}
+
+// src/cli.ts
+function usage() {
+  return [
+    "usage: opencode-plugin-flow <doctor|sync|uninstall> [options]",
+    "",
+    "commands:",
+    "  doctor              Inspect managed Flow skills",
+    "  sync                Install or refresh managed Flow skills",
+    "  uninstall           Remove pristine Flow-owned managed skills",
+    "",
+    "doctor options:",
+    "  --json              Write the doctor report as JSON",
+    "  --check, --strict   Exit nonzero when doctor status is not ok",
+    "",
+    "uninstall options:",
+    "  --dry-run           Preview removals without deleting anything",
+    "",
+    "global options:",
+    "  --help              Show this help",
+    "  --version           Print the plugin version"
+  ].join(`
+`);
+}
+function hasOnlyKnownFlags(flags, known) {
+  return flags.every((flag) => known.has(flag));
+}
+function writeDoctorReport(report, options) {
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}
+`);
+    return;
+  }
+  process.stdout.write(formatFlowSkillDoctor(report));
+}
+async function main(argv) {
+  const command = argv[2];
+  const flags = argv.slice(3);
+  if (command === "--help" || command === "-h") {
+    process.stdout.write(`${usage()}
+`);
+    return;
+  }
+  if (command === "--version" || command === "-v") {
+    process.stdout.write(`${resolveFlowPluginVersion()}
+`);
+    return;
+  }
+  if (command !== "uninstall" && command !== "doctor" && command !== "sync") {
+    process.stderr.write(`${usage()}
+`);
+    process.exitCode = 2;
+    return;
+  }
+  if (command === "doctor") {
+    const knownDoctorFlags = new Set(["--json", "--check", "--strict"]);
+    if (!hasOnlyKnownFlags(flags, knownDoctorFlags)) {
+      process.stderr.write(`${usage()}
+`);
+      process.exitCode = 2;
+      return;
+    }
+    const report = await inspectFlowSkillInstall();
+    writeDoctorReport(report, { json: flags.includes("--json") });
+    if ((report.status === "sync_required" || report.status === "action_required") && (flags.includes("--check") || flags.includes("--strict"))) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+  const knownUninstallFlags = new Set(["--dry-run"]);
+  if (command === "uninstall" && !hasOnlyKnownFlags(flags, knownUninstallFlags)) {
+    process.stderr.write(`${usage()}
+`);
+    process.exitCode = 2;
+    return;
+  }
+  if (command === "sync" && flags.length > 0) {
+    process.stderr.write(`${usage()}
+`);
+    process.exitCode = 2;
+    return;
+  }
+  if (command === "sync") {
+    const version = resolveFlowPluginVersion();
+    const results = await syncFlowSkills(version);
+    const changed = results.filter((result2) => ["installed", "updated", "updated_with_backup"].includes(result2.action));
+    const actionRequired = results.filter((result2) => result2.action === "skipped_foreign");
+    process.stdout.write(`Flow skill sync (${version})
+`);
+    for (const result2 of results) {
+      process.stdout.write(`- ${result2.name}: ${result2.action}
+`);
+      for (const backupPath of result2.backupPaths ?? []) {
+        process.stdout.write(`  backup: ${backupPath}
+`);
+      }
+    }
+    if (changed.length > 0) {
+      process.stdout.write(`Restart OpenCode so the refreshed skill registry is used.
+`);
+    }
+    if (actionRequired.length > 0) {
+      process.stdout.write(`Some managed skill folders are user-owned or edited; run doctor for repair guidance.
+`);
+    }
+    return;
+  }
+  const dryRun = flags.includes("--dry-run");
+  const result = await uninstallFlowSkills(undefined, { dryRun });
+  for (const path of result.removed) {
+    process.stdout.write(`${dryRun ? "Would remove" : "Removed"} Flow skill: ${path}
+`);
+  }
+  for (const path of result.kept) {
+    process.stdout.write(`Kept non-Flow or user-edited skill: ${path}
+`);
+  }
+  process.stdout.write(dryRun ? `Dry run: no files were removed.
+` : `Remove opencode-plugin-flow from your OpenCode plugin config and restart OpenCode.
+`);
+}
+main(process.argv).catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+  process.exitCode = 1;
+});
+
+//# debugId=8ECEECE32879216C64756E2164756E21