{"id":48355116,"url":"https://github.com/ddv1982/flow-opencode","last_synced_at":"2026-06-13T02:01:06.929Z","repository":{"id":348383747,"uuid":"1196661711","full_name":"ddv1982/flow-opencode","owner":"ddv1982","description":"Durable planning and execution workflow plugin for OpenCode with reviewer-gated autonomous runs","archived":false,"fork":false,"pushed_at":"2026-06-12T20:09:26.000Z","size":3559,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-12T20:11:54.028Z","etag":null,"topics":["ai-coding","flow-opencode","opencode","plugin","task-orchestration","validation","workflow"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ddv1982.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-30T23:16:18.000Z","updated_at":"2026-06-12T18:18:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ddv1982/flow-opencode","commit_stats":null,"previous_names":["ddv1982/flow-opencode"],"tags_count":132,"template":false,"template_full_name":null,"purl":"pkg:github/ddv1982/flow-opencode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddv1982%2Fflow-opencode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddv1982%2Fflow-opencode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddv1982%2Fflow-opencode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddv1982%2Fflow-opencode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ddv1982","download_url":"https://codeload.github.com/ddv1982/flow-opencode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddv1982%2Fflow-opencode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34269364,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-coding","flow-opencode","opencode","plugin","task-orchestration","validation","workflow"],"created_at":"2026-04-05T11:01:16.928Z","updated_at":"2026-06-13T02:01:06.923Z","avatar_url":"https://github.com/ddv1982.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flow Plugin for OpenCode\n\n`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.\n\nFlow 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.\n\n## Quick start\n\nInstall Flow, open OpenCode in the project you want to work on, then run:\n\n```text\n/flow-auto \u003cyour goal\u003e\n```\n\nCommon examples:\n\n```text\n/flow-auto Add CSV export to the reports page\n/flow-plan Refactor the authentication middleware\n/flow-review Review this repository for release risks\n/flow-status\n```\n\nFlow 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.\n\n## Install\n\nAdd Flow to the `plugin` array in your `opencode.json` (global `~/.config/opencode/opencode.json` or per-project):\n\n```json\n{\n  \"plugin\": [\"opencode-plugin-flow@3.3.0\"]\n}\n```\n\nOpenCode installs the package from npm on the first startup and caches it per spec string under `~/.cache/opencode/packages/\u003cspec\u003e/` — it does **not** re-resolve the version on later startups. Pin an exact version and bump the pin to upgrade: a changed spec string installs fresh. See [Updating](#updating) below.\n\nOn startup the plugin syncs its global skills, commands, and review agent into OpenCode's normal discovery paths:\n\n```text\n~/.config/opencode/skills/flow/SKILL.md          # driving loop\n~/.config/opencode/skills/flow-plan/SKILL.md     # decomposition heuristics\n~/.config/opencode/skills/flow-run/SKILL.md      # validation discipline\n~/.config/opencode/skills/flow-review/SKILL.md   # review rubric\n~/.config/opencode/commands/flow-auto.md         # slash command pointers\n~/.config/opencode/agents/flow-reviewer.md       # read-only review agent\n```\n\n**Restart OpenCode once after the first install or after an update** so freshly synced skills, commands, and agents are discovered.\n\nSync is ownership-aware: each Flow-owned skill folder carries a `.flow-skill-version` marker with a sha256 line per shipped file, and each synced command/agent file has a sidecar `.flow-version` marker. Folders or files without Flow markers are never touched, and if you edit a Flow-owned file by hand the previous content is backed up next to it before an update replaces it.\n\n### Updating\n\nOpenCode never auto-updates plugins: the cached install for a given spec string is reused as-is on every startup. Flow therefore checks npm in the background after startup and logs a one-line notice when a newer release exists — it only notifies and never edits your `opencode.json`. Set `FLOW_DISABLE_UPDATE_CHECK=1` to turn the check off.\n\nTo update with an exact pin (recommended):\n\n1. Change the pin in `opencode.json` to the new version (same form as the install snippet above).\n2. Restart OpenCode once to install the new version, and a second time so the freshly re-synced skills, commands, and agents are discovered.\n\nIf you pinned a range like `@3` instead, the spec string never changes, so the cache entry must be cleared by hand before restarting:\n\n```bash\nrm -rf ~/.cache/opencode/packages/opencode-plugin-flow@3\n```\n\n`/flow-status` shows the running plugin version in its install check, so you can always confirm which version OpenCode actually loaded.\n\n### Per-project skill overrides\n\nSkills 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:\n\n```text\n.opencode/skills/flow-plan/SKILL.md\n```\n\nOpenCode'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.\n\n### Upgrading from the pre-npm (curl) install\n\nReleases 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.\n\n### Uninstall\n\n```bash\nbunx opencode-plugin-flow uninstall\n```\n\nThis removes the Flow-owned global skill folders, command files, agent files, 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`. Files you created yourself are never deleted. Use `--dry-run` to preview.\n\n## Skills, commands, and tools\n\n### The four skills\n\n| Skill | What it carries |\n| --- | --- |\n| `flow` | The driving loop: check status, plan, run, review, repeat; stop conditions, when to ask the user, recovery playbook. |\n| `flow-plan` | How to decompose work into features, size them, profile the repo, and when a plan is safe to auto-approve. |\n| `flow-run` | One-feature-at-a-time discipline and what counts as validation evidence. |\n| `flow-review` | Review depth criteria, finding taxonomy, and report format. |\n\nDeeper 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.\n\n### Commands\n\nCommands are thin pointers into the skills — the skill content is the real instruction surface.\n\n| Command | Use it when... |\n| --- | --- |\n| `/flow-auto \u003cgoal\u003e` | You want Flow to drive the whole loop — plan, run, validate, review — until completion or a real blocker. Run without a goal to resume. |\n| `/flow-plan \u003cgoal\u003e` | You want to create, inspect, or shape the plan before execution. |\n| `/flow-run [feature-id]` | You want to execute exactly one approved feature. |\n| `/flow-review \u003cgoal\u003e` | You want a read-only review and findings report (runs in the fresh-context `flow-reviewer` subagent). |\n| `/flow-status` | You want session state, readiness checks, and the suggested next step. |\n\nThese five are the whole command surface since v3.1. The v2/v3.0 convenience commands (`/flow-doctor`, `/flow-history`, `/flow-session`, `/flow-reset`) were retired: each was a thin wrapper over a single tool call that works as a plain request — \"show the flow history\", \"close this session as completed\", \"reset feature X\" — and `/flow-doctor` duplicated `/flow-status`. Startup sync removes the retired command files from earlier installs (user-edited copies are kept).\n\n### Tools\n\nThe plugin registers a small tool surface (7 tools) that owns all `.flow/**` mutations:\n\n| Tool | Purpose |\n| --- | --- |\n| `flow_status` | Session state, doctor-style readiness, and a computed suggested next step. |\n| `flow_plan_save` | Create or update the draft plan (planning context plus features). |\n| `flow_plan_approve` | Approve the plan, optionally restricted to a feature subset. |\n| `flow_run_start` | Start the next runnable feature. |\n| `flow_feature_complete` | Record a validated feature result; also handles feature reset. |\n| `flow_review_record` | Record a reviewer decision (`scope: feature` or `final`). |\n| `flow_session` | Activate or close a session, list history, or show a stored session. |\n\nThese seven tools are the whole registered surface — the v2 tool-name redirect stubs that shipped in 3.0 were removed in v3.1 as scheduled. Existing v2 sessions still migrate seamlessly (the session schema is unchanged).\n\n### Agents\n\nFlow 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.\n\n## What the plugin enforces vs. what skills guide\n\nThe plugin code enforces only hard invariants and persistence safety:\n\n1. A feature cannot be completed without recorded validation evidence.\n2. A session cannot close as `completed` with unfinished features.\n3. An approved plan cannot be mutated without an explicit reset.\n4. If the session's review policy is strict, a reviewer decision must be recorded before completion.\n\nPlus: 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.\n\nEverything 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.\n\n## What Flow writes\n\nFlow stores workflow state in the project/worktree where OpenCode is running:\n\n```text\n.flow/active/\u003csession-id\u003e/session.json        # active session (source of truth)\n.flow/active/\u003csession-id\u003e/docs/**             # readable derived views\n.flow/stored/\u003csession-id\u003e/session.json        # parked resumable sessions\n.flow/completed/\u003csession-id\u003e-\u003ctimestamp\u003e/**   # closed session history\n.flow/locks/\n```\n\nThe 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/**`.\n\nFlow 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).\n\n## Troubleshooting\n\n```text\n/flow-status\n```\n\nshows the workspace readiness checks (skills in sync, no stale pre-npm copy, workspace writable) with remediation steps, plus the active session state, the current blocker, and the suggested next step.\n\n## OpenCode references\n\n- Plugins: https://opencode.ai/docs/plugins\n- Skills: https://opencode.ai/docs/skills\n- Agents: https://opencode.ai/docs/agents\n\n## Releases\n\nRelease notes live in [`CHANGELOG.md`](CHANGELOG.md) and under [`docs/releases/`](docs/releases/).\n\n## Working on Flow itself\n\n- Development guide: [`docs/development.md`](docs/development.md)\n- Maintainer contract: [`docs/maintainer-contract.md`](docs/maintainer-contract.md)\n- Codebase map: [`docs/contributor-map.md`](docs/contributor-map.md)\n\n### Package API boundary\n\n`opencode-plugin-flow` supports root-only imports:\n\n```ts\nimport flowPlugin from \"opencode-plugin-flow\";\n```\n\nDeep imports such as `opencode-plugin-flow/dist/...` are intentionally not exported.\n\n## License\n\nMIT. See [`LICENSE`](LICENSE) for the full text.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddv1982%2Fflow-opencode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fddv1982%2Fflow-opencode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddv1982%2Fflow-opencode/lists"}