skills: Relayflows v2 authoring friction, 12.4 PR-owner subscribe, and the v1 deprecation

README.md

@@ -2,19 +2,19 @@
 
 Skills, slash commands, and a Claude Code plugin for building multi-agent systems with Agent Relay.
 
-Package metadata lives in [prpm.json](prpm.json). The repo currently publishes `agent-workforce-skills` version `1.1.6`.
+Package metadata lives in [prpm.json](prpm.json). The repo currently publishes `agent-workforce-skills` version `1.7.0`.
 
 ## Published Skills
 
 | Skill | Version | Description |
 |-------|---------|-------------|
 | [choosing-swarm-patterns](skills/choosing-swarm-patterns/SKILL.md) | 1.1.5 | Pick the right Agent Relay orchestration pattern across the 10 core swarm patterns plus specialized patterns. |
-| [writing-agent-relay-workflows](skills/writing-agent-relay-workflows/SKILL.md) | 1.6.24 | Build multi-agent workflows with WorkflowBuilder, DAG dependencies, Relayfile-backed Slack human assistance, integration subscriptions, waitFor gates, review-depth review/fix loops, channels, and chat-native coordination recipes. |
+| [writing-agent-relay-workflows](skills/writing-agent-relay-workflows/SKILL.md) | 2.0.0 | **DEPRECATED** - the superseded v1 `@relayflows/core` WorkflowBuilder engine. Use [`writing-relayflows`](skills/writing-relayflows/SKILL.md) for v2; keep this only to maintain an existing v1 workflow. |
 | [setting-up-relayfile](skills/setting-up-relayfile/SKILL.md) | 1.1.1 | Set up Relayfile mounts and writeback for provider files through local filesystem access. |
-| [writing-relayflows](skills/writing-relayflows/SKILL.md) | 1.0.0 | Author a Relayflows v2 flow (`@relayflows/surface`/`@relayflows/sdk`, the `flows` CLI) in TypeScript or YAML/JSON — the run/llm/agent ladder, verification gates, cli/model resolution, flows.json, and real `flows check`/`run` refusal shapes. Not the older `@relayflows/core` WorkflowBuilder engine. |
+| [writing-relayflows](skills/writing-relayflows/SKILL.md) | 1.4.0 | Author a Relayflows v2 flow (`@relayflows/surface`/`@relayflows/sdk`, the `flows` CLI) in TypeScript or YAML/JSON — the run/llm/agent ladder, verification gates, cli/model resolution, flows.json, and real `flows check`/`run` refusal shapes. Not the older `@relayflows/core` WorkflowBuilder engine. |
 | [using-agent-relay](skills/using-agent-relay/SKILL.md) | 1.4.0 | Participant-side MCP reference for a **registered** relay agent (spawned worker / registered lead): messaging, channels, threads, reactions, search, inbox, actions, and worker spawn/release. Counterpart to `orchestrating-agent-relay`. |
-| [orchestrating-agent-relay](skills/orchestrating-agent-relay/SKILL.md) | 2.3.1 | The canonical way to run agent-relay: self-bootstrap the broker (`agent-relay node up`) and autonomously spawn, monitor, and coordinate a worker team over the relay MCP without human intervention. |
-| [relay-80-100-workflow](skills/relay-80-100-workflow/SKILL.md) | 1.0.9 | Author workflows that close the 80-to-100 validation gap with repair-aware test, verify, review-depth review/fix with test hardening, and commit gates. |
+| [orchestrating-agent-relay](skills/orchestrating-agent-relay/SKILL.md) | 2.4.0 | The canonical way to run agent-relay: self-bootstrap the broker (`agent-relay node up`) and autonomously spawn, monitor, and coordinate a worker team over the relay MCP without human intervention, including GitHub PR-owner integration subscriptions. |
+| [relay-80-100-workflow](skills/relay-80-100-workflow/SKILL.md) | 2.1.0 | Close the 80-to-100 validation gap in a Relayflows v2 flow: the evidence recorder that turns a red check into work for a repair agent, repairable gates on the critical path, edit and hazard gates, when *not* to add a repair step, and the fresh-eyes review rounds that catch what green gates miss. |
 | [review-fix-signoff-loop](skills/review-fix-signoff-loop/SKILL.md) | 1.0.2 | Loop review, repair, validation, and fresh-context dual-agent signoff until independent reviewers both satisfy the verdict contract. |
 | [trigger-autocomplete-catalog](skills/trigger-autocomplete-catalog/SKILL.md) | 1.0.0 | Enforce webhook/event trigger autocomplete coverage through KNOWN_TRIGGER_CATALOG in @relayfile/adapter-core. |
 | [activity-summary](skills/activity-summary/SKILL.md) | 1.0.0 | Answer "what did I work on yesterday" questions by reading `digests/yesterday.md` first instead of crawling provider directories. |
@@ -67,10 +67,11 @@ npx prpm install collections/agent-relay-starter --as codex,claude
 This collection includes:
 
 - `@agent-relay/choosing-swarm-patterns`
-- `@agent-relay/writing-agent-relay-workflows`
+- `@agent-relay/writing-relayflows`
 - `@agent-workforce/trail-snippet`
 - optional `@agent-relay/relay-80-100-workflow`
 - optional `@agent-relay/review-fix-signoff-loop`
+- optional `@agent-relay/writing-agent-relay-workflows` (deprecated v1 engine)
 
 Install the `relayfile-workspace` collection when you want the full Relayfile workspace primitive stack:
 

prpm.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-workforce-skills",
-  "version": "1.1.6",
+  "version": "1.7.0",
   "description": "Skills for multi-agent coordination - swarm patterns, workflow building, relay usage, and orchestrating agent-relay",
   "author": "khaliqgant",
   "organization": "agent-relay",
@@ -10,7 +10,7 @@
   "packages": [
     {
       "name": "migrating-persona-to-relayflow",
-      "version": "1.0.0",
+      "version": "1.1.0",
       "description": "Use when migrating an existing defineAgent persona (in AgentWorkforce/agents or AgentWorkforce/internal-agents) to run its LLM-heavy work through a Relayflow v1 workflow via ctx.workflow.run(). Covers scope decisions, the 4-step durable-workflow shape, colocation with the persona, ctx.workflow.run() invocation, red-first + resume tests, useSubscription semantics for realtime triggers, and the agentworkforce >= 4.1.44 CI-deploy bump. Reference migration: hn-monitor PR #126.",
       "format": "claude",
       "subtype": "skill",
@@ -47,8 +47,8 @@
     },
     {
       "name": "writing-agent-relay-workflows",
-      "version": "1.6.24",
-      "description": "Use when building multi-agent workflows with relay broker-sdk. Covers conversation vs pipeline coordination, WorkflowBuilder/DAG steps, agents, {{steps.X.output}} chaining, Relayfile-backed human assistance, Slack answer injection, integration subscriptions, waitFor gates, repairable verification, review-depth fresh-eyes review/fix loops with test hardening, channels, chat-native recipes, error handling, event listeners, step sizing, lead+workers teams, and parallel waves.",
+      "version": "2.0.0",
+      "description": "DEPRECATED - the superseded v1 @relayflows/core WorkflowBuilder engine (failOnError, captureOutput, {{steps.X.output}}, .onError()). All new work uses writing-relayflows (v2: @relayflows/surface / @relayflows/sdk, CLI `flows`). Keep this only to read or maintain an existing v1 workflow: conversation vs pipeline coordination, DAG steps, idle detection, human assistance, waitFor gates, review-depth review/fix loops, channels, and parallel waves.",
       "format": "claude",
       "subtype": "skill",
       "languages": [
@@ -95,8 +95,8 @@
     },
     {
       "name": "writing-relayflows",
-      "version": "1.0.0",
-      "description": "Use when authoring a Relayflows flow (@relayflows/surface / @relayflows/sdk, the v2 journal-based engine, CLI `flows`) in TypeScript or YAML/JSON. Covers the run/llm/agent ladder, human/dispatch/done, verification gates, cli/model resolution, flows.json, and flows check/run/resume refusal shapes. Not for the older @relayflows/core WorkflowBuilder (chained .pattern('dag')/.agent()/.step() calls) \u2014 see writing-agent-relay-workflows / migrating-persona-to-relayflow instead.",
+      "version": "1.4.0",
+      "description": "Use when authoring a Relayflows flow (@relayflows/surface / @relayflows/sdk, the v2 journal-based engine, CLI `flows`) in TypeScript or YAML/JSON. Covers the run/llm/agent ladder, human/dispatch/done, verification gates, cli/model resolution, flows.json, and flows check/run/resume refusal shapes. Not for the older @relayflows/core WorkflowBuilder (chained .pattern('dag')/.agent()/.step() calls) — see writing-agent-relay-workflows / migrating-persona-to-relayflow instead.",
       "format": "claude",
       "subtype": "skill",
       "languages": [
@@ -136,8 +136,8 @@
     },
     {
       "name": "orchestrating-agent-relay",
-      "version": "2.3.1",
-      "description": "The canonical way to run agent-relay - self-bootstrap the local broker and autonomously spawn, monitor, and coordinate a team of worker agents without human intervention. Covers infrastructure startup, agent spawning, lifecycle monitoring, message-based reading via the relay MCP, and team coordination.",
+      "version": "2.4.0",
+      "description": "The canonical way to run agent-relay - self-bootstrap the local broker and autonomously spawn, monitor, and coordinate a team of worker agents without human intervention. Covers infrastructure startup, agent spawning, lifecycle monitoring, message-based reading via the relay MCP, GitHub PR-owner integration subscriptions, and team coordination.",
       "format": "claude",
       "subtype": "skill",
       "tags": [
@@ -154,11 +154,12 @@
     },
     {
       "name": "relay-80-100-workflow",
-      "version": "1.0.9",
-      "description": "Use when writing agent-relay workflows that must fully validate features end-to-end before merging - covers the 80-to-100 pattern with review-depth fresh-eyes review/fix loops with test hardening, PGlite in-memory Postgres testing, mock sandbox patterns, test-fix-rerun loops, verify gates, and full lifecycle from implementation through passing tests to commit",
+      "version": "2.1.0",
+      "description": "Use when writing a Relayflows v2 flow (@relayflows/surface / @relayflows/sdk, CLI `flows`) that must fully validate a feature end-to-end before it is sealed or merged - the 80-to-100 gap. Covers the evidence-recorder pattern that replaces v1's failOnError/captureOutput, repairable gates on the critical path, edit and hazard gates, gate cross-checking, fresh-eyes review rounds, and what a wall of green gates still misses.",
       "format": "claude",
       "subtype": "skill",
       "tags": [
+        "relayflows",
         "workflow",
         "testing",
         "e2e-validation",
@@ -478,7 +479,7 @@
       "id": "agent-relay-starter",
       "name": "Agent Relay Starter",
       "description": "Essential skills for building multi-agent systems with Agent Relay - swarm pattern selection, workflow authoring, and trail debugging",
-      "version": "1.1.0",
+      "version": "1.2.0",
       "category": "development",
       "tags": [
         "multi-agent",
@@ -495,10 +496,16 @@
           "reason": "Decision framework for picking the right multi-agent orchestration pattern"
         },
         {
-          "packageId": "@agent-relay/writing-agent-relay-workflows",
+          "packageId": "@agent-relay/writing-relayflows",
           "version": "latest",
           "required": true,
-          "reason": "WorkflowBuilder API guide for authoring DAG-based multi-agent workflows with review-depth review/fix loops and test hardening"
+          "reason": "Authoring guide for the current Relayflows v2 engine (@relayflows/surface / @relayflows/sdk, CLI `flows`)"
+        },
+        {
+          "packageId": "@agent-relay/writing-agent-relay-workflows",
+          "version": "latest",
+          "required": false,
+          "reason": "DEPRECATED v1 WorkflowBuilder reference - install only to maintain an existing v1 workflow"
         },
         {
           "packageId": "@agent-workforce/trail-snippet",

skills/migrating-persona-to-relayflow/SKILL.md

@@ -5,6 +5,12 @@ description: Use when migrating an existing `defineAgent` persona (in AgentWorkf
 
 # Migrating a persona to Relayflow v1
 
+> **v1 engine.** This skill targets the superseded `@relayflows/core` engine via
+> `ctx.workflow.run()`. The current engine is **v2** — `@relayflows/surface` /
+> `@relayflows/sdk`, CLI `flows` — documented in
+> [`writing-relayflows`](../writing-relayflows/SKILL.md). Use this skill only to move an
+> existing persona onto v1's durable execution today.
+
 ## When to use this skill
 
 You are working on a persona in `AgentWorkforce/agents` or `AgentWorkforce/internal-agents` that today does its work inline in a `defineAgent({ handler })` — LLM calls via `ctx.llm(...)`, ranking, curation, review — and you want to move the LLM-heavy portion behind a durable Relayflow v1 workflow via `ctx.workflow.run()` so that the work is exactly-once resumable, journaled, and step-level retriable.
@@ -16,7 +22,7 @@ Read the RFC first: [`docs/RFC-0001-everything-is-a-relayflow.md`](https://githu
 ## Do not use this skill for
 
 - **Authoring a v1 workflow from scratch** — use [`writing-agent-relay-workflows`](../writing-agent-relay-workflows/SKILL.md).
-- **Cloud v2 execution** — v2 is still under construction (see the RFC gate 3–4 work). Migrate to v1 first; v2 becomes an opt-in `relayflowVersion: "v2"` flip on the same `ctx.workflow.run()` call once v2 is generally available.
+- **Authoring for the v2 engine** — v2 (`@relayflows/surface`/`@relayflows/sdk`, CLI `flows`, packages `2.0.x`) is a different product that ships today; see [`writing-relayflows`](../writing-relayflows/SKILL.md). This skill and `writing-agent-relay-workflows` cover the superseded **v1** engine. Personas still migrate to v1 first: v2 becomes an opt-in `relayflowVersion: "v2"` flip on the same `ctx.workflow.run()` call once the persona runtime supports it.
 - **Repointing a workflow between packages** (`@agent-relay/sdk/workflows` → `@relayflows/core`) — that is covered in `writing-agent-relay-workflows`.
 
 ## The seven-step recipe