design: simulated preview of the 22-workflow composer picker (screenshots only, nothing implemented)

[leoncheng57]

These are SIMULATED previews of work that has not landed. Nothing in client/,
server/, agent-skills/ or reminders/ is changed by this PR — it contains only
16 PNGs under design/. The images were produced by a transient Playwright spec that
stubbed GET /api/workflows with a 22-workflow catalogue and screenshotted today's
real components against it. The spec was deleted before publishing, per the repo's
transient-capture convention.

Purpose: let the 22-workflow end state be reviewed now, without waiting for the
sibling conversion of 16 slash-commands into composer workflows.

---

What was simulated, and how faithfully

Element	Real or invented
The 6 existing workflows	Real — fetched from the live /api/workflows
16 new descriptions	Real — the description: frontmatter of agent-skills/commands/*.md
16 new injectors	Real — the full command body of each .md file
16 new titles	Invented — mechanical Title-Case of the command slug, lightly polished
Six group labels	Invented — Review · Coordinate · Execute · Investigate · Document · Ship
Grouping of rows	Applied by DOM re-parenting after render (see caveat below)
Icons	Real fallback — untouched, and that is itself a finding

Caveats you must read before trusting an image

1. Grouping is client-side and hardcoded, in client/lib/workflows.ts
   (WORKFLOW_GROUPS, three groups keyed by literal id). A stubbed catalogue alone
   cannot produce six groups, so after the picker painted, the rendered rows were
   re-parented into six relabelled sections. Every row is still the genuine component
   with genuine content; only the section headings and row order were rearranged.
2. The generic-argument form does not exist yet. Its screenshot is an
   approximation — managed-child (which already renders a single required
   "Objective" textarea) was opened and its child-specific chrome (agent picker, model
   picker, managed-child notes) was hidden. The filename says APPROXIMATION.
3. The long-injector preview rides design-doc-prototype's zero-field path
   because that is the only workflow that reaches the preview stage with no input.
   Its catalogue entry was swapped to carry system-design-artifacts' real 160-line
   body; the visible prompt line and the server-resolved from id "…" label were
   relabelled so the image reads coherently.
4. full-list and todays-grouping images have the dialog's height clamp lifted
   so all 22 rows fit one image. That is not a state the app can reach — it exists
   only so the whole set can be judged at once. Use the plain
   workflows-22-picker-* images for the real, clamped viewport.
5. Titles are mechanical. Real conversion titles will likely be longer prose, which
   makes rows taller than shown — so the scrolling numbers below are optimistic.

---

1. Does 22 still scan? — the main question

All 22, six groups, height clamp lifted so the whole set is visible at once:

And what you actually see in the real, clamped dialog — desktop then mobile:

Scrolled to the bottom of the same dialog:

Mobile, all 22 at once:

Yes, it needs scrolling, and a lot of it. Measured from the captures:

	panel	scroll viewport	content	screenfuls
desktop 1280×800	672×576	~438px	~1,765px	~4.0
mobile 390×740	390×607	~449px	~2,189px	~4.9

Roughly 4½ rows are visible at a time out of 22 on desktop, and 4 on mobile.
Group headings help, but at most one and a half groups are on screen at once, so the
six-way structure is never actually visible — you can only ever see the label you are
standing in. The organising idea does not survive the viewport.

2. Side-by-side with today's reminder picker (12 tiles, unmodified)

This is the most useful comparison in the set. 12 reminders in a 3-column grid of
compact, title-only tiles get four groups and ten of twelve tiles onto one desktop
screen. 22 workflows in 1-column full-width rows with a 2–3 line description get
four. The difference is the row format, not the count — and the workflow picker is
already 672px wide, most of which is empty to the right of the shorter descriptions.

3. Generic-argument form (APPROXIMATION — this kind does not exist yet)

Read as /goal: title, the real frontmatter description as subtitle, one labelled
required textarea, Cancel + "Preview and confirm". This shape looks right and needs no
new layout — the existing dialog already does it. The one thing to decide is the hint
text: (required — substituted for $ARGUMENTS in the trusted body) is shown here, and
saying where the argument lands seems worth the words, since the injector below it
is visible and contains a literal $ARGUMENTS.

4. Preview stage with the longest converted body

system-design-artifacts, 160 lines / 8,110 characters:

max-h-48 is not adequate. The clamp is 192px, which at text-xs/leading-relaxed
shows about 8 of 160 lines — roughly 5% of the body — inside a scroll region with no
indication of how much lies below. For scale, today's longest injector is
pr-snippet-review at 19 lines / 1,917 characters, which nearly fits. The converted
commands are up to 8× longer by line count.

This matters more than a normal overflow nit because decision #21 makes the visible
injector the security story: workflows invert the reminder secrecy rule specifically
so the user can read the exact trusted text before submitting. A 5% window does not
deliver that. It does not overflow or clip — it scrolls correctly — it is just far too
small to be read in.

---

Two things that are broken in today's code, not in the mock

Grouping: 16 unknown ids all fall into one "Other"

This is the unretouched render of the 22-workflow catalogue against today's client:
groupWorkflows() matches ids against a hardcoded WORKFLOW_GROUPS and sweeps
everything else into Other. Result: Review 2, Coordinate 3, Document 1, and a
16-row undifferentiated "OTHER". If the conversion ships without extending
client/lib/workflows.ts, this is what users get. Worth an explicit checklist item on
the sibling PRs.

Icons: all 16 new rows get the same fallback circle

WORKFLOW_ICONS in client/components/workflow-picker.tsx is a hardcoded
Record<string, LucideIcon> keyed by id, falling back to Circle. Every converted row
in these images shows an identical empty circle, while the original six have distinct
glyphs. In a 22-row list the icon rail is the main scanning aid, and here it carries no
information for 16 of 22 rows. Either add icons per workflow or drop the rail for
unmapped ones — an identical glyph repeated 16 times is worse than none, because it
implies a distinction that is not there.

Also worth a look: search is noisier at 22

matches() searches title + description + id. Querying review returns
"Send an update to another session" and "Start a DCA session" — because their
descriptions contain "preview" and "reviewing". With six workflows that was
harmless; with 22 the description field turns a precise query into a fuzzy one. If
search is meant to be the escape hatch from the scrolling above, it should probably
weight title/id matches above description matches, or drop description from the
haystack.

Does the mobile sheet still work?

Structurally, yes. At 390×740 the bottom sheet renders correctly at 22 items: no
clipping or horizontal overflow, the search field and the footer hint stay pinned while
only the list scrolls, group headings survive, rows wrap rather than truncate, and the
safe-area padding holds. The problem is purely quantity — ~4 rows per screen and about
five screenfuls to reach the last one.

Are the six group labels sensible?

Mostly. Review, Investigate and Document read cleanly. Two seams are soft:

• Execute vs Ship — verify and worktree-up sit in Execute while standup and
  leaving-now-wrap-up sit in Ship, but all four are "end of a work session" actions.
  Ship only has two members and may not earn a heading.
• Coordinate is overloaded at 6 of 22 — it mixes sending work to an existing
  session (session-update, session-handoff) with creating new agents
  (managed-child, start-dca-session, manager-children,
  native-worktree-subagents). That is plausibly two groups, and splitting it would
  also even out the distribution (4/6/4/2/4/2 today).

---

Suggested follow-ups (not done here — this PR is preview-only)

1. Decide the row format before the count lands. The reminder picker's compact
   title-only tile grid is the existing in-repo answer to "too many to scan", and it is
   two columns wider in the same space.
2. Extend WORKFLOW_GROUPS in the same change that adds the workflows, or the six
   groups silently become one "Other".
3. Add icons for the new ids, or suppress the rail when unmapped.
4. Raise or replace max-h-48 on the injector <pre>; at 160 lines the current clamp
   undercuts the "read the trusted text before you send" contract.
5. Consider dropping description from the search haystack.

Reproducing

The capture spec was transient and is deleted. It stubbed page.route("**/api/workflows*")
with the 22-entry catalogue, read the 16 descriptions/bodies from agent-skills/commands/*.md
at runtime, and wrote to the gitignored screenshot-output/. All images are dark mode,
desktop 1280×800 and mobile 390×740, captured as element screenshots of the popup rather
than full pages; the largest is 231 KB.

[leoncheng57]

Closing: these previews did their job. They drove four fixes that shipped in #330 — per-id icons instead of a Circle fallback, the raised injector ceiling (max-h-48 was showing ~5% of the longest procedure, which decision 21 makes a security concern, not a cosmetic one), search scoped off description, and the tile-grid layout that replaced a row list needing ~4 screenfuls.

The catalogue they depict is also now out of date: 22 workflows became 14, and Investigate is gone. Superseded rather than rejected.