skills: Relayflows v2 authoring friction, 12.4 PR-owner subscribe, and the v1 deprecation
Scope: this PR now also contains #108, and deprecates the v1 workflow skill
#108 is closed and merged in here (f41e050) so the two land as one PR — no SKILL.md overlap between them; see the fold comment for the full write-up.
Added on top of the original scope below:
orchestrating-agent-relay 2.3.1 → 2.4.0 (from #108) — subscribe the live PR-owner agent to the PR's GitHub provider resources the moment a PR number exists; rebinding after respawn, no duplicate writable helper subscriptions, unsubscribe/release hygiene, verify delivery rather than binding creation, plus the 12.4 CLI corrections.writing-agent-relay-workflows 1.6.24 → 2.0.0 — DEPRECATED. It documents the superseded v1 @relayflows/core WorkflowBuilder engine. A notice at the top of SKILL.md, and in the frontmatter description / prpm.json description / README row (that description is what an agent picks a skill on), points new work at writing-relayflows for the v2 authoring surface and relay-80-100-workflow for the v2 validation shape. All v1 reference material stays intact below the notice.migrating-persona-to-relayflow 1.0.0 → 1.1.0 — same pointer, and its stale "v2 is still under construction" bullet corrected.relay-80-100-workflow → 2.1.0 — two engine-independent lessons retargeted out of the v1 skill: don't add a repair step to a gate with nothing to repair, and grade computable things deterministically, never with an LLM. The idle-detection / per-turn-spawn material is genuinely v1-only (v2 has no interactive channel agents) and stayed put.writing-relayflows 1.2.0 → 1.3.0 — reconciles "always gate an agent step" with this PR's "enforce after the agent, not on it." The two skills contradicted each other.agent-relay-starter collection 1.1.0 → 1.2.0 — writing-relayflows replaces the deprecated skill as the required workflow-authoring package.- Root
agent-workforce-skills 1.5.0 → 1.6.0.
All 14 open review threads here, and all 3 on #108, are answered inline.
🤖 Generated with Claude Code
What this is
Friction found while authoring a real Relayflows v2 flow — a 58-step native-delivery migration campaign for AgentWorkforce/relay (flows/migrate/native-delivery.spec.ts), run against CLI 2.0.22 — plus the corroborated findings from the Relayflows v2 Field Report (2026-09-18, Julian Fann).
Two things in here each cost a full run, and neither skill mentioned them.
writing-relayflows 1.0.0 → 1.1.0
--local-agent is required for any local run with an agent step. Without it the run parks at the first agent step with a message that reads as your infrastructure is missing a worker, not pass this flag. Plus the three sharp edges around it:
- the remedy is appended only for
flows runon a YAML/JSON spec path — a.flow.tsgets no hint, andflows resumenever does (packages/sdk/src/cli/run.ts:627-640); flows resume --local-agent <run-id>accepts the flag and ignores it on a spec run (resumeFlowattaches a worker only on the authored-TS path,run.ts:209), so it parks again identically;flows schedulehas no--local-agentat all, so a scheduled agent flow parks forever on a timer.
A failing subprocess_gate tells you nothing. The lowering runs the command under stdio: 'inherit' and the daemon's stdio is captured nowhere. My implement-rust step succeeded and journaled all four required sources; its gate then failed three times and exhausted retries, reporting:
{"completionReason":"retries_exhausted","output":{"exit_code":1,"stderr_tail":"","stdout_tail":""}}
The gate command prints a verdict on every path. That verdict was in none of: the journal, .relayflowd/relayflowd.log (0 bytes), the CLI output. The skill now says to prefer artifact_exists/regex_match, and to put enforcement in a deterministic step after the agent rather than in a gate on it.
Also corrected:
- eight gate types, not three (
regex_match,artifact_exists,subprocess_gate,references_input,word_count_boundswere all missing), plus the TypeScript.gate()postfix form onStep<T>; - the three-argument
flow(name, header, body)and where a TypeScript budget lives; f.run's default lease is 30s, max 15m (packages/surface/src/context.ts:60) — invisible in the documented signature and long enough to bitegit fetch,cargo buildorgh pr createin their bad case;- there is no
failOnError: false— both workarounds documented, with why|| trueis the weaker one; permissionsis journaled and not enforced, andoptions.cwdis declared by surface+sdk and rejected by the runtime at the same version;- a green
flows checksays nothing about whether the daemon will accept the spec, so budget a shakedown run and treat green unit tests plusCHECK PASSEDas necessary but not sufficient.
relay-80-100-workflow 1.0.9 → 1.1.0
Every code example in it is the v1 builder (failOnError, captureOutput, {{steps.X.output}}, .onError()). None of those exist in v2, so following the skill literally for a v2 flow produces something that will not compile. Added:
- an up-front statement of which engine the examples are;
- a v1→v2 translation table;
- the evidence-recorder pattern that replaces
failOnError+captureOutput+{{steps.X.output}}— a script that runs a command, journals{name, command, exitCode, verdict, tail}and always exits 0, with arequire-greengate reading it back. This is what I actually had to build, and it buys something v1 didn't: final acceptance recomputes green from recordings instead of trusting an agent's report; - "don't gate agent steps in v2", for the reason above;
- two anti-pattern rows.
Verification
Every claim is cited to a file and line in AgentWorkforce/flows@e73b315e (CLI 2.0.22) or to an observed run — I checked each one against the tree rather than repeating the field report. Where a finding is the report's and I could not cheaply re-derive it (the f.gitlab writeback catalog), it is attributed and the part I did verify (providers.ts marking both supported: true identically) is what's cited.
Upstream issues filed from the same material: AgentWorkforce/flows#502–#511, all labelled factory-ready.
Both package descriptions stay under the 500-character limit that #105 fixed (475 and 492).
🤖 Generated with Claude Code
[!NOTE]
Low Risk
Documentation and package metadata only; no runtime code paths change, though mis-routed agents could follow wrong engine guidance until packages are republished.
Overview
This PR repositions the skills repo around Relayflows v2 and bumps the root package to 1.7.0, with coordinated prpm.json / README version and description updates.
Deprecation and routing: writing-agent-relay-workflows is marked DEPRECATED (2.0.0) for the v1 @relayflows/core WorkflowBuilder; new work is directed to writing-relayflows and relay-80-100-workflow. The agent-relay-starter collection now requires @agent-relay/writing-relayflows and lists the v1 skill as optional. migrating-persona-to-relayflow (1.1.0) clarifies v1 vs v2 and drops the stale “v2 under construction” wording.
relay-80-100-workflow (2.1.0) is rewritten for v2 flows: the evidence recorder (record / require-green, runId stamping) replaces v1 failOnError / captureOutput, plus edit/hazard gates, gate cross-checks, fresh-eyes review, and explicit guidance on when not to add repair steps or use LLMs as graders.
writing-relayflows (1.4.0) is reconciled with @relayflows/surface / @relayflows/sdk 2.0.22: permissions (journaled, unenforced), working predicate / artifact_exists gates, executable f.human (while f.dispatch still isn’t), and enforce-after-agent vs terminal gates aligned with the 80–100 skill. The v1 workflow skill picks up matching repair/LLM-grading cautions and idle-detection / per-turn spawn notes.
orchestrating-agent-relay (2.4.0) adds GitHub PR-owner integration subscribe (four globs, rebinding after respawn, no helper duplicate bindings, unsubscribe before release, verify real events not just --list), plus fleet inventory/release and expanded troubleshooting.
Reviewed by Cursor Bugbot for commit b373c76ea82ae05644d2317b7e5e9c79de71999c. Bugbot is set up for automated code reviews on this repo. Configure here.
Agent Relay sessions