Structured "design-first" dispatch: a needs_design_loop flag that routes a brief through a design-loop before build

You are being dispatched from flower Brief #248: Structured "design-first" dispatch: a needs_design_loop flag that routes a brief through a design-loop before build

Recall pointer:
- Use recall_brief with id 248 for the full folder if you need provenance.

Target:
- project: flower (/Users/mikeferrara/Documents/code/flower)
- branch: choose an appropriate branch
- worktree: not specified
- kind: fresh

Current brief spec:
# Structured "design-first" dispatch: a `needs_design_loop` flag

## Problem (operator, 2026-07-04)
When refine plans a brief that would benefit from a design-loop, today it says so only in PROSE ("design-loop candidate", as on #229/#246) — unstructured, easy to miss, not automatable. The orchestrator/worker must read the prose and remember to run the loop, or it just gets built without the design pass. Need a first-class way to mark + route "design-first" briefs.

## The shape: a SPECTRUM by size/uncertainty (not an either/or)
- **Small / well-understood → dispatch build directly** (no loop). E.g. #237, #230, #246. Refine plans → build worker.
- **Medium / design-sensitive → `needs_design_loop` flag (THIS brief's primitive).** Refine sets the flag at plan time; dispatch routes the brief to a **design worker FIRST** (writer↔reviewer design-loop → design doc → updates the brief spec → clears the flag), after which the normal **build** dispatch fires. Turns "design-loop candidate" from prose into an automatable pipeline step.
- **Large / multi-brief / phased → epic-lead (#226).** A dedicated per-epic orchestrator owns the arc and runs the design-loop as its phase 1. Heavyweight — for big fan-out features.

## DECIDED (operator Mike, 2026-07-05 — decisions #69 / #70)
- **Q1 Auto vs triggered → AUTO.** The design-loop **auto-runs when the brief hits `planned`** (mirrors auto_dispatch). Refine's flag-setting heuristic (codified in the charter, #170) is the guard against over-designing trivial one-liners — refine only sets the flag when a brief is genuinely design-sensitive.
- **Q4 Epic-lead boundary → COMPOSE.** The flag = single-brief / one-PR design-sensitive work; the epic-lead (#226) = multi-brief / phased fan-out. They **compose**: an epic-lead can set `needs_design_loop` on its children. The flag is the general lightweight primitive; epic-lead covers the large end. Neither is dropped.

## Mechanic (build-ready)
- **`briefs.needs_design_loop` (bool)** — set by refine at plan time; parallels `needs_operator_approval` / `auto_dispatch_on_planned`. Operator-toggleable in the /briefs UI (like the auto-dispatch switch, #230).
- **Dispatch routing:** `planned` + `needs_design_loop=true` → dispatch spawns a **design worker** (runs the existing `/design` skill / design-loop — Q5, reuse not reinvent) instead of a build worker. This design leg fires **automatically on `planned`** (decision #69), independent of `auto_dispatch_on_planned` (which gates the *build* leg, not the design leg).
- **Design→build handoff (Q3):** on completion the design worker updates the spec + **clears `needs_design_loop`** (→ brief is build-ready). The BUILD leg then follows the brief's normal dispatch policy: auto-fires if `auto_dispatch_on_planned=true`, else waits for orchestrator/operator dispatch. Net: the **design leg always auto-runs on planned; the build leg keeps the existing opt-in**.
- **Who sets it (Q2):** refine at plan time by judgment (heuristic → charter/#170) + operator UI toggle.
- **Symmetry:** `needs_operator_approval` gates dispatch until the operator approves; `needs_design_loop` gates the BUILD until the design-loop completes (auto-runs the loop — no operator needed).

## Guard against over-designing (from decision #69)
Refine only sets `needs_design_loop` when a brief is genuinely design-sensitive (multiple viable shapes, cross-cutting UX, unresolved design questions). The heuristic lives in the refine charter (ties #170); small/well-understood briefs skip the flag and dispatch straight to build.

## Relationships
- **#226** epic-lead — the heavyweight design-first path; composes with this flag (decision #70).
- **#170 / #155** — charter (home of the refine "when to set the flag" heuristic).
- **DispatchService** (routing) + the **`/design`** skill (the design-loop tooling).
- **Sibling motivation / first consumers:** #229 & #246 are current "design-loop candidate" briefs that this flag would route structurally instead of via prose.

## Provenance
Operator question (Mike, 2026-07-04). Refined by flower-refine; the two steers — #69 (auto) + #70 (compose) — answered by Mike 2026-07-05.

**Disposition:** `planned` — mechanic decided end-to-end; build-ready. This brief itself does NOT need a design-loop (it is well-specified). Medium build touching: migration (`briefs.needs_design_loop`), DispatchService routing (design leg auto on planned), the design-worker spawn (reuse `/design`), the /briefs UI toggle (#230-adjacent), and the refine charter heuristic (#170).

Recent/key trace events:
[1] participant_joined flower-refine: (no body)
[2] note_added flower-refine: Operator question (Mike, 2026-07-04): when a refine daemon plans a brief that would benefit from a design-loop, should there be a way to (a) flag it for a design-loop, (b) just note it in the plan prose, or (c) make it an epic-lead (#226) with a design-loop up front? This brief = the structured-flag answer, framed as a spectrum. See #244/#246 session context.
[3] plan_proposed flower-refine: # Structured "design-first" dispatch: a `needs_design_loop` flag

## Problem (operator, 2026-07-04)
When refine plans a brief that would benefit from a design-loop, today it says so only in PROSE ("design-loop candidate", as on #229/#246) — unstructured, easy to miss, not automatable. The orchestrator/worker must read the prose and remember to run the loop, or it just gets built without the design pass. Need a first-class way to mark + route "design-first" briefs.

## The shape: a SPECTRUM by size/uncertainty (not an either/or)
- **Small / well-understood → dispatch build directly** (no loop). E.g. #237, #230, #246. Refine plans → build worker.
- **Medium / design-sensitive → `needs_design_loop` flag (THIS brief's primitive).** Refine sets the flag at plan time; dispatch routes the brief to a **design worker FIRST** (writer↔reviewer design-loop → design doc → updates the brief spec → clears the flag), after which the normal **build** dispatch fires. Turns "design-loop candidate" from prose into an automatable pipeline step.
- **Large / multi-brief / phased → epic-lead (#226).** A dedicated per-epic orchestrator owns the arc and runs the design-loop as its phase 1. Heavyweight — for big fan-out features, not a one-PR tweak.

**Recommendation:** build the flag primitive as the general mechanism; epic-lead (#226) covers the large end; prose is the weak status quo we replace. They **compose** — an epic-lead can set `needs_design_loop` on its children.

## Mechanic (strawman)
- `briefs.needs_design_loop` (bool), set by refine at plan time — parallels `needs_operator_approval` / `auto_dispatch_on_planned`. Operator-toggleable in the UI too (like the auto-dispatch switch).
- **Dispatch routing:** `planned` + `needs_design_loop=true` → the dispatch spawns a **design worker** (runs the existing `/design` skill / design-loop) instead of a build worker. On completion the design worker updates the spec + **clears the flag** (or sets `design_complete`) → brief is build-ready → normal build dispatch (auto if `auto_dispatch_on_planned`, else orchestrator/operator).
- **Symmetry:** `needs_operator_approval` gates dispatch until the operator approves; `needs_design_loop` gates the BUILD until the design-loop completes (auto-runs the loop — no operator needed).

## Open questions (→ operator steer before planned)
1. **Auto vs triggered:** auto-run the design-loop on `planned`, or require an orchestrator/operator trigger? (Lean: auto, like auto_dispatch — but guard against over-designing trivial briefs.)
2. **Who sets it:** refine at plan time by judgment (codify the heuristic in the charter → ties #170) + an operator UI toggle.
3. **Design→build handoff:** design worker clears flag + spec updated → does build auto-fire, or return to a "ready for review" state first?
4. **Epic-lead interplay (#226):** flag on the epic vs on its children.
5. **Reuse:** the design worker = the existing `/design` skill dispatched as a Solo worker (not reinvented).

## Relationships
- **#226** — epic-lead (the heavyweight design-first path); this flag is the lightweight one; they compose.
- **#170 / #155** — charter (home of the refine "when to set the flag" heuristic).
- DispatchService (routing) + the `/design` skill (the design-loop tooling).
- Sibling motivation: #229 & #246 are current "design-loop candidate" briefs that this would route structurally instead of via prose.

## Provenance
Operator question (Mike, 2026-07-04). Refined by flower-refine.

**Disposition:** `refining` — concept + recommendation clear; wants operator steer on auto-vs-triggered (#1) + the epic-lead boundary (#4) before `planned`.
[4] status_change flower-refine: (no body)
[5] agent_question flower-refine: For a brief flagged `needs_design_loop`, when should the design-loop actually RUN? (This + the epic-lead boundary are the last two steers before I mark #248 planned.)
[6] agent_question flower-refine: Where's the boundary between the lightweight `needs_design_loop` flag and a full epic-lead (#226) for design-first work?
[7] participant_joined operator:mike: (no body)
[8] operator_answer operator:mike: {"choice":"auto"}
[9] operator_answer operator:mike: {"choice":"compose"}
[10] spec_snapshot flower-refine: # Structured "design-first" dispatch: a `needs_design_loop` flag

## Problem (operator, 2026-07-04)
When refine plans a brief that would benefit from a design-loop, today it says so only in PROSE ("design-loop candidate", as on #229/#246) — unstructured, easy to miss, not automatable. The orchestrator/worker must read the prose and remember to run the loop, or it just gets built without the design pass. Need a first-class way to mark + route "design-first" briefs.

## The shape: a SPECTRUM by size/uncertainty (not an either/or)
- **Small / well-understood → dispatch build directly** (no loop). E.g. #237, #230, #246. Refine plans → build worker.
- **Medium / design-sensitive → `needs_design_loop` flag (THIS brief's primitive).** Refine sets the flag at plan time; dispatch routes the brief to a **design worker FIRST** (writer↔reviewer design-loop → design doc → updates the brief spec → clears the flag), after which the normal **build** dispatch fires. Turns "design-loop candidate" from prose into an automatable pipeline step.
- **Large / multi-brief / phased → epic-lead (#226).** A dedicated per-epic orchestrator owns the arc and runs the design-loop as its phase 1. Heavyweight — for big fan-out features, not a one-PR tweak.

**Recommendation:** build the flag primitive as the general mechanism; epic-lead (#226) covers the large end; prose is the weak status quo we replace. They **compose** — an epic-lead can set `needs_design_loop` on its children.

## Mechanic (strawman)
- `briefs.needs_design_loop` (bool), set by refine at plan time — parallels `needs_operator_approval` / `auto_dispatch_on_planned`. Operator-toggleable in the UI too (like the auto-dispatch switch).
- **Dispatch routing:** `planned` + `needs_design_loop=true` → the dispatch spawns a **design worker** (runs the existing `/design` skill / design-loop) instead of a build worker. On completion the design worker updates the spec + **clears the flag** (or sets `design_complete`) → brief is build-ready → normal build dispatch (auto if `auto_dispatch_on_planned`, else orchestrator/operator).
- **Symmetry:** `needs_operator_approval` gates dispatch until the operator approves; `needs_design_loop` gates the BUILD until the design-loop completes (auto-runs the loop — no operator needed).

## Open questions (→ operator steer before planned)
1. **Auto vs triggered:** auto-run the design-loop on `planned`, or require an orchestrator/operator trigger? (Lean: auto, like auto_dispatch — but guard against over-designing trivial briefs.)
2. **Who sets it:** refine at plan time by judgment (codify the heuristic in the charter → ties #170) + an operator UI toggle.
3. **Design→build handoff:** design worker clears flag + spec updated → does build auto-fire, or return to a "ready for review" state first?
4. **Epic-lead interplay (#226):** flag on the epic vs on its children.
5. **Reuse:** the design worker = the existing `/design` skill dispatched as a Solo worker (not reinvented).

## Relationships
- **#226** — epic-lead (the heavyweight design-first path); this flag is the lightweight one; they compose.
- **#170 / #155** — charter (home of the refine "when to set the flag" heuristic).
- DispatchService (routing) + the `/design` skill (the design-loop tooling).
- Sibling motivation: #229 & #246 are current "design-loop candidate" briefs that this would route structurally instead of via prose.

## Provenance
Operator question (Mike, 2026-07-04). Refined by flower-refine.

**Disposition:** `refining` — concept + recommendation clear; wants operator steer on auto-vs-triggered (#1) + the epic-lead boundary (#4) before `planned`.
[11] refinement flower-refine: # Structured "design-first" dispatch: a `needs_design_loop` flag

## Problem (operator, 2026-07-04)
When refine plans a brief that would benefit from a design-loop, today it says so only in PROSE ("design-loop candidate", as on #229/#246) — unstructured, easy to miss, not automatable. The orchestrator/worker must read the prose and remember to run the loop, or it just gets built without the design pass. Need a first-class way to mark + route "design-first" briefs.

## The shape: a SPECTRUM by size/uncertainty (not an either/or)
- **Small / well-understood → dispatch build directly** (no loop). E.g. #237, #230, #246. Refine plans → build worker.
- **Medium / design-sensitive → `needs_design_loop` flag (THIS brief's primitive).** Refine sets the flag at plan time; dispatch routes the brief to a **design worker FIRST** (writer↔reviewer design-loop → design doc → updates the brief spec → clears the flag), after which the normal **build** dispatch fires. Turns "design-loop candidate" from prose into an automatable pipeline step.
- **Large / multi-brief / phased → epic-lead (#226).** A dedicated per-epic orchestrator owns the arc and runs the design-loop as its phase 1. Heavyweight — for big fan-out features.

## DECIDED (operator Mike, 2026-07-05 — decisions #69 / #70)
- **Q1 Auto vs triggered → AUTO.** The design-loop **auto-runs when the brief hits `planned`** (mirrors auto_dispatch). Refine's flag-setting heuristic (codified in the charter, #170) is the guard against over-designing trivial one-liners — refine only sets the flag when a brief is genuinely design-sensitive.
- **Q4 Epic-lead boundary → COMPOSE.** The flag = single-brief / one-PR design-sensitive work; the epic-lead (#226) = multi-brief / phased fan-out. They **compose**: an epic-lead can set `needs_design_loop` on its children. The flag is the general lightweight primitive; epic-lead covers the large end. Neither is dropped.

## Mechanic (build-ready)
- **`briefs.needs_design_loop` (bool)** — set by refine at plan time; parallels `needs_operator_approval` / `auto_dispatch_on_planned`. Operator-toggleable in the /briefs UI (like the auto-dispatch switch, #230).
- **Dispatch routing:** `planned` + `needs_design_loop=true` → dispatch spawns a **design worker** (runs the existing `/design` skill / design-loop — Q5, reuse not reinvent) instead of a build worker. This design leg fires **automatically on `planned`** (decision #69), independent of `auto_dispatch_on_planned` (which gates the *build* leg, not the design leg).
- **Design→build handoff (Q3):** on completion the design worker updates the spec + **clears `needs_design_loop`** (→ brief is build-ready). The BUILD leg then follows the brief's normal dispatch policy: auto-fires if `auto_dispatch_on_planned=true`, else waits for orchestrator/operator dispatch. Net: the **design leg always auto-runs on planned; the build leg keeps the existing opt-in**.
- **Who sets it (Q2):** refine at plan time by judgment (heuristic → charter/#170) + operator UI toggle.
- **Symmetry:** `needs_operator_approval` gates dispatch until the operator approves; `needs_design_loop` gates the BUILD until the design-loop completes (auto-runs the loop — no operator needed).

## Guard against over-designing (from decision #69)
Refine only sets `needs_design_loop` when a brief is genuinely design-sensitive (multiple viable shapes, cross-cutting UX, unresolved design questions). The heuristic lives in the refine charter (ties #170); small/well-understood briefs skip the flag and dispatch straight to build.

## Relationships
- **#226** epic-lead — the heavyweight design-first path; composes with this flag (decision #70).
- **#170 / #155** — charter (home of the refine "when to set the flag" heuristic).
- **DispatchService** (routing) + the **`/design`** skill (the design-loop tooling).
- **Sibling motivation / first consumers:** #229 & #246 are current "design-loop candidate" briefs that this flag would route structurally instead of via prose.

## Provenance
Operator question (Mike, 2026-07-04). Refined by flower-refine; the two steers — #69 (auto) + #70 (compose) — answered by Mike 2026-07-05.

**Disposition:** `planned` — mechanic decided end-to-end; build-ready. This brief itself does NOT need a design-loop (it is well-specified). Medium build touching: migration (`briefs.needs_design_loop`), DispatchService routing (design leg auto on planned), the design-worker spawn (reuse `/design`), the /briefs UI toggle (#230-adjacent), and the refine charter heuristic (#170).
[12] status_change flower-refine: (no body)

Recommended linked context:
{
    "todos": [],
    "scratchpads": []
}

Execution notes:
- Treat the brief as the source of truth.
- Keep work scoped to this dispatch request.
- Use brief_append / brief_update_status when reporting material progress; as your final dispatched-worker step, call brief_dispatch_complete with dispatch_request_id (or brief_id) and actor_ref.
- Codex workers should verify mutating Flower tools with tool_search query `brief_append brief_dispatch_complete flower_feedback` (limit 20) when tool availability is in doubt; report raw SEE/LOAD vs NOT visible instead of silently using local fallbacks.
- Add a git commit trailer `Brief: #248` to every commit for this brief so flower can exact-link commits back to the brief.
- Need an operator call while working this brief? A question ABOUT THIS BRIEF -> brief_ask(248, ...); a standalone decision not tied to the brief -> decision_ask(...). Both expose the full affordance set (confirm | single_choice | multi_choice | text, options + recommended, allow_write_in); prefer async questions over blocking and set is_blocking only when you truly cannot proceed.
- Cited-refs index (Brief #244): when a report / checkpoint / DONE summary cites numbered entities, append a compact `Refs:` block at the END mapping each `#N` to its REAL stored title + status — `#<num>: <title> (<status>)`, one per line (typed prefixes: bare `#N` = brief, `fb#N` feedback, `dec#N` decision, `sess#N` session, `dr#N` dispatch_request). Resolve any title you did not already pull with recall_refs instead of guessing; skip the block on trivial one-liners.