opencode-plugin-flow 4.1.0 → 4.1.2

package/CHANGELOG.md

@@ -3,11 +3,17 @@
 One short line per release. For the full rationale behind each entry, see the
 commit history and review evidence.
 
-## [Unreleased]
+## [4.1.2] - 2026-06-15
+
+Make Flow's skill registry lag visible with restart-aware setup warnings, a doctor command, and a bundled review fallback for stale OpenCode startups.
+
+## [4.1.1] - 2026-06-15
+
+Keep Flow's local session ledger out of Git by default with a generated `.flow/.gitignore`, while preserving opt-in versioning for teams that intentionally archive session evidence.
 
 ## [4.1.0] - 2026-06-15
 
-- Add Flow-native orchestration handoffs, verification gates, and a hidden verifier worker while keeping the public runtime surface unchanged.
+Add Flow-native orchestration handoffs, verification gates, and a hidden verifier worker, inspired by Ray Fernando's parallel agent workflow skill work and RepoPrompt CE's context-engineering approach, while keeping the public runtime surface unchanged.
 
 ## [4.0.1] - 2026-06-15
 

package/README.md

@@ -1,16 +1,26 @@
 # Flow Plugin for OpenCode
 
-`opencode-plugin-flow` is a skills-first workflow helper for OpenCode. The skills carry the planning, execution, validation, cleanup, UI, and review guidance. The plugin code is deliberately small: it keeps a durable `.flow/session.json` ledger and enforces the few binary gates that prompts cannot reliably enforce.
+`opencode-plugin-flow` is a skills-first workflow helper for OpenCode. The skills carry planning, execution, validation, cleanup, UI quality, review, and orchestration judgment. The plugin code stays deliberately small: it keeps a durable `.flow/session.json` ledger and enforces the hard gates prompts should not be trusted to remember.
 
 Flow v4 is a breaking simplification. It does not preserve v3 session layouts or retired tool aliases.
 
+## What Flow adds
+
+- A resumable one-feature-at-a-time loop for larger coding work.
+- Skill-guided planning, running, validation, review, cleanup, and UI quality.
+- Hidden evidence, review, validation, audit, verifier, and candidate workers for broad work.
+- Structured handoffs with coverage, evidence, confidence, and gaps.
+- Runtime gates for approval immutability, validation evidence, review evidence, and safe session closure.
+
+The manager still owns every Flow state change. Workers gather evidence; they do not approve plans, complete features, or close sessions.
+
 ## Install
 
 Add Flow to your OpenCode config:
 
 ```json
 {
-  "plugin": ["opencode-plugin-flow@4.1.0"]
+  "plugin": ["opencode-plugin-flow@4.1.2"]
 }
 ```
 
@@ -31,6 +41,18 @@ Project-local skill overrides still work through OpenCode's normal lookup:
 .opencode/skills/flow-plan/SKILL.md
 ```
 
+If Flow installs or updates skills during the current OpenCode startup, restart
+OpenCode once more before using Flow commands. OpenCode may have already scanned
+the skill registry for the running process, so a just-synced skill can exist on
+disk while still being unavailable to that process. Flow reports this through
+`flow_status` as `setup.skills.status: "restart_required"`.
+
+To inspect the installed skill set:
+
+```bash
+npx -y opencode-plugin-flow@4.1.2 doctor
+```
+
 ## Commands
 
 Commands are thin pointers into skills:
@@ -45,7 +67,7 @@ Commands are thin pointers into skills:
 
 ## Tools
 
-The v4 runtime exposes seven tools:
+The runtime exposes seven tools:
 
 | Tool | Purpose |
 | --- | --- |
@@ -59,8 +81,6 @@ The v4 runtime exposes seven tools:
 
 There is no `flow_context` and no separate review-record tool. Review evidence is part of `flow_feature_complete`: every completed feature needs a passing `featureReview`, and the final feature also needs a passing `finalReview`.
 
-Broad Flow work can fan out through hidden evidence, review, validation, audit, verifier, and candidate workers. Those workers return structured handoffs with coverage, evidence, confidence, and gaps; the manager still owns all Flow state changes and no extra user command is required.
-
 ## Runtime Contract
 
 The runtime owns only safety:
@@ -68,6 +88,7 @@ The runtime owns only safety:
 - `.flow/session.json` is the active source of truth.
 - `.flow/history/<session-id>.json` stores closed sessions.
 - Session writes are locked and atomic.
+- Flow writes `.flow/.gitignore` so session state stays out of Git by default.
 - Mutable roots cannot be filesystem roots or `$HOME`.
 - Plans cannot be changed after approval.
 - Only one feature can be active at a time.
@@ -76,7 +97,7 @@ The runtime owns only safety:
 - Final completion requires `validationScope: "broad"` and a passing final review matching the plan's `finalReviewPolicy`.
 - `flow_session_close` accepts `kind: "completed"` only after an approved plan has passed final completion.
 
-Planning quality, decomposition, review depth, validation adequacy, and recovery judgment live in the skills.
+Planning quality, decomposition, review depth, validation adequacy, orchestration, and recovery judgment live in the skills.
 
 ## State Layout
 
@@ -86,6 +107,10 @@ Planning quality, decomposition, review depth, validation adequacy, and recovery
 .flow/session.lock/
 ```
 
+Versioning `.flow` state is opt-in. Edit `.flow/.gitignore` or use
+`git add -f` only when a repository intentionally wants to archive Flow session
+evidence.
+
 ## Development
 
 ```bash
@@ -99,6 +124,12 @@ The package exports only the OpenCode plugin entrypoint:
 import flowPlugin from "opencode-plugin-flow";
 ```
 
+## Credits
+
+Flow's parallel orchestration guidance was inspired by Ray Fernando's skill work on parallel agent workflows. Flow also draws conceptual inspiration from [RepoPrompt CE](https://github.com/repoprompt/repoprompt-ce), especially its emphasis on codebase orientation, context engineering, agent orchestration, and reviewable handoffs.
+
+The Flow version is its own OpenCode-native design: skills-first, manager-owned state, hidden workers, and no extra runtime ledger.
+
 ## Uninstall
 
 ```bash