relay-flow 0.2.3-alpha → 0.2.5-alpha

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 native project prompt template in
+# .pi/prompts/<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,35 @@
+# Smallest Beads Task workflow.
+# Register the code repository with a repo-scoped beadsDir before submitting.
+# For Pi, use default or a native project prompt template from
+# .pi/prompts/<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: {}

package/examples/workflow-reference.yaml

@@ -0,0 +1,112 @@
+# Complete workflow definition reference.
+#
+# This example uses Jira-native values and the OpenCode agent names build and
+# plan. For Beads, use provider-native values: open, task, in_progress, and
+# closed. For Pi, use default or a native project prompt template from
+# .pi/prompts/<agent>.md.
+
+name: referenceFlow
+
+repos:
+  - payments
+
+cleanupRunnerOnEnd: true
+
+taskConfig:
+  # Optional assignee inherited by node mailboxes. It does not filter parent
+  # tickets; use filters.assignees for ticket pickup.
+  assignee: developer@example.com
+
+  filters:
+    parentStatuses:
+      - To Do
+    issueTypes:
+      - Task
+    labels:
+      - relay-ready
+    assignees:
+      - currentUser()
+      # Jira-only symbolic value: resolves to the authenticated Jira email.
+      # Other assignee values are normalized Jira emails, not JQL expressions.
+
+  # filters.assignees controls ticket pickup independently of assignee.
+  # Use an explicit empty list to include all assignees while retaining any
+  # inherited mailbox assignment:
+  # filters:
+  #   assignees: []
+  # To disable mailbox assignment too, set assignee: "" at this scope.
+
+  # Prefer lifecycle-specific transitionTo values on start, work nodes, and
+  # end. A value here is inherited by every lifecycle point that reads it.
+  # transitionTo:
+  #   parentStatus: In Progress
+  #   taskStatus: In Progress
+
+nodes:
+  start:
+    # start has no type, agent, description, nudgePrompt, or failure routes.
+    taskConfig:
+      transitionTo:
+        parentStatus: In Progress
+    onSuccess:
+      - target: implement
+        when: The parent ticket is ready for implementation.
+
+  implement:
+    type: agent
+    agent: build
+    description: |
+      Implement the parent ticket in the ticket worktree.
+      Run the relevant tests and verification commands.
+    nudgePrompt: |
+      Continue working on {{ticket}} at node {{node}}.
+      Read the latest mailbox feedback.
+      Valid next steps are: {{nextSteps}}.
+      Return the complete report contract.
+    taskConfig:
+      transitionTo:
+        taskStatus: In Progress
+    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.
+    taskConfig:
+      transitionTo:
+        taskStatus: In Progress
+    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.
+    taskConfig:
+      transitionTo:
+        taskStatus: In Progress
+    onSuccess:
+      - target: end
+        when: The human approves the PR review.
+    onFailure:
+      - target: implement
+        when: The human requests changes.
+
+  end:
+    # end has no type, agent, description, nudgePrompt, or routes.
+    taskConfig:
+      transitionTo:
+        parentStatus: Done

package/go.mod

@@ -1,13 +1,24 @@
 module github.com/rajpopat27/relay-flow
 
-go 1.24.6
+go 1.26.0
 
-	require (
+require (
 	github.com/cschleiden/go-workflows v1.4.2
 	github.com/google/renameio/v2 v2.0.1
 	github.com/google/uuid v1.6.0
 	github.com/yuin/goldmark v1.7.13
+	go.temporal.io/api v1.63.4
+	go.temporal.io/sdk v1.48.0
+	google.golang.org/protobuf v1.36.12
 	gopkg.in/yaml.v3 v3.0.1
+	modernc.org/sqlite v1.27.0
+)
+
+require (
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20260825221802-da73d73af1c5 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260825221802-da73d73af1c5 // indirect
 )
 
 require (
@@ -19,7 +30,7 @@ require (
 	github.com/charmbracelet/bubbles v0.21.1-0.20250623103423-23b8fd6302d7 // indirect
 	github.com/charmbracelet/bubbletea v1.3.6 // indirect
 	github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
-	github.com/charmbracelet/huh v1.0.0 // indirect
+	github.com/charmbracelet/huh v1.0.0
 	github.com/charmbracelet/lipgloss v1.1.0 // indirect
 	github.com/charmbracelet/x/ansi v0.9.3 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.13 // indirect
@@ -28,38 +39,49 @@ require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
+	github.com/facebookgo/clock v0.0.0-20150410010913-600d898af40a // indirect
 	github.com/go-errors/errors v1.4.2 // indirect
-	github.com/go-logr/logr v1.4.2 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
 	github.com/golang-migrate/migrate/v4 v4.16.2 // indirect
+	github.com/golang/mock v1.6.0 // indirect
+	github.com/grpc-ecosystem/go-grpc-middleware/v2 v2.3.2 // indirect
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.22.0 // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect
 	github.com/hashicorp/go-multierror v1.1.1 // indirect
 	github.com/jellydator/ttlcache/v3 v3.0.0 // indirect
 	github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51 // indirect
 	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
-	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mattn/go-isatty v0.0.20
 	github.com/mattn/go-localereader v0.0.1 // indirect
 	github.com/mattn/go-runewidth v0.0.16 // indirect
 	github.com/mitchellh/hashstructure/v2 v2.0.2 // indirect
 	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
 	github.com/muesli/cancelreader v0.2.2 // indirect
 	github.com/muesli/termenv v0.16.0 // indirect
+	github.com/nexus-rpc/nexus-proto-annotations v0.1.0 // indirect
+	github.com/nexus-rpc/sdk-go v0.7.0 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
+	github.com/robfig/cron v1.2.0 // indirect
 	github.com/stretchr/objx v0.5.2 // indirect
-	github.com/stretchr/testify v1.10.0 // indirect
+	github.com/stretchr/testify v1.11.1 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
-	go.opentelemetry.io/otel v1.31.0 // indirect
-	go.opentelemetry.io/otel/metric v1.31.0 // indirect
-	go.opentelemetry.io/otel/sdk v1.31.0 // indirect
-	go.opentelemetry.io/otel/trace v1.31.0 // indirect
+	go.opentelemetry.io/otel v1.43.0 // indirect
+	go.opentelemetry.io/otel/metric v1.43.0 // indirect
+	go.opentelemetry.io/otel/sdk v1.43.0 // indirect
+	go.opentelemetry.io/otel/trace v1.43.0 // indirect
 	go.uber.org/atomic v1.11.0 // indirect
-	golang.org/x/mod v0.28.0 // indirect
-	golang.org/x/sync v0.17.0 // indirect
-	golang.org/x/sys v0.36.0 // indirect
-	golang.org/x/text v0.29.0 // indirect
-	golang.org/x/tools v0.37.0 // indirect
+	golang.org/x/mod v0.37.0 // indirect
+	golang.org/x/net v0.56.0 // indirect
+	golang.org/x/sync v0.22.0 // indirect
+	golang.org/x/sys v0.47.0 // indirect
+	golang.org/x/text v0.40.0 // indirect
+	golang.org/x/time v0.3.0 // indirect
+	golang.org/x/tools v0.47.0 // indirect
+	google.golang.org/grpc v1.82.1 // indirect
 	lukechampine.com/uint128 v1.2.0 // indirect
 	modernc.org/cc/v3 v3.40.0 // indirect
 	modernc.org/ccgo/v3 v3.16.13 // indirect
@@ -67,7 +89,6 @@ require (
 	modernc.org/mathutil v1.6.0 // indirect
 	modernc.org/memory v1.7.2 // indirect
 	modernc.org/opt v0.1.3 // indirect
-	modernc.org/sqlite v1.27.0 // indirect
 	modernc.org/strutil v1.1.3 // indirect
 	modernc.org/token v1.0.1 // indirect
 )