relay-flow 0.3.10-alpha → 0.3.11-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.11-alpha
 ```
 
 **Pi**
 
 ```sh
-pi install npm:relay-flow-plugin@0.3.10-alpha
+pi install npm:relay-flow-plugin@0.3.11-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.11-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.11-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.11-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

@@ -23,6 +23,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"
@@ -386,6 +387,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 +410,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 +487,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 +535,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

@@ -664,6 +664,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 {

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_test.go

@@ -72,13 +72,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)
 		}
 	}
@@ -467,6 +470,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 +489,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 +514,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
 }

package/internal/execution/temporal/compact_mailbox_test.go

@@ -0,0 +1,56 @@
+package temporal
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/run"
+	"github.com/rajpopat27/relay-flow/internal/task"
+	"github.com/rajpopat27/relay-flow/internal/workflow"
+)
+
+type compactMailboxRenderer struct{ *lagTaskSystem }
+
+func (*compactMailboxRenderer) RenderText(_ 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
+}
+
+func TestCompactMailboxTemplateDoesNotAppendGenericInstructions(t *testing.T) {
+	wf := workflow.Workflow{Name: "test", Nodes: map[string]workflow.Node{
+		"coder": {Type: workflow.NodeAgent, Agent: "coder", Description: "Implement", OnSuccess: []workflow.Route{{Target: "end"}}},
+	}}
+	specs, err := RenderMailboxSpecs(&compactMailboxRenderer{&lagTaskSystem{}}, run.Work{
+		Parent: task.TicketRef{Key: "PAY-101"}, Repo: "payments", Workflow: wf.Name,
+	}, &wf)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(specs) != 1 {
+		t.Fatalf("compact mailbox descriptions = %+v", specs)
+	}
+	for _, required := range []string{"PAY-101 / coder — agent — coder", "Implement", "Success routes:\nend", "Failure routes:", workflow.ReportFormat} {
+		if !strings.Contains(specs[0].Description, required) {
+			t.Fatalf("mailbox description lacks %q: %q", required, specs[0].Description)
+		}
+	}
+	if strings.Contains(specs[0].Description, "Required report format:") {
+		t.Fatalf("generic instructions appended to Jira template: %q", specs[0].Description)
+	}
+}
+
+func TestConciseReportRendersOnlySelectedSummaryAndFeedback(t *testing.T) {
+	r := workflow.Report{
+		Summary: workflow.Summary{Completed: "done", Commits: workflow.None, NotCompleted: workflow.None,
+			IssuesDiscovered: workflow.None, Verification: workflow.None, Notes: workflow.None},
+		Feedback: workflow.Feedback{ReasonForNextStep: workflow.None, RequiredActions: "review it",
+			RelevantContext: workflow.None, ExpectedResult: workflow.None},
+	}
+	if got := renderSummaryReport(r); got != "done" {
+		t.Fatalf("summary comment = %q", got)
+	}
+	if got := renderFeedbackReport(r); got != "review it" {
+		t.Fatalf("feedback comment = %q", got)
+	}
+}

package/internal/execution/temporal/interpreter.go

@@ -342,6 +342,7 @@ func runGraph(ctx temporalworkflow.Context, start run.Start, state *workflowStat
 	state.upsertStep(startStep)
 
 	current := target
+	previousFeedback := ""
 	lastStepByNode := map[string]int64{}
 	lastDepthByNode := map[string]int{}
 	for current != "end" {
@@ -407,7 +408,7 @@ func runGraph(ctx temporalworkflow.Context, start run.Start, state *workflowStat
 			PromptData: harness.PromptData{
 				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: mailbox.Key,
+				NextSteps: nextStepsText(nextSteps), Mailbox: mailbox.Key, PreviousFeedback: previousFeedback,
 			},
 			NextSteps: nextSteps,
 		}
@@ -516,7 +517,9 @@ func runGraph(ctx temporalworkflow.Context, start run.Start, state *workflowStat
 		stepMessage := accepted.Report.Summary.Completed
 		if accepted.Report.Status == domainworkflow.OutcomeFailure {
 			stepStatus = run.StepFailed
-			stepMessage = accepted.Report.Summary.IssuesDiscovered
+			if accepted.Report.Summary.IssuesDiscovered != domainworkflow.None {
+				stepMessage = accepted.Report.Summary.IssuesDiscovered
+			}
 		}
 		stepFinished := temporalworkflow.Now(ctx).UTC()
 		step.Status, step.FinishedAt, step.Message, step.Route = stepStatus, &stepFinished, stepMessage, accepted.Report.NextStep
@@ -569,6 +572,7 @@ func runGraph(ctx temporalworkflow.Context, start run.Start, state *workflowStat
 			return err
 		}
 		applyRuntimePolicy(state, current, work.Runtime)
+		previousFeedback = accepted.Report.Feedback.RequiredActions
 		current = next
 	}
 
@@ -859,11 +863,19 @@ func applyRuntimePolicy(state *workflowState, node string, policy run.RuntimePol
 }
 
 func renderSummaryReport(r domainworkflow.Report) string {
+	if r.Summary.Commits == domainworkflow.None && r.Summary.NotCompleted == domainworkflow.None &&
+		r.Summary.IssuesDiscovered == domainworkflow.None && r.Summary.Verification == domainworkflow.None && r.Summary.Notes == domainworkflow.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 domainworkflow.Report) string {
+	if r.Summary.Commits == domainworkflow.None && r.Feedback.ReasonForNextStep == domainworkflow.None &&
+		r.Feedback.RelevantContext == domainworkflow.None && r.Feedback.ExpectedResult == domainworkflow.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/harness/harness.go

@@ -24,20 +24,32 @@ const (
 	PromptFeedback PromptKind = "feedback"
 )
 
+// Jira prompt defaults keep each agent read limited to the relevant mailbox.
+// A node that needs its parent's details can request the optional parent-read
+// instruction in its node description.
+const JiraInitialPrompt = `Read the description of your assigned Jira task:
+acli jira workitem view "{{mailbox}}" --fields "summary,description" --json
+
+Follow the work instructions, valid routes, and report format in that description.`
+
+const JiraFeedbackPrompt = `Continue {{node}} from the latest update on your assigned Jira task:
+acli jira workitem comment list --key "{{mailbox}}" --limit 1 --order "-created" --json`
+
 // PromptData is the task-system-neutral data core supplies to the selected
 // harness. Harness templates, including HITL instructions, are rendered only
 // by the harness.
 type PromptData struct {
-	TaskSystem      string
-	Ticket          string
-	Workflow        string
-	Repo            string
-	Node            string
-	NodeType        workflow.NodeType
-	Agent           string
-	NodeDescription string
-	NextSteps       string
-	Mailbox         string
+	TaskSystem       string
+	Ticket           string
+	Workflow         string
+	Repo             string
+	Node             string
+	NodeType         workflow.NodeType
+	Agent            string
+	NodeDescription  string
+	NextSteps        string
+	Mailbox          string
+	PreviousFeedback string
 }
 
 type LaunchSpec struct {

package/internal/harness/opencode/opencode.go

@@ -137,23 +137,35 @@ func (h *Harness) FindSession(context.Context, string, string) (harness.Session,
 	return harness.Session{}, false, nil
 }
 
-// RenderPrompt renders the selected session prompt, appends the harness-owned
-// HITL/TUI instructions for HITL nodes, then renders and appends the node's
-// nudge template.
+// RenderPrompt renders the selected session prompt and HITL instructions.
+// Jira first launches omit the node nudge so the initial read stays limited
+// to the assigned mailbox description.
 func (h *Harness) RenderPrompt(kind harness.PromptKind, data harness.PromptData, nudgeTemplate string) (string, error) {
 	var tmpl string
 	switch kind {
 	case harness.PromptInitial:
 		tmpl = h.templates.Initial
+		if data.TaskSystem == "jira" && tmpl == defaultInitialPrompt {
+			tmpl = harness.JiraInitialPrompt
+		}
 	case harness.PromptFeedback:
 		tmpl = h.templates.Feedback
+		if data.TaskSystem == "jira" && tmpl == defaultFeedbackPrompt {
+			tmpl = harness.JiraFeedbackPrompt
+		}
 	default:
 		return "", fmt.Errorf("opencode: unknown prompt kind %q", kind)
 	}
 	prompt := renderTemplate(tmpl, data)
-	if data.NodeType == workflow.NodeHITL {
+	if data.TaskSystem == "jira" && data.PreviousFeedback != "" {
+		prompt = appendPrompt(prompt, "Previous step feedback: "+data.PreviousFeedback)
+	}
+	if data.NodeType == workflow.NodeHITL && (data.TaskSystem != "jira" || h.templates.HITL != defaultHITLPrompt) {
 		prompt = appendPrompt(prompt, renderTemplate(h.templates.HITL, data))
 	}
+	if kind == harness.PromptInitial && data.TaskSystem == "jira" {
+		return prompt, nil
+	}
 	return appendPrompt(prompt, renderTemplate(nudgeTemplate, data)), nil
 }
 
@@ -204,6 +216,7 @@ func (h *Harness) BuildCommand(spec harness.LaunchSpec) (runner.Command, error)
 		"RELAY_FLOW_NODE_TYPE":       string(spec.NodeType),
 		"RELAY_FLOW_NUDGE_PROMPT":    spec.NudgePrompt,
 		"RELAY_FLOW_NEXT_STEPS_JSON": string(nextSteps),
+		"RELAY_FLOW_REPORT_FORMAT":   workflow.ReportFormat,
 	} {
 		env[key] = value
 	}

package/internal/harness/opencode/opencode_test.go

@@ -14,7 +14,7 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/workflow"
 )
 
-const configuredPlugin = "relay-flow-plugin@0.3.10-alpha"
+const configuredPlugin = "relay-flow-plugin@0.3.11-alpha"
 
 func TestBuildCommandArgv(t *testing.T) {
 	t.Setenv("RELAY_FLOW_HOME", "/var/lib/relay-flow-test")
@@ -105,6 +105,30 @@ func TestRenderPromptTemplatesExposeAllValues(t *testing.T) {
 	}
 }
 
+func TestJiraDefaultPromptsUseOnlyMailboxReadsAndSelectedFeedback(t *testing.T) {
+	h := opencode.New()
+	data := harness.PromptData{
+		TaskSystem: "jira", Ticket: "PAY-101", Mailbox: "PAY-234", Node: "coder", NodeType: workflow.NodeHITL,
+	}
+	initial, err := h.RenderPrompt(harness.PromptInitial, data, "Read the latest mailbox feedback.")
+	if err != nil {
+		t.Fatal(err)
+	}
+	wantInitial := "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 initial != wantInitial {
+		t.Fatalf("Jira initial prompt = %q, want %q", initial, wantInitial)
+	}
+	data.PreviousFeedback = "Review found a missing test; add it."
+	continuation, err := h.RenderPrompt(harness.PromptFeedback, data, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	wantContinuation := "Continue coder from the latest update on your assigned Jira task:\nacli jira workitem comment list --key \"PAY-234\" --limit 1 --order \"-created\" --json\n\nPrevious step feedback: Review found a missing test; add it."
+	if continuation != wantContinuation {
+		t.Fatalf("Jira continuation = %q, want %q", continuation, wantContinuation)
+	}
+}
+
 func TestHarnessConfigRejectsUnknownPromptVariable(t *testing.T) {
 	_, err := harness.New("opencode", config.RawValues{"initial": "{{unknown}}"})
 	if err == nil || !strings.Contains(err.Error(), "unknown template variable {{unknown}}") {

package/internal/harness/opencode/repo_setup.go

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

package/internal/harness/opencode/task_env_test.go

@@ -51,7 +51,7 @@ func TestBuildCommandWithoutTaskEnvKeepsRelayVariablesOnly(t *testing.T) {
 	if err != nil {
 		t.Fatalf("BuildCommand: %v", err)
 	}
-	if len(cmd.Env) != 9 {
-		t.Fatalf("Env = %#v, want only the nine relay-flow variables", cmd.Env)
+	if len(cmd.Env) != 10 {
+		t.Fatalf("Env = %#v, want only the ten relay-flow variables", cmd.Env)
 	}
 }

package/internal/harness/pi/pi.go

@@ -150,7 +150,7 @@ func (*Harness) FindSession(context.Context, string, string) (harness.Session, b
 }
 
 // RenderPrompt renders the selected initial or feedback template and the
-// node's nudge template. Initial prompts use Pi's native prompt-template
+// node's nudge template (except on a Jira first launch). Initial prompts use Pi's native prompt-template
 // command syntax; feedback is sent to an existing session and must remain
 // raw so Pi does not expand the full prompt template again. HITL approval is
 // not encoded in the prompt; the Pi extension asks for approval through
@@ -160,8 +160,14 @@ func (h *Harness) RenderPrompt(kind harness.PromptKind, data harness.PromptData,
 	switch kind {
 	case harness.PromptInitial:
 		tmpl = h.templates.Initial
+		if data.TaskSystem == "jira" && tmpl == defaultInitialPrompt {
+			tmpl = harness.JiraInitialPrompt
+		}
 	case harness.PromptFeedback:
 		tmpl = h.templates.Feedback
+		if data.TaskSystem == "jira" && tmpl == defaultFeedbackPrompt {
+			tmpl = harness.JiraFeedbackPrompt
+		}
 	default:
 		return "", fmt.Errorf("pi: unknown prompt kind %q", kind)
 	}
@@ -170,7 +176,13 @@ func (h *Harness) RenderPrompt(kind harness.PromptKind, data harness.PromptData,
 			return "", err
 		}
 	}
-	prompt := appendPrompt(renderTemplate(tmpl, data), renderTemplate(nudgeTemplate, data))
+	prompt := renderTemplate(tmpl, data)
+	if data.TaskSystem == "jira" && data.PreviousFeedback != "" {
+		prompt = appendPrompt(prompt, "Previous step feedback: "+data.PreviousFeedback)
+	}
+	if kind != harness.PromptInitial || data.TaskSystem != "jira" {
+		prompt = appendPrompt(prompt, renderTemplate(nudgeTemplate, data))
+	}
 	if kind == harness.PromptInitial {
 		return applyPromptTemplate(data.Agent, prompt), nil
 	}
@@ -213,6 +225,7 @@ func (*Harness) BuildCommand(spec harness.LaunchSpec) (runner.Command, error) {
 		"RELAY_FLOW_NODE_TYPE":       string(spec.NodeType),
 		"RELAY_FLOW_NUDGE_PROMPT":    spec.NudgePrompt,
 		"RELAY_FLOW_NEXT_STEPS_JSON": string(nextSteps),
+		"RELAY_FLOW_REPORT_FORMAT":   workflow.ReportFormat,
 	} {
 		env[key] = value
 	}

package/internal/harness/pi/pi_test.go

@@ -42,6 +42,7 @@ func TestBuildCommandUsesStrictPiCLIContract(t *testing.T) {
 		"RELAY_FLOW_NODE_TYPE":       string(base.NodeType),
 		"RELAY_FLOW_NUDGE_PROMPT":    base.NudgePrompt,
 		"RELAY_FLOW_NEXT_STEPS_JSON": string(nextSteps),
+		"RELAY_FLOW_REPORT_FORMAT":   workflow.ReportFormat,
 	}
 
 	tests := []struct {
@@ -248,13 +249,13 @@ func runStrictPi(t *testing.T, command runner.Command, cwd, capturePath string)
 		t.Fatalf("read strict Pi capture: %v", err)
 	}
 	fields := strings.Split(string(data), "\x00")
-	if len(fields) < 12 || fields[len(fields)-1] != "" {
+	if len(fields) < 13 || fields[len(fields)-1] != "" {
 		t.Fatalf("malformed strict Pi capture: %q", data)
 	}
 	fields = fields[:len(fields)-1]
 	capture := piCapture{
 		cwd:  fields[0],
-		args: strings.Split(fields[10], "\x1f"),
+		args: strings.Split(fields[11], "\x1f"),
 		env: map[string]string{
 			"RELAY_FLOW_HOME":            fields[1],
 			"RELAY_FLOW_RUN_ID":          fields[2],
@@ -265,6 +266,7 @@ func runStrictPi(t *testing.T, command runner.Command, cwd, capturePath string)
 			"RELAY_FLOW_NODE_TYPE":       fields[7],
 			"RELAY_FLOW_NUDGE_PROMPT":    fields[8],
 			"RELAY_FLOW_NEXT_STEPS_JSON": fields[9],
+			"RELAY_FLOW_REPORT_FORMAT":   fields[10],
 		},
 	}
 	return capture
@@ -325,11 +327,12 @@ fi
 [ -n "${RELAY_FLOW_NODE:-}" ] || exit 3
 [ -n "${RELAY_FLOW_NODE_TYPE:-}" ] || exit 3
 [ -n "${RELAY_FLOW_NEXT_STEPS_JSON:-}" ] || exit 3
+[ -n "${RELAY_FLOW_REPORT_FORMAT:-}" ] || exit 3
 
-printf '%s\000%s\000%s\000%s\000%s\000%s\000%s\000%s\000%s\000%s\000%s\000' \
+printf '%s\000%s\000%s\000%s\000%s\000%s\000%s\000%s\000%s\000%s\000%s\000%s\000' \
   "$PWD" "$RELAY_FLOW_HOME" "$RELAY_FLOW_RUN_ID" "$RELAY_FLOW_WORKFLOW" \
   "$RELAY_FLOW_REPO" "$RELAY_FLOW_TICKET" "$RELAY_FLOW_NODE" "$RELAY_FLOW_NODE_TYPE" \
-  "${RELAY_FLOW_NUDGE_PROMPT:-}" "$RELAY_FLOW_NEXT_STEPS_JSON" "$original_args" > "$capture"
+  "${RELAY_FLOW_NUDGE_PROMPT:-}" "$RELAY_FLOW_NEXT_STEPS_JSON" "$RELAY_FLOW_REPORT_FORMAT" "$original_args" > "$capture"
 `
 	if err := os.WriteFile(executable, []byte(script), 0o700); err != nil {
 		t.Fatal(err)

package/internal/harness/pi/prompt_test.go

@@ -29,7 +29,7 @@ func TestPiRenderPromptSubstitutesInitialAndFeedbackData(t *testing.T) {
 	if err != nil {
 		t.Fatalf("RenderPrompt(initial): %v", err)
 	}
-	wantInitial := "Task system: jira\nUse the jira 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\nnudge jira|PAY-101|basicFlow|payments|implement|PAY-234|review (when: ready)"
+	wantInitial := "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 initial != wantInitial {
 		t.Fatalf("initial prompt = %q, want %q", initial, wantInitial)
 	}
@@ -38,10 +38,18 @@ func TestPiRenderPromptSubstitutesInitialAndFeedbackData(t *testing.T) {
 	if err != nil {
 		t.Fatalf("RenderPrompt(feedback): %v", err)
 	}
-	wantFeedback := "New feedback was added to the comments section of your mailbox subtask PAY-234. Read it.\n\nnudge jira|PAY-101|basicFlow|payments|implement|PAY-234|review (when: ready)"
+	wantFeedback := "Continue implement from the latest update on your assigned Jira task:\nacli jira workitem comment list --key \"PAY-234\" --limit 1 --order \"-created\" --json\n\nnudge jira|PAY-101|basicFlow|payments|implement|PAY-234|review (when: ready)"
 	if feedback != wantFeedback {
 		t.Fatalf("feedback prompt = %q, want %q", feedback, wantFeedback)
 	}
+	data.PreviousFeedback = "Add the missing test."
+	continued, err := h.RenderPrompt(harness.PromptFeedback, data, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if want := "Continue implement from the latest update on your assigned Jira task:\nacli jira workitem comment list --key \"PAY-234\" --limit 1 --order \"-created\" --json\n\nPrevious step feedback: Add the missing test."; continued != want {
+		t.Fatalf("Jira Pi continuation = %q, want %q", continued, want)
+	}
 }
 
 func TestPiRenderPromptHonorsNodeNudgeTimingInput(t *testing.T) {
@@ -107,11 +115,11 @@ func TestPiRenderPromptUsesNativeTemplateCommandForInitialNamedAgent(t *testing.
 		Mailbox:    "PAY-234",
 	}
 
-	initial, err := h.RenderPrompt(harness.PromptInitial, data, "nudge {{node}}")
+	initial, err := h.RenderPrompt(harness.PromptInitial, data, "Read the latest mailbox feedback for {{node}}.")
 	if err != nil {
 		t.Fatalf("RenderPrompt(initial): %v", err)
 	}
-	wantInitial := "/coder Task system: jira\nUse the jira 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\nnudge implement"
+	wantInitial := "/coder 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 initial != wantInitial {
 		t.Fatalf("initial prompt = %q, want %q", initial, wantInitial)
 	}
@@ -120,7 +128,7 @@ func TestPiRenderPromptUsesNativeTemplateCommandForInitialNamedAgent(t *testing.
 	if err != nil {
 		t.Fatalf("RenderPrompt(feedback): %v", err)
 	}
-	wantFeedback := "New feedback was added to the comments section of your mailbox subtask PAY-234. Read it.\n\nfeedback nudge"
+	wantFeedback := "Continue implement from the latest update on your assigned Jira task:\nacli jira workitem comment list --key \"PAY-234\" --limit 1 --order \"-created\" --json\n\nfeedback nudge"
 	if feedback != wantFeedback {
 		t.Fatalf("feedback prompt = %q, want %q", feedback, wantFeedback)
 	}

package/internal/harness/pi/task_env_test.go

@@ -61,7 +61,7 @@ func TestBuildCommandWithoutTaskEnvKeepsRelayVariablesOnly(t *testing.T) {
 	if err != nil {
 		t.Fatalf("BuildCommand: %v", err)
 	}
-	if len(cmd.Env) != 9 {
-		t.Fatalf("Env = %#v, want only the nine relay-flow variables", cmd.Env)
+	if len(cmd.Env) != 10 {
+		t.Fatalf("Env = %#v, want only the ten relay-flow variables", cmd.Env)
 	}
 }

package/internal/task/jira/jira.go

@@ -66,17 +66,16 @@ const (
 	defaultWorkTaskStatus     = "In Progress"
 	defaultEndParentStatus    = "Done"
 	currentUserAssigneeFilter = "currentUser()"
-	defaultMailboxDescription = `Parent ticket: {{ticket}}
-Workflow: {{workflow}}
-Node: {{node}}
-Node type: {{nodeType}}
-Agent: {{agent}}
-Mailbox: {{mailbox}}
-
-Node work:
+	defaultMailboxDescription = `{{ticket}} / {{node}} — {{nodeType}} — {{agent}}
 {{nodeDescription}}
 
-Read this mailbox's comments for feedback from previous nodes.`
+Success routes:
+{{successRoutes}}
+
+Failure routes:
+{{failureRoutes}}
+
+{{report}}`
 	defaultSummaryComment = `Summary for {{node}}
 
 {{summaryReport}}`
@@ -93,6 +92,7 @@ var knownTextVars = map[string]bool{
 	"nodeDescription": true, "nextSteps": true, "successRoutes": true,
 	"failureRoutes": true, "mailbox": true, "sourceNode": true,
 	"targetNode": true, "summaryReport": true, "feedbackReport": true,
+	"report": true,
 }
 
 // DefaultConfig supplies Jira task-system text defaults for relay-flow init.
@@ -509,6 +509,11 @@ func validateTemplates(templates Templates) error {
 			}
 		}
 	}
+	for _, key := range []string{"report", "ticket", "node", "nodeType", "agent", "nodeDescription", "successRoutes", "failureRoutes"} {
+		if !strings.Contains(templates.MailboxDescription, "{{"+key+"}}") {
+			return fmt.Errorf("mailboxDescription must contain {{%s}}", key)
+		}
+	}
 	if !strings.Contains(templates.SummaryComment, "{{summaryReport}}") {
 		return fmt.Errorf("summaryComment must contain {{summaryReport}}")
 	}
@@ -535,11 +540,11 @@ func (s *system) RenderText(kind task.TextKind, data task.TextData) (string, err
 		"runID": data.RunID, "ticket": data.Ticket,
 		"workflow": data.Workflow, "repo": data.Repo, "node": data.Node,
 		"nodeType": data.NodeType, "agent": data.Agent,
-		"nodeDescription": data.NodeDescription, "nextSteps": data.NextSteps,
+		"nodeDescription": strings.ReplaceAll(data.NodeDescription, "{{ticket}}", data.Ticket), "nextSteps": data.NextSteps,
 		"successRoutes": data.SuccessRoutes, "failureRoutes": data.FailureRoutes,
 		"mailbox": data.Mailbox, "sourceNode": data.SourceNode,
 		"targetNode": data.TargetNode, "summaryReport": data.SummaryReport,
-		"feedbackReport": data.FeedbackReport,
+		"feedbackReport": data.FeedbackReport, "report": data.Report,
 	}
 	return textVarPattern.ReplaceAllStringFunc(tmpl, func(match string) string {
 		return values[textVarPattern.FindStringSubmatch(match)[1]]

package/internal/task/jira/templates_test.go

@@ -10,6 +10,7 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/config"
 	"github.com/rajpopat27/relay-flow/internal/run"
 	"github.com/rajpopat27/relay-flow/internal/task"
+	"github.com/rajpopat27/relay-flow/internal/workflow"
 )
 
 func TestTaskTextTemplatesExposeValues(t *testing.T) {
@@ -17,7 +18,7 @@ func TestTaskTextTemplatesExposeValues(t *testing.T) {
 	sys, err := newSystem(context.Background(), &fakeClient{fake: fake}, task.RepoSpec{
 		Name: "payments",
 		RootConfig: config.RawValues{"templates": map[string]any{
-			"mailboxDescription": "mailbox {{runID}}|{{ticket}}|{{workflow}}|{{repo}}|{{node}}|{{nodeType}}|{{agent}}|{{nodeDescription}}|{{nextSteps}}|{{successRoutes}}|{{failureRoutes}}|{{mailbox}}",
+			"mailboxDescription": "mailbox {{runID}}|{{ticket}}|{{workflow}}|{{repo}}|{{node}}|{{nodeType}}|{{agent}}|{{nodeDescription}}|{{nextSteps}}|{{successRoutes}}|{{failureRoutes}}|{{mailbox}}|{{report}}",
 			"summaryComment":     "summary {{sourceNode}}|{{targetNode}}|{{mailbox}}\n{{summaryReport}}",
 			"feedbackComment":    "feedback {{sourceNode}}|{{targetNode}}|{{mailbox}}\n{{feedbackReport}}",
 		}},
@@ -31,7 +32,7 @@ func TestTaskTextTemplatesExposeValues(t *testing.T) {
 		Node: "review", NodeType: "hitl", Agent: "reviewer", NodeDescription: "Review changes.",
 		NextSteps: "implement; end", SuccessRoutes: "end", FailureRoutes: "implement",
 		Mailbox: "PAY-3", SourceNode: "review", TargetNode: "implement",
-		SummaryReport: "COMPLETED:\nreviewed", FeedbackReport: "REQUIRED ACTIONS:\nfix it",
+		SummaryReport: "COMPLETED:\nreviewed", FeedbackReport: "REQUIRED ACTIONS:\nfix it", Report: "STATUS: success | failure",
 	}
 	description, err := sys.RenderText(task.TextMailboxDescription, data)
 	if err != nil {
@@ -52,12 +53,47 @@ func TestTaskTextTemplatesExposeValues(t *testing.T) {
 	}
 }
 
+func TestJiraDefaultMailboxDescriptionIsCompact(t *testing.T) {
+	sys, err := newSystem(context.Background(), &fakeClient{fake: &fakeJira{}}, task.RepoSpec{
+		Name: "payments", RepoConfig: testRepoConfig(nil),
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	data := task.TextData{
+		Ticket: "PAY-101", Node: "coder", NodeType: "agent", Agent: "coder",
+		NodeDescription: "Implement the change.", SuccessRoutes: "reviewer — when: ready",
+		FailureRoutes: "coder — when: retry", Report: workflow.ReportFormat,
+	}
+	description, err := sys.RenderText(task.TextMailboxDescription, data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := "PAY-101 / coder — agent — coder\nImplement the change.\n\nSuccess routes:\nreviewer — when: ready\n\nFailure routes:\ncoder — when: retry\n\n" + workflow.ReportFormat
+	if description != want {
+		t.Fatalf("description = %q, want %q", description, want)
+	}
+	if strings.Contains(description, "comment history") {
+		t.Fatal("Jira description requested comment history")
+	}
+	data.NodeDescription = "Read the parent Jira ticket for this step:\nacli jira workitem view \"{{ticket}}\" --fields \"summary,description\" --json"
+	withParent, err := sys.RenderText(task.TextMailboxDescription, data)
+	if err != nil || !strings.Contains(withParent, `acli jira workitem view "PAY-101" --fields "summary,description" --json`) {
+		t.Fatalf("node-specific parent instruction = %q, %v", withParent, err)
+	}
+}
+
 func TestCommentTemplatesRequireReportValues(t *testing.T) {
 	for _, tc := range []struct {
 		name      string
 		override  map[string]any
 		wantError string
 	}{
+		{name: "description", override: map[string]any{"mailboxDescription": "missing"}, wantError: "mailboxDescription must contain {{report}}"},
+		{name: "report only", override: map[string]any{"mailboxDescription": "{{report}}"}, wantError: "mailboxDescription must contain {{ticket}}"},
+		{name: "no node work", override: map[string]any{"mailboxDescription": strings.Replace(defaultMailboxDescription, "{{nodeDescription}}", "No work provided", 1)}, wantError: "mailboxDescription must contain {{nodeDescription}}"},
+		{name: "no success routes", override: map[string]any{"mailboxDescription": strings.Replace(defaultMailboxDescription, "{{successRoutes}}", "None", 1)}, wantError: "mailboxDescription must contain {{successRoutes}}"},
+		{name: "no failure routes", override: map[string]any{"mailboxDescription": strings.Replace(defaultMailboxDescription, "{{failureRoutes}}", "None", 1)}, wantError: "mailboxDescription must contain {{failureRoutes}}"},
 		{name: "summary", override: map[string]any{"summaryComment": "missing"}, wantError: "summaryComment must contain {{summaryReport}}"},
 		{name: "feedback", override: map[string]any{"feedbackComment": "missing"}, wantError: "feedbackComment must contain {{feedbackReport}}"},
 		{name: "unknown", override: map[string]any{"mailboxDescription": "{{mailboxInstructions}}"}, wantError: "unknown template variable {{mailboxInstructions}}"},

package/internal/task/task.go

@@ -70,6 +70,7 @@ type TextData struct {
 	TargetNode      string
 	SummaryReport   string
 	FeedbackReport  string
+	Report          string
 }
 
 type Target struct {

package/internal/workflow/report.go

@@ -9,6 +9,13 @@ import (
 // represents an intentionally empty section.
 const None = "None"
 
+// ReportFormat is the canonical agent-facing contract. Runtime plugins parse
+// these four fields into the existing structured Report wire shape.
+const ReportFormat = `STATUS: success | failure
+NEXT STEP: <one valid route>
+SUMMARY: <concise result>
+FEEDBACK: <concise handoff, or None when NEXT STEP is end>`
+
 type Summary struct {
 	Completed        string `json:"completed"`
 	Commits          string `json:"commits"`

package/package.json

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