relay-flow 0.2.2-alpha → 0.2.4-alpha

package/README.md

@@ -1,6 +1,6 @@
 # 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 built-in) 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 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.
 
 This is a ground-up rewrite. The previous per-workflow, in-memory daemon is gone. There is no migration path and no compatibility layer.
 
@@ -25,7 +25,7 @@ This is a ground-up rewrite. The previous per-workflow, in-memory daemon is gone
 go install github.com/rajpopat27/relay-flow/cmd/relay-flow@latest
 ```
 
-OpenCode plugin: add `"relay-flow-plugin"` to the `plugin` array in your repo's `opencode.json`:
+OpenCode plugin configuration uses both entrypoints. The server entrypoint is listed in `opencode.json`:
 
 ```json
 {
@@ -34,7 +34,42 @@ OpenCode plugin: add `"relay-flow-plugin"` to the `plugin` array in your repo's
 }
 ```
 
-The plugin is the report-path half of the harness contract: it registers each emitted harness session with `{runId, node, sessionId}`, parses the agent's structured report, applies the agent/HITL nudge policy, and delivers `{runId, node, reportId, report}` via `relay-flow report` with retry. `reportId` comes from the harness session/message identity; `nodeVisitID` is internal and is never part of either plugin payload.
+The native HITL approval entrypoint is listed in `.opencode/tui.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["relay-flow-plugin"]
+}
+```
+
+The OpenCode harness adds both entries when a repo is registered. The server
+entrypoint registers sessions, handles agent reports, and nudges invalid agent
+output. The TUI entrypoint handles only HITL reports: after a valid completed
+assistant report it shows a native Approve/Reject dialog. Approval delivers
+`{runId, node, reportId, report}` via `relay-flow report` with retry; rejection
+delivers nothing. `reportId` comes from the harness session/message identity;
+`nodeVisitID` is internal and is never part of either plugin payload.
+
+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>
+```
+
+Relay-flow does not install or configure the package automatically. Pi resolves
+`pi.ts` from the package's `pi.extensions` manifest entry, so do not add
+`-e`/`--extension` to the relay-flow launch command. The runner launches Pi in
+an interactive PTY; the package's OpenCode entry point remains available for
+OpenCode sessions.
+
+The plugin is the report-path half of the harness contract: it registers each
+emitted harness session with `{runId, node, sessionId}`, parses the agent's
+structured report, applies the agent/HITL nudge policy, and delivers
+`{runId, node, reportId, report}` via `relay-flow report` with retry.
+`reportId` comes from the harness session/message identity; `nodeVisitID` is
+internal and is never part of either plugin payload.
 
 ### One-time machine setup
 
@@ -53,6 +88,13 @@ relay-flow init --task-plugin beads --runner-plugin orca --harness-plugin openco
 
 Beads authentication is owned by the Beads workspace and its `bd`/Dolt configuration. `relay-flow task auth` is a no-op for Beads and does not create relay-flow credentials; do not add a Jira token to a Beads-only installation.
 
+Pi is available through the existing harness selection. For a non-interactive
+setup, select it with the existing flags:
+
+```sh
+relay-flow init --task-plugin jira --runner-plugin orca --harness-plugin pi
+```
+
 The full machine layout is fixed under `~/.relay-flow` (0700):
 
 ```
@@ -159,10 +201,14 @@ Beads workflow filters are structured and evaluated in relay-flow. For example,
 taskConfig:
   filters:
     parentStatuses: [open]
-    issueTypes: [epic]
+    issueTypes: [task]
     labels: [relay-ready]
 ```
 
+Jira and Beads use the same conceptual `Task` issue type, but each adapter
+keeps its provider-native spelling: Jira uses `Task` and Beads uses `task`.
+Filter values are exact and are not translated between providers.
+
 The supported Beads status names are `open`, `in_progress`, `blocked`, `deferred`, `hooked`, and `closed`. The claimed-parent poll uses the canonical active set `open,in_progress,blocked,deferred`; it intentionally does not substitute `hooked` for `deferred`. Omitted lifecycle settings move the parent to `in_progress` at `start`, a work-node mailbox to `in_progress`, and the parent to `closed` at `end` — the same shape as Jira, with Beads-native values. Relay-flow creates one Repo Poller per registered repo, not one poller per workflow. Each poll reads ready top-level parents and relay-owned active parents, deduplicates them, and never routes mailbox children. Claims are permanent `wf:<workflow>` labels.
 
 Beads does not need relay-flow credentials or a Beads-specific poller. In server mode, leave Dolt and Beads server setup running outside relay-flow and point each repo at its own `beadsDir`.
@@ -175,7 +221,12 @@ relay-flow workflow submit --file <path>
 
 Workflows live at `~/.relay-flow/workflows/<name>.yaml` after submit. Replacement and removal are rejected while any run of that workflow is active.
 
-Use [`examples/default-story-workflow.yaml`](examples/default-story-workflow.yaml) as a fully annotated Jira-oriented starting point, or [`examples/beads-workflow.yaml`](examples/beads-workflow.yaml) for the Beads filter and lifecycle shape. Replace the repo name and uncomment only the optional fields you need.
+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.
 
 ### Run
 
@@ -269,19 +320,89 @@ A parent moved to `in_progress` stays visible to the claimed-parent poll, which
 
 Beads and Jira use the shared `filters`, `templates`, optional top-level
 `assignee`, and `transitionTo` field names. `transitionTo` uses
-`parentStatus` for the parent issue and `taskStatus` for a mailbox. In both
-adapters `assignee` is the default assignee filter when `filters.assignees` is
-absent, and an `assignee` in effect for a node also assigns that node's
-mailbox. Beads requires the repo-only `taskConfig.beadsDir` shown above; Jira
-instead uses its repo `project` and `component` keys. `project` and
-`component` are not Beads fields, and a Beads issue prefix is not a component
-or workspace selector. Beads status values remain native (`open`,
+`parentStatus` for the parent issue and `taskStatus` for a mailbox. Both
+adapters support the structured `filters.assignees` list. Jira values are
+normalized account emails; Beads values are the provider's assignee strings.
+Jira additionally supports the reserved `currentUser()` value inside
+`filters.assignees`; relay-flow resolves it to the authenticated Jira email
+without sending it as JQL. On first Jira authentication, when no root
+`taskConfig.assignee` is configured, relay-flow stores the authenticated email
+as the root mailbox assignee. In both adapters `assignee` applies to a node's
+mailbox assignment; only `filters.assignees` controls parent-ticket pickup.
+When `filters.assignees` is absent, there is no assignee filter. To make that
+explicit while keeping mailbox assignment, set an empty list:
+
+```yaml
+taskConfig:
+  filters:
+    assignees: []
+```
+
+This still applies the other filters, such as project, status, issue type, and
+labels. If mailbox assignment should also be disabled for a workflow, override
+`assignee` with an empty string at that scope as well. Beads requires the repo-only
+`taskConfig.beadsDir` shown above; Jira instead uses its repo `project` and
+`component` keys. `project` and `component` are not Beads fields, and a Beads
+issue prefix is not a component or workspace selector. Beads status values remain native (`open`,
 `in_progress`, `blocked`, `deferred`, `hooked`, `closed`), while Jira values
 remain native (`In Progress`, `Done`, and so on); relay-flow does not
 translate arbitrary values between providers. Beads rejects workflow/node-level
 template overrides because the fixed task text rendering contract has no
 lower-scope input.
 
+### Pi harness
+
+Pi has one built-in coding agent. Relay-flow keeps Pi's configured model,
+provider, tools, extensions, and settings, while allowing a workflow node to
+select a repository-owned role prompt. `agent: default` uses Pi's built-in
+coding agent without an additional role prompt. A non-default value such as
+`coder` or `reviewer` is resolved to a readable, non-empty
+`.pi/roles/<agent>.md` file in the registered repository and passed to Pi with
+`--append-system-prompt`.
+
+Pi has no native `pi agent list` command. Role existence is therefore verified
+by the filesystem check above; missing, empty, non-regular, or unsafe role
+paths fail workflow preflight. The workflow agent value is never treated as a
+model ID and relay-flow never passes an OpenCode-style `--agent` option.
+
+For example, a Pi workflow with repository roles uses:
+
+```yaml
+type: agent
+agent: coder
+```
+
+with:
+
+```text
+.pi/roles/coder.md
+.pi/roles/reviewer.md
+```
+
+Pi node launches use the installed Pi 0.84.1 interactive command contract:
+
+```text
+pi --name <ticket>:<node> [--append-system-prompt <role-file>] [--session-id <persisted-session-id>] <prompt>
+```
+
+The prompt is one positional argument. Pi 0.84.1 rejects a bare `--`, so the
+launch command does not include one. A persisted session uses
+`--session-id`; print mode, JSON/RPC mode, and extension-install flags are not
+used. The runner supplies a PTY for both standard streams, and the Pi process
+remains available for interactive input after a response settles.
+
+For a `hitl` node, a valid report is approved directly in Pi's host UI with
+`ctx.ui.select`:
+
+```text
+Approve relay-flow report for <ticket>:<node>
+  Approve
+  Reject
+```
+
+Approve delivers the report. Reject or Escape submits nothing and leaves the
+durable run waiting; Pi does not require an LLM Question tool for this step.
+
 ---
 
 ## Structured node report
@@ -309,7 +430,27 @@ EXPECTED RESULT: ...
 
 The labels above are fixed; configurable templates do not change the parsed report contract. The plugin submits one `report` object containing both lower-camel `summary` and `feedback` objects. Relay-flow validates that complete shape once, renders `summaryReport` through the task system's summary-comment template on the current mailbox, and renders `feedbackReport` through its feedback-comment template on only the selected next mailbox. `None` is the literal marker for an intentionally empty section. When `NEXT STEP` is `end`, every FEEDBACK field must be `None` and no feedback comment is written.
 
-The plugin delivers `{runId, node, reportId, report}` as one JSON object via `relay-flow report` stdin with the shared backoff (initial 2s, factor 2, jitter 0.2, max 5m) until acknowledged. It derives `reportId` from the harness session/message identity. Duplicate/stale reports are acked safely with no repeated graph effects. Invalid agent output is nudged; invalid HITL output stays silent.
+The plugin delivers `{runId, node, reportId, report}` as one JSON object via `relay-flow report` stdin with the shared backoff (initial 2s, factor 2, jitter 0.2, max 5m) until acknowledged. It derives `reportId` from the harness session/message identity. Duplicate/stale reports are acked safely with no repeated graph effects. Invalid agent output is nudged; invalid or missing HITL output stays silent, while a valid HITL report opens the native TUI approval dialog. Relay-flow HITL approval does not use OpenCode's Question tool.
+
+---
+
+## Canceled run restart
+
+Cancellation is permanent for the current execution. A canceled ticket is not
+restarted by polling or by a ticket-status change. Start a fresh attempt
+explicitly:
+
+```sh
+relay-flow run restart --ticket PAY-101
+```
+
+The new attempt starts at `start`, preserves the existing worktree/mailboxes/
+comments/labels, and uses a numeric attempt ID (`2`, `3`, ...), with a fenced
+execution ID such as `payments/basicFlow/PAY-101~attempt~2`. If a human has
+moved the parent ticket to an incompatible status, `run get` shows `blocked`
+with an instruction to move it to an allowed active start status; relay-flow
+retries automatically and never overwrites the human-owned status. Done/Closed
+tickets are not reopened automatically.
 
 ---
 

package/cmd/relay-flow/commands_test.go

@@ -47,7 +47,7 @@ func TestCommandSurfaceExists(t *testing.T) {
 		{"workflow", "submit", "--file", "x.yaml"}, {"workflow", "remove", "--name", "x"},
 		{"workflow", "list"}, {"workflow", "get", "--name", "x"},
 		{"repo", "register"}, {"repo", "remove", "--name", "x"}, {"repo", "list"}, {"repo", "get", "--name", "x"},
-		{"run", "list"}, {"run", "get", "--ticket", "PAY-101"}, {"run", "cancel", "--ticket", "PAY-101"},
+		{"run", "list"}, {"run", "get", "--ticket", "PAY-101"}, {"run", "restart", "--ticket", "PAY-101"}, {"run", "cancel", "--ticket", "PAY-101"},
 	}
 	for _, argv := range commands {
 		// Recognized commands do not exit 2 ("usage/unknown"); they may exit
@@ -75,6 +75,7 @@ func TestRequiredFlagMissingExits2(t *testing.T) {
 		{"repo", "remove"},     // missing --name
 		{"repo", "get"},        // missing --name
 		{"run", "get"},         // missing --ticket
+		{"run", "restart"},     // missing --ticket
 		{"run", "cancel"},      // missing --ticket
 	} {
 		if code := cli(t, home, "", argv...); code != 2 {
@@ -1004,6 +1005,9 @@ func (s *ackServer) ListRuns(context.Context, runsvc.Filter) ([]runsvc.Run, erro
 func (s *ackServer) GetRunByTicket(context.Context, string) (runsvc.Run, error) {
 	panic("unreachable")
 }
+func (s *ackServer) RestartRun(context.Context, string) (runsvc.Run, error) {
+	panic("unreachable")
+}
 func (s *ackServer) CancelRun(context.Context, string, string) error { panic("unreachable") }
 func (s *ackServer) DiscoverRepos(context.Context) ([]runner.RepoCandidate, error) {
 	panic("unreachable")

package/cmd/relay-flow/main.go

@@ -37,6 +37,8 @@ import (
 	// Adapter registrations (factories registered via init for plugin
 	// name validation at init-time).
 	_ "github.com/rajpopat27/relay-flow/internal/harness/opencode"
+	_ "github.com/rajpopat27/relay-flow/internal/harness/pi"
+	_ "github.com/rajpopat27/relay-flow/internal/runner/herdr"
 	_ "github.com/rajpopat27/relay-flow/internal/runner/orca"
 	_ "github.com/rajpopat27/relay-flow/internal/task/beads"
 	_ "github.com/rajpopat27/relay-flow/internal/task/jira"
@@ -149,6 +151,7 @@ Usage:
 
   relay-flow run list
   relay-flow run get --ticket <key>
+  relay-flow run restart --ticket <key>
   relay-flow run cancel --ticket <key>`)
 }
 
@@ -946,6 +949,25 @@ func cmdRun(c *server.Client, args []string) int {
 		enc.SetIndent("", "  ")
 		_ = enc.Encode(rn)
 		return exitOK
+	case "restart":
+		fs := flag.NewFlagSet("run restart", flag.ContinueOnError)
+		ticket := fs.String("ticket", "", "ticket key")
+		if err := fs.Parse(args[1:]); err != nil {
+			return exitUsage
+		}
+		if *ticket == "" {
+			fmt.Fprintln(os.Stderr, "run restart: --ticket is required")
+			return exitUsage
+		}
+		rn, err := c.RestartRun(context.Background(), *ticket)
+		if err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return exitFail
+		}
+		enc := json.NewEncoder(os.Stdout)
+		enc.SetIndent("", "  ")
+		_ = enc.Encode(rn)
+		return exitOK
 	case "cancel":
 		fs := flag.NewFlagSet("run cancel", flag.ContinueOnError)
 		ticket := fs.String("ticket", "", "ticket key")
@@ -968,7 +990,11 @@ func cmdRun(c *server.Client, args []string) int {
 }
 
 func formatRunListRow(r runsvc.Run) string {
-	row := fmt.Sprintf("%s\t%s\t%s\t%s", r.ID, r.Ticket.Key, r.Workflow, r.State)
+	attempt := r.AttemptID
+	if attempt == 0 {
+		attempt = 1
+	}
+	row := fmt.Sprintf("%s\t%s\t%s\t%s\tattempt=%d", r.ID, r.Ticket.Key, r.Workflow, r.State, attempt)
 	if r.Retry != nil {
 		row += fmt.Sprintf("\tretrying attempt=%d next=%s error=%q",
 			r.Retry.Attempt, r.Retry.NextRetryAt.Format(time.RFC3339), r.Retry.LastError)

package/cmd/relay-flow/pi_wiring_test.go

@@ -0,0 +1,64 @@
+package main
+
+import (
+	"bytes"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/harness"
+)
+
+func TestPiAppearsInDynamicHarnessSelection(t *testing.T) {
+	names := harness.Names()
+	if !containsHarnessName(names, "pi") {
+		t.Fatalf("harness.Names() = %v, want pi", names)
+	}
+
+	var selected string
+	field, err := pluginSelectField("Select harness", names, &selected)
+	if err != nil {
+		t.Fatalf("pluginSelectField: %v", err)
+	}
+	var output bytes.Buffer
+	if err := field.RunAccessible(&output, strings.NewReader("1\n")); err != nil {
+		t.Fatalf("RunAccessible: %v", err)
+	}
+	if !strings.Contains(output.String(), "Select harness") {
+		t.Fatalf("selection output %q missing unchanged harness title", output.String())
+	}
+}
+
+func TestInitPiFlagUsesGenericHarnessSelectionPath(t *testing.T) {
+	home := t.TempDir()
+	code, output := captureStdout(t, func() int {
+		return cli(t, home, "", "init",
+			"--task-plugin", "jira",
+			"--runner-plugin", "orca",
+			"--harness-plugin", "pi")
+	})
+	if code != 0 {
+		t.Fatalf("Pi init exit = %d, want 0", code)
+	}
+	if !strings.Contains(output, "Harness: pi") {
+		t.Fatalf("Pi init output = %q, want generic harness summary", output)
+	}
+
+	cfg, err := config.LoadMachine(filepath.Join(home, ".relay-flow", "config.yaml"))
+	if err != nil {
+		t.Fatalf("load Pi machine config: %v", err)
+	}
+	if cfg.HarnessPlugin != "pi" {
+		t.Fatalf("harnessPlugin = %q, want pi", cfg.HarnessPlugin)
+	}
+}
+
+func containsHarnessName(names []string, want string) bool {
+	for _, name := range names {
+		if name == want {
+			return true
+		}
+	}
+	return false
+}

package/cmd/relay-flow/serve.go

@@ -34,6 +34,8 @@ import (
 
 	// Adapter registrations (factories are registered by name via init).
 	_ "github.com/rajpopat27/relay-flow/internal/harness/opencode"
+	_ "github.com/rajpopat27/relay-flow/internal/harness/pi"
+	_ "github.com/rajpopat27/relay-flow/internal/runner/herdr"
 	_ "github.com/rajpopat27/relay-flow/internal/runner/orca"
 	_ "github.com/rajpopat27/relay-flow/internal/task/beads"
 	_ "github.com/rajpopat27/relay-flow/internal/task/jira"
@@ -249,6 +251,8 @@ func serveRoot(ctx context.Context, p paths.Paths, recover bool) error {
 	// the SAME registry by pointer (via replaceInternal), so the engine,
 	// pollers, and handlers observe one in-memory repo set.
 	wfSvc := workflow.NewService(store, engine, repoExists{repoReg})
+	runManager.Repos = repoReg
+	runManager.Workflows = wfSvc.Registry()
 	wfSvc.Gate = lifecycleGate
 	wfSvc.ValidateTaskConfig = workflowConfigValidator(repoReg)
 	// Submit/Remove must also rebuild repo bindings under the gate (spec
@@ -455,6 +459,16 @@ func (d *serveDeps) ListRuns(ctx context.Context, filter runsvc.Filter) ([]runsv
 func (d *serveDeps) GetRunByTicket(ctx context.Context, ticket string) (runsvc.Run, error) {
 	return d.engine.FindRunByTicket(ctx, ticket)
 }
+func (d *serveDeps) RestartRun(ctx context.Context, ticket string) (runsvc.Run, error) {
+	rn, err := d.runManager.RestartByTicket(ctx, ticket)
+	if err != nil {
+		if errors.Is(err, runsvc.ErrRestartConflict) {
+			return runsvc.Run{}, fmt.Errorf("%w: %v", server.ErrConflict, err)
+		}
+		return runsvc.Run{}, err
+	}
+	return rn, nil
+}
 func (d *serveDeps) CancelRun(ctx context.Context, ticket, reason string) error {
 	return d.runManager.CancelByTicket(ctx, ticket, reason)
 }

package/examples/beads-workflow.yaml

@@ -16,13 +16,13 @@ taskConfig:
     parentStatuses:
       - open
     issueTypes:
-      - epic
+      - task
     labels:
       - relay-ready
     # assignees:
     #   - owner@example.com
-  # Optional shared default; filters.assignees overrides it when provided.
-  # An assignee in effect for a node also assigns that node's mailbox.
+  # Optional mailbox assignee inherited by nodes. It does not filter parent
+  # tickets; configure filters.assignees explicitly to filter pickup.
   # assignee: owner@example.com
 
 # transitionTo describes one lifecycle point, so configure it on a node.

package/examples/config-reference.yaml

@@ -0,0 +1,144 @@
+# Complete relay-flow machine configuration reference.
+#
+# This example uses Jira + Orca + OpenCode. Replace the example values before
+# use. The live machine file is ~/.relay-flow/config.yaml.
+#
+# One task plugin, runner plugin, and harness plugin are selected for the whole
+# machine. Jira and Beads therefore use separate relay-flow configurations.
+
+pollIntervalSeconds: 15
+completedRunRetentionDays: 30
+
+# These default to true when omitted. keepTerminalsAlive: true requires
+# keepSessionsAlive: true.
+keepTerminalsAlive: true
+keepSessionsAlive: true
+
+taskPlugin: jira
+
+taskConfig:
+  # Root mailbox assignee. This does not filter parent tickets; use
+  # filters.assignees for ticket pickup. Replace it with a real Jira account
+  # email or omit it.
+  assignee: relay-bot@example.com
+
+  # Task-system filters are adapter-owned. These values are Jira-native.
+  filters:
+    parentStatuses:
+      - To Do
+    issueTypes:
+      - Task
+    labels:
+      - relay-ready
+    assignees:
+      - currentUser()
+      # Jira resolves currentUser() to the authenticated Jira email and does
+      # not send it as JQL. Ticket pickup is controlled only by this list;
+      # the top-level assignee controls mailbox assignment.
+
+  # Avoid setting transitionTo at root scope unless the same values should
+  # apply to every lifecycle point, including end. Prefer node-level values.
+  # transitionTo:
+  #   parentStatus: In Progress
+  #   taskStatus: In Progress
+
+  # Task-system text templates. The fixed report contract is appended by
+  # relay-flow and is not changed by these templates.
+  templates:
+    mailboxDescription: |-
+      Parent ticket: {{ticket}}
+      Workflow: {{workflow}}
+      Node: {{node}}
+      Node type: {{nodeType}}
+      Agent: {{agent}}
+      Mailbox: {{mailbox}}
+
+      Node work:
+      {{nodeDescription}}
+
+      Read this mailbox's comments for feedback from previous nodes.
+
+    summaryComment: |-
+      Summary for {{node}}
+
+      {{summaryReport}}
+
+    feedbackComment: |-
+      Feedback from {{sourceNode}} to {{targetNode}} mailbox {{mailbox}}
+
+      {{feedbackReport}}
+
+runnerPlugin: orca
+
+runnerConfig:
+  # Optional Orca base branch. When omitted, Orca derives it from the repo's
+  # primary worktree.
+  baseRef: main
+
+harnessPlugin: opencode
+
+harnessConfig:
+  # OpenCode supports initial, feedback, and hitl templates.
+  initial: |-
+    Task system: {{taskSystem}}
+    Use the {{taskSystem}} tools to read the parent ticket {{ticket}}.
+
+    Your mailbox is {{mailbox}}. Read its description and comments for node instructions and feedback.
+
+  feedback: |-
+    New feedback was added to the comments section of your mailbox subtask {{mailbox}}. Read it.
+
+  hitl: |-
+    Return the complete report directly. Relay-flow will show a native TUI approval dialog after the report is valid. Do not use OpenCode's Question tool for relay-flow approval.
+
+repos:
+  payments:
+    # Code/runner repository. It must already be registered in Orca.
+    path: /work/payments
+
+    taskConfig:
+      # Jira repo-scoped required values. component is derived from the
+      # relay-flow repo name during repo registration.
+      project: PAY
+      component: payments
+
+      # Optional repo-level overrides inherit into workflows and nodes.
+      # assignee: relay-bot@example.com
+      # filters:
+      #   labels:
+      #     - backend
+
+# Beads variant:
+# taskPlugin: beads
+# repos:
+#   payments:
+#     path: /work/payments
+#     taskConfig:
+#       beadsDir: /work/payments/.beads
+#
+# Beads uses the shared taskConfig fields (filters, assignee, transitionTo,
+# templates) but does not accept Jira-only project/component fields. beadsDir
+# is required at repo scope and must not be supplied only at root scope.
+#
+# Pi variant:
+# harnessPlugin: pi
+# harnessConfig:
+#   initial: |
+#     Task system: {{taskSystem}}
+#     Use the {{taskSystem}} tools to read the parent ticket {{ticket}}.
+#
+#     Your mailbox is {{mailbox}}. Read its description and comments for node instructions and feedback.
+#   feedback: |
+#     New feedback was added to the comments section of your mailbox subtask {{mailbox}}. Read it.
+#
+# Pi accepts only initial and feedback harness templates. Pi workflow nodes
+# may use agent: default or a repository role in .pi/roles/<agent>.md; HITL
+# approval is provided by Pi's host UI.
+#
+# Herdr variant:
+# runnerPlugin: herdr
+# runnerConfig:
+#   session: relay-flow
+#   socketPath: /run/user/1000/herdr.sock
+#
+# Do not combine Orca-only baseRef with Herdr-only configuration.

package/examples/minimal-beads-task-workflow.yaml

@@ -0,0 +1,34 @@
+# Smallest Beads Task workflow.
+# Register the code repository with a repo-scoped beadsDir before submitting.
+# For Pi, use default or a repository role from .pi/roles/<agent>.md.
+name: minimalBeadsTaskFlow
+
+repos:
+  - payments
+
+cleanupRunnerOnEnd: true
+
+taskConfig:
+  filters:
+    parentStatuses:
+      - open
+    issueTypes:
+      - task
+    labels:
+      - relay-ready
+
+nodes:
+  start:
+    onSuccess:
+      - target: implement
+
+  implement:
+    type: agent
+    agent: build
+    description: Implement the Beads Task and verify the changes.
+    onSuccess:
+      - target: end
+    onFailure:
+      - target: implement
+
+  end: {}

package/examples/minimal-jira-task-workflow.yaml

@@ -0,0 +1,68 @@
+# Smallest Jira Task workflow with implementation, agent review, and HITL PR review.
+# Register the repo with Jira project/component values before submitting.
+# For Pi, replace build and plan with default.
+name: minimalJiraTaskFlow
+
+repos:
+  - payments
+
+cleanupRunnerOnEnd: true
+
+taskConfig:
+  filters:
+    parentStatuses:
+      - To Do
+    issueTypes:
+      - Task
+    labels:
+      - relay-ready
+    assignees:
+      - currentUser()
+      # Jira resolves currentUser() to the authenticated Jira email.
+      # Replace this list with `assignees: []` to match all assignees.
+
+nodes:
+  start:
+    onSuccess:
+      - target: implement
+
+  implement:
+    type: agent
+    agent: build
+    description: |
+      Implement the Jira Task in the ticket worktree.
+      Run the relevant tests and verification commands.
+    onSuccess:
+      - target: review
+        when: Implementation and verification are complete.
+    onFailure:
+      - target: implement
+        when: Implementation needs another pass.
+
+  review:
+    type: agent
+    agent: plan
+    description: |
+      Review the implementation for correctness, regressions, missing tests,
+      and unresolved issues. Prepare the work for human PR review.
+    onSuccess:
+      - target: prReview
+        when: The implementation is ready for human PR review.
+    onFailure:
+      - target: implement
+        when: The review found issues requiring implementation changes.
+
+  prReview:
+    type: hitl
+    agent: plan
+    description: |
+      Review the implementation and proposed changes with a human.
+      Approve the work or request implementation changes.
+    onSuccess:
+      - target: end
+        when: The human approves the PR review.
+    onFailure:
+      - target: implement
+        when: The human requests changes.
+
+  end: {}