Skip to content

Retire the command catalogue for generic-argument workflows - #330

Merged
leoncheng57 merged 4 commits into
mainfrom
feat/workflows-generic-argument
Aug 30, 2026
Merged

leoncheng57 merged 4 commits into
mainfrom
feat/workflows-generic-argument

Conversation

@leoncheng57

Copy link
Copy Markdown
Owner

Eliminates the repository-owned command catalogue. All 23 files under
agent-skills/commands/ are deleted: 16 become composer workflows through a new
generic argument-taking workflow kind, and 7 are dropped because a same-subject
runtime reminder already said everything they said.

What changed

A workflow can now describe its own field. WorkflowPreset gains an optional
argument spec (label, placeholder, hint, required, maxLength) whose typed
value is the visible prompt, and an optional fixed prompt for a workflow that
collects nothing. server/routes/workflows.ts projects both; WorkflowSummary and the
public-simulator fixture carry both.

The dialog stopped growing id lists. It previously branched on workflow id in four
separate places, and one of those ternaries ended : objective.trim() — an
unrecognized id was silently treated as a Managed Child launch. It now holds one
BESPOKE_WORKFLOW_IDS set naming what is special (the five workflows with real
bespoke fields or their own submit path) plus one sendsIntoThisSession predicate
shared by the submit branch, the apply note and the buttons. An id this build has never
seen degrades to "generic form, sent into this session".

Two deliberate refusals. maxLength is clamped server-side to the prompt route's
own 100,000-character ceiling, so a preset cannot advertise a field the send would
reject. And an optional field left blank is refused rather than sent — the resulting
message would be the trusted injector with nothing to apply it to. Consequently all 16
ported arguments ship required: true; the "no subject supplied" fallback lives in the
injector text, where the agent can act on it.

The preview says what a workflow cannot promise. Every workflow that sends into
this session now shows "Sent in this session's current mode." The ported procedures
could pin their own agent in frontmatter (agent: plan for the read-only ones) and a
workflow carries no declarative mode. Declarative mode was deliberately not added, so
the old guarantee is gone and the UI states that rather than dropping it silently.

standup is the one that could not be ported cleanly. Its three !`…` shell
interpolations were its entire input dataset, and a workflow injector is never
expanded. It now instructs the agent to run those three commands itself and says
plainly that bash is likely denied in a Plan session — pretending the data was
pre-fetched would produce a confident standup written from the transcript.

Six groups, 22 workflows, nothing in Other. Review · Coordinate · Execute · Investigate · Document · Ship. groupWorkflows still appends Other for an id a
newer server ships; a shipped workflow landing there is now a test failure.

Playbooks is workflows-only. The per-project load-state badge, install-command
blocks, ScopeTable, the simulation player and /playbooks/commands* are gone, and
the page no longer calls /api/catalog at all — there is no per-directory installation
question left to ask. The reminder picker's documentation link follows to
/playbooks/workflows/<id> for the 6 reminders whose command survived as a workflow,
and renders nothing for the 6 whose command was deleted rather than converted.

Known breakage — owned by a sibling PR

Deleting agent-skills/commands/ and agent-skills/src/lib/commands.ts leaves the
static-catalogue publisher unable to compile or run:

  • npm run typecheck fails on scripts/agent-skills-site.ts (2 errors)
  • npm test fails to collect tests/agent-skills-site.test.ts (1 suite)

Both files, plus scripts/generate-agent-skills-site.ts,
scripts/stage-agent-skills-site.ts, scripts/publish-workflow-audit.ts and
.github/workflows/publish-agent-skills.yml, are deliberately untouched here: a
sibling PR retires the command publication pipeline and removes them. Merge that one
with or before this one. Nothing else is red.

Verification run here

Check Result
npm run typecheck client + server clean; tools fails only on the sibling-owned publisher
npm test 1123 passed, 2 skipped, 79/80 files — only agent-skills-site fails
npm run test:e2e:docker (full suite) exit 0 — 413 passed, 1 skipped, 1 pre-existing flake

The Docker lane was used because host ports 3410/4599/4600 were held by a sibling
worktree. The one flake (start DCA session: structured failure…, which counts a
global mock payload list) is pre-existing and passed on retry.

Human verification

Run the stack, open any session in a project.

  1. Open the composer Workflows picker. Expect 22 options in 6 groups labelled
    Review, Coordinate, Execute, Investigate, Document, Ship, and a scrollable list.
    Failure signal: a group called "Other", fewer than 22 options, or a list that
    cannot be scrolled to reach "Write a standup update".
  2. Search the picker for snippet-by-snippet. Expect exactly one result, "Post a
    snippet-by-snippet PR review". Failure signal: zero results, or the "Nothing is
    sent or launched until you confirm." line disappearing from the panel.
  3. Choose "Run the checks, then write verification steps" and leave the field empty.
    Expect one textarea labelled "Surface to verify (required — this text becomes the
    prompt)", focused, with a hint below it, and a disabled "Preview and confirm".
    Failure signal: an enabled Preview button, or no field at all.
  4. Type the notification popover on mobile and press Preview and confirm. Expect
    the "Exact prompt" block to contain exactly that sentence and nothing else, the
    trusted injector to show the full verify procedure including its failure table, and
    a line reading "Sent in this session's current mode." naming your current mode.
    Failure signal: a prompt that includes extra generated framing, an injector
    containing the literal text $ARGUMENTS, or a missing mode line.
  5. Press "Apply to composer". Expect the dialog to close and the composer draft to
    hold that sentence with the workflow chip attached, and nothing sent.
    Failure signal: a message appearing in the transcript.
  6. Reopen the same workflow, fill it again, and press Send. Expect one user message
    in the transcript showing only your typed sentence, with the trusted injector
    rendered separately as an attachment. Failure signal: the raw
    <workflow name="verify"> tag visible inside the user bubble.
  7. Switch the composer to Plan, open "Write a standup update", and preview it.
    Expect the injector to contain "Nothing is pre-fetched for you", three literal shell
    commands, and an explicit note that bash is likely denied in a Plan session.
    Failure signal: injector text that presents commit or PR data as already gathered.
  8. Open "Launch a Managed Child". Expect the objective textarea, agent buttons and
    model picker exactly as before, and a "Launch Managed Child" button (not "Send").
    Failure signal: a generic argument textarea replacing the managed-child form, or a
    Send button on this workflow.
  9. Visit /playbooks. Expect 22 workflow cards in 6 group sections, no "Commands"
    category link, no per-project "Loaded in " badge, and no install commands.
    Failure signal: a Commands nav item, or a 404 on any card link.
  10. Open /playbooks/workflows/standup, then press Escape. Expect a modal showing
    "what it asks for" (Scope, required, character bound), the exact injector, and a
    scope note mentioning the current-mode caveat; Escape returns you to
    /playbooks/workflows with focus still inside the document.
    Failure signal: focus landing on <body>, or the modal not closing.
  11. Load /playbooks/workflows/verify at 390×740 in light mode. Expect a
    full-bleed modal with no horizontal page scroll and legible (not washed-out)
    injector text. Failure signal: document.documentElement.scrollWidth > 390, or
    near-white text on the dark injector panel.
  12. Open the composer Reminder picker. Expect the "Write Human Verification Steps"
    tile to carry an external-link button pointing at /playbooks/workflows/verify,
    and the "Cite File Lines" tile to carry no link at all.
    Failure signal: a link resolving to /playbooks/commands/... (404), or a link on
    a reminder whose command was deleted.
/playbooks
full:/playbooks/workflows
/playbooks/workflows/standup
/sessions/ses_mock_done?directory=/tmp/mock-project
full:/sessions/ses_mock_workflow_main?directory=/tmp/mock-workflow-project

Adds a generic argument kind to composer workflows, ports 16 of the 23
repository-owned OpenCode commands onto it verbatim, and deletes the
command catalogue, its parser, its simulations and its Playbooks UI.

A `WorkflowPreset` may now declare one `argument` spec whose typed value
IS the visible prompt, or a fixed `prompt` when it collects nothing. The
dialog previously branched on workflow id in four places, one of which
fell through to `objective.trim()` — so an unrecognized id was silently
treated as a Managed Child launch. It now keeps a list of what is
special (the five workflows with real bespoke fields or their own submit
path) rather than a list of what is supported, so an unknown id degrades
to "generic form, sent into this session".

`maxLength` is clamped server-side to the prompt route's own 100,000
character ceiling, and an optional field left blank is refused rather
than sent: the message would be the trusted injector with nothing to
apply it to.

The preview now states "Sent in this session's current mode" for every
workflow that sends into this session. The ported procedures could pin
their own agent in frontmatter (`agent: plan` for the read-only ones)
and a workflow cannot, so the UI says the guarantee is gone instead of
dropping it silently.

The seven commands already covered by same-subject reminders —
background, build-waves, handoff, duck-mode, grill-me, cite-file-lines,
diagram — are deleted rather than converted. `standup` could not be
ported cleanly: its three shell interpolations were its entire input
dataset and an injector is never expanded, so it now instructs the agent
to run them itself and says bash may be denied in a Plan session.

Playbooks becomes workflows-only: the per-project load-state badge, the
install-command blocks, the simulation player and `/playbooks/commands*`
are gone, and the page no longer calls `/api/catalog` at all. The
reminder picker's documentation link follows to `/playbooks/workflows/`
for the six reminders whose command survived as a workflow, and renders
nothing for the six whose command was deleted.

Known breakage, owned by a sibling PR: deleting `agent-skills/commands/`
and its parser leaves `scripts/agent-skills-site.ts` and
`tests/agent-skills-site.test.ts` unable to compile or run. Those files
are deliberately untouched here.
The user reviewed the converted list and kept eight: hand off to another
session, complete an objective autonomously, operate DCA sessions over the
API, build system design artifacts, preview documentation, write a mini
design doc, leaving now, and write today's standup.

Removes red-team, review-learning, worktree-up, verify, manager-children,
native-worktree-subagents, deep-research and research-handoff from the
catalogue. They are NOT restored as commands: the command model is gone
either way. Four keep an equivalent reminder (deep-research ->
deep-research-subagents, native-worktree-subagents ->
native-worktree-subagents, research-handoff -> parallel-research-handoff,
verify -> human-verification-steps). The other four leave the app entirely
and that is intended.

The Investigate group loses both members and goes with them, leaving five
groups over fourteen workflows.

Trims the reminder-to-workflow join to the two links that still resolve,
rather than leaving four pointing at deleted pages.
@leoncheng57
leoncheng57 force-pushed the feat/workflows-generic-argument branch from 79de542 to 923aa56 Compare August 30, 2026 04:33
github-actions Bot added a commit that referenced this pull request Aug 30, 2026
Collapses the header to one row - search left, close right - and moves the
"nothing is sent until you confirm" promise into the footer hint. The
heading band cost a whole fold of a panel whose scarce resource is vertical
space, and the promise is still permanently on screen where it now sits.

Records why there is no tag chip row: workflows have no tags field, the five
group headings already carry the taxonomy, and a second one would have to be
authored, served and kept true. That is the one structural difference between
the two pickers and it is deliberate.
github-actions Bot added a commit that referenced this pull request Aug 30, 2026
The cut left six specs asserting the old shape: card and option counts of 22,
a six-group chooser, and `nth()` spot-checks naming workflows that no longer
exist. It also left three specs anchored on the deleted `verify` id - the
Playbooks detail fixture, the generic-argument dialog test, and the reminder
details link.

Re-anchors the detail fixture on system-design-artifacts, which is now the
longest injector and so the honest subject for the full-procedure, light-mode
and phone-width tests. Re-anchors the generic-argument test on goal.

Recomputes the two derived numbers rather than guessing: the chooser's
"review" search matches four titles-or-ids, not five, and the order
spot-checks now name the first entry of each of the five groups so a workflow
moving between groups fails loudly instead of shifting an opaque index.

The reminder round-trip now exercises session-handoff, one of the two joins
that survives, and asserts that human-verification-steps renders no link at
all - its command was deleted rather than converted.
github-actions Bot added a commit that referenced this pull request Aug 30, 2026
@leoncheng57
leoncheng57 marked this pull request as ready for review August 30, 2026 05:01
@leoncheng57
leoncheng57 merged commit 1d56afb into main Aug 30, 2026
7 of 8 checks passed
github-actions Bot added a commit that referenced this pull request Aug 30, 2026
leoncheng57 added a commit that referenced this pull request Aug 30, 2026
…rkflows (#338)

Records #330 in the changelog. It merged as "Retire the command catalogue for
generic-argument workflows (#330)" - a correct sentence but not a conventional
commit, so release-please would have skipped the single largest change in this
release: all 23 repository-owned commands deleted, eight converted into
generic-argument composer workflows, and the catalogue cut to fourteen.

Empty by design. The code is already on main in 1d56afb; rewriting a merged
commit to fix a changelog entry would be the more invasive repair.
leoncheng57 added a commit that referenced this pull request Aug 30, 2026
)

The simulations were deleted with the command catalogue in #330 because they
were STORED there, not because they were command-shaped ideas. All eight
surviving converted workflows had one, so the deletion silently removed working
documentation for things that still exist.

Restores the parser, playback helpers and player from 1d56afb^ into client/,
since agent-skills/src/ is gone and that tree is now declared retired. Recovers
19 examples - 8 workflows and 11 reminders, five of which needed re-keying to
their renamed ids - and authors the 7 that never existed, so coverage is 14/14
workflows and 12/12 reminders.

tests/simulations.test.ts asserts that in BOTH directions. A shipped id with no
example fails; an example for something no longer shipped fails too, which is
how a file describing a deleted capability lingers as documentation for a
feature nobody can invoke. The 5 examples for genuinely removed capabilities
stay deleted.

Workflows and reminders get separate directories because an id can be both:
session-handoff is a workflow AND a reminder, and one flat directory would serve
one's example for the other.

Every restored example invoked a slash command that no longer exists. Those are
rewritten to the real invocation, and a test pins the retired names by exact
name rather than by shape - a bare ^/[a-z] pattern also matches /etc/passwd in a
table about rejected paths.

Also adds the workflow tile's detail link. It was deliberately absent while the
page only restated the injector the form already shows; that reasoning expired
when the page gained a worked example the form cannot show.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant