@temporal-architect/claude-plugin 0.9.0

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

@@ -0,0 +1,73 @@
+# promise
+
+## DSL
+
+```twf
+promise handleA <- activity ProcessA(items.a)
+# ... do other work ...
+await handleA -> resultA
+```
+
+## Go
+
+```go
+futureA := workflow.ExecuteActivity(ctx, ProcessA, items.A)
+// ... do other work ...
+var resultA ResultA
+err := futureA.Get(ctx, &resultA)
+if err != nil {
+    return Result{}, err
+}
+```
+
+## Variants
+
+```twf
+promise childHandle <- workflow SlowChild(input.data)
+```
+
+```go
+childFuture := workflow.ExecuteChildWorkflow(ctx, SlowChild, input.Data)
+```
+
+```twf
+promise timeout <- timer(5m)
+```
+
+```go
+timerFuture := workflow.NewTimer(ctx, 5*time.Minute)
+```
+
+```twf
+promise approved <- signal Approved
+```
+
+```go
+approvedCh := workflow.GetSignalChannel(ctx, "Approved")
+// Use approvedCh.Receive later, or add to selector
+```
+
+```twf
+promise payHandle <- nexus BillingEndpoint BillingService.ChargePayment(payment)
+```
+
+```go
+c := workflow.NewNexusClient("BillingEndpoint", "BillingService")
+payFuture := c.ExecuteOperation(ctx, "ChargePayment", payment, workflow.NexusOperationOptions{})
+```
+
+## Notes
+
+- A promise is just a future — the call starts immediately, `.Get` defers the blocking
+- Activity/workflow promises → `workflow.Future` from `ExecuteActivity`/`ExecuteChildWorkflow`
+- Timer promises → `workflow.Future` from `workflow.NewTimer`
+- Signal promises → `workflow.ReceiveChannel` from `workflow.GetSignalChannel` — **not a `Future`**. Use `.Receive()` to block or add to a selector with `AddReceive`. Do not call `.Get()` on a channel
+- Nexus promises → `NexusOperationFuture` from `NexusClient.ExecuteOperation`; same `.Get()` pattern as activity/workflow futures. Also has `GetNexusOperationExecution()` to optionally wait for the operation to start (not finish)
+- Updates are handler-driven, not future-driven — they don't produce futures directly. To race an update completion, use a channel set by the update handler (see [update-handler.md](./update-handler.md))
+- Promises used in `await one:` are added as selector cases — see [await-one.md](./await-one.md)
+
+## When to use
+
+- Use a promise (deferred `.Get`) when other work can proceed before the result is needed — the call starts immediately and runs concurrently with subsequent workflow code
+- Use an inline blocking call (`.Get()` immediately) when the result is needed before any further work. This is the simpler pattern and should be the default
+- Promises are essential for `await all:` (parallel fan-out) and `await one:` (racing) patterns

package/skills/temporal-architect-author-go/reference/proto-driven.md

@@ -0,0 +1,197 @@
+# proto-driven
+
+Codegen variant where **protobuf is the single source of truth** for workflow and activity interfaces. Generators produce the Temporal framework — typed interfaces, registration helpers, activity futures, Nexus stubs — leaving only business logic hand-written. Route here when the [Orient](../SKILL.md#orient) signals fire (`buf.gen.yaml` → `protoc-gen-go_temporal`, generated `*_temporal.pb.go`, `(temporal.v1.activity|workflow)` annotations).
+
+Sometimes called **PFI** (proto-first interfaces). Detect it from those repo signals, never from the name.
+
+In an existing proto-first repo, the layout, tooling, and naming are **requirements to match** — conform to what discovery found; do not impose this skeleton over a different one.
+
+---
+
+## Contract + layout
+
+Three directories, one direction of flow: `proto/` (source of truth) → `gen/` (generated, never edit) → `lib/` (hand-written).
+
+```
+<project>/
+├── proto/<service>/<version>/<service>.proto   # interface definitions (source of truth)
+├── gen/<service>/<version>/
+│   ├── *.pb.go                                  # generated: message types
+│   └── *_temporal.pb.go                         # generated: interfaces, registration helpers, futures
+└── lib/<service>/<version>/
+    ├── activities.go                            # hand-written: implements generated Activities interface
+    ├── workflows.go                             # hand-written: implements generated Workflows interface (if any)
+    ├── client.go                                # hand-written: external system client
+    └── fx.go                                    # hand-written: dependency injection wiring
+```
+
+Everything under `gen/` is generated — never hand-edit it.
+
+---
+
+## Tools
+
+[buf](https://buf.build) drives generation; plugins are installed from `go.mod` so versions are pinned to the module:
+
+```bash
+go install google.golang.org/protobuf/cmd/protoc-gen-go
+go install github.com/alta/protopatch/cmd/protoc-gen-go-patch
+go install github.com/cludden/protoc-gen-go-temporal/cmd/protoc-gen-go_temporal
+# Optional: Nexus support
+go install github.com/bergundy/protoc-gen-go-nexus/cmd/protoc-gen-go-nexus
+go install github.com/bergundy/protoc-gen-go-nexus-temporal/cmd/protoc-gen-go-nexus-temporal
+```
+
+These must be on `$PATH` when `buf generate` runs.
+
+### `buf.yaml` skeleton
+
+```yaml
+version: v2
+modules:
+  - path: proto/<service>
+deps:
+  - buf.build/cludden/protoc-gen-go-temporal   # Temporal annotations
+  - buf.build/alta/protopatch                   # struct tag patching
+lint:
+  use:
+    - STANDARD
+  except:
+    # Temporal uses XxxInput/XxxOutput, not XxxRequest/XxxResponse
+    - RPC_REQUEST_STANDARD_NAME
+    - RPC_RESPONSE_STANDARD_NAME
+    - RPC_REQUEST_RESPONSE_UNIQUE
+breaking:
+  use:
+    - FILE
+```
+
+### `buf.gen.yaml` skeleton
+
+```yaml
+version: v2
+managed:
+  enabled: true
+plugins:
+  - local: protoc-gen-go-patch       # Go message types (with struct tag patching)
+    out: gen/<service>
+    opt: [paths=source_relative, plugin=go]
+  - local: protoc-gen-go_temporal    # Temporal workflow/activity stubs and interfaces
+    out: gen/<service>
+    opt: [paths=source_relative, enable-patch-support=true]
+    strategy: all
+inputs:
+  - directory: proto/<service>
+```
+
+Run generation with `buf generate`.
+
+---
+
+## Proto annotations
+
+```proto
+service MyService {
+  option (temporal.v1.service) = {task_queue: "my-task-queue"};
+
+  rpc CreateThing(CreateThingInput) returns (CreateThingOutput) {
+    option (temporal.v1.activity) = {
+      name: "myservice.v1.CreateThing"
+      schedule_to_close_timeout: {seconds: 300}
+    };
+  }
+
+  rpc DeployCluster(DeployClusterInput) returns (DeployClusterOutput) {
+    option (temporal.v1.workflow) = {
+      name: "myservice.v1.DeployCluster"
+      id: "deploy-cluster-{{.Input.ClusterName}}"
+    };
+  }
+}
+
+message CreateThingInput {
+  string name = 1 [(go.field).tags = 'json:"Name" validate:"required"'];
+}
+```
+
+- `(temporal.v1.service)` sets the task queue for all RPCs in the service.
+- `(temporal.v1.activity)` / `(temporal.v1.workflow)` mark an RPC; set a unique `name` and timeouts. Workflows and activities coexist in one service.
+- `(go.field).tags` injects struct tags on the generated Go type (requires `protopatch`).
+- Use `XxxInput` / `XxxOutput` naming — the Temporal ecosystem expects these, not `Request`/`Response`.
+
+---
+
+## Generated-symbol table
+
+For each annotated service, `protoc-gen-go_temporal` emits these in `*_temporal.pb.go`. This is the Rosetta Stone — the same table is read **backward** during [reverse engineering](../../temporal-architect-design/reference/reverse-engineering.md) to recover intent from generated code.
+
+| Generated symbol | Purpose |
+|---|---|
+| `XxxActivities` interface | implement with your business logic |
+| `RegisterXxxActivities(worker, impl)` | register all activities at once |
+| `XxxActivityName` constant | activity name string for Temporal |
+| `XxxFuture` struct | typed future for async activity calls from workflows |
+| `XxxWorkflows` interface | implement for workflows (if RPCs are annotated as workflows) |
+| `RegisterXxxWorkflows(worker, impl)` | register all workflows |
+| `XxxClient` struct | call activities/workflows from outside Temporal |
+
+You never write these — only the implementations.
+
+---
+
+## Implement, register, client
+
+**Implement** the generated interface; each method is validate → call → return:
+
+```go
+// activities.go
+type Activities struct {
+    client MyServiceClient // hand-written external system client
+}
+
+func (a *Activities) CreateThing(ctx context.Context, req *pb.CreateThingInput) (*pb.CreateThingOutput, error) {
+    if req.Name == "" {                              // 1. validate
+        return nil, errors.New("name is required")
+    }
+    id, err := a.client.Create(ctx, req.Name)        // 2. call external system
+    if err != nil {
+        return nil, fmt.Errorf("create thing: %w", err)
+    }
+    return &pb.CreateThingOutput{Id: id}, nil        // 3. return typed output
+}
+```
+
+**Register** the generated helper at worker startup (commonly via `fx`):
+
+```go
+// fx.go
+var Module = fx.Options(
+    fx.Provide(NewMyServiceClient),
+    fx.Provide(func(c MyServiceClient) pb.MyServiceActivities { return NewActivities(c) }),
+)
+
+func RegisterActivities(w worker.Worker, a pb.MyServiceActivities) {
+    pb.RegisterMyServiceActivities(w, a) // generated; missing registration → "activity not found" at runtime
+}
+```
+
+**Client interface** — define a hand-written interface for the external system in the implementation package so activities depend on the interface, not the concrete type (and it can be mocked in tests):
+
+```go
+// client.go
+type MyServiceClient interface {
+    Create(ctx context.Context, name string) (id string, err error)
+    Delete(ctx context.Context, id string) error
+}
+```
+
+For the testing seam on these generated and hand-written interfaces, see [three-layer-testing.md](./three-layer-testing.md).
+
+---
+
+## References
+
+- [protoc-gen-go-temporal](https://github.com/cludden/protoc-gen-go-temporal) — the core Temporal code generator
+- [protopatch](https://github.com/alta/protopatch) — struct tag injection for Go proto types
+- [buf](https://buf.build/docs) — proto dependency management and generation pipeline
+- [three-layer-testing.md](./three-layer-testing.md) — testing strategy; the generated activities interface is the proto seam for mocks

package/skills/temporal-architect-author-go/reference/query-handler.md

@@ -0,0 +1,34 @@
+# query handler
+
+## DSL
+
+```twf
+query GetStatus() -> (string):
+    return status
+```
+
+## Go
+
+```go
+err := workflow.SetQueryHandler(ctx, "GetStatus", func() (string, error) {
+    return status, nil
+})
+if err != nil {
+    return Result{}, err
+}
+```
+
+## Notes
+
+- Query handlers always return `(ReturnType, error)`
+- Query handlers must not modify workflow state — read-only
+- Query handlers have no `workflow.Context` parameter in their signature
+- With params: `func(param1 Type1, param2 Type2) (ReturnType, error)`
+- Non-deterministic operations (e.g., ranging over a map) are permitted in query handlers — they execute outside the replay path
+- Register queries at the very start of the workflow function, before any blocking calls. If a query arrives before the handler is registered during replay, the caller receives an `unknown queryType` error
+
+## Pitfalls
+
+- **No blocking operations.** Query handlers must not call `workflow.Go()`, `workflow.NewChannel()`, `Channel.Get()`, `Future.Get()`, or `workflow.Await()`. Violation causes a panic caught by the SDK, returning `QueryFailedError` to the caller
+- **No activities or commands.** Query handlers cannot execute activities, schedule timers, start child workflows, or produce any workflow command. This also produces `QueryFailedError`
+- These restrictions exist because queries are dispatched outside the normal workflow execution context — they cannot participate in the event history

package/skills/temporal-architect-author-go/reference/signal-handler.md

@@ -0,0 +1,73 @@
+# signal handler
+
+## DSL
+
+```twf
+workflow OrderWorkflow(orderId: string) -> (OrderResult):
+    signal PaymentReceived(transactionId: string, amount: decimal):
+        status = "payment_received"
+        lastTransactionId = transactionId
+
+    # ... body uses await signal PaymentReceived or await one with signal case
+```
+
+## Go
+
+```go
+func OrderWorkflow(ctx workflow.Context, orderId string) (OrderResult, error) {
+    var status string
+    var lastTransactionId string
+
+    // Signal struct
+    type PaymentReceivedSignal struct {
+        TransactionId string
+        Amount        float64
+    }
+
+    // Signal channel
+    paymentReceivedCh := workflow.GetSignalChannel(ctx, "PaymentReceived")
+
+    // Register handler via goroutine that loops on the channel
+    workflow.Go(ctx, func(gCtx workflow.Context) {
+        for {
+            var sig PaymentReceivedSignal
+            paymentReceivedCh.Receive(gCtx, &sig)
+            status = "payment_received"
+            lastTransactionId = sig.TransactionId
+        }
+    })
+
+    // ... workflow body
+}
+```
+
+## Notes
+
+- Signal params become a struct; signal name becomes the channel name string
+- The handler goroutine loops forever — it processes every signal arrival, not just the first
+- Handler body mutates workflow-scoped variables (closures over workflow state)
+- Signals with no params: use `paymentReceivedCh.Receive(gCtx, nil)`
+- When a signal is also used in `await one:`, the selector reads from the same channel — see [await-one.md](./await-one.md)
+- `decimal` type in DSL maps to `float64` by default. For financial values where precision matters, consider `shopspring/decimal` or integer-cents representation instead
+
+## When to use each pattern
+
+- **Goroutine loop** (`workflow.Go` + `Receive` in a loop, as shown above): use when every signal must be processed as it arrives, independent of the main workflow flow. Most common pattern
+- **Blocking `Receive` inline**: use when the workflow must pause and wait for exactly one signal before continuing. Simpler but blocks the main flow
+- **`Selector.AddReceive`**: use when racing a signal against other events (timers, activities, other signals) — see [await-one.md](./await-one.md)
+
+## Pitfalls
+
+- **Signal drain before Continue-As-New (Go SDK only).** Signals are lost if the channel is not drained before `workflow.NewContinueAsNewError`. Drain with `ReceiveAsync` immediately before CAN:
+  ```go
+  for {
+      var sig SignalType
+      if !signalCh.ReceiveAsync(&sig) {
+          break
+      }
+      // process or forward to next run via workflow input
+  }
+  return workflow.NewContinueAsNewError(ctx, MyWorkflow, state)
+  ```
+- When using a `Selector` for signal handling, drain with `selector.HasPending()` + `selector.Select(ctx)` loop before CAN
+- Do not trigger Continue-As-New from inside a signal handler — call it from the main workflow thread to avoid signal loss

package/skills/temporal-architect-author-go/reference/three-layer-testing.md

@@ -0,0 +1,173 @@
+# three-layer-testing
+
+Temporal Go code divides into three testable layers. **Each layer mocks only its direct dependency** — never anything deeper. This is good practice for any clean Go Temporal project, not just proto-driven ones.
+
+| Layer | File | Mocks | Build tag | Speed |
+|---|---|---|---|---|
+| Workflows | `workflows_test.go` | activities interface | *(none)* | fast, no Docker |
+| Activities | `activities_test.go` | client interface | *(none)* | fast, no Docker |
+| Clients | `client_test.go` | nothing (real system) | `integration` | slow, needs Docker |
+
+**Why three layers:** workflow tests check orchestration (right activities, right order, failures propagate) but can't see bugs inside activities; activity tests check validation and error handling but can't see bugs in the real client; client tests check the real protocol/error codes that mocks would hide. Each layer catches bugs the others cannot.
+
+---
+
+## Layer 1: Workflow tests
+
+Use `testsuite.WorkflowTestSuite`; mock the activities interface so the workflow can be driven to any outcome without real systems. A fresh environment per table case:
+
+```go
+func TestProcessOrderWorkflow(t *testing.T) {
+    tests := []struct {
+        name      string
+        createErr error
+        wantErr   bool
+    }{
+        {name: "success - order processed", wantErr: false},
+        {name: "error - charge fails", createErr: errors.New("declined"), wantErr: true},
+    }
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            env := (&testsuite.WorkflowTestSuite{}).NewTestWorkflowEnvironment()
+            mockActivities := mocks.NewMockActivities(t)
+            env.RegisterActivity(mockActivities)
+
+            // Conditional mock: only set expectations on the path the case reaches.
+            mockActivities.EXPECT().
+                ChargePayment(mock.Anything, mock.Anything).
+                Return(&pb.ChargeOutput{Id: "ch-1"}, tt.createErr)
+
+            env.ExecuteWorkflow(ProcessOrder, &pb.OrderInput{})
+
+            err := env.GetWorkflowError()
+            if tt.wantErr {
+                require.Error(t, err)
+                return
+            }
+            require.NoError(t, err)
+        })
+    }
+}
+```
+
+**Split validation tests from execution tests.** A constructor that validates input is tested directly, with no workflow environment — those run in milliseconds:
+
+```go
+func TestNewProcessOrder(t *testing.T) {
+    _, err := newProcessOrder(&pb.OrderInput{}) // empty → invalid
+    require.ErrorContains(t, err, "order_id")
+}
+```
+
+Workflow tests also guard **replay safety**: Temporal replays from event history, so if changed code executes activities in a different order, replay breaks. These tests pin the activity-call sequence for given inputs.
+
+---
+
+## Layer 2: Activity tests
+
+Mock the client interface. Cover, in order: validation errors (caught before any client call), success, then each client error type.
+
+```go
+func TestCreateThingActivity(t *testing.T) {
+    tests := []struct {
+        name      string
+        input     *pb.CreateThingInput
+        clientErr error
+        wantErr   bool
+    }{
+        {name: "error - empty name", input: &pb.CreateThingInput{}, wantErr: true},                                   // validation
+        {name: "success", input: &pb.CreateThingInput{Name: "x"}, wantErr: false},                                    // success
+        {name: "error - already exists", input: &pb.CreateThingInput{Name: "x"}, clientErr: errExists, wantErr: true}, // client error
+    }
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            env := (&testsuite.WorkflowTestSuite{}).NewTestActivityEnvironment()
+            mockClient := mocks.NewMockClient(t)
+
+            // Conditional mock: only expect a client call if validation would pass.
+            if tt.input.Name != "" {
+                mockClient.EXPECT().Create(mock.Anything, tt.input.Name).Return("id-123", tt.clientErr)
+            }
+
+            acts := NewActivities(mockClient)
+            env.RegisterActivity(acts.CreateThing)
+            _, err := env.ExecuteActivity(acts.CreateThing, tt.input)
+
+            if tt.wantErr {
+                require.Error(t, err)
+                return
+            }
+            require.NoError(t, err)
+        })
+    }
+}
+```
+
+**Conditional mocks** are the key pattern: when input is invalid, set no expectations — mockery fails the test if the client is called anyway, which proves the validation layer works.
+
+---
+
+## Layer 3: Client tests (integration)
+
+Real system in a container via [testcontainers-go](https://golang.testcontainers.org), gated by a build tag so normal `go test ./...` skips them:
+
+```go
+//go:build integration
+
+func TestMyServiceClient(t *testing.T) {
+    if testing.Short() {
+        t.Skip("skipping integration test in short mode")
+    }
+    ctx := context.Background()
+    container, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
+        ContainerRequest: testcontainers.ContainerRequest{
+            Image:        "myservice:latest",
+            ExposedPorts: []string{"8080/tcp"},
+            WaitingFor:   wait.ForHTTP("/health").WithPort("8080/tcp"),
+        },
+        Started: true,
+    })
+    require.NoError(t, err)
+    defer container.Terminate(ctx)
+
+    host, _ := container.Host(ctx)
+    port, _ := container.MappedPort(ctx, "8080")
+    client := NewMyServiceClient(fmt.Sprintf("http://%s:%s", host, port.Port()))
+
+    id, err := client.Create(ctx, "my-thing")
+    require.NoError(t, err)
+    require.NotEmpty(t, id)
+}
+```
+
+- The `//go:build integration` tag keeps these out of normal runs; include with `go test -tags=integration ./...`.
+- Start a fresh container per test function; always `defer container.Terminate(ctx)`.
+- Assert against the client's **real error types** (`ErrNotFound`), not test sentinels — this verifies the client translates system error codes correctly.
+
+---
+
+## Mock generation (the proto seam)
+
+Hand-written interfaces can be mocked by hand or with a generator. When the project is **proto-driven**, the activities interface is generated (`XxxActivities` — see [proto-driven.md](./proto-driven.md)), so its mock must be generated too. [mockery](https://vektra.github.io/mockery/) generates both kinds from a `.mockery.yaml`:
+
+```yaml
+with-expecter: true
+packages:
+  github.com/myorg/myproject/gen/myservice/v1:   # generated activities interface → workflow tests
+    interfaces:
+      MyServiceActivities:
+  github.com/myorg/myproject/lib/myservice/v1:    # hand-written client interface → activity tests
+    interfaces:
+      MyServiceClient:
+```
+
+Generated mocks are an **option within** testing — the one proto seam — not a requirement of the three-layer approach.
+
+---
+
+## Key principles
+
+- **Only mock your direct dependency.** Workflow → activities; activity → client. Never reach two layers deep (a workflow must not know about HTTP).
+- **Conditional mocks mirror code flow.** No expectation set for inputs that validation rejects.
+- **Fresh setup per case.** Never share `env` or mock state across table-driven cases.
+- **Test names are documentation.** `"error - empty role name"`, not `"test1"`.

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

@@ -0,0 +1,72 @@
+# types
+
+## Strategy
+
+Types in generated code come from two sources. Each has a different resolution method.
+
+**Types you define** — derived from the `.twf` file. You control the shape; the TWF tells you what fields exist.
+
+**Dependency types** — from external packages. The shape is fixed; you discover it at the call site.
+
+### Defined types
+
+Resolve in priority order:
+
+1. **Explicit signatures** — workflow/activity params and return types name the type directly
+2. **Constructor usage** — `Result{field: value}` reveals struct fields and their types (inferred from the values assigned)
+3. **Field access** — `order.items` implies `Order` has an `items` field; the accessed type propagates from usage context
+4. **Generate** — only for application-specific types with no existing match
+
+### Dependency types
+
+The ground truth is the call site — the method you will call in the activity body.
+
+1. **Identify the method** — which function or method on the dependency will the activity call?
+2. **Read the method signature** — `go doc <package>.Method` gives you the exact parameter and return types. If `go doc` is unavailable (dependency not yet in `go.mod`, docs sparse, or offline), fall back to: read source on pkg.go.dev, inspect the dependency source directly, or ask the user
+3. **Read each parameter type** — `go doc <package>.ParamType` gives you the fields you need to populate. Verify every field type the same way — the field name alone can be misleading (e.g., a `Tools` field may accept a union wrapper type, not the type you'd guess from the name)
+4. **Follow the chain until you reach primitives or types you recognize** — stop when every type in the call is verified
+
+Dependency APIs are version-specific — verify types against the version in `go.mod`, not trained knowledge. A dependency is resolved when you can write the full call expression with concrete types:
+```
+client.Messages.New(ctx, anthropic.MessageNewParams{
+    Model:    anthropic.Model(model),     // verified: Model is a string typedef
+    Messages: []anthropic.MessageParam{}, // verified: not []Message
+    Tools:    []anthropic.ToolUnionParam{}, // verified: not []ToolParam
+})
+```
+
+### Serialization boundaries
+
+Workflow and activity parameters pass through Temporal's data converter (JSON by default). Types you define are safe — you control their fields and they round-trip cleanly. Dependency types may have custom marshaling, unexported fields, or non-JSON-safe constructs.
+
+**Keep dependency types inside activity bodies.** Expose your own types in workflow/activity signatures and convert to dependency types within the activity implementation. This keeps the serialization boundary clean and decouples your workflow logic from any single dependency.
+
+## Go
+
+```go
+// From explicit signature: activity ValidateOrder(order: Order) -> (ValidateResult)
+type Order struct { /* fields derived from usage */ }
+type ValidateResult struct { /* fields derived from constructor */ }
+
+// From constructor: Result{status: "completed", trackingId: reservation.trackingId}
+type Result struct {
+    Status     string
+    TrackingId string
+}
+
+// Primitive mapping
+// string   → string
+// int      → int
+// decimal  → float64
+// bool     → bool
+// []Type   → []Type
+// duration → time.Duration (e.g., 5m → 5*time.Minute)
+// time     → time.Time
+```
+
+## Notes
+
+- Collect all constructor sites and field accesses across the `.twf` file before defining a type — a type used in multiple places may reveal different fields in each
+- When a field's type is ambiguous (e.g., assigned from an untyped expression), leave a `// TODO` comment and ask the user
+- Generic containers: `Map[K]V` → `map[K]V`, `[]Item` → `[]Item`
+- Export all struct fields (uppercase) — these cross workflow/activity boundaries via serialization