relay-flow 0.2.0-alpha → 0.2.2-alpha

package/cmd/relay-flow/scenario_test.go

@@ -2,9 +2,11 @@ package main
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
+	"fmt"
 	"path/filepath"
-	"sort"
+	"reflect"
 	"strings"
 	"sync"
 	"testing"
@@ -14,23 +16,34 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/execution/goworkflows"
 	"github.com/rajpopat27/relay-flow/internal/harness"
 	"github.com/rajpopat27/relay-flow/internal/identity"
+	"github.com/rajpopat27/relay-flow/internal/paths"
 	"github.com/rajpopat27/relay-flow/internal/repo"
 	runsvc "github.com/rajpopat27/relay-flow/internal/run"
 	"github.com/rajpopat27/relay-flow/internal/runner"
+	"github.com/rajpopat27/relay-flow/internal/server"
 	"github.com/rajpopat27/relay-flow/internal/task"
 	"github.com/rajpopat27/relay-flow/internal/workflow"
 )
 
-const scenarioTaskPlugin = "scenario-e2e-task"
+const (
+	scenarioTaskPlugin    = "scenario-e2e-task"
+	scenarioRunnerPlugin  = "scenario-e2e-runner"
+	scenarioHarnessPlugin = "scenario-e2e-harness"
+)
 
 var (
-	scenarioFactoryMu     sync.Mutex
-	scenarioFactorySystem task.System
+	scenarioFactoryMu      sync.Mutex
+	scenarioFactorySystem  task.System
+	scenarioFactoryRunner  runner.Runner
+	scenarioFactoryHarness harness.Harness
 )
 
 func init() {
 	task.Register(scenarioTaskPlugin, task.Factory{
 		RequiredRepoKeys: func() []string { return nil },
+		DefaultConfig: func() config.RawValues {
+			return config.RawValues{"templates": map[string]any{"format": "alternate"}}
+		},
 		TaskScopeKey: func(config.RawValues, config.RawValues) (string, error) {
 			return "scenario-scope", nil
 		},
@@ -40,9 +53,37 @@ func init() {
 			if scenarioFactorySystem == nil {
 				return nil, errors.New("scenario task system not configured")
 			}
+			if fake, ok := scenarioFactorySystem.(*scenarioTaskSystem); ok {
+				fake.log.add("factory:task:" + scenarioTaskPlugin)
+			}
 			return scenarioFactorySystem, nil
 		},
 	})
+	runner.Register(scenarioRunnerPlugin, func(config.RawValues) (runner.Runner, error) {
+		scenarioFactoryMu.Lock()
+		defer scenarioFactoryMu.Unlock()
+		if scenarioFactoryRunner == nil {
+			return nil, errors.New("scenario runner not configured")
+		}
+		if fake, ok := scenarioFactoryRunner.(*scenarioRunner); ok {
+			fake.log.add("factory:runner:" + scenarioRunnerPlugin)
+		}
+		return scenarioFactoryRunner, nil
+	})
+	harness.Register(scenarioHarnessPlugin, harness.Factory{
+		DefaultConfig: func() config.RawValues { return config.RawValues{"runtime": "alternate"} },
+		New: func(config.RawValues) (harness.Harness, error) {
+			scenarioFactoryMu.Lock()
+			defer scenarioFactoryMu.Unlock()
+			if scenarioFactoryHarness == nil {
+				return nil, errors.New("scenario harness not configured")
+			}
+			if fake, ok := scenarioFactoryHarness.(*scenarioHarness); ok {
+				fake.log.add("factory:harness:" + scenarioHarnessPlugin)
+			}
+			return scenarioFactoryHarness, nil
+		},
+	})
 }
 
 func setScenarioFactorySystem(system task.System) {
@@ -51,6 +92,14 @@ func setScenarioFactorySystem(system task.System) {
 	scenarioFactoryMu.Unlock()
 }
 
+func setScenarioFactoryAdapters(system task.System, rnr runner.Runner, hrn harness.Harness) {
+	scenarioFactoryMu.Lock()
+	scenarioFactorySystem = system
+	scenarioFactoryRunner = rnr
+	scenarioFactoryHarness = hrn
+	scenarioFactoryMu.Unlock()
+}
+
 // These scenarios exercise the same composition chain as serve:
 // RepoPoller/handleBatch -> RunManager -> real go-workflows SQLite engine.
 // The only replacements are the documented task, runner, and harness seams.
@@ -89,6 +138,130 @@ func TestScenarioHappyPath(t *testing.T) {
 	assertExactHappyEffects(t, f)
 }
 
+func TestCompositionRootSelectsAlternatePluginsForDurableRun(t *testing.T) {
+	log := newScenarioLog()
+	tasks := newScenarioTaskSystem(log)
+	rnr := newScenarioRunner(log)
+	hrn := newScenarioHarness(log)
+	setScenarioFactoryAdapters(tasks, rnr, hrn)
+
+	root := filepath.Join(t.TempDir(), ".relay-flow")
+	t.Setenv("RELAY_FLOW_HOME", root)
+	p, err := home()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := paths.Ensure(p); err != nil {
+		t.Fatal(err)
+	}
+	if err := config.SaveMachine(p.Config, &config.Machine{
+		PollIntervalSeconds: 1,
+		TaskPlugin:          scenarioTaskPlugin,
+		TaskConfig:          config.RawValues{"provider": "alternate"},
+		RunnerPlugin:        scenarioRunnerPlugin,
+		RunnerConfig:        config.RawValues{"transport": "opaque"},
+		HarnessPlugin:       scenarioHarnessPlugin,
+		HarnessConfig:       config.RawValues{"runtime": "alternate"},
+		Repos: map[string]config.Repo{
+			scenarioRepo: {Path: scenarioRepoPath, TaskConfig: config.RawValues{"scope": "test"}},
+		},
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if err := (&workflow.Store{Dir: p.Workflows}).Put(scenarioWorkflowName, scenarioWorkflowYAML); err != nil {
+		t.Fatal(err)
+	}
+	if err := goworkflows.InitDatabase(p.Database); err != nil {
+		t.Fatal(err)
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	stopped := false
+	go func() { done <- serveRoot(ctx, p, false) }()
+	t.Cleanup(func() {
+		if stopped {
+			return
+		}
+		cancel()
+		select {
+		case <-done:
+		case <-time.After(10 * time.Second):
+		}
+	})
+
+	client := server.NewClient(p.Socket)
+	waitForServer(t, client)
+	var active runsvc.Run
+	waitScenario(t, 10*time.Second, func() bool {
+		var lookupErr error
+		active, lookupErr = client.GetRunByTicket(context.Background(), scenarioTicket)
+		return lookupErr == nil && active.State == runsvc.StateWaiting && active.CurrentNode == "implement"
+	})
+
+	launch := hrn.launch("implement")
+	wantPrompt := "initial taskSystem=" + scenarioTaskPlugin
+	if !strings.Contains(launch.Prompt, wantPrompt) {
+		t.Fatalf("selected task system did not reach launch prompt: %q", launch.Prompt)
+	}
+	command := rnr.command(scenarioTicket + ":implement")
+	wantArgs := []string{"opaque", launch.Prompt}
+	if command.Executable != "fake-harness" || !reflect.DeepEqual(command.Args, wantArgs) {
+		t.Fatalf("runner command = %#v, want opaque harness command args %#v", command, wantArgs)
+	}
+	for _, event := range []string{
+		"factory:task:" + scenarioTaskPlugin,
+		"factory:runner:" + scenarioRunnerPlugin,
+		"factory:harness:" + scenarioHarnessPlugin,
+		"task-config-validated",
+		"runner-repo-validated",
+		"harness-agent-validated:implementer",
+		"harness-launched:" + scenarioTicket + ":implement",
+		"terminal-created:" + scenarioTicket + ":implement",
+	} {
+		if log.countPrefix(event) == 0 {
+			t.Fatalf("composition did not call selected interface boundary %q; events=%v", event, log.all())
+		}
+	}
+
+	for i, next := range []string{"verify", "pr-review", "end"} {
+		current, getErr := client.GetRunByTicket(context.Background(), scenarioTicket)
+		if getErr != nil {
+			t.Fatal(getErr)
+		}
+		ack, submitErr := client.SubmitReport(context.Background(), runsvc.ReportRequest{
+			RunID: current.ID, Node: current.CurrentNode,
+			ReportID: "alternate-session:message-" + fmt.Sprint(i+1),
+			Report:   scenarioReport(workflow.OutcomeSuccess, next),
+		})
+		if submitErr != nil || !ack.Accepted {
+			t.Fatalf("submit durable report %s -> %s: ack=%+v err=%v", current.CurrentNode, next, ack, submitErr)
+		}
+		if next != "end" {
+			waitScenario(t, 10*time.Second, func() bool {
+				advanced, advanceErr := client.GetRunByTicket(context.Background(), scenarioTicket)
+				return advanceErr == nil && advanced.State == runsvc.StateWaiting && advanced.CurrentNode == next
+			})
+		}
+	}
+	waitScenario(t, 10*time.Second, func() bool {
+		finished, getErr := client.GetRunByTicket(context.Background(), scenarioTicket)
+		return getErr == nil && finished.State == runsvc.StateCompleted
+	})
+	if err := client.Stop(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatalf("serveRoot: %v", err)
+		}
+	case <-time.After(10 * time.Second):
+		t.Fatal("serveRoot did not stop")
+	}
+	stopped = true
+}
+
 func TestScenarioHITLRejectLoop(t *testing.T) {
 	f := newScenarioFixture(t)
 	f.pollOnce()
@@ -249,7 +422,7 @@ func TestScenarioLateRegisterAndLateSubmit(t *testing.T) {
 	}
 	repoService := repo.NewServiceWithRegistry(repo.ServiceConfig{
 		ConfigPath: configPath, TaskPlugin: scenarioTaskPlugin, Runner: fr,
-		Active: engine, Workflows: wfService.Registry(),
+		Harness: fh, Active: engine, Workflows: wfService.Registry(),
 	}, reg)
 	deps := &serveDeps{
 		repos:          repoService,
@@ -618,6 +791,7 @@ type scenarioTaskSystem struct {
 	mu  sync.Mutex
 
 	claimed          bool
+	renderText       func(task.TextKind, task.TextData) (string, error)
 	mailboxes        map[string]task.Mailbox
 	specs            map[string]task.MailboxSpec
 	mailboxStatus    map[string]string
@@ -629,6 +803,8 @@ type scenarioTaskSystem struct {
 	completeFailures int
 }
 
+var _ task.System = (*scenarioTaskSystem)(nil)
+
 func newScenarioTaskSystem(log *scenarioLog) *scenarioTaskSystem {
 	return &scenarioTaskSystem{
 		log: log, mailboxes: map[string]task.Mailbox{}, specs: map[string]task.MailboxSpec{},
@@ -660,9 +836,26 @@ func (s *scenarioTaskSystem) Claim(_ context.Context, ref task.TicketRef, workfl
 }
 
 func (s *scenarioTaskSystem) ValidateConfig(context.Context, config.RawValues, map[string]config.RawValues) error {
+	s.log.add("task-config-validated")
 	return nil
 }
 
+func (s *scenarioTaskSystem) RenderText(kind task.TextKind, data task.TextData) (string, error) {
+	if s.renderText != nil {
+		return s.renderText(kind, data)
+	}
+	switch kind {
+	case task.TextMailboxDescription:
+		return "mailbox " + data.Node + ": " + data.NodeDescription, nil
+	case task.TextSummaryComment:
+		return "SUMMARY\n" + data.SummaryReport, nil
+	case task.TextFeedbackComment:
+		return "Feedback from " + data.SourceNode + " to " + data.TargetNode + " mailbox " + data.Mailbox + "\n" + data.FeedbackReport, nil
+	default:
+		return "", fmt.Errorf("unknown task text kind %q", kind)
+	}
+}
+
 func (s *scenarioTaskSystem) EnsureMailboxes(_ context.Context, parent task.TicketRef, _ string, specs []task.MailboxSpec) (map[string]task.Mailbox, error) {
 	s.log.add("mailboxes:ensure")
 	s.mu.Lock()
@@ -827,6 +1020,8 @@ type scenarioRunner struct {
 	cleanups     int
 }
 
+var _ runner.Runner = (*scenarioRunner)(nil)
+
 func newScenarioRunner(log *scenarioLog) *scenarioRunner {
 	return &scenarioRunner{
 		log: log, environments: map[string]runner.Environment{}, terminals: map[string]*scenarioTerminal{},
@@ -838,7 +1033,10 @@ func (r *scenarioRunner) DiscoverRepos(context.Context) ([]runner.RepoCandidate,
 	return []runner.RepoCandidate{{Name: scenarioRepo, Path: scenarioRepoPath}}, nil
 }
 
-func (r *scenarioRunner) ValidateRepo(context.Context, string, string) error { return nil }
+func (r *scenarioRunner) ValidateRepo(context.Context, string, string) error {
+	r.log.add("runner-repo-validated")
+	return nil
+}
 
 func (r *scenarioRunner) EnsureEnvironment(_ context.Context, spec runner.RunSpec) (runner.Environment, error) {
 	r.mu.Lock()
@@ -852,16 +1050,12 @@ func (r *scenarioRunner) EnsureEnvironment(_ context.Context, spec runner.RunSpe
 	return env, nil
 }
 
-func (r *scenarioRunner) FindTerminal(_ context.Context, _ runner.Environment, title string) (runner.Terminal, bool, error) {
-	r.mu.Lock()
-	defer r.mu.Unlock()
-	t, ok := r.terminals[title]
-	if !ok || !t.live {
-		return runner.Terminal{}, false, nil
-	}
-	return t.terminal, true, nil
+func (r *scenarioRunner) SetEnvironmentStatus(_ context.Context, _ runner.Environment, status string) error {
+	r.log.add("workspace-status:" + status)
+	return nil
 }
-func (r *scenarioRunner) InspectTerminal(_ context.Context, terminal runner.Terminal) (runner.Terminal, bool, error) {
+
+func (r *scenarioRunner) FindTerminal(_ context.Context, terminal runner.Terminal) (runner.Terminal, bool, error) {
 	r.mu.Lock()
 	defer r.mu.Unlock()
 	for _, current := range r.terminals {
@@ -872,8 +1066,15 @@ func (r *scenarioRunner) InspectTerminal(_ context.Context, terminal runner.Term
 	return runner.Terminal{}, false, nil
 }
 func (r *scenarioRunner) SendTerminal(context.Context, runner.Terminal, string) error { return nil }
-func (r *scenarioRunner) CreateTerminal(ctx context.Context, env runner.Environment, title string, command runner.Command) (runner.Terminal, error) {
-	return r.EnsureTerminal(ctx, env, title, command)
+func (r *scenarioRunner) CreateTerminal(_ context.Context, _ runner.Environment, title string, command runner.Command) (runner.Terminal, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	terminal := runner.Terminal{ID: "terminal-" + title, Title: title}
+	r.terminals[title] = &scenarioTerminal{terminal: terminal, live: true}
+	r.commands[title] = append(r.commands[title], command)
+	r.launches[title]++
+	r.log.add("terminal-created:" + title)
+	return terminal, nil
 }
 
 func (r *scenarioRunner) CloseTerminal(_ context.Context, terminal runner.Terminal) error {
@@ -886,18 +1087,13 @@ func (r *scenarioRunner) CloseTerminal(_ context.Context, terminal runner.Termin
 	return nil
 }
 
-func (r *scenarioRunner) EnsureTerminal(_ context.Context, _ runner.Environment, title string, command runner.Command) (runner.Terminal, error) {
-	r.mu.Lock()
-	defer r.mu.Unlock()
-	if existing, ok := r.terminals[title]; ok && existing.live {
-		return existing.terminal, nil
+func (r *scenarioRunner) EnsureTerminal(ctx context.Context, env runner.Environment, stored runner.Terminal, title string, command runner.Command) (runner.Terminal, error) {
+	if terminal, ok, err := r.FindTerminal(ctx, stored); err != nil {
+		return runner.Terminal{}, err
+	} else if ok {
+		return terminal, nil
 	}
-	terminal := runner.Terminal{ID: "terminal-" + title, Title: title}
-	r.terminals[title] = &scenarioTerminal{terminal: terminal, live: true}
-	r.commands[title] = append(r.commands[title], command)
-	r.launches[title]++
-	r.log.add("terminal-created:" + title)
-	return terminal, nil
+	return r.CreateTerminal(ctx, env, title, command)
 }
 
 func (r *scenarioRunner) CloseTerminals(context.Context, runner.RunSpec) error {
@@ -948,11 +1144,18 @@ type scenarioHarness struct {
 	launches map[string][]harness.LaunchSpec
 }
 
+func (*scenarioHarness) SetupRepo(context.Context, string) error { return nil }
+
+var _ harness.Harness = (*scenarioHarness)(nil)
+
 func newScenarioHarness(log *scenarioLog) *scenarioHarness {
 	return &scenarioHarness{log: log, sessions: map[string]harness.Session{}, launches: map[string][]harness.LaunchSpec{}}
 }
 
-func (h *scenarioHarness) ValidateAgent(context.Context, string, string) error { return nil }
+func (h *scenarioHarness) ValidateAgent(_ context.Context, _, agent string) error {
+	h.log.add("harness-agent-validated:" + agent)
+	return nil
+}
 
 func (h *scenarioHarness) FindSession(_ context.Context, _ string, title string) (harness.Session, bool, error) {
 	h.mu.Lock()
@@ -961,6 +1164,17 @@ func (h *scenarioHarness) FindSession(_ context.Context, _ string, title string)
 	return session, ok, nil
 }
 
+func (h *scenarioHarness) RenderPrompt(kind harness.PromptKind, data harness.PromptData, nudge string) (string, error) {
+	prompt := string(kind) + " taskSystem=" + data.TaskSystem + " mailbox=" + data.Mailbox
+	if data.NodeType == workflow.NodeHITL {
+		prompt += " hitl"
+	}
+	if nudge != "" {
+		prompt += " " + nudge
+	}
+	return prompt, nil
+}
+
 func (h *scenarioHarness) BuildCommand(spec harness.LaunchSpec) (runner.Command, error) {
 	h.mu.Lock()
 	h.launches[spec.Node] = append(h.launches[spec.Node], spec)
@@ -969,6 +1183,7 @@ func (h *scenarioHarness) BuildCommand(spec harness.LaunchSpec) (runner.Command,
 	h.log.add("harness-launched:" + spec.Title)
 	return runner.Command{
 		Executable: "fake-harness",
+		Args:       []string{"opaque", spec.Prompt},
 		Env: map[string]string{
 			"RELAY_FLOW_RUN_ID":          string(spec.RunID),
 			"RELAY_FLOW_WORKFLOW":        spec.Workflow,
@@ -993,12 +1208,8 @@ func (h *scenarioHarness) launch(node string) harness.LaunchSpec {
 }
 
 func routesJSON(routes []workflow.Route) string {
-	parts := make([]string, 0, len(routes))
-	for _, route := range routes {
-		parts = append(parts, route.Target)
-	}
-	sort.Strings(parts)
-	return "[\"" + strings.Join(parts, "\",\"") + "\"]"
+	b, _ := json.Marshal(routes)
+	return string(b)
 }
 
 type scenarioRepoLookup struct{ reg *repo.Registry }

package/cmd/relay-flow/serve.go

@@ -35,6 +35,7 @@ import (
 	// Adapter registrations (factories are registered by name via init).
 	_ "github.com/rajpopat27/relay-flow/internal/harness/opencode"
 	_ "github.com/rajpopat27/relay-flow/internal/runner/orca"
+	_ "github.com/rajpopat27/relay-flow/internal/task/beads"
 	_ "github.com/rajpopat27/relay-flow/internal/task/jira"
 )
 
@@ -204,6 +205,7 @@ func serveRoot(ctx context.Context, p paths.Paths, recover bool) error {
 		Repos:         repoReg,
 		Runner:        rnr,
 		Harness:       hrn,
+		TaskSystem:    cfg.TaskPlugin,
 		RetentionDays: cfg.CompletedRunRetentionDays,
 		Runtime: &runsvc.RuntimePolicy{
 			KeepTerminalsAlive: cfg.KeepTerminalsAlive,
@@ -262,6 +264,7 @@ func serveRoot(ctx context.Context, p paths.Paths, recover bool) error {
 		ConfigPath: p.Config,
 		TaskPlugin: cfg.TaskPlugin,
 		Runner:     rnr,
+		Harness:    hrn,
 		Active:     engine,
 		Workflows:  wfSvc.Registry(),
 	}, repoReg)
@@ -272,8 +275,8 @@ func serveRoot(ctx context.Context, p paths.Paths, recover bool) error {
 	// specs come from the engine so the recover path builds the same
 	// description content as normal run execution.
 	if recover {
-		specsFor := func(wf *workflow.Workflow, ticketKey string) []task.MailboxSpec {
-			return goworkflows.MailboxSpecs(wf, ticketKey)
+		specsFor := func(sys task.System, work runsvc.Work, wf *workflow.Workflow) ([]task.MailboxSpec, error) {
+			return goworkflows.RenderMailboxSpecs(sys, work, wf)
 		}
 		if err := recoverpkg.FromTaskSystem(ctx, repoReg, rnr, runManager, specsFor); err != nil {
 			shutdownCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)

package/examples/beads-workflow.yaml

@@ -0,0 +1,74 @@
+# Beads workflow example. Register the code repository with a required
+# repo-scoped taskConfig.beadsDir before submitting this workflow, for example:
+#
+#   relay-flow repo register --name payments --path /work/payments \
+#     --set beadsDir=/work/payments/.beads
+#
+# The Beads prefix is optional and is not a workspace/component selector.
+name: beadsStoryFlow
+repos:
+  - payments
+cleanupRunnerOnEnd: true
+
+taskConfig:
+  filters:
+    # Beads statuses are open, in_progress, blocked, deferred, hooked, closed.
+    parentStatuses:
+      - open
+    issueTypes:
+      - epic
+    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.
+  # assignee: owner@example.com
+
+# transitionTo describes one lifecycle point, so configure it on a node.
+# Omitting it entirely already gives the Jira-equivalent lifecycle:
+# start parent -> in_progress, work mailbox -> in_progress, end parent -> closed.
+# Values are Beads-native, not Jira values such as "In Progress" or "Done".
+nodes:
+  start:
+    taskConfig:
+      transitionTo:
+        parentStatus: in_progress
+    onSuccess:
+      - target: implement
+        when: The Beads parent is ready for implementation
+
+  implement:
+    type: agent
+    agent: build
+    description: Implement the Beads parent and verify the changes.
+    taskConfig:
+      # assignee: developer@example.com
+      transitionTo:
+        taskStatus: in_progress
+    onSuccess:
+      - target: review
+        when: Implementation and verification are complete
+    onFailure:
+      - target: implement
+        when: Implementation needs another pass
+
+  review:
+    type: hitl
+    agent: plan
+    description: Review the implementation and obtain approval.
+    taskConfig:
+      # assignee: reviewer@example.com
+      transitionTo:
+        taskStatus: in_progress
+    onSuccess:
+      - target: end
+        when: The review is approved
+    onFailure:
+      - target: implement
+        when: Changes are requested
+
+  end:
+    taskConfig:
+      transitionTo:
+        parentStatus: closed

package/examples/default-story-workflow.yaml

@@ -0,0 +1,88 @@
+# Copy this file and replace "payments" with one or more registered repo names.
+# Optional fields are shown commented; uncomment only the behavior you need.
+name: defaultStoryFlow
+repos:
+  - test-relay-flow
+cleanupRunnerOnEnd: true
+
+taskConfig:
+  filters:
+    parentStatuses:
+      - To Do
+    issueTypes:
+      - Story
+    # labels:
+    #   - coding
+    # assignees:
+    #   - owner@example.com
+  # assignee: default-node-owner@example.com
+  # project: PAY
+  # component: api
+  # transitionTo:
+  #   parentStatus: In Progress
+  #   taskStatus: In Progress
+
+nodes:
+  start:
+    taskConfig:
+      transitionTo:
+        parentStatus: In Progress
+    onSuccess:
+      - target: implement
+        when: The parent story is ready for implementation
+
+  implement:
+    type: agent
+    agent: build
+    description: Implement the parent story and verify the changes.
+    # nudgePrompt: "Finish {{node}} for {{ticket}} and choose one of: {{nextSteps}}"
+    taskConfig:
+      # assignee: developer@example.com
+      transitionTo:
+        taskStatus: In Progress
+        # parentStatus: 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, and missing tests.
+    # nudgePrompt: "Complete the review for {{ticket}}. Valid routes: {{nextSteps}}"
+    taskConfig:
+      # assignee: reviewer@example.com
+      transitionTo:
+        taskStatus: In Progress
+        # parentStatus: In Review
+    onSuccess:
+      - target: prReview
+        when: The changes are ready for human approval
+    onFailure:
+      - target: implement
+        when: Code changes are required
+
+  prReview:
+    type: hitl
+    agent: plan
+    description: Discuss the pull request with the human and obtain approval.
+    # nudgePrompt: "Review {{ticket}} with the human. Valid routes: {{nextSteps}}"
+    taskConfig:
+      # assignee: human-reviewer@example.com
+      transitionTo:
+        taskStatus: In Progress
+        # parentStatus: In Review
+    onSuccess:
+      - target: end
+        when: The human approves the review
+    onFailure:
+      - target: implement
+        when: The human requests code changes
+
+  end:
+    taskConfig:
+      transitionTo:
+        parentStatus: Done

package/go.mod

@@ -2,10 +2,11 @@ module github.com/rajpopat27/relay-flow
 
 go 1.24.6
 
-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
 	gopkg.in/yaml.v3 v3.0.1
 )
 

package/go.sum

@@ -122,6 +122,8 @@ github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOf
 github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
+github.com/yuin/goldmark v1.7.13 h1:GPddIs617DnBLFFVJFgpo1aBfe/4xcvMc3SB5t/D0pA=
+github.com/yuin/goldmark v1.7.13/go.mod h1:ip/1k0VRfGynBgxOz0yCqHrbZXhcjxyuS66Brc7iBKg=
 go.opentelemetry.io/otel v1.31.0 h1:NsJcKPIW0D0H3NgzPDHmo0WW6SptzPdqg/L1zsIm2hY=
 go.opentelemetry.io/otel v1.31.0/go.mod h1:O0C14Yl9FgkjqcCZAsE053C13OaddMYr/hz6clDkEJE=
 go.opentelemetry.io/otel/metric v1.31.0 h1:FSErL0ATQAmYHUIzSezZibnyVlft1ybhy4ozRPcF2fE=

package/internal/config/config.go

@@ -26,9 +26,9 @@ func Merge(values ...RawValues) RawValues {
 
 func mergeInto(dst, src map[string]any) map[string]any {
 	for k, sv := range src {
-		if sm, ok := sv.(map[string]any); ok {
+		if sm, ok := rawMap(sv); ok {
 			fresh := map[string]any{}
-			if dm, ok := dst[k].(map[string]any); ok {
+			if dm, ok := rawMap(dst[k]); ok {
 				mergeInto(fresh, dm)
 			}
 			dst[k] = mergeInto(fresh, sm)
@@ -39,6 +39,17 @@ func mergeInto(dst, src map[string]any) map[string]any {
 	return dst
 }
 
+func rawMap(value any) (map[string]any, bool) {
+	switch values := value.(type) {
+	case map[string]any:
+		return values, true
+	case RawValues:
+		return map[string]any(values), true
+	default:
+		return nil, false
+	}
+}
+
 // DecodeStrict decodes raw values into dst, rejecting unknown fields and
 // explicit null values.
 func DecodeStrict(values RawValues, dst any) error {