@temporal-architect/claude-plugin 0.9.0

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

@@ -0,0 +1,125 @@
+# Temporal Cloud + Terraform (`temporalio/temporalcloud`)
+
+Provision Temporal Cloud control-plane resources with the official Terraform provider. This is the target when the repo already has `*.tf` referencing `temporalio/temporalcloud`, or when the user chooses Temporal Cloud for greenfield.
+
+## Provider Setup
+
+```hcl
+terraform {
+  required_providers {
+    temporalcloud = {
+      source  = "temporalio/temporalcloud"
+      version = ">= 0.0.6"
+    }
+  }
+}
+
+provider "temporalcloud" {
+  # api_key = "..."   # prefer the env var below over inlining a secret
+}
+```
+
+Authenticate with a Temporal Cloud API key via the environment — never commit it:
+
+```bash
+export TEMPORAL_CLOUD_API_KEY=<your-secret-key>
+```
+
+## `temporalcloud_namespace`
+
+Maps from a `.twf` `namespace` block.
+
+```hcl
+resource "temporalcloud_namespace" "orders" {
+  name           = "orders"
+  regions        = ["aws-us-east-1"] # cloud-prefixed; 1 region, or 2 for HA replication
+  retention_days = 14
+
+  # Auth: choose ONE model.
+  api_key_auth = true
+  # accepted_client_ca = base64encode(file("${path.module}/ca.pem"))  # mTLS alternative
+
+  namespace_lifecycle = {
+    enable_delete_protection = true # blocks accidental destroy; flip to false before destroying
+  }
+}
+```
+
+Key attributes:
+
+| Attribute | Notes |
+|-----------|-------|
+| `name` | Must start/end alphanumeric, hyphens allowed. The `.twf` namespace name. |
+| `regions` | Cloud-prefixed (`aws-us-east-1`, not `us-east-1`). One region, or two for an HA namespace. **Changing/adding/removing regions on an existing namespace is not supported** — the provider errors. |
+| `retention_days` | Workflow history retention. A deliberate cost/compliance choice — ask the user. |
+| `api_key_auth` vs `accepted_client_ca` | API-key auth or mTLS client CA. Pick the model the workers will use; this must match `author-go`'s client config. |
+| `namespace_lifecycle.enable_delete_protection` | Recommend `true` for anything real. |
+
+## `temporalcloud_namespace_search_attribute`
+
+One resource per custom search attribute. **Not yet modeled in `.twf`** — ask the user for the name and type (see SKILL.md → Not-Yet-Modeled Intent).
+
+```hcl
+resource "temporalcloud_namespace_search_attribute" "order_status" {
+  namespace_id = temporalcloud_namespace.orders.id
+  name         = "OrderStatus"
+  type         = "Keyword" # one of: Bool, Datetime, Double, Int, Keyword, KeywordList, Text (case-insensitive)
+}
+```
+
+## `temporalcloud_nexus_endpoint`
+
+Maps from a `.twf` `nexus endpoint` block. The endpoint's `worker_target` is the `.twf` endpoint's target namespace + `task_queue`; `allowed_caller_namespaces` is the access policy (**not yet in `.twf`** — ask the user which caller namespaces to trust; do not default to allow-all).
+
+```hcl
+resource "temporalcloud_nexus_endpoint" "payments_endpoint" {
+  name        = "payments-endpoint"
+  description = "Service: PaymentsService; Operations: ProcessPayment, GetPaymentStatus"
+
+  worker_target = {
+    namespace_id = temporalcloud_namespace.payments.id # the .twf endpoint's target namespace
+    task_queue   = "payments"                          # the .twf worker_target task_queue
+  }
+
+  allowed_caller_namespaces = [
+    temporalcloud_namespace.orders.id, # caller namespace(s) — the access policy
+  ]
+}
+```
+
+Notes:
+- `name` must match `^[a-zA-Z][a-zA-Z0-9\-]*[a-zA-Z0-9]$` and is the identifier caller workflow code uses to invoke the endpoint — it must match the endpoint name in the `.twf` / `author-go` output.
+- Only a single `worker_target` is supported per endpoint.
+- `allowed_caller_namespaces` is the runtime access control: only listed namespaces may invoke the endpoint.
+
+## Import + Drift Workflow (adopting existing infra)
+
+When the resource already exists in Temporal Cloud, **import it before managing** — otherwise Terraform plans a create and you get a duplicate or an error.
+
+1. Write an empty (or matching) resource block as the import target.
+2. Import using the resource's ID:
+
+```bash
+# Namespace — ID is namespaceid.acctid (or just the namespace id, per UI)
+terraform import temporalcloud_namespace.orders <namespace-id>
+
+# Search attribute — ID is namespaceid.acctid/attrName
+terraform import temporalcloud_namespace_search_attribute.order_status <namespace-id>/OrderStatus
+
+# Nexus endpoint — ID from `tcld nexus endpoint list`
+terraform import temporalcloud_nexus_endpoint.payments_endpoint <endpoint-id>
+```
+
+3. `terraform plan` — reconcile the block to match reality until the plan is clean (no changes). A non-empty plan after import means your HCL diverges from the live resource; fix the HCL, don't apply blindly.
+
+**Drift discipline:** once imported/managed, never edit the resource in the console or via `tcld` — the next `terraform plan` will try to revert it. Terraform is the single owner. Run `terraform plan` in CI to detect drift early.
+
+## Verify
+
+```bash
+terraform init
+terraform plan   # review the diff; an unexpected "create" on a resource that should exist means a missing import
+terraform apply
+```
+
+Confirm the provisioned task queue names match what `author-go`'s workers register on — a mismatch means Nexus tasks route nowhere.

package/skills/temporal-architect-design/README.md

@@ -0,0 +1,16 @@
+# Skill: Temporal Architect — System Design
+
+**Goal:** Guide an AI to design well-structured Temporal systems using `.twf` — making sound architectural decisions about workflow boundaries, activity decomposition, and primitive selection.
+
+**Primary focus:** Judgment. The hard part is not syntax — it's knowing *when* to use each primitive, *where* to draw boundaries, and *how* to model async behavior clearly. This skill teaches those decisions.
+
+**Scope:**
+- Produces: a validated `.twf` design file
+- Consumes: a user's description of the system or process to model
+- Does not: generate Go code (that's `author-go`), implement the parser, or modify the DSL
+
+**Authoritative references:**
+- `tools/spec/sections/` — DSL ground truth; consult for any syntax or construct question (also `twf spec` / `twf spec <slug>`)
+- Temporal docs MCP server — consult for Temporal primitive semantics before making design decisions
+
+**Entry point:** `SKILL.md` → `reference/` on demand → `topics/` for worked examples

package/skills/temporal-architect-design/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: temporal-architect-design
+description: Design Temporal systems — workflows, activities, workers, namespaces, and Nexus — with proper determinism, idempotency, and decomposition in `.twf`. Use when designing or reviewing Temporal architecture, planning workflow/activity boundaries, or decomposing a system into Temporal primitives.
+---
+
+# Temporal Architect: System Design
+
+Design entire Temporal systems using `.twf` (Temporal Workflow Format) — capturing system topology, workflow structure, activity boundaries, and Temporal primitives as a parseable source of truth. Always produce `.twf` files as deliverables, never SDK code.
+
+---
+
+## Design Flow
+
+Core loop: **orient → write TWF → `twf check` → fix/consult → design review → repeat**. Parser errors are design feedback — validate early and often. But a clean `twf check` is a *grammar gate*, not a finished design: it never routes straight to done (see [Design Review](#design-review)).
+
+**Write before you read the reference docs.** Draft TWF from the workflow description even if you're unsure — use `twf check --lenient` while iterating on incomplete designs — it still reports every error, it just exits 0 instead of failing the gate. Consult `notation-reference.md` and the other references only to fix specific errors, not to prepare. **This does not apply to prior project artifacts** (existing `.twf`, `DESIGN.md`): those are requirements — read them first (see [Orient](#orient)).
+
+### Orient
+
+Before drafting, glance for prior work — a quick discovery step, not a research phase:
+
+- existing `.twf` files in the project,
+- prior design docs (`DESIGN.md`, `docs/`-style notes, `archive*/` directories).
+
+If found, read them **as requirements** and enter [Revising an Existing Design](#revising-an-existing-design) rather than drafting from scratch — drafting on top of validated prior work re-derives (and silently diverges from) boundaries someone already debated. When the task is migrating an existing orchestration (Claude-Code → Temporal, cron → Temporal, etc.), the prior artifacts *are* the requirements; discovering and reading them is the first step, not a detour.
+
+**When the source of truth is existing code** (an already-running Temporal app, no design doc — the dominant adoption path), the `.twf` is *recovered from the implementation*, not drafted. This is a distinct, **parallel** path — do not improvise it inline, and do not let it slow the greenfield loop. Trigger it deliberately on a **bounded slice** (one domain at a time, never the whole repo reflexively), dispatch the [project-discovery subagent](./reference/project-discovery-subagent.md) to scan in isolation, and follow [reverse-engineering.md](./reference/reverse-engineering.md) for the mechanics. The reverse path rejoins the core loop at [Design Review](#design-review).
+
+```
+  ┌────────────┐
+  │ Write/Edit │◄────────────────────────┐
+  │ .twf file  │                         │
+  └─────┬──────┘                         │
+        ▼                                │
+  ┌────────────┐                         │
+  │ twf check  │                         │
+  └─────┬──────┘                         │
+        ▼                                │
+   ┌─────────┐   Yes   ┌─────────────┐   │
+   │ Error?  │────────►│ Can fix     │   │
+   └────┬────┘         │ confidently?│   │
+        │No            └──┬───────┬──┘   │
+        │             Yes │       │No    │
+        │                 │       ▼      │
+        │                 │  ┌─────────┐ │
+        │                 │  │ Consult │ │
+        │                 │  │ user    │ │
+        │                 │  └────┬────┘ │
+        │                 └───────┴──────┤
+        ▼                                │
+  ┌───────────────┐                      │
+  │ Design Review │ (fresh-eyes rubric)  │
+  └───────┬───────┘                      │
+          ▼                              │
+     ┌─────────┐   Yes (revise)          │
+     │ Issues? │─────────────────────────┘
+     └────┬────┘
+          │No
+          ▼
+        Done
+```
+
+### Worked Example
+
+**Draft** — write from the description, don't worry about completeness:
+
+```twf
+workflow ProcessOrder(order: Order) -> (OrderResult):
+    activity ValidateOrder(order) -> validated
+    activity ChargePayment(order.payment) -> payment
+    activity ShipOrder(order, payment) -> shipment
+    close complete(OrderResult{shipment})
+```
+
+**Iteration 1** — `twf check` finds errors:
+
+```
+resolve error at 2:5: undefined activity "ValidateOrder"
+resolve error at 3:5: undefined activity "ChargePayment"
+resolve error at 4:5: undefined activity "ShipOrder"
+```
+
+Fix — add the missing definitions. `twf check` → `✓ OK`
+
+**Iteration 2** — design review. Shipping involves creating a shipment, waiting for carrier pickup, and tracking — multiple steps with independent retry. Consult [workflow-boundaries.md](./reference/workflow-boundaries.md): multi-step orchestration with its own lifecycle → child workflow.
+
+Revise — extract `ShipOrder` as a child workflow, and make the behavior over time and at scale explicit. `twf check` validates structure but says nothing about timeouts, retries, or history growth — those are design decisions you must add:
+
+```twf
+workflow ProcessOrder(order: Order) -> (OrderResult):
+    activity ValidateOrder(order) -> validated
+    activity ChargePayment(order.payment) -> payment
+        options:
+            start_to_close_timeout: 30s   # bound the external charge call
+            retry_policy:
+                maximum_attempts: 3       # payment provider can be flaky
+    workflow ShipOrder(order, payment) -> shipment
+    close complete(OrderResult{shipment})
+```
+
+`twf check` → `✓ OK`. Structurally sound — now run the [Design Review](#design-review) before presenting.
+
+**Long-running variant** — when a workflow loops over a large bound (or accumulates chunky per-iteration history), it must reach `close continue_as_new(...)` even though the loop is finite. A bound alone does not make history safe:
+
+```twf
+workflow ReindexCatalog(cursor: Cursor):
+    pageCount = 0
+    for:
+        activity FetchPage(cursor) -> page
+        activity IndexItems(page.items)
+        cursor = page.next
+        pageCount = pageCount + 1
+        if (cursor == null):
+            close complete
+        # History grows per page — reset it before it gets large.
+        if (pageCount >= 500):
+            close continue_as_new(cursor)
+```
+
+### Design Review
+
+A clean `twf check` (and, when it exists, `twf lint`) does **not** mean the design is correct. Idempotency of side effects, concurrent-write races, and cross-file payload data flow are invisible to the tooling and remain review concerns. Before presenting, do one **fresh-eyes pass**: re-read the finished design as if reviewing someone else's PR — set the prose/intent aside, or dispatch a reviewer that sees only the `.twf` artifacts. Self-review with the authoring mindset reproduces the author's blind spots; the value is in the *independence* of the second look, not its existence.
+
+Grade against this rubric:
+
+- **Call-site integrity** — every `activity` / `workflow` / `nexus` definition has at least one *structured* call site. A bare expression like `x = ActName(args)` parses as `raw` text and is silently **not** wired up — these orphans hide behind a clean `twf check`.
+- **Reachability / dead code** — every workflow is reachable from a declared entry point via a call or Nexus op. Call out leftover/dead workflows; don't assume they're live.
+- **Anti-pattern re-check** — walk the finished design against every entry in [anti-patterns.md](./reference/anti-patterns.md). Wrapper workflows, monoliths, and unbounded/bounded-but-large history are exactly what get copied in uncritically.
+- **Idempotency** — each non-idempotent-by-nature activity states its idempotency strategy and key derivation (e.g. "workflow ID + activity name"). No tool validates this.
+- **Concurrent writes to shared state** — does any parallel fan-out (`await all`, `for` + promises) have branches that write the same external blob/record? If so, state the isolation/keying assumption. TWF can't express it, so no tool can catch it — human-review-only.
+- **Runtime / cost / lifecycle** — timeouts and retries set where failure can happen; history growth bounded (`continue_as_new` where needed); large payloads handled (see [anti-patterns.md](./reference/anti-patterns.md#large-payloads-in-workflow-state)).
+
+### Revising an Existing Design
+
+This is also the entry point when [Orient](#orient) surfaces prior work. Treat prior artifacts as **requirements**, not reference material. Run `twf symbols` to understand current structure, make edits, then re-enter the core loop (`twf check` → fix → [Design Review](#design-review) → repeat). Treat user feedback as new requirements — ask clarifying questions before editing if the feedback is ambiguous.
+
+### When to Consult the User
+
+**Fix yourself:** clear syntax mistakes, unambiguous errors (undefined → add definition), pattern exists in docs.
+
+**Ask the user:** multiple valid approaches, requirements gap, unclear architectural choice, workaround feels wrong.
+
+**Cost of asking < Cost of wrong design.**
+
+---
+
+## `twf` CLI
+
+**Run `twf check` after every `.twf` edit.** Fix all errors before presenting to user.
+
+For the authoritative flag set on any command, run `twf help` or
+`twf <command> --help` — that help is generated from the binary and never
+drifts. The table below is the *when/why*, not the flag reference:
+
+| Command | Purpose |
+|---------|---------|
+| `twf check <file...>` | Parse + resolve — run after every edit |
+| `twf symbols <file...>` | List all workflow/activity signatures |
+| `twf symbols --json <file...>` | Machine-readable symbol output |
+| `twf check --lenient <file...>` | Same checks; still prints every error but exits 0 instead of failing — for WIP iteration (it suppresses nothing) |
+
+**Error format** (stderr): `<severity> [<kind>/<CODE>] at <file>:<line>:<col>: <message>` — e.g. `error [resolve/UNDEFINED_ACTIVITY] at order.twf:2:3: undefined activity: Foo`.
+
+---
+
+## TWF Syntax
+
+Full grammar: [`tools/spec/sections/`](../../../tools/spec/sections/) (or run `twf spec` for the concatenated view; `twf spec --list` for slugs). Quick reference: [`notation-reference.md`](./reference/notation-reference.md). Examples: [`notation-examples.md`](./reference/notation-examples.md). Common errors: [`common-errors.md`](./reference/common-errors.md).
+
+All `.twf` must pass `twf check` before presenting to user. Activity bodies are free-form pseudocode — detail level depends on how obvious the behavior is (see [notation-examples.md](./reference/notation-examples.md#activity-body-detail)).
+
+---
+
+## Completion
+
+The design is ready to present when both gates pass.
+
+**Grammar / structure gate** (does it parse, resolve, and deploy?):
+
+1. `twf check` passes with no errors
+2. `twf symbols` lists all expected workflows and activities
+3. Worker/namespace topology validates (when present)
+
+**Design-quality gate** (is it a good Temporal design?) — these are *not* checked by any tool:
+
+4. All I/O, time, and randomness live in activities (determinism)
+5. Activities are idempotent, with the strategy stated per side-effecting activity
+6. Failure modes have recovery strategies
+7. The [Design Review](#design-review) rubric passes (call-site integrity, reachability, anti-pattern re-check)
+
+The design is **not** ready on a clean `twf check` alone — gates 4-7 are where Temporal design quality actually lives. For the full checklist: [design-checklist.md](./reference/design-checklist.md). For complex control flow, parallel execution, or signal/timer races, suggest the TWF visualizer extension. Present a summary alongside the `.twf` file: key workflows, activity purposes, and notable design decisions.
+
+---
+
+## Handoff
+
+The deliverable is the `.twf` file. **Produce/review `.twf`; `temporal-architect` routes implementation** — do not select authoring skills or orchestrate subagents from here. Alongside the `.twf`, note what `temporal-architect` and the authors need: target SDK/language, external system assumptions, and design decisions not captured in the notation.
+
+This skill may run **in the main agent** (collaborative, interactive design — the common case, since `.twf` is the elevated surface the user designs *from*) or as a reviewer subagent dispatched by `temporal-architect`. `temporal-architect` decides which; either way, the output is the same `.twf` plus its handoff notes.
+
+---
+
+## Reference Index
+
+Read only what the current design requires.
+
+| Topic | When to Consult | File |
+|-------|-----------------|------|
+| Determinism & Idempotency | Replay safety and retry resilience review | [core-principles.md](./reference/core-principles.md) |
+| Workflow Boundaries | Activity vs child workflow decision | [workflow-boundaries.md](./reference/workflow-boundaries.md) |
+| Signal vs Update | Choosing between signal and update for external input | [signals-queries-updates.md](./topics/signals-queries-updates.md) |
+| Notation Examples | Control flow, handlers, timers, nexus in TWF | [notation-examples.md](./reference/notation-examples.md) |
+| Notation Reference | All TWF syntax constructs | [notation-reference.md](./reference/notation-reference.md) |
+| `.twf` Conventions | File placement + comment conventions (impl-link, cross-domain stub) | [twf-conventions.md](./reference/twf-conventions.md) |
+| Design Checklist | Final verification before presenting | [design-checklist.md](./reference/design-checklist.md) |
+| Anti-Patterns | Common Temporal design mistakes | [anti-patterns.md](./reference/anti-patterns.md) |
+| Reverse Engineering | Recovering `.twf` from existing code | [reverse-engineering.md](./reference/reverse-engineering.md) |
+| Common Errors | Troubleshooting `twf check` parser/resolver errors | [common-errors.md](./reference/common-errors.md) |
+| Primitives Reference | Temporal primitive lookup | [primitives-reference.md](./reference/primitives-reference.md) |
+| Project Discovery Subagent | Scanning an existing repo on a bounded slice | [project-discovery-subagent.md](./reference/project-discovery-subagent.md) |
+| Workers & Task Queues | Worker grouping, task queue routing, deployment | [task-queues.md](./topics/task-queues.md) |
+| Namespaces | Deciding namespace count / boundaries | [namespaces.md](./reference/namespaces.md) |
+| Nexus | Cross-namespace communication | [nexus.md](./topics/nexus.md) |
+Topic deep-dives are in `reference/` and `topics/` — consult as needed during design.

package/skills/temporal-architect-design/reference/LANGUAGE.md

@@ -0,0 +1,5 @@
+# TWF Language Reference
+
+The canonical grammar specification lives in [`tools/spec/sections/`](../../../../tools/spec/sections/) — one markdown file per topic, named `NN-slug.md`. The full concatenation is also available via `twf spec`; individual sections via `twf spec <slug>`.
+
+Always consult the canonical spec for syntax questions. This redirect exists so that skill-internal links resolve.