flow-workflows 0.86.0 → 0.88.0

package/adapters/hermes/CORE.md

@@ -17,7 +17,7 @@ Every `/flow-*` command assumes these rules. They are stated once, here, so a co
 carries what is specific to its phase. Read this once per session; a command that says "load
 `flow-core`" means this file.
 
-**This file belongs to flow `0.86.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.88.0`.** Compare it once, at the start of the session, against
 `version` in `~/.claude/flow/.claude-plugin/plugin.json`. The two differing means the session
 is running a **mixture** — the commands from one copy of the plugin, these shared rules from another
 — which is exactly what happens when a branch or a release candidate is loaded over an installed
@@ -218,6 +218,16 @@ sensible default and record it.
 
 Asking these anyway is how a run in `guided`/`auto` degrades into a manual one.
 
+**A study made for handoff.** `git.handoff_branch` set and the mode not `unattended` → the study is
+built somewhere else, so wherever a study phase (`start`, `design`, `plan`, `investigate`) or
+`resume` would hand the work to `/flow-feat-build` or `/flow-bug-fix`, it hands it to
+`/flow-work-handoff` instead. Only the target changes: a Close that asks (`manual`) offers **Hand
+off the study** recommended and **Build here** second; a Close that chains (`guided`/`auto`) chains
+into handoff, whose push question is the one confirmation — no stop is added. In `unattended` the
+rule does not apply: the repo's `FLOW.md` reaches the server too, and a run that studies a ticket
+there goes on to build it. A repo that hands its studies off pairs the key with
+`autonomy.mode: auto`, and the study then runs on its own up to the push.
+
 ### 2.1 `unattended` — where a person would have been asked
 
 No person is there to answer a question in this mode. A question tool — `AskUserQuestion`, OpenCode's `question`,

package/adapters/hermes/skills/flow-bug-investigate/SKILL.md

@@ -36,7 +36,7 @@ Read `~/.claude/flow/CORE.hermes.md` first (shared rules: `FLOW.md` step 0, mode
 **In `unattended`, before this phase's first step, read flow-core §2.1 whole — from its heading to the next section, unless it is already in your context whole; having read parts of it does not count** — the orchestrator command, the question stop and the way its answer comes back are all in it, and a phase that reads only part of it skips them.
 
 - Read `meta.json` and `00-summary.md`; open in full only `01-context.md`. (flow-core §5)
-- `type` is not `bug` → refuse. `size` is `XS` → suggest `/flow-bug-fix` and stop.
+- `type` is not `bug` → refuse. `size` is `XS` → suggest `/flow-bug-fix` — `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff) — and stop.
 - Require `context` in `phases_done`.
 
 ## 1.5 Reproduce — what is failing, before why
@@ -221,5 +221,5 @@ If `knowledge.stage` is set and the root cause reveals a **non-obvious "why"** a
 
 - Update `meta.json`: `phase = "investigate"`, add to `phases_done`.
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5).
-- Suggest `/flow-bug-fix`.
-- **Autonomy handoff** (`autonomy.mode`, flow-core §2): `manual` → propose `/flow-bug-fix` with a single `AskUserQuestion`, invoke it only on confirmation; `guided`/`auto` → chain into it in this same turn.
+- Suggest `/flow-bug-fix` — `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff).
+- **Autonomy handoff** (`autonomy.mode`, flow-core §2): `manual` → propose `/flow-bug-fix` with a single `AskUserQuestion`, invoke it only on confirmation; `guided`/`auto` → chain into it in this same turn. Either way: `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff).

package/adapters/hermes/skills/flow-bug-start/SKILL.md

@@ -228,6 +228,6 @@ Run `tracker.start_cmd` with `{TICKET}` = `meta.json.ticket` and `{ASSIGNEE}` =
 
 ## 5. Close
 
-- Suggest the next command by size: `/flow-bug-fix` for XS, `/flow-bug-investigate` for the rest.
+- Suggest the next command by size: `/flow-bug-fix` for XS (`git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff)), `/flow-bug-investigate` for the rest.
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5).
 - Apply `autonomy.mode`: `manual` stops and recommends; `guided`/`auto` chain into that command automatically, subject to the hard gates.

package/adapters/hermes/skills/flow-feat-design/SKILL.md

@@ -40,7 +40,7 @@ after writing each challenge's Response.
 
 - Load `meta.json` by current branch — in `unattended`, the work `/flow-work-run` found (flow-core §2.1). Missing → ask the user to start with `/flow-feat-start`.
 - Read `meta.json` and `00-summary.md`; open in full only `01-context.md` (ticket, decisions, contracts received). (flow-core §5)
-- `size` is `XS` → suggest jumping to `/flow-feat-build` and stop unless the user insists.
+- `size` is `XS` → suggest jumping to `/flow-feat-build` — `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff) — and stop unless the user insists.
 
 ## 1.5 Approaches — open the option space first (M/L)
 
@@ -408,6 +408,6 @@ Never invoke `knowledge.save` here — the final save is in `/flow-feat-ship` af
 - **Confirm the acceptance criteria** within the design review: present the enumerated list. If every criterion is unambiguous and verifiable, the review covers them — no separate prompt. `AskUserQuestion` **only** when a criterion is ambiguous, not verifiable, or one is likely missing for today's ticket (same restraint as the challenger). Apply the user's edits to `03-design.md` before advancing.
 - **In `manual`/`guided`**, ask the user to review the design; edit the artifact on requested changes before advancing. **In `auto`, do not ask** — record it as accepted per the handoff below. Not an unconditional stop.
 - Next step by size:
-  - **XS / S**: suggest `/flow-feat-build` (1 single MR/PR, no planned split).
+  - **XS / S**: suggest `/flow-feat-build` (1 single MR/PR, no planned split) — `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff).
   - **M / L**: suggest `/flow-feat-plan` to split the work into independently mergeable MRs/PRs before implementing.
-- **Autonomy handoff.** Design review is a genuine decision point: `manual` and `guided` ask for it before advancing. `auto` records the design as accepted in the artifact and **chains into the command for the size** in this same turn. `manual` proposes that command with a single `AskUserQuestion` (recommended option by default), never a written suggestion. Unresolved `high`-severity findings (§6) stop the flow in **every** mode — do not chain over them.
+- **Autonomy handoff.** Design review is a genuine decision point: `manual` and `guided` ask for it before advancing. `auto` records the design as accepted in the artifact and **chains into the command for the size** in this same turn — `build` there: `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff). `manual` proposes that command with a single `AskUserQuestion` (recommended option by default), never a written suggestion. Unresolved `high`-severity findings (§6) stop the flow in **every** mode — do not chain over them.

package/adapters/hermes/skills/flow-feat-plan/SKILL.md

@@ -31,7 +31,7 @@ Delivery planning phase. **No code is written.** Splits the feature into MRs/PRs
 - Load `meta.json` by current branch — in `unattended`, the work `/flow-work-run` found (flow-core §2.1). Missing → send the user to `/flow-feat-start`.
 - Require `design` in `phases_done`. Missing → send to `/flow-feat-design` and stop.
 - Read `meta.json` and `00-summary.md`; open in full only `03-design.md`. (flow-core §5)
-- **`size` `XS` or `S`** → warn that this phase does not apply (always 1 MR/PR), add `"plan:skipped"` to `phases_done`, suggest `/flow-feat-build`. Stop.
+- **`size` `XS` or `S`** → warn that this phase does not apply (always 1 MR/PR), add `"plan:skipped"` to `phases_done`, suggest `/flow-feat-build` — `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff). Stop.
 
 ## 2. Work
 
@@ -165,5 +165,5 @@ A slice landing in **another repo** is not one of *this* repo's `mrs`: record it
 
   `∥` = no dependency between them, can be built in parallel or as a train; `→` = the next wave waits for the previous one to merge. Then the table with `#`, wave, `depends_on`, title and estimate. One line for the split rationale, and — when any pair was merged — one line saying how many were and what they would have cost (`merged #a into #b: would have been a wave of its own`). Nothing else — risks and discarded alternatives live in the artifact.
 - Changes requested → edit the artifact and `meta.json.mrs` before advancing.
-- Suggest `/flow-feat-build` to start the first MR/PR.
-- **Autonomy handoff.** Approving the split is a genuine decision point: in `manual` and `guided` ask before advancing. In `auto`, record the plan as accepted in `04-mr-plan.md` and **chain into `/flow-feat-build` automatically** in this same turn. In `manual`, propose it with a single `AskUserQuestion`.
+- Suggest `/flow-feat-build` to start the first MR/PR — `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff).
+- **Autonomy handoff.** Approving the split is a genuine decision point: in `manual` and `guided` ask before advancing. In `auto`, record the plan as accepted in `04-mr-plan.md` and **chain into `/flow-feat-build` automatically** in this same turn. In `manual`, propose it with a single `AskUserQuestion`. Either way: `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff).

package/adapters/hermes/skills/flow-feat-start/SKILL.md

@@ -309,5 +309,5 @@ Run `tracker.start_cmd` with `{TICKET}` = `meta.json.ticket`, `{ASSIGNEE}` = `tr
 ## 7. Close
 
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5) — first written in §6; refresh it if §6.5 changed anything.
-- Report **following the stop header** (flow-core §3), branch added, body 2-3 lines: ticket, size, branch; recommended next command per the §4 table — in `guided`/`auto` you run it in this same turn, so there is no report and no question here: update the panel and chain (flow-core §3).
+- Report **following the stop header** (flow-core §3), branch added, body 2-3 lines: ticket, size, branch; recommended next command per the §4 table (`build` on XS: `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff)) — in `guided`/`auto` you run it in this same turn, so there is no report and no question here: update the panel and chain (flow-core §3).
 - Apply `autonomy.mode`: `manual` → stop and let the user invoke the recommended command; `guided`/`auto` → chain into it, subject to the hard gates (the §5 branch-base ambiguity already stops on its own).

package/adapters/hermes/skills/flow-work-README/SKILL.md

@@ -249,6 +249,7 @@ Two signals arrive on an open MR/PR, each with its own cross-cutting loop (feat
 - `/flow-work-daily [question]` — the **work assistant** (daily standup), read-only. **Local** (`.claude/work/` + git) + **forge** (open MRs/PRs, reviews awaiting you, red CI, unmergeable, unresolved threads via `git.cli`) + **tracker** (assigned tickets, priority changes via `tracker.tool`); where they cross, concrete commands (`/flow-feat-start`, `/flow-work-green`, `/flow-work-respond`). No argument → *yesterday · today · blockers*; a question → just that. External sources best-effort, never blocking; the only write is a "last seen" marker, like `/flow-news`.
 - `/flow-work-status` — all works in `.claude/work/`, current phase, divergence with git.
 - `/flow-work-run [ticket]` — the **entry an orchestrator launches** for an `unattended` run: asks it `why` (start · answer · merged · review · pipeline), routes to the phase that answers it, and makes no decision of its own. Refuses to run in any other mode.
+- `/flow-work-handoff` — hands a **finished study** to whoever builds it elsewhere (an unattended server, another machine): refuses an unfinished one, pushes only this work's folder as a parentless commit to `git.handoff_branch` without touching the checkout, asks before the push, then offers a marked summary for the ticket body (`tracker.edit_cmd`).
 - `/flow-work-resume` — detects the branch, reads `meta.json`, recaps, suggests the next step. **Re-reads the ticket's comment thread** (§2.5), reports only what is new since `01-context.md`, appends it to the artifact; never amends the design on its own.
 - `/flow-work-try <branch>` / `/flow-work-try --back` — point the main checkout at a branch to test it here, then return; re-syncs per `git.worktree_resync`. Resolves the work behind the branch and, once the environment is up, **prints the manual test plan already written** (the `needs-manual`/`unproven` criteria, or the acceptance criteria when `validate` has not run) and offers to collect Pass/Fail/Blocked into the validation artifact. No work behind the branch → the plain switch, as before.
 - `/flow-work-clean [--dry-run]` — **periodic sweep** of finished work's residue: worktree, local branch, `.claude/work/` folder (intermediate train MR/PRs never set `phase: done`, so the `ship`/`abandon` prompt never fires). Verdict per branch from **the forge** with local fallbacks, including patch-equivalence for **squash merges** (`git branch --merged` misses them); acts only on `merged`/`empty`. `unknown` never a candidate; dirty and unpushed protected; work folders **archived, never deleted**; remote never touched. **`autonomy.mode` does not authorize deletion**: `auto` confirms the list too. `--purge-archive <N>d`: separate opt-in pass over `_archive/`, only folders already committed to git.

package/adapters/hermes/skills/flow-work-handoff/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: flow-work-handoff
+description: "Hand a finished study to whoever builds it elsewhere — push only this work's folder to a branch of its own, then offer a summary for the ticket"
+---
+
+<!-- GENERATED by script/adapter-build.py from plugins/flow/commands/work/handoff.md — do not edit; change the plugin file and run the script. -->
+
+# `/flow-work-handoff`
+
+> **hermes adapter — how the Claude Code primitives named below map here.**
+> - `AskUserQuestion` → ask in plain text with numbered options and wait for the reply.
+> - `Agent <role>` / `Agent general-purpose` / subagents → `delegate_task`, which creates the child on the spot from the `goal` and `context` you give it: the name in `agents.<role>` in `FLOW.md` is a role to state in that prompt, not an agent to declare anywhere; empty → do it in this context.
+> - Parallel fan-out → several `delegate_task` calls in one response, capped at `agents.fanout_max` (empty → 4) and, above that, by `delegation.max_concurrent_children` in `config.yaml` (default 10); `agents.fanout_tool` is Claude Code-only, ignore it.
+> - `ScheduleWakeup` / `Monitor` / `/loop` → Hermes schedules itself: the `cronjob` tool, or `/cron add "every 30m" "<this command>"`. Each firing is a fresh session with no history, so the state still lives in `monitor.md` and the scheduled text must stand alone; retiring the job from inside a firing needs `cron.allow_agent_scheduling: true`.
+> - `TaskCreate` → a markdown checklist in the phase artifact.
+> - `Skill commit-commands:commit-push-pr` → `git add` · `git commit` · `git push -u origin HEAD` · the `git.cli` CLI (`gh pr create` / `glab mr create`).
+> - `/model <value>` → Hermes's own `/model`; a subagent's model is `delegation.model` in `config.yaml`, one value for every child of a round.
+> - `knowledge.*` roles → whatever tools `FLOW.md` names there; an MCP tool keeps its name, its server is declared under `mcp_servers` in `~/.hermes/config.yaml` (see `config.snippet.yaml`).
+> - `$ARGUMENTS` → what the user typed after the skill name: Hermes takes everything from the first non-skill token on as the instruction.
+
+Read `~/.claude/flow/CORE.hermes.md` first (shared rules: `FLOW.md` step 0, autonomy, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session.
+
+**Panel words are closed** — `mark`: `done` · `current` · `pending` · `wait` · `block` · `info`; `style`: `normal` · `dim` · `title` · `accent` · `ok` · `warn` · `error`. Anything else is dropped by the reader in silence: the panel still paints, and nobody is told.
+
+For a study made here and built somewhere else — a server running `/flow-work-run` unattended,
+another person, another machine. The builder gets the work folder at the same path and nothing
+else: no conversation, maybe a less capable model. So this command checks the study can stand on
+its own, pushes the folder to a branch that holds only it, and offers to put a summary in the
+ticket for the people who review it.
+
+## 1. Pre-flight
+
+- Effective FLOW configuration per flow-core §0. `autonomy.mode: unattended` → refuse in one line:
+  an unattended run never pushes (flow-core §2.1); handing off is a person's step.
+- Locate the active `meta.json` by current branch; not found → ask the user for the ticket.
+- `git.handoff_branch` empty → refuse, naming the key and an example
+  (`git.handoff_branch: study/{TICKET}`): where the study goes is the receiver's convention, never
+  flow's guess. `{TICKET}` = `meta.json.ticket`.
+- `origin` not configured → refuse; there is nowhere to push.
+
+## 2. Is the study finished?
+
+The builder can ask no one. Refuse — pushing nothing, naming every reason that holds — when:
+
+- **The study's last phase is not in `phases_done`.** A feature: `context` on XS (what `start`
+  records), `design` on S, `plan` on M/L. A bug: `context` on XS, `investigate` otherwise.
+- **`meta.json.pending` is set** — a question is still waiting for its answer.
+- **A clarification is still open** — a question under "Decisions clarified at start" in
+  `01-context.md` recorded without its answer.
+
+Any refusal names the way on: finish what is missing, or **build here** (`/flow-feat-build` /
+`/flow-bug-fix`) — a run that chained here (flow-core §2, a study made for handoff) must not end on
+a dead end.
+
+Then, **before anything is pushed**: decisions this session settled while talking that no artifact
+records yet → write them where they belong now (`01-context.md` "Decisions clarified at start",
+`03-design.md` "Decisions (ADR-light)", `04-mr-plan.md`), and say which. What was decided only in
+the chat does not travel.
+
+## 3. Build the commit, without touching the checkout
+
+A throwaway index holds only this folder, so the current branch, `HEAD`, the real index (staged
+work included) and the working tree are never read into it nor written to, and a git-ignored
+`.claude/work/` is no obstacle.
+
+**Each block below is one shell call, run as it stands** — a harness need not keep variables from
+one call to the next, so every block sets its own. Replace each `@…@` with its literal value first:
+`@WORK@` the work folder relative to the repository root (`.claude/work/<work-dir>`, no trailing
+slash), `@BRANCH@` the resolved `git.handoff_branch`, `@TICKET@` `meta.json.ticket`, `@COMMIT@` the
+sha the build block printed. A value holding a `'` cannot go inside those quotes: refuse it and
+say which.
+
+First, the branch must not exist on `origin` — a second push would need a force, and this command
+never forces:
+
+```bash handoff-check
+BRANCH='@BRANCH@'
+git ls-remote --exit-code origin "refs/heads/$BRANCH" >/dev/null; echo "rc=$?"
+```
+
+`rc=0` → the branch exists: refuse, and say what the person does next — delete it on the forge
+(only when nothing still reads it), or set another name in `git.handoff_branch`. `rc=2` → absent,
+continue. Anything else → stop and say why (no network, no access). Then build the commit:
+
+```bash handoff-build
+WORK='@WORK@'; TICKET='@TICKET@'
+cd "$(git rev-parse --show-toplevel)" || exit 1
+[ -d "$WORK" ] || { echo "no such folder: $WORK"; exit 1; }
+tmp=$(mktemp -d) || exit 1
+idx="$tmp/index"   # does not exist yet: git starts an empty index there
+GIT_INDEX_FILE="$idx" git add -f -- "$WORK" ":(exclude)$WORK/panel.json" &&
+  files=$(GIT_INDEX_FILE="$idx" git ls-files) &&
+  tree=$(GIT_INDEX_FILE="$idx" git write-tree) &&
+  commit=$(git commit-tree "$tree" -m "study $TICKET")
+rc=$?; rm -rf "$tmp"
+[ "$rc" -eq 0 ] && [ -n "$files" ] || { echo "nothing was built (rc=$rc)"; exit 1; }
+printf '%s\n' "$files"; echo "commit=$commit"
+```
+
+`GIT_INDEX_FILE` is set per command, never exported, so a failure leaves no session pointing git
+at a deleted index. `panel.json` stays out: it is this machine's terminal panel, and on another one
+it would show this session's last state as if it were theirs. The block failing → its message, and
+stop: `commit-tree` with no git identity configured is the usual cause.
+
+## 4. Confirm, then push
+
+Show the branch, the remote and the file list the build printed — every path, one per line — then
+ask with `AskUserQuestion` **in every `autonomy.mode`**: a push leaves the machine (flow-core §2).
+**Push** · **Cancel**. Nothing between the list and the question (flow-core §3).
+
+```bash handoff-push
+BRANCH='@BRANCH@'; COMMIT='@COMMIT@'
+case "$COMMIT" in ''|*[!0-9a-f]*) echo "not a commit sha: $COMMIT"; exit 1 ;; esac
+git cat-file -e "$COMMIT^{commit}" || exit 1
+git push origin "$COMMIT:refs/heads/$BRANCH"
+```
+
+The sha is checked first because `git push origin :refs/heads/<branch>` — an empty source —
+deletes the branch on the remote. A rejected push → its message, verbatim, and stop. Never retried
+with `--force`.
+
+## 5. The ticket summary (offer)
+
+Only after a successful push, and only in ticket mode with a real tracker id. The people reviewing
+the ticket read it there, never in the work folder; the receiver does not parse it.
+
+- **Read the body back** — the summary goes inside the ticket's own text, never over it:
+  `gh` → `gh issue view {TICKET} --json body -q .body` · `glab` → `glab issue view {TICKET} -F json`,
+  its `description`. Any other tracker → the offer is not made: one line saying flow cannot read that
+  body back to keep its text.
+- **The write command** — `tracker.edit_cmd`, `{TICKET}` and `{BODY_FILE}` substituted. Empty →
+  `gh issue edit {TICKET} --body-file {BODY_FILE}` for `gh`,
+  `glab issue update {TICKET} --description-file {BODY_FILE}` for `glab`.
+- **The block**, short, in the language of the ticket. A feature takes it from `01-context.md`,
+  `03-design.md` and `04-mr-plan.md`; a bug from `01-context.md` and `03-investigation.md` — the
+  expected behaviour as its criteria, the root cause and the intended fix as its design, "Areas with
+  similar risk" as its risks. A section whose source does not exist (an XS study, an S feature with
+  no plan) says `none`:
+
+  ```
+  <!-- flow-study -->
+  ## What and why
+  ## Acceptance criteria
+  ## Design in brief
+  ## MR/PR plan
+  ## Risks
+  <!-- end flow-study -->
+  ```
+
+  Criteria keep their literal values. The plan lists each MR/PR with what it covers and what it
+  waits on; a bug's plan is its single fix.
+- **The new body**: the body read above with the block between the two markers replaced — or, with
+  no markers yet, the block appended after a blank line. Written to a `mktemp` file outside the
+  tree — `{BODY_FILE}` — so nothing of it can be committed later.
+- **Show the block and ask** with `AskUserQuestion`, **in every mode**: it writes to a shared
+  tracker. **Write it** · **Skip**. Failure → its message in one line; the push stands.
+
+## 6. Close
+
+Report following flow-core §3: the branch and the commit, the file count, whether the ticket
+summary was written. Refresh the panel: a `Now` line saying the study was handed off, no `Decision`
+line. `meta.json` gains nothing — the branch on `origin` is the record, and the §3 refusal reads it.

package/adapters/hermes/skills/flow-work-resume/SKILL.md

@@ -92,7 +92,7 @@ With what is new (there is already work on disk):
 ## 4. Next step
 
 - An `Unattended:` line → the question is the orchestrator's to bring back: say so, and that answering it here instead means clearing `meta.json.pending` and continuing in this session's mode; the next step itself comes from `phase` as always.
-- Suggest the concrete command from `phase` and `size`. Interrupted phase (e.g. `build` with an empty artifact) → suggest rerunning it with `/flow-feat-build` or `/flow-bug-fix`.
+- Suggest the concrete command from `phase` and `size` — a study whose next step is `build` or `fix`: `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff). Interrupted phase (e.g. `build` with an empty artifact) → suggest rerunning it with `/flow-feat-build` or `/flow-bug-fix`.
 - §2.5 found something new → let it inform the suggestion (a contract that arrived after you left may mean rerunning `design` rather than continuing `build`); say why in one line.
 - `meta.json.related_repos` entries not `done` → remind that a **sibling repo still has a pending part** (`<repo>: <scope>`, plus `contract not handed over` when its `contract_handoff` is `pending`); suggest `/flow-feat-start <TICKET>` there. flow only reminds; it never scans or touches the other repo.
 - Do not advance on your own. The user decides.

package/adapters/opencode/CORE.md

@@ -16,7 +16,7 @@ Every `/flow-*` command assumes these rules. They are stated once, here, so a co
 carries what is specific to its phase. Read this once per session; a command that says "load
 `flow-core`" means this file.
 
-**This file belongs to flow `0.86.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.88.0`.** Compare it once, at the start of the session, against
 `version` in `~/.claude/flow/.claude-plugin/plugin.json`. The two differing means the session
 is running a **mixture** — the commands from one copy of the plugin, these shared rules from another
 — which is exactly what happens when a branch or a release candidate is loaded over an installed
@@ -217,6 +217,16 @@ sensible default and record it.
 
 Asking these anyway is how a run in `guided`/`auto` degrades into a manual one.
 
+**A study made for handoff.** `git.handoff_branch` set and the mode not `unattended` → the study is
+built somewhere else, so wherever a study phase (`start`, `design`, `plan`, `investigate`) or
+`resume` would hand the work to `/flow-feat-build` or `/flow-bug-fix`, it hands it to
+`/flow-work-handoff` instead. Only the target changes: a Close that asks (`manual`) offers **Hand
+off the study** recommended and **Build here** second; a Close that chains (`guided`/`auto`) chains
+into handoff, whose push question is the one confirmation — no stop is added. In `unattended` the
+rule does not apply: the repo's `FLOW.md` reaches the server too, and a run that studies a ticket
+there goes on to build it. A repo that hands its studies off pairs the key with
+`autonomy.mode: auto`, and the study then runs on its own up to the push.
+
 ### 2.1 `unattended` — where a person would have been asked
 
 No person is there to answer a question in this mode. A question tool — `AskUserQuestion`, OpenCode's `question`,

package/adapters/opencode/commands/flow-bug-investigate.md

@@ -34,7 +34,7 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, mo
 **In `unattended`, before this phase's first step, read flow-core §2.1 whole — from its heading to the next section, unless it is already in your context whole; having read parts of it does not count** — the orchestrator command, the question stop and the way its answer comes back are all in it, and a phase that reads only part of it skips them.
 
 - Read `meta.json` and `00-summary.md`; open in full only `01-context.md`. (flow-core §5)
-- `type` is not `bug` → refuse. `size` is `XS` → suggest `/flow-bug-fix` and stop.
+- `type` is not `bug` → refuse. `size` is `XS` → suggest `/flow-bug-fix` — `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff) — and stop.
 - Require `context` in `phases_done`.
 
 ## 1.5 Reproduce — what is failing, before why
@@ -219,5 +219,5 @@ If `knowledge.stage` is set and the root cause reveals a **non-obvious "why"** a
 
 - Update `meta.json`: `phase = "investigate"`, add to `phases_done`.
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5).
-- Suggest `/flow-bug-fix`.
-- **Autonomy handoff** (`autonomy.mode`, flow-core §2): `manual` → propose `/flow-bug-fix` with a single `AskUserQuestion`, invoke it only on confirmation; `guided`/`auto` → chain into it in this same turn.
+- Suggest `/flow-bug-fix` — `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff).
+- **Autonomy handoff** (`autonomy.mode`, flow-core §2): `manual` → propose `/flow-bug-fix` with a single `AskUserQuestion`, invoke it only on confirmation; `guided`/`auto` → chain into it in this same turn. Either way: `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff).

package/adapters/opencode/commands/flow-bug-start.md

@@ -226,6 +226,6 @@ Run `tracker.start_cmd` with `{TICKET}` = `meta.json.ticket` and `{ASSIGNEE}` =
 
 ## 5. Close
 
-- Suggest the next command by size: `/flow-bug-fix` for XS, `/flow-bug-investigate` for the rest.
+- Suggest the next command by size: `/flow-bug-fix` for XS (`git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff)), `/flow-bug-investigate` for the rest.
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5).
 - Apply `autonomy.mode`: `manual` stops and recommends; `guided`/`auto` chain into that command automatically, subject to the hard gates.

package/adapters/opencode/commands/flow-feat-design.md

@@ -38,7 +38,7 @@ after writing each challenge's Response.
 
 - Load `meta.json` by current branch — in `unattended`, the work `/flow-work-run` found (flow-core §2.1). Missing → ask the user to start with `/flow-feat-start`.
 - Read `meta.json` and `00-summary.md`; open in full only `01-context.md` (ticket, decisions, contracts received). (flow-core §5)
-- `size` is `XS` → suggest jumping to `/flow-feat-build` and stop unless the user insists.
+- `size` is `XS` → suggest jumping to `/flow-feat-build` — `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff) — and stop unless the user insists.
 
 ## 1.5 Approaches — open the option space first (M/L)
 
@@ -406,6 +406,6 @@ Never invoke `knowledge.save` here — the final save is in `/flow-feat-ship` af
 - **Confirm the acceptance criteria** within the design review: present the enumerated list. If every criterion is unambiguous and verifiable, the review covers them — no separate prompt. `AskUserQuestion` **only** when a criterion is ambiguous, not verifiable, or one is likely missing for today's ticket (same restraint as the challenger). Apply the user's edits to `03-design.md` before advancing.
 - **In `manual`/`guided`**, ask the user to review the design; edit the artifact on requested changes before advancing. **In `auto`, do not ask** — record it as accepted per the handoff below. Not an unconditional stop.
 - Next step by size:
-  - **XS / S**: suggest `/flow-feat-build` (1 single MR/PR, no planned split).
+  - **XS / S**: suggest `/flow-feat-build` (1 single MR/PR, no planned split) — `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff).
   - **M / L**: suggest `/flow-feat-plan` to split the work into independently mergeable MRs/PRs before implementing.
-- **Autonomy handoff.** Design review is a genuine decision point: `manual` and `guided` ask for it before advancing. `auto` records the design as accepted in the artifact and **chains into the command for the size** in this same turn. `manual` proposes that command with a single `AskUserQuestion` (recommended option by default), never a written suggestion. Unresolved `high`-severity findings (§6) stop the flow in **every** mode — do not chain over them.
+- **Autonomy handoff.** Design review is a genuine decision point: `manual` and `guided` ask for it before advancing. `auto` records the design as accepted in the artifact and **chains into the command for the size** in this same turn — `build` there: `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff). `manual` proposes that command with a single `AskUserQuestion` (recommended option by default), never a written suggestion. Unresolved `high`-severity findings (§6) stop the flow in **every** mode — do not chain over them.

package/adapters/opencode/commands/flow-feat-plan.md

@@ -29,7 +29,7 @@ Delivery planning phase. **No code is written.** Splits the feature into MRs/PRs
 - Load `meta.json` by current branch — in `unattended`, the work `/flow-work-run` found (flow-core §2.1). Missing → send the user to `/flow-feat-start`.
 - Require `design` in `phases_done`. Missing → send to `/flow-feat-design` and stop.
 - Read `meta.json` and `00-summary.md`; open in full only `03-design.md`. (flow-core §5)
-- **`size` `XS` or `S`** → warn that this phase does not apply (always 1 MR/PR), add `"plan:skipped"` to `phases_done`, suggest `/flow-feat-build`. Stop.
+- **`size` `XS` or `S`** → warn that this phase does not apply (always 1 MR/PR), add `"plan:skipped"` to `phases_done`, suggest `/flow-feat-build` — `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff). Stop.
 
 ## 2. Work
 
@@ -163,5 +163,5 @@ A slice landing in **another repo** is not one of *this* repo's `mrs`: record it
 
   `∥` = no dependency between them, can be built in parallel or as a train; `→` = the next wave waits for the previous one to merge. Then the table with `#`, wave, `depends_on`, title and estimate. One line for the split rationale, and — when any pair was merged — one line saying how many were and what they would have cost (`merged #a into #b: would have been a wave of its own`). Nothing else — risks and discarded alternatives live in the artifact.
 - Changes requested → edit the artifact and `meta.json.mrs` before advancing.
-- Suggest `/flow-feat-build` to start the first MR/PR.
-- **Autonomy handoff.** Approving the split is a genuine decision point: in `manual` and `guided` ask before advancing. In `auto`, record the plan as accepted in `04-mr-plan.md` and **chain into `/flow-feat-build` automatically** in this same turn. In `manual`, propose it with a single `AskUserQuestion`.
+- Suggest `/flow-feat-build` to start the first MR/PR — `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff).
+- **Autonomy handoff.** Approving the split is a genuine decision point: in `manual` and `guided` ask before advancing. In `auto`, record the plan as accepted in `04-mr-plan.md` and **chain into `/flow-feat-build` automatically** in this same turn. In `manual`, propose it with a single `AskUserQuestion`. Either way: `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff).

package/adapters/opencode/commands/flow-feat-start.md

@@ -307,5 +307,5 @@ Run `tracker.start_cmd` with `{TICKET}` = `meta.json.ticket`, `{ASSIGNEE}` = `tr
 ## 7. Close
 
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5) — first written in §6; refresh it if §6.5 changed anything.
-- Report **following the stop header** (flow-core §3), branch added, body 2-3 lines: ticket, size, branch; recommended next command per the §4 table — in `guided`/`auto` you run it in this same turn, so there is no report and no question here: update the panel and chain (flow-core §3).
+- Report **following the stop header** (flow-core §3), branch added, body 2-3 lines: ticket, size, branch; recommended next command per the §4 table (`build` on XS: `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff)) — in `guided`/`auto` you run it in this same turn, so there is no report and no question here: update the panel and chain (flow-core §3).
 - Apply `autonomy.mode`: `manual` → stop and let the user invoke the recommended command; `guided`/`auto` → chain into it, subject to the hard gates (the §5 branch-base ambiguity already stops on its own).

package/adapters/opencode/commands/flow-work-README.md

@@ -247,6 +247,7 @@ Two signals arrive on an open MR/PR, each with its own cross-cutting loop (feat
 - `/flow-work-daily [question]` — the **work assistant** (daily standup), read-only. **Local** (`.claude/work/` + git) + **forge** (open MRs/PRs, reviews awaiting you, red CI, unmergeable, unresolved threads via `git.cli`) + **tracker** (assigned tickets, priority changes via `tracker.tool`); where they cross, concrete commands (`/flow-feat-start`, `/flow-work-green`, `/flow-work-respond`). No argument → *yesterday · today · blockers*; a question → just that. External sources best-effort, never blocking; the only write is a "last seen" marker, like `/flow-news`.
 - `/flow-work-status` — all works in `.claude/work/`, current phase, divergence with git.
 - `/flow-work-run [ticket]` — the **entry an orchestrator launches** for an `unattended` run: asks it `why` (start · answer · merged · review · pipeline), routes to the phase that answers it, and makes no decision of its own. Refuses to run in any other mode.
+- `/flow-work-handoff` — hands a **finished study** to whoever builds it elsewhere (an unattended server, another machine): refuses an unfinished one, pushes only this work's folder as a parentless commit to `git.handoff_branch` without touching the checkout, asks before the push, then offers a marked summary for the ticket body (`tracker.edit_cmd`).
 - `/flow-work-resume` — detects the branch, reads `meta.json`, recaps, suggests the next step. **Re-reads the ticket's comment thread** (§2.5), reports only what is new since `01-context.md`, appends it to the artifact; never amends the design on its own.
 - `/flow-work-try <branch>` / `/flow-work-try --back` — point the main checkout at a branch to test it here, then return; re-syncs per `git.worktree_resync`. Resolves the work behind the branch and, once the environment is up, **prints the manual test plan already written** (the `needs-manual`/`unproven` criteria, or the acceptance criteria when `validate` has not run) and offers to collect Pass/Fail/Blocked into the validation artifact. No work behind the branch → the plain switch, as before.
 - `/flow-work-clean [--dry-run]` — **periodic sweep** of finished work's residue: worktree, local branch, `.claude/work/` folder (intermediate train MR/PRs never set `phase: done`, so the `ship`/`abandon` prompt never fires). Verdict per branch from **the forge** with local fallbacks, including patch-equivalence for **squash merges** (`git branch --merged` misses them); acts only on `merged`/`empty`. `unknown` never a candidate; dirty and unpushed protected; work folders **archived, never deleted**; remote never touched. **`autonomy.mode` does not authorize deletion**: `auto` confirms the list too. `--purge-archive <N>d`: separate opt-in pass over `_archive/`, only folders already committed to git.

package/adapters/opencode/commands/flow-work-handoff.md

@@ -0,0 +1,160 @@
+---
+description: Hand a finished study to whoever builds it elsewhere — push only this work's folder to a branch of its own, then offer a summary for the ticket
+---
+
+<!-- GENERATED by script/adapter-build.py from plugins/flow/commands/work/handoff.md — do not edit; change the plugin file and run the script. -->
+
+# `/flow-work-handoff`
+
+> **opencode adapter — how the Claude Code primitives named below map here.**
+> - `AskUserQuestion` → ask in plain text with numbered options and wait for the reply.
+> - `Agent <role>` / `Agent general-purpose` / subagents → `@<name>` declared in `agents/<name>.md` (`mode: subagent`); the name comes from `agents.<role>` in `FLOW.md`, empty → do it in this context.
+> - Parallel fan-out → several `@name` in one prompt, capped at `agents.fanout_max` (empty → 4); `agents.fanout_tool` is Claude Code-only, ignore it.
+> - `ScheduleWakeup` / `Monitor` / `/loop` → not available in-session: run one cycle, persist state in `monitor.md`, let the user schedule `opencode run -p "<command>"` with cron.
+> - `TaskCreate` → a markdown checklist in the phase artifact.
+> - `Skill commit-commands:commit-push-pr` → `git add` · `git commit` · `git push -u origin HEAD` · the `git.cli` CLI (`gh pr create` / `glab mr create`).
+> - `/model <value>` → opencode's model picker (`/models`).
+> - `knowledge.*` roles → whatever tools `FLOW.md` names there; an MCP tool keeps its name, its server is declared in `opencode.json` (see this adapter's `opencode.json` for the domain-memory example).
+
+Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, autonomy, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session.
+
+**Panel words are closed** — `mark`: `done` · `current` · `pending` · `wait` · `block` · `info`; `style`: `normal` · `dim` · `title` · `accent` · `ok` · `warn` · `error`. Anything else is dropped by the reader in silence: the panel still paints, and nobody is told.
+
+For a study made here and built somewhere else — a server running `/flow-work-run` unattended,
+another person, another machine. The builder gets the work folder at the same path and nothing
+else: no conversation, maybe a less capable model. So this command checks the study can stand on
+its own, pushes the folder to a branch that holds only it, and offers to put a summary in the
+ticket for the people who review it.
+
+## 1. Pre-flight
+
+- Effective FLOW configuration per flow-core §0. `autonomy.mode: unattended` → refuse in one line:
+  an unattended run never pushes (flow-core §2.1); handing off is a person's step.
+- Locate the active `meta.json` by current branch; not found → ask the user for the ticket.
+- `git.handoff_branch` empty → refuse, naming the key and an example
+  (`git.handoff_branch: study/{TICKET}`): where the study goes is the receiver's convention, never
+  flow's guess. `{TICKET}` = `meta.json.ticket`.
+- `origin` not configured → refuse; there is nowhere to push.
+
+## 2. Is the study finished?
+
+The builder can ask no one. Refuse — pushing nothing, naming every reason that holds — when:
+
+- **The study's last phase is not in `phases_done`.** A feature: `context` on XS (what `start`
+  records), `design` on S, `plan` on M/L. A bug: `context` on XS, `investigate` otherwise.
+- **`meta.json.pending` is set** — a question is still waiting for its answer.
+- **A clarification is still open** — a question under "Decisions clarified at start" in
+  `01-context.md` recorded without its answer.
+
+Any refusal names the way on: finish what is missing, or **build here** (`/flow-feat-build` /
+`/flow-bug-fix`) — a run that chained here (flow-core §2, a study made for handoff) must not end on
+a dead end.
+
+Then, **before anything is pushed**: decisions this session settled while talking that no artifact
+records yet → write them where they belong now (`01-context.md` "Decisions clarified at start",
+`03-design.md` "Decisions (ADR-light)", `04-mr-plan.md`), and say which. What was decided only in
+the chat does not travel.
+
+## 3. Build the commit, without touching the checkout
+
+A throwaway index holds only this folder, so the current branch, `HEAD`, the real index (staged
+work included) and the working tree are never read into it nor written to, and a git-ignored
+`.claude/work/` is no obstacle.
+
+**Each block below is one shell call, run as it stands** — a harness need not keep variables from
+one call to the next, so every block sets its own. Replace each `@…@` with its literal value first:
+`@WORK@` the work folder relative to the repository root (`.claude/work/<work-dir>`, no trailing
+slash), `@BRANCH@` the resolved `git.handoff_branch`, `@TICKET@` `meta.json.ticket`, `@COMMIT@` the
+sha the build block printed. A value holding a `'` cannot go inside those quotes: refuse it and
+say which.
+
+First, the branch must not exist on `origin` — a second push would need a force, and this command
+never forces:
+
+```bash handoff-check
+BRANCH='@BRANCH@'
+git ls-remote --exit-code origin "refs/heads/$BRANCH" >/dev/null; echo "rc=$?"
+```
+
+`rc=0` → the branch exists: refuse, and say what the person does next — delete it on the forge
+(only when nothing still reads it), or set another name in `git.handoff_branch`. `rc=2` → absent,
+continue. Anything else → stop and say why (no network, no access). Then build the commit:
+
+```bash handoff-build
+WORK='@WORK@'; TICKET='@TICKET@'
+cd "$(git rev-parse --show-toplevel)" || exit 1
+[ -d "$WORK" ] || { echo "no such folder: $WORK"; exit 1; }
+tmp=$(mktemp -d) || exit 1
+idx="$tmp/index"   # does not exist yet: git starts an empty index there
+GIT_INDEX_FILE="$idx" git add -f -- "$WORK" ":(exclude)$WORK/panel.json" &&
+  files=$(GIT_INDEX_FILE="$idx" git ls-files) &&
+  tree=$(GIT_INDEX_FILE="$idx" git write-tree) &&
+  commit=$(git commit-tree "$tree" -m "study $TICKET")
+rc=$?; rm -rf "$tmp"
+[ "$rc" -eq 0 ] && [ -n "$files" ] || { echo "nothing was built (rc=$rc)"; exit 1; }
+printf '%s\n' "$files"; echo "commit=$commit"
+```
+
+`GIT_INDEX_FILE` is set per command, never exported, so a failure leaves no session pointing git
+at a deleted index. `panel.json` stays out: it is this machine's terminal panel, and on another one
+it would show this session's last state as if it were theirs. The block failing → its message, and
+stop: `commit-tree` with no git identity configured is the usual cause.
+
+## 4. Confirm, then push
+
+Show the branch, the remote and the file list the build printed — every path, one per line — then
+ask with `AskUserQuestion` **in every `autonomy.mode`**: a push leaves the machine (flow-core §2).
+**Push** · **Cancel**. Nothing between the list and the question (flow-core §3).
+
+```bash handoff-push
+BRANCH='@BRANCH@'; COMMIT='@COMMIT@'
+case "$COMMIT" in ''|*[!0-9a-f]*) echo "not a commit sha: $COMMIT"; exit 1 ;; esac
+git cat-file -e "$COMMIT^{commit}" || exit 1
+git push origin "$COMMIT:refs/heads/$BRANCH"
+```
+
+The sha is checked first because `git push origin :refs/heads/<branch>` — an empty source —
+deletes the branch on the remote. A rejected push → its message, verbatim, and stop. Never retried
+with `--force`.
+
+## 5. The ticket summary (offer)
+
+Only after a successful push, and only in ticket mode with a real tracker id. The people reviewing
+the ticket read it there, never in the work folder; the receiver does not parse it.
+
+- **Read the body back** — the summary goes inside the ticket's own text, never over it:
+  `gh` → `gh issue view {TICKET} --json body -q .body` · `glab` → `glab issue view {TICKET} -F json`,
+  its `description`. Any other tracker → the offer is not made: one line saying flow cannot read that
+  body back to keep its text.
+- **The write command** — `tracker.edit_cmd`, `{TICKET}` and `{BODY_FILE}` substituted. Empty →
+  `gh issue edit {TICKET} --body-file {BODY_FILE}` for `gh`,
+  `glab issue update {TICKET} --description-file {BODY_FILE}` for `glab`.
+- **The block**, short, in the language of the ticket. A feature takes it from `01-context.md`,
+  `03-design.md` and `04-mr-plan.md`; a bug from `01-context.md` and `03-investigation.md` — the
+  expected behaviour as its criteria, the root cause and the intended fix as its design, "Areas with
+  similar risk" as its risks. A section whose source does not exist (an XS study, an S feature with
+  no plan) says `none`:
+
+  ```
+  <!-- flow-study -->
+  ## What and why
+  ## Acceptance criteria
+  ## Design in brief
+  ## MR/PR plan
+  ## Risks
+  <!-- end flow-study -->
+  ```
+
+  Criteria keep their literal values. The plan lists each MR/PR with what it covers and what it
+  waits on; a bug's plan is its single fix.
+- **The new body**: the body read above with the block between the two markers replaced — or, with
+  no markers yet, the block appended after a blank line. Written to a `mktemp` file outside the
+  tree — `{BODY_FILE}` — so nothing of it can be committed later.
+- **Show the block and ask** with `AskUserQuestion`, **in every mode**: it writes to a shared
+  tracker. **Write it** · **Skip**. Failure → its message in one line; the push stands.
+
+## 6. Close
+
+Report following flow-core §3: the branch and the commit, the file count, whether the ticket
+summary was written. Refresh the panel: a `Now` line saying the study was handed off, no `Decision`
+line. `meta.json` gains nothing — the branch on `origin` is the record, and the §3 refusal reads it.

package/adapters/opencode/commands/flow-work-resume.md

@@ -90,7 +90,7 @@ With what is new (there is already work on disk):
 ## 4. Next step
 
 - An `Unattended:` line → the question is the orchestrator's to bring back: say so, and that answering it here instead means clearing `meta.json.pending` and continuing in this session's mode; the next step itself comes from `phase` as always.
-- Suggest the concrete command from `phase` and `size`. Interrupted phase (e.g. `build` with an empty artifact) → suggest rerunning it with `/flow-feat-build` or `/flow-bug-fix`.
+- Suggest the concrete command from `phase` and `size` — a study whose next step is `build` or `fix`: `git.handoff_branch` set and not `unattended` → `/flow-work-handoff` in its place, **Hand off the study** recommended and **Build here** second where it asks (flow-core §2, a study made for handoff). Interrupted phase (e.g. `build` with an empty artifact) → suggest rerunning it with `/flow-feat-build` or `/flow-bug-fix`.
 - §2.5 found something new → let it inform the suggestion (a contract that arrived after you left may mean rerunning `design` rather than continuing `build`); say why in one line.
 - `meta.json.related_repos` entries not `done` → remind that a **sibling repo still has a pending part** (`<repo>: <scope>`, plus `contract not handed over` when its `contract_handoff` is `pending`); suggest `/flow-feat-start <TICKET>` there. flow only reminds; it never scans or touches the other repo.
 - Do not advance on your own. The user decides.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-workflows",
-  "version": "0.86.0",
+  "version": "0.88.0",
   "description": "Guided feat/bug workflows (start→ship), post-deploy monitoring and multi-agent code review, stack-agnostic. Each repo uses a shared FLOW.md plus optional harness overlay.",
   "type": "module",
   "bin": {

package/plugins/flow/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "flow",
   "displayName": "Flow — guided dev workflows",
   "description": "Guided feat/bug workflows (start→ship), post-deploy monitoring and multi-agent code review, stack-agnostic. Each repo uses a shared FLOW.md plus optional harness overlay.",
-  "version": "0.86.0",
+  "version": "0.88.0",
   "author": {
     "name": "Alberto Vioque",
     "email": "mashware@gmail.com"