opencode-plugin-flow 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Douwe de Vries
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# Flow Plugin for OpenCode
+
+`opencode-plugin-flow` adds a resumable planning, execution, validation, and review workflow to OpenCode. Use it when a task is important enough that you want a plan, recorded validation evidence, review gates, and a clear way to resume later.
+
+Flow is skills-first: four hand-authored skills carry the workflow guidance, and a small plugin provides durable `.flow/**` session state plus a few hard, code-enforced invariants.
+
+## Quick start
+
+Install Flow, open OpenCode in the project you want to work on, then run:
+
+```text
+/flow-auto <your goal>
+```
+
+Common examples:
+
+```text
+/flow-auto Add CSV export to the reports page
+/flow-plan Refactor the authentication middleware
+/flow-review Review this repository for release risks
+/flow-status
+```
+
+Flow creates a tracked session under `.flow/**`, drafts a plan, executes one feature at a time, records validation evidence, reviews, and either continues, recovers, or stops with a concrete blocker.
+
+## Install
+
+Add Flow to the `plugin` array in your `opencode.json` (global `~/.config/opencode/opencode.json` or per-project):
+
+```json
+{
+  "plugin": ["opencode-plugin-flow@3"]
+}
+```
+
+OpenCode installs the package from npm on startup. Pin the major version you install (currently `@3`) so restarts pick up fixes without crossing a breaking release.
+
+On startup the plugin syncs its global skills into `~/.config/opencode/skills/`:
+
+```text
+flow/SKILL.md          # the driving loop: status → plan → run → review → repeat
+flow-plan/SKILL.md     # decomposition heuristics, feature sizing, approval criteria
+flow-run/SKILL.md      # one-feature discipline, validation evidence standards
+flow-review/SKILL.md   # review depth criteria, finding taxonomy, report format
+```
+
+**Restart OpenCode once after the first install or after an update** so freshly synced skills are discovered.
+
+Skill sync is ownership-aware: each Flow-owned skill folder carries a `.flow-skill-version` marker with a sha256 line per shipped file. Folders without the marker are never touched, and if you edit a Flow-owned file by hand — `SKILL.md` or a `references/` file — the previous content is backed up next to it (`SKILL.md.backup`, `references/<name>.md.backup`) before an update replaces it.
+
+### Per-project skill overrides
+
+Skills are plain markdown and deliberately overridable. To customize Flow's behavior for one project — for example a team-specific planning or review rubric — place a project-local skill at:
+
+```text
+.opencode/skills/flow-plan/SKILL.md
+```
+
+OpenCode's project skill takes precedence over the global one. This is a supported feature, not a hack: edit the global synced copy for personal defaults (it will be backed up on update), or commit a project override for team conventions.
+
+### Upgrading from the pre-npm (curl) install
+
+Releases before 2.1.0 installed a bundled plugin file at `~/.config/opencode/plugins/flow.js`. Once you add the npm plugin entry, that copy would load Flow twice — the plugin warns about this at startup. Remove it with the uninstall command below.
+
+### Uninstall
+
+```bash
+bunx opencode-plugin-flow uninstall
+```
+
+This removes the Flow-owned global skill folders (those carrying the Flow marker) and a pre-npm `flow.js` copy if one exists, then reminds you to remove `"opencode-plugin-flow"` from the `plugin` array in `opencode.json`. Skills you created yourself are never deleted. Use `--dry-run` to preview.
+
+## Skills, commands, and tools
+
+### The four skills
+
+| Skill | What it carries |
+| --- | --- |
+| `flow` | The driving loop: check status, plan, run, review, repeat; stop conditions, when to ask the user, recovery playbook. |
+| `flow-plan` | How to decompose work into features, size them, profile the repo, and when a plan is safe to auto-approve. |
+| `flow-run` | One-feature-at-a-time discipline and what counts as validation evidence. |
+| `flow-review` | Review depth criteria, finding taxonomy, and report format. |
+
+Deeper methodology (worked plan examples, validation and review rubrics) lives in `references/` files next to the `flow-plan`, `flow-run`, and `flow-review` skills and is loaded only when needed.
+
+### Commands
+
+Commands are thin pointers into the skills — the skill content is the real instruction surface. Command names are stable across the v2 → v3 upgrade.
+
+| Command | Use it when... |
+| --- | --- |
+| `/flow-auto <goal>` | You want Flow to drive the whole loop — plan, run, validate, review — until completion or a real blocker. Run without a goal to resume. |
+| `/flow-plan <goal>` | You want to create, inspect, or shape the plan before execution. |
+| `/flow-run [feature-id]` | You want to execute exactly one approved feature. |
+| `/flow-review <goal>` | You want a read-only review and findings report (runs in the fresh-context `flow-reviewer` subagent). |
+| `/flow-status` | You want session state, readiness checks, and the suggested next step. |
+| `/flow-doctor` | You want the workspace readiness checks with remediation steps (same `flow_status` view, doctor framing). |
+| `/flow-history` | You want to list saved sessions. |
+| `/flow-session activate <id>` / `close <completed\|deferred\|abandoned>` / `show <id>` | You want to switch, close, or inspect sessions. |
+| `/flow-reset <feature-id>` | You want to reset a feature back to pending (convenience over `flow_feature_complete` with `reset: true`). |
+
+### Tools
+
+The plugin registers a small tool surface (7 tools) that owns all `.flow/**` mutations:
+
+| Tool | Purpose |
+| --- | --- |
+| `flow_status` | Session state, doctor-style readiness, and a computed suggested next step. |
+| `flow_plan_save` | Create or update the draft plan (planning context plus features). |
+| `flow_plan_approve` | Approve the plan, optionally restricted to a feature subset. |
+| `flow_run_start` | Start the next runnable feature. |
+| `flow_feature_complete` | Record a validated feature result; also handles feature reset. |
+| `flow_review_record` | Record a reviewer decision (`scope: feature` or `final`). |
+| `flow_session` | Activate or close a session, list history, or show a stored session. |
+
+These seven tools are the whole canonical surface. For one minor cycle, the retired v2 tool names (for example `flow_run_complete_feature` or `flow_session_close`) remain registered as hidden redirect stubs: calling one returns an error naming its replacement and the key arguments, so resumed v2 sessions and old transcripts degrade gracefully instead of failing on an unknown tool. The stubs are scheduled for removal in v3.1. Existing v2 sessions migrate seamlessly (the session schema is unchanged).
+
+### Agents
+
+Flow ships one dedicated subagent: `flow-reviewer`, a read-only reviewer used for fresh-context review passes. Its read-only boundary is enforced by OpenCode's native per-agent permissions, not by prompt text. Everything else runs in your normal agent, guided by the skills.
+
+## What the plugin enforces vs. what skills guide
+
+The plugin code enforces only hard invariants and persistence safety:
+
+1. A feature cannot be completed without recorded validation evidence.
+2. A session cannot close as `completed` with unfinished features.
+3. An approved plan cannot be mutated without an explicit reset.
+4. If the session's review policy is strict, a reviewer decision must be recorded before completion.
+
+Plus: atomic, locked, path-safe writes under `.flow/**`; schema validation of all tool payloads; and the compaction hook that keeps Flow state intact when OpenCode compacts a long session.
+
+Everything judgment-shaped — how to decompose a plan, how deep to review, what counts as good evidence, when to stop and ask — lives in the skills, where you can read and override it.
+
+## What Flow writes
+
+Flow stores workflow state in the project/worktree where OpenCode is running:
+
+```text
+.flow/active/<session-id>/session.json        # active session (source of truth)
+.flow/active/<session-id>/docs/**             # readable derived views
+.flow/stored/<session-id>/session.json        # parked resumable sessions
+.flow/completed/<session-id>-<timestamp>/**   # closed session history
+.flow/locks/
+```
+
+The JSON session files are the source of truth; markdown files are derived views. There is one active session per worktree — activating another parks the current one under `.flow/stored/**`.
+
+Flow refuses to write session state at filesystem roots or directly in `$HOME`, and asks before writing `.flow/**` under unusual workspace roots. Existing v2 sessions resume under v3 (the session schema is unchanged).
+
+## Troubleshooting
+
+```text
+/flow-doctor
+```
+
+shows the workspace readiness checks (skills in sync, no stale pre-npm copy, workspace writable) with remediation steps; `/flow-status` adds the active session state, the current blocker, and the suggested next step.
+
+## OpenCode references
+
+- Plugins: https://opencode.ai/docs/plugins
+- Skills: https://opencode.ai/docs/skills
+- Agents: https://opencode.ai/docs/agents
+
+## Releases
+
+Release notes live in [`CHANGELOG.md`](CHANGELOG.md) and under [`docs/releases/`](docs/releases/).
+
+## Working on Flow itself
+
+- Development guide: [`docs/development.md`](docs/development.md)
+- Maintainer contract: [`docs/maintainer-contract.md`](docs/maintainer-contract.md)
+- Codebase map: [`docs/contributor-map.md`](docs/contributor-map.md)
+
+### Package API boundary
+
+`opencode-plugin-flow` supports root-only imports:
+
+```ts
+import flowPlugin from "opencode-plugin-flow";
+```
+
+Deep imports such as `opencode-plugin-flow/dist/...` are intentionally not exported.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE) for the full text.

package/dist/cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import{homedir as a}from"node:os";import{readdir as k,readFile as g,rm as X,rmdir as p}from"node:fs/promises";import{dirname as f,join as Z,normalize as h,sep as m}from"node:path";import{createHash as R}from"node:crypto";import{join as x}from"node:path";var S=x(".config","opencode","skills"),O=".flow-skill-version",w="SKILL.md.backup",F=x(".config","opencode","plugins","flow.js"),C=`// Managed by flow-opencode install/uninstall
+`,I="flow-opencode-generated-skill",c=`<!-- ${I} `,P=new RegExp(`^<!-- ${I} name=([a-z0-9]+(?:-[a-z0-9]+)*) version=([0-9]+) hash=sha256:([a-f0-9]{64}) -->$`,"u");function W(j){return R("sha256").update(j,"utf8").digest("hex")}function K(j){let q=j.split(`
+`),z=q.flatMap((M,L)=>M.startsWith(c)?[L]:[]);if(z.length===0)return{kind:"not_generated"};if(z.length>1)return{kind:"invalid_generated",reason:"duplicate_marker"};let B=z[0];if(B===void 0)return{kind:"not_generated"};let J=q[B];if(J===void 0)return{kind:"invalid_generated",reason:"malformed_marker"};let Q=J.match(P);if(!Q)return{kind:"invalid_generated",reason:"malformed_marker"};let[,V,$,Y]=Q;if(V===void 0||$===void 0||Y===void 0)return{kind:"invalid_generated",reason:"malformed_marker"};let T=[...q.slice(0,B),...q.slice(B+1)].join(`
+`);if(W(T)!==Y)return{kind:"invalid_generated",reason:"hash_mismatch"};return{kind:"valid_generated",marker:{name:V,version:$,hash:Y}}}var u="opencode-plugin-flow",A="file=",D="=sha256:";function U(j){let q=new Map;for(let z of j.split(`
+`)){if(!z.startsWith(A))continue;let B=z.slice(A.length),J=B.lastIndexOf(D);if(J===-1)continue;let Q=B.slice(0,J),V=B.slice(J+D.length);if(Q.length>0&&/^[a-f0-9]{64}$/.test(V))q.set(Q,V)}return q}function _(j){let q=new Map;for(let Q of j.split(`
+`)){let V=Q.indexOf("=");if(V===-1)continue;q.set(Q.slice(0,V),Q.slice(V+1))}let z=q.get("plugin"),B=q.get("version");if(z!==u||!B)return null;let J=q.get("hash");return{plugin:z,version:B,hash:J?.startsWith("sha256:")?J.slice(7):null}}async function E({homeDir:j,dryRun:q=!1,logger:z}){let B={removedSkills:[],keptUserEditedSkills:[],removedPreNpmPlugin:null,keptForeignPreNpmPlugin:null},J=Z(j,S);for(let $ of await i(J)){if($!=="flow"&&!$.startsWith("flow-"))continue;let Y=Z(J,$),T=await d(Y);if(T==="foreign")continue;if(T==="user_edited"){B.keptUserEditedSkills.push(Y),z?.(`Kept user-edited Flow skill at ${Y}; remove it manually if it is no longer needed.`);continue}if(!q)await s(Y);B.removedSkills.push(Y),z?.(`${q?"Would remove":"Removed"} Flow skill at ${Y}.`)}let Q=Z(j,F),V=await H(Q);if(V!==null)if(V.startsWith(C)){if(!q)await X(Q,{force:!0});B.removedPreNpmPlugin=Q,z?.(`${q?"Would remove":"Removed"} pre-npm Flow plugin copy at ${Q}.`)}else B.keptForeignPreNpmPlugin=Q,z?.(`Kept ${Q}: it is not managed by Flow. Remove it manually if it is a stale Flow copy.`);return z?.('Finally, remove "opencode-plugin-flow" from the plugin array in opencode.json and restart OpenCode.'),B}async function d(j){let q=Z(j,"SKILL.md"),z=await H(q),B=await H(Z(j,O)),J=B===null?null:_(B);if(J!==null&&B!==null){for(let[$,Y]of U(B)){if($==="SKILL.md")continue;let T=N(j,$);if(T===null)continue;let M=await H(T);if(M!==null&&W(M)!==Y)return"user_edited"}if(z===null)return"pristine";if(J.hash!==null&&W(z)===J.hash)return"pristine";return K(z).kind==="valid_generated"?"pristine":"user_edited"}if(z===null)return"foreign";let Q=K(z);if(Q.kind==="valid_generated")return"pristine";if(Q.kind==="invalid_generated")return"user_edited";return"foreign"}function N(j,q){let z=h(Z(j,...q.split("/")));if(z!==j&&z.startsWith(`${j}${m}`))return z;return null}async function s(j){let q=await H(Z(j,O)),z=new Set;if(q!==null)for(let B of U(q).keys()){let J=N(j,B);if(J===null)continue;await X(J,{force:!0}),await X(`${J}.backup`,{force:!0});let Q=f(J);if(Q!==j)z.add(Q)}await X(Z(j,"SKILL.md"),{force:!0}),await X(Z(j,O),{force:!0}),await X(Z(j,w),{force:!0});for(let B of[...z].sort((J,Q)=>Q.length-J.length))await v(B);await v(j)}async function v(j){try{await p(j)}catch(q){let z=q.code;if(z!=="ENOENT"&&z!=="ENOTEMPTY")throw q}}async function i(j){try{return(await k(j,{withFileTypes:!0})).filter((z)=>z.isDirectory()).map((z)=>z.name).sort()}catch(q){if(q.code==="ENOENT")return[];throw q}}async function H(j){try{return await g(j,"utf8")}catch(q){if(q.code==="ENOENT")return null;throw q}}var b=`opencode-plugin-flow — Flow plugin lifecycle commands
+
+Usage:
+  bunx opencode-plugin-flow uninstall [--dry-run]
+
+Commands:
+  uninstall   Remove Flow-owned global skills from ~/.config/opencode/skills/
+              and the pre-npm plugin copy at ~/.config/opencode/plugins/flow.js.
+              Prints the opencode.json cleanup step; never touches files that
+              are not Flow-owned.
+
+Options:
+  --dry-run   Show what would be removed without deleting anything
+  --help      Show this message`;function y(j){process.stdout.write(`${j}
+`)}function G(j){process.stderr.write(`${j}
+`)}async function n(j){let q=[...j];if(q.length===0||q.includes("--help")||q.includes("-h"))return y(b),0;let z=q.shift();if(z!=="uninstall")return G(`Unknown command: ${z}
+
+${b}`),1;let B=!1;for(let J of q){if(J==="--dry-run"){B=!0;continue}return G(`Unknown argument: ${J}
+
+${b}`),1}return await E({homeDir:process.env.HOME??a(),dryRun:B,logger:y}),0}try{process.exitCode=await n(process.argv.slice(2))}catch(j){G(j instanceof Error?j.message:String(j)),process.exitCode=1}