@temporal-architect/claude-plugin 0.9.0

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

@@ -0,0 +1,54 @@
+# activity definition
+
+## DSL
+
+```twf
+activity ValidateOrder(order: Order) -> (ValidateResult):
+    result = validate(order)
+    return result
+```
+
+## Go
+
+```go
+func ValidateOrder(ctx context.Context, order Order) (ValidateResult, error) {
+    result, err := validate(ctx, order)
+    if err != nil {
+        return ValidateResult{}, err
+    }
+    return result, nil
+}
+```
+
+## Notes
+
+- Activities use `context.Context` (stdlib), not `workflow.Context`
+- Every activity returns `error` as the last return value
+- No return type in DSL → `func Name(ctx context.Context, params...) error`
+- Activity bodies in `.twf` are pseudocode — ask the user about real implementation logic when it's ambiguous
+- In practice, activities are methods on a struct with injected dependencies — see [Activity Implementation Pattern](#activity-implementation-pattern) below
+
+## Activity Implementation Pattern
+
+Activities follow a thin-wrapper pattern with dependency injection:
+
+1. **Activity struct** holds interfaces as fields (one per external dependency)
+2. **Activity methods** are thin translation layers: validate inputs, call the interface, translate the output
+3. **Interfaces** are shaped by what activities need, informed by real SDK capabilities from the dependency map (see [dependency-resolution.md](./dependency-resolution.md))
+4. **Concrete implementations** of those interfaces contain the real SDK integration — client construction, request/response conversion, error handling
+
+The skill generates all four pieces. Activity methods and interfaces are mechanical. Concrete implementations require SDK knowledge from the dependency resolution step.
+
+## Pitfalls
+
+- **Context cancellation.** The activity's `context.Context` is a real stdlib context subject to cancellation. When Temporal times out or cancels an activity, the context is cancelled — but only if the activity calls `activity.RecordHeartbeat`. Without heartbeating, the activity goroutine never learns about cancellation and keeps running until it returns on its own
+- Long-running activities must check `ctx.Done()` or `ctx.Err()` to respect cancellation:
+  ```go
+  select {
+  case <-ctx.Done():
+      return Result{}, ctx.Err()
+  default:
+      // continue processing
+  }
+  ```
+- Activities that ignore `ctx.Done()` waste resources after timeout — the goroutine continues executing even though Temporal has already recorded the failure

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

@@ -0,0 +1,36 @@
+# assignment
+
+## DSL
+
+```twf
+paymentStatus = "pending"
+status = "awaiting_payment"
+```
+
+## Go
+
+```go
+paymentStatus := "pending"
+status := "awaiting_payment"
+
+// Reassignment (variable already declared):
+status = "processing"
+
+// Struct assignment from activity result or constructor:
+order := Order{Status: "new", Items: items}
+
+// Slice/map:
+var results []ProcessResult
+totals := make(map[string]int)
+```
+
+## Notes
+
+- First use of a variable → `:=` (short declaration); subsequent assignments → `=`
+- Workflow-scoped variables are declared at the top of the workflow function so signal/update handlers can access them via closure
+- DSL assignments in `state:` blocks and signal handler bodies all map to the same workflow-level variables
+
+## Pitfalls
+
+- **Closure scoping.** Variables declared inside a handler (signal, update, query) are invisible to the main workflow flow and to other handlers. If a value must be shared, declare the variable at workflow scope (top of the workflow function) and mutate it from the handler via closure
+- **Determinism.** Workflow variables must not be assigned from non-deterministic sources (`time.Now()`, `rand`, HTTP responses, global mutable state). Use `workflow.Now()`, `workflow.SideEffect()`, or activity results instead. See [workflow-def.md](./workflow-def.md) for the full constraint list

package/skills/temporal-architect-author-go/reference/await-all.md

@@ -0,0 +1,104 @@
+# await all
+
+## DSL
+
+```twf
+await all:
+    activity ReserveInventory(order) -> inventory
+    activity ChargePayment(order) -> payment
+```
+
+## Go
+
+```go
+var inventory Inventory
+var payment Payment
+var inventoryErr, paymentErr error
+
+wg := workflow.NewWaitGroup(ctx)
+
+wg.Go(ctx, func(gCtx workflow.Context) {
+    inventoryErr = workflow.ExecuteActivity(gCtx, ReserveInventory, order).Get(gCtx, &inventory)
+})
+wg.Go(ctx, func(gCtx workflow.Context) {
+    paymentErr = workflow.ExecuteActivity(gCtx, ChargePayment, order).Get(gCtx, &payment)
+})
+
+wg.Wait(ctx)
+
+if inventoryErr != nil {
+    return Result{}, inventoryErr
+}
+if paymentErr != nil {
+    return Result{}, paymentErr
+}
+```
+
+## Fan-out pattern
+
+### DSL
+
+```twf
+await all:
+    for (item in items):
+        activity ProcessBatchItem(item)
+```
+
+### Go
+
+```go
+futures := make([]workflow.Future, len(items))
+for i, item := range items {
+    futures[i] = workflow.ExecuteActivity(ctx, ProcessBatchItem, item)
+}
+for _, f := range futures {
+    if err := f.Get(ctx, nil); err != nil {
+        return Result{}, err
+    }
+}
+```
+
+## Mixed activity + nexus
+
+### DSL
+
+```twf
+await all:
+    activity ReserveInventory(order) -> inventory
+    nexus BillingEndpoint BillingService.ChargePayment(order.payment) -> payment
+```
+
+### Go
+
+```go
+var inventory Inventory
+var payment PaymentResult
+var inventoryErr, paymentErr error
+
+wg := workflow.NewWaitGroup(ctx)
+
+wg.Go(ctx, func(gCtx workflow.Context) {
+    inventoryErr = workflow.ExecuteActivity(gCtx, ReserveInventory, order).Get(gCtx, &inventory)
+})
+wg.Go(ctx, func(gCtx workflow.Context) {
+    c := workflow.NewNexusClient("BillingEndpoint", "BillingService")
+    paymentErr = c.ExecuteOperation(gCtx, "ChargePayment", order.Payment, workflow.NexusOperationOptions{}).Get(gCtx, &payment)
+})
+
+wg.Wait(ctx)
+
+if inventoryErr != nil {
+    return Result{}, inventoryErr
+}
+if paymentErr != nil {
+    return Result{}, paymentErr
+}
+```
+
+## Notes
+
+- Each statement in `await all:` runs in its own goroutine via `workflow.WaitGroup.Go`
+- `wg.Wait(ctx)` blocks until all goroutines complete — no fragile completion predicates
+- Fan-out with `for`: start all futures first, then `.Get` all — no goroutines needed since `ExecuteActivity` returns immediately
+- Nexus operations in `await all:` follow the same goroutine pattern — `ExecuteOperation` returns a future, `.Get()` blocks in the goroutine
+- Errors: check each goroutine's error after `wg.Wait`. For fail-fast, use `workflow.WithCancel` and cancel the context on first error

package/skills/temporal-architect-author-go/reference/await-one.md

@@ -0,0 +1,193 @@
+# await one
+
+## DSL
+
+```twf
+await one:
+    signal PaymentReceived:
+        status = "processing"
+    timer(24h):
+        activity CancelOrder(orderId)
+        close fail(OrderResult{status: "cancelled"})
+```
+
+## History Hygiene
+
+Per DSL semantics, non-winning cases are **not** cancelled by `await one` — they continue running until the workflow run ends (`close complete`, `close fail`, `close continue_as_new`, or external cancellation). The Go `Selector.Select` API mirrors this: it fires one case and returns, leaving all other registered futures and channels active.
+
+Explicitly cancelling the losing timer is an **optimization** for history hygiene, not a correctness requirement. A non-cancelled timer will fire later and generate unnecessary workflow tasks.
+
+```go
+// WASTEFUL: the losing timer fires later, adding unnecessary history events
+sel.Select(ctx)
+// timer still scheduled — generates a timer-fired event when it expires
+
+// BETTER: cancel the timer in the winning handler to avoid wasted history events
+sel.AddReceive(signalCh, func(ch workflow.ReceiveChannel, more bool) {
+    ch.Receive(ctx, nil)
+    cancelTimer() // prevents the timer from generating further history events
+})
+```
+
+## Go
+
+```go
+timerCtx, cancelTimer := workflow.WithCancel(ctx)
+
+sel := workflow.NewSelector(ctx)
+
+sel.AddReceive(paymentReceivedCh, func(ch workflow.ReceiveChannel, more bool) {
+    var sig PaymentReceivedSignal
+    ch.Receive(ctx, &sig)
+    status = "processing"
+    cancelTimer()
+})
+
+timerFuture := workflow.NewTimer(timerCtx, 24*time.Hour)
+sel.AddFuture(timerFuture, func(f workflow.Future) {
+    if err := f.Get(ctx, nil); err != nil {
+        // timer cancelled — signal won the race
+        return
+    }
+    err := workflow.ExecuteActivity(ctx, CancelOrder, orderId).Get(ctx, nil)
+    if err != nil {
+        // handle activity error
+    }
+    // close fail handled after selector
+})
+
+sel.Select(ctx)
+```
+
+## Case types
+
+**Signal case** — `sel.AddReceive(channel, handler)`
+```go
+sel.AddReceive(signalCh, func(ch workflow.ReceiveChannel, more bool) {
+    var sig SignalType
+    ch.Receive(ctx, &sig)
+    // case body
+})
+```
+
+**Timer case** — `sel.AddFuture(workflow.NewTimer(...), handler)`
+```go
+sel.AddFuture(workflow.NewTimer(ctx, duration), func(f workflow.Future) {
+    if err := f.Get(ctx, nil); err != nil {
+        // timer cancelled
+        return
+    }
+    // case body
+})
+```
+
+**Activity case** — `sel.AddFuture(workflow.ExecuteActivity(...), handler)`
+```go
+sel.AddFuture(workflow.ExecuteActivity(ctx, DoWork, args), func(f workflow.Future) {
+    var result ResultType
+    if err := f.Get(ctx, &result); err != nil {
+        // handle error
+        return
+    }
+    // case body
+})
+```
+
+**Workflow case** — `sel.AddFuture(workflow.ExecuteChildWorkflow(...), handler)`
+```go
+sel.AddFuture(workflow.ExecuteChildWorkflow(ctx, Child, args), func(f workflow.Future) {
+    var result ResultType
+    if err := f.Get(ctx, &result); err != nil {
+        // handle error
+        return
+    }
+    // case body
+})
+```
+
+**Nexus case** — `sel.AddFuture(client.ExecuteOperation(...), handler)`. Nexus operations return `NexusOperationFuture`, which satisfies `workflow.Future` — add to selector with `AddFuture`.
+```go
+c := workflow.NewNexusClient("BillingEndpoint", "BillingService")
+sel.AddFuture(c.ExecuteOperation(ctx, "ChargePayment", input, workflow.NexusOperationOptions{}), func(f workflow.Future) {
+    var result PaymentResult
+    if err := f.Get(ctx, &result); err != nil {
+        // handle error
+        return
+    }
+    // case body
+})
+```
+
+**Update case** — register handler separately (see [update-handler.md](./update-handler.md)), share state between the update handler and selector
+```go
+// Update handlers are registered separately (see update-handler.md).
+// To race an update against other events, share state between the update handler and selector:
+sel.AddReceive(updateDoneCh, func(ch workflow.ReceiveChannel, more bool) {
+    ch.Receive(ctx, nil)
+    // react to update completion
+})
+```
+
+**Promise (ident) case** — add the existing future or channel to the selector
+```go
+// future promise
+sel.AddFuture(myFuture, func(f workflow.Future) {
+    var result ResultType
+    if err := f.Get(ctx, &result); err != nil {
+        // handle error
+        return
+    }
+    // case body
+})
+
+// condition promise — use a goroutine that signals a channel
+condCh := workflow.NewChannel(ctx)
+workflow.Go(ctx, func(gCtx workflow.Context) {
+    if err := workflow.Await(gCtx, func() bool { return myCondition }); err != nil {
+        return // context cancelled — don't send
+    }
+    condCh.Send(gCtx, true)
+})
+sel.AddReceive(condCh, func(ch workflow.ReceiveChannel, more bool) {
+    ch.Receive(ctx, nil)
+    // case body
+})
+```
+
+## Notes
+
+- `sel.Select(ctx)` blocks until exactly one case fires — the first to complete wins
+- **Non-winning cases are not cancelled by `await one`.** Per DSL semantics, they continue running until the workflow run ends (`close complete`, `close fail`, `close continue_as_new`, or external cancellation). This matches `Selector.Select` Go SDK behavior. Explicit cancellation in the winning handler is an optimization for history hygiene, not a semantic requirement
+- Cancelling a **timer** via `workflow.WithCancel` is clean — the timer stops and generates no further history events. Cancelling a **child workflow** sends a cancellation *request*; the child's actual behavior depends on its own cancellation handling. For controlling child lifecycle at parent completion, use `parent_close_policy` in child workflow options (see [options.md](./options.md))
+- Uncancelled timers remain active and generate unnecessary workflow tasks when they fire
+- Empty case bodies (just the colon in DSL) → handler function with only the `Receive`/`Get` call, no additional logic
+- For `close` inside a case body: set a variable in the handler, check it after `sel.Select`, then return
+- Nested `await all:` inside `await one:` → wrap the `await all` logic in a goroutine that signals a channel on completion, add as `AddReceive`:
+  ```go
+  allDoneCh := workflow.NewChannel(ctx)
+  workflow.Go(ctx, func(gCtx workflow.Context) {
+      wg := workflow.NewWaitGroup(gCtx)
+      wg.Go(gCtx, func(gCtx2 workflow.Context) { /* activity A */ })
+      wg.Go(gCtx, func(gCtx2 workflow.Context) { /* activity B */ })
+      wg.Wait(gCtx)
+      allDoneCh.Send(gCtx, true)
+  })
+  sel.AddReceive(allDoneCh, func(ch workflow.ReceiveChannel, more bool) {
+      ch.Receive(ctx, nil)
+      // all activities completed
+  })
+  ```
+
+## When to use: single Select vs loop
+
+- **Single `sel.Select(ctx)`** (as shown above): use for one-time races — "whichever happens first wins" (e.g., payment or timeout)
+- **`sel.Select(ctx)` in a loop**: use for event-driven workflows that process multiple events over time. Re-add cases each iteration or use persistent cases. Common for entity workflows that react to signals indefinitely
+  ```go
+  for {
+      sel := workflow.NewSelector(ctx)
+      sel.AddReceive(signalCh, func(ch workflow.ReceiveChannel, more bool) { ... })
+      sel.AddFuture(workflow.NewTimer(ctx, interval), func(f workflow.Future) { ... })
+      sel.Select(ctx)
+      if done { break }
+  }
+  ```

package/skills/temporal-architect-author-go/reference/await-timer.md

@@ -0,0 +1,35 @@
+# await timer
+
+## DSL
+
+```twf
+await timer(5m)
+```
+
+## Go
+
+```go
+err := workflow.Sleep(ctx, 5*time.Minute)
+if err != nil {
+    return Result{}, err
+}
+```
+
+## Notes
+
+- Duration units: `s` → `time.Second`, `m` → `time.Minute`, `h` → `time.Hour`, `d` → `24*time.Hour`
+- Variable durations: `await timer(backoff)` → use the variable directly: `workflow.Sleep(ctx, backoff)`
+- Inside `await one:`, timers use `workflow.NewTimer` instead — see [await-one.md](./await-one.md)
+
+## Pitfalls
+
+- `workflow.Sleep` returns `*CanceledError` when the context is cancelled (either by `workflow.WithCancel` or by external workflow cancellation). Do not treat this as a generic failure — check for `*temporal.CanceledError` to enable clean cancellation handling:
+  ```go
+  err := workflow.Sleep(ctx, duration)
+  if err != nil {
+      if temporal.IsCanceledError(err) {
+          // clean cancellation — run cleanup logic
+      }
+      return Result{}, err
+  }
+  ```

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

@@ -0,0 +1,71 @@
+# close
+
+## close complete
+
+### DSL
+
+```twf
+close complete(Result{status: "done"})
+```
+
+### Go
+
+```go
+return Result{Status: "done"}, nil
+```
+
+## close complete (no value)
+
+### DSL
+
+```twf
+close complete
+```
+
+### Go
+
+```go
+return nil
+```
+
+## close fail
+
+### DSL
+
+```twf
+close fail(OrderResult{status: "cancelled"})
+```
+
+### Go
+
+```go
+return OrderResult{}, temporal.NewApplicationError("order cancelled", "OrderCancelled", OrderResult{Status: "cancelled"})
+```
+
+## close continue_as_new
+
+### DSL
+
+```twf
+close continue_as_new(userId, user)
+```
+
+### Go
+
+```go
+return workflow.NewContinueAsNewError(ctx, UserEntity, userId, user)
+```
+
+## Notes
+
+- `close complete(value)` → `return value, nil`
+- `close fail(value)` → return zero value + `temporal.NewApplicationError`. Pass the struct as error details to preserve structured data across workflow boundaries. Use `NewNonRetryableApplicationError` when the failure should not be retried
+- `close continue_as_new` passes args to the same workflow function via `workflow.NewContinueAsNewError`
+- `close complete` with no args and no return type → `return nil`
+
+## When to use each error type
+
+- **`temporal.NewApplicationError(msg, errType, details...)`** — structured workflow error. The `errType` string enables callers to distinguish error types. Pass the original struct as `details` to preserve data across workflow boundaries. Retryable by default
+- **`temporal.NewNonRetryableApplicationError(msg, errType, cause, details...)`** — same as above but the workflow will not be retried. Use for permanent failures (invalid input, business rule violations)
+- **Retryable vs non-retryable:** retryable errors trigger the workflow's retry policy (if configured). Non-retryable errors fail the workflow immediately regardless of retry policy
+- Plain `fmt.Errorf` or `errors.New` produces an untyped error — callers cannot distinguish error types or extract structured details. Prefer `ApplicationError` for workflow-boundary errors

package/skills/temporal-architect-author-go/reference/composite-patterns.md

@@ -0,0 +1,176 @@
+# composite patterns
+
+Patterns in isolation are straightforward. Bugs cluster where patterns combine. These worked examples show the most common compositions and their pitfalls.
+
+## Pattern 1: Update handler + condition + selector (HumanReview)
+
+An update handler sets a condition that races against a timer in a selector: "approve within the deadline, or auto-escalate."
+
+### DSL
+
+```twf
+workflow HumanReview(docId: string) -> (ReviewResult):
+    state:
+        condition reviewComplete
+
+    update SubmitReview(decision: string) -> (ReviewResult):
+        result = decision
+        set reviewComplete
+        return ReviewResult{decision: result}
+
+    await one:
+        reviewComplete:
+            close complete(ReviewResult{decision: result})
+        timer(48h):
+            activity Escalate(docId)
+            close complete(ReviewResult{decision: "escalated"})
+```
+
+### Go
+
+```go
+func HumanReview(ctx workflow.Context, docId string) (ReviewResult, error) {
+    reviewComplete := false
+    var result string
+
+    // Register update handler FIRST — before any blocking call
+    err := workflow.SetUpdateHandlerWithOptions(ctx, "SubmitReview",
+        func(ctx workflow.Context, decision string) (ReviewResult, error) {
+            result = decision
+            reviewComplete = true
+            return ReviewResult{Decision: result}, nil
+        },
+        workflow.UpdateHandlerOptions{},
+    )
+    if err != nil {
+        return ReviewResult{}, err
+    }
+
+    // Race: condition (set by update) vs timer
+    timerCtx, cancelTimer := workflow.WithCancel(ctx)
+
+    sel := workflow.NewSelector(ctx)
+
+    // Condition case — wrap in goroutine + channel (conditions aren't futures)
+    condCh := workflow.NewChannel(ctx)
+    workflow.Go(ctx, func(gCtx workflow.Context) {
+        if err := workflow.Await(gCtx, func() bool { return reviewComplete }); err != nil {
+            return // context cancelled
+        }
+        condCh.Send(gCtx, true)
+    })
+    sel.AddReceive(condCh, func(ch workflow.ReceiveChannel, more bool) {
+        ch.Receive(ctx, nil)
+        cancelTimer()
+    })
+
+    // Timer case
+    sel.AddFuture(workflow.NewTimer(timerCtx, 48*time.Hour), func(f workflow.Future) {
+        if err := f.Get(ctx, nil); err != nil {
+            return // timer cancelled — review won the race
+        }
+        var a *Activities
+        _ = workflow.ExecuteActivity(ctx, a.Escalate, docId).Get(ctx, nil)
+        result = "escalated"
+    })
+
+    sel.Select(ctx)
+
+    // Wait for any in-flight update handlers before returning
+    _ = workflow.Await(ctx, func() bool { return workflow.AllHandlersFinished(ctx) })
+
+    return ReviewResult{Decision: result}, nil
+}
+```
+
+### Why this is tricky
+
+1. **Update handler must be registered before `sel.Select`** — if the selector blocks first, updates arriving during the race window are rejected
+2. **Condition is not a future** — it must be bridged to the selector via a goroutine + channel (see [await-one.md](./await-one.md), "condition promise" pattern)
+3. **Timer should be cancelled in the condition handler** — per DSL semantics, non-winning cases are not automatically cancelled; the timer continues running until workflow completion. Cancelling it in the winning handler is an optimization that prevents unnecessary history events (a timer-fired event 48h later)
+4. **`AllHandlersFinished` wait before return** — without this, an in-flight update handler is abandoned when the workflow completes (see [update-handler.md](./update-handler.md))
+
+---
+
+## Pattern 2: Signal handler goroutine + main-thread await after sleep (ManageRetention)
+
+A long-running workflow sleeps for a retention period while a signal handler goroutine listens for early cancellation.
+
+### DSL
+
+```twf
+workflow ManageRetention(docId: string, retentionDays: int):
+    state:
+        condition cancelled
+
+    signal CancelRetention():
+        set cancelled
+
+    await one:
+        cancelled:
+            activity DeleteDocument(docId)
+            close complete
+        timer(retentionDays * 24h):
+            activity DeleteDocument(docId)
+            close complete
+```
+
+### Go
+
+```go
+func ManageRetention(ctx workflow.Context, docId string, retentionDays int) error {
+    cancelled := false
+
+    // Signal channel + handler goroutine
+    cancelRetentionCh := workflow.GetSignalChannel(ctx, "CancelRetention")
+    workflow.Go(ctx, func(gCtx workflow.Context) {
+        for {
+            cancelRetentionCh.Receive(gCtx, nil)
+            cancelled = true
+        }
+    })
+
+    // Race: signal-set condition vs retention timer
+    timerCtx, cancelTimer := workflow.WithCancel(ctx)
+
+    sel := workflow.NewSelector(ctx)
+
+    // Condition case
+    condCh := workflow.NewChannel(ctx)
+    workflow.Go(ctx, func(gCtx workflow.Context) {
+        if err := workflow.Await(gCtx, func() bool { return cancelled }); err != nil {
+            return
+        }
+        condCh.Send(gCtx, true)
+    })
+    sel.AddReceive(condCh, func(ch workflow.ReceiveChannel, more bool) {
+        ch.Receive(ctx, nil)
+        cancelTimer()
+    })
+
+    // Timer case
+    duration := time.Duration(retentionDays) * 24 * time.Hour
+    sel.AddFuture(workflow.NewTimer(timerCtx, duration), func(f workflow.Future) {
+        if err := f.Get(ctx, nil); err != nil {
+            return // timer cancelled — signal won
+        }
+    })
+
+    sel.Select(ctx)
+
+    // Both paths delete the document
+    var a *Activities
+    err := workflow.ExecuteActivity(ctx, a.DeleteDocument, docId).Get(ctx, nil)
+    if err != nil {
+        return err
+    }
+    return nil
+}
+```
+
+### Why this is tricky
+
+1. **Signal handler goroutine runs independently of the selector** — it loops forever, processing every signal arrival. The condition bridge (`workflow.Await` + channel send) connects it to the selector
+2. **The signal handler mutates `cancelled`, the selector reads it via the condition goroutine** — two goroutines share state through a bool, which is safe in Temporal's cooperative scheduling model but would be a data race in normal Go
+3. **Timer cancellation is recommended** — per DSL semantics, non-winning cases are not automatically cancelled; the timer continues until workflow completion regardless. Cancelling it in the winning handler avoids a wasted timer-fired history event
+4. **Shared post-race logic** — when both branches do the same thing, factor the common activity call after `sel.Select` instead of duplicating inside handlers