opencode-plugin-flow 4.3.9 → 5.0.0

package/dist/cli.js

@@ -1,2772 +1,347 @@
 #!/usr/bin/env node
 
-// src/distribution/sync.ts
+// src/distribution/legacy-cleanup.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."
-
-Empty or unstructured worker output is a failed handoff. If the worker cannot
-cover the assigned scope, verify the evidence, or satisfy the handoff shape, it
-must return \`Status: blocked\` with the missing elements, and the manager must
-not treat the slice as complete.
-
-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
-  immaterial to the assigned question.
-- \`partial\`: useful evidence was gathered, but material assigned scope remains
-  unchecked or unresolved.
-- \`blocked\`: the worker cannot answer the assigned question without missing
-  access, input, dependencies, or manager clarification.
-
-## 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>
-
-## Pass metadata
-- Pass id: <stable pass id from the manifest>
-- Manifest row id: <row id from the manifest>
-- Depends on: <upstream row ids or "none">
-- Write scope: <none | manager-serial | exact-path | isolated-worktree | mixed>
-
-## 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. In the shared \`Findings or facts\` section, review workers
-should prefix review items with \`blocking:\` or \`advisory:\` before the claim.
-
-Example evidence quality:
-
-- Good fact: \`[high] public Flow command prompts include bundled instructions;
-  evidence: src/config-shared.ts:135; corroboration: single source\`.
-- Weak fact: \`[high] prompts look self-contained; evidence: read the config\`.
-- Good validation: \`bun test tests/distribution-and-surface.test.ts\`, status
-  passed, summary \`surface tests passed and covered bundled command prompts\`.
-- Weak validation: \`tests pass\`, with no command, status, or raw outcome.
-
-## 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, and do not say which worker produced the claim.
-
-\`\`\`markdown
-## Status
-success | partial | blocked
-
-## Scope
-<claim ids, sources or commands checked, and the acceptance question>
-
-## Pass metadata
-- Pass id: <stable pass id from the manifest>
-- Manifest row id: <row id from the manifest>
-- Depends on: <upstream row ids or "none">
-
-## 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 with explicit user authorization, in an isolated worktree or an
-exact non-overlapping path-owned slice assigned by the manager.
-
-\`\`\`markdown
-## Status
-success | partial | blocked
-
-## Scope
-<isolated worktree or exact path-owned slice>
-
-## Pass metadata
-- Pass id: <stable pass id from the manifest>
-- Manifest row id: <row id from the manifest>
-- Depends on: <upstream row ids or "none">
-- Write scope: <exact-path | isolated-worktree>
-
-## 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.
-
-## Manager pass accounting record
-
-The manager, not the worker, may carry compact records into
-\`flow_feature_complete.orchestrationPasses\`. Use one record per material pass or
-implementation decision; keep handoffs and long artifacts outside \`.flow/**\`.
-The candidate accounting rules — which \`candidateEligibility\`,
-\`candidateDecision\`, and \`decision\` combinations validate, and what counts as
-candidate execution evidence — live in
-[parallel-orchestration.md](parallel-orchestration.md) under "Implementation
-pass decision"; note \`decision: "parallel"\` is not valid on
-\`implementation-decision\` records.
-
-\`\`\`json
-{
-  "id": "stable-pass-id",
-  "kind": "discovery | audit | review | validation | verification | candidate | implementation-decision",
-  "decision": "serial | parallel | candidate-exact-path | candidate-worktree | tournament | skipped",
-  "decisionReason": "why this pass shape was chosen",
-  "candidateEligibility": "eligible | not_eligible | unknown",
-  "candidateDecision": "used | skipped | serial_required",
-  "decisionFactors": [
-    "shared_state",
-    "overlapping_files",
-    "small_slice",
-    "needs_manager_judgment",
-    "independent_surface",
-    "validation_available"
-  ],
-  "modes": ["evidence"],
-  "workerCount": 1,
-  "candidateWorkerCount": 0,
-  "verifierWorkerCount": 0,
-  "sliceIds": ["manifest-row-id"],
-  "dependsOn": [],
-  "writeScope": "none | manager-serial | exact-path | isolated-worktree | mixed",
-  "handoffRefs": ["/tmp/flow-handoff.md"],
-  "verificationStatus": "not-needed | pending | passed | failed | mixed | downgraded",
-  "outcome": "accepted | modified | rejected | partial | not-covered | superseded",
-  "synthesisRef": "/tmp/flow-synthesis.md"
-}
-\`\`\`
-`;
-
-// 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.
-
-Every parallel pass runs the same loop:
-
-**orient → slice → manifest → fan out → account → verify → synthesize →
-extend or stop.**
-
-This file is the whole playbook; read it once and run the pass. Two companions
-stay separate:
-
-- \`handoff-format.md\` holds the worker response templates. The manager pastes
-  the matching template verbatim into every worker prompt.
-- \`parallel-pass-example.md\` walks one concrete end-to-end pass (synced with
-  the \`flow\` skill; not bundled into commands).
-
-## Choose a pass
-
-| Situation | Flow pass | Output the manager may synthesize |
-| --- | --- | --- |
-| Repo shape is unclear before planning | Discovery pass | Requirements, decisions, targets, validation entries, or a review-first feature |
-| A broad finding set needs refutation | Audit pass | Surviving findings with guards checked and gaps named |
-| Changed files or risk lenses are too broad for one review pass | Review pass | One feature review packet or \`finalReview\` payload owned by the manager |
-| Test strategy or route coverage is unclear | Validation pass | Candidate commands or authorized raw command evidence |
-| A claim is single-source, surprising, high-stakes, or payload-bound | Verification pass | Per-claim keep, narrow, rewrite, or remove decisions |
-| Multiple implementation paths are plausible | Candidate pass | Candidate patches inspected and validated by the manager before use |
-
-Pass notes:
-
-- **Discovery**: workers read specific modules, routes, docs, commands, or risk
-  lenses; only evidenced claims become plan fields.
-- **Audit**: workers actively look for guards, lifecycle resets, deployment
-  constraints, and counterexamples before reporting a finding. A finding
-  without refutation work stays advisory or becomes a follow-up question.
-- **Review**: workers separate blocking findings from advisory notes; the
-  manager resolves conflicts and returns one review payload.
-- **Validation**: workers run only manager-authorized commands and report the
-  exact command, status, and raw outcome summary.
-- **Verification**: verifiers judge atomic claims against cited sources or
-  commands; do not ask a verifier to redesign the work or review the whole
-  feature.
-- **Candidate**: only with explicit user authorization plus isolated worktrees
-  or exact non-overlapping path ownership. Patches stay proposals until the
-  manager inspects, merges or rejects, and validates.
-
-## Implementation pass decision
-
-Before implementing a broad, risky, or multi-target feature, record one manager
-decision. This is required even when the answer is "stay serial"; the point is
-to make the skipped parallelism visible instead of relying on memory.
-
-First classify candidate eligibility:
-
-- \`eligible\`: at least one slice is independent enough for a candidate worker.
-- \`not_eligible\`: worker isolation would not make the implementation safer or
-  cheaper because the slice shares state, files, tests, or one mental model.
-- \`unknown\`: orientation did not produce enough evidence to classify; use this
-  only for non-decision pass rows or legacy low-signal records, not for
-  \`implementation-decision\` records and not as a substitute for judgment.
-
-Then record the candidate decision:
-
-- \`used\`: candidate workers were used or a candidate pass carried the work.
-- \`skipped\`: candidates were eligible, but the manager chose serial anyway.
-  This is the underused-parallelism signal counted by Flow status; use it only
-  on \`kind: "implementation-decision"\` records.
-- \`serial_required\`: candidates were not eligible, so serial work was the
-  correct implementation shape. Use it only on \`kind: "implementation-decision"\`
-  records.
-
-Use one of these decisions:
-
-- \`serial\`: the manager implements directly because slices overlap, the next
-  edit depends on one shared contract, or prompt/merge overhead would exceed the
-  value. Pair unsafe or not-useful worker cases with
-  \`candidateEligibility: "not_eligible"\` and
-  \`candidateDecision: "serial_required"\`.
-- \`candidate-exact-path\`: one or more candidate workers may edit exact
-  non-overlapping paths or modules named by the manager.
-- \`candidate-worktree\`: one or more candidate workers may edit in isolated
-  worktrees, then the manager inspects and merges or rejects.
-- \`tournament\`: several isolated candidate implementations compete for the same
-  outcome; the manager filters by tests, review, and source inspection before
-  accepting one.
-- Candidate-shaped decisions (\`candidate-exact-path\`, \`candidate-worktree\`,
-  \`tournament\`) require candidate execution evidence on the same record:
-  \`kind: "candidate"\`, \`modes\` includes \`candidate-implementation\`, or
-  \`candidateWorkerCount > 0\`. The same evidence rule applies to
-  \`candidateDecision: "used"\`. Non-decision candidate rows (for example
-  \`kind: "candidate"\`) may omit \`decision\`; \`implementation-decision\` rows must
-  always set one, and when \`candidateDecision\` is \`"used"\` that decision must
-  be candidate-shaped — never \`serial\`, \`parallel\`, or \`skipped\`.
-- \`parallel\` describes multi-worker read or audit passes (discovery, audit,
-  review); it is not a valid \`implementation-decision\` value. Implementation
-  decisions use \`serial\`, \`skipped\`, or a candidate-shaped decision.
-- \`skipped\`: candidate workers were eligible but the manager chose serial
-  anyway; pair this with \`candidateEligibility: "eligible"\` and
-  \`candidateDecision: "skipped"\`. Do not use \`skipped\` for shared fixtures,
-  shared API contracts, unclear ownership, or other unsafe worker cases; use
-  \`serial\` plus \`serial_required\` for those.
-
-Use structured \`decisionFactors\` alongside prose \`decisionReason\`:
-\`shared_state\`, \`overlapping_files\`, \`small_slice\`,
-\`needs_manager_judgment\`, \`independent_surface\`, and
-\`validation_available\`. Serial-required records usually cite
-\`shared_state\`, \`overlapping_files\`, or \`needs_manager_judgment\`; eligible
-records usually cite \`independent_surface\` and \`validation_available\`, with
-\`small_slice\` explaining an eligible-but-skipped choice.
-
-### Worker decision rubric
-
-Default to considering candidate workers when:
-
-- the plan has three or more features.
-- features touch separate surfaces such as frontend, core, docs, release
-  scripts, tests, or bindings.
-- validation can run per slice.
-- the work is mostly additive or localized.
-- the final manager can review, apply, adapt, or reject the result safely.
-
-Prefer serial when:
-
-- one tight invariant crosses shared files.
-- migrations, persistence, storage, or lifecycle semantics require one mental
-  model.
-- tests require iterative local debugging in one checkout.
-- multiple slices would edit the same files or fixtures.
-- the slice is so small that prompt, handoff, merge, and verification overhead
-  costs more than direct work.
-
-Record the decision in the pass manifest with a stable pass id,
-\`candidateEligibility\`, \`candidateDecision\`, \`decisionFactors\`,
-\`decisionReason\`, \`writeScope\`, expected verification, and where any handoff or
-synthesis artifact will live. If the feature completes, include the compact
-record in the \`orchestrationPasses\` array of the \`flow_feature_complete\`
-payload. The runtime stores only compact accounting; full worker handoffs stay
-in manager-owned scratch files or the conversation.
-
-## When to stay serial
-
-- One file, command, or design question determines the next step.
-- Slices would share the same contracts, fixtures, or edit targets.
-- The manager can inspect the full scope faster than writing and checking
-  worker prompts.
-- The result would still need the same manual synthesis with no time saved.
-
-Do not fan out to keep agents busy. Every worker should reduce a named
-planning, validation, review, audit, or implementation uncertainty. A normal
-first pass is two to five workers with independent slices; use more only when
-the manifest stays countable and non-overlapping.
-
-## 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 |
-
-Use worker-specific model routing where the installation can support it:
-\`OPENCODE_FLOW_READONLY_WORKER_MODEL\` for evidence, validation, and audit
-workers; \`OPENCODE_FLOW_REVIEW_WORKER_MODEL\` for reviewer and verifier workers;
-\`OPENCODE_FLOW_CANDIDATE_WORKER_MODEL\` for candidate implementation workers; and
-\`OPENCODE_FLOW_WORKER_MODEL\` as a fallback for all hidden Flow workers. Model IDs
-are OpenCode installation-specific (\`provider/model\`), so leave these unset when
-the configured provider is unknown. Spend stronger models where being wrong is
-expensive; read-heavy discovery slices tolerate the cheapest configured option,
-while verifier and review slices deserve the strongest.
-
-## Permission contract
-
-The plugin injects these hidden workers with the following permission values.
-\`Flow state tools\` means the \`flow_*\` rule, while \`Flow status\` documents the
-explicit \`flow_status\` exception.
-
-| Worker | Edit | Bash | Task | Skill | Flow state tools | Flow status |
-| --- | --- | --- | --- | --- | --- | --- |
-| \`flow-reviewer\` | deny | deny | deny | deny | deny | allow |
-| \`flow-evidence-worker\` | deny | deny | deny | deny | deny | allow |
-| \`flow-validation-worker\` | deny | ask | deny | deny | deny | allow |
-| \`flow-audit-worker\` | deny | ask | deny | deny | deny | allow |
-| \`flow-candidate-worker\` | ask | ask | deny | deny | deny | allow |
-| \`flow-verifier-worker\` | deny | ask | deny | deny | deny | allow |
-
-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.
-
-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/**\`,
-must not call state-changing Flow tools, and 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.
-
-## Stage 1 — Orient (serial)
-
-Call \`flow_status\` if a Flow session may already exist. Read enough files,
-schemas, docs, tests, commands, or artifacts to identify real slices. Keep the
-immediate blocker local: do not delegate the question that determines whether
-fan-out is even valid.
-
-Treat orientation as uncertainty reduction. Resolve environment uncertainty by
-inspecting the repo, running cheap commands, or assigning evidence workers; ask
-the user only when the remaining specification uncertainty would make a wrong
-slice expensive to undo. Do not split a vague goal into workers until the
-candidate slices have concrete targets, dependencies, and verification signals.
-
-## Stage 2 — Slice
-
-Split along whichever axis keeps slices independent: modules or path sets,
-route or endpoint groups, risk lenses, command surfaces, data ranges, or claim
-sets. Each slice needs a one-line scope, expected coverage, and a defined
-output the manager can check.
-
-For implementation slices, also name dependencies and write ownership before
-spawning. A real dependency edge means the later slice waits for a verified
-handoff or manager synthesis from the earlier slice; a shared file, fixture,
-schema, or public contract usually means the work should stay serial unless an
-isolated worktree is used. The manifest owns those edges through \`dependsOn\`
-and \`writeScope\`.
-
-## Stage 3 — Manifest (the pre-fan-out coverage gate)
-
-Before spawning, write a pass manifest: one row per slice, plus a totals check.
-Give the pass a stable id so later handoffs, verifier claims, and completion
-payloads can refer to the same work without replaying chat.
-
-| Row id | Slice scope | Expected coverage | Mode | Depends on | Write scope | Verification tier | Handoff ref | Verification status | Synthesis ref |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| \`runtime-read\` | \`src/core/**\` plus its tests | 14 files | \`evidence\` | none | none | accept locally | pending | pending | pending |
-| \`release-read\` | release contract: CI workflows, \`package.json\`, changelog | 6 files | \`evidence\` | none | none | verify once | pending | pending | pending |
-
-\`writeScope\` values in runtime accounting are \`none\`, \`manager-serial\`,
-\`exact-path\`, \`isolated-worktree\`, or \`mixed\`. Use \`manager-serial\` for a
-recorded serial implementation decision, \`exact-path\` for disjoint candidate
-edits in one checkout, and \`isolated-worktree\` for candidate work that must be
-merged back by the manager.
-
-- Count the total work items when countable: files, modules, routes, commands,
-  rows, findings, screenshots, or claims. Confirm slice counts add back to the
-  total, with no overlaps, gaps, empty slices, or ambiguous shared contracts.
-- 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."
-- Assign each slice's verification tier now (see Stage 6). Deciding where a
-  wrong claim is expensive belongs before handoffs arrive, not after.
-- Record dependency edges now. A row may be spawned only after every \`depends on\`
-  row it names has returned a verified handoff or a manager synthesis that
-  explicitly settles the dependency.
-- Fix the slice map centrally before spawning if the gate does not reconcile.
-
-The manifest is also the accounting contract for the pass: N rows spawned means
-N handoffs collected and checked in Stage 5 before anything is synthesized.
-
-For implementation decisions, add a manifest row even when no worker is spawned:
-\`kind=implementation-decision\`, \`decision=serial\` or \`decision=skipped\`,
-\`candidateEligibility\`, \`candidateDecision\`, \`decisionFactors\`,
-\`workerCount=0\`, \`writeScope=manager-serial\`, and a concrete \`decisionReason\`.
-Use \`decision=serial\` with \`candidateDecision=serial_required\` for ineligible
-worker cases; reserve \`decision=skipped\` for eligible candidate work that the
-manager chose not to delegate. When an implementation-decision row uses
-\`candidateDecision=used\`, it must also record actual candidate execution
-evidence: either \`modes=candidate-implementation\`, or \`candidateWorkerCount > 0\`
-with \`workerCount\` raised to cover it — a \`workerCount=0\` row cannot carry a
-positive \`candidateWorkerCount\`. Neither subtype count may exceed the total:
-\`candidateWorkerCount <= workerCount\` and \`verifierWorkerCount <= workerCount\`
-(a single worker may fill both roles).
-This is how Flow distinguishes deliberate serial work from forgotten candidate
-or verifier passes.
-
-Write the manifest where it survives the pass: the conversation is enough for a
-single bounded pass, but when a follow-up pass or a session resume is
-plausible, persist it with the synthesis (Stage 7) so the accounting can be
-reconstructed.
-
-## Stage 4 — Fan out
-
-Every worker prompt includes:
-
-\`\`\`text
-Overall goal, context only: <goal>
-Mode: evidence | review | validation | audit | verifier | candidate-implementation
-Pass id and manifest row id: <stable ids from the manifest>
-Your exact slice: <paths, modules, command, claim ids, risk lens, or worktree>
-Expected coverage: <count, paths, range, or complete question set>
-Dependencies and write scope: <verified dependencies, if any; none | manager-serial | exact-path | isolated-worktree>
-Do: <bounded actions>
-Do not: call state-changing Flow tools, edit .flow/**, own sibling slices, or make the final Flow verdict.
-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. Workers also cannot read the conversation, so
-prompts cite file paths — including any synthesis file from an earlier pass —
-instead of restating chat history.
-
-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.
-
-Continue non-overlapping manager work while workers run.
-
-## Stage 5 — Account
-
-Check every manifest row off against a returned handoff before synthesis. A
-worker that never returns, errors out, returns empty or unstructured output, or
-reports \`partial\` or \`blocked\` is a hole in the pass, and synthesizing around it
-silently drops a slice.
-
-For each row, fill in:
-
-- \`handoffRefs\`: worker ids, handoff file paths, command output artifacts, or
-  review packet location that the manager can re-open.
-- \`verificationStatus\`: \`not-needed\`, \`pending\`, \`passed\`, \`failed\`, \`mixed\`,
-  or \`downgraded\`.
-- \`outcome\`: \`accepted\`, \`modified\`, \`rejected\`, \`partial\`, \`not-covered\`, or
-  \`superseded\`.
-- \`synthesisRef\`: the manager-owned synthesis file or plan field that carries
-  the accepted result forward.
-
-Rows with no worker, such as serial or skipped implementation decisions, still
-need a row id, decision, reason, and outcome. They are not handoffs, but they
-are accounting.
-
-Worker failure ladder:
-
-1. Re-spawn once with a narrower slice and a note about what the first attempt
-   returned.
-2. If it fails again, cover the slice directly in the manager session.
-3. If it stays blocked, carry the slice into the synthesis explicitly as
-   not-covered. Never present results as if coverage were complete.
-
-## Stage 6 — Verify
-
-\`Status: success\` only says the worker believes its slice is done. Accept a
-handoff only after a cheap manager-side pass:
-
-- \`Status\` is present and terminal: \`success\`, \`partial\`, or \`blocked\`; empty or
-  unstructured output fails this check.
-- 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.
-- Dependency claims cite the verified upstream handoff, synthesis, or source
-  artifact they depend on.
-- Candidate implementation claims identify whether they came from exact path
-  ownership or an isolated worktree, and whether the manager inspected the
-  resulting patch. Record the manager result as \`accepted\`, \`modified\`, or
-  \`rejected\` where that is the most precise candidate outcome.
-- Contradictions between workers are either resolved or explicitly marked as
-  contested.
-
-Demote, drop, re-task, or verify claims that fail this pass.
-
-### Verification tiers
-
-One taxonomy decides how much verification a claim gets: the manifest assigns
-a default tier per slice, and this stage applies it per claim. Use the cheapest
-check that matches the risk:
-
-- **Accept locally**: low-risk claims with direct evidence that the manager can
-  cheaply inspect or recount.
-- **Verify once** with \`flow-verifier-worker\`: single-source, surprising,
-  inferred, low-confidence, citation-heavy, contested, or Flow-payload-bound
-  claims, including any count, benchmark, command result, or pass/fail claim a
-  Flow payload will rely on.
-- **Verify strongly**: blocking or release-sensitive claims and claims that
-  affect user data, security, persistence, permissions, public API behavior,
-  release behavior, or data loss. Use independent verifier checks, manager-run
-  commands, or direct artifact inspection strong enough to settle the claim.
-- **Do not accept**: claims without concrete evidence, claims outside the
-  assigned slice, claims contradicted by inspected artifacts, or claims where
-  the cited evidence supports only the topic rather than the assertion.
-
-Verifier prompts use stable claim ids, one atomic assertion per id, the cited
-source or command for each id, and the exact acceptance question. Do not
-include the generator's reasoning unless that reasoning is the thing being
-verified, do not say which worker produced the claim, and do not ask a
-verifier to redesign the work or review the whole feature.
-
-## Stage 7 — Synthesize
-
-Apply the manager synthesis barrier before presenting or recording anything:
-
-- 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. Do not average conflicting claims.
-- Run the strongest practical local check for the deliverable.
-- For broad implementation sessions, use one verifier worker after manager
-  synthesis when the risk is medium or high. Ask it whether every planned
-  feature landed, worker validation claims are supported, final code matches
-  the audit finding, generated bindings/docs/version metadata stayed
-  consistent, and changed files have plausible test coverage.
-- Re-read critical files or docs that will be cited in the final decision.
-- Move only distilled, evidence-backed claims forward; raw handoffs remain
-  candidate evidence, not a plan, review, completion payload, or final answer.
-- Record gaps honestly instead of converting missing evidence into success
-  language.
-
-Where accepted evidence goes:
-
-- Planning evidence becomes \`requirements\`, \`decisions\`, feature \`targets\`,
-  feature \`validation\`, or plan notes — only when the source and scope are
-  clear. Unverified broad findings become a review-first feature, not a fix
-  plan.
-- Validation evidence may become \`validationRun\` only when the worker was
-  explicitly authorized to run the command and reported the exact command,
-  status, and raw outcome summary.
-- Review evidence informs \`featureReviewDepth\` plus \`featureReview\`, or \`finalReview\`, but the manager
-  owns the pass/fail verdict and must resolve blockers, contradictions, and
-  coverage gaps before returning the payload.
-- Audit evidence becomes findings only after refutation; blocking findings need
-  guards checked, deployment context, and evidence that the current code
-  exhibits the behavior.
-- Candidate patches are not Flow evidence until the manager inspects, merges or
-  rejects them, and validates the main Flow-managed workspace.
-
-When completing a feature, include compact pass accounting in
-\`flow_feature_complete.orchestrationPasses\` for any pass or implementation
-decision that materially affected the feature:
-
-\`\`\`json
-{
-  "id": "feature-id-implementation-decision",
-  "kind": "implementation-decision",
-  "decision": "serial",
-  "decisionReason": "Shared schema and tests made exact path ownership unsafe.",
-  "candidateEligibility": "not_eligible",
-  "candidateDecision": "serial_required",
-  "decisionFactors": ["shared_state", "overlapping_files"],
-  "modes": [],
-  "workerCount": 0,
-  "candidateWorkerCount": 0,
-  "verifierWorkerCount": 0,
-  "sliceIds": ["manager-implementation"],
-  "dependsOn": [],
-  "writeScope": "manager-serial",
-  "handoffRefs": [],
-  "verificationStatus": "not-needed",
-  "outcome": "accepted",
-  "synthesisRef": "/tmp/flow-pass-synthesis.md"
-}
-\`\`\`
-
-For candidate and verifier passes, use \`kind: "candidate"\` or
-\`kind: "verification"\`, list the worker modes used, worker counts, slice ids,
-handoff refs, dependency ids, verification status, and whether the manager
-accepted, rejected, downgraded, or superseded the pass. The runtime aggregates
-these compact records into \`session.budget.orchestration\` and stores them on
-the feature history entry. Do not store full handoffs, long logs, or scratch
-tables in \`.flow/session.json\`.
-
-Status accounting distinguishes three cases: \`candidateDecision: "used"\` means
-candidate execution evidence was recorded, \`candidateDecision:
-"serial_required"\` means workers were not safe or useful, and
-\`candidateEligibility: "eligible"\` plus \`candidateDecision: "skipped"\`
-increments \`skippedCandidateDecisionCount\`. These candidate decision counters
-come from \`kind: "implementation-decision"\` records; \`skipped\` and
-\`serial_required\` are not valid on discovery, audit, review, validation,
-verification, or candidate pass rows. \`candidatePassCount\`
-counts actual candidate pass or worker evidence (\`kind: "candidate"\`,
-\`modes\` includes \`candidate-implementation\`, or \`candidateWorkerCount > 0\`) —
-a candidate-shaped decision label without that evidence is rejected, so decision
-labels alone never count. \`verifierPassCount\` similarly counts
-actual verifier pass or worker evidence (\`kind: "verification"\`, \`modes\`
-includes \`verifier\`, or \`verifierWorkerCount > 0\`).
-
-Persist the manifest and the synthesis when another pass may follow or the
-session is long enough to be compacted or resumed: write the distilled result —
-the accounted manifest, accepted claims with evidence and confidence, dropped
-claims with one-line reasons, and open gaps — into plan prose fields or a
-manager-owned scratch file outside both \`.flow/**\` and the repository worktree,
-such as a file in the OS temporary directory. The runtime owns the \`.flow/**\`
-layout, and scratch files left in the worktree end up staged or reviewed as if
-they were project changes. Follow-up worker prompts cite that path; files are
-the only shared memory between passes.
-
-## Stage 8 — Extend or stop
-
-Stop after a pass when:
-
-- the manifest's coverage rule is satisfied and every row is accounted for.
-- accepted claims are evidenced, scoped, and confidence-labeled.
-- material single-source, contested, high-stakes, or payload-bound claims have
-  been verified or downgraded.
-- every dependency edge named in the manifest has either a verified upstream
-  result or an explicit not-covered outcome.
-- implementation pass decisions are recorded, including skipped candidate
-  workers, candidate eligibility, candidate decision, structured factors, and
-  the reason eligible workers were skipped.
-- remaining gaps are explicit and do not block the Flow artifact being produced.
-
-Start a bounded follow-up pass only when:
-
-- the original slice map missed material scope.
-- workers disagree on a claim that affects the Flow decision.
-- a high-stakes or payload-bound claim needs verification.
-- a dependency has just become verified and now unlocks a dependent slice.
-- a candidate patch was rejected and an isolated alternative is still cheaper
-  than serial repair.
-- a first pass exposes a narrower implementation or validation slice worth
-  isolating.
-
-Run at most one routine follow-up pass. Extra passes need an explicit manager
-reason, such as a high-stakes verifier check or a newly discovered bounded
-slice. 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, starting again from the manifest.
-
-## Worker count defaults
-
-Use caps, not a fixed feature limit:
-
-- small implementation: zero or one worker.
-- medium independent implementation: two workers.
-- broad audit: three to five workers.
-- broad implementation: two to four candidate workers, only for
-  non-overlapping slices.
-- final verifier: one worker when risk is medium or high.
-
-The target is not "more workers." The target is explicit accounting: Flow must
-justify not using workers when the work was eligible.
-`;
-
-// 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. The project below is illustrative; derive your own slices
-from the actual repo during serial orientation.
-
-Goal: review whether a web app's API error handling is consistent before
-planning a refactor.
-
-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.
-
-Pass manifest: twelve countable route modules remain after the local check, and
-4 + 3 + 5 adds back to 12 with no overlaps or gaps. The pass id is
-\`api-error-handling-read\`.
-
-| Row id | Slice scope | Expected coverage | Mode | Depends on | Write scope | Verification tier | Handoff ref | Verification status | Synthesis ref |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| \`routes-auth\` | auth and account routes | 4/12 modules | \`evidence\` | none | none | accept locally | pending | pending | pending |
-| \`routes-billing\` | billing and subscription routes | 3/12 modules | \`review\` | none | none | verify once | pending | pending | pending |
-| \`routes-admin\` | remaining content and admin routes | 5/12 modules | \`audit\` | none | none | verify once | pending | pending | pending |
-
-Worker prompts:
-
-\`\`\`text
-Overall goal, context only: confirm API error handling is consistent.
-Mode: evidence
-Pass id and manifest row id: api-error-handling-read / routes-auth
-Your exact slice: the four auth and account route modules under src/routes/.
-Expected coverage: 4/4 modules.
-Dependencies and write scope: none; none.
-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 Flow handoff in this exact shape:
-<matching handoff template copied verbatim from handoff-format.md>
-\`\`\`
-
-\`\`\`text
-Overall goal, context only: confirm API error handling is consistent.
-Mode: review
-Pass id and manifest row id: api-error-handling-read / routes-billing
-Your exact slice: the three billing and subscription route modules under src/routes/.
-Expected coverage: 3/3 modules.
-Dependencies and write scope: none; none.
-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 Flow handoff in this exact shape:
-<matching handoff template copied verbatim from handoff-format.md>
-\`\`\`
-
-\`\`\`text
-Overall goal, context only: confirm API error handling is consistent.
-Mode: audit
-Pass id and manifest row id: api-error-handling-read / routes-admin
-Your exact slice: the five content and admin route modules under src/routes/.
-Expected coverage: 5/5 modules.
-Dependencies and write scope: none; none.
-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 Flow handoff in this exact shape:
-<matching handoff template copied verbatim from handoff-format.md>
-\`\`\`
-
-Accounting: three manifest rows spawned means three handoffs collected before
-synthesis. If slice B returned \`partial\`, the manager would re-spawn it once
-with a narrower scope, then cover it directly, and as a last resort carry it
-into the synthesis explicitly as not-covered.
-The manager fills \`handoffRefs\`, \`verificationStatus\`, \`outcome\`, and
-\`synthesisRef\` for each row before any claim becomes a plan decision or review
-payload.
-
-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] 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: 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 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.
-
-If the pass shaped feature execution, the manager records compact accounting in
-\`flow_feature_complete.orchestrationPasses\`, such as pass id
-\`api-error-handling-read\`, kind \`review\`, worker count \`3\`, slice ids
-\`routes-auth\`, \`routes-billing\`, and \`routes-admin\`, verification status
-\`mixed\` or \`passed\`, and a synthesis ref pointing to the manager-owned summary.
-`;
-
-// 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- `Feature review depth ... does not meet the plan requirement`: rerun review\n  at the feature\'s planned depth or reset/replan if the depth was chosen\n  incorrectly.\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- `Review retry budget exhausted`: stop and report the remaining blocker. Do\n  not keep patching; reset or replan only after explicit user direction.\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/SKILL.md
-var SKILL_default = "---\nname: flow\ndescription: Manage the end-to-end Flow loop for skills-first OpenCode work. Use when a user asks for Flow-guided delivery from goal to completion, resumable autonomous delivery, or resuming or closing a Flow session. For plan-only work use flow-plan; for executing one approved feature use flow-run.\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\nRouting: this manager skill owns the whole loop and every state-changing `flow_*` call. Load `flow-plan` alone for plan-only requests and `flow-run` alone when an approved plan needs one feature executed. Answer status-only questions with `flow_status`; no skill load is needed. `flow-test`, `flow-deslop`, and `flow-ui-quality` are optional helpers loaded from inside the loop; `flow-commit` is user-triggered only and never part of the autonomous loop.\n\n## Loop\n\n1. Call `flow_status` first. Trust its active session and next action over conversation memory.\n   If the result includes `setup.skills`, follow the Skill Availability rules\n   below before loading any Flow skill.\n   If it includes `session.resumePacket` or `session.budget.phaseBoundary`, stop\n   and report the resume instructions unless this is a fresh user invocation\n   explicitly resuming the session. Only then may the next `flow_run_start` use\n   `phaseBoundaryAck: true`.\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. For validation-heavy, regression-sensitive, browser QA, route QA, or failure-prone work, use `flow-test` to choose and summarize evidence before completion.\n4. Load `flow-review` for the required feature review. Send a compact review\n   packet, not the accumulated root transcript. The reviewer reports\n   `featureReviewDepth` and `featureReview`; the manager records both inside\n   `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 passes. It is the whole pass playbook — orient, slice, manifest, fan out, account, verify, synthesize, extend or stop — and its `references/handoff-format.md` companion holds the worker report templates the manager pastes into prompts. Hidden Flow workers are injected by plugin config; invoke the named worker when it is available. The manager owns every `flow_*` state change.\n\nDo not commit, push, amend, rebase, publish, or mutate releases during the\nautonomous Flow loop. Load `flow-commit` only when the user explicitly asks for\ncommit preparation or commit creation.\n\n## Skill Availability\n\nIf `flow_status` returns `setup.skills`, report that setup status and stop\nnative-loading Flow skills in the current OpenCode startup. Missing, incomplete,\nor outdated managed skills require a sync/restart cycle before their native skill\ninstructions can be trusted by the running process. Public command bundles are\nself-contained and may continue when the command prompt already embeds the\nrequired Flow instructions.\n\nIf optional helper skills such as `flow-test`, `flow-deslop`, or\n`flow-ui-quality` are unavailable, continue only with explicit coverage gaps. Do\nnot copy their rubrics into another skill and do not claim their quality checks\nwere completed.\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, skills, or references 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- Each feature's planned `reviewDepth` is the minimum accepted\n  `featureReviewDepth` for completion.\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- Failed reviews pause the loop by default. Autonomous repair may make at most\n  one repair plus one retry review before stopping.\n- Phase boundaries stop the current root session; resume from\n  `.flow/session.json` in a fresh OpenCode session.\n- `flow_session_close` accepts `kind: \"completed\"` only after an approved plan has passed final completion.\n\n## Budget And Retry Boundaries\n\nFlow enforces review retry counts in the runtime ledger and tracks completed\nfeature counts as telemetry only. The current OpenCode plugin surface does not\nexpose per-turn token usage to Flow; when usage is visible in the host UI or\nlogs, stop the current autonomous loop once the root session is large enough to\nthreaten latency or cost and report a compact handoff instead of continuing.\nTreat high visible tokens, high non-cache tokens, or repeated reviewer fan-out\nas a reason to finish the current feature, emit the resume packet, and continue\nin a fresh session.\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";
-
-// 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.
----
-
-# Flow Commit
-
-Use this skill only when the user asks to prepare or create a commit, write a
-commit message, stage intended work, or validate staged changes before
-committing. It is not part of the autonomous Flow loop and must not be loaded
-automatically by \`flow\`, \`flow-run\`, or \`flow_feature_complete\`.
-
-When a Flow session exists, a commit never substitutes for Flow completion. The
-manager still records validation and review evidence through
-\`flow_feature_complete\` before claiming a Flow feature is done. Default to commit
-preparation only after \`flow_feature_complete\` has recorded the relevant
-completion evidence. If the user explicitly asks for a WIP commit, preserve
-failing or incomplete validation context in the message.
-
-## Boundaries
-
-- Preserve unrelated user work.
-- Stage explicit paths or hunks only. Do not default to \`git add .\` or
-  \`git add -A\`.
-- Do not commit \`.flow/**\` state unless the maintainer explicitly asks to
-  archive those exact files.
-- Do not push, amend, rebase, squash, reset, force-push, tag, release, publish,
-  or mutate remote state unless the user explicitly authorizes that exact
-  operation.
-- Stop before committing secrets, local config, credentials, private keys,
-  generated release artifacts, or suspicious environment files.
-- Stop when validation fails unless the user explicitly wants an unfinished WIP
-  commit and the commit message says so.
-
-## Inspect
-
-Start with the worktree and intent:
-
-1. Run \`git status --short\`.
-2. Inspect unstaged and staged changes separately with \`git diff\` and
-   \`git diff --cached\`.
-3. Inspect untracked files before deciding whether they belong.
-4. Group changes by intent, feature, and risk. Prefer one coherent commit over
-   one large mixed commit.
-5. Identify exclusions: unrelated files, local notes, \`.flow/**\`, generated
-   artifacts, logs, caches, credentials, and temporary outputs.
-
-If the commit boundary is unclear, propose the boundary and ask before staging.
-
-## Stage
-
-Stage only the intended boundary:
-
-- Use explicit file paths for whole-file staging.
-- Use patch staging for mixed-intent files.
-- Re-run \`git status --short\` and \`git diff --cached --stat\` after staging.
-- Review the full staged diff before validation and commit.
-
-Never undo or rewrite user changes to make staging easier. If a file contains
-mixed user and agent work, either stage selected hunks or ask for direction.
-
-## Screen and Validate
-
-Before commit creation, check the staged diff for:
-
-- Secrets, tokens, private keys, credentials, cookies, and unredacted personal
-  data.
-- \`.env\`, local config, machine-specific paths, and editor files.
-- \`.flow/**\` state.
-- Generated artifacts that are not normally versioned.
-- Package or version metadata drift unrelated to the requested change.
-
-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
-checks as whole-worktree evidence unless the repository explicitly provides a
-staged-content runner. Use narrower tests only when the user has asked for a
-lighter pass or when the change is intentionally not ready for the broad gate.
-
-## Message
-
-Propose a commit message that reflects the staged diff:
-
-- Subject: imperative, specific, and scoped.
-- Body when useful: context, changed areas, validation run, and remaining risk.
-- Do not mention unstaged or excluded work as if it were included.
-- Include WIP or failing-validation context only when the user explicitly chose
-  that path.
-
-## Create Commit
-
-Create the commit only after the user explicitly asks for commit creation or has
-already authorized it in the current request.
-
-Before running \`git commit\`, report:
-
-- Staged paths.
-- Excluded dirty or untracked paths.
-- Validation command and result.
-- Proposed message.
-- Any risks or gaps.
-
-After a successful commit, report the commit hash and leave push or release
-actions for a separate explicit request.
-`;
-
-// 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.
-
-## 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.
-`;
-
-// 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.
-
-## 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.
-`;
-
-// 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, and dead code. Review verdicts on cleanup work stay in flow-review, which loads this skill to judge cleanup claims.
----
-
-# 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.
-
-This is a helper skill: it produces cleanup findings and evidence only. The manager owns every state-changing \`flow_*\` call, and cleanup review verdicts are returned through \`flow-review\`.
-
-## 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.
-`;
-
-// 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.
-
-For broad parallel passes, also load \`../../flow/references/parallel-orchestration.md\`.
-Use its pass manifest as the 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.
-
-## Deriving first-pass slices
-
-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 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 pass manifest.
-
-## Manifest and prompts
-
-Write the pass manifest and the worker prompts exactly as Stages 3 and 4 of
-\`../../flow/references/parallel-orchestration.md\` define them: one manifest row
-per slice with expected coverage, dependencies, write scope, and a verification
-tier, and a self-contained prompt per worker naming the mode (usually
-\`evidence\`), the exact slice, and the expected coverage. Discovery-specific
-rules:
-
-- Workers are read-only. For validation-oriented discovery, workers may report
-  commands that should be run, and include raw output only for commands they
-  actually ran.
-- Workers cannot read reference files themselves; paste the matching handoff
-  template from \`../../flow/references/handoff-format.md\` into the prompt.
-- If discovery finds later features with disjoint path ownership, preserve that
-  fact in feature \`targets\` and \`dependsOn\` so execution can make an explicit
-  serial or candidate-pass decision instead of rediscovering ownership.
-
-## 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.
-
-Apply the manager synthesis barrier from
-\`../../flow/references/parallel-orchestration.md\`: only distilled,
-evidence-backed claims become plan fields.
-`;
-
-// skills/flow-plan/references/plan-quality-checklist.md
-var plan_quality_checklist_default = `# Plan quality checklist
-
-Use this checklist before \`flow_plan_save\` and again before approval if the plan
-changed during discussion. The goal is not a long planning artifact; it is a
-compact plan another agent can execute without rediscovering the work.
-
-## Must pass
-
-- Outcome: \`summary\` names the user-visible result, not an internal activity.
-- Requirements: acceptance criteria, constraints, and non-goals that affect
-  implementation are captured in \`requirements\`.
-- Decisions: assumptions, scope choices, and architecture choices already made
-  are captured in \`decisions\`.
-- Uncertainty: specification uncertainty is resolved by a decision or a user
-  question; environment uncertainty is resolved by inspection, discovery, or a
-  first evidence-producing feature.
-- Feature shape: each feature has one coherent outcome and can be reviewed on
-  its own.
-- Targets: each feature names bounded files, modules, routes, commands, docs, or
-  generated surfaces. Whole-repo targets are allowed only for explicit broad
-  audits or final validation.
-- Validation: each feature names expected check levels, such as targeted unit,
-  integration, browser/e2e, package/build, docs/static, cleanup preservation, or
-  broad project gate.
-- Dependencies: \`dependsOn\` captures true ordering and avoids hidden dependency
-  chains.
-- Review policy: \`finalReviewPolicy\` is \`detailed\` when the work changes
-  behavior, persistence, public contracts, security posture, release surfaces,
-  or multiple modules.
-
-## Revise when you see this
-
-- A feature title describes a step like "update files" instead of a result.
-- A validation entry says only "manual testing" or "run tests".
-- A feature has targets but no behavior or artifact that can be judged.
-- A feature claims cleanup or simplification without an evidence-producing
-  audit or cited smell.
-- A docs feature depends on behavior that is not yet implemented but lacks
-  \`dependsOn\`.
-- A low-risk \`finalReviewPolicy: "broad"\` is used while the plan crosses runtime,
-  schema, persistence, security, or release boundaries.
-
-## Approval summary
-
-When presenting the plan for approval, include:
-
-- The promised outcome.
-- The feature order and any dependencies that matter.
-- The main validation levels.
-- Material assumptions in \`decisions\`.
-- Any known gaps that remain intentional.
-`;
-
-// skills/flow-plan/references/planning-examples.md
-var planning_examples_default = `# 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.
-\`\`\`
-
-## Bugfix plan
-
-Human summary:
-
-1. Reproduce and localize the failed password reset redirect.
-2. Fix the redirect state handling and cover the regression.
-3. Update release notes only if user-facing behavior changed.
-
-Payload:
-
-\`\`\`json
-{
-  "goal": "Fix password reset links landing users on the wrong page",
-  "plan": {
-    "summary": "Password reset links land users on the intended reset confirmation flow.",
-    "overview": "Start with a focused reproduction, then fix the redirect state and update user-facing notes only if the behavior change needs documentation.",
-    "requirements": [
-      "Preserve existing token validation and expiry behavior.",
-      "Users with valid reset links should not be sent to the generic sign-in page before completing the reset."
-    ],
-    "decisions": [
-      "Treat the current redirect mismatch as a regression until reproduction proves otherwise."
-    ],
-    "finalReviewPolicy": "detailed",
-    "features": [
-      {
-        "id": "reset-redirect-repro",
-        "title": "Redirect reproduction",
-        "summary": "Produce a failing focused check or trace that identifies where the reset redirect is lost.",
-        "targets": ["src/auth/reset", "tests/auth"],
-        "validation": ["targeted unit or integration reproduction for reset redirect behavior"],
-        "dependsOn": []
-      },
-      {
-        "id": "reset-redirect-fix",
-        "title": "Redirect fix",
-        "summary": "Preserve reset redirect state through token validation and completion.",
-        "targets": ["src/auth/reset", "tests/auth"],
-        "validation": ["targeted regression test passes", "auth package/build check if available"],
-        "dependsOn": ["reset-redirect-repro"]
-      },
-      {
-        "id": "reset-redirect-notes",
-        "title": "User-facing notes",
-        "summary": "Document the corrected reset-link behavior if release notes or help text mention the flow.",
-        "targets": ["CHANGELOG.md", "docs/auth.md"],
-        "validation": ["docs/static check if available", "review docs against implemented behavior"],
-        "dependsOn": ["reset-redirect-fix"]
-      }
-    ]
-  }
-}
-\`\`\`
-
-## UI/frontend plan
-
-Human summary:
-
-1. Map the current checkout empty state and responsive constraints.
-2. Implement the empty state with accessible controls and mobile layout.
-3. Verify the visual states with screenshots or browser evidence.
-
-Good feature outline:
-
-\`\`\`text
-1. Empty-state discovery - inspect the route, component boundaries, design tokens, existing empty states, and likely responsive breakpoints.
-2. Empty-state implementation - add the checkout empty state, action wiring, focus order, and loading/error boundaries in the existing component style.
-3. Visual and interaction verification - capture desktop and mobile evidence, run available route/component checks, and fix overlap or accessibility regressions.
-\`\`\`
-
-Why this is better than one "build UI" feature: the plan names the uncertain
-surface first, keeps implementation scoped to the route/components, and makes
-visual evidence part of completion rather than an afterthought.
-
-## Runtime or schema plan
-
-Human summary:
-
-1. Introduce the schema change behind a backward-compatible parser.
-2. Migrate callers and persistence writes.
-3. Add compatibility validation and docs.
-
-Good feature outline:
-
-\`\`\`text
-1. Compatible schema reader - accept old and new session payloads, with targeted parser tests for both.
-2. New writer path - emit the new field from runtime transitions and update affected callers.
-3. Compatibility sweep - run persistence/workspace tests, update docs, and verify old sessions still recover.
-\`\`\`
-
-Use \`finalReviewPolicy: "detailed"\` for this shape. Persistence and schema work
-usually has hidden downstream contracts, so feature validation should name both
-targeted parser checks and broader workspace/runtime gates.
-
-## Docs-only plan
-
-Docs-only work can use \`finalReviewPolicy: "broad"\` when it does not change
-commands, configuration, generated files, or release metadata.
-
-Good feature outline:
-
-\`\`\`text
-1. Align installation docs - update README and troubleshooting steps for the current setup flow.
-2. Verify commands and links - check documented commands against package scripts and make sure links/paths resolve.
-\`\`\`
-
-Bad validation:
-
-\`\`\`text
-validation: ["manual review"]
-\`\`\`
-
-Better validation:
-
-\`\`\`text
-validation: ["docs/static link and path review", "command examples checked against package scripts"]
-\`\`\`
-
-## Audit-first and review-first plans
-
-Use an evidence-producing first feature when the request asks to "review",
-"audit", "clean up", "modernize", or "improve" a broad area.
-
-Good feature outline:
-
-\`\`\`text
-1. Audit checkout state management - cite concrete findings with file:line evidence, refutation checks, severity, and recommended fix order.
-2. Fix confirmed high-impact state leak - only for findings that survived the audit.
-3. Regression validation - add or run checks covering the changed state paths.
-\`\`\`
-
-Do not plan fixes for guessed findings. If the audit might find no actionable
-issue, say that in the first feature summary and make later features conditional
-on evidence.
-
-## Validation examples
-
-Weak:
-
-\`\`\`text
-validation: ["run tests", "manual testing"]
-\`\`\`
-
-Stronger:
-
-\`\`\`text
-validation: [
-  "targeted unit tests for empty and invalid input",
-  "integration test for persisted session recovery",
-  "package/build gate for changed TypeScript exports",
-  "browser screenshot at desktop and mobile widths for layout-sensitive UI",
-  "docs/static review for changed command examples"
-]
-\`\`\`
-
-The stronger version says what level of evidence is expected and which behavior
-or surface it covers.
-
-## 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\`.
-`;
-
-// skills/flow-plan/SKILL.md
-var SKILL_default4 = `---
-name: flow-plan
-description: "Use when Flow work needs planning before implementation: a new goal to turn into an approved Flow feature plan, a draft plan to revise, or a decomposition or plan-approval decision in the v4 skills-first runtime. For executing an approved feature use flow-run; for the full goal-to-completion loop use flow."
----
-
-# 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 write its pass manifest 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\`.
-- 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.
-
-## Reduce uncertainty before decomposing
-
-A vague goal does not slice into reliable features yet. Name what is uncertain,
-because the two kinds resolve differently:
-
-- **Specification uncertainty** — what the user wants: ambiguous goal, missing
-  acceptance criteria, unstated constraints. Resolve by stating an explicit
-  assumption in \`decisions\` and proceeding, or by asking only when a wrong
-  guess would be expensive to undo.
-- **Environment uncertainty** — facts the repo, docs, commands, or data can
-  answer: code shape, schema, API behavior, current conventions. Resolve by
-  inspecting or by a discovery pass, never by asking the user.
-
-Spend the cheapest probe that removes the most uncertainty first: local reads
-before worker fan-out, fan-out before user questions. Decompose into features
-only once the remaining uncertainty is low enough that \`targets\` and
-\`validation\` can be stated concretely; otherwise the first feature is a
-review-first or discovery deliverable that produces the missing evidence.
-
-## 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",
-        "reviewDepth": "standard",
-        "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.
-
-Set each feature's \`reviewDepth\` to one of:
-
-- \`quick\`: docs, comments, config-only changes, generated output, or mechanical changes fully covered by tooling.
-- \`standard\`: the default for ordinary implementation slices. The review reads every changed file and relevant tests.
-- \`detailed\`: persistence, migrations, concurrency, security, cross-module behavior, release/package surfaces, large refactors, weak validation, or any work where a missed edge case would be expensive.
-
-Do not make reviews shallower to save tokens. Reduce token use by splitting features, keeping \`targets\` precise, and using scoped review packets during execution.
-
-## Plan quality gate
-
-Before saving or asking for approval, load
-\`references/plan-quality-checklist.md\` and check the draft against it. Revise the
-plan until it passes, or record the remaining gap in \`decisions\` when the gap is
-an intentional assumption. Do not approve a plan whose outcome, requirements,
-targets, validation, or dependency order are still too vague for another agent
-to execute.
-
-## 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\`. Each
-  validation entry should name the expected test level, such as targeted unit,
-  integration, browser/e2e, package/build, docs/static, cleanup preservation, or
-  broad project gate.
-- When a feature may benefit from parallel implementation, make \`targets\`
-  precise enough for later ownership decisions: name exact modules, docs,
-  commands, or route groups, and use \`dependsOn\` to preserve prerequisite order.
-  Broad shared-contract work should stay in one feature or an earlier foundation
-  feature so later candidate passes can own disjoint paths safely.
-- Assign \`reviewDepth\` from risk. Use \`detailed\` for persistence, migration,
-  concurrency, security, final-delivery-adjacent, or cross-module slices; use
-  \`standard\` for normal code changes; reserve \`quick\` for low-risk non-behavioral
-  work.
-
-## 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.
-`;
-
-// 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.
-
-## 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
-
-- The original goal is satisfied by the delivered behavior or artifacts.
-- Every approved requirement is either met or explicitly accounted for by an
-  accepted gap.
-- Plan decisions and scope boundaries still match the implementation.
-- Every planned feature is complete, has recorded validation evidence, and
-  contributes to the final outcome.
-- Feature dependencies were completed in an order that makes the evidence
-  trustworthy.
-- Changed artifacts match the plan's \`targets\`; extra changed surfaces are
-  explained and reviewed.
-- Broad validation ran and passed, or any skipped broad check is justified as a
-  non-blocking gap.
-- 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"\`.
-
-## Final convergence scan
-
-Run this scan before returning a passing \`finalReview\`:
-
-1. Restate the original goal and the approved plan summary in your own words.
-2. Map each requirement to delivered evidence, validation output, or an explicit
-   accepted gap.
-3. Walk every planned feature and confirm its completion evidence, review
-   result, and validation level.
-4. Compare the changed files, docs, commands, generated surfaces, and package
-   metadata to the planned targets and requirements.
-5. Check whether the validation evidence would have caught the main failure
-   modes introduced by the work.
-6. Decide whether remaining gaps are advisory or blocking before setting
-   \`status\`.
-
-Fail the final review when the delivered work cannot be traced back to the
-approved goal and requirements, even if each individual feature review passed.
-
-## Payloads
-
-Feature review:
-
-\`\`\`json
-{
-  "featureReviewDepth": "standard",
-  "featureReview": {
-    "status": "passed",
-    "summary": "Reviewed changed runtime files and focused tests; validation covers the new gate.",
-    "blockingFindings": []
-  }
-}
-\`\`\`
-
-Failed feature review:
-
-\`\`\`json
-{
-  "featureReviewDepth": "detailed",
-  "featureReview": {
-    "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.
-`;
-
-// skills/flow-review/SKILL.md
-var SKILL_default5 = `---
-name: flow-review
-description: "Use when Flow work needs a review verdict in the v4 runtime: a completed feature awaiting its featureReview, a final session review, or an assigned review slice. Validation evidence gathering stays in flow-test; cleanup judgment stays in flow-deslop."
----
-
-# 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, 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 the Flow loop (the \`flow\` or
-  \`flow-run\` skills, or a bundled public Flow command) 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.
-- Prefer the manager's compact review packet over parent-session memory. The
-  packet should name the active feature, minimum \`reviewDepth\`, changed files,
-  diff summary, validation evidence, and targeted paths or risk lenses. If the
-  packet is missing important scope or evidence, record that as a coverage gap
-  or blocker instead of searching the full conversation transcript.
-- Read the approved plan fields relevant to the work: \`requirements\`, \`decisions\`, feature \`targets\`, feature \`validation\`, and dependencies.
-- For final review, also compare the original goal, full feature list, completed
-  feature evidence, changed artifacts, and final validation against the
-  convergence checklist in \`references/review-rubric.md\`.
-- Inspect the actual diff, changed files, tests, and validation output. Do not review only the completion summary.
-- 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
-
-- **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 a packet the manager can copy into
-\`flow_feature_complete\`:
-
-\`\`\`json
-{
-  "featureReviewDepth": "standard",
-  "featureReview": {
-    "status": "passed",
-    "summary": "what was reviewed and why it is acceptable",
-    "blockingFindings": []
-  }
-}
-\`\`\`
-
-\`featureReviewDepth\` must be at least the feature's planned \`reviewDepth\`.
-Use the actual depth performed: \`quick\`, \`standard\`, or \`detailed\`.
-
-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: 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 (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. Write its pass manifest before fan-out and apply its Stage 6
-  handoff acceptance and verification tiers; only the manager
-  returns the final \`featureReview\` or \`finalReview\` payload. If that reference
-  is unavailable in the current context (for example in a bundled public Flow
-  command that does not include it), review serially and record the skipped
-  fan-out as a coverage gap instead of improvising worker contracts. 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.
-`;
-
-// 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.
-
-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.
-`;
-
-// skills/flow-run/references/validation-rubric.md
-var validation_rubric_default = `# 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 the verification stage of \`../../flow/references/parallel-orchestration.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.
-`;
-
-// skills/flow-run/SKILL.md
-var SKILL_default6 = '---\nname: flow-run\ndescription: "Use when an approved Flow plan has a feature to implement, validate, or complete in the v4 runtime, and the work is scoped to one active feature. For planning a goal first use flow-plan; for the full goal-to-completion loop or resuming a session use flow."\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- If `flow_status` returns a `session.resumePacket` or\n  `session.budget.phaseBoundary`, stop the current autonomous loop and report\n  the resume instructions. Only call `flow_run_start` with\n  `phaseBoundaryAck: true` at the start of a fresh user invocation that is\n  explicitly resuming the Flow session; do not acknowledge a boundary inside\n  the same uninterrupted loop that created it.\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- Helper rule: when a named helper skill is unavailable, record the gap and\n  keep the corresponding claims conservative instead of simulating its checks.\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- Treat the feature\'s `reviewDepth` as the minimum feature-review depth that\n  must be recorded in `flow_feature_complete`.\n- For broad, risky, or multi-target work, record an implementation pass\n  decision before editing: `serial`, `candidate-exact-path`,\n  `candidate-worktree`, `tournament`, or `skipped`. Use\n  `../flow/references/parallel-orchestration.md` for the decision rules,\n  manifest fields, and compact `orchestrationPasses` record.\n- Classify `candidateEligibility` (`eligible`, `not_eligible`, or `unknown`)\n  and `candidateDecision` (`used`, `skipped`, or `serial_required`) separately;\n  implementation decisions must use `eligible` or `not_eligible` and always set\n  an explicit `decision`. The valid pairings and the candidate execution\n  evidence rules are in `../flow/references/parallel-orchestration.md` under\n  "Implementation pass decision" — follow that reference when composing the\n  record.\n- Record structured `decisionFactors`: `shared_state`, `overlapping_files`,\n  `small_slice`, `needs_manager_judgment`, `independent_surface`, and\n  `validation_available`.\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- Do not stage, commit, push, amend, rebase, publish, or mutate releases as part\n  of feature execution. If the user explicitly asks for commit preparation, load\n  `flow-commit` only after `flow_feature_complete` has been recorded, unless the\n  user explicitly asks for a WIP commit path. Keep Git boundaries separate from\n  Flow state recording.\n\n## Validate\n\n- For complex validation, regression-sensitive changes, browser QA, route QA,\n  failure-prone checks, unclear coverage, exploratory QA, or\n  `validationRun` summarization, load `flow-test` (helper rule applies).\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.\nWrite its pass manifest before fan-out, paste the matching handoff template\nfrom `../flow/references/handoff-format.md` into every worker prompt, and\napply its verification tiers to the handoffs that come back.\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 or rejects, validates, and records Flow state serially. Record whether a\ncandidate was `accepted`, `modified`, or `rejected`.\nWhen a candidate pass or serial/skipped implementation decision materially\nshaped the feature, include its compact record in\n`flow_feature_complete.orchestrationPasses`. Do not paste full worker handoffs\nor long logs into the runtime payload.\n\n## Review and complete\n\nBefore `flow_feature_complete`, obtain a `featureReview` payload. Load\n`flow-review`; for read-only subagent reviews, the manager receives the review\npacket and records both `featureReviewDepth` and `featureReview`.\n\nSend reviewers a compact review packet. Do not rely on the accumulated parent\nconversation. Include only:\n\n- active feature id, title, summary, `reviewDepth`, targets, validation, and dependencies\n- relevant plan requirements, decisions, and final review policy\n- changed files and a short diff summary\n- validation evidence with exact commands, status, and observed result\n- targeted paths or risk lenses the reviewer must inspect\n\nIf the review returns `status: "failed"`, do not fix inside the review pass.\nRecord the failed attempt by calling `flow_feature_complete` with the otherwise\nprepared completion payload, the failed `featureReview`, and the attempted\n`featureReviewDepth`; the runtime will reject completion and update the retry\nbudget. Default to stopping and reporting the blocker. When the user already\nauthorized autonomous implementation, make at most one repair and run one retry\nreview. If the retry fails or the runtime reports review retry budget\nexhausted, stop with the blocker.\n\nIf `flow_status` reports `setup.skills` or `flow-review` cannot be loaded, do\nnot record a Flow-gated `featureReview` or `finalReview`. You may perform an\nadvisory review using available context or the bundled review fallback provided\nby plugin config, then complete with `status: "needs_input"` if review evidence\nis required to proceed.\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  "featureReviewDepth": "standard",\n  "featureReview": { "status": "passed", "summary": "review summary", "blockingFindings": [] },\n  "orchestrationPasses": [\n    {\n      "id": "active-feature-id-implementation-decision",\n      "kind": "implementation-decision",\n      "decision": "serial",\n      "decisionReason": "Shared contract edits made worker ownership unsafe.",\n      "candidateEligibility": "not_eligible",\n      "candidateDecision": "serial_required",\n      "decisionFactors": ["shared_state", "overlapping_files"],\n      "writeScope": "manager-serial",\n      "verificationStatus": "not-needed",\n      "outcome": "accepted"\n    }\n  ]\n}\n```\n\nIf `flow_feature_complete` returns a `session.resumePacket` or\n`session.budget.phaseBoundary`, stop after reporting the compact handoff. If\ngenuinely blocked, call `flow_feature_complete` with `status: "needs_input"` and\nan `outcome` that explains the blocker and next step. Never fabricate validation\nor review evidence to force progress.\n';
-
-// skills/flow-test/SKILL.md
-var SKILL_default7 = `---
-name: flow-test
-description: Choose, run, and summarize validation checks for Flow features. Use when selecting validation coverage, running tests or browser/e2e QA, classifying test failures, or preparing validationRun evidence for flow_feature_complete. Visual design judgment stays in flow-ui-quality and review verdicts stay in flow-review.
----
-
-# Flow Test
-
-Use this skill to decide and gather validation evidence. It produces validation
-evidence only: the manager still owns \`flow_feature_complete\`, review payloads,
-plan approval, session closure, and every other Flow state change.
-
-Do not mutate \`.flow/**\`, approve plans, complete features, close sessions, or
-substitute for \`flow-review\`. If Flow tools are unavailable, this skill can still
-produce an advisory validation plan or test summary, but it cannot record Flow
-state.
-
-## Inputs
-
-Start from the smallest concrete surface:
-
-- The approved feature \`summary\`, \`targets\`, and \`validation\` entries when a
-  Flow session exists.
-- The actual diff, changed files, package scripts, docs, and test conventions.
-- Recent command output from this session or from a trusted worker handoff.
-- Any user-stated acceptance criteria, browser target, fixture, or environment
-  constraint.
-
-Prefer repository scripts and local conventions over invented commands. If a
-command has not been run in this session or directly reported by a trusted
-worker with raw outcome, recommend it instead of claiming it passed.
-
-## Select Coverage
-
-Choose checks from changed-surface risk, not from habit:
-
-- **Targeted behavior**: unit, integration, CLI, route, or component tests that
-  exercise the changed behavior and would fail without the fix.
-- **Integration and persistence**: database, filesystem, API, adapter, lock, or
-  serialization paths touched by the feature.
-- **Browser or e2e**: user-visible workflows, responsive states, accessibility
-  basics, form flows, and screenshots when a local target and browser tooling
-  are available.
-- **Package and build shape**: typecheck, lint, build, generated distribution,
-  or schema checks when public contracts, bundling, or package exports changed.
-- **Docs and mechanical edits**: markdown rendering, link/path sanity, spelling
-  of commands, or the narrowest project check when behavior is unchanged.
-- **Cleanup/refactor**: behavior-preservation tests plus the relevant broad
-  check; formatting alone is not evidence of preserved behavior.
-- **Final feature**: the repository's broad gate, full relevant suite, build, or
-  equivalent release gate before \`validationScope: "broad"\` is recorded.
-
-If the planned coverage is weaker than the risk, say so explicitly and list the
-missing evidence.
-
-## Run Discipline
-
-For each check:
-
-1. State the hypothesis: what behavior or contract the check is expected to
-   prove.
-2. Run the command or manual workflow when the environment allows it.
-3. Record exact command, status, and observed result.
-4. If it fails, classify the failure before editing:
-   - product failure
-   - test failure
-   - environment failure
-   - pre-existing failure
-   - flake
-   - unrelated failure
-5. Before a fix attempt, write a short failure hypothesis that names the likely
-   cause and the file or behavior to inspect.
-6. After a fix, rerun the failing check and one appropriate regression check.
-
-Do not trim failure output so far that the manager cannot understand the
-failure. Do redact secrets and credentials.
-
-## Browser and Exploratory QA
-
-For meaningful UI or browser workflow changes, browser evidence is expected when
-a local target can run:
-
-- Open the relevant route or story with the available browser tooling.
-- Exercise the main changed workflow, not only page load.
-- Check desktop and mobile breakpoints when responsive behavior is in scope.
-- Capture screenshots or describe the viewport, route, steps, and observed
-  result.
-- Inspect visible error states, empty states, long labels, focus behavior, and
-  console or network failures when the tooling exposes them.
-
-Browser claims are evidence requirements, not guaranteed coverage. If browser
-tooling, credentials, seed data, or a local server is unavailable, record the
-gap and provide the next-best evidence such as component tests, build output, or
-static inspection.
-
-Exploratory QA should be scenario-based. Name the user path, the state varied,
-and the expected outcome. Do not replace automated evidence with exploratory QA
-when a practical automated check exists.
-
-## Output
-
-Return a concise validation summary and a \`validationRun\` array that the manager
-can record through \`flow_feature_complete\` if it accepts the evidence:
-
-\`\`\`json
-{
-  "validationRun": [
-    {
-      "command": "bun test tests/foo.test.ts",
-      "status": "passed",
-      "summary": "3 pass; covered foo creation, duplicate rejection, and reset behavior"
-    }
-  ],
-  "testSummary": "Targeted behavior and package shape passed. Browser evidence was not applicable.",
-  "gaps": []
-}
-\`\`\`
-
-Only passing checks belong in \`validationRun\` for completion. Failed, skipped,
-or unavailable checks belong in \`testSummary\`, \`gaps\`, or a blocker outcome.
-Each summary must state what behavior, file set, route, command, or state was
-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.
-`;
-
-// skills/flow-ui-quality/references/ui-rubric.md
-var ui_rubric_default = `# 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.
-`;
-
-// 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.
-
-## 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.
-`;
-
-// 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, screenshot assessment, and avoiding generic AI-generated UI. Browser-run mechanics and validationRun summaries stay in flow-test.
----
-
-# 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.
-
-This is a helper skill: it contributes UI judgment and visual evidence only. The manager owns every state-changing \`flow_*\` call.
-
-## 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.
-- For browser-driven QA, route selection, failure classification, and
-  \`validationRun\` summaries, load \`flow-test\`. Keep visual judgment, design
-  quality, and screenshot assessment in \`flow-ui-quality\`.
-- 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.
-`;
-
-// 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-example.md",
-        content: parallel_pass_example_default
-      },
-      {
-        relativePath: "references/handoff-format.md",
-        content: handoff_format_default
-      }
-    ]
-  },
-  {
-    name: "flow-plan",
-    files: [
-      { relativePath: "SKILL.md", content: SKILL_default4 },
-      {
-        relativePath: "references/planning-examples.md",
-        content: planning_examples_default
-      },
-      {
-        relativePath: "references/plan-quality-checklist.md",
-        content: plan_quality_checklist_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 }]
-  }
+import { constants } from "node:fs";
+import {
+  lstat,
+  mkdir,
+  open,
+  readdir,
+  rename
+} from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, normalize, sep } from "node:path";
+
+// src/guidance/ids.ts
+var FLOW_GUIDANCE_TOPICS = [
+  "flow",
+  "flow-plan",
+  "flow-run",
+  "flow-test",
+  "flow-review",
+  "flow-deslop",
+  "flow-ui-quality",
+  "flow-commit"
 ];
 
-// src/distribution/sync.ts
-var MARKER_FILENAME = ".flow-skill-version";
-var BACKUP_FILE_PATTERN = /\.backup\.([0-9a-f]{12})(?:\.\d+)?$/;
-function backupHashFromName(relativePath) {
-  return BACKUP_FILE_PATTERN.exec(relativePath)?.[1] ?? null;
-}
-async function isFlowCreatedBackup(folder, relativePath) {
-  const namedHash = backupHashFromName(relativePath);
-  if (!namedHash)
-    return false;
-  const content = await optionalRead(resolveSkillFile(folder, relativePath));
-  if (content === null)
-    return false;
-  return sha256(content).slice(0, 12) === namedHash;
-}
-function normalizeNewlines(value) {
-  return value.replace(/\r\n/g, `
-`);
-}
-var CHANGED_SYNC_ACTIONS = [
-  "installed",
-  "updated",
-  "updated_with_backup"
-];
-function isChangedSyncAction(action) {
-  return CHANGED_SYNC_ACTIONS.includes(action);
+// src/distribution/legacy-cleanup.ts
+var LEGACY_MARKER = ".flow-skill-version";
+var NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
+var SUPPORTED_LEGACY_MAJOR = "4";
+var SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+function configuredHome() {
+  return process.env.HOME?.trim() || process.env.USERPROFILE?.trim() || homedir();
 }
-function homeDir() {
-  const configured = process.env.HOME?.trim() || process.env.USERPROFILE?.trim();
-  return configured || homedir();
-}
-function resolveFlowSkillsRoot(home = homeDir()) {
+function resolveLegacySkillsRoot(home = configuredHome()) {
   return join(home, ".config", "opencode", "skills");
 }
-function sha256(value) {
-  return createHash("sha256").update(value).digest("hex");
+function resolveLegacyArchiveRoot(home = configuredHome()) {
+  return join(home, ".config", "opencode", "flow-legacy-skills");
 }
-function markerFor(definition, version) {
-  return [
-    `version=${version}`,
-    ...definition.files.map((file) => `file=${file.relativePath} sha256=${sha256(file.content)}`),
-    ""
-  ].join(`
-`);
+function sha256(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+function safeLegacyPath(folder, relativePath) {
+  if (!relativePath || isAbsolute(relativePath) || relativePath.includes("\\") || relativePath.split("/").some((part) => !part || part === "." || part === "..")) {
+    throw new Error(`unsafe marker path '${relativePath}'`);
+  }
+  const resolved = normalize(join(folder, ...relativePath.split("/")));
+  if (!resolved.startsWith(`${folder}${sep}`)) {
+    throw new Error(`unsafe marker path '${relativePath}'`);
+  }
+  return resolved;
 }
-async function optionalRead(path) {
+async function optionalStat(path) {
   try {
-    return await readFile(path, "utf8");
+    return await lstat(path, { bigint: false });
   } catch (error) {
-    const code = error.code;
-    if (code === "ENOENT" || code === "ENOTDIR")
+    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]);
+async function readRegularFileWithoutFollowing(path) {
+  let handle;
+  try {
+    const pathMetadata = await lstat(path);
+    if (pathMetadata.isSymbolicLink()) {
+      throw new Error(`symbolic link refused: ${path}`);
+    }
+    if (!pathMetadata.isFile())
+      throw new Error(`not a regular file: ${path}`);
+    handle = await open(path, constants.O_RDONLY | NO_FOLLOW);
+    const metadata = await handle.stat();
+    if (!metadata.isFile())
+      throw new Error(`not a regular file: ${path}`);
+    if (metadata.dev !== pathMetadata.dev || metadata.ino !== pathMetadata.ino) {
+      throw new Error(`file changed while cleanup was running: ${path}`);
     }
+    return await handle.readFile({ encoding: "utf8" });
+  } catch (error) {
+    if (error.code === "ELOOP") {
+      throw new Error(`symbolic link refused: ${path}`);
+    }
+    throw error;
+  } finally {
+    await handle?.close();
   }
-  return files;
 }
-function parseMarkerVersion(content) {
-  if (!content)
-    return null;
+function parseMarker(content) {
+  let version;
+  const files = new Map;
   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;
+    if (!line)
+      continue;
+    const versionMatch = /^version=(.+)$/.exec(line);
+    if (versionMatch?.[1]) {
+      if (version)
+        throw new Error("marker contains duplicate versions");
+      version = versionMatch[1];
+      continue;
     }
-  }
-}
-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);
-  if (markerContent === null) {
-    for (const file of definition.files) {
-      const existing = await optionalRead(resolveSkillFile(folder, file.relativePath));
-      if (existing !== null) {
-        return { name: definition.name, action: "skipped_foreign" };
+    const fileMatch = /^file=(.+) sha256=([a-f0-9]{64})$/.exec(line) ?? /^file=(.+)=sha256:([a-f0-9]{64})$/.exec(line);
+    if (fileMatch?.[1] && fileMatch[2]) {
+      if (files.has(fileMatch[1])) {
+        throw new Error(`marker contains duplicate file '${fileMatch[1]}'`);
       }
-    }
-  }
-  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)
+      files.set(fileMatch[1], fileMatch[2]);
       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)
+    const topLevelHash = /^hash=sha256:([a-f0-9]{64})$/.exec(line);
+    if (topLevelHash?.[1] && !files.has("SKILL.md")) {
+      files.set("SKILL.md", topLevelHash[1]);
       continue;
-    changed = true;
-    if (sha256(existing) !== recordedHash) {
-      backupPaths.push(await writeBackup(path, existing));
     }
-    await rm(path, { force: true });
-  }
-  if (!changed && markerContent !== null && normalizeNewlines(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");
+    throw new Error(`marker contains an invalid line: '${line}'`);
+  }
+  if (!version)
+    throw new Error("marker has no version");
+  if (!files.has("SKILL.md"))
+    throw new Error("marker does not own SKILL.md");
+  return { version, files };
+}
+function assertSupportedLegacyVersion(version) {
+  const match = SEMVER_PATTERN.exec(version);
+  if (!match) {
+    throw new Error(`marker version '${version}' is not a valid semantic version`);
+  }
+  if (match[1] !== SUPPORTED_LEGACY_MAJOR) {
+    throw new Error(`marker version '${version}' is outside the supported legacy range >=4.0.0 <5.0.0`);
+  }
+}
+function expectedDirectoryEntries(marker) {
+  const entries = new Map([
+    ["", new Set([LEGACY_MARKER])]
+  ]);
+  for (const relativePath of marker.files.keys()) {
+    const parts = relativePath.split("/");
+    let parent = "";
+    for (let index = 0;index < parts.length; index += 1) {
+      const part = parts[index];
+      if (!part)
+        throw new Error(`unsafe marker path '${relativePath}'`);
+      const children = entries.get(parent) ?? new Set;
+      children.add(part);
+      entries.set(parent, children);
+      if (index < parts.length - 1) {
+        parent = parent ? `${parent}/${part}` : part;
+        if (!entries.has(parent))
+          entries.set(parent, new Set);
+      }
+    }
   }
-  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`;
+  return entries;
 }
-function resolveFlowPluginVersion() {
-  if (process.env.npm_package_version)
-    return process.env.npm_package_version;
+async function inspectLegacyFolder(name, folder) {
+  const metadata = await optionalStat(folder);
+  if (!metadata)
+    return { name, path: folder, status: "absent" };
+  if (!metadata.isDirectory()) {
+    return {
+      name,
+      path: folder,
+      status: "refused",
+      reason: "path is not a real directory"
+    };
+  }
   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"));
-    const backupFiles = markerContent === null ? [] : await listFlowBackupFiles(folder);
-    if (existingSkill === null) {
-      return {
-        name: definition.name,
-        path: folder,
-        status: "missing",
-        markerVersion,
-        missingFiles: definition.files.map((file) => file.relativePath),
-        editedFiles: [],
-        outdatedFiles: [],
-        backupFiles
-      };
-    }
-    if (markerContent === null) {
-      return {
-        name: definition.name,
-        path: folder,
-        status: "foreign",
-        markerVersion,
-        missingFiles: [],
-        editedFiles: [],
-        outdatedFiles: [],
-        backupFiles
-      };
-    }
-    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;
+    const markerPath = join(folder, LEGACY_MARKER);
+    const marker = parseMarker(await readRegularFileWithoutFollowing(markerPath));
+    assertSupportedLegacyVersion(marker.version);
+    const directories = expectedDirectoryEntries(marker);
+    for (const [relativeDirectory, expectedEntries] of directories) {
+      const directory = relativeDirectory ? safeLegacyPath(folder, relativeDirectory) : folder;
+      const directoryMetadata = await optionalStat(directory);
+      if (!directoryMetadata?.isDirectory()) {
+        throw new Error(`expected real directory: ${relativeDirectory || "."}`);
+      }
+      const actualEntries = await readdir(directory);
+      const unexpected = actualEntries.filter((entry) => !expectedEntries.has(entry));
+      const missing = [...expectedEntries].filter((entry) => !actualEntries.includes(entry));
+      if (unexpected.length > 0 || missing.length > 0) {
+        throw new Error([
+          unexpected.length > 0 ? `unexpected entries: ${unexpected.join(", ")}` : "",
+          missing.length > 0 ? `missing entries: ${missing.join(", ")}` : ""
+        ].filter(Boolean).join("; "));
       }
-      if (existing === file.content)
-        continue;
-      const recordedHash = markerHashes.get(file.relativePath);
-      if (recordedHash && sha256(existing) !== recordedHash) {
-        editedFiles.push(file.relativePath);
-        continue;
+    }
+    for (const [relativePath, expectedHash] of marker.files) {
+      const path = safeLegacyPath(folder, relativePath);
+      const content = await readRegularFileWithoutFollowing(path);
+      if (sha256(content) !== expectedHash) {
+        throw new Error(`edited file refused: ${relativePath}`);
       }
-      outdatedFiles.push(file.relativePath);
     }
-    const markerDrift = normalizeNewlines(markerContent) !== markerFor(definition, version);
-    const status = missingFiles.length > 0 ? "incomplete" : editedFiles.length > 0 ? "edited" : markerDrift || outdatedFiles.length > 0 ? "outdated" : "ok";
     return {
-      name: definition.name,
+      name,
       path: folder,
-      status,
-      markerVersion,
-      missingFiles,
-      editedFiles,
-      outdatedFiles,
-      backupFiles
+      status: "eligible"
     };
-  }));
-  let entries = [];
-  try {
-    entries = await readdir(root);
   } catch (error) {
-    if (error.code !== "ENOENT")
-      throw error;
+    return {
+      name,
+      path: folder,
+      status: "refused",
+      reason: error instanceof Error ? error.message : String(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) || skill.backupFiles.length > 0).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 (skill.backupFiles.length > 0) {
-      lines.push(`  backups: ${skill.backupFiles.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.");
-    if (report.skills.some((skill) => skill.backupFiles.length > 0)) {
-      lines.push("- Flow saved earlier local edits as .backup files; review each one and delete it once the saved copy is no longer needed. Sync ignores them, and uninstall removes them (naming each) along with the folder.");
+async function ensureRealArchiveRoot(path) {
+  const existing = await optionalStat(path);
+  if (existing) {
+    if (!existing.isDirectory()) {
+      throw new Error(`Legacy archive path is not a real directory: ${path}`);
     }
+    return;
   }
-  lines.push(`- Details command: ${formatFlowDoctorCommand(report.version)}`);
-  return `${lines.join(`
-`)}
-`;
-}
-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 listFlowBackupFiles(folder) {
-  let names;
   try {
-    names = await listSkillFolderFiles(folder);
+    await mkdir(path, { mode: 448 });
   } catch (error) {
-    if (error.code === "ENOENT")
-      return [];
-    throw error;
-  }
-  const backups = [];
-  for (const name of names) {
-    if (await isFlowCreatedBackup(folder, name))
-      backups.push(name);
+    if (error.code !== "EEXIST")
+      throw error;
+    const raced = await optionalStat(path);
+    if (!raced?.isDirectory()) {
+      throw new Error(`Legacy archive path is not a real directory: ${path}`);
+    }
   }
-  return backups;
 }
-async function inspectManagedFolderForUninstall(folder, markerContent) {
-  const hashes = parseMarkerFiles(markerContent);
-  if (hashes.size === 0)
-    return { pristine: false, backups: [] };
-  const backups = [];
-  for (const relativePath of await listSkillFolderFiles(folder)) {
-    if (relativePath === MARKER_FILENAME)
-      continue;
-    const recordedHash = hashes.get(relativePath);
-    if (recordedHash !== undefined) {
-      const content = await optionalRead(resolveSkillFile(folder, relativePath));
-      if (content === null || sha256(content) !== recordedHash) {
-        return { pristine: false, backups };
-      }
-      continue;
-    }
-    if (await isFlowCreatedBackup(folder, relativePath)) {
-      backups.push(relativePath);
+async function cleanupLegacySkills(options) {
+  const home = options?.home ?? configuredHome();
+  const root = resolveLegacySkillsRoot(home);
+  const archiveRoot = resolveLegacyArchiveRoot(home);
+  const apply = options?.apply === true;
+  const results = [];
+  let archiveReady = false;
+  for (const name of FLOW_GUIDANCE_TOPICS) {
+    const path = join(root, name);
+    const inspected = await inspectLegacyFolder(name, path);
+    if (!apply || inspected.status !== "eligible") {
+      results.push(inspected);
       continue;
     }
-    return { pristine: false, backups };
-  }
-  return { pristine: true, backups };
-}
-async function uninstallFlowSkills(home = homeDir(), options = {}) {
-  const root = resolveFlowSkillsRoot(home);
-  const removed = [];
-  const kept = [];
-  const removedBackups = [];
-  let entries;
-  try {
-    entries = await readdir(root);
-  } catch (error) {
-    if (error.code === "ENOENT") {
-      return { removed, kept, removedBackups };
+    if (!archiveReady) {
+      await ensureRealArchiveRoot(archiveRoot);
+      archiveReady = true;
     }
-    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) {
-      kept.push(folder);
+    const archivePath = join(archiveRoot, `${name}-${new Date().toISOString().replaceAll(":", "-")}-${crypto.randomUUID()}`);
+    try {
+      await rename(path, archivePath);
+    } catch (error) {
+      if (error.code !== "ENOENT")
+        throw error;
+      results.push({
+        name,
+        path,
+        status: "refused",
+        reason: "folder changed while cleanup was running"
+      });
       continue;
     }
-    const { pristine, backups } = await inspectManagedFolderForUninstall(folder, markerContent);
-    if (!pristine) {
-      kept.push(folder);
+    await options?.afterQuarantine?.({ name, path, archivePath });
+    const verified = await inspectLegacyFolder(name, archivePath);
+    if (verified.status !== "eligible") {
+      results.push({
+        name,
+        path,
+        status: "quarantined",
+        reason: "folder changed while cleanup was running; preserved for manual recovery",
+        archivePath
+      });
       continue;
     }
-    for (const backup of backups) {
-      removedBackups.push(resolveSkillFile(folder, backup));
-    }
-    if (!options.dryRun) {
-      await rm(folder, { recursive: true, force: true });
-    }
-    removed.push(folder);
+    results.push({
+      name,
+      path,
+      status: "archived",
+      archivePath
+    });
   }
-  return { removed, kept, removedBackups };
+  return {
+    mode: apply ? "apply" : "dry-run",
+    root,
+    archiveRoot,
+    results
+  };
+}
+
+// src/version.ts
+import { createRequire } from "node:module";
+function resolveFlowPluginVersion() {
+  try {
+    const require2 = createRequire(import.meta.url);
+    const manifest = require2("../package.json");
+    if (manifest.version)
+      return manifest.version;
+  } catch {}
+  return "0.0.0";
 }
 
 // src/cli.ts
 function usage() {
   return [
-    "usage: opencode-plugin-flow <doctor|sync|uninstall> [options]",
+    "usage: opencode-plugin-flow legacy-cleanup <--dry-run|--apply> [--json]",
     "",
     "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",
+    "  legacy-cleanup      Inspect or archive marker-proven legacy global Flow skills",
     "",
-    "uninstall options:",
-    "  --dry-run           Preview removals without deleting anything",
-    "",
-    "global options:",
+    "options:",
+    "  --dry-run           Report eligible folders without changing the filesystem",
+    "  --apply             Move eligible folders to a recoverable archive outside skill discovery",
+    "                      Cleanup never deletes legacy folders",
+    "  --json              Write the report as JSON",
     "  --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) {
+function writeReport(report, json) {
+  if (json) {
     process.stdout.write(`${JSON.stringify(report, null, 2)}
 `);
     return;
   }
-  process.stdout.write(formatFlowSkillDoctor(report));
+  process.stdout.write(`Flow legacy skill cleanup (${report.mode})
+`);
+  process.stdout.write(`- legacy root: ${report.root}
+`);
+  process.stdout.write(`- archive root: ${report.archiveRoot}
+`);
+  for (const result of report.results) {
+    process.stdout.write(`- ${result.name}: ${result.status}
+`);
+    if (result.reason)
+      process.stdout.write(`  reason: ${result.reason}
+`);
+    if (result.archivePath) {
+      const label = result.status === "archived" ? "archived" : "preserved";
+      process.stdout.write(`  ${label} at: ${result.archivePath}
+`);
+    }
+  }
 }
 async function main(argv) {
-  const command = argv[2];
-  const flags = argv.slice(3);
+  const [command, ...flags] = argv.slice(2);
   if (command === "--help" || command === "-h") {
     process.stdout.write(`${usage()}
 `);
@@ -2777,86 +352,21 @@ async function main(argv) {
 `);
     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) {
+  const knownFlags = new Set(["--dry-run", "--apply", "--json"]);
+  const validFlags = flags.every((flag) => knownFlags.has(flag));
+  const dryRun = flags.includes("--dry-run");
+  const apply = flags.includes("--apply");
+  if (command !== "legacy-cleanup" || !validFlags || dryRun === apply) {
     process.stderr.write(`${usage()}
 `);
     process.exitCode = 2;
     return;
   }
-  if (command === "sync") {
-    const version = resolveFlowPluginVersion();
-    const results = await syncFlowSkills(version);
-    const changed = results.filter((result2) => isChangedSyncAction(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}
-`);
-  }
-  if (result.removedBackups.length > 0) {
-    process.stdout.write(`${dryRun ? "Would remove" : "Removed"} Flow-created backup files holding your earlier edits:
-`);
-    for (const path of result.removedBackups) {
-      process.stdout.write(`  ${path}
-`);
-    }
+  const report = await cleanupLegacySkills({ apply });
+  writeReport(report, flags.includes("--json"));
+  if (apply && report.results.some((result) => ["refused", "quarantined"].includes(result.status))) {
+    process.exitCode = 1;
   }
-  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)}
@@ -2864,4 +374,4 @@ main(process.argv).catch((error) => {
   process.exitCode = 1;
 });
 
-//# debugId=6088D1387043CD7A64756E2164756E21
+//# debugId=690F8C77CD4F802F64756E2164756E21