relay-flow 0.3.10-alpha → 0.3.12-alpha

package/README.md

@@ -28,13 +28,13 @@ same `relay-flow-plugin` package with host-specific entrypoints.
 **OpenCode**
 
 ```sh
-opencode plugin relay-flow-plugin@0.3.10-alpha
+opencode plugin relay-flow-plugin@0.3.12-alpha
 ```
 
 **Pi**
 
 ```sh
-pi install npm:relay-flow-plugin@0.3.10-alpha
+pi install npm:relay-flow-plugin@0.3.12-alpha
 ```
 
 Pi loads the package's `pi.ts` extension from its manifest. Do not add
@@ -164,7 +164,7 @@ OpenCode plugin configuration uses both entrypoints. The server entrypoint is li
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["relay-flow-plugin@0.3.10-alpha"]
+  "plugin": ["relay-flow-plugin@0.3.12-alpha"]
 }
 ```
 
@@ -173,7 +173,7 @@ The native HITL approval entrypoint is listed in `.opencode/tui.json`:
 ```json
 {
   "$schema": "https://opencode.ai/tui.json",
-  "plugin": ["relay-flow-plugin@0.3.10-alpha"]
+  "plugin": ["relay-flow-plugin@0.3.12-alpha"]
 }
 ```
 
@@ -189,7 +189,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@0.3.10-alpha
+pi install npm:relay-flow-plugin@0.3.12-alpha
 ```
 
 Relay-flow does not install or configure the package automatically. Pi resolves
@@ -614,28 +614,16 @@ durable run waiting; Pi does not require an LLM Question tool for this step.
 
 ## Structured node report
 
-Every visit (agent or HITL) submits one report with the same fixed labels:
+Every visit (agent or HITL) submits one report with four fixed fields:
 
 ```
 STATUS: success | failure
-NEXT STEP: <one configured route for that status>
-
-SUMMARY:
-COMPLETED: ...
-COMMITS: <commit IDs or None>
-NOT COMPLETED: ... | None
-ISSUES DISCOVERED: ... | None
-VERIFICATION: ...
-NOTES: ... | None
-
-FEEDBACK:
-REASON FOR NEXT STEP: ...
-REQUIRED ACTIONS: ...
-RELEVANT CONTEXT: ...
-EXPECTED RESULT: ...
+NEXT STEP: <one valid route>
+SUMMARY: <concise result>
+FEEDBACK: <concise handoff, or None when NEXT STEP is end>
 ```
 
-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 report format is hardcoded, exposed as `{{report}}` in Jira mailbox templates and passed to the runtime plugin through `RELAY_FLOW_REPORT_FORMAT`; configurable templates do not change it. The plugin maps `SUMMARY` to `report.summary.completed` and `FEEDBACK` to `report.feedback.requiredActions`, filling the remaining internal JSON fields with `None`. Relay-flow validates the structured report and writes the current summary to its mailbox and only the selected feedback to the next mailbox. When `NEXT STEP` is `end`, `FEEDBACK` must be exactly `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; ordinary, missing, or empty HITL output stays silent, while partial report-shaped HITL output is corrected and a valid HITL report opens the native TUI approval dialog. Relay-flow HITL approval does not use OpenCode's Question tool.
 

package/cmd/relay-flow/commands_test.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"database/sql"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
@@ -23,6 +24,7 @@ import (
 
 	"github.com/charmbracelet/huh"
 	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/harness"
 	"github.com/rajpopat27/relay-flow/internal/repo"
 	runsvc "github.com/rajpopat27/relay-flow/internal/run"
 	"github.com/rajpopat27/relay-flow/internal/runner"
@@ -276,6 +278,36 @@ func TestReportAckMatrix(t *testing.T) {
 	}
 }
 
+func TestReportValidationErrorIsStructuredOnStderr(t *testing.T) {
+	const message = "NEXT STEP is end, so FEEDBACK must be exactly None."
+	const valid = `{"runId":"run-1","node":"coding","reportId":"s:m","report":{"status":"success","nextStep":"end","summary":{"completed":"done","commits":"None","notCompleted":"None","issuesDiscovered":"None","verification":"None","notes":"None"},"feedback":{"reasonForNextStep":"None","requiredActions":"None","relevantContext":"None","expectedResult":"None"}}}`
+	home := t.TempDir()
+	serveAck(t, home, runsvc.ReportAck{}, &runsvc.InvalidReportError{Reason: message})
+	reader, writer, err := os.Pipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	original := os.Stderr
+	os.Stderr = writer
+	code := cli(t, home, valid, "report")
+	os.Stderr = original
+	_ = writer.Close()
+	defer reader.Close()
+	output, err := io.ReadAll(reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var response struct {
+		Error struct {
+			Code    string `json:"code"`
+			Message string `json:"message"`
+		} `json:"error"`
+	}
+	if err := json.Unmarshal(output, &response); err != nil || code != exitFail || response.Error.Code != "invalidReport" || response.Error.Message != message {
+		t.Fatalf("CLI validation response: exit=%d stderr=%q parsed=%+v err=%v", code, output, response, err)
+	}
+}
+
 func TestReportUnreachableServerExits1(t *testing.T) {
 	valid := `{"runId":"payments/basicFlow/PAY-101","node":"coding","reportId":"s:m","report":{"status":"success","nextStep":"end","summary":{"completed":"x","commits":"abc123","notCompleted":"None","issuesDiscovered":"None","verification":"x","notes":"None"},"feedback":{"reasonForNextStep":"None","requiredActions":"None","relevantContext":"None","expectedResult":"None"}}}`
 	if code := cli(t, t.TempDir(), valid, "report"); code != 1 {
@@ -386,6 +418,9 @@ func TestInitWritesHarnessPromptDefaults(t *testing.T) {
 			t.Fatalf("harnessConfig.%s = %#v", key, cfg.HarnessConfig[key])
 		}
 	}
+	if cfg.HarnessConfig["initial"] != harness.JiraInitialPrompt || cfg.HarnessConfig["feedback"] != harness.JiraFeedbackPrompt {
+		t.Fatalf("Jira prompt defaults = %#v", cfg.HarnessConfig)
+	}
 }
 
 func TestInitWritesTaskTextDefaults(t *testing.T) {
@@ -406,6 +441,9 @@ func TestInitWritesTaskTextDefaults(t *testing.T) {
 			t.Fatalf("taskConfig.templates.%s = %#v", key, templates[key])
 		}
 	}
+	if !strings.Contains(templates["mailboxDescription"].(string), "{{report}}") {
+		t.Fatal("Jira mailbox description must expose the canonical report")
+	}
 }
 
 func TestInitDoesNotCollectOrWriteTaskCredentials(t *testing.T) {
@@ -480,7 +518,7 @@ func TestInitForcePreservesDurableAndUserState(t *testing.T) {
 	if !ok {
 		t.Fatalf("taskConfig.templates = %#v", cfg.TaskConfig["templates"])
 	}
-	taskTemplates["mailboxDescription"] = "custom {{nodeDescription}}"
+	taskTemplates["mailboxDescription"] = "custom {{ticket}} / {{node}} — {{nodeType}} — {{agent}}\n{{nodeDescription}}\n{{successRoutes}}\n{{failureRoutes}}\n{{report}}"
 	if err := config.SaveMachine(filepath.Join(root, "config.yaml"), cfg); err != nil {
 		t.Fatal(err)
 	}
@@ -528,7 +566,7 @@ func TestInitForcePreservesDurableAndUserState(t *testing.T) {
 	if !ok {
 		t.Fatalf("taskConfig.templates = %#v", cfg.TaskConfig["templates"])
 	}
-	if got := gotTaskTemplates["mailboxDescription"]; got != "custom {{nodeDescription}}" {
+	if got := gotTaskTemplates["mailboxDescription"]; got != "custom {{ticket}} / {{node}} — {{nodeType}} — {{agent}}\n{{nodeDescription}}\n{{successRoutes}}\n{{failureRoutes}}\n{{report}}" {
 		t.Fatalf("forced init changed task text override: %#v", got)
 	}
 	for _, key := range []string{"summaryComment", "feedbackComment"} {

package/cmd/relay-flow/main.go

@@ -9,6 +9,7 @@ import (
 	"bufio"
 	"context"
 	"encoding/json"
+	"errors"
 	"flag"
 	"fmt"
 	"io"
@@ -664,6 +665,10 @@ func cmdInit(p paths.Paths, args []string, stdin io.Reader) int {
 		fmt.Fprintln(os.Stderr, "init: harness plugin: "+err.Error())
 		return exitFail
 	}
+	if names[0] == "jira" {
+		harnessDefaults["initial"] = harness.JiraInitialPrompt
+		harnessDefaults["feedback"] = harness.JiraFeedbackPrompt
+	}
 	if !*force || !configExists {
 		cfg.HarnessConfig = harnessDefaults
 	} else {
@@ -1142,7 +1147,14 @@ func cmdReport(c *server.Client, stdin io.Reader) int {
 	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
 	defer cancel()
 	if _, err := c.SubmitReport(ctx, req); err != nil {
-		fmt.Fprintln(os.Stderr, err)
+		var apiErr *server.APIError
+		if errors.As(err, &apiErr) && apiErr.Code == "invalidReport" {
+			_ = json.NewEncoder(os.Stderr).Encode(map[string]any{
+				"error": map[string]string{"code": apiErr.Code, "message": apiErr.Message},
+			})
+		} else {
+			fmt.Fprintln(os.Stderr, err)
+		}
 		return exitFail
 	}
 	return exitOK

package/examples/config-reference.yaml

@@ -42,21 +42,19 @@ taskConfig:
   #   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.
+  # Jira mailbox descriptions include the canonical report through {{report}}.
   templates:
     mailboxDescription: |-
-      Parent ticket: {{ticket}}
-      Workflow: {{workflow}}
-      Node: {{node}}
-      Node type: {{nodeType}}
-      Agent: {{agent}}
-      Mailbox: {{mailbox}}
-
-      Node work:
+      {{ticket}} / {{node}} — {{nodeType}} — {{agent}}
       {{nodeDescription}}
 
-      Read this mailbox's comments for feedback from previous nodes.
+      Success routes:
+      {{successRoutes}}
+
+      Failure routes:
+      {{failureRoutes}}
+
+      {{report}}
 
     summaryComment: |-
       Summary for {{node}}
@@ -80,14 +78,19 @@ harnessPlugin: opencode
 harnessConfig:
   # OpenCode supports initial, feedback, and hitl templates.
   initial: |-
-    Task system: {{taskSystem}}
-    Use the {{taskSystem}} tools to read the parent ticket {{ticket}}.
+    Read the description of your assigned Jira task:
+    acli jira workitem view "{{mailbox}}" --fields "summary,description" --json
 
-    Your mailbox is {{mailbox}}. Read its description and comments for node instructions and feedback.
+    Follow the work instructions, valid routes, and report format in that description.
 
   feedback: |-
-    New feedback was added to the comments section of your mailbox subtask {{mailbox}}. Read it.
+    Continue {{node}} from the latest update on your assigned Jira task:
+    acli jira workitem comment list --key "{{mailbox}}" --limit 1 --order "-created" --json
 
+  # A node needing parent details can request this additional instruction
+  # in its node description (it is not included by default):
+  # Read the parent Jira ticket for this step:
+  # acli jira workitem view "{{ticket}}" --fields "summary,description" --json
   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.
 
@@ -135,12 +138,13 @@ repos:
 # harnessPlugin: pi
 # harnessConfig:
 #   initial: |
-#     Task system: {{taskSystem}}
-#     Use the {{taskSystem}} tools to read the parent ticket {{ticket}}.
+#     Read the description of your assigned Jira task:
+#     acli jira workitem view "{{mailbox}}" --fields "summary,description" --json
 #
-#     Your mailbox is {{mailbox}}. Read its description and comments for node instructions and feedback.
+#     Follow the work instructions, valid routes, and report format in that description.
 #   feedback: |
-#     New feedback was added to the comments section of your mailbox subtask {{mailbox}}. Read it.
+#     Continue {{node}} from the latest update on your assigned Jira task:
+#     acli jira workitem comment list --key "{{mailbox}}" --limit 1 --order "-created" --json
 #
 # Pi accepts only initial and feedback harness templates. Pi workflow nodes
 # may use agent: default or a native project prompt template in

package/examples/workflow-reference.yaml

@@ -56,6 +56,9 @@ nodes:
     type: agent
     agent: build
     description: |
+      Read the parent Jira ticket for this step:
+      acli jira workitem view "{{ticket}}" --fields "summary,description" --json
+
       Implement the parent ticket in the ticket worktree.
       Run the relevant tests and verification commands.
     nudgePrompt: |

package/internal/execution/goworkflows/activities.go

@@ -80,7 +80,11 @@ func (a *Activities) EnsureMailboxes(ctx context.Context, w run.Work, specs []ta
 		if err != nil {
 			return nil, fmt.Errorf("render mailbox %q description: %w", specs[i].Node, err)
 		}
-		specs[i].Description = appendText(custom, specs[i].Description)
+		if data.Report != "" && strings.Contains(custom, data.Report) {
+			specs[i].Description = custom
+		} else {
+			specs[i].Description = appendText(custom, specs[i].Description)
+		}
 	}
 	return sys.EnsureMailboxes(ctx, w.Parent, w.Workflow, specs)
 }
@@ -488,26 +492,9 @@ func MailboxSpecForNode(wf *workflow.Workflow, ticketKey, name string, n workflo
 	var b strings.Builder
 	b.WriteString(`Required report format:
 
-STATUS: success | failure
-NEXT STEP: <one valid node name>
-
-SUMMARY:
-COMPLETED:
-COMMITS:
-NOT COMPLETED:
-ISSUES DISCOVERED:
-VERIFICATION:
-NOTES:
-
-FEEDBACK:
-REASON FOR NEXT STEP:
-REQUIRED ACTIONS:
-RELEVANT CONTEXT:
-EXPECTED RESULT:
+` + workflow.ReportFormat + `
 
-Every field is required; use None for an intentionally empty section. COMMITS must contain the relevant commit IDs or None.
-
-Node names identify workflow stages; they are not task-system statuses. STATUS describes whether the work at this node succeeded or failed, not the status of the parent or mailbox. NEXT STEP must name exactly one target listed below for that STATUS. Submit one report only: its SUMMARY is written to this current mailbox, while its FEEDBACK is written only to the selected next node's mailbox. For review nodes, put requested changes in FEEDBACK and select the node responsible for acting on them. Relay-flow and the task system own parent and mailbox status changes. When NEXT STEP is end, every FEEDBACK field must be None.`)
+Node names identify workflow stages; they are not task-system statuses. STATUS describes whether the work at this node succeeded or failed, not the status of the parent or mailbox. NEXT STEP must name exactly one target listed below for that STATUS. Submit one report only: its SUMMARY is written to this current mailbox, while its FEEDBACK is written only to the selected next node's mailbox. For review nodes, put requested changes in FEEDBACK and select the node responsible for acting on them. Relay-flow and the task system own parent and mailbox status changes. When NEXT STEP is end, FEEDBACK must be None.`)
 	writeRoutes := func(label string, routes []workflow.Route) {
 		if len(routes) == 0 {
 			return
@@ -535,7 +522,7 @@ Node names identify workflow stages; they are not task-system statuses. STATUS d
 			Agent: n.Agent, NodeDescription: n.Description,
 			NextSteps:     nextStepsText(append(append([]workflow.Route{}, n.OnSuccess...), n.OnFailure...)),
 			SuccessRoutes: successRoutes, FailureRoutes: failureRoutes,
-			Mailbox: ticketKey + ":" + name,
+			Mailbox: ticketKey + ":" + name, Report: workflow.ReportFormat,
 		},
 	}
 }
@@ -569,7 +556,11 @@ func RenderMailboxSpecs(sys task.System, w run.Work, wf *workflow.Workflow) ([]t
 		if err != nil {
 			return nil, fmt.Errorf("render mailbox %q description: %w", specs[i].Node, err)
 		}
-		specs[i].Description = appendText(custom, specs[i].Description)
+		if data.Report != "" && strings.Contains(custom, data.Report) {
+			specs[i].Description = custom
+		} else {
+			specs[i].Description = appendText(custom, specs[i].Description)
+		}
 	}
 	return specs, nil
 }

package/internal/execution/goworkflows/engine.go

@@ -394,7 +394,7 @@ func (e *Engine) SubmitReport(ctx context.Context, req run.ReportRequest) (run.R
 	}
 	if err := wf.ValidateReport(req.Node, req.Report); err != nil {
 		slog.Info("report validation failed", append(attrs, "reason", err.Error())...)
-		return run.ReportAck{Accepted: false}, err
+		return run.ReportAck{}, &run.InvalidReportError{Reason: err.Error()}
 	}
 	signal := reportSignal{
 		ReportID: req.ReportID, Node: req.Node,

package/internal/execution/goworkflows/engine_test.go

@@ -3,6 +3,7 @@ package goworkflows_test
 import (
 	"context"
 	"database/sql"
+	"errors"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -72,13 +73,16 @@ func TestMailboxDescriptionAndLaunchPromptAreTaskSystemNeutral(t *testing.T) {
 			t.Fatal(err)
 		}
 		want := "Task system: " + taskSystem + "\nUse the " + taskSystem + " tools to read the parent ticket PAY-101.\n\nYour mailbox is PAY-234. Read its description and comments for node instructions and feedback.\n\nKeep the summary brief, and make the feedback as detailed and actionable as possible for the next agent.\n\nReturn 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."
+		if taskSystem == "jira" {
+			want = "Read the description of your assigned Jira task:\nacli jira workitem view \"PAY-234\" --fields \"summary,description\" --json\n\nFollow the work instructions, valid routes, and report format in that description."
+		}
 		if prompt != want {
 			t.Fatalf("RenderPrompt(%s) = %q, want %q", taskSystem, prompt, want)
 		}
-		if strings.Contains(prompt, "Jira") || strings.Contains(prompt, "subtask") {
+		if taskSystem != "jira" && (strings.Contains(prompt, "Jira") || strings.Contains(prompt, "subtask")) {
 			t.Fatalf("launch prompt contains task-system-specific mailbox wording: %q", prompt)
 		}
-		if strings.Contains(prompt, "STATUS:") || strings.Contains(prompt, node.Description) {
+		if strings.Contains(prompt, "STATUS:") || (taskSystem != "jira" && strings.Contains(prompt, node.Description)) {
 			t.Fatalf("launch prompt duplicates mailbox instructions: %q", prompt)
 		}
 	}
@@ -291,6 +295,40 @@ func TestSerialGraphOneNodeAtATime(t *testing.T) {
 	})
 }
 
+func TestInvalidReportIsPermanentAndDoesNotSignal(t *testing.T) {
+	log := newEventLog()
+	engine := newEngine(t, goworkflows.Dependencies{
+		Repos:  repoRegistryWith("payments", newFakeTaskSystem(log)),
+		Runner: newFakeRunner(log), Harness: newFakeHarness(log),
+	})
+	rid, err := startRun(engine, linearWorkflow(false))
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 10*time.Second, func() bool {
+		r, err := engine.GetRun(context.Background(), rid)
+		return err == nil && r.CurrentNode == "coding" && r.CurrentNodeVisitID != ""
+	})
+	before, _ := engine.GetRun(context.Background(), rid)
+	invalid := successReport("end")
+	invalid.Feedback.RequiredActions = "needs work"
+	ack, err := engine.SubmitReport(context.Background(), reportRequest(rid, "coding", invalid))
+	if !errors.Is(err, run.ErrInvalidReport) || ack.Accepted {
+		t.Fatalf("invalid report: ack=%+v err=%v", ack, err)
+	}
+	if want := `report selects "end": every feedback field must be "None" because end has no mailbox`; err.Error() != want {
+		t.Fatalf("validation message = %q, want %q", err, want)
+	}
+	after, err := engine.GetRun(context.Background(), rid)
+	if err != nil || after.CurrentNodeVisitID != before.CurrentNodeVisitID {
+		t.Fatalf("invalid report advanced visit: before=%+v after=%+v err=%v", before, after, err)
+	}
+	ack, err = engine.SubmitReport(context.Background(), reportRequest(rid, "coding", successReport("end")))
+	if err != nil || !ack.Accepted {
+		t.Fatalf("corrected report: ack=%+v err=%v", ack, err)
+	}
+}
+
 func TestRevisitCreatesNewVisit(t *testing.T) {
 	log := newEventLog()
 	sys := newFakeTaskSystem(log)
@@ -467,6 +505,7 @@ func TestTransitionOrdering(t *testing.T) {
 	log := newEventLog()
 	sys := newFakeTaskSystem(log)
 	fr := newFakeRunner(log)
+	fh := newFakeHarness(log)
 	wf := workflow.Workflow{
 		Name: "reviewFlow", Repos: []string{"payments"},
 		Nodes: map[string]workflow.Node{
@@ -485,7 +524,7 @@ func TestTransitionOrdering(t *testing.T) {
 		},
 	}
 	engine := newEngine(t, goworkflows.Dependencies{
-		Repos: repoRegistryWith("payments", sys), Runner: fr, Harness: newFakeHarness(log),
+		Repos: repoRegistryWith("payments", sys), Runner: fr, Harness: fh,
 	})
 	rid, _ := startRun(engine, wf)
 	waitFor(t, 10*time.Second, func() bool {
@@ -510,6 +549,16 @@ func TestTransitionOrdering(t *testing.T) {
 		t.Fatalf("HITL status was not set before terminal start; events=%v", events)
 	}
 
+	var sawReviewFeedback bool
+	for _, call := range fh.promptCalls() {
+		if call.Data.Node == "review" && call.Data.PreviousFeedback == "review it" {
+			sawReviewFeedback = true
+		}
+	}
+	if !sawReviewFeedback {
+		t.Fatalf("next node prompt did not receive selected feedback: %+v", fh.promptCalls())
+	}
+
 	// Exact cross-primitive order, observed through the fake-adapter and fake-
 	// runner call logs (the settled observation seam):
 	// summary(current) -> feedback(selected next) -> CompleteMailbox(current)

package/internal/execution/goworkflows/interpreter.go

@@ -205,6 +205,7 @@ func (a *Activities) runGraph(ctx goworkflow.Context, start run.Start) error {
 	}
 
 	current := target
+	previousFeedback := ""
 	seenReportIDs := map[string]bool{}
 	lastStepByNode := map[string]int64{}
 	lastDepthByNode := map[string]int{}
@@ -297,16 +298,17 @@ func (a *Activities) runGraph(ctx goworkflow.Context, start run.Start) error {
 			Title:       title,
 			NudgePrompt: node.NudgePrompt,
 			PromptData: harness.PromptData{
-				TaskSystem:      a.TaskSystem,
-				Ticket:          start.Ticket.Key,
-				Workflow:        wf.Name,
-				Repo:            start.Repo,
-				Node:            current,
-				NodeType:        node.Type,
-				Agent:           node.Agent,
-				NodeDescription: node.Description,
-				NextSteps:       nextStepsText(nextSteps),
-				Mailbox:         mb.Key,
+				TaskSystem:       a.TaskSystem,
+				Ticket:           start.Ticket.Key,
+				Workflow:         wf.Name,
+				Repo:             start.Repo,
+				Node:             current,
+				NodeType:         node.Type,
+				Agent:            node.Agent,
+				NodeDescription:  node.Description,
+				NextSteps:        nextStepsText(nextSteps),
+				Mailbox:          mb.Key,
+				PreviousFeedback: previousFeedback,
 			},
 			NextSteps: nextSteps,
 		}
@@ -395,7 +397,9 @@ func (a *Activities) runGraph(ctx goworkflow.Context, start run.Start) error {
 		stepMessage := report.Summary.Completed
 		if report.Status == workflow.OutcomeFailure {
 			stepStatus = run.StepFailed
-			stepMessage = report.Summary.IssuesDiscovered
+			if report.Summary.IssuesDiscovered != workflow.None {
+				stepMessage = report.Summary.IssuesDiscovered
+			}
 		}
 		stepFinished := goworkflow.Now(ctx).UTC()
 		if _, err := retryLoop(ctx, start.ID, a, work, current,
@@ -465,6 +469,7 @@ func (a *Activities) runGraph(ctx goworkflow.Context, start run.Start) error {
 			return err
 		}
 
+		previousFeedback = report.Feedback.RequiredActions
 		current = next
 	}
 
@@ -761,11 +766,19 @@ func nextStepsText(routes []workflow.Route) string {
 }
 
 func renderSummaryReport(r workflow.Report) string {
+	if r.Summary.Commits == workflow.None && r.Summary.NotCompleted == workflow.None &&
+		r.Summary.IssuesDiscovered == workflow.None && r.Summary.Verification == workflow.None && r.Summary.Notes == workflow.None {
+		return r.Summary.Completed
+	}
 	return fmt.Sprintf("COMPLETED:\n%s\n\nCOMMITS:\n%s\n\nNOT COMPLETED:\n%s\n\nISSUES DISCOVERED:\n%s\n\nVERIFICATION:\n%s\n\nNOTES:\n%s",
 		r.Summary.Completed, r.Summary.Commits, r.Summary.NotCompleted, r.Summary.IssuesDiscovered, r.Summary.Verification, r.Summary.Notes)
 }
 
 func renderFeedbackReport(r workflow.Report) string {
+	if r.Summary.Commits == workflow.None && r.Feedback.ReasonForNextStep == workflow.None &&
+		r.Feedback.RelevantContext == workflow.None && r.Feedback.ExpectedResult == workflow.None {
+		return r.Feedback.RequiredActions
+	}
 	return fmt.Sprintf("COMMITS:\n%s\n\nREASON FOR NEXT STEP:\n%s\n\nREQUIRED ACTIONS:\n%s\n\nRELEVANT CONTEXT:\n%s\n\nEXPECTED RESULT:\n%s",
 		r.Summary.Commits, r.Feedback.ReasonForNextStep, r.Feedback.RequiredActions, r.Feedback.RelevantContext, r.Feedback.ExpectedResult)
 }

package/internal/execution/goworkflows/mailbox_test.go

@@ -41,6 +41,33 @@ func threeNodeWorkflow() workflow.Workflow {
 	}
 }
 
+func TestCompactMailboxTemplateDoesNotAppendGenericInstructions(t *testing.T) {
+	wf := threeNodeWorkflow()
+	sys := newFakeTaskSystem(newEventLog())
+	sys.renderText = func(_ task.TextKind, data task.TextData) (string, error) {
+		return data.Ticket + " / " + data.Node + " — " + data.NodeType + " — " + data.Agent +
+			"\n" + data.NodeDescription + "\nSuccess routes:\n" + data.SuccessRoutes +
+			"\nFailure routes:\n" + data.FailureRoutes + "\n" + data.Report, nil
+	}
+	specs, err := goworkflows.RenderMailboxSpecs(sys, run.Work{
+		Parent: task.TicketRef{Key: "PAY-101"}, Repo: "payments", Workflow: wf.Name,
+	}, &wf)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, spec := range specs {
+		for _, required := range []string{"PAY-101 / " + spec.Node, wf.Nodes[spec.Node].Description,
+			"Success routes:", "Failure routes:", " — when: ", workflow.ReportFormat} {
+			if !strings.Contains(spec.Description, required) {
+				t.Fatalf("mailbox %s description lacks %q: %q", spec.Node, required, spec.Description)
+			}
+		}
+		if strings.Contains(spec.Description, "Required report format:") {
+			t.Fatalf("mailbox %s appended generic instructions: %q", spec.Node, spec.Description)
+		}
+	}
+}
+
 func TestMailboxesEnsuredForWorkNodesOnly(t *testing.T) {
 	log := newEventLog()
 	sys := newFakeTaskSystem(log)
@@ -107,7 +134,7 @@ func TestMailboxesEnsuredForWorkNodesOnly(t *testing.T) {
 				t.Fatalf("%s description lacks route explanation %q: %q", node, when, d)
 			}
 		}
-		for _, required := range []string{"Required report format:", "STATUS:", "COMMITS:", "FEEDBACK:"} {
+		for _, required := range []string{"Required report format:", "STATUS:", "NEXT STEP:", "SUMMARY:", "FEEDBACK:"} {
 			if !strings.Contains(d, required) {
 				t.Fatalf("%s description lacks %q: %q", node, required, d)
 			}

package/internal/execution/temporal/activities.go

@@ -85,7 +85,11 @@ func (a *Activities) EnsureMailboxes(ctx context.Context, w run.Work, specs []ta
 		if err != nil {
 			return nil, fmt.Errorf("render mailbox %q description: %w", specs[i].Node, err)
 		}
-		specs[i].Description = appendText(custom, specs[i].Description)
+		if data.Report != "" && strings.Contains(custom, data.Report) {
+			specs[i].Description = custom
+		} else {
+			specs[i].Description = appendText(custom, specs[i].Description)
+		}
 	}
 	return sys.EnsureMailboxes(ctx, w.Parent, w.Workflow, specs)
 }
@@ -486,26 +490,9 @@ func MailboxSpecForNode(wf *workflow.Workflow, ticketKey, name string, n workflo
 	var b strings.Builder
 	b.WriteString(`Required report format:
 
-STATUS: success | failure
-NEXT STEP: <one valid node name>
-
-SUMMARY:
-COMPLETED:
-COMMITS:
-NOT COMPLETED:
-ISSUES DISCOVERED:
-VERIFICATION:
-NOTES:
-
-FEEDBACK:
-REASON FOR NEXT STEP:
-REQUIRED ACTIONS:
-RELEVANT CONTEXT:
-EXPECTED RESULT:
+` + workflow.ReportFormat + `
 
-Every field is required; use None for an intentionally empty section. COMMITS must contain the relevant commit IDs or None.
-
-Node names identify workflow stages; they are not task-system statuses. STATUS describes whether the work at this node succeeded or failed, not the status of the parent or mailbox. NEXT STEP must name exactly one target listed below for that STATUS. Submit one report only: its SUMMARY is written to this current mailbox, while its FEEDBACK is written only to the selected next node's mailbox. For review nodes, put requested changes in FEEDBACK and select the node responsible for acting on them. Relay-flow and the task system own parent and mailbox status changes. When NEXT STEP is end, every FEEDBACK field must be None.`)
+Node names identify workflow stages; they are not task-system statuses. STATUS describes whether the work at this node succeeded or failed, not the status of the parent or mailbox. NEXT STEP must name exactly one target listed below for that STATUS. Submit one report only: its SUMMARY is written to this current mailbox, while its FEEDBACK is written only to the selected next node's mailbox. For review nodes, put requested changes in FEEDBACK and select the node responsible for acting on them. Relay-flow and the task system own parent and mailbox status changes. When NEXT STEP is end, FEEDBACK must be None.`)
 	writeRoutes := func(label string, routes []workflow.Route) {
 		if len(routes) == 0 {
 			return
@@ -533,7 +520,7 @@ Node names identify workflow stages; they are not task-system statuses. STATUS d
 			Agent: n.Agent, NodeDescription: n.Description,
 			NextSteps:     nextStepsText(append(append([]workflow.Route{}, n.OnSuccess...), n.OnFailure...)),
 			SuccessRoutes: successRoutes, FailureRoutes: failureRoutes,
-			Mailbox: ticketKey + ":" + name,
+			Mailbox: ticketKey + ":" + name, Report: workflow.ReportFormat,
 		},
 	}
 }
@@ -567,7 +554,11 @@ func RenderMailboxSpecs(sys task.System, w run.Work, wf *workflow.Workflow) ([]t
 		if err != nil {
 			return nil, fmt.Errorf("render mailbox %q description: %w", specs[i].Node, err)
 		}
-		specs[i].Description = appendText(custom, specs[i].Description)
+		if data.Report != "" && strings.Contains(custom, data.Report) {
+			specs[i].Description = custom
+		} else {
+			specs[i].Description = appendText(custom, specs[i].Description)
+		}
 	}
 	return specs, nil
 }