npm - flow-workflows - Versions diffs - 0.94.1 → 0.95.1 - Mend

flow-workflows 0.94.1 → 0.95.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (48) hide show

package/adapters/gemini/commands/flow/work/README.toml CHANGED Viewed

@@ -252,7 +252,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 · study · answer · merged · review · pipeline), routes to the phase that answers it — a `study` run stops at the door to code with a summary for a person to approve — 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: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`). A work started with `/flow:feat:start --study` (or `/flow:bug:start --study`) ends its study here on its own; one started without the flag is built here, even with the key set.
 - `/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/gemini/commands/flow/work/resume.toml CHANGED Viewed

@@ -88,7 +88,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` — 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`.
+- Suggest the concrete command from `phase` and `size` — a study whose next step is `build` or `fix`: `meta.json.handoff` 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/hermes/CORE.md CHANGED Viewed

@@ -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.94.1`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.95.1`.** 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
@@ -249,16 +249,18 @@ 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
+**A study made for handoff.** A work started with `--study` (`/flow-feat-start`,
+`/flow-bug-start`) records `meta.json.handoff: true`: it is studied here and built somewhere else.
+That field set and the mode not `unattended` → 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 — unless the orchestrator launched it as a study run (§2.1), which stops
-at the door to code. 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.
+into handoff, whose push question is the one confirmation — no stop is added. A work started without
+`--study` is built here, whatever `git.handoff_branch` says: the key only names where a study is
+pushed, so one repo can hold both kinds of work. In `unattended` the rule does not apply: a run that
+studies a ticket there goes on to build it — unless the orchestrator launched it as a study run
+(§2.1), which stops at the door to code. With `autonomy.mode: auto`, a `--study` work runs on its
+own up to the push.
 ### 2.1 `unattended` — where a person would have been asked
@@ -392,6 +394,7 @@ person asking for changes, a ticket that already has code — is `/flow-work-run
 | An approved study's branch (`run`, `why = start`, no build or fix begun) | record — fast-forwarded to its base when it holds no commit of its own (`/flow-work-run` §2); the base unreadable or the fast-forward failing → blocked. Not integrating: nothing of the run's is merged |
 | Integrating the base into the MR/PR's branch (`green`) | on `why = conflict`, record — `git merge origin/<base>` as the orchestrator left it, never rebase, each conflict resolved on its merits (`/flow-work-green` §5.C); on any other `why`, blocked — the orchestrator brings the base in |
 | Any offer about the work's own bookkeeping — a tracker issue, the first `KNOWLEDGE.md` or a knowledge save, a FLOW convention, an agent lesson or a saved specialist, the follow-up survey, carrying files over from the main checkout, a contract handoff, archiving the work | record — `Later`; nothing written outside the work folder |
+| A wait — a suite, a quality gate, anything run in the background (`validate`, `review`) | in the turn, on its condition, with a deadline (§6.5) — never a supervisor, never a fixed-length sleep, never ending the turn to be woken |
 | A step the command cannot complete (a red suite it cannot fix, a tool missing, auth failing, the same check failing a second time) | blocked |
 | Anything `auto` already decides on its own (size, flow mechanics, WIP commits, the next command) | as `auto` |
@@ -800,7 +803,7 @@ merge now. Delegating that judgement is how a pipeline ends up declared green by
 cheapest to ask, which is the one thing `/flow-work-green` exists to forbid. Delegate the waiting
 and the evidence; the verdict stays here.
-**Then end the turn.** Dispatching a supervisor and staying in a poll loop of your own pays both
+**Then end the turn** — except in `unattended`, below. Dispatching a supervisor and staying in a poll loop of your own pays both
 bills and saves nothing. What wakes you is whatever the harness offers — a background task that
 re-invokes you when it finishes, a scheduled wake-up, a message back to this thread; where it offers
 none, the supervisor's evidence file is read at your next stop, and **you say that** rather than
@@ -817,6 +820,21 @@ moving.
 than to run — the brief, the round trip and the report are the whole of the saving. And anything you
 must *react to* mid-wait is not a wait at all: it is the work, and it stays here.
+**In `unattended`, the wait stays in the turn** (§2.1). Nobody can bring back a run whose turn
+ended, and whether a headless harness re-invokes a run when its background task finishes is not
+something the run can count on. So no supervisor and no ending the turn: the wait is sat through
+here, on the condition it waits for, with a deadline —
+- **In the foreground**, when the command fits the harness's own limit for one call.
+- **Otherwise launched with its exit code written to a file**, then waited on by a loop that checks
+  for that file every few seconds and stops at the deadline — one tool call per stretch, each under
+  that same limit, repeated until the file appears or the deadline passes. The loop runs inside the
+  call, so its cycles cost nothing on this thread.
+- **Never a fixed-length sleep.** A guessed duration pays the whole sleep when the suite finished in
+  a fraction of it, and wakes before the suite when the guess is short.
+The deadline reached with nothing back → `blocked`, naming the command and how long it ran.
 ### 6.6 — Which agent a role resolves to
 **The harness already tells you which agents are installed**, each with a line on what it is for,

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

@@ -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` — `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.
+- `type` is not `bug` → refuse. `size` is `XS` → suggest `/flow-bug-fix` — `meta.json.handoff` 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
@@ -232,5 +232,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` — `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).
+- Suggest `/flow-bug-fix` — `meta.json.handoff` 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: `meta.json.handoff` 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 CHANGED Viewed

@@ -22,12 +22,13 @@ Start a bug. `$ARGUMENTS` is **optional**:
 - **Given** — a ticket (format `tracker.prefix` from FLOW.md) → *ticket mode*: start from it (§1 reads it).
 - **Empty** — *ticket-less mode*: do **not** stop. Synthesize the bug from the conversation just held with the user (§1.5). Ask for a one-line symptom only if there is no conversation to draft from.
+- **`--study`**, anywhere in `$ARGUMENTS` — a flag, not part of the identifier: take it out before deciding the mode. The bug is studied here and fixed somewhere else: §4 records `meta.json.handoff: true`, and the study ends at `/flow-work-handoff` instead of `fix` (flow-core §2, a study made for handoff). `git.handoff_branch` empty → say in one line that `--study` needs that key, and go on as a work fixed here. Without the flag the bug is fixed here, whatever `git.handoff_branch` says.
 **In `unattended`** (flow-core §2.1) this command asks nothing; each place it would ask resolves as
 that table says. Here: **the ticket is `<cmd> ticket --json`**, not the tracker — `number` is the
 identifier, `title` and `body` replace §1's tracker read, and its `comments` (already limited to
 authorised authors) are the whole thread of §1.1; `$ARGUMENTS` that disagrees with `number` is
-ignored and named. The order failing or empty → `blocked` · **the base is the ticket's `base`**
+ignored and named, and `--study` is ignored (the orchestrator says why it launched the run). The order failing or empty → `blocked` · **the base is the ticket's `base`**
 (empty → `git.default_base`), recorded as `meta.json.base` — the branch of §3 starts there, and asks
 nothing · uncommitted changes, or a checkout not on that base → `blocked`: the orchestrator owns the
 checkout · the branch is named `<number>-<slug>` whatever `git.branch_pattern` says · cross-repo
@@ -47,7 +48,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.
 - Verify you are in the correct repo.
-- **Determine the mode** from `$ARGUMENTS`: non-empty → *ticket mode* (identifier = `$ARGUMENTS`); empty → *ticket-less mode* (identifier = the slug resolved in §1.5).
+- **Determine the mode** from `$ARGUMENTS` (`--study` already taken out): non-empty → *ticket mode* (identifier = `$ARGUMENTS`); empty → *ticket-less mode* (identifier = the slug resolved in §1.5).
 - Once the identifier is known, check whether the work already exists: ticket mode → glob `.claude/work/<TICKET>/` and `.claude/work/<TICKET>-*/` for a `meta.json` whose `ticket` equals `<TICKET>`; ticket-less → `.claude/work/<slug>/meta.json`, right after §1.5.2 decides the slug. If one exists, suggest `/flow-work-resume`.
 - This command **creates** `00-summary.md` (§4); there is nothing to read yet.
@@ -185,6 +186,8 @@ Create the work directory per §0: `.claude/work/<TICKET>-<slug>/` in ticket mod
 In `unattended`, add `"base"`: the ticket's `base`, or `git.default_base` when it is empty — never empty; the branch the fix starts from and targets. Omit it in every other mode.
+Add `"handoff": true` only when `--study` was given and `git.handoff_branch` is set; omit it otherwise.
 Populate `related_repos` from §1.6 — one `{ "repo": "<name>", "scope": "<one line>", "status": "pending", "contract_handoff": "pending" | "none" }` per *other* repo the fix touches; `[]` for a single-repo fix. `pending` only when the fix **changes a surface that sibling consumes** (a payload key, an error code, a route, an event shape); otherwise `none`.
 **This fix *is* an accepted follow-up** (the ticket came from another work's `followups[]` — typically a prevention action or a neighbouring bug, flow-core §7) → set `origin: { "work": "<originating work dir>", "followup": "F<n>" }`, carry that entry's recorded `why` into `01-context.md` verbatim rather than re-deriving it, and move the originating entry to `in_progress` with `work` naming this folder. Not a follow-up → omit `origin`.
@@ -228,6 +231,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 (`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.
+- Suggest the next command by size: `/flow-bug-fix` for XS (`meta.json.handoff` 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-bug-validate/SKILL.md CHANGED Viewed

@@ -41,7 +41,7 @@ Read `~/.claude/flow/CORE.hermes.md` first (shared rules: `FLOW.md` step 0, mode
 Then:
 1. Run only that test with `quality.test_one` from FLOW.md; it must pass.
-2. Run the full suite with `quality.test` to rule out collateral regressions (in the background if slow; measured in tens of minutes → delegate it as a wait to a supervisor subagent on `models.supervisors`, flow-core §6.5 — it returns the exit code and the failing output, and the reading of them stays here).
+2. Run the full suite with `quality.test` to rule out collateral regressions (in the background if slow — in `unattended`, waited on in this turn, flow-core §6.5; otherwise, measured in tens of minutes → delegate it as a wait to a supervisor subagent on `models.supervisors`, flow-core §6.5 — it returns the exit code and the failing output, and the reading of them stays here).
 3. DB touched → verify the schema has no unexpected differences (`quality.db_update` or the FLOW.md equivalent, if defined; in `unattended` it is never run without an answer — a schema difference to apply is question
 `migration`, flow-core §2.1; the orchestrator's *Apply it* relaunches this phase, this site takes the
 answer just applied and runs it, and `05-validation.md` names that answer beside the migration).

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

@@ -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` — `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.
+- `size` is `XS` → suggest jumping to `/flow-feat-build` — `meta.json.handoff` 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)
@@ -438,6 +438,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) — `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).
+  - **XS / S**: suggest `/flow-feat-build` (1 single MR/PR, no planned split) — `meta.json.handoff` 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 — `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.
+- **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: `meta.json.handoff` 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 CHANGED Viewed

@@ -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` — and, when `01-context.md` has `## Study revisions` (a person's reply to an unattended study, flow-core §2.1), that section too: a request about the split is applied here, and goes into §2's brief. (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` — `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.
+- **`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` — `meta.json.handoff` 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
@@ -166,5 +166,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 — `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).
+- Suggest `/flow-feat-build` to start the first MR/PR — `meta.json.handoff` 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: `meta.json.handoff` 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-review/SKILL.md CHANGED Viewed

@@ -302,7 +302,7 @@ Not run for XS/S, small diffs, or fewer than 4 ambiguous findings. When skipped,
 Read `quality.*` from `FLOW.md`. Empty → auto-discover equivalent commands (Makefile, npm/composer scripts, Gradle, dotnet, Xcode, Flutter…) and note what you use.
-Launch in parallel (background if slow):
+Launch in parallel (background if slow; in `unattended`, waited on in this turn, flow-core §6.5):
 - `quality.style_fix`
 - `quality.static_analysis`
 - `quality.test_one` (if there are new tests, with the appropriate filter)

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

@@ -28,12 +28,14 @@ Read `~/.claude/flow/CORE.hermes.md` first (shared rules: `FLOW.md` step 0, mode
 - **Given** — an identifier in `tracker.prefix` format from `FLOW.md` → *ticket mode* (§2 reads it).
 - **Empty** — *ticket-less mode*: do **not** stop or demand a ticket. Draft a ticket from the conversation just held (§2.5), as `/flow-feat-ship` builds the MR/PR body from the work log. Ask for a one-liner only if there is no conversation to draft from.
+- **`--study`**, anywhere in `$ARGUMENTS` — a flag, not part of the identifier: take it out before deciding the mode. The work is studied here and built somewhere else: §6 records `meta.json.handoff: true`, and the study ends at `/flow-work-handoff` instead of `build` (flow-core §2, a study made for handoff). `git.handoff_branch` empty → say in one line that `--study` needs that key, and go on as a work built here. Without the flag the work is built here, whatever `git.handoff_branch` says.
 **In `unattended`** (flow-core §2.1) this command asks nothing; each place it would ask resolves as
 that table says. Here: **the ticket is `<cmd> ticket --json`**, not the tracker — `number` is the
 identifier, `title` and `body` replace §2's tracker read, and its `comments` (already limited to
 authorised authors) are the whole thread of §2.1, read as that section says; `$ARGUMENTS` that
-disagrees with `number` is ignored and named. The order failing or empty → `blocked` (there is no
+disagrees with `number` is ignored and named, and `--study` is ignored (the orchestrator says why it
+launched the run). The order failing or empty → `blocked` (there is no
 conversation to draft from and nobody to paste it) · **the base is the ticket's `base`** (empty →
 `git.default_base`), recorded as `meta.json.base` — the branch of §5.2 starts there, never from
 where the checkout stands, and §5.1 asks nothing · uncommitted changes, or a checkout not on that
@@ -53,7 +55,7 @@ its reason file in a `mktemp -d` directory (flow-core §2.1).
 - Read the effective FLOW configuration per flow-core §0; no FLOW layer present → each
   step's default. This command **creates** `00-summary.md` (§6) instead of reading it (flow-core §5).
 - No recognizable project structure → warn and stop.
-- **Determine the mode**: `$ARGUMENTS` non-empty → *ticket mode* (identifier = `$ARGUMENTS`); empty → *ticket-less* (identifier = the §2.5 slug).
+- **Determine the mode** (`--study` already taken out): `$ARGUMENTS` non-empty → *ticket mode* (identifier = `$ARGUMENTS`); empty → *ticket-less* (identifier = the §2.5 slug).
 - Once the identifier is known, check the work does not exist: ticket mode → glob `.claude/work/<TICKET>/` and `.claude/work/<TICKET>-*/` for a `meta.json` whose `ticket` equals `<TICKET>`; ticket-less → `.claude/work/<slug>/meta.json`, right after the slug is decided in §2.5. Exists → do not overwrite; warn and suggest `/flow-work-resume`.
 **Work directory naming.** Work lives in `.claude/work/<work-dir>/`. `meta.json.ticket` stays the **pure identifier** (real ticket id, or the slug in ticket-less local-only) — it feeds the tracker view, the issue link and `{TICKET}`. The directory adds a slug:
@@ -254,6 +256,7 @@ Create the work directory per §1: `.claude/work/<TICKET>-<slug>/` (ticket mode)
 }
 ```
+- `handoff` — `true` only when `--study` was given and `git.handoff_branch` is set; omit it otherwise.
 - Ticket-less (§2.5) → `draft_from_conversation: true`, `tracker_issue` = created issue id/url (or `null` if local-only). Ticket mode → defaults above.
 - `base` — `unattended` only: the ticket's `base`, or `git.default_base` when it is empty — never empty (the branch every MR/PR of this work starts from and targets; `/flow-work-run` refreshes it on `merged`). Omit it in every other mode.
 - `related_repos` from §3.5 — one `{ "repo": "<name>", "scope": "<one line>", "status": "pending", "contract_handoff": "pending" | "none" }` per *other* repo; `[]` for a single-repo task.
@@ -309,5 +312,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 (`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).
+- 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: `meta.json.handoff` 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-feat-validate/SKILL.md CHANGED Viewed

@@ -46,7 +46,7 @@ One of the three below writes and two of them read, so they do not all go at onc
    **A green suite is not a performance result** — a tiny fixture database proves a query's **rows**, never its **plan**. If `/flow-feat-review §3.6` left any query verdict `unresolved`, or an acceptance criterion concerns speed or volume: run the measurement of **`/flow-work-query §4`** with the volumes in `data.volumes` (or a data set shaped like them — the distribution matters more than the total), record plan and timings, and gate on the result. No `data.*` configuration and the criterion cannot be measured → it is `unproven` with the reason, never silently `proven`.
-3. **Full suite**: run `quality.test` from `FLOW.md` in the background; if empty, auto-discover the project's test command and note what you use. **A suite measured in tens of minutes is a wait, not a step**: hand it to a supervisor subagent on `models.supervisors` (flow-core §6.5) — it runs it, times out, and brings back the exit code plus the failing tests' output, never a reading of whether those failures matter. Short suites stay here; delegating ninety seconds costs more than running them. A repo with more than one suite chains them in that one key (`make test && make test-frontend`); when it does not and the diff touches a suite the key misses, run that one too and say so in one line.
+3. **Full suite**: run `quality.test` from `FLOW.md` in the background (in `unattended`, waited on in this turn, flow-core §6.5); if empty, auto-discover the project's test command and note what you use. **A suite measured in tens of minutes is a wait, not a step**: hand it to a supervisor subagent on `models.supervisors` (flow-core §6.5) — it runs it, times out, and brings back the exit code plus the failing tests' output, never a reading of whether those failures matter. Short suites stay here; delegating ninety seconds costs more than running them. A repo with more than one suite chains them in that one key (`make test && make test-frontend`); when it does not and the diff touches a suite the key misses, run that one too and say so in one line.
 ## 3. Criteria coverage (S and larger)

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

@@ -256,7 +256,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 · study · answer · merged · review · pipeline), routes to the phase that answers it — a `study` run stops at the door to code with a summary for a person to approve — 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-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`). A work started with `/flow-feat-start --study` (or `/flow-bug-start --study`) ends its study here on its own; one started without the flag is built here, even with the key set.
 - `/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-resume/SKILL.md CHANGED Viewed

@@ -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` — 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`.
+- Suggest the concrete command from `phase` and `size` — a study whose next step is `build` or `fix`: `meta.json.handoff` 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 CHANGED Viewed

@@ -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.94.1`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.95.1`.** 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
@@ -248,16 +248,18 @@ 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
+**A study made for handoff.** A work started with `--study` (`/flow-feat-start`,
+`/flow-bug-start`) records `meta.json.handoff: true`: it is studied here and built somewhere else.
+That field set and the mode not `unattended` → 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 — unless the orchestrator launched it as a study run (§2.1), which stops
-at the door to code. 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.
+into handoff, whose push question is the one confirmation — no stop is added. A work started without
+`--study` is built here, whatever `git.handoff_branch` says: the key only names where a study is
+pushed, so one repo can hold both kinds of work. In `unattended` the rule does not apply: a run that
+studies a ticket there goes on to build it — unless the orchestrator launched it as a study run
+(§2.1), which stops at the door to code. With `autonomy.mode: auto`, a `--study` work runs on its
+own up to the push.
 ### 2.1 `unattended` — where a person would have been asked
@@ -391,6 +393,7 @@ person asking for changes, a ticket that already has code — is `/flow-work-run
 | An approved study's branch (`run`, `why = start`, no build or fix begun) | record — fast-forwarded to its base when it holds no commit of its own (`/flow-work-run` §2); the base unreadable or the fast-forward failing → blocked. Not integrating: nothing of the run's is merged |
 | Integrating the base into the MR/PR's branch (`green`) | on `why = conflict`, record — `git merge origin/<base>` as the orchestrator left it, never rebase, each conflict resolved on its merits (`/flow-work-green` §5.C); on any other `why`, blocked — the orchestrator brings the base in |
 | Any offer about the work's own bookkeeping — a tracker issue, the first `KNOWLEDGE.md` or a knowledge save, a FLOW convention, an agent lesson or a saved specialist, the follow-up survey, carrying files over from the main checkout, a contract handoff, archiving the work | record — `Later`; nothing written outside the work folder |
+| A wait — a suite, a quality gate, anything run in the background (`validate`, `review`) | in the turn, on its condition, with a deadline (§6.5) — never a supervisor, never a fixed-length sleep, never ending the turn to be woken |
 | A step the command cannot complete (a red suite it cannot fix, a tool missing, auth failing, the same check failing a second time) | blocked |
 | Anything `auto` already decides on its own (size, flow mechanics, WIP commits, the next command) | as `auto` |
@@ -799,7 +802,7 @@ merge now. Delegating that judgement is how a pipeline ends up declared green by
 cheapest to ask, which is the one thing `/flow-work-green` exists to forbid. Delegate the waiting
 and the evidence; the verdict stays here.
-**Then end the turn.** Dispatching a supervisor and staying in a poll loop of your own pays both
+**Then end the turn** — except in `unattended`, below. Dispatching a supervisor and staying in a poll loop of your own pays both
 bills and saves nothing. What wakes you is whatever the harness offers — a background task that
 re-invokes you when it finishes, a scheduled wake-up, a message back to this thread; where it offers
 none, the supervisor's evidence file is read at your next stop, and **you say that** rather than
@@ -816,6 +819,21 @@ moving.
 than to run — the brief, the round trip and the report are the whole of the saving. And anything you
 must *react to* mid-wait is not a wait at all: it is the work, and it stays here.
+**In `unattended`, the wait stays in the turn** (§2.1). Nobody can bring back a run whose turn
+ended, and whether a headless harness re-invokes a run when its background task finishes is not
+something the run can count on. So no supervisor and no ending the turn: the wait is sat through
+here, on the condition it waits for, with a deadline —
+- **In the foreground**, when the command fits the harness's own limit for one call.
+- **Otherwise launched with its exit code written to a file**, then waited on by a loop that checks
+  for that file every few seconds and stops at the deadline — one tool call per stretch, each under
+  that same limit, repeated until the file appears or the deadline passes. The loop runs inside the
+  call, so its cycles cost nothing on this thread.
+- **Never a fixed-length sleep.** A guessed duration pays the whole sleep when the suite finished in
+  a fraction of it, and wakes before the suite when the guess is short.
+The deadline reached with nothing back → `blocked`, naming the command and how long it ran.
 ### 6.6 — Which agent a role resolves to
 **The harness already tells you which agents are installed**, each with a line on what it is for,

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

@@ -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` — `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.
+- `type` is not `bug` → refuse. `size` is `XS` → suggest `/flow-bug-fix` — `meta.json.handoff` 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
@@ -230,5 +230,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` — `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).
+- Suggest `/flow-bug-fix` — `meta.json.handoff` 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: `meta.json.handoff` 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 CHANGED Viewed

@@ -20,12 +20,13 @@ Start a bug. `$ARGUMENTS` is **optional**:
 - **Given** — a ticket (format `tracker.prefix` from FLOW.md) → *ticket mode*: start from it (§1 reads it).
 - **Empty** — *ticket-less mode*: do **not** stop. Synthesize the bug from the conversation just held with the user (§1.5). Ask for a one-line symptom only if there is no conversation to draft from.
+- **`--study`**, anywhere in `$ARGUMENTS` — a flag, not part of the identifier: take it out before deciding the mode. The bug is studied here and fixed somewhere else: §4 records `meta.json.handoff: true`, and the study ends at `/flow-work-handoff` instead of `fix` (flow-core §2, a study made for handoff). `git.handoff_branch` empty → say in one line that `--study` needs that key, and go on as a work fixed here. Without the flag the bug is fixed here, whatever `git.handoff_branch` says.
 **In `unattended`** (flow-core §2.1) this command asks nothing; each place it would ask resolves as
 that table says. Here: **the ticket is `<cmd> ticket --json`**, not the tracker — `number` is the
 identifier, `title` and `body` replace §1's tracker read, and its `comments` (already limited to
 authorised authors) are the whole thread of §1.1; `$ARGUMENTS` that disagrees with `number` is
-ignored and named. The order failing or empty → `blocked` · **the base is the ticket's `base`**
+ignored and named, and `--study` is ignored (the orchestrator says why it launched the run). The order failing or empty → `blocked` · **the base is the ticket's `base`**
 (empty → `git.default_base`), recorded as `meta.json.base` — the branch of §3 starts there, and asks
 nothing · uncommitted changes, or a checkout not on that base → `blocked`: the orchestrator owns the
 checkout · the branch is named `<number>-<slug>` whatever `git.branch_pattern` says · cross-repo
@@ -45,7 +46,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.
 - Verify you are in the correct repo.
-- **Determine the mode** from `$ARGUMENTS`: non-empty → *ticket mode* (identifier = `$ARGUMENTS`); empty → *ticket-less mode* (identifier = the slug resolved in §1.5).
+- **Determine the mode** from `$ARGUMENTS` (`--study` already taken out): non-empty → *ticket mode* (identifier = `$ARGUMENTS`); empty → *ticket-less mode* (identifier = the slug resolved in §1.5).
 - Once the identifier is known, check whether the work already exists: ticket mode → glob `.claude/work/<TICKET>/` and `.claude/work/<TICKET>-*/` for a `meta.json` whose `ticket` equals `<TICKET>`; ticket-less → `.claude/work/<slug>/meta.json`, right after §1.5.2 decides the slug. If one exists, suggest `/flow-work-resume`.
 - This command **creates** `00-summary.md` (§4); there is nothing to read yet.
@@ -183,6 +184,8 @@ Create the work directory per §0: `.claude/work/<TICKET>-<slug>/` in ticket mod
 In `unattended`, add `"base"`: the ticket's `base`, or `git.default_base` when it is empty — never empty; the branch the fix starts from and targets. Omit it in every other mode.
+Add `"handoff": true` only when `--study` was given and `git.handoff_branch` is set; omit it otherwise.
 Populate `related_repos` from §1.6 — one `{ "repo": "<name>", "scope": "<one line>", "status": "pending", "contract_handoff": "pending" | "none" }` per *other* repo the fix touches; `[]` for a single-repo fix. `pending` only when the fix **changes a surface that sibling consumes** (a payload key, an error code, a route, an event shape); otherwise `none`.
 **This fix *is* an accepted follow-up** (the ticket came from another work's `followups[]` — typically a prevention action or a neighbouring bug, flow-core §7) → set `origin: { "work": "<originating work dir>", "followup": "F<n>" }`, carry that entry's recorded `why` into `01-context.md` verbatim rather than re-deriving it, and move the originating entry to `in_progress` with `work` naming this folder. Not a follow-up → omit `origin`.
@@ -226,6 +229,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 (`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.
+- Suggest the next command by size: `/flow-bug-fix` for XS (`meta.json.handoff` 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-bug-validate.md CHANGED Viewed

@@ -39,7 +39,7 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, mo
 Then:
 1. Run only that test with `quality.test_one` from FLOW.md; it must pass.
-2. Run the full suite with `quality.test` to rule out collateral regressions (in the background if slow; measured in tens of minutes → delegate it as a wait to a supervisor subagent on `models.supervisors`, flow-core §6.5 — it returns the exit code and the failing output, and the reading of them stays here).
+2. Run the full suite with `quality.test` to rule out collateral regressions (in the background if slow — in `unattended`, waited on in this turn, flow-core §6.5; otherwise, measured in tens of minutes → delegate it as a wait to a supervisor subagent on `models.supervisors`, flow-core §6.5 — it returns the exit code and the failing output, and the reading of them stays here).
 3. DB touched → verify the schema has no unexpected differences (`quality.db_update` or the FLOW.md equivalent, if defined; in `unattended` it is never run without an answer — a schema difference to apply is question
 `migration`, flow-core §2.1; the orchestrator's *Apply it* relaunches this phase, this site takes the
 answer just applied and runs it, and `05-validation.md` names that answer beside the migration).

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

@@ -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` — `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.
+- `size` is `XS` → suggest jumping to `/flow-feat-build` — `meta.json.handoff` 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)
@@ -436,6 +436,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) — `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).
+  - **XS / S**: suggest `/flow-feat-build` (1 single MR/PR, no planned split) — `meta.json.handoff` 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 — `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.
+- **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: `meta.json.handoff` 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 CHANGED Viewed

@@ -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` — and, when `01-context.md` has `## Study revisions` (a person's reply to an unattended study, flow-core §2.1), that section too: a request about the split is applied here, and goes into §2's brief. (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` — `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.
+- **`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` — `meta.json.handoff` 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
@@ -164,5 +164,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 — `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).
+- Suggest `/flow-feat-build` to start the first MR/PR — `meta.json.handoff` 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: `meta.json.handoff` 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-review.md CHANGED Viewed

@@ -300,7 +300,7 @@ Not run for XS/S, small diffs, or fewer than 4 ambiguous findings. When skipped,
 Read `quality.*` from `FLOW.md`. Empty → auto-discover equivalent commands (Makefile, npm/composer scripts, Gradle, dotnet, Xcode, Flutter…) and note what you use.
-Launch in parallel (background if slow):
+Launch in parallel (background if slow; in `unattended`, waited on in this turn, flow-core §6.5):
 - `quality.style_fix`
 - `quality.static_analysis`
 - `quality.test_one` (if there are new tests, with the appropriate filter)

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

@@ -26,12 +26,14 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, mo
 - **Given** — an identifier in `tracker.prefix` format from `FLOW.md` → *ticket mode* (§2 reads it).
 - **Empty** — *ticket-less mode*: do **not** stop or demand a ticket. Draft a ticket from the conversation just held (§2.5), as `/flow-feat-ship` builds the MR/PR body from the work log. Ask for a one-liner only if there is no conversation to draft from.
+- **`--study`**, anywhere in `$ARGUMENTS` — a flag, not part of the identifier: take it out before deciding the mode. The work is studied here and built somewhere else: §6 records `meta.json.handoff: true`, and the study ends at `/flow-work-handoff` instead of `build` (flow-core §2, a study made for handoff). `git.handoff_branch` empty → say in one line that `--study` needs that key, and go on as a work built here. Without the flag the work is built here, whatever `git.handoff_branch` says.
 **In `unattended`** (flow-core §2.1) this command asks nothing; each place it would ask resolves as
 that table says. Here: **the ticket is `<cmd> ticket --json`**, not the tracker — `number` is the
 identifier, `title` and `body` replace §2's tracker read, and its `comments` (already limited to
 authorised authors) are the whole thread of §2.1, read as that section says; `$ARGUMENTS` that
-disagrees with `number` is ignored and named. The order failing or empty → `blocked` (there is no
+disagrees with `number` is ignored and named, and `--study` is ignored (the orchestrator says why it
+launched the run). The order failing or empty → `blocked` (there is no
 conversation to draft from and nobody to paste it) · **the base is the ticket's `base`** (empty →
 `git.default_base`), recorded as `meta.json.base` — the branch of §5.2 starts there, never from
 where the checkout stands, and §5.1 asks nothing · uncommitted changes, or a checkout not on that
@@ -51,7 +53,7 @@ its reason file in a `mktemp -d` directory (flow-core §2.1).
 - Read the effective FLOW configuration per flow-core §0; no FLOW layer present → each
   step's default. This command **creates** `00-summary.md` (§6) instead of reading it (flow-core §5).
 - No recognizable project structure → warn and stop.
-- **Determine the mode**: `$ARGUMENTS` non-empty → *ticket mode* (identifier = `$ARGUMENTS`); empty → *ticket-less* (identifier = the §2.5 slug).
+- **Determine the mode** (`--study` already taken out): `$ARGUMENTS` non-empty → *ticket mode* (identifier = `$ARGUMENTS`); empty → *ticket-less* (identifier = the §2.5 slug).
 - Once the identifier is known, check the work does not exist: ticket mode → glob `.claude/work/<TICKET>/` and `.claude/work/<TICKET>-*/` for a `meta.json` whose `ticket` equals `<TICKET>`; ticket-less → `.claude/work/<slug>/meta.json`, right after the slug is decided in §2.5. Exists → do not overwrite; warn and suggest `/flow-work-resume`.
 **Work directory naming.** Work lives in `.claude/work/<work-dir>/`. `meta.json.ticket` stays the **pure identifier** (real ticket id, or the slug in ticket-less local-only) — it feeds the tracker view, the issue link and `{TICKET}`. The directory adds a slug:
@@ -252,6 +254,7 @@ Create the work directory per §1: `.claude/work/<TICKET>-<slug>/` (ticket mode)
 }
 ```
+- `handoff` — `true` only when `--study` was given and `git.handoff_branch` is set; omit it otherwise.
 - Ticket-less (§2.5) → `draft_from_conversation: true`, `tracker_issue` = created issue id/url (or `null` if local-only). Ticket mode → defaults above.
 - `base` — `unattended` only: the ticket's `base`, or `git.default_base` when it is empty — never empty (the branch every MR/PR of this work starts from and targets; `/flow-work-run` refreshes it on `merged`). Omit it in every other mode.
 - `related_repos` from §3.5 — one `{ "repo": "<name>", "scope": "<one line>", "status": "pending", "contract_handoff": "pending" | "none" }` per *other* repo; `[]` for a single-repo task.
@@ -307,5 +310,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 (`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).
+- 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: `meta.json.handoff` 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).