@temporal-architect/claude-plugin 0.9.0

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

@@ -0,0 +1,64 @@
+# update handler
+
+## DSL
+
+```twf
+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}
+```
+
+## Go
+
+```go
+err := workflow.SetUpdateHandlerWithOptions(ctx, "ChangePlan",
+    func(ctx workflow.Context, newPlan string) (ChangeResult, error) {
+        var validation Validation
+        err := workflow.ExecuteActivity(ctx, ValidatePlan, newPlan).Get(ctx, &validation)
+        if err != nil {
+            return ChangeResult{}, err
+        }
+        if validation.Valid {
+            plan = newPlan
+            return ChangeResult{Success: true, Plan: plan}, nil
+        }
+        return ChangeResult{Success: false, Error: validation.Reason}, nil
+    },
+    workflow.UpdateHandlerOptions{},
+)
+if err != nil {
+    return Result{}, err
+}
+```
+
+## Notes
+
+- Update handlers receive `workflow.Context` as first param (unlike queries) — they can call activities and use temporal primitives
+- Update handlers can modify workflow state (unlike queries)
+- The caller blocks until the handler returns
+- Update handlers cannot call `close` — only the main workflow body can terminate the workflow
+- Register updates at the very start of the workflow function, before any blocking calls
+
+## Validators
+
+- Set via `workflow.UpdateHandlerOptions{Validator: func(...) error{...}}` in `SetUpdateHandlerWithOptions`
+- **Validators reject updates before History write.** If the validator returns an error, no events are recorded — the update "disappears." The caller receives an "Update failed" error
+- **Handler errors are post-acceptance.** Once the validator passes (or is absent), `WorkflowExecutionUpdateAccepted` is written. If the handler then returns an error, `WorkflowExecutionUpdateCompleted` records the failure — but the acceptance event persists
+- The validator function has the same parameter types as the handler but returns only `error`. It may optionally include or omit `workflow.Context` as the first parameter
+- **Validators must not mutate workflow state** — no variable assignment, no scheduling activities, no side-effects. They may read workflow state
+- **Validators must not block** — same restriction as query handlers
+- A panic in a validator is treated as a rejection (equivalent to returning an error)
+
+## Pitfalls
+
+- **Missing validator.** The example above performs validation via an activity inside the handler — this is post-acceptance validation. To reject invalid updates without writing to History, add a validator
+- **Handler lifetime vs workflow completion.** Default `HandlerUnfinishedPolicy` is `WarnAndAbandon` — if the workflow completes or calls Continue-As-New while an update handler is still running, the handler is abandoned and the caller receives `ServiceError` "workflow execution already completed"
+- To avoid abandoned handlers, wait before exiting:
+  ```go
+  err = workflow.Await(ctx, func() bool { return workflow.AllHandlersFinished(ctx) })
+  ```
+- **Continue-As-New during handler execution.** The caller gets "workflow execution already completed." The update is lost. Drain handlers before CAN

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

@@ -0,0 +1,215 @@
+# worker
+
+## DSL
+
+```twf
+worker orderTypes:
+    workflow ProcessOrder
+    activity ValidateOrder
+    activity ChargePayment
+
+namespace default:
+    worker orderTypes
+        options:
+            task_queue: "orders"
+```
+
+## Go
+
+```go
+import (
+    "log"
+
+    "go.temporal.io/sdk/client"
+    "go.temporal.io/sdk/worker"
+)
+
+func main() {
+    c, err := client.Dial(client.Options{})
+    if err != nil {
+        log.Fatalln("Unable to create client", err)
+    }
+    defer c.Close()
+
+    w := worker.New(c, "orders", worker.Options{})
+
+    w.RegisterWorkflow(ProcessOrder)
+    w.RegisterActivity(&Activities{/* dependencies */})
+
+    err = w.Run(worker.InterruptCh())
+    if err != nil {
+        log.Fatalln("Unable to start worker", err)
+    }
+}
+```
+
+## Notes
+
+- `worker.New(client, taskQueue, options)` — task queue comes from namespace `options: task_queue`
+- `RegisterWorkflow(func)` — one call per workflow in the worker's type set
+- `RegisterActivity(struct)` — register the activity struct (all exported methods become activities) or individual functions
+- `worker.InterruptCh()` for graceful shutdown on SIGINT/SIGTERM
+- Multiple `worker` blocks in the DSL with different task queues → multiple `worker.New` calls in the same `main()`
+- For nexus services on the same worker, see [nexus-service-def.md](./nexus-service-def.md)
+
+## When to use: struct vs function registration
+
+- **Struct registration** (`w.RegisterActivity(&Activities{...})`): standard pattern. All exported methods on the struct become activities. Use when activities share dependencies (DB connections, API clients) injected via the struct
+- **Individual function registration** (`w.RegisterActivity(SomeFunc)`): use when activities span multiple structs with different dependency sets, or for standalone functions with no dependencies
+- `RegisterActivityWithOptions` with `Name` sets a prefix for struct methods or overrides the name for individual functions
+- Registration panics if two activities share the same type name. Use `DisableAlreadyRegisteredCheck: true` in tests only
+- If a struct has exported methods that don't match the activity signature `(context.Context, ...) (..., error)`, registration panics. Set `SkipInvalidStructFunctions: true` to skip them
+
+### Nil-pointer method binding
+
+Workflow bodies reference an activity by **method value on a nil struct pointer** so the call is type-checked and the name is derived from the method — no string literal:
+
+```go
+var a *Activities // nil; never dereferenced — only its method value is taken
+workflow.ExecuteActivity(ctx, a.ChargePayment, order).Get(ctx, &receipt)
+```
+
+The worker must still register a **real, fully-constructed** instance (`w.RegisterActivity(&Activities{db: db})`). The nil pointer in the workflow only names the activity; the registered instance is what actually runs. The two must name the same type.
+
+## Dependency injection into activity structs
+
+Activities reach external systems through dependencies held on the struct. Construct the struct with its dependencies at startup and register it:
+
+```go
+acts := &Activities{db: db, payments: paymentsClient}
+w.RegisterActivity(acts)
+```
+
+In larger apps this is wired with `fx` (an `fx.go` per package provides the client and the activities struct, and a registration function calls `w.RegisterActivity` / the generated helper). Keep construction at the composition root — workflows and activity bodies never build their own dependencies.
+
+## Proto-driven registration
+
+When the project is [proto-driven](./proto-driven.md), the generator emits registration helpers — use them instead of hand-registering each type:
+
+```go
+pb.RegisterMyServiceActivities(w, acts)   // registers every activity on the service at once
+pb.RegisterMyServiceWorkflows(w, wfs)     // if the service declares workflows
+```
+
+A missing helper call is the proto-driven form of an unregistered type: the worker starts fine and fails the task at runtime.
+
+## Nexus service registration
+
+Register a Nexus service on the **handler** worker (the target namespace's worker), alongside its handler workflows:
+
+```go
+service := nexus.NewService(BillingServiceName)
+_ = service.Register(ChargePaymentOperation)
+w.RegisterNexusService(service)
+w.RegisterWorkflow(BillingChargeWorkflow) // handler workflows must also be registered
+```
+
+Creating the Nexus **endpoint** that routes to this service is out-of-band infrastructure (`tcld` / Terraform), not worker code — that belongs to a future `author-infra` skill. See [nexus-service-def.md](./nexus-service-def.md) for the handler/operation patterns.
+
+## Graceful shutdown
+
+`worker.InterruptCh()` stops the worker cleanly on SIGINT/SIGTERM, draining in-flight tasks:
+
+```go
+if err := w.Run(worker.InterruptCh()); err != nil {
+    log.Fatalln("worker stopped", err)
+}
+```
+
+Close the Temporal client (`defer c.Close()`) and any injected dependencies (DB pools, external clients) after `Run` returns.
+
+## Registration coverage & the TWF↔Go bridge
+
+**Coverage reality:**
+
+- An **unregistered type fails the task, not the workflow.** The task returns to the queue for another worker; the workflow itself does not fail, but latency and wasted resources accumulate. This silent degradation is why coverage matters.
+- **All workers on the same task queue must register the identical Workflow Type and Activity Type set.** A partial set on one worker means tasks intermittently land on a worker that can't run them.
+- Multiple DSL `worker` blocks with different type sets must use **different task queues**.
+
+**The TWF↔Go bridge:** the design-time topology maps directly onto worker wiring —
+
+| TWF | Go |
+|-----|-----|
+| `worker Name:` (its workflow/activity members) | the registered type set on one `worker.New` |
+| `namespace` + `task_queue` option | `worker.New(client, taskQueue, ...)` |
+
+The resolver previews coverage gaps **at design time**: `UNCOVERED_WORKFLOW` / `UNCOVERED_ACTIVITY` / `UNCOVERED_SERVICE` flag a type no worker covers, and `IMPLICIT_ROUTING_MISMATCH` flags a routing mismatch. Treat a clean resolve as the design-time analog of full registration. These same codes are also a **reverse-reading signal**: when recovering a `.twf` from existing Go, the registered set on each `worker.New` is what populates each `worker` block.
+
+## Worker options → `worker.Options`
+
+Worker tuning now lives in the namespace `options:` block — the SDK-union worker-options set (concurrency caps, rate limiters, sticky cache, versioning). Map each key onto a `worker.Options` field rather than keeping it out of the `.twf`:
+
+| TWF worker option | `worker.Options` field | Go type |
+|-------------------|------------------------|---------|
+| `task_queue` | 2nd arg to `worker.New` (not a field) | string |
+| `max_concurrent_activity_executions` | `MaxConcurrentActivityExecutionSize` | int |
+| `max_concurrent_workflow_task_executions` | `MaxConcurrentWorkflowTaskExecutionSize` | int |
+| `max_concurrent_local_activity_executions` | `MaxConcurrentLocalActivityExecutionSize` | int |
+| `max_concurrent_nexus_task_executions` | `MaxConcurrentNexusTaskExecutionSize` | int |
+| `max_concurrent_workflow_task_pollers` | `MaxConcurrentWorkflowTaskPollers` | int |
+| `max_concurrent_activity_task_pollers` | `MaxConcurrentActivityTaskPollers` | int |
+| `max_concurrent_nexus_task_pollers` | `MaxConcurrentNexusTaskPollers` | int |
+| `worker_activity_rate_limit` | `WorkerActivitiesPerSecond` | float64 |
+| `task_queue_activity_rate_limit` | `TaskQueueActivitiesPerSecond` | float64 |
+| `worker_local_activity_rate_limit` | `WorkerLocalActivitiesPerSecond` | float64 |
+| `sticky_schedule_to_start_timeout` | `StickyScheduleToStartTimeout` | time.Duration |
+| `heartbeat_throttle_interval` | `MaxHeartbeatThrottleInterval` | time.Duration |
+| `worker_identity` | `Identity` | string |
+| `worker_shutdown_timeout` | `WorkerStopTimeout` | time.Duration |
+| `local_activity_only_mode` | `LocalActivityWorkerOnly` | bool |
+| `enable_sessions` | `EnableSessionWorker` | bool |
+| `max_concurrent_session_executions` | `MaxConcurrentSessionExecutionSize` | int |
+| `max_cached_workflows` | **not** a `worker.Options` field — process-global via `worker.SetStickyWorkflowCacheSize(n)` | int |
+| `versioning` | not 1:1 — see below | enum |
+
+Example — a namespace worker carrying a couple of options:
+
+```twf
+namespace orders:
+    worker orderTypes
+        options:
+            task_queue: "orders"
+            max_concurrent_activity_executions: 50
+            enable_sessions: true
+```
+
+maps to:
+
+```go
+w := worker.New(c, "orders", worker.Options{
+    MaxConcurrentActivityExecutionSize: 50,
+    EnableSessionWorker:                true,
+})
+```
+
+> **Permissive-union caveat:** the DSL worker-options set is the SDK *union* accepted permissively, so a `.twf` may carry a key the Go SDK has no field for (a per-language one-off). When a key has no `worker.Options` field, **drop it — do not invent an API.** The richer versioning model (ramping, per-namespace-vs-per-worker placement) stays deferred in `internal/changes/dsl/BACKLOG.md`.
+
+### `versioning` (not 1:1)
+
+The DSL `versioning` enum carries *strategy*, not identifiers. Concrete Build ID / deployment name / version are **deploy-time inputs from config/env** — never fabricate them into generated code.
+
+- `none` → no versioning fields (default unversioned worker).
+- `build_id` → **legacy** path (the SDK marks these **Deprecated** in favor of `DeploymentOptions`):
+
+```go
+worker.Options{
+    BuildID:                 buildID, // from env/config, not the .twf
+    UseBuildIDForVersioning: true,
+}
+```
+
+- `deployment` → **current** path:
+
+```go
+worker.Options{
+    DeploymentOptions: worker.DeploymentOptions{
+        UseVersioning: true,
+        Version: worker.WorkerDeploymentVersion{
+            DeploymentName: deploymentName, // from env/config
+            BuildId:        buildID,        // from env/config
+        },
+    },
+}
+```
+
+> **Pitfall — mutual exclusion:** worker versioning (`UseBuildIDForVersioning` or `DeploymentOptions.UseVersioning`) **cannot** be enabled together with `EnableSessionWorker`. A `.twf` carrying both `versioning: build_id|deployment` and `enable_sessions: true` cannot map to one `worker.Options` — surface it as a conflict; do not silently pick one.

package/skills/temporal-architect-author-go/reference/workflow-call.md

@@ -0,0 +1,37 @@
+# workflow call (child)
+
+## DSL
+
+```twf
+workflow ShipOrder(order) -> shipResult
+```
+
+## Go
+
+```go
+var shipResult ShipResult
+err := workflow.ExecuteChildWorkflow(ctx, ShipOrder, order).Get(ctx, &shipResult)
+if err != nil {
+    return Result{}, err
+}
+```
+
+## Notes
+
+- The child workflow function is passed by reference — `workflow.ExecuteChildWorkflow(ctx, FuncName, args...)`
+- `ctx` must carry child workflow options; see [options.md](./options.md) for setting `ChildWorkflowOptions`
+- For fire-and-forget, see [detach.md](./detach.md)
+- For cross-namespace, see [nexus.md](./nexus.md)
+
+## When to use
+
+- **Use a child workflow when:** the sub-process needs its own event history (parent history has a 51,200 event / 50 MB limit), independent retry/timeout policies, a different task queue, separate cancellation scope (via `ParentClosePolicy`), or represents a composite operation orchestrating multiple steps
+- **Use an activity when:** the operation is a single action on an external system (API call, DB write, message send). "When in doubt, use an Activity" — Temporal's official recommendation
+- Activities add events to the parent's history; child workflows get their own independent history
+- Child workflows cannot share state with the parent — communication is through signals only
+- Do NOT use child workflows solely for code organization — use Go packages and functions instead
+
+## Pitfalls
+
+- Default `ParentClosePolicy` is `TERMINATE` (child is killed immediately) — if the parent completes, fails, or times out, the child is forcefully terminated. Set `REQUEST_CANCEL` (child receives a cancellation request and can handle it gracefully) or `ABANDON` (child continues running independently) explicitly when the child should outlive the parent. See [options.md](./options.md) for the DSL-to-Go mapping
+- If the parent completes before the `ChildWorkflowExecutionStarted` event is recorded, the child may never spawn. Always call `childFuture.GetChildWorkflowExecution().Get(ctx, nil)` to confirm the child started — see [detach.md](./detach.md)

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

@@ -0,0 +1,45 @@
+# workflow definition
+
+## DSL
+
+```twf
+workflow ProcessOrder(order: Order) -> (Result):
+    # body
+    close complete(Result{status: "done"})
+```
+
+## Go
+
+```go
+import "go.temporal.io/sdk/workflow"
+
+func ProcessOrder(ctx workflow.Context, order Order) (Result, error) {
+    // body
+    return Result{Status: "done"}, nil
+}
+```
+
+## Notes
+
+- Every workflow returns `error` as the last return value, even if the DSL has no return type (signature becomes `func Name(ctx workflow.Context, params...) error`)
+- `workflow.Context` is always the first parameter
+- Multiple return types `-> (A, B)` → `func Name(ctx workflow.Context, ...) (A, B, error)`
+
+## Determinism constraints
+
+Workflow functions must be deterministic — every replay must produce the same commands in the same order. Violating determinism causes a non-deterministic error: the Workflow Task fails and retries indefinitely until the code is fixed.
+
+**Forbidden in workflow code:**
+- `time.Now()` → use `workflow.Now(ctx)`
+- `time.Sleep()` → use `workflow.Sleep(ctx, duration)`
+- `math/rand`, `crypto/rand` → use `workflow.SideEffect()` or compute in an activity
+- HTTP clients, network calls, file I/O, database access → move to activities
+- `go` keyword → use `workflow.Go(ctx, func(gCtx workflow.Context) { ... })`
+- Native `chan`, `select` → use `workflow.Channel`, `workflow.Selector`
+- `range` over `map` → sort keys first, then iterate
+- Global mutable state → use workflow-local variables or activity results
+- Standard loggers → use `workflow.GetLogger(ctx)`
+
+**Safe changes** (do not break determinism): changing activity/child workflow input values, changing timer durations (except to zero), adding calls that don't produce commands (`workflow.GetInfo()`, `workflow.GetLogger()`).
+
+Use `workflow.GetVersion()` or `workflow.Patched()` to safely modify running workflow definitions.

package/skills/temporal-architect-author-infra/README.md

@@ -0,0 +1,16 @@
+# Skill: Temporal Architect — Infra Authoring
+
+**Goal:** Provision the control-plane resources a validated TWF design depends on — namespaces, Nexus endpoints, and search attributes — as infrastructure-as-code.
+
+**Primary focus:** Topology fidelity. The third implementer of a design, parallel to `author-go`: `author-go` writes the worker code, `author-infra` provisions the resources that code registers against and runs on. Closes the Nexus endpoint registration `author-go` deliberately punts as out-of-band infra.
+
+**Scope:**
+- Produces: applied IaC — Terraform (`temporalio/temporalcloud`) or `tcld` / `temporal operator` CLI runbooks
+- Consumes: a validated `.twf` file's deployment topology (`namespace`, `nexus endpoint`, worker task queues)
+- Does not: generate workflow/activity code, make design decisions, or model worker runtime tuning
+
+**Authoritative references:**
+- Temporal Cloud Terraform provider (`temporalio/temporalcloud`) and `tcld` / `temporal operator` CLI docs — current resource and command surface
+- `tools/spec/sections/` — source of truth for the `.twf` topology constructs being provisioned
+
+**Entry point:** `SKILL.md` → Orient (detect Cloud+Terraform vs self-hosted CLI) → the matching `reference/` file

package/skills/temporal-architect-author-infra/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: temporal-architect-author-infra
+description: Provision the control-plane resources a .twf design needs — namespaces, Nexus endpoints, search attributes — via the Temporal Cloud Terraform provider or self-hosted tcld / temporal operator CLI. Use when deploying Temporal infrastructure for a workflow design, not worker code.
+---
+
+# Temporal Architect: Infrastructure Authoring
+
+Provision the **out-of-band control-plane resources** a `.twf` design depends on, using infrastructure-as-code. The primary goal is real, applied infrastructure — namespaces, Nexus endpoints, and search attributes — that the worker code (`author-go`) can register against and run on. Always produce IaC artifacts (`.tf` files or CLI runbooks) as deliverables.
+
+`author-infra` is the **third implementer** of a design, parallel to `author-go`:
+
+```
+design (topology) ──► author-go    (worker code: workflows, activities, registration)
+                 └──► author-infra (provisioning: namespaces, endpoints, search attributes)
+```
+
+The split is deliberate: `author-go` punts Nexus **endpoint** registration ("out-of-band → infra skill") because it is a Terraform/CLI resource, not worker code. This skill closes that gap. Worker code and the resources it runs on are two different artifacts with two different lifecycles.
+
+---
+
+## Core Principles
+
+**Provision only the topology, not the code.** This skill reads the `.twf` deployment topology — `namespace`, `nexus endpoint` (with its `worker_target`), and worker task queues — and provisions the control-plane resources for it. It never generates workflow or activity code; that is `author-go`'s job.
+
+**The `.twf` is the contract.** Resources derive from declared topology, not invented. If a resource needs an input the `.twf` does not model (see [Not-Yet-Modeled `.twf` Intent](#not-yet-modeled-twf-intent)), ask the user — do not guess at access policies or attribute schemas.
+
+**IaC discipline: one owner per resource.** Once a resource is Terraform-managed, manage it *only* through Terraform. Mixing console/CLI edits with Terraform produces drift that the next `terraform plan` will try to revert. For resources that already exist, `import` them into state before managing — never let Terraform try to create a duplicate.
+
+**User as decision-maker.** The skill owns the mechanical mapping (topology → resource blocks); the user owns consequential choices — deployment target, region selection, retention, auth model, and which caller namespaces an endpoint trusts. Surface these as specific options with tradeoffs, not open-ended questions.
+
+---
+
+## Process
+
+### Orient
+
+Before provisioning, resolve **where the infrastructure lands** along two independent axes — the same model as `author-go`.
+
+| Axis | Existing infra | Greenfield |
+|------|----------------|------------|
+| **1. Greenfield vs. existing** | *Detect* — signals below; if any fire, infra already exists | *Ask* the user |
+| **2. Deployment target** | *Detect from the repo* and conform to it | *Ask*; no default — Cloud vs self-hosted is a real decision |
+
+**Cheap detection signals** (check these first — no subagent needed):
+
+- `*.tf` with `temporalio/temporalcloud` in `required_providers` → **Temporal Cloud + Terraform**
+- existing `temporalcloud_namespace` / `temporalcloud_nexus_endpoint` resource blocks → **Temporal Cloud + Terraform** (and candidates for `import`)
+- `tcld` invocations in scripts/CI, or a self-hosted `temporal server` / Helm chart → **self-hosted + `tcld` / `temporal operator`**
+- no infra signals at all → greenfield; *ask* the user which target
+
+**Target → reference routing:**
+
+| Target | Load |
+|--------|------|
+| Temporal Cloud, declarative (Terraform) | [terraform.md](./reference/terraform.md) |
+| CLI, imperative (`tcld` for Cloud, `temporal operator` for self-hosted) | [tcld.md](./reference/tcld.md) |
+
+Route on concrete repo signals, never on a name. Adding a target later (e.g. a `helm.md` for k8s worker deployment) = one reference file + one routing row.
+
+**For existing infra, dispatch the shared `project-discovery` subagent** to scan a **bounded slice** (the `.tf` directory or the namespace in scope — never the whole repo) and return a compact summary of existing providers, resource blocks, namespaces, endpoints, and any `.twf` for this domain. Trigger it deliberately; if the slice is unclear, narrow it with the user first. Its contract lives in [project-discovery-subagent.md](../temporal-architect-design/reference/project-discovery-subagent.md) (owned by the design skill, shared across skills; it scans `.tf` as well as `.twf` and code). Consume its summary — don't re-scan in the main context.
+
+### 1. Read the Topology
+
+From the `.twf` in scope, extract the deployment topology only:
+
+- every `namespace` block and its name
+- every `nexus endpoint` and its `worker_target` (the target namespace + `task_queue` it routes to)
+- worker task queues (they inform each endpoint's `worker_target` and confirm which namespace a worker runs in)
+
+Ignore workflow/activity bodies — they are `author-go`'s concern, not infrastructure.
+
+### 2. Map Topology to Resources
+
+This is the contract from `.twf` to control-plane resources:
+
+| `.twf` construct | Temporal Cloud (Terraform) | Self-hosted (CLI) |
+|------------------|----------------------------|-------------------|
+| `namespace Name:` | `temporalcloud_namespace` | `temporal operator namespace create` / `tcld namespace create` |
+| `nexus endpoint Name` (`worker_target` = namespace + `task_queue`) | `temporalcloud_nexus_endpoint` (`worker_target { namespace_id, task_queue }`) | `tcld nexus endpoint create --target-namespace --target-task-queue` |
+| worker `task_queue` option | informs the endpoint's `worker_target.task_queue`; not itself a resource | same |
+| custom search attribute *(not yet in `.twf` — see below)* | `temporalcloud_namespace_search_attribute` | `temporal operator search-attribute create` |
+| endpoint access policy *(not yet in `.twf` — see below)* | `allowed_caller_namespaces` on the endpoint | `--allow-namespace` / `tcld nexus endpoint allowed-namespace` |
+
+Task queues are **not** standalone resources — they exist implicitly when a worker polls them. The endpoint's `worker_target` is what makes a task queue routable for Nexus.
+
+### 3. Provision + Verify
+
+Follow the target's reference file. Verify with the target's plan/apply (or dry-run) before applying for real:
+
+- **Terraform:** `terraform init` → `terraform plan` (review the diff — especially any unexpected create on a resource that should be imported) → `terraform apply`.
+- **CLI:** run `... list` / `... get` to confirm current state before `create`; re-run after to confirm.
+
+For existing infra, `import` before plan so Terraform manages rather than recreates. See each reference for the import workflow.
+
+After provisioning: present the resources created/changed and how they line up with the `.twf` topology and the worker code's expectations (task queue names must match what `author-go` registered).
+
+---
+
+## Not-Yet-Modeled `.twf` Intent
+
+Two things the infra author needs are **not yet expressible in `.twf`**:
+
+- **Nexus endpoint access policy** — which caller namespaces may invoke an endpoint (`allowed_caller_namespaces` / `--allow-namespace`). Tracked in `dsl/BACKLOG.md` (Nexus Endpoint Access Policy).
+- **Custom search attributes** — namespace-level attribute declarations (name + type). Tracked in `dsl/BACKLOG.md` (Custom Search Attributes).
+
+Until the grammar lands, **ask the user** for these (or read an interim annotation if the project uses one) rather than inventing them. Do not default an endpoint to "allow all callers" or guess attribute types — both are security- and schema-relevant. When the DSL backlog items are promoted, this skill consumes them from the topology like any other resource and the asking step drops away.
+
+---
+
+## Output Conventions
+
+- Terraform: group resources for one `.twf` design into a module or a single `.tf` file alongside the `.twf` (or where the user's IaC lives); never scatter a design's resources across unrelated state.
+- CLI: produce an ordered, idempotent runbook (`list`/`get` guard → `create`) the user can paste or commit, not a one-off transcript.
+- Name resources after their `.twf` identifiers so the topology↔infra mapping stays legible.
+
+---
+
+## Reference Index
+
+Read only the reference for the detected (or chosen) deployment target.
+
+| Target | File |
+|--------|------|
+| Temporal Cloud, declarative — Terraform (`temporalio/temporalcloud`) | [terraform.md](./reference/terraform.md) |
+| Imperative CLI — `tcld` (Cloud) / `temporal operator` (self-hosted) | [tcld.md](./reference/tcld.md) |
+
+Shared:
+
+| Topic | File |
+|-------|------|
+| Bounded-slice repo discovery (existing infra) | [project-discovery-subagent.md](../temporal-architect-design/reference/project-discovery-subagent.md) |
+| Namespace count / boundary decisions (a *design* call, upstream of provisioning) | [namespaces.md](../temporal-architect-design/reference/namespaces.md) |

package/skills/temporal-architect-author-infra/reference/tcld.md

@@ -0,0 +1,112 @@
+# CLI Provisioning (`tcld` / `temporal operator`)
+
+The imperative alternative to Terraform. Two distinct CLIs cover two deployment targets:
+
+| CLI | Target | Use when |
+|-----|--------|----------|
+| `tcld` | **Temporal Cloud** | You want imperative Cloud provisioning without committing to Terraform state. |
+| `temporal operator` | **Self-hosted** OSS cluster | There is no Cloud account — you run your own `temporal server`. |
+
+Prefer [Terraform](./terraform.md) for Temporal Cloud when the project keeps IaC in state; reach for `tcld` for one-off or scripted Cloud changes. For self-hosted there is no Terraform provider, so `temporal operator` is the path.
+
+Whichever CLI: **make the runbook idempotent** — guard every `create` with a `list`/`get` so re-running is safe, and commit the runbook rather than leaving provisioning as an untracked transcript.
+
+---
+
+## Namespaces
+
+**Temporal Cloud (`tcld`):**
+
+```bash
+tcld namespace create \
+  --namespace orders \
+  --region aws-us-east-1 \
+  --retention-days 14 \
+  --auth-method api_key
+```
+
+**Self-hosted (`temporal operator`):**
+
+```bash
+temporal operator namespace create \
+  --namespace orders \
+  --retention 14d
+```
+
+Self-hosted namespaces have no region/auth-method flags — those are Cloud concerns. Retention is `--retention` with a duration (`14d`).
+
+## Custom Search Attributes
+
+**Not yet modeled in `.twf`** — ask the user for the name and type (see SKILL.md → Not-Yet-Modeled Intent).
+
+**Self-hosted (`temporal operator`):**
+
+```bash
+temporal operator search-attribute create \
+  --namespace orders \
+  --name OrderStatus \
+  --type Keyword   # Bool | Datetime | Double | Int | Keyword | KeywordList | Text
+```
+
+**Temporal Cloud:** register via `tcld namespace` configuration or the operator API for the Cloud namespace; the type set is the same.
+
+## Nexus Endpoints
+
+Maps from a `.twf` `nexus endpoint` block. `--target-namespace` + `--target-task-queue` are the endpoint's `worker_target`; `--allow-namespace` is the access policy (**not yet in `.twf`** — ask the user which caller namespaces to trust; do not default to allow-all).
+
+**Temporal Cloud (`tcld`):**
+
+```bash
+# Guard, then create.
+tcld nexus endpoint list
+tcld nexus endpoint create \
+  --name payments-endpoint \
+  --target-namespace payments.<acct> \
+  --target-task-queue payments \
+  --allow-namespace orders.<acct>
+```
+
+Manage the access policy after creation:
+
+```bash
+tcld nexus endpoint allowed-namespace list  --name payments-endpoint
+tcld nexus endpoint allowed-namespace add   --name payments-endpoint --namespace orders.<acct>
+tcld nexus endpoint allowed-namespace set   --name payments-endpoint --namespace orders.<acct>   # replaces the full set
+```
+
+`create` fails if an endpoint of the same name already exists — hence the `list` guard. Use `tcld nexus endpoint update` to change an existing endpoint's target.
+
+**Self-hosted (`temporal operator`):**
+
+```bash
+temporal operator nexus endpoint create \
+  --name payments-endpoint \
+  --target-namespace payments \
+  --target-task-queue payments
+```
+
+Notes:
+- The endpoint `--name` is the identifier caller workflow code uses to invoke the endpoint — it must match the endpoint name in the `.twf` / `author-go` output.
+- The target task queue must match the queue `author-go`'s handler worker polls, or Nexus tasks route nowhere.
+
+---
+
+## Verify
+
+```bash
+# Cloud
+tcld namespace get --namespace orders
+tcld nexus endpoint get --name payments-endpoint
+
+# Self-hosted
+temporal operator namespace describe --namespace orders
+temporal operator nexus endpoint get --name payments-endpoint
+```
+
+Confirm each resource exists and its target task queue matches what the workers register on.
+
+---
+
+## Future: `helm.md`
+
+Self-hosted **worker deployment** (k8s Helm chart) is a natural future variant — a separate reference + one routing row in SKILL.md. It is worker runtime, distinct from the control-plane resources this file provisions.