flow-workflows 0.83.0 → 0.84.0

package/adapters/opencode/commands/flow-doctor.md

@@ -168,12 +168,14 @@ base branch resolvable — is §2 below; flag the key here, check the world ther
   echo the mode and remind that the hard gates stop and ask in `manual`/`guided`/`auto` and that `guided`/`auto`
   never ask about the flow's own mechanics or anything already decided (both lists: `flow:flow-core`
   skill §2). Unrecognized value → flag, `manual` assumed. `unattended` → say what it does instead of
-  the gates (flow-core §2.1): nothing is asked, questions end the run in `.claude/work/stop.json` for a runner, whose answer in `.claude/work/answer.json` lets the relaunched run continue,
-  and `ship` is a draft only when `autonomy.unattended_ship` is `draft` — echo that value, or that it
-  is empty and ship will stop on a question. Say which file set it: every session that reads that file
-  — a person's included, when they share the checkout and the harness — stops asking too, so it
-  belongs in a FLOW file only the runner's environment has. `unattended_ship` set with any other mode → note it is ignored; a
-  value other than `draft`/`stop` → flag, `stop` assumed.
+  the gates (flow-core §2.1): nothing is asked, and every run ends with one order to the
+  orchestrator command — `ask`, `publish`, `blocked` or `done`; flow pushes nothing and opens no
+  MR/PR. Echo `autonomy.orchestrator_cmd` and the file it came from, and whether its first word
+  resolves on `PATH` (`command -v`) — **empty → flag it as an error**: no phase runs in
+  `unattended` without it. Say which file set the mode: every session that reads that file — a
+  person's included, when they share the checkout and the harness — stops asking too, so it belongs
+  in a FLOW file only the orchestrator's environment has. `orchestrator_cmd` set with any other mode
+  → note it is ignored.
 
 ## 2. Checks
 

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

@@ -20,6 +20,8 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, mo
 
 **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.
 
+**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.
+
 Implementation phase. Code is written here.
 
 ## 1. Pre-flight
@@ -29,9 +31,9 @@ Implementation phase. Code is written here.
 - `size` XS/S: may start without a design — ask the user for a 2-3 line note on what will be done and save it as a minimal `03-design.md`. No MR/PR plan (always 1 MR/PR).
 - **If `meta.json.mrs` has more than one entry**: pick the **startable** MR/PR — the `pending` one with the **lowest `n` whose `depends_on` are all `merged`**. Dependencies still `pending`/`in_progress` → not startable, even with a low `n`. (No `wave`/`depends_on` — an older plan — → "first pending by `n`".)
   - **Parallel siblings**: startable `pending` MRs/PRs in the **same `wave`** with no dependency between them can be built in parallel or as a train. `manual`: let the user choose which to take now (default: lowest `n`); `guided`/`auto`: take the lowest `n`, record the choice. Mark the chosen one `in_progress`.
-  - All `merged` → warn: feature is done, nothing to build (in `unattended`: `done`, `detail` saying so).
-  - Some `pending` but **none** startable → start nothing: tell the user which MR/PR must merge to unlock the next wave, and stop. In `unattended`: `blocked`, the detail naming it.
-  - **Train/stacked** (never in `unattended`: there the startable MR/PR gets a **new branch of its own** from `git.default_base`, created as `/flow-feat-start §5.2` (in place) or `§5.4` (worktree) says — `git.worktree: always` → worktree, `off`/empty/`ask` → in place; base `git.default_base`, already decided, so §5.1 asks nothing; `--no-track`, no linked remote branch — and never commits onto a previous MR/PR's branch; flow-core §2.1): this MR/PR needs its own branch stacked on the previous one — do **not** keep committing on the previous MR/PR's branch. `/flow-feat-ship §6.2` creates and links it when it chains here; if you arrived directly and are still on the previous branch, create it now per `/flow-feat-start §5` (explicit base = the previous MR/PR's branch, `--no-track`, worktree per `git.worktree`) and, for `tracker.tool: gh`, the linked-branch step `/flow-feat-start §5.5`. Record `stacked_on` in `meta.json`. The train does **not** wait for the previous MR/PR to merge.
+  - All `merged` → warn: feature is done, nothing to build (in `unattended`: `done`, the summary saying so).
+  - Some `pending` but **none** startable → start nothing: tell the user which MR/PR must merge to unlock the next wave, and stop. In `unattended`: `blocked`, the reason naming it.
+  - **Train/stacked** (never in `unattended`: there the startable MR/PR gets a **new branch of its own** from `meta.json.base` (empty → `git.default_base`) — the base the orchestrator gave the ticket, an umbrella branch once a split task's first part is merged. That branch may exist only on the remote, or locally without the part that just merged: `git fetch origin <base>` when a remote is configured (best-effort — a fetch the container cannot make is not an error), then start from `origin/<base>` when it resolves, the local `<base>` otherwise. Named `<ticket>-<slug>-<n>` and created as `/flow-feat-start §5.2` (in place) or `§5.4` (worktree) says — `git.worktree: always` → worktree, `off`/empty/`ask` → in place; that base is already decided, so §5.1 asks nothing; `--no-track`, no linked remote branch — and never commits onto a previous MR/PR's branch; flow-core §2.1): this MR/PR needs its own branch stacked on the previous one — do **not** keep committing on the previous MR/PR's branch. `/flow-feat-ship §6.2` creates and links it when it chains here; if you arrived directly and are still on the previous branch, create it now per `/flow-feat-start §5` (explicit base = the previous MR/PR's branch, `--no-track`, worktree per `git.worktree`) and, for `tracker.tool: gh`, the linked-branch step `/flow-feat-start §5.5`. Record `stacked_on` in `meta.json`. The train does **not** wait for the previous MR/PR to merge.
 
 ## 2. Business brief (before typing)
 
@@ -65,7 +67,7 @@ In `unattended` (flow-core §2.1) nobody is there to answer: write the brief, ma
 `recorded (unattended)` under its heading, record the site in `meta.json.defaults_used[]`, and build.
 The gate's purpose moves to the draft MR/PR, whose body carries the brief for the person who reads it.
 **A schema change or migration is still a question** (`migration`): before writing the first line
-of one → stop file, end the run. A person continues from there, or a runner's answer re-enters here
+of one → the question stop, end the run. The orchestrator's answer re-enters here
 (flow-core §2.1): the brief, the contracts and the plan are already written — keep them — and the
 MR/PR is the one already `in_progress`, not a new pick. *Write it and continue* → the first unticked
 step, the migration included · *Change the design first* → `blocked`. A plan step marked approved

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

@@ -20,14 +20,16 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, mo
 
 **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.
 
+**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.
+
 Technical design phase. **Still no production code is written.** Opens the option space first (M/L), then designs the approach that was chosen. Output: a plan the next step executes.
 
 **In `unattended`** (flow-core §2.1) this command asks nothing. Panel and approach choice run as in
 `auto` · questions the options surfaced (§1.5.5) or an acceptance criterion that is ambiguous (§9) →
 question `clarify` · a size that no longer fits (§1.5.5, §7) → record the new size · a `high`
 challenge with no response (§6) → question `design_challenge`, the findings and their options in the
-stop file · the design review (§9) → recorded as accepted, as in `auto`. Each of these stops comes
-after `03-design.md` holds what the phase computed, and a runner's answer re-enters where flow-core
+question · the design review (§9) → recorded as accepted, as in `auto`. Each of these stops comes
+after `03-design.md` holds what the phase computed, and the orchestrator's answer re-enters where flow-core
 §2.1's table says: the approaches are not generated again, the design is not written again — the
 answer goes into its section, and the phase continues from the choice (§1.5.5), from §9, or from §7
 after writing each challenge's Response.

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

@@ -20,6 +20,8 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, mo
 
 **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.
 
+**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.
+
 Delivery planning phase. **No code is written.** Splits the feature into MRs/PRs that can each live on the main branch even if the subsequent ones never land.
 
 ## 1. Pre-flight

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

@@ -20,6 +20,8 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, mo
 
 **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.
 
+**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.
+
 Mandatory review phase. **`/flow-feat-ship` cannot run without passing through here and resolving blockers.**
 
 ## 1. Pre-flight
@@ -388,10 +390,9 @@ Write `.claude/work/<TICKET>/06-review.md`. The `Cost:` line of `## Summary` is
 - Report findings and next step **following the stop header** (flow-core §3) **when this is a stop**; in `guided`/`auto` with a clean gate the next command runs in this same turn, so this goes to `06-review.md` and the turn opens with the call that chains — the `Cost:` line then travels to the stop the run does reach, added to that phase's own. Include it once. Body: the findings that **survived** verification and what you did with each — a blocker, an applied fix, a rejection with its reason. Corrections to the reviewers' own reports go to `06-review.md`, not here.
 - **Autonomy handoff.** Only when there are **no blockers and no unresolved high-severity findings** — with any of those, stop in every mode (hard gate; in `unattended`, see below). Clean: in `manual`, propose `/flow-feat-validate` with a single `AskUserQuestion` and invoke it on confirmation; in `guided`/`auto`, **chain into `/flow-feat-validate` automatically** in this same turn. Never chain into `/flow-feat-ship` from here — ship is reached through `validate`.
 - **In `unattended`** (flow-core §2.1), blockers or unresolved high-severity findings are question
-  `high_findings`: the surviving findings in `question`, one line each, and the run ends — after
-  §8 has written them to `06-review.md` and the round's own fixes are committed. A person picks it
-  up in a session of their own, where they are fixed and reviewed again; or a runner answers
-  (flow-core §2.1). *Accept and go on* → this command re-enters at this Close: no reader is
+  `high_findings`: the surviving findings in the question, one line each, and the run ends — after
+  §8 has written them to `06-review.md` and the round's own fixes are committed. The orchestrator brings
+  the answer back (flow-core §2.1). *Accept and go on* → this command re-enters at this Close: no reader is
   launched again, the findings are recorded under "Answered (unattended)" as accepted by that
   answer, `reviewed_sha` = the candidate, and the phase advances and chains; `ship` lists them in
   the body. *Fix them* → this command re-enters at this Close too: it writes each finding as an

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

@@ -20,20 +20,23 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, mo
 
 **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.
 
+**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.
+
 Closes the feature: commit, push, MR/PR (assigned per `git.assignee`, squash per `git.squash`, sections per `git.request_sections`) and an optional offer to consolidate knowledge.
 
-**In `unattended`** (flow-core §2.1) this command asks nothing, and it is the only place that run
-pushes. Each place it would ask:
-
-- **The MR/PR itself (§3–§4)** — `autonomy.unattended_ship: draft` → skip the confirmation and
-  create it **as draft** with the §2 content (§4.1 says how); never merge it, never mark it ready.
-  The body gains one line saying an unattended run opened it and nobody confirmed its brief.
-  Empty or `stop` → nothing is pushed: question `ship`, the §3 preview as the question, and the run
-  ends; a person ships it from a session of their own. Pre-deploy SQL in the branch → question
-  `migration`, whatever `unattended_ship` says. A runner's answer (flow-core §2.1) relaunches this
-  command from its pre-flight, since the draft lives only in context, and the site it was for takes
-  the answer the pickup applied — *Create it as draft* creates the draft as `draft` would,
-  *The SQL is complete — ship it* goes on to the MR/PR.
+**In `unattended`** (flow-core §2.1) this command asks nothing, pushes nothing and opens nothing:
+it hands the finished MR/PR to the orchestrator, which pushes the branch and opens the draft. Each
+place it would ask:
+
+- **The MR/PR itself (§3–§4)** — no confirmation and no forge. §2's title and description are
+  written to `publish-title.md` and `publish-body.md` in the work folder; the body gains one line
+  saying an unattended run prepared it and nobody confirmed its brief. §4.0's branch check still
+  runs (never the base; the name starts with `<ticket>-`) — and an upstream on the base is unset
+  (`git branch --unset-upstream`), with no push after it. §4.1–§4.3 do not: no push, no
+  pre-deploy thread, no performance comment — those numbers go in the body. Pre-deploy SQL in the
+  branch → question `migration` first; its answer relaunches this command from its pre-flight,
+  since the draft lives only in context, and the site takes the answer just applied
+  (*The SQL is complete — ship it*) and goes on.
 - **The §1 tree check** — `reviewed_sha` or `validated_sha` behind `HEAD` with more than tests →
   re-run what is behind, **once per MR/PR**: the review on the delta, then `validate`. First record
   `{ "key": "unattended:ship-recheck", "default": "mr <n>", "phase": "ship" }` in
@@ -41,21 +44,27 @@ pushes. Each place it would ask:
   MR/PR's `n` already there → `blocked`, whatever the sha. Tracked changes this run's own phases left uncommitted → commit them
   as WIP first (a WIP commit is `auto`'s to make) and check again · **blocking TODO/FIXME (§1)** →
   continue and list them in the body.
-- **Posting anything else** — the performance comment (§4.3), a contract handoff (§6.3) — → not
-  posted; the numbers go in the body, the handoff stays `pending`.
+- **Posting anything else** — a contract handoff (§6.3) — → not posted; the handoff stays
+  `pending`.
 - **The offers and surveys (§5, §5.1, §5.2, §5.5, §6.4, §6.4bis)** → `Later`; nothing written outside
   the work folder.
-- **"Was it merged?" (§6.1)** → not merged; `meta.json` as §6.1 says for an unmerged MR/PR. **The
-  parent merged first (§6.2.1)** → blocked, never force-push. **Train continuation (§6.2)** → not
-  started: one MR/PR per unattended run.
-- **At Close** write the stop file with `reason: "done"`, `mr_url`, and — with `mrs` still pending —
-  `detail` naming the next MR/PR and what it waits on (its `depends_on` merged, then
-  `/flow-feat-build`). It is the last thing the run does.
+- **"Was it merged?" (§6.1)** → not merged: the entry stays `in_progress` (a work with no `mrs`
+  keeps `phase = "ship"`) until `publish` succeeds, below. **The parent merged first (§6.2.1)** → blocked, never
+  force-push. **Train continuation (§6.2)** → not started: one MR/PR per unattended run.
+- **At Close**, after `meta.json` and `00-summary.md` are written: commit what is left outside
+  `.claude/work/` so the tree is clean, then the run's closing order — `<cmd> publish --title-file
+  <work>/publish-title.md --body-file <work>/publish-body.md`, plus `--part <n> --of <N>` when
+  `meta.json.mrs` has more than one entry (`n` this MR/PR's, `N` the number of entries). Exit 0 →
+  this MR/PR's `mrs[]` entry gets `status: "published"` (a work with no `mrs`: `meta.json.published:
+  true`) — what `/flow-work-run` turns into `merged` when the orchestrator relaunches with
+  `why = merged` — and nothing else runs. The summary and the panel written before it say the work
+  was *handed to the orchestrator*, never that it was published. Exit ≠ 0 → nothing
+  is marked; its stderr goes in the stop header (flow-core §2.1).
 
 **In every mode**, criteria `07-validation.md` marks `not-verified-unattended` go into the body under
 `## Not verified — needs a human`, with what to do for each — and so do the tests the suite left red
 because they also fail on the base (`unattended:validate-red-base`): each name, and the base sha
-where it failed too — and the review findings a runner's answer accepted unfixed
+where it failed too — and the review findings an orchestrator's answer accepted unfixed
 (`06-review.md` "Answered (unattended)"), one line each. The §3 preview shows that section like
 any other, and the person reading it is the check the run could not do.
 
@@ -211,14 +220,7 @@ git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null   # must NOT be
 - Train mode (`stacked_on` ≠ null) → the MR/PR must target that parent branch, not the main base.
 
 ### 4.1 Create MR/PR
-**A draft (`unattended`, flow-core §2.1) — read this first: it replaces the invocation below.** Do
-**not** invoke `commit-push-pr`, and do not use the plain CLI fallback below: both open a normal
-MR/PR. Commit, `git push -u origin HEAD`, and create it with the forge CLI and its draft flag
-(`gh pr create --draft`, `glab mr create --draft`, the equivalent elsewhere), assignee and squash as
-below. The forge refusing a draft → `blocked` with its message; never retried without the flag.
-Then record the URL, as the paragraph after the bullets says.
-
-Otherwise, only here — with the content approved in §3 — invoke `Skill commit-commands:commit-push-pr` passing **the final title and description**. The skill must not re-ask for the content; if it does, answer with what was confirmed. Any push it does must be `git push -u origin HEAD` (own branch), never to the base branch.
+Only here — with the content approved in §3 — invoke `Skill commit-commands:commit-push-pr` passing **the final title and description**. The skill must not re-ask for the content; if it does, answer with what was confirmed. Any push it does must be `git push -u origin HEAD` (own branch), never to the base branch.
 
 - `git.assignee` not empty → assign to that user. `git.squash` `true` → enable squash-before-merge.
 - `commit-push-pr` skill unavailable → commit and push manually and create the MR/PR with the `git.cli` CLI from `FLOW.md` — always with the content confirmed in §3.

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

@@ -20,25 +20,31 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, mo
 
 **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.
 
+**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.
+
 `$ARGUMENTS` is **optional**:
 
 - **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.
 
 **In `unattended`** (flow-core §2.1) this command asks nothing; each place it would ask resolves as
-that table says. Here: a ticket is required — empty, or a tracker read that fails, ends the run
-`blocked` (there is no conversation to draft from and nobody to paste it) · uncommitted changes or a
-branch other than the main one (§5.1) → `blocked`: the runner owns the checkout · cross-repo scope
-(§3.5) → only the repos the ticket names · below-XS (§4) → open the work · `git.worktree: ask`
-(§5.0) → in place · §5.5's linked branch → skipped, it pushes a branch and nothing is pushed before
-`ship` · the tracker transition (§6.5) → as `auto`. **Clarifying questions (§2.1 precedence, §3)
-wait until the branch and the work folder exist** — create them (§5, §6) first, write the questions
-into `01-context.md` under "Decisions clarified at start" as open, then question `clarify` with all
-of them in one stop. Whoever picks the work up is asked them by the next phase, first (flow-core
-§2.1). That next phase is the stop's `resume` — the one §4 routes this size to — so a runner's answer
-lands there and `start` is never relaunched.
-A `blocked` before the folder exists still has the stop file: its path does not depend on the folder
-(flow-core §2.1).
+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
+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
+base → `blocked`: the orchestrator owns the checkout · the branch is named `<number>-<slug>`
+whatever `git.branch_pattern` says — the orchestrator recognises the work branch by that prefix ·
+cross-repo scope (§3.5) → only the repos the ticket names · below-XS (§4) → open the work ·
+`git.worktree: ask` (§5.0) → in place · §5.5's linked branch and the tracker transition (§6.5) →
+skipped: nothing outside the checkout is written in this mode. **Clarifying questions (§2.1
+precedence, §3) wait until the branch and the work folder exist** — create them (§5, §6) first,
+write the questions into `01-context.md` under "Decisions clarified at start" as open, then question
+`clarify` with all of them in one stop. Its `resume` is the next phase §4 routes this size to, so
+the answer lands there and `start` is never relaunched. A `blocked` before the folder exists writes
+its reason file in a `mktemp -d` directory (flow-core §2.1).
 
 ## 1. Pre-flight
 
@@ -247,6 +253,7 @@ Create the work directory per §1: `.claude/work/<TICKET>-<slug>/` (ticket mode)
 ```
 
 - 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` (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.
 - **This work *is* an accepted follow-up** (the ticket came from another work's `followups[]`, flow-core §7) → set `origin: { "work": "<originating work dir>", "followup": "F<n>" }`, carry that entry's recorded `why` into `01-context.md` verbatim instead of re-deriving it, and set the originating entry to `in_progress` with `work` naming this folder. Not a follow-up → omit `origin` entirely.
 

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

@@ -20,6 +20,8 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, mo
 
 **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.
 
+**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 the feature is complete: test coverage, edge cases, performance, regressions.
 
 ## 1. Pre-flight
@@ -162,7 +164,7 @@ If the feature has UI or critical flows:
 - Payments → test with the test cards or credentials the provider publishes for its sandbox (and the harness skill for that provider, if installed).
 - Workers/queues → make sure no jobs are stuck in dead-letter. Stuck jobs that are not yours: do not touch them here.
 - Migrations → run `quality.db_update` from `FLOW.md` (if defined; in `unattended`, never without an answer — a migration to apply is question `migration`, flow-core
-§2.1; a runner's *Apply it* relaunches this phase from §1, this site takes the answer the pickup
+§2.1; the orchestrator's *Apply it* relaunches this phase from §1, this site takes the answer just
 applied and runs it, and §6 names that answer beside the migration under "Edge cases verified"); verify no unexpected schema difference with the comparison command the project uses.
 
 ## 6. Output
@@ -224,7 +226,7 @@ Write `.claude/work/<TICKET>/07-validation.md`:
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5).
 - **Autonomy handoff — this one stops in every mode, `auto` included.** `ship` pushes and opens the MR/PR: a hard gate in every mode, so do **not** chain into it. Stop here and propose `/flow-feat-ship` with a single `AskUserQuestion` (recommended option by default), invoking it only when the user confirms. This is the deliberate end of a run in `auto`.
   **In `unattended`** (flow-core §2.1): the phase advanced → chain into `/flow-feat-ship`, which
-  decides from `autonomy.unattended_ship` between a draft MR/PR and a question. It did not advance
+  hands the MR/PR to the orchestrator with `publish`. It did not advance
   (red suite, a criterion `unproven`) → `blocked`, naming what failed; never chain. A red suite
   advances only under the base exception of flow-core §2.1: run the failing tests on the base, and
   write each name, its result there and the base sha under "Suite results" in `07-validation.md`.

package/adapters/opencode/commands/flow-init.md

@@ -99,7 +99,8 @@ review, not a questionnaire. Then, and only then, five questions:
    `auto` — also resolves the rest with recorded defaults. Explain the hard gates that stop in these
    three modes and the list of what `guided`/`auto` never ask (both in the `~/.claude/flow/CORE.opencode.md` §2),
    so `auto` runs without a stop between the brief and `ship`. Do not offer `unattended`: it is for a
-   runner, written by hand where only the runner reads it. Editable any time. Empty = `manual`.
+   run an orchestrator launches, written by hand — with `autonomy.orchestrator_cmd` — where only that
+   run reads it. Editable any time. Empty = `manual`.
 4. **The quality commands as one block** (`quality.test`, `test_one`, `static_analysis`, `style_fix`,
    `db_update`, `db_diff`) — confirm or edit what §2 found, all in one question, each may stay empty
    (= auto-discover at the moment it is needed). Several suites chain into `test` with `&&`.

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

@@ -246,6 +246,7 @@ Two signals arrive on an open MR/PR, each with its own cross-cutting loop (feat
   resume; otherwise status.
 - `/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), routes to the phase that answers it, and makes no decision of its own. Refuses to run in any other mode.
 - `/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-resume.md

@@ -21,7 +21,7 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, au
 **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.
 
 Use when returning to a work after a break (next morning, another session) — including a work an
-unattended run left waiting on a person (flow-core §2.1).
+unattended run left with a question pending at its orchestrator (flow-core §2.1).
 
 **In `unattended`** this command asks nothing: recap, name the next step, end. It is how a person
 reads where the run got to, not how the run continues.
@@ -47,7 +47,7 @@ Last updated:   <updated_at>
 Notes:          <meta.notes>
 Cross-repo:     <meta.related_repos entries not "done", as "repo: scope"; or "—">
 Ticket thread:  <new since <updated_at>: <n> comment(s) that change the work — detailed below · or "nothing new" · or "not read">   (line only in ticket mode, from §2.5)
-Unattended:     <from `.claude/work/stop.json` when its `work` is this one: `question` → the gate and the question, verbatim, with its options, its `id` and `resume` — and, when `answer_rejected` is set, which check the runner's answer failed (`answer_rejected`) · `blocked` → the detail · `running` → "a run is working in <phase>, or died there, at <at>" · `done` → the MR/PR · `picked_up` → omit the line>   (line only when that file names this work)
+Unattended:     <from `meta.json.pending` when it is set: the gate, `resume` and the question file's first line — the orchestrator holds the question and will relaunch with its answer>   (line only when `pending` is set)
 ```
 
 - `MR/PRs:` and `Waves:` from `meta.json.mrs` (same format as `/flow-work-status §2`). `∥` = can run in parallel, `→` = waits for the previous wave to merge.
@@ -89,7 +89,7 @@ With what is new (there is already work on disk):
 
 ## 4. Next step
 
-- A pending `question` in the `Unattended:` line → say that the next phase will ask it first (flow-core §2.1); the next step itself comes from `phase` as always.
+- 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`.
 - §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.

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

@@ -0,0 +1,66 @@
+---
+description: The one entry an orchestrator launches for an unattended run — asks it why it was launched and routes to the phase that answers it
+---
+
+<!-- GENERATED by script/adapter-build.py from plugins/flow/commands/work/run.md — do not edit; change the plugin file and run the script. -->
+
+# `/flow-work-run`
+
+> **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 modes and hard gates, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session. **Models: this command runs with the model it was launched with (no `models` key).**
+
+**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.
+
+**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.
+
+The command an orchestrator puts in its launch line, for every run of every ticket. It does no work
+of its own: it asks the orchestrator why this run exists and hands the run to the phase that
+answers it. `$ARGUMENTS` is the ticket, optional — the orchestrator's `ticket` order is the source
+of truth, and an argument that disagrees with it is ignored and named in the log.
+
+## 1. Pre-flight
+
+- Effective FLOW configuration per flow-core §0. `autonomy.mode` is not `unattended` → say this
+  command only routes unattended runs, name the mode and where it came from, and end: in any
+  other mode a person is the router (`/flow-next`).
+- `autonomy.orchestrator_cmd` empty → flow-core §2.1: no phase runs.
+- Run `<cmd> why`. It fails, or prints anything but `start`, `answer`, `review`, `pipeline` or
+  `merged` → print what it returned and its stderr in the §3 header and end. No closing order: an
+  orchestrator that cannot say why it launched the run cannot take one either.
+- Run `<cmd> ticket --json` and keep `number`, `title`, `base` and `kind` (`kind` absent → `feat`).
+  It fails or prints no `number` → `blocked` (flow-core §2.1).
+- Find the work: the `meta.json` under `.claude/work/` whose `ticket` equals `number` (archive
+  excluded). None is not an error — it is the "none" of the table below.
+
+## 2. Route
+
+| `why` | The work | Run |
+|---|---|---|
+| `start` | none for this ticket | `/flow-feat-start <number>` — `/flow-bug-start <number>` when `kind` is `bug` |
+| `start` | exists, `pending` set | a stop whose `ask` never landed, or a crash after it: send the same question again — `ask` with `<work>/<pending.question_file>`, `<work>/<pending.options_file>`, `--recommended 1` when that options file is not empty, `--free-text` when `pending.free_text`, `--gate pending.gate` — and end. `pending` stays as it is; nothing is recomputed |
+| `start` | exists, an `mrs[]` entry `published`, or `meta.json.published` true (a work with no `mrs`) | `done` — the summary says it is waiting for that merge; the next launch for it is `merged` |
+| `start` | exists, nothing pending | the phase after `meta.json.phase` on this work's route (`/flow-feat-start` §4 for a feature, `/flow-bug-start`'s routing for a bug, by `size`), or `phase` itself when its own Close never ran. A work folder the orchestrator restored from a study made elsewhere enters here, and is never started a second time |
+| `answer` | `pending` set | apply `<cmd> answer` as flow-core §2.1 "The answer comes back" says, then `pending.resume` at `pending.resume_at`. The order fails or prints nothing → `blocked` |
+| `answer` | nothing pending | `blocked` — there is no question for that answer to decide |
+| `merged` | exists, something published | the entry of `meta.json.mrs` whose `status` is `published` (the only one: one MR/PR per run) becomes `merged`; set `meta.json.base` to the `base` just read; the next startable MR/PR → `/flow-feat-build`; none left, or a work with no `mrs` and `published` true (one MR/PR, every bug) → `phase = done` and `done`, the summary naming the ticket as complete |
+| `merged` | none, or nothing published | `blocked` — nothing of this ticket was published from here |
+| `review` · `pipeline` | any | `blocked` — not supported yet in `unattended`; the reason says so |
+
+The phase you hand the run to is unattended too: it reads §2.1, chains as `auto` and makes the
+run's one closing order. This command makes none of its own except the re-sent `ask`, the `blocked`
+and the `done` of the table above.
+
+## 3. Close
+
+Nothing to write here beyond the routing above — the phase it hands to owns the artifacts, the
+panel and the closing order. When the route ended the run itself (`ask` → `wait`, `blocked` → `block`,
+`done` → `done`), publish the panel with that `attention` (flow-core §4) and print the §3 header.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-workflows",
-  "version": "0.83.0",
+  "version": "0.84.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.83.0",
+  "version": "0.84.0",
   "author": {
     "name": "Alberto Vioque",
     "email": "mashware@gmail.com"

package/plugins/flow/CHANGELOG.md

@@ -5,6 +5,48 @@ plugin and is what `/flow:news` reads to show you what changed since your previo
 
 The canonical, richest notes live in the [GitHub Releases](https://github.com/mashware/flow-workflows/releases).
 
+## v0.84.0 — An unattended run talks to its orchestrator through one command  ·  2026-10-01
+
+**In short**
+- **Whoever launches an unattended run now names one command, and flow talks to it through that
+  command alone.** Set `autonomy.orchestrator_cmd` (for example `orch`): the run asks it why it was
+  launched, reads the ticket and the answer from it, and ends with exactly one order — `ask` a
+  question, `publish` the finished work, say it is `blocked`, or say it is `done`.
+- **flow no longer pushes or opens MR/PRs in this mode, and needs no forge credentials.** When the
+  work is ready it commits on its own branch and hands over a title and a body; the orchestrator
+  pushes the branch and opens the draft. A split task says which part it is (`--part 2 --of 3`).
+- **One entry for every run: `/flow:work:run`.** It starts a new feature or bug from the ticket the
+  orchestrator serves, continues after an answer exactly where the run stopped, or builds the next
+  part once the previous one merged. Review comments and red pipelines end the run as "not
+  supported yet" until the next version.
+- **The stop and answer files are gone** — `.claude/work/stop.json`, `.claude/work/answer.json`, the
+  `running` mark, the person pickup and `autonomy.unattended_ship`. A pending question is recorded
+  in `meta.json.pending`; every free text (question, options, title, body, reason) travels in a
+  file, never on a command line, so a backtick in a ticket title cannot reach a shell.
+- **`unattended` without `orchestrator_cmd` runs nothing** and says why; `/flow:doctor` flags it.
+- The Codex/OpenCode smoke runner now judges the call log of a fake orchestrator
+  (`script/tests/fixtures/fake-orchestrator.sh`) instead of the stop file.
+
+Breaking for anyone running `unattended` on 0.82/0.83: add `orchestrator_cmd` and launch
+`/flow:work:run`. Nothing changes in `manual`, `guided` or `auto`. Tracked in #177; makes #176 moot.
+
+## v0.83.1 — Every unattended phase reads its stop-file rules whole  ·  2026-09-30
+
+**In short**
+- **An unattended phase no longer skips the `running` mark at its start.** On Codex, one run went
+  through build, review and validate without writing `reason: "running"` to
+  `.claude/work/stop.json`. It had read the shared rules in slices and stopped two lines short of
+  that rule, so a crash in any of those phases would have looked like an old question instead of a
+  crash.
+- **Each feat and bug phase now opens by sending an unattended run to read §2.1 whole**, from its
+  heading to the next section: the `running` write, the pending question and the runner's answer
+  are all there. The line points at the rules and repeats none of them, so it cannot contradict
+  them.
+- The preflight keeps the line identical in all fourteen phases and first after the panel line.
+  It fails if §2.1 loses its heading or one of the paragraphs the line sends the reader to.
+
+Found by the Codex smoke run of #171; tracked in #180. Nothing changes outside `unattended`.
+
 ## v0.83.0 — A runner can answer, and the run goes on  ·  2026-09-29
 
 **In short**

package/plugins/flow/examples/FLOW.template.md

@@ -100,11 +100,10 @@ How much the flow advances on its own vs. stopping to ask you.
                       #   auto   — as guided, plus auto-resolves the remaining decision points with sensible
                       #            (recorded) defaults, chaining phases without pausing.
                       #   unattended — as auto, for a run nobody watches (script, container, headless CLI):
-                      #            never asks; each hard gate is recorded, becomes a draft MR/PR, or ends
-                      #            the run with a question in .claude/work/stop.json for a runner to
-                      #            post; its answer comes back in .claude/work/answer.json and the run
-                      #            continues, or a person picks it up. One MR/PR per run. Only when set explicitly —
-                      #            in a FLOW file only the runner's environment reads.
+                      #            never asks; driven by `orchestrator_cmd`. Each hard gate is recorded or
+                      #            ends the run with one order to that command (ask · publish · blocked ·
+                      #            done); flow never pushes or opens an MR/PR. One MR/PR per run. Only when
+                      #            set explicitly — in a FLOW file only the orchestrator's environment reads.
                       # HARD GATES stop and ask in manual/guided/auto, no exceptions: any push or MR/PR (ship),
                       # branch creation with an ambiguous base, DB schema changes/migrations, a review
                       # with high-severity findings, and the business brief confirmed just before the
@@ -113,10 +112,10 @@ How much the flow advances on its own vs. stopping to ask you.
                       # (panels, challengers, how many reviewers), WIP commits, continuing a train when
                       # the train's next MR/PR in `guided`/`auto`, size confirmation, and anything already decided
                       # and recorded — only new contradicting evidence reopens a settled decision.
-- `unattended_ship:`  # What `ship` does in `unattended`: `draft` | `stop`. Empty = `stop`.
-                      #   draft — push the work branch and open the MR/PR as draft; never merge, never ready.
-                      #   stop  — nothing is pushed; ship ends the run with a question in stop.json.
-                      # Read only when mode is `unattended`.
+- `orchestrator_cmd:` # Required in `unattended`: the command that run talks to, e.g. `orch`.
+                      #   It says why the run was launched, serves the ticket and the answer, and takes
+                      #   the run's one closing order (`ask`, `publish`, `blocked`, `done`). Read only
+                      #   in that mode. The orders: flow-core §2.1.
 
 ## quality
 Repo commands for quality gates, whatever the stack — `make test`, `./gradlew test`, `dotnet test`,