@temporal-architect/claude-plugin 0.9.0

package/skills/temporal-architect-author-go/reference/condition.md

@@ -0,0 +1,56 @@
+# condition
+
+## DSL
+
+```twf
+workflow JobCoordinator(config: JobConfig):
+    state:
+        condition jobReady
+
+    # ... later in body:
+    set jobReady
+
+    # ... elsewhere:
+    await jobReady
+```
+
+## Go
+
+```go
+func JobCoordinator(ctx workflow.Context, config JobConfig) error {
+    jobReady := false
+
+    // ... later in body:
+    jobReady = true
+
+    // ... elsewhere:
+    err := workflow.Await(ctx, func() bool { return jobReady })
+    if err != nil {
+        return err
+    }
+}
+```
+
+## Notes
+
+- `condition name` in `state:` → `name := false` (a `bool` variable)
+- `set name` → `name = true`
+- `unset name` → `name = false`
+- `await name` → `workflow.Await(ctx, func() bool { return name })`
+- Conditions in `await one:` become selector cases via a goroutine that awaits the condition and sends to a channel — see the "condition promise" pattern in [await-one.md](./await-one.md)
+
+## Pitfalls
+
+- **Never poll with `workflow.Sleep` in a loop.** Each `Sleep` generates 2 history events (timer-started + timer-fired). A tight polling loop can exhaust the 51,200 event limit and force the workflow into a non-recoverable state. Always use `workflow.Await` — it generates zero history events and re-evaluates on every state transition:
+  ```go
+  // WRONG: polling loop — 2 history events per iteration
+  for !ready {
+      workflow.Sleep(ctx, 5*time.Second)
+  }
+
+  // RIGHT: zero history events, wakes on any state change
+  workflow.Await(ctx, func() bool { return ready })
+  ```
+- **Indefinite blocking.** `workflow.Await` blocks until the condition returns `true`. If the condition is never set (logic bug, missing signal handler, unreachable code path), the workflow hangs indefinitely. Consider using `workflow.AwaitWithTimeout` when a bounded wait is appropriate
+- **Time-based conditions are unreliable.** `workflow.Await(ctx, func() bool { return workflow.Now(ctx).After(deadline) })` may never return — the condition is only re-evaluated on workflow state transitions (signals, activity completions, etc.), not on wall-clock time. Use `workflow.Sleep` or `workflow.NewTimer` for time-based waits
+- `workflow.Await` returns `*CanceledError` if the context is cancelled

package/skills/temporal-architect-author-go/reference/control-flow.md

@@ -0,0 +1,151 @@
+# control flow
+
+## if / else
+
+### DSL
+
+```twf
+if (validated.priority == "high"):
+    activity ExpediteOrder(order)
+else:
+    activity StandardProcessing(order)
+```
+
+### Go
+
+```go
+if validated.Priority == "high" {
+    err := workflow.ExecuteActivity(ctx, ExpediteOrder, order).Get(ctx, nil)
+    if err != nil {
+        return Result{}, err
+    }
+} else {
+    err := workflow.ExecuteActivity(ctx, StandardProcessing, order).Get(ctx, nil)
+    if err != nil {
+        return Result{}, err
+    }
+}
+```
+
+## for (iteration)
+
+### DSL
+
+```twf
+for (item in order.items):
+    activity ProcessItem(item)
+```
+
+### Go
+
+```go
+for _, item := range order.Items {
+    err := workflow.ExecuteActivity(ctx, ProcessItem, item).Get(ctx, nil)
+    if err != nil {
+        return Result{}, err
+    }
+}
+```
+
+## for (conditional)
+
+### DSL
+
+```twf
+for (retries < maxRetries):
+    activity Attempt(data)
+    retries = retries + 1
+```
+
+### Go
+
+```go
+for retries < maxRetries {
+    err := workflow.ExecuteActivity(ctx, Attempt, data).Get(ctx, nil)
+    if err != nil {
+        return Result{}, err
+    }
+    retries++
+}
+```
+
+## for (infinite loop)
+
+### DSL
+
+```twf
+for:
+    # body
+    if (done):
+        break
+```
+
+### Go
+
+```go
+for {
+    // body
+    if done {
+        break
+    }
+}
+```
+
+## switch
+
+### DSL
+
+```twf
+switch (phase):
+    case "draft":
+        # ...
+    case "approved":
+        # ...
+    else:
+        # ...
+```
+
+### Go
+
+```go
+switch phase {
+case "draft":
+    // ...
+case "approved":
+    // ...
+default:
+    // ...
+}
+```
+
+## Notes
+
+- `break` → `break`, `continue` → `continue` — direct mapping
+- DSL `else:` in switch → Go `default:`
+- DSL boolean operators: `and` → `&&`, `or` → `||`, `not` → `!`
+- All condition expressions (`if`, `for`, `switch`) must be deterministic — no `time.Now()`, `rand`, or non-deterministic function calls. See [workflow-def.md](./workflow-def.md) for the full constraint list
+
+## When to use: sequential vs parallel iteration
+
+- **Sequential** (`.Get()` inside loop): each iteration waits for the previous to complete. Use when order matters or when items depend on prior results
+  ```go
+  for _, item := range items {
+      err := workflow.ExecuteActivity(ctx, Process, item).Get(ctx, nil)
+      // blocks here — next iteration starts after this one completes
+  }
+  ```
+- **Parallel** (collect futures, `.Get()` after loop): all iterations start concurrently. Use when items are independent
+  ```go
+  var futures []workflow.Future
+  for _, item := range items {
+      futures = append(futures, workflow.ExecuteActivity(ctx, Process, item))
+  }
+  for _, f := range futures {
+      if err := f.Get(ctx, nil); err != nil { ... }
+  }
+  ```
+- The DSL does not distinguish these — infer from context. If unsure, ask the user
+
+## Pitfalls
+
+- **Manual retry loops** (the `for (retries < max)` pattern) are almost always inferior to SDK `RetryPolicy` on `ActivityOptions`. Use `RetryPolicy` for standard retry logic; reserve manual loops for non-standard control flow (e.g., retry with modified input, conditional retry based on error type)

package/skills/temporal-architect-author-go/reference/dependency-resolution.md

@@ -0,0 +1,29 @@
+# dependency resolution
+
+Scan all activities in the `.twf` and identify external integration points. Most activities are thin wrappers around calls to external systems — the activity itself is simple, but the dependency behind it is not.
+
+## For each activity
+
+- **Categorize:** external API call, storage operation, protocol client, or pure logic
+- **Check existing code:** does the project already have a client/library for this?
+- **Check `go.mod`:** is a relevant SDK already imported?
+- **If unresolved:** suggest specific options with tradeoffs to the user
+- **Read the chosen dependency's API:** identify the method the activity will call, then trace its signature to concrete types. See [types.md](./types.md) for the full resolution strategy
+
+Resolve as many as possible early — it prevents expensive rework later. If a dependency choice is unclear or blocked on another decision, defer it and continue.
+
+## Deliverable
+
+A dependency map, presented to the user for confirmation before generation begins.
+
+A dependency is resolved when you can write the call expression with verified types. The map should include the method, every parameter type, and the return type — all confirmed from `go doc` or source, not inferred from names.
+
+```
+Example dependency map:
+  ChargePayment → stripe-go
+    paymentintent.New(params *stripe.PaymentIntentParams) (*stripe.PaymentIntent, error)
+  SendPaymentConfirmation → sendgrid-go
+    client.SendWithContext(ctx, mail *sgmail.SGMailV3) (*rest.Response, error)
+  LoadOrderRecord → database/sql (no external dependency)
+  CalculateTotal → pure logic (no dependency)
+```

package/skills/temporal-architect-author-go/reference/detach.md

@@ -0,0 +1,52 @@
+# detach
+
+## DSL
+
+```twf
+detach workflow NotifyCustomer(order.customer)
+```
+
+## Go
+
+```go
+childCtx := workflow.WithChildOptions(ctx, workflow.ChildWorkflowOptions{
+    ParentClosePolicy: enumspb.PARENT_CLOSE_POLICY_ABANDON,
+})
+childFuture := workflow.ExecuteChildWorkflow(childCtx, NotifyCustomer, order.Customer)
+// DO NOT skip this — child may silently fail to spawn if parent completes first
+if err := childFuture.GetChildWorkflowExecution().Get(ctx, nil); err != nil {
+    return Result{}, err
+}
+// Do NOT call childFuture.Get() — that waits for completion, defeating detach
+```
+
+## Detach with nexus
+
+### DSL
+
+```twf
+detach nexus NotificationsEndpoint NotificationsService.SendConfirmation(order.customer, paymentResult)
+```
+
+### Go
+
+```go
+c := workflow.NewNexusClient("NotificationsEndpoint", "NotificationsService")
+c.ExecuteOperation(ctx, "SendConfirmation", sendConfirmationInput, workflow.NexusOperationOptions{})
+// No .Get() — fire-and-forget. The operation starts when the schedule command is processed
+```
+
+## Notes
+
+- `detach` = start the child but never wait for its result
+- Set `ParentClosePolicy` to `ABANDON` so the child survives if the parent completes
+- Always call `GetChildWorkflowExecution().Get()` to confirm the child started — without this, the child may never spawn if the parent completes first
+- Do not call `.Get()` on the child workflow future itself (that would wait for completion)
+- The child workflow runs independently and its success/failure does not affect the parent
+- **Nexus fire-and-forget caveat:** omitting `.Get()` is an emergent pattern, not a first-class SDK mode. The caller workflow must not complete before the `ScheduleNexusOperation` command is processed, or the operation may not start. When the handler workflow completes, it attempts a callback to the (already-completed) caller, producing an ignorable error
+
+## When to use
+
+- Use `detach` when the parent does not need the child's result and the child should outlive the parent (e.g., sending a notification after order completion)
+- Use a normal child workflow call (with `.Get()`) when the parent needs the result or should fail if the child fails
+- `detach` uses `ABANDON` so the child survives parent completion independently. The default `ParentClosePolicy` is `TERMINATE` (child killed). `REQUEST_CANCEL` is a middle ground — the child receives a cancellation request and can handle it gracefully before stopping, but does not run indefinitely like `ABANDON`

package/skills/temporal-architect-author-go/reference/heartbeat.md

@@ -0,0 +1,84 @@
+# heartbeat
+
+## DSL
+
+```twf
+activity ProcessLargeFile(fileId: string) -> (ProcessResult):
+    file = download(fileId)
+    for (chunk in file.chunks):
+        process(chunk)
+        heartbeat(progress: {current: chunk, total: len(file.chunks)})
+    return ProcessResult{success: true}
+```
+
+Calling the activity with heartbeat and timeout options:
+
+```twf
+workflow ProcessFiles(fileId: string) -> (ProcessResult):
+    activity ProcessLargeFile(fileId) -> result
+        options:
+            start_to_close_timeout: 2h
+            heartbeat_timeout: 30s
+    close complete(result)
+```
+
+## Go
+
+```go
+func ProcessLargeFile(ctx context.Context, fileId string) (ProcessResult, error) {
+    file, err := download(ctx, fileId)
+    if err != nil {
+        return ProcessResult{}, err
+    }
+    for _, chunk := range file.Chunks {
+        if err := process(ctx, chunk); err != nil {
+            return ProcessResult{}, err
+        }
+        activity.RecordHeartbeat(ctx, map[string]interface{}{
+            "current": chunk,
+            "total":   len(file.Chunks),
+        })
+    }
+    return ProcessResult{Success: true}, nil
+}
+```
+
+## Notes
+
+- `heartbeat(args)` → `activity.RecordHeartbeat(ctx, details...)` — activity-only, never in workflows
+- Heartbeat details are arbitrary; use a struct or map
+- Set `HeartbeatTimeout` in `ActivityOptions` on the calling side — see [options.md](./options.md)
+- The SDK throttles heartbeats automatically (sent at `heartbeatTimeout * 0.8`, capped at 60s). No manual batching needed — call `RecordHeartbeat` as often as desired
+- The plain function shown above becomes a struct method in practice — see [activity-def.md](./activity-def.md) notes
+
+## Resume pattern
+
+Activities that heartbeat should resume from the last recorded progress on retry. Check for previous heartbeat details at activity start:
+
+```go
+func (a *Activities) ProcessLargeFile(ctx context.Context, fileId string) (ProcessResult, error) {
+    startIdx := 0
+    if activity.HasHeartbeatDetails(ctx) {
+        var lastIdx int
+        if err := activity.GetHeartbeatDetails(ctx, &lastIdx); err == nil {
+            startIdx = lastIdx + 1
+        }
+    }
+
+    file, err := a.download(ctx, fileId)
+    if err != nil {
+        return ProcessResult{}, err
+    }
+    for i := startIdx; i < len(file.Chunks); i++ {
+        if err := a.process(ctx, file.Chunks[i]); err != nil {
+            return ProcessResult{}, err
+        }
+        activity.RecordHeartbeat(ctx, i)
+    }
+    return ProcessResult{Success: true}, nil
+}
+```
+
+- `HasHeartbeatDetails` returns `false` on the first attempt (no prior failure)
+- Details come from the last heartbeat delivered to the server (post-throttling) — may be slightly behind the last `RecordHeartbeat` call
+- Heartbeat recording without a resume pattern is incomplete — the activity restarts from the beginning on every retry, wasting the progress tracking

package/skills/temporal-architect-author-go/reference/nexus-service-def.md

@@ -0,0 +1,73 @@
+# nexus service definition
+
+## DSL
+
+```twf
+nexus service BillingService:
+    operation ChargePayment(PaymentRequest) -> (PaymentResult)
+    operation RefundPayment(RefundRequest) -> (RefundResult)
+```
+
+## Go — Service contract (shared types)
+
+```go
+const BillingServiceName = "BillingService"
+const ChargePaymentOp = "ChargePayment"
+const RefundPaymentOp = "RefundPayment"
+```
+
+## Go — Async operation handler (workflow-backed)
+
+```go
+var ChargePaymentOperation = temporalnexus.NewWorkflowRunOperation(
+    ChargePaymentOp,
+    BillingChargeWorkflow,
+    func(ctx context.Context, input PaymentRequest, options nexus.StartOperationOptions) (client.StartWorkflowOptions, error) {
+        return client.StartWorkflowOptions{
+            ID: "payment-" + input.OrderID, // business-meaningful ID for deduplication
+        }, nil
+    },
+)
+```
+
+## Go — Sync operation handler
+
+```go
+var RefundPaymentOperation = nexus.NewSyncOperation(RefundPaymentOp, func(ctx context.Context, input RefundRequest, options nexus.StartOperationOptions) (RefundResult, error) {
+    // Direct implementation or use temporalnexus.GetClient(ctx) for Temporal client calls
+    return RefundResult{}, nil
+})
+```
+
+## Go — Registration on worker
+
+```go
+service := nexus.NewService(BillingServiceName)
+err := service.Register(ChargePaymentOperation, RefundPaymentOperation)
+if err != nil {
+    log.Fatalln("Unable to register operations", err)
+}
+w.RegisterNexusService(service)
+w.RegisterWorkflow(BillingChargeWorkflow) // handler workflows must also be registered
+```
+
+## Notes
+
+- Imports: `"github.com/nexus-rpc/sdk-go/nexus"` for `nexus.NewService`, `nexus.NewSyncOperation`; `"go.temporal.io/sdk/temporalnexus"` for `NewWorkflowRunOperation`, `GetClient`
+- Async operations (backed by workflows) use `temporalnexus.NewWorkflowRunOperation` — the workflow is started and the nexus operation resolves when the workflow completes
+- Sync operations use `nexus.NewSyncOperation` — for direct computation or queries/signals via `temporalnexus.GetClient(ctx)`
+- The service is registered on the handler worker (the target namespace's worker), not the caller
+- Handler workflows must also be registered with `RegisterWorkflow` on the same worker
+
+## When to use: sync vs async operations
+
+- **Sync** (`nexus.NewSyncOperation`): must complete within 10 seconds. Use for short computations, querying a workflow, signaling a workflow, sending an update, calling external services/databases directly. If the handler times out, the caller's Nexus machinery auto-retries until ScheduleToCloseTimeout
+- **Async / workflow-backed** (`temporalnexus.NewWorkflowRunOperation`): arbitrary duration. Use when the operation is a Temporal workflow. The caller receives a completion callback when the handler workflow finishes. Supports cancellation propagation and re-attachment via operation token
+- The choice is static — it depends on which SDK builder function you use, not on runtime conditions
+
+## Naming contract
+
+- Operation names must match exactly at the wire level between caller and handler — no automatic transformation
+- The string passed to `NewWorkflowRunOperation` or `NewSyncOperation` is the canonical operation name
+- Define operation names as Go constants (as shown in the service contract section) and reference them from both caller and handler code
+- In polyglot environments, both sides must agree on service name, operation names, and input/output types. Use Protobuf or JSON as the Data Converter format

package/skills/temporal-architect-author-go/reference/nexus.md

@@ -0,0 +1,35 @@
+# nexus
+
+## DSL
+
+```twf
+nexus BillingEndpoint BillingService.ChargePayment(order.payment) -> paymentResult
+```
+
+## Go
+
+```go
+c := workflow.NewNexusClient("BillingEndpoint", "BillingService")
+var paymentResult PaymentResult
+fut := c.ExecuteOperation(ctx, "ChargePayment", order.Payment, workflow.NexusOperationOptions{})
+if err := fut.Get(ctx, &paymentResult); err != nil {
+    return Result{}, err
+}
+```
+
+## Notes
+
+- `workflow.NewNexusClient(endpoint, service)` creates a typed client scoped to one endpoint + service pair
+- `ExecuteOperation(ctx, operationName, input, options)` starts the operation and returns a `NexusOperationFuture`
+- The calling pattern mirrors child workflows — execute and `.Get()`
+- For nexus options (timeouts), see [options.md](./options.md)
+- For fire-and-forget nexus: see [detach.md](./detach.md)
+- For nexus service definitions and handler registration: see [nexus-service-def.md](./nexus-service-def.md)
+- Prefer referencing operation name constants from the service contract (see [nexus-service-def.md](./nexus-service-def.md#naming-contract)) rather than bare strings — keeps caller and handler in sync
+
+## When to use Nexus vs child workflow
+
+- **Use Nexus when:** crossing namespace boundaries (child workflows are same-namespace only in Temporal Cloud), isolating service boundaries (caller only knows endpoint name + operation — not namespace, task queue, retry policy, or workflow ID constraints), enabling polyglot interop (caller and handler can use different SDKs/languages), or enforcing blast-radius isolation between teams
+- **Use child workflows when:** within a single namespace and team, partitioning event history, representing a resource with a unique workflow ID, or executing periodic logic via Continue-As-New
+- Nexus adds Endpoint configuration overhead — if you don't need cross-namespace or service isolation, child workflows are simpler
+- Nexus works within a single namespace too — you can start with Nexus and later split into separate namespaces with configuration changes only

package/skills/temporal-architect-author-go/reference/options.md

@@ -0,0 +1,138 @@
+# options
+
+## Activity options
+
+### DSL
+
+```twf
+activity QuickLookup(data.id) -> result
+    options:
+        start_to_close_timeout: 30s
+```
+
+### Go
+
+```go
+actCtx := workflow.WithActivityOptions(ctx, workflow.ActivityOptions{
+    StartToCloseTimeout: 30 * time.Second,
+})
+var result LookupResult
+err := workflow.ExecuteActivity(actCtx, QuickLookup, data.Id).Get(ctx, &result)
+```
+
+## Activity options with retry policy
+
+### DSL
+
+```twf
+activity UnreliableService(data) -> result
+    options:
+        start_to_close_timeout: 2m
+        retry_policy:
+            maximum_attempts: 5
+            initial_interval: 1s
+            backoff_coefficient: 2.0
+            maximum_interval: 60s
+```
+
+### Go
+
+```go
+actCtx := workflow.WithActivityOptions(ctx, workflow.ActivityOptions{
+    StartToCloseTimeout: 2 * time.Minute,
+    RetryPolicy: &temporal.RetryPolicy{
+        MaximumAttempts:        5,
+        InitialInterval:       1 * time.Second,
+        BackoffCoefficient:    2.0,
+        MaximumInterval:       60 * time.Second,
+    },
+})
+var result ServiceResult
+err := workflow.ExecuteActivity(actCtx, UnreliableService, data).Get(ctx, &result)
+```
+
+## Child workflow options
+
+### DSL
+
+```twf
+workflow ChildWorkflow(input.data) -> childResult
+    options:
+        workflow_execution_timeout: 1h
+        retry_policy:
+            maximum_attempts: 3
+```
+
+### Go
+
+```go
+childCtx := workflow.WithChildOptions(ctx, workflow.ChildWorkflowOptions{
+    WorkflowExecutionTimeout: 1 * time.Hour,
+    RetryPolicy: &temporal.RetryPolicy{
+        MaximumAttempts: 3,
+    },
+})
+var childResult ChildResult
+err := workflow.ExecuteChildWorkflow(childCtx, ChildWorkflow, input.Data).Get(ctx, &childResult)
+```
+
+## Child workflow `parent_close_policy`
+
+### DSL
+
+```twf
+workflow NotifyCustomer(order.customer)
+    options:
+        parent_close_policy: REQUEST_CANCEL
+```
+
+### Go
+
+```go
+childCtx := workflow.WithChildOptions(ctx, workflow.ChildWorkflowOptions{
+    ParentClosePolicy: enumspb.PARENT_CLOSE_POLICY_REQUEST_CANCEL,
+})
+err := workflow.ExecuteChildWorkflow(childCtx, NotifyCustomer, order.Customer).Get(ctx, nil)
+```
+
+## Nexus operation options
+
+### DSL
+
+```twf
+nexus BillingEndpoint BillingService.ChargePayment(payment) -> paymentResult
+    options:
+        schedule_to_close_timeout: 1h
+```
+
+### Go
+
+```go
+c := workflow.NewNexusClient("BillingEndpoint", "BillingService")
+var paymentResult PaymentResult
+fut := c.ExecuteOperation(ctx, "ChargePayment", payment, workflow.NexusOperationOptions{
+    ScheduleToCloseTimeout: 1 * time.Hour,
+})
+err := fut.Get(ctx, &paymentResult)
+```
+
+## Notes
+
+- When no `options:` block is specified, set a default `ActivityOptions` with `StartToCloseTimeout` on `ctx` near the top of the workflow function
+- Option keys map: `start_to_close_timeout` → `StartToCloseTimeout`, `schedule_to_close_timeout` → `ScheduleToCloseTimeout`, `heartbeat_timeout` → `HeartbeatTimeout`, `parent_close_policy` → `ParentClosePolicy` (type: `enumspb.ParentClosePolicy`; values: `PARENT_CLOSE_POLICY_TERMINATE` (default), `PARENT_CLOSE_POLICY_REQUEST_CANCEL`, `PARENT_CLOSE_POLICY_ABANDON`)
+- `retry_policy:` → `&temporal.RetryPolicy{...}` (pointer)
+- `NexusOperationOptions` fields: `ScheduleToCloseTimeout` (primary) and `CancellationType` (experimental). Options are passed inline — no context wrapping like activities
+
+## When to use each timeout
+
+- **`StartToCloseTimeout`** — maximum time for a single activity attempt. Resets on each retry. Primary mechanism for detecting worker crashes. Temporal recommends always setting this
+- **`ScheduleToCloseTimeout`** — total wall-clock time from when the activity is scheduled, including all retries. Does not reset. Use to cap total time when retries have exponential backoff
+- **`WorkflowExecutionTimeout`** — end-to-end timeout for the entire workflow execution including retries and Continue-As-New chains. Set on the client when starting the workflow, not in `ActivityOptions`
+- At least one of `StartToCloseTimeout` or `ScheduleToCloseTimeout` is required for activities — omitting both is a runtime error
+
+## Pitfalls
+
+- **`MaximumAttempts: 1`** means one attempt total — this disables retries. `MaximumAttempts: 0` (the default) means unlimited retries
+- **`BackoffCoefficient: 1.0`** produces fixed-interval retries (no exponential growth). The formula is `InitialInterval * BackoffCoefficient^(attempt-1)`
+- Activities retry by default (server default: initial interval 1s, backoff 2.0, max interval 100s, unlimited attempts). Workflows do not retry by default
+- If no `RetryPolicy` is specified on an activity, the server default applies — this is a common source of surprise