relay-flow 0.2.6-alpha → 0.2.7-alpha

package/README.md

@@ -1,36 +1,160 @@
 # relay-flow
 
-Durable, graph-based agent workflow runner. A ticket is the unit of work; a workflow YAML declares nodes and routes; a durable engine (go-workflows + SQLite) drives progression, waits, retries, and recovery. The task system (Jira and Beads built-ins) supplies parent tickets and mailbox subtasks; the runner (Orca built-in) owns worktrees and terminals; the harness (OpenCode and Pi built-ins) owns agent sessions and report semantics. All three are pluggable.
+Durable, graph-based agent workflow runner. A ticket is the unit of work; a workflow YAML declares nodes and routes; a durable executor drives progression, waits, retries, and recovery. Task systems (Jira and Beads), runners (Orca and Herdr), harnesses (OpenCode and Pi), and durable executors (go-workflows and Temporal) are selectable independently.
 
 This is a ground-up rewrite. The previous per-workflow, in-memory daemon is gone. There is no migration path and no compatibility layer.
 
 ---
 
-## Setup
+## Quick start
 
-### Prerequisites
+### 1. Install relay-flow
 
-| Tool | Why |
-|---|---|
-| [opencode](https://opencode.ai) | Agents run in opencode sessions (harness) |
-| [Orca](https://github.com/Necmttn/orca) CLI + app | Worktrees + terminals (runner) |
-| `bd` CLI | Beads task-system access (required when `taskPlugin: beads`) |
-| Dolt | External/server-backed Beads only |
-| Jira API token | Jira REST API v3 access (required when `taskPlugin: jira`) |
-| Go 1.24+ | Build the CLI |
+Install the latest released CLI with Homebrew:
 
-### Install
+```sh
+brew install rajpopat27/tap/relay-flow
+```
+
+### 2. Install the harness extension
+
+Choose the harness that will run your agent sessions. Both commands install the
+same `relay-flow-plugin` package with host-specific entrypoints.
+
+**OpenCode**
+
+```sh
+opencode plugin relay-flow-plugin@0.2.7-alpha
+```
+
+**Pi**
+
+```sh
+pi install npm:relay-flow-plugin@0.2.7-alpha
+```
+
+Pi loads the package's `pi.ts` extension from its manifest. Do not add
+`-e`/`--extension` to relay-flow's Pi launch command.
+
+### 3. Initialize relay-flow
+
+Choose one task system, runner, harness, and durable executor. This example
+uses Jira, Orca, OpenCode, and the default embedded executor:
 
 ```sh
-go install github.com/rajpopat27/relay-flow/cmd/relay-flow@latest
+relay-flow init \
+  --task-plugin jira \
+  --runner-plugin orca \
+  --harness-plugin opencode
 ```
 
+The default executor is `goworkflows` with SQLite. To use Temporal instead,
+add `--executor-plugin temporal`, `--temporal-address <host:port>`, and
+`--temporal-namespace <name>` to the command.
+
+### 4. Authenticate the task system
+
+For Jira, authenticate the selected task plugin:
+
+```sh
+relay-flow task auth
+```
+
+For Beads, skip this command and initialize/authenticate the Beads workspace
+with `bd` and, when needed, Dolt. See [Beads task system](#beads-task-system)
+below.
+
+### 5. Start the server
+
+```sh
+relay-flow serve --background
+```
+
+### 6. Register a repository
+
+The repository must already exist in the selected runner. For Orca:
+
+```sh
+orca repo add --path /work/payments
+relay-flow repo register
+```
+
+For Herdr, register the repository path directly; relay-flow creates ticket
+worktrees lazily. The interactive registration asks for the task-system values
+required by the selected task plugin.
+
+### 7. Submit a workflow
+
+```sh
+relay-flow workflow submit --file examples/minimal-jira-task-workflow.yaml
+relay-flow workflow list
+```
+
+Replace the example workflow with
+`examples/minimal-beads-task-workflow.yaml` when using Beads. The workflow's
+`repos` value must match the name used during repository registration.
+
+## Supported plugins
+
+Each category is a replaceable boundary. Select one plugin from each category
+at initialization; the workflow YAML and core orchestration do not change when
+you switch an implementation.
+
+| Category | Supported plugins | Owns |
+|---|---|---|
+| Task system | `jira`, `beads` | Parent tickets, mailbox subtasks, task state, labels, comments, and task configuration |
+| Runner | `orca`, `herdr` | Ticket worktrees, environments, terminals, process liveness, and cleanup |
+| Harness | `opencode`, `pi` | Agent launch commands, sessions, prompts, report parsing, nudges, and resume behavior |
+| Durable executor | `goworkflows`, `temporal` | Graph progression, waits, retries, recovery, and durable execution state |
+
+The default durable executor is `goworkflows`, which stores execution state in
+SQLite. `temporal` uses an external Temporal server and is selected with the
+Temporal address and namespace during `init`.
+
+The plugin composition is explicit:
+
+```text
+Task system (Jira or Beads)
+        │
+        ▼
+Durable executor (go-workflows or Temporal)
+        │
+        ▼
+Runner (Orca or Herdr)
+        │
+        ▼
+Harness (OpenCode or Pi)
+        │
+        ▼
+relay-flow report transport
+```
+
+The equivalent non-interactive selection is:
+
+```sh
+relay-flow init \
+  --task-plugin <jira|beads> \
+  --runner-plugin <orca|herdr> \
+  --harness-plugin <opencode|pi> \
+  --executor-plugin <goworkflows|temporal>
+```
+
+`--executor-plugin` defaults to `goworkflows`. Jira requires Jira credentials;
+Beads requires the `bd` CLI and a configured workspace. Orca requires its CLI
+and app; Herdr requires its CLI/server. OpenCode and Pi each require their
+corresponding agent runtime. These integrations remain behind their small
+contracts, so task-system fields do not leak into runners or harnesses.
+
+## Detailed setup
+
+### Harness configuration
+
 OpenCode plugin configuration uses both entrypoints. The server entrypoint is listed in `opencode.json`:
 
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["relay-flow-plugin"]
+  "plugin": ["relay-flow-plugin@0.2.7-alpha"]
 }
 ```
 
@@ -39,7 +163,7 @@ The native HITL approval entrypoint is listed in `.opencode/tui.json`:
 ```json
 {
   "$schema": "https://opencode.ai/tui.json",
-  "plugin": ["relay-flow-plugin"]
+  "plugin": ["relay-flow-plugin@0.2.7-alpha"]
 }
 ```
 
@@ -55,7 +179,7 @@ Pi plugin: install the same published package manually in Pi's global package
 settings before starting a Pi harness session:
 
 ```sh
-pi install npm:relay-flow-plugin@<version>
+pi install npm:relay-flow-plugin@0.2.7-alpha
 ```
 
 Relay-flow does not install or configure the package automatically. Pi resolves
@@ -71,14 +195,14 @@ structured report, applies the agent/HITL nudge policy, and delivers
 `reportId` comes from the harness session/message identity; `nodeVisitID` is
 internal and is never part of either plugin payload.
 
-### One-time machine setup
+### Machine setup details
 
 ```sh
 relay-flow init
 relay-flow task auth
 ```
 
-`init` only selects the task system, runner, and harness (singleton options are automatic), writes machine config, and initializes SQLite. `task auth` delegates authentication to that selected task plug-in. Jira prompts for its site, email, and masked API token, validates `/myself`, and owns the system-wide `credentials.yaml`; for scripts, pass `task auth --site`, `--email`, and `--token`. A normal init rerun refuses existing state. `relay-flow init --force` updates safe stopped instances while preserving durable and repo state.
+`init` selects the task system, runner, harness, and durable executor (singleton options are automatic), writes machine config, and initializes the selected execution backend. `task auth` delegates authentication to that selected task plug-in. Jira prompts for its site, email, and masked API token, validates `/myself`, and owns the system-wide `credentials.yaml`; for scripts, pass `task auth --site`, `--email`, and `--token`. A normal init rerun refuses existing state. `relay-flow init --force` updates safe stopped instances while preserving durable and repo state.
 
 For Beads, select the plugin explicitly when scripting setup:
 
@@ -135,7 +259,7 @@ Shows a multi-select titled `Select repositories`; use Space to select Orca repo
 
 Each Jira poll uses REST v3 enhanced search and requests linked-issue status with the candidate fields. Tickets with any unfinished inward `Blocks` issue are filtered before routing; no per-ticket blocker lookup is made.
 
-For scripts, use `relay-flow repo register --name <name> --path <path> --set project=<project>`. Component is always derived from `--name` and cannot be overridden. Registration is rejected while another repo already holds the same canonical task scope.
+For scripted Jira registration, use `relay-flow repo register --name <name> --path <path> --set project=<project>`. Component is always derived from `--name` and cannot be overridden. Registration is rejected while another repo already holds the same canonical task scope.
 
 ### Beads task system
 
@@ -229,10 +353,7 @@ Workflows live at `~/.relay-flow/workflows/<name>.yaml` after submit. Replacemen
 
 Use [`examples/config-reference.yaml`](examples/config-reference.yaml) for the complete machine configuration, [`examples/workflow-reference.yaml`](examples/workflow-reference.yaml) for the complete workflow schema, or the provider-specific minimal workflows [`examples/minimal-jira-task-workflow.yaml`](examples/minimal-jira-task-workflow.yaml) and [`examples/minimal-beads-task-workflow.yaml`](examples/minimal-beads-task-workflow.yaml). Runtime node agents should follow [`docs/agent-instructions.md`](docs/agent-instructions.md). The existing [`examples/default-story-workflow.yaml`](examples/default-story-workflow.yaml) remains a more detailed Jira Story example, while [`examples/beads-workflow.yaml`](examples/beads-workflow.yaml) shows the Beads lifecycle shape. Replace the repo name and uncomment only the optional fields you need.
 
-Task, runner, and harness plugins are selected machine-wide. A single relay-flow
-configuration cannot run Jira and Beads simultaneously; use separate
-`RELAY_FLOW_HOME` directories or machine configurations when both providers are
-needed.
+Task, runner, harness, and durable executor plugins are selected machine-wide. A single relay-flow configuration cannot run Jira and Beads simultaneously; use separate `RELAY_FLOW_HOME` directories or machine configurations when both providers are needed.
 
 ### Run
 
@@ -262,6 +383,8 @@ cleanupRunnerOnEnd: false        # optional; when true the runner tears down at
 taskConfig:                      # optional; adapter-owned; merged root → repo → workflow → node
   filters:
     parentStatuses: [To Do]
+    labels: ["workflow:true"]
+    assignees: ["currentUser()"] # Jira resolves this to the authenticated email.
 
 nodes:
   start:
@@ -271,20 +394,43 @@ nodes:
     onSuccess: [{ target: coding }]
 
   coding:
-    type: agent                  # or hitl
-    agent: build                 # opencode agent
+    type: agent
+    agent: build
     description: |               # becomes the mailbox description and launch prompt
-      Implement the ticket.
+      Implement the ticket in the current worktree.
+    nudgePrompt: |
+      Continue working on {{ticket}}. Read the parent {{taskSystem}} ticket
+      {{ticket}} and your assigned ticket {{mailbox}} to understand the requirements. Read
+      the latest feedback, address the requested changes, and work on the next
+      bounded task slice. Return the complete report. Valid choices are:
+      {{nextSteps}}.
     onSuccess: [{ target: reviewing, when: "work complete" }]
     onFailure: [{ target: coding,   when: "retry" }]
-    nudgePrompt: "Check edge cases for {{ticket}} before reporting." # optional custom instructions
 
   reviewing:
+    type: agent
+    agent: plan
+    description: Review the completed implementation and report required changes.
+    nudgePrompt: |
+      Review {{ticket}}. Read the parent {{taskSystem}} ticket {{ticket}} and
+      your assigned ticket {{mailbox}} to understand the requirements. Re-check the
+      implementation and latest coding feedback, then return the complete
+      report. Valid choices are:
+      {{nextSteps}}.
+    onSuccess: [{ target: humanReview, when: "ready for human review" }]
+    onFailure: [{ target: coding,      when: "changes required" }]
+
+  humanReview:
     type: hitl
-    agent: build
-    description: Human review.
-    onSuccess: [{ target: end }]
-    onFailure: [{ target: coding }]
+    agent: plan
+    description: Approve the reviewed implementation or request changes.
+    nudgePrompt: |
+      Review the completed work for {{ticket}} with the human. Read the parent
+      {{taskSystem}} ticket {{ticket}} and your assigned ticket {{mailbox}} to
+      understand the requirements. Return the complete report. Valid choices are:
+      {{nextSteps}}.
+    onSuccess: [{ target: end,    when: "approved" }]
+    onFailure: [{ target: coding, when: "changes requested" }]
 
   end: {}
 ```
@@ -468,7 +614,7 @@ tickets are not reopened automatically.
 ## Architecture
 
 - **Task system** owns parent tickets, mailbox subtasks, task state, labels, comments, and adapter config. The parent ticket is the unit of work.
-- **Durable workflow engine** (go-workflows + SQLite) owns graph progression, waits, reports, retries, and recovery. No custom state machine.
+- **Durable workflow engine** (`goworkflows` + SQLite or `temporal`) owns graph progression, waits, reports, retries, and recovery. No custom state machine.
 - **Mailbox subtask** is one agent/HITL node's scratch space; its description defines the node's work and its comments hold the node's summary plus selected incoming feedback.
 - **Harness** owns agent launch, session/report behavior, parsing, nudging, and resume semantics.
 - **Runner** owns ticket worktrees/environments, terminals, liveness, and execution of harness commands.

package/examples/default-story-workflow.yaml

@@ -11,10 +11,11 @@ taskConfig:
       - To Do
     issueTypes:
       - Story
-    # labels:
-    #   - coding
-    # assignees:
-    #   - owner@example.com
+    labels:
+      - "workflow:true"
+    assignees:
+      - currentUser()
+      # Jira resolves currentUser() to the authenticated Jira email.
   # assignee: default-node-owner@example.com
   # project: PAY
   # component: api
@@ -28,48 +29,62 @@ nodes:
       transitionTo:
         parentStatus: In Progress
     onSuccess:
-      - target: implement
+      - target: coding
         when: The parent story is ready for implementation
 
-  implement:
+  coding:
     type: agent
     agent: build
-    description: Implement the parent story and verify the changes.
-    # nudgePrompt: "Finish {{node}} for {{ticket}} and choose one of: {{nextSteps}}"
+    description: Implement the parent story in the current ticket worktree.
+    nudgePrompt: |
+      Continue working on {{ticket}}. Read the parent {{taskSystem}} ticket
+      {{ticket}} and your assigned ticket {{mailbox}} to understand the requirements. Read
+      the latest feedback, address the requested changes, and work on the next
+      bounded task slice. Return the complete report. Valid choices are:
+      {{nextSteps}}.
     taskConfig:
       # assignee: developer@example.com
       transitionTo:
         taskStatus: In Progress
         # parentStatus: In Progress
     onSuccess:
-      - target: review
+      - target: reviewing
         when: Implementation and verification are complete
     onFailure:
-      - target: implement
+      - target: coding
         when: Implementation needs another pass
 
-  review:
+  reviewing:
     type: agent
     agent: plan
-    description: Review the implementation for correctness, regressions, and missing tests.
-    # nudgePrompt: "Complete the review for {{ticket}}. Valid routes: {{nextSteps}}"
+    description: Review the completed implementation and report required changes.
+    nudgePrompt: |
+      Review {{ticket}}. Read the parent {{taskSystem}} ticket {{ticket}} and
+      your assigned ticket {{mailbox}} to understand the requirements. Re-check the
+      implementation and latest coding feedback, then return the complete
+      report. Valid choices are:
+      {{nextSteps}}.
     taskConfig:
       # assignee: reviewer@example.com
       transitionTo:
         taskStatus: In Progress
         # parentStatus: In Review
     onSuccess:
-      - target: prReview
+      - target: humanReview
         when: The changes are ready for human approval
     onFailure:
-      - target: implement
+      - target: coding
         when: Code changes are required
 
-  prReview:
+  humanReview:
     type: hitl
     agent: plan
-    description: Discuss the pull request with the human and obtain approval.
-    # nudgePrompt: "Review {{ticket}} with the human. Valid routes: {{nextSteps}}"
+    description: Approve the reviewed implementation or request changes.
+    nudgePrompt: |
+      Review the completed work for {{ticket}} with the human. Read the parent
+      {{taskSystem}} ticket {{ticket}} and your assigned ticket {{mailbox}} to
+      understand the requirements. Return the complete report. Valid choices are:
+      {{nextSteps}}.
     taskConfig:
       # assignee: human-reviewer@example.com
       transitionTo:
@@ -79,7 +94,7 @@ nodes:
       - target: end
         when: The human approves the review
     onFailure:
-      - target: implement
+      - target: coding
         when: The human requests code changes
 
   end:

package/internal/harness/opencode/opencode_test.go

@@ -14,7 +14,7 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/workflow"
 )
 
-const configuredPlugin = "relay-flow-plugin@0.2.6-alpha"
+const configuredPlugin = "relay-flow-plugin@0.2.7-alpha"
 
 func TestBuildCommandArgv(t *testing.T) {
 	t.Setenv("RELAY_FLOW_HOME", "/var/lib/relay-flow-test")

package/internal/harness/opencode/repo_setup.go

@@ -10,7 +10,7 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/config"
 )
 
-const relayFlowPlugin = "relay-flow-plugin@0.2.6-alpha"
+const relayFlowPlugin = "relay-flow-plugin@0.2.7-alpha"
 
 type jsoncToken struct {
 	kind       byte

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-flow",
-  "version": "0.2.6-alpha",
+  "version": "0.2.7-alpha",
   "description": "Graph-based agent workflow engine — tracker-agnostic, pluggable runners",
   "bin": {
     "relay-flow": "./bin/relay-flow.js",