Add the prowl-workflow bundled agent skill - #754
Merged
Conversation
Teaches any linked agent to author, validate, run, and participate in Agent Workflows. Lean SKILL.md carries task routing, the run commands, and the participant protocol; the full DSL reference and the run runbook sit under references/ for on-demand loading. Registered automatically by the ProwlSkills bundle scan; settings docs updated. Claude-Session: https://claude.ai/code/session_01M5cFnjhGxu2wxhB7yU48Yt
Two fresh agents that saw only the skill and the CLI drove it end to end (one ran a demo workflow, one authored and ran a two-agent workflow, and a launched participant loaded the skill from the typed line). Everything worked, but the pass exposed places where the skill under-specified V1: - repeat semantics: a loop is only left through a satisfied `until`; reaching `max` unsatisfied, or a loop without `until`, ends the run as `max_rounds_reached` and skips every later step. The "poor-man's if" pattern now carries that caveat, and a gave-up-verdict pattern shows how to bound a loop and still reach notify/close. - authoring reference: inputs section (integer/string/enum, required inputs), agent tokens for `agents:`, optional `kind`, multi-line `prompt`, `timeout` grammar, `on_timeout` needing `timeout`, `loop.count` after a skipped loop, enum input and `repeat` title in the worked example (re-validated). - runbook: "Watching a run" field guide for `status --json`, run states including `needs_attention` and `interrupted`, invocation-ordinal wording that matches log.md and run.json, `skills/` in the layout, panes staying open after completion, RUN_NOT_FOUND / DISPATCH_PENDING / TARGET_NOT_FOUND / AGENT_NOT_FOUND in the error table. - SKILL.md: how to find the worktree name for `[source]`, what an omitted source means inside and outside a pane, how to poll a run. - docs/components/cli.md names the new bundled skill; the 063 plan and release plan record the `prowl-workflow` name and the early D1 slice. Claude-Session: https://claude.ai/code/session_01XTYsDAXaUVUAo3Q329MeZS
shanegao
pushed a commit
to shanegao/Prowl
that referenced
this pull request
Sep 6, 2026
The release plan's Status table still read "C2 starts next" after onevcat#752 and onevcat#754 merged. Add the R2b PR ledger, the 000-plan status/PR lines, and the 063.013 slice record that scopes the rest of D1: Settings › Workflows, the workflows manual page, and the CLI reachability status deferred from C0. Claude-Session: https://claude.ai/code/session_012iYf2VkE26G6k8oqur1fyX
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Front-runs the authoring-skill half of 063 D1 (release plan, slice D1).
What this is
Workflows can be started from the CLI (R2a) and the GUI (C2/#752), but creating one still requires reading the DSL spec inside this repo — nothing teaches an arbitrary coding agent how to write, run, or take part in a workflow. This PR adds the bundled
prowl-workflowagent skill: once linked (prowl skills install prowl-workflow), a user can tell their own agent "write me a workflow that…" or "use Prowl's X workflow for this" and the agent knows the contract.Structured per agent-skills conventions (lean entry file, progressive disclosure):
skills/prowl-workflow/SKILL.md— trigger description, task routing, the run commands, and the participant protocol (the time-critical part: what to do when a[Prowl] … prowl workflow doneline appears in your pane).references/authoring.md— the full DSL: a validated worked example, roles/verbs/expect/template tables, the validator rules that aren't guessable (stepsas a sibling ofrepeat:, seed-before-loop, never spellprowl workflow done, …), and working patterns (poor-man'sif, fork/ordered join with the idle-gate caveat, broadcast outputs).references/runbook.md— run lifecycle (admission, binding resolution, watchdog/attention), the run-directory layout (log.md, ordinal ledger, atomic latest views), token travel, and the error table.Patterns and pitfalls are distilled from the recorded boundary experiments (
docs-ai/063-agent-workflows/012-v1-boundary-observations.md).Mechanics
ProwlSkillsscansResources/skills/at runtime andmake embed-skills(already inbuild-app/archive/test) stages the directory, so the skill registers automatically in Settings › Agent Skills andprowl skills list|install.prowl-workflow(singular) to match the command surfaceprowl workflow …and theprowl-cliconvention; the D1 plan'sprowl-workflowsname should be treated as superseded when the slice record is written.prowl skills path prowl-workflow, so a future Settings "Create Workflow… / Ask agent" button can hand the skill to any agent the same way the help button's "Ask agent about Prowl" hands over the docs folder.docs/components/workflows.md, and the CLI reachability status.Verification
PROWL_SKILLS_DIR=$PWD/skills prowl skills listparses both bundled skills (frontmatter contract).references/authoring.mdextracted and passedprowl workflow validate.make build-appgreen with the skill embedded;docs/components/settings.mdbundled-skill enumeration updated.https://claude.ai/code/session_01M5cFnjhGxu2wxhB7yU48Yt
Review pass (2026-09-04)
Driven end to end against a main build with two fresh agents that saw only the skill and the CLI (no repo sources or docs):
demo.launch-then-message): completed in 13 s; the launched helper loaded the skill from the typed[Prowl] …line and delivered on the first try.review.swift-count, two launched agents, verdict loop, notify, close): validated on the first attempt, run completed in 45 s, bothclose:steps closed their panes.repeat, loop reference without a seed, spelled completion command,on_timeout: skipwith a consumer) produce exactly the diagnostics the skill describes.The second commit closes the gaps that pass exposed — above all that a loop is only left through a satisfied
until(so the "poor-man's if" is not anif, and a bounded loop needs a give-up verdict to reach notify/close) — plus the inputs section, agent tokens, timeout grammar, astatus --jsonfield guide, the full run-directory layout, and the missing error codes.docs/components/cli.mdnow names the skill, and the 063 plan/release plan record theprowl-workflowname.https://claude.ai/code/session_01XTYsDAXaUVUAo3Q329MeZS