Add Workflow

Step 7: Implement the Graph Builder in service.go

The previous step generated a placeholder graph builder func (svc *Service) MyWorkflow(ctx context.Context) (graph *workflow.Graph, err error) in service.go, tagged // MARKER: MyWorkflow, with a graph = workflow.NewGraph("MyWorkflow") starter that returns an empty graph (which fails validation until you define it). Build out the graph with the workflow.NewGraph builder API, referencing task endpoints from this or other microservices by their URL() method. Leave the generated godoc as it is.

Each node in the graph carries both a short name (used in transitions) and a URL (used to dispatch the task at runtime). Register nodes with graph.SetEndpoint("Name", taskURL), then write transitions in terms of names. Use PascalCase node names matching the task endpoint (e.g. "TaskA" for TaskA) - they are graph-topology identifiers, kept visually distinct from the lowercased dispatch URLs and the camelCase state field names. The graph display name passed to NewGraph is PascalCase too (conventionally the workflow's own name). Child workflows are not graph nodes; they are launched dynamically from a task body via flow.Subgraph(childWorkflow.URL(), input) - see the "Subgraphs and Interrupts" section in .claude/rules/workflows.txt.

// MyWorkflow does X.
func (svc *Service) MyWorkflow(ctx context.Context) (graph *workflow.Graph, err error) { // MARKER: MyWorkflow
	graph = workflow.NewGraph("MyWorkflow")
	graph.SetEndpoint("TaskA", myserviceapi.TaskA.URL())
	graph.SetEndpoint("TaskB", myserviceapi.TaskB.URL())
	graph.SetEndpoint("TaskC", myserviceapi.TaskC.URL())
	// graph.AddTransition("TaskA", "TaskB")
	// graph.AddTransitionSwitch("TaskB", "TaskC", "score >= 50") // first-match-wins routing; end with a "true" arm for the default
	// graph.AddTransitionSwitch("TaskB", workflow.END, "true")
	// graph.AddTransitionGoto("TaskB", "TaskC")
	return graph, nil
}

If a subgraph call needs its input or output adapted across a contract boundary, do it in any ordinary task immediately upstream or downstream of the subgraph using flow.Del/flow.Clear - see the "State Transformation Around a Subgraph" section in .claude/rules/workflows.txt. If the workflow's terminal state needs scrubbing before it lands in final_state, the last task calls flow.Del.

Naming the same task URL twice with different names is the supported way to reuse a task at multiple positions in the graph (each position keeps its own node identity for fan-in tracking).

Every fan-out requires a matching fan-in. Any node with two or more normal outgoing transitions, or an AddTransitionForEach transition, is a fan-out: its branches run in parallel. Every fan-out must converge on a single node that you mark with graph.SetFanIn("name"). Add the SetFanIn call in the same edit as the fan-out transitions, and route every parallel branch into the marked node before the graph reaches workflow.END. A graph that fans out without a SetFanIn node still compiles and passes go vet, but graph.Validate() (run by the generated marshaler) rejects it at run time, so the test in Step 8 fails. This is the single most common workflow-graph mistake. The fan-out/fan-in section in .claude/rules/workflows.txt has the full rule and a worked example.

Reducers for fan-in fields. When parallel branches converge, each field that needs anything other than last-write-wins must be explicitly wired with graph.SetReducer(field, reducer) at graph-build time. Fields without a registered reducer use Replace (last write wins). No name-driven inference - a field named messages and a field named total are treated identically until SetReducer says otherwise.

graph.SetReducer("messages", workflow.ReducerAppend) // accumulate per-branch deltas
graph.SetReducer("total",    workflow.ReducerAdd)    // sum numeric contributions
graph.SetReducer("seen",     workflow.ReducerUnion)  // dedupe across branches
graph.SetReducer("attrs",    workflow.ReducerMerge)  // merge per-branch objects
graph.SetReducer("approved", workflow.ReducerAnd)    // all branches must approve
graph.SetReducer("flagged",  workflow.ReducerOr)     // any branch flags
graph.SetReducer("notes",    workflow.ReducerConcat) // join string deltas

Pick the reducer by what the merge means, not by what the field is named. The default Replace is correct when only one branch ever writes the field.

Prefer AddTransitionSwitch > AddTransitionWhen > AddTransitionGoto for branching. AddTransitionSwitch is the default for any routing where exactly one branch should run: siblings are first-match-wins in declaration order (use when="true" as the last arm for a default), the validator enforces mutual exclusivity, and no SetFanIn is needed because only one branch ever fires. Drop to AddTransitionWhen only when the source genuinely fans out under multiple independent predicates that may all match - that's parallel work, not routing, and it needs a matching SetFanIn. Two When predicates meant to be mutually exclusive (x>0 and x<=0) should be a Switch so the validator enforces it. Reserve AddTransitionGoto for runtime control-flow the task body decides via flow.Goto, the canonical case being a fan-in node looping back ("ask for more info, retry the review"). The "Switch Transitions" and "When to choose Switch vs. When vs. Goto" sections in .claude/rules/workflows.txt carry the full rules.

To embed this workflow as a subgraph from inside another task body, use the generated Subgraph client (otherapi.NewSubgraph(flow).MyWorkflow(ctx, ...)), never the Executor - the Executor is test-only.

Step 8: Test the Workflow

Skip this step if instructed to be "quick" or to skip tests.

The boilerplate generator created a placeholder test function TestMyService_MyWorkflow in service_test.go, tagged with a // MARKER: MyWorkflow comment and a HINT block. Add one or more test cases at the bottom of that function, following the pattern shown in its HINT comment. Do not remove the HINT comment.

If the feature or microservice cannot or should not be tested - for example, it starts a daemon or requires a resource unavailable in the test environment - do not delete the generated test. The generator keys on the test function's name and would scaffold it again on the next regeneration. Instead, replace the entire body of the test with a t.Skip("reason") explaining why.

Step 9: Housekeeping

Follow the housekeeping skill.