@temporal-architect/claude-plugin 0.9.0

package/skills/temporal-architect-design/topics/signals-queries-updates.twf

@@ -0,0 +1,234 @@
+# Source: signals-queries-updates.md
+# Patterns: signal/query/update declarations, watch blocks, approval flows
+
+# --- Signal-driven order workflow ---
+
+workflow OrderTrackingWorkflow(orderId: string) -> (OrderResult):
+    signal PaymentReceived(transactionId: string, amount: decimal):
+        status = "payment_received"
+        lastTransactionId = transactionId
+
+    query GetStatus() -> (string):
+        return status
+
+    query GetProgress() -> (Progress):
+        return Progress{status: status, orderId: orderId}
+
+    activity LoadOrderRecord(orderId) -> order
+
+    status = "validating"
+    activity ValidateOrderRecord(order)
+
+    status = "awaiting_payment"
+
+    # Wait for payment signal with timeout
+    await one:
+        signal PaymentReceived:
+            status = "completed"
+            close complete(OrderResult{status: "completed"})
+        timer(24h):
+            status = "payment_timeout"
+            close fail(OrderResult{status: "payment_timeout"})
+
+# --- Approval flow with multi-target await ---
+
+workflow ApprovalWorkflow(request: Request) -> (Decision):
+    signal Approved(approver: string):
+        approved = true
+        approver_name = approver
+
+    signal Rejected(approver: string, reason: string):
+        rejected = true
+        reject_reason = reason
+
+    approved = false
+    rejected = false
+    approver_name = ""
+    reject_reason = ""
+
+    activity NotifyApprovers(request)
+
+    # Wait for either Approved or Rejected signal, or timeout
+    await one:
+        signal Approved:
+            close complete(Decision{status: "approved", approver: approver_name})
+        signal Rejected:
+            close fail(Decision{status: "rejected", reason: reject_reason})
+        timer(7d):
+            activity NotifyExpired(request)
+            close fail(Decision{status: "expired"})
+
+# --- Batch collector with signal accumulation ---
+
+workflow BatchCollector(batchId: string) -> (BatchResult):
+    signal AddItem(item: Item):
+        itemCount = itemCount + 1
+
+    signal CompleteBatch():
+        completed = true
+
+    itemCount = 0
+    completed = false
+
+    for:
+        await one:
+            signal CompleteBatch:
+                break
+            timer(1h):
+                break
+
+    activity RunBatchProcessing(batchId, itemCount) -> result
+    close complete(BatchResult{itemCount: itemCount, result: result})
+
+# --- Update-driven subscription workflow ---
+# Updates are read-write: caller sends data and blocks for a result.
+
+workflow SubscriptionWorkflow(userId: string):
+    signal Cancel():
+        cancelled = true
+
+    # Simple update: immediate state mutation + return
+    update AddCredits(amount: int) -> (CreditResult):
+        credits = credits + amount
+        return CreditResult{total: credits}
+
+    # Update with activity: validates before mutating, caller blocks for the full round-trip
+    update ChangePlan(newPlan: string) -> (ChangeResult):
+        activity ValidatePlan(newPlan) -> validation
+        if (validation.valid):
+            plan = newPlan
+            return ChangeResult{success: true, plan: plan}
+        else:
+            return ChangeResult{success: false, error: validation.reason}
+
+    query GetPlan() -> (string):
+        return plan
+
+    plan = "free"
+    credits = 0
+    cancelled = false
+
+    for:
+        await one:
+            signal Cancel:
+                break
+            timer(30d):
+                activity BillUser(userId, plan)
+
+    close complete
+
+# --- Shipping workflow: update racing in await one ---
+# Shows update as an await one case competing with a timer.
+
+workflow ShippingWorkflow(orderId: string) -> (ShipResult):
+    update ChangeAddress(newAddress: Address) -> (AddressResult):
+        address = newAddress
+        return AddressResult{updated: true}
+
+    query GetAddress() -> (Address):
+        return address
+
+    activity LoadOrderRecord(orderId) -> order
+    address = order.shippingAddress
+
+    # Race: accept address changes until the cutoff window closes
+    await one:
+        update ChangeAddress:
+            activity NotifyShippingUpdate(orderId, address)
+        timer(1h):
+            activity FinalizeShipping(orderId, address)
+
+    activity Ship(orderId, address) -> shipment
+    close complete(ShipResult{shipment: shipment})
+
+# --- Update handler waiting on condition ---
+# Shows the condition + update handler pattern where the caller blocks
+# until the condition is set by the main workflow body.
+
+workflow JobCoordinator(config: JobConfig):
+    state:
+        condition jobReady
+
+    signal Shutdown():
+        shutdownRequested = true
+
+    update WaitUntilReady() -> (JobState):
+        await jobReady
+        return JobState{ready: true}
+
+    query GetStatus() -> (string):
+        return status
+
+    status = "provisioning"
+    activity ProvisionJobRunner(config)
+    activity StartJobRunner(config)
+    set jobReady
+    status = "running"
+
+    await signal Shutdown
+    close complete
+
+# --- Supporting activities ---
+
+activity LoadOrderRecord(orderId: string) -> (Order):
+    return db.get(orderId)
+
+activity ValidateOrderRecord(order: Order):
+    validate(order)
+
+activity NotifyApprovers(request: Request):
+    notify_approvers(request)
+
+activity NotifyExpired(request: Request):
+    notify_expired(request)
+
+activity RunBatchProcessing(batchId: string, count: int) -> (BatchResult):
+    return process(batchId, count)
+
+activity BillUser(userId: string, plan: string):
+    bill(userId, plan)
+
+activity ValidatePlan(plan: string) -> (Validation):
+    return validate_plan(plan)
+
+activity NotifyShippingUpdate(orderId: string, address: Address):
+    notify_shipping(orderId, address)
+
+activity FinalizeShipping(orderId: string, address: Address):
+    finalize(orderId, address)
+
+activity Ship(orderId: string, address: Address) -> (Shipment):
+    return ship(orderId, address)
+
+activity ProvisionJobRunner(config: JobConfig):
+    provision(config)
+
+activity StartJobRunner(config: JobConfig):
+    start(config)
+
+# --- Worker and namespace ---
+
+worker handlerWorker:
+    workflow OrderTrackingWorkflow
+    workflow ApprovalWorkflow
+    workflow BatchCollector
+    workflow SubscriptionWorkflow
+    workflow ShippingWorkflow
+    workflow JobCoordinator
+    activity LoadOrderRecord
+    activity ValidateOrderRecord
+    activity NotifyApprovers
+    activity NotifyExpired
+    activity RunBatchProcessing
+    activity BillUser
+    activity ValidatePlan
+    activity NotifyShippingUpdate
+    activity FinalizeShipping
+    activity Ship
+    activity ProvisionJobRunner
+    activity StartJobRunner
+
+namespace handlers:
+    worker handlerWorker
+        options:
+            task_queue: "handlers"

package/skills/temporal-architect-design/topics/task-queues.md

@@ -0,0 +1,205 @@
+# Workers, Task Queues, and Deployment Topology
+
+> **Example:** [`task-queues.twf`](./task-queues.twf)
+
+Workers group type registrations. Task queues route work to workers. Namespaces instantiate workers with deployment options. Together they answer: **what runs together, how work reaches it, and where it's deployed.**
+
+---
+
+## Worker Type Sets
+
+Workers are reusable type sets that list which workflows, activities, and nexus services belong together:
+
+```twf
+worker orderTypes:
+    workflow ProcessOrder
+    workflow CancelOrder
+    activity ChargePayment
+    activity SendNotification
+
+worker paymentTypes:
+    activity ChargePayment
+    activity GetPaymentStatus
+    nexus service PaymentService
+```
+
+Workers contain only type references — no deployment config. Naming: `lowerCamelCase`.
+
+---
+
+## Namespace Instantiation
+
+Namespaces instantiate workers with deployment options (task queue, versioning strategy, and more — see [Worker Options](#worker-options) below) and expose nexus endpoints for external callers:
+
+```twf
+namespace ecommerce:
+    worker orderTypes
+        options:
+            task_queue: "orderProcessing"
+            max_concurrent_activity_executions: 50
+    worker paymentTypes
+        options:
+            task_queue: "payments"
+    # Nexus endpoint lives in the target namespace alongside the worker that serves it.
+    # External callers in other namespaces reach PaymentService via this endpoint.
+    nexus endpoint PaymentEndpoint
+        options:
+            task_queue: "payments"
+```
+
+The same worker type set can be reused across namespaces:
+
+```twf
+namespace staging:
+    worker orderTypes
+        options:
+            task_queue: "staging-orders"
+```
+
+### Worker Options
+
+The worker `options:` block is the **union of SDK worker options**, accepted *permissively* — the parser does no per-language validation, so an option a given SDK lacks is still allowed. Use it to express **strategy and intent at design altitude**, not exhaustive numeric ops tuning (exact poller counts and cache TTLs belong in implementation):
+
+- **`task_queue`** (required) — routing; pins the worker pool.
+- **`versioning: none | build_id | deployment`** — the worker-versioning *strategy* a pool follows (see [versioning.md](./versioning.md#declaring-the-strategy-in-twf)). A reliability/availability decision the design should make; concrete Build IDs / deployment names are deploy-time inputs, not `.twf` content.
+- **`enable_sessions`** — a genuine design call: sessions pin a sequence of activities to one worker (host-affinity for stateful or resource-bound work), distinct from numeric tuning.
+- **Concurrency caps and rate limiters** (`max_concurrent_*`, `*_rate_limit`, sticky cache) are part of the union but are ops tuning — include them only when a workload demands it; the design agent generally should not hand-set them.
+
+The full key list lives in the spec — run `twf spec` or see [`tools/spec/sections/03-workers-and-namespaces.md`](../../../tools/spec/sections/03-workers-and-namespaces.md) — rather than being duplicated here (avoids drift, keeps the design at altitude).
+
+### Nexus Endpoints in Namespaces
+
+A `nexus endpoint` in a namespace declaration exposes a nexus service to callers in other namespaces. The endpoint's `task_queue` must match the queue where a worker with that nexus service is running. See [nexus.md](./nexus.md) for the full cross-namespace pattern.
+
+### What the Resolver Validates
+
+- **Undefined references** — Catch typos (e.g., referencing a workflow or worker that doesn't exist)
+- **Coverage gaps** — Warn when a defined workflow/activity isn't registered on any instantiated worker
+- **Task queue coherence** — Error when different workers on the same queue register different type sets
+- **Missing configuration** — Error when a worker instantiation is missing the required `task_queue` option
+
+### Rules
+
+- Workers contain only `workflow`, `activity`, and `nexus service` entries (type set only, no deployment config)
+- Each worker instantiation in a namespace requires a `task_queue` option
+- Worker names use lowerCamelCase; workflow/activity names keep UpperCamelCase
+- Multiple workers can be instantiated on the same task queue (but must register the same type sets)
+- Workers not instantiated in any namespace produce warnings
+
+---
+
+## Task Queue Design Decisions
+
+### Single vs Multiple Task Queues
+
+| Single Queue | Multiple Queues |
+|--------------|-----------------|
+| Simple deployment | More operational complexity |
+| All workers handle all work | Workers specialize |
+| Scaling affects everything | Scale queues independently |
+| One failure domain | Isolated failure domains |
+
+### When to Use Separate Task Queues
+
+> **Different runtimes do not require different namespaces — use task queues.** GPU workers, licensed-software workers, region-specific workers, and bursty-vs-steady workloads are all *task queue* concerns within a single namespace. Reaching for a namespace per runtime is the misconception that produces namespace-per-worker. See [namespaces.md](../reference/namespaces.md) — the default namespace count is one.
+
+| Use Case | Rationale |
+|----------|-----------|
+| **Different resource requirements** | CPU-heavy vs I/O-heavy work |
+| **Different scaling characteristics** | Bursty vs steady workloads |
+| **Isolation requirements** | Tenant isolation, security boundaries |
+| **Priority handling** | High-priority vs batch processing |
+| **Geographic distribution** | Region-specific workers |
+| **Specialized capabilities** | GPU workers, licensed software |
+
+---
+
+## Task Queue Patterns
+
+### Priority Queues
+
+Separate queues for different priorities:
+
+```twf
+workflow OrderWorkflow(order: Order) -> (Result):
+    if (order.priority == "express"):
+        activity ProcessOrder(order)
+            options:
+                task_queue: "high-priority"
+    else:
+        activity ProcessOrder(order)
+            options:
+                task_queue: "standard"
+```
+
+### Tenant Isolation
+
+Separate queues per tenant:
+
+```twf
+workflow TenantWorkflow(tenantId: string, data: Data) -> (Result):
+    # Route to tenant-specific queue
+    activity ProcessData(data)
+        options:
+            task_queue: "tenant-{tenantId}"
+```
+
+### Capability-Based Routing
+
+Route based on required capabilities:
+
+```twf
+workflow MediaWorkflow(media: Media) -> (Result):
+    if (media.type == "video"):
+        # Needs GPU workers
+        activity TranscodeVideo(media)
+            options:
+                task_queue: "gpu-workers"
+    else:
+        activity ProcessImage(media)
+            options:
+                task_queue: "standard-workers"
+```
+
+### Geographic Routing
+
+Route to region-specific workers:
+
+```twf
+workflow GlobalWorkflow(request: Request) -> (Result):
+    # Route to nearest region
+    activity ProcessLocally(request)
+        options:
+            task_queue: "workers-{request.region}"
+```
+
+---
+
+## Anti-Patterns
+
+### One Queue Per Workflow Type
+
+```twf
+# BAD: Unnecessary complexity — one queue per type
+# Results in many queues, complex deployment
+
+# GOOD: Shared queue unless isolation needed
+# Put related workflows on the same worker and task queue
+```
+
+### Dynamic Queue Names Without Cleanup
+
+```twf
+# BAD: Creates queue per request (never cleaned up)
+workflow Process(requestId: string):
+    activity DoWork()
+        options:
+            task_queue: "request-{requestId}"  # Unbounded queues!
+
+# GOOD: Bounded set of queues
+workflow Process(request: Request):
+    queue = selectQueue(request.priority)  # "high", "medium", "low"
+    activity DoWork()
+        options:
+            task_queue: queue
+```

package/skills/temporal-architect-design/topics/task-queues.twf

@@ -0,0 +1,184 @@
+# Workers, task queues, and deployment topology
+# Demonstrates: worker type sets, namespace instantiation, explicit routing, capability-based queues
+
+# --- Explicit routing + implicit inheritance ---
+
+workflow OrderWorkflow(order: Order) -> (Result):
+    # Implicit: inherits OrderWorkflow's queue ("orders")
+    activity ValidateOrder(order) -> validated
+
+    # Explicit: route to dedicated payment workers
+    activity ChargePayment(order) -> payment
+        options:
+            task_queue: "payments"
+
+    # Explicit: conditional routing by shipping priority
+    if (order.priority == "express"):
+        activity ShipOrder(order, payment) -> shipment
+            options:
+                task_queue: "shipping-express"
+    else:
+        activity ShipOrder(order, payment) -> shipment
+            options:
+                task_queue: "shipping-standard"
+
+    close complete(Result{shipment})
+
+# --- Capability-based routing ---
+
+workflow MediaPipeline(media: Media) -> (Result):
+    # Explicit: route to GPU-capable workers
+    activity TranscodeVideo(media) -> transcoded
+        options:
+            task_queue: "gpu-transcode"
+            start_to_close_timeout: 10m
+
+    # Implicit: inherits MediaPipeline's queue ("media")
+    activity GenerateThumbnail(transcoded) -> thumb
+
+    close complete(Result{thumb})
+
+# --- Activities ---
+
+activity ValidateOrder(order: Order) -> (ValidationResult):
+    return validate(order)
+
+activity ChargePayment(order: Order) -> (Payment):
+    return charge(order)
+
+activity ShipOrder(order: Order, payment: Payment) -> (Shipment):
+    return ship(order)
+
+activity TranscodeVideo(media: Media) -> (TranscodeResult):
+    heartbeat(media.progress)
+    return transcode(media)
+
+activity GenerateThumbnail(video: Video) -> (Thumbnail):
+    return thumbnail(video)
+
+# --- Nexus services (exposed for external callers in other namespaces) ---
+
+# PaymentService: registered on paymentWorker, exposed via PaymentEndpoint in ecommerce namespace.
+# External callers (e.g., partner namespace below) reach it cross-namespace via the endpoint.
+nexus service PaymentService:
+    sync CheckPaymentStatus(paymentId: string) -> (PaymentStatus):
+        activity GetPaymentStatus(paymentId) -> status
+        close complete(status)
+
+# AnalyticsService: independent scaling on its own worker, same cross-namespace exposure pattern.
+nexus service AnalyticsService:
+    async TrackEvent workflow TrackEventWorkflow
+
+activity GetPaymentStatus(paymentId: string) -> (PaymentStatus):
+    return lookup(paymentId)
+
+workflow TrackEventWorkflow(event: Event):
+    activity RecordEvent(event)
+    close complete
+
+activity RecordEvent(event: Event):
+    record(event)
+
+# --- Workers ---
+
+worker orderWorker:
+    workflow OrderWorkflow
+    activity ValidateOrder
+
+worker paymentWorker:
+    activity ChargePayment
+    activity GetPaymentStatus
+    nexus service PaymentService
+
+worker analyticsWorker:
+    workflow TrackEventWorkflow
+    activity RecordEvent
+    nexus service AnalyticsService
+
+worker expressShipWorker:
+    activity ShipOrder
+
+worker standardShipWorker:
+    activity ShipOrder
+
+# Tiered registration: a workflow or nexus service hosted on multiple
+# workers, each on its OWN task queue (same pattern as expressShipWorker
+# / standardShipWorker above). The registered type set is shared across
+# the tier so the caller picks behaviour by routing to the right queue —
+# realtime vs batch analytics here, primary vs DR-region payments below.
+worker realtimeAnalyticsWorker:
+    workflow TrackEventWorkflow
+    activity RecordEvent
+
+worker paymentWorkerSecondary:
+    activity ChargePayment
+    activity GetPaymentStatus
+    nexus service PaymentService
+
+worker mediaWorker:
+    workflow MediaPipeline
+    activity GenerateThumbnail
+
+worker gpuWorker:
+    activity TranscodeVideo
+
+# --- Namespaces ---
+
+namespace ecommerce:
+    worker orderWorker
+        options:
+            task_queue: "orders"
+    worker paymentWorker
+        options:
+            task_queue: "payments"
+    # Same registered type set as paymentWorker, on its own queue —
+    # callers route by region by picking the destination task queue.
+    worker paymentWorkerSecondary
+        options:
+            task_queue: "payments-secondary"
+    worker expressShipWorker
+        options:
+            task_queue: "shipping-express"
+    worker standardShipWorker
+        options:
+            task_queue: "shipping-standard"
+    # Endpoints live in the target namespace (ecommerce) alongside the workers that serve them.
+    # External callers in other namespaces (e.g., partner) reach these services cross-namespace.
+    nexus endpoint PaymentEndpoint
+        options:
+            task_queue: "payments"
+    worker analyticsWorker
+        options:
+            task_queue: "analytics"
+    # Same registered type set as analyticsWorker, on its own queue —
+    # callers pick the realtime tier by dispatching to this queue.
+    worker realtimeAnalyticsWorker
+        options:
+            task_queue: "analytics-realtime"
+    nexus endpoint AnalyticsEndpoint
+        options:
+            task_queue: "analytics"
+
+namespace media:
+    worker mediaWorker
+        options:
+            task_queue: "media"
+    worker gpuWorker
+        options:
+            task_queue: "gpu-transcode"
+
+# --- Cross-namespace caller ---
+# A partner service in a separate namespace reaches into ecommerce via Nexus endpoints.
+
+workflow PartnerCheckout(request: PartnerRequest) -> (PartnerResult):
+    nexus PaymentEndpoint PaymentService.CheckPaymentStatus(request.paymentId) -> status
+    detach nexus AnalyticsEndpoint AnalyticsService.TrackEvent(request.event)
+    close complete(PartnerResult{status: status})
+
+worker partnerWorker:
+    workflow PartnerCheckout
+
+namespace partner:
+    worker partnerWorker
+        options:
+            task_queue: "partner"