opencode-plugin-flow 4.3.2 → 4.3.4

package/dist/index.js

@@ -836,6 +836,60 @@ Apply the manager synthesis barrier from
 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
 
@@ -914,6 +968,164 @@ Better plan:
 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.
@@ -997,6 +1209,15 @@ Call \`flow_plan_save\` with:
 
 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.
 
+## 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.
@@ -1012,7 +1233,8 @@ Use only \`finalReviewPolicy: "broad"\` or \`"detailed"\`. These are the canonic
 
 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.
+See \`references/planning-examples.md\` for payload examples and decomposition
+anti-patterns.
 `;
 
 // skills/flow-review/references/review-rubric.md
@@ -1048,13 +1270,42 @@ If unsure whether a finding is real, read more or downgrade it. Do not promote g
 
 ## Final review checklist
 
-- Every feature is complete and together they satisfy the original goal.
-- Broad validation ran and passed.
+- 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:
@@ -1139,6 +1390,9 @@ These instructions run in two contexts, and only one of them can load helpers:
 - Call \`flow_status\` when available.
 - Identify whether this is a feature review or final review.
 - 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
@@ -1710,6 +1964,10 @@ var FLOW_SKILL_DEFINITIONS = [
         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
@@ -1802,6 +2060,7 @@ var FLOW_REVIEW_BUNDLED_INSTRUCTIONS = bundledFlowInstructions([
 var FLOW_PLAN_BUNDLED_INSTRUCTIONS = bundledFlowInstructions([
   ["flow-plan", "SKILL.md"],
   ["flow-plan", "references/planning-examples.md"],
+  ["flow-plan", "references/plan-quality-checklist.md"],
   ["flow-plan", "references/parallel-discovery.md"],
   ["flow", "references/parallel-orchestration.md"],
   ["flow", "references/handoff-format.md"]
@@ -1822,6 +2081,7 @@ var FLOW_AUTO_BUNDLED_INSTRUCTIONS = bundledFlowInstructions([
   ["flow", "references/handoff-format.md"],
   ["flow-plan", "SKILL.md"],
   ["flow-plan", "references/planning-examples.md"],
+  ["flow-plan", "references/plan-quality-checklist.md"],
   ["flow-plan", "references/parallel-discovery.md"],
   ["flow-run", "SKILL.md"],
   ["flow-run", "references/validation-rubric.md"],
@@ -3744,4 +4004,4 @@ export {
   plugin_default as default
 };
 
-//# debugId=F01203B3D1AFDF4F64756E2164756E21
+//# debugId=72872E938F875B1A64756E2164756E21