{"id":48355116,"url":"https://github.com/ddv1982/flow-opencode","last_synced_at":"2026-07-20T01:00:55.511Z","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-07-20T01:00:55.504Z","avatar_url":"https://github.com/ddv1982.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flow Plugin for OpenCode\n\n`opencode-plugin-flow` gives OpenCode a durable, resumable planning-and-execution\nloop for larger coding work: plan a goal as discrete features, approve the plan,\nthen implement one feature at a time with enforced validation and review\nevidence. State lives in `.flow/session.json`, so a session survives restarts,\nmodel switches, and context loss.\n\nThe design is guidance-first: package-owned Markdown carries planning,\nexecution, validation, review, and orchestration judgment, while the plugin\nruntime stays bounded and policy-focused — it keeps the session ledger and\nenforces the hard gates prompts should not be trusted to remember.\n\nThe maintained documentation starts at [docs/index.md](docs/index.md). The\ntracked `droid-wiki/` tree is an archived generated snapshot and is not a\ncurrent product or contributor contract.\n\n## Quick start\n\n```bash\nnpx -y opencode-plugin-flow@latest install \\\n  --project \"$PWD\" --scope global\n```\n\n`install` resolves npm's current release before it starts, writes that package's\nembedded exact version as the sole Flow activation, and permanently removes\npositively identified older Flow wrappers and OpenCode cache artifacts. It\nrefuses a downgrade when a newer installed version is detected. The final check\nperformed by that same fetched CLI must report exactly one active Flow source at\nthe installed exact version and no proven inactive Flow cache artifacts. Do not\nresolve `@latest` a second time for post-install verification. Inventory covers\nglobal sources plus the selected `--project`; it does not scan unrelated project\ntrees. Run the installer from each project that has its own OpenCode config. Use\n`--scope project` when the canonical pin should live with that selected project\ninstead of global config.\n\nFor a read-only preview, run `activation-apply` without `--apply` using an exact\npackage version. Flow refuses ambiguous local wrappers, cache entries, unsafe\nlinks, and config it cannot change conservatively rather than guessing which\ncopy is authoritative.\n\nStart or restart OpenCode, then give Flow a goal:\n\n```text\n/flow-auto add rate limiting to the public API\n```\n\nFlow inspects the repo, saves a plan of features, asks for approval (or\nproceeds if you already authorized autonomous work), then runs the loop:\nimplement one feature → validate it → review it → record evidence → next\nfeature. `/flow-status` shows where you are at any point, including after a\nrestart.\n\n`/flow-auto` still respects the scope of the request. If you ask for a plan\nonly or explicitly say not to implement, it saves and summarizes the plan and\nstops before `flow_run_start`.\n\n## What a session looks like\n\n```text\n\u003e /flow-auto add rate limiting to the public API\n\n  flow_plan_save    goal: \"add rate limiting to the public API\"\n                    features: rate-limit-middleware, per-route-config, docs-update\n  (you approve the plan)\n  flow_plan_approve plan locked — features are now immutable\n  flow_run_start    mutation acknowledged\n  flow_status       request.view: execution, feature: rate-limit-middleware\n  ... implementation, tests ...\n  flow_validation_start\n                    command: exact next Bash command\n                    coverageScope: focused\n  bash              exact armed command\n                    [flow-validation-receipt] immutable receipt reference\n  flow_review_start request.validationRefs: [receipt reference]\n                    request.reviewKind: feature\n                    request.validationScope: targeted\n                    assignmentId: review-assignment:runtime-id\n  flow_status       request.view: reviewer\n                    request.assignmentId: review-assignment:runtime-id\n  ... independent review ...\n  flow_feature_complete\n                    request.result.kind: completed\n                    request.result.validationScope: targeted\n                    request.result.featureReview.assignmentId: review-assignment:runtime-id\n                    request.result.featureReview.verdict: passed\n  flow_run_start    mutation acknowledged\n  flow_status       request.view: execution, feature: per-route-config\n  ...\n\n\u003e /flow-status\n  status: ok\n  workflowData.projection.view: compact\n  workflowData.projection.status: running\n  workflowData.projection.progress: { completed: 1, total: 3, remaining: 2 }\n\n\u003e /flow-run\n  flow_status       request.view: execution\n                    workflowData.projection: full active-feature scope\n```\n\n`flow_status` returns workflow state under `workflowData.projection`: compact is\nrouting-only, execution is the full active-feature working scope, detail is\ndiagnostic, and reviewer is narrow assignment context. State-changing tools\nreturn `workflowData.receipt` acknowledgements; a receipt never replaces a\nfresh status projection. Rejected mutations explicitly report\n`operationAccepted: false` and `operationIdConsumed: false`; accepted results,\nincluding durable review blockers, report the corresponding accepted receipt.\n\nInterrupt at any point; `/flow-run` resumes the next approved feature. On the\nfinal feature Flow requires broad project-level validation and a final review\nwhose depth matches the approved plan before the session can close as\ncompleted.\n\n## Commands\n\n| Command | Purpose |\n| --- | --- |\n| `/flow-auto \u003cgoal\u003e` | Drive the authorized loop; stop after planning when requested. |\n| `/flow-plan \u003cgoal\u003e` | Create or approve a plan. |\n| `/flow-run` | Execute one approved feature. |\n| `/flow-review` | Run a read-only review. |\n| `/flow-status` | Show the active session and next action. |\n\nCommands are compiled entrypoints: manager commands carry only their applicable\ncore instructions, while `/flow-review` runs against the reserved reviewer's\nrole-specific agent contract. Flow does not install files into OpenCode's\nglobal skill registry and does not depend on native skill discovery.\n\n`flow-test`, `flow-deslop`, `flow-ui-quality`, and `flow-commit` are optional\npackage-owned guides loaded on demand through `flow_guidance`, not public\ncommands. `flow-commit` is user-triggered only and stays outside the autonomous\nloop.\n\n## Tools\n\nThe plugin exposes 12 tools. Nine own the durable lifecycle; three add bounded\nharness admission, runtime-attested validation, and deterministic audit\nrendering:\n\n| Tool | Purpose |\n| --- | --- |\n| `flow_guidance` | Load exact package-owned guidance by stable id. |\n| `flow_status` | Read the active session and next action. |\n| `flow_plan_save` | Create a session or update its active same-goal draft. |\n| `flow_plan_approve` | Approve the draft plan. |\n| `flow_run_start` | Start the next runnable feature. |\n| `flow_review_start` | Bind validation to current source and create a runtime-owned reviewer assignment; final review also binds the passing feature result. |\n| `flow_feature_complete` | Atomically record a completed or blocked assignment result. |\n| `flow_feature_reset` | Reset one feature and its dependents. |\n| `flow_session_close` | Archive the active session as completed, deferred, or abandoned. |\n| `flow_orchestration_admit` | Evaluate and arm one bounded optional-worker proposal for the active harness profile. |\n| `flow_validation_start` | Arm capture for the exact next Bash command against current causal guards, feature run, and source. |\n| `flow_audit_render` | Validate `AuditLedgerV1` and render its reconciled Markdown deterministically. |\n\nOnly the root manager calls `flow_review_start`. Reviewers recover the exact\nassignment with\n`flow_status { request: { view: \"reviewer\", assignmentId } }` and return only\nthe assignment id, verdict, typed findings, reported time, and terminal\ndisposition. The runtime derives all attempt, pass, source, packet, run,\nstart-time, and required-depth identity. Final assignment creation durably binds\nthe exact passing feature-assignment result. The final feature outcome submits\nonly the final-assignment result; Flow records both results atomically from the\ndurable binding.\n\nValidation input is no longer a caller-authored success claim. Immediately\nbefore a check, call `flow_validation_start` with the exact command and current\nguards, execute that exact command as the next Bash call, and copy the emitted\nimmutable receipt reference into `flow_review_start.request.validationRefs`.\nFlow verifies receipt bytes, run, feature, current source, host-observed exit,\noutput completeness, and scope before materializing Session v4 evidence. A\nfailed, truncated, missing, stale, altered, or duplicate receipt is rejected\nwithout consuming the review-start operation id.\n\nThe first final assignment pins that binding for every same-source final-review\nretry. A manager recovering context loads detail status and copies\n`workflowData.projection.finalReviewRetry.prerequisite.result` unchanged into\nthe new final review start's `request.featureReview`. Compact and reviewer views\nomit the aggregate. A mismatch records nothing and leaves its operation id\nreusable; a source edit requires a new targeted feature-review sequence.\n\n## What the runtime enforces\n\nThe runtime owns only safety; judgment lives in package-owned guidance:\n\n- `.flow/session.json` is the single source of truth; writes are locked and\n  atomic, and closed sessions are archived under `.flow/history/`.\n- Plans cannot be changed after approval.\n- A different-goal plan save cannot replace an unclosed session, including an\n  unapproved draft. Close it explicitly as `deferred` or `abandoned` and finish\n  archive publication before saving the new goal.\n- Only one feature run can be active at a time; reset preserves its audit\n  history but the next start receives a fresh run id.\n- Reviewer assignment requires source-bound passing validation: `targeted` for\n  feature review and `broad` for final review. A source edit invalidates stale\n  pending review work when its replacement is created.\n- Validation receipts are host-attested from the exact next Bash execution.\n  Callers cannot supply validation timestamps, exit status, command class, or\n  output digest to `flow_review_start`.\n- Feature outcome uses a nested `completed` or `blocked` result. Invalid or stale\n  input records nothing and does not consume its operation id.\n- Each OpenCode handler validates the registered nested schema again at entry;\n  invalid host invocations fail as tool errors before Flow state I/O.\n- The runtime derives review depth from the approved plan and owns assignment,\n  attempt, logical-pass, packet, source, and start-time identity.\n- Failed reviews are bounded: an accepted blocker returns operation status\n  `ok`, and autonomous repair is limited to one repair plus one retry before\n  the feature blocks.\n- Review exhaustion uses the ordinary blocked-feature state; continuing requires\n  an explicit `flow_feature_reset`, not a second checkpoint protocol.\n- A passing final feature outcome marks progress completed but leaves closure null;\n  `flow_session_close` exclusively records and archives it.\n- Once a closure is recorded, the session is archive-only. If publication fails,\n  compact status supplies `closure.retryOperationId`; retry only with\n  `flow_session_close { request: { mode: \"retry\", operationId } }`. No new\n  close, run, reset, approval, or replan can reopen or adopt it.\n- A new close operation id must be absent from the active causal chain and every\n  mutation in canonical Session v4 workspace history. Any archived match is a\n  collision; malformed or ambiguous canonical history fails closed before\n  active state changes.\n- Archive publication requires explicit non-null closure. Closureless Session\n  v4 state may remain active, but it is rejected as canonical history and makes\n  canonical lookup fail closed if found there.\n- Every closure is quiescent: no active execution or pending review assignment\n  remains. A session can close as `completed` only after the final feature\n  outcome has passed.\n- Host-observed validation times and reviewer-reported result times must follow\n  run, validation, and assignment order and cannot postdate runtime acceptance.\n- Session locks fail closed: Flow never guesses that an old lock is abandoned,\n  and only the unique owner may release it. Only a valid Session v4 document can\n  become active state; canonical history additionally requires explicit\n  non-null closure.\n- Flow writes `.flow/.gitignore` so session state stays out of Git by default.\n- `.flow/session.json` is the only active-state representation. Canonical Flow\n  commands call `flow_status` before acting; plugin configuration does not read,\n  refresh, or project workspace state.\n- Exactly one Flow runtime instance may operate in an OpenCode process. If\n  duplicate copies load, every copy fails closed; the highest semantic version\n  is named only as a diagnostic leader and does not become operational.\n\n## Hidden workers\n\nFor broad work, Flow's manager can fan out isolated hidden workers\n(`flow-evidence-worker`, `flow-validation-worker`, `flow-audit-worker`,\n`flow-candidate-worker`, `flow-verifier-worker`, and the `flow-reviewer`) with\nlocked-down permissions. Workers gather evidence; they never approve plans,\ncomplete features, or close sessions. Flow reserves those agent ids and the\npublic command ids while the plugin is enabled, and warns if they collide with\nyour own config.\n\nEach hidden worker receives only its applicable handoff schema. The manager\ncontract treats empty or malformed handoffs as coverage gaps instead of\nsuccess. The offline handoff validator detects missing headings, empty sections,\nunresolved placeholders, and invalid statuses; current OpenCode worker output\nremains plain text, so runtime acceptance still depends on the manager applying\nthat contract. Inspect rendered surfaces and static contracts with\n`bun run prompt:quality`; run opt-in model decisions with\n`bun run prompt:model-eval -- --model \u003cprovider/model\u003e --timeout-ms 300000`;\nsee\n[docs/prompt-quality.md](docs/prompt-quality.md).\n\nThe trusted command footer selects one harness profile with\n`OPENCODE_FLOW_HARNESS_PROFILE=control|standard|assurance` (default\n`standard`) and one admission rollout with\n`OPENCODE_FLOW_ROLLOUT_MODE=control|observe|enforce` (default `observe`).\n`control` preserves discretionary optional-worker behavior without admission\nceremony. `standard` admits a small bounded discovery/challenge path;\n`assurance` permits broader bounded evidence and audit coverage when risk\njustifies it. In `observe`, a policy violation is reported but does not block;\nin `enforce`, the exact admitted optional worker class and count must be\ndispatched. Lifecycle-required reviewer and validation workers are not optional\npasses and do not use orchestration admission. Validation receipts remain\nmandatory in every profile.\n\nHidden worker routing can be tuned without changing the domain contract. Set\n`OPENCODE_FLOW_READONLY_WORKER_MODEL`,\n`OPENCODE_FLOW_REVIEW_WORKER_MODEL`, or\n`OPENCODE_FLOW_CANDIDATE_WORKER_MODEL`, with\n`OPENCODE_FLOW_WORKER_MODEL` as the fallback. Matching `*_WORKER_STEPS`\nvariables set OpenCode's current `steps` limit; values must be integers from 1\nthrough 1000.\n\nFor broad implementation, the manager records whether work stayed serial,\nused exact-path candidate workers, used isolated worktrees, ran a tournament, or\nskipped eligible candidates. Feature completion can carry bounded\n`result.orchestrationPasses` with candidate eligibility, decision, and structured\nfactors. Bounded projections report the relevant aggregate while full worker\nhandoffs remain outside `.flow/**`.\n\n## Install details and legacy cleanup\n\nSee [docs/troubleshooting.md](docs/troubleshooting.md) for updates,\nactivation refusal and duplicate-runtime recovery, stuck session recovery, and\nremoval of global Flow skill folders left by v4.\n\nTo update, run the same `@latest install` command. The installer inventories\nOpenCode's global sources plus the selected project's project, `.opencode`,\ncustom, inline, and readable managed configuration; singular and plural plugin\ndirectories; and the Flow package cache. Other project trees are deliberately\nnot discovered; run the command from each project with project-local OpenCode\nconfiguration. It preserves unrelated plugins, removes recognized Flow config\nentries outside the selected canonical scope, and permanently removes only\nmarker-proven wrappers, the exact known legacy wrapper format, and\nmanifest-proven inactive cache artifacts. Applied changes receive config\nbackups and a recovery journal. Obsolete artifacts are staged reversibly while\nactivation changes are verified, restored if activation fails, and deleted\nbefore installation reports success.\nSources that cannot be proved safe—including unknown wrappers, ambiguous cache\nartifacts, JSONC that would require a lossy rewrite, inline config, and\nadministrator-managed config—produce manual remediation instead of mutation.\nIf an applied multi-source change fails, Flow attempts exact safe rollback and\nrecords either `rolled-back` or `rollback-failed` in the recovery journal;\nconcurrent or unsafe state is preserved for manual recovery. Remote and\nmanaged-preference sources that cannot be decoded offline remain covered by\nfail-closed runtime leadership within each OpenCode project context. A later\ninstall reconciles interrupted v2 journals before planning: pre-commit work is\nrolled back, while committed removal work finishes verified deletion.\n\nTo preview recoverable migration of pristine v4 global skill folders:\n\n```bash\nnpx -y opencode-plugin-flow@5.3.3 legacy-cleanup --dry-run\n```\n\n## Development\n\n```bash\nbun install\nbun run check        # typecheck + lint + release metadata + prompt quality + build + tests\nbun run harness:report # sanitized control/candidate resource and quality status\nbun run smoke:live   # boots a real OpenCode server against the packed tarball\n```\n\nThe package exports only the OpenCode plugin entrypoint:\n\n```ts\nimport flowPlugin from \"opencode-plugin-flow\";\n```\n\nSee [docs/development.md](docs/development.md) and\n[docs/maintainer-contract.md](docs/maintainer-contract.md) for the\nv5 domain/application/infrastructure/platform boundaries, guidance split, and\nrelease process.\n\n## Credits\n\nFlow's parallel orchestration guidance was inspired by Ray Fernando's skill\nwork on parallel agent workflows. Flow also draws conceptual inspiration from\n[RepoPrompt CE](https://github.com/repoprompt/repoprompt-ce), especially its\nemphasis on codebase orientation, context engineering, agent orchestration,\nand reviewable handoffs.\n\nThe Flow version is its own OpenCode-native design: package-owned guidance,\nmanager-owned state, hidden workers, and no extra runtime ledger.\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"}