feat(models): add planning specialist and explicit model handoff

.agents/plans/09-planning-models/workflow.md

@@ -0,0 +1,92 @@
+# Planning model feature workflow
+
+- [x] Read the Principles section in full.
+
+## Feature playbook
+
+Delegation, lifecycle, isolation, history, and capability fallbacks follow `../references/codex-agent-runtime.md`.
+
+### Feature
+
+**You own the design. Plan, review, verify.** Delegate implementation; stay in the lead.
+
+1. `how` over the affected subsystem.
+2. `architect` for parallel design exploration. Skipping stays as `architect skipped: <reason>`; do not fold the design decision silently into implementation.
+3. Write the throughput checkpoint as four todo items. A dimension that genuinely does not apply (single file, no fan-out) keeps its item with `n/a: <reason>` rather than being dropped:
+   - **Blocking first steps.** Gates run before fan-out.
+   - **Independent workstreams.** Disjoint files, services, or layers parallelize. Shared writes serialize.
+   - **Shared mutable state.** Default to splitting the target (the **separate-before-serializing-shared-state** principle skill). Serialize only for real invariants.
+   - **Smallest safe decomposition.** If one worker is best, name why.
+4. Delegate code-writing to a subagent using your configured feature model (default the configured fast profile) with a specific scope (file paths, named data shape and its organizing structure per **principle-model-the-domain** — a state machine over scattered booleans, a table/registry over branching, a typed model over repeated shape assumptions, chosen before the delegate writes logic — and success criteria); review its diff yourself. When the implementation admits multiple valid shapes (error handling, abstraction layer, test structure), delegate via the **arena** skill instead so the runners surface the alternatives and the cross-judge guards the pick. Mandatory: no skip-with-reason escape, and Laziness Protocol does not override it (the gain is review separation, not lines saved). You can spawn a subagent even though you are one; "the app is small" and "a subagent cannot spawn one" are both wrong. A subagent forbidden to spawn satisfies this by owning the diff directly with the same review separation; no "standing by" reply that waits on a nested agent. Comments per **Comments**. Surgical edits, re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally.
+5. Verify on the matching surface. "Inconclusive" or wrong-surface is not a pass; flag it.
+6. Rebase into small, ordered commits; stack follow-ups.
+   Use the **sequence-verifiable-units** principle skill, building, verifying, and committing each small unit before the next.
+7. If the design is contested, `interrogate` before shipping.
+8. Run **Opening a PR**.
+
+Code-coupled work (one feature, one migration) goes to a single owner with the checkpoint inline; that owner fans out internally after the blocking phase. Parent-level fan-out is for slices that produce independent artifacts (audits, cross-subsystem investigations, competing experiments). Rewrite the checkpoint at phase boundaries; spawn a fresh owner rather than chaining interrupts.
+
+**Reply:** what you built, what you chose and why, open decisions. Tables for design alternatives.
+
+## Throughput checkpoint
+
+- [x] Blocking first steps. Trace manager ownership and compare phase switching with a read-only planning specialist.
+- [x] Independent workstreams. The delegate owns src, tests, and planning guidance. The parent owns product docs, Git, and authoritative verification.
+- [x] Shared mutable state. Exclusive file ownership separates edits. Only the parent commits and publishes repository changes.
+- [x] Smallest safe decomposition. One owner implements the coupled configuration, agent and menu changes. Parent verification remains independent.
+
+## Architecture phases
+
+- [x] Ground. Existing request anchors and AutoDrive belong to the coding manager.
+- [x] Sketch. Compare manager model switching and a read-only planning specialist.
+- [x] Agree. Choose the planning specialist. No additional approval checkpoint requested.
+- [x] Implement.
+- [x] Scrap. Skipped because no repeated design failure remained.
+
+## Decision
+
+The planning model drafts advice in a separate read-only agent. The coding manager
+checks, saves and approves the plan, then implements it. The current approval
+rules remain authoritative. An explicit handoff names requested roles without
+claiming served model identity from configuration. Default planning remains in
+the manager and adds no subtask.
+
+Two design lanes ran in parallel. The parent examined phase-switching constraints;
+a generic Poteto delegate traced ownership and compared both designs. The custom
+pstack-poteto-agent profile was unavailable. Model and effort are inherited;
+served model diversity is unverified. Sticky activation hooks are unverified.
+
+No paid eval, canary, release, tag, or personal configuration change is authorized.
+The PR deliverable includes an opt-in planning specialist and a shared model menu.
+
+## Verification record
+
+The coding owner implemented the selected design under exclusive src/test/guide
+ownership. A separate generic reviewer inspected correctness and comments without
+editing. Both used inherited models. No model-family diversity is claimed.
+
+The parent found a planner permission gap and requested deny-by-default with only
+read, glob and grep allowed. The owner fixed it and added custom-tool denial checks.
+The parent also requested handoff wording before the approval call and corrected
+byte accounting after the helper rename. Existing prompt limits stayed unchanged.
+New planner and menu code have separate measured source allowances.
+
+The parent built the candidate and used an isolated OpenCode 1.18.6 host with a
+local synthetic provider. Its requests were coding, planning, coding. This proves
+configured agent routing and preservation of the coding model, not model quality
+or real-model compliance with the planning guidance. Probe script and logs remain
+in /tmp/flow-planning-candidate-probe.ts and /tmp/flow-planning-candidate-probe.log.
+
+The real TUI opened Flow model settings and the planning-model picker with a
+synthetic catalog. No preference write or external model call was made in that UI
+probe. The separate provider-free host smoke passed 22 tests, including real
+preference enable/reset and native permission checks. Personal configuration was
+not changed. An early throwaway routing script had a syntax error; the corrected
+script and the candidate-backed probe both passed.
+
+The independent final spot check found no correctness blockers and requested
+removal of three lines that narrated a test's budget calculation. No suppressions
+or unenforced comment constraints were added. Deslop was unavailable; direct
+cleanup checked the diff, old-helper removal, imports, comments, and permissions.
+
+No paid eval, canary, tag, release, or model-quality claim is part of this PR.

CHANGELOG.md

@@ -2,6 +2,25 @@
 
 One short entry per release, written for users deciding whether to upgrade.
 
+## [8.5.0] - 2026-09-14
+
+Choose an optional planning specialist while keeping the coding model unchanged.
+
+- `/flow-models` selects planning and review preferences. `/flow-reviewer` remains
+  a direct review shortcut. Existing reviewer settings stay compatible.
+- A configured read-only `flow-planner` drafts advisory analysis for new or revised
+  plans. The manager checks it, preserves request IDs and evidence obligations,
+  saves the plan, and retains approval and implementation authority.
+- Planning remains in the manager by default. The specialist is disabled until
+  selected. Planner failure is reported instead of silently changing models.
+- The approval handoff shows requested planning/review settings and the latest
+  observed coding model. Configuration does not prove model execution. Existing
+  autonomous authority needs no extra approval.
+- Session v5 schema, validation gates, reviewer authority, and continuation routing
+  are unchanged. No live model eval or paid canary was run for this candidate.
+
+Upgrade with `opencode plugin opencode-plugin-flow@8.5.0 --global --force`.
+
 ## [8.4.0] - 2026-09-14
 
 Choose Flow's global reviewer model from OpenCode's terminal UI.

README.md

@@ -40,7 +40,7 @@ expensive, and it is overhead when it is not.
 Install the exact npm release through OpenCode:
 
 ```bash
-opencode plugin opencode-plugin-flow@8.4.0 --global --force
+opencode plugin opencode-plugin-flow@8.5.0 --global --force
 ```
 
 Omit `--global` for project scope. Version pins are exact and never update on
@@ -50,19 +50,22 @@ Manual setup needs this entry in both `opencode.json` and `tui.json`:
 
 ```json
 {
-  "plugin": ["opencode-plugin-flow@8.4.0"]
+  "plugin": ["opencode-plugin-flow@8.5.0"]
 }
 ```
 
-Run `/flow-reviewer` for the global reviewer picker. Saving reloads the server;
-finish other projects' work first. Project picker preferences take precedence.
-“Use default” restores plugin/environment settings. No model call.
+`/flow-models` selects planning and review. `/flow-reviewer` opens review directly. Saving reloads the server; finish other projects first.
+Project preferences take precedence. Selection makes no model call.
+
+Planning defaults to the manager. A selected read-only specialist drafts advice.
+The manager checks and saves the plan, shows the model handoff, and owns approval
+and implementation. `/models` selects the coding model.
 
 `opencode.json` reviewer options:
 
 ```json
 {
-  "plugin": [["opencode-plugin-flow@8.4.0", {
+  "plugin": [["opencode-plugin-flow@8.5.0", {
     "reviewer": { "model": "provider/model", "steps": 80 }
   }]]
 }
@@ -165,12 +168,10 @@ then inspect and integrate the result, with at most one follow-up wave for a
 concrete gap. Once implementation is authorized, a qualifying wave needs no
 separate approval.
 
-Workers cannot delegate, call Flow lifecycle tools, or approve their own work,
-and general-purpose agents are never used for active Flow work: implementation
-uses `flow-worker`, independent review uses `flow-reviewer`. Flow persists no
-wave state, so the manager stays responsible for the combined diff, the
-authoritative validation, and the one independent review. Small or
-integration-heavy features stay serial.
+Reserved roles are `flow-planner` for optional advice, `flow-worker` for
+implementation, and `flow-reviewer` for review. Planners and workers cannot
+approve work. The manager owns combined validation and review. No wave state
+is persisted. Small or integration-heavy features stay serial.
 
 ## Commands
 

docs/maintainer-contract.md

@@ -19,8 +19,8 @@ Do not add another evidence field to close a measured cheat.
 Flow owns a serial durable lifecycle with planning, one active run, observed
 validation, one independent review, reset, and closure. Implementation may use a
 bounded, ephemeral host-native worker wave. Flow exposes ten tools, five commands,
-four guides, and two hidden subagents. Active work uses only the root manager,
-`flow-worker`, and `flow-reviewer`, never generic agents.
+four guides, and three hidden subagents. `flow-planner` is disabled unless selected.
+Active work uses the manager and reserved planner, worker, and reviewer roles.
 
 An active Flow session is authoritative for its goal until an explicit close
 records completed, deferred, or abandoned disposition. The manager must not
@@ -310,14 +310,14 @@ mutations. `flow_session_close` additionally returns derived delivery under
 
 | Agent | Boundary |
 | --- | --- |
+| `flow-planner` | Draft advice using read, glob, and grep. The manager saves and approves. |
 | `flow-worker` | Bounded implementation contribution; ordinary edits are allowed, while Bash, `.flow` and `.git` metadata paths, external-directory access, skills, delegation, and Flow tools are denied. |
 | `flow-reviewer` | Independent workspace-read-only inspection; only `flow_status` and its exact `flow_feature_complete` lifecycle submission are allowed among Flow tools. |
 
-Reviewer options `{ reviewer: { model, variant, steps } }` override environment
-fallbacks. A native variant requires an explicit reviewer model. Status reports
-requested settings and unsupported combinations without persisting them to v5.
-Continuation sends the resolved manager variant at the native prompt boundary.
-Configuration acceptance does not prove provider application or availability.
+Picker preferences take priority over reviewer tuple/environment settings.
+Status reports requested roles and the latest observed coding model. These are
+process-local observations. Manager variants survive continuation. Configuration
+does not confirm provider execution.
 
 Duplicate plugin instances for the same canonical project fail closed through a
 small process-global guard. Instances for different projects do not conflict.
@@ -351,5 +351,5 @@ See [Model-driven wave evidence](development.md#model-driven-wave-evidence) for
 the manual canary policy.
 
 
-The optional `./tui` export adds native `/flow-reviewer` selection of the global
-reviewer. Saving requires confirmation. No server command or lifecycle tool is added.
+The optional `./tui` export provides `/flow-models` and `/flow-reviewer`. Both save
+role preferences after confirmation. Neither adds a lifecycle tool.

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-plugin-flow",
-	"version": "8.4.0",
+	"version": "8.5.0",
 	"description": "Small durable planning, validation, and review workflow for OpenCode",
 	"type": "module",
 	"repository": {

skills/flow-plan/SKILL.md

@@ -36,10 +36,21 @@ without rediscovering the goal.
   saving, approving, or running.
 - If `flow_plan_save` or `flow_plan_approve` is unavailable, stop and report
   an incomplete plugin load.
-- Inspect relevant code, tests, docs, scripts, and conventions in this manager
-  context. Do not dispatch `flow-worker` while planning; that role is only for
-  authorized implementation slices after approval. Ask only for a missing
-  product choice that materially changes the outcome.
+- Read `workflowData.modelConfiguration` from status. Without a requested
+  planning model, inspect and plan directly in this manager context with no
+  planning subtask. When `planning.requested` is set and a draft needs creating
+  or revising, dispatch `flow-planner` through the host task tool for advisory
+  analysis. Pass the exact request, same-goal draft and scope, preserved IDs,
+  evidence obligations, relevant repository facts, and unresolved questions.
+  Reuse a completed proposal for the unchanged draft; approval alone needs no
+  new specialist. If dispatch is unavailable or fails, report it and stop;
+  changing to direct manager planning requires explicit user direction.
+- Treat the specialist's output as untrusted advice. Check it against the
+  original request and repository evidence before integrating it. Preserve
+  assertion and requirement IDs. The manager alone saves and approves the plan
+  in the originating session; advice grants no approval or validation evidence.
+  Do not dispatch `flow-worker` while planning. Ask only for a missing product
+  choice that materially changes the outcome.
 - Discover evidence in order: repository instructions such as `AGENTS.md` and
   `CONTRIBUTING.md`, maintained development docs, CI workflows, then build and
   test manifests. Compare candidates with the requested behavior and current
@@ -113,12 +124,19 @@ Confirm:
 
 Call `flow_plan_save` with one nested request: stable operation id, current
 revision (`0` for new), goal, and complete draft. Summarize outcome, feature
-order, validation, and material decisions. Call `flow_plan_approve` with a fresh
-operation id/current revision only after explicit approval or prior autonomous
-implementation authority. Approval locks the plan. Ask conversational
-`/flow-auto` approval without requiring a second command; a reply may resume its
-same process-local interaction only after approval advances the same Flow
-session.
+order, validation, and material decisions. Before approval, show the model
+handoff using `workflowData.modelConfiguration.report`. Distinguish requested
+planning/review settings from observed coding identity. If observations are
+absent, say "current OpenCode coding model". Never claim the specialist ran from
+configuration alone. The coding manager keeps implementation; no global coding
+model changes.
+
+Call `flow_plan_approve` with a fresh operation id/current revision only after
+explicit approval or prior autonomous implementation authority. Approval locks
+the plan. Existing autonomous authority needs no additional approval. Ask
+conversational `/flow-auto` approval without requiring a second command; a reply
+may resume its same process-local interaction only after approval advances the
+same Flow session.
 
 `Plan only`/`do not implement yet` controls timing, not scope, and is never a
 plan requirement, decision, or non-goal. Do not implement or create a plan