@temporal-architect/claude-plugin 0.9.0

package/skills/temporal-architect-design/reference/notation-examples.md

@@ -0,0 +1,304 @@
+# TWF Notation Examples
+
+## Basic Structure
+
+A complete `.twf` file: workflows, activities, worker registration, and namespace deployment.
+
+```twf
+workflow WorkflowName(input: InputType) -> (OutputType):
+    activity ActivityName(input) -> result
+    workflow ChildWorkflowName(input) -> childResult
+    close complete(OutputType{result, childResult})
+
+workflow ChildWorkflowName(input: InputType) -> (ChildResult):
+    activity DoWork(input) -> result
+    close complete(ChildResult{result})
+
+activity ActivityName(input: InputType) -> (Result):
+    return process(input)
+
+activity DoWork(input: InputType) -> (WorkResult):
+    return work(input)
+
+worker mainWorker:
+    workflow WorkflowName
+    workflow ChildWorkflowName
+    activity ActivityName
+    activity DoWork
+
+namespace default:
+    worker mainWorker
+        options:
+            task_queue: "main"
+```
+
+## Activity Body Detail
+
+Activity bodies are intentionally free-form (`raw_stmt`) — pseudocode or descriptive text representing SDK-level implementation. Every activity needs at least one statement (comments alone are not enough). Detail level depends on how obvious the behavior is from name and signature:
+
+**Obvious** — minimal body:
+
+```twf
+activity SendEmail(to: string, body: string):
+    send(to, body)
+```
+
+**Non-obvious** — comments describe intent, pseudocode anchors the body:
+
+```twf
+activity ExecuteToolCalls(toolCalls: ToolCalls) -> (ToolResults):
+    # Look up each tool by name in the tool registry
+    # Execute calls in parallel where possible
+    # If a tool is not found, return an error result (don't fail the activity)
+    registry.executeAll(toolCalls)
+```
+
+**Complex contract** — describe error conditions, ordering, and idempotency:
+
+```twf
+activity ReconcileInventory(warehouseId: string, expected: Inventory) -> (ReconcileResult):
+    # Fetch current inventory, diff against expected, flag discrepancies
+    # Must be idempotent — running twice with same input produces same flags
+    # Warehouse API is rate-limited: max 10 requests/second
+    warehouse.reconcile(warehouseId, expected)
+```
+
+## Control Flow
+
+```twf
+workflow ProcessOrder(order: Order) -> (Result):
+    activity ValidateOrder(order) -> validated
+
+    # Conditionals
+    if (validated.priority == "high"):
+        activity ExpediteOrder(order)
+    else:
+        activity StandardProcessing(order)
+
+    # Sequential loop — use for when each iteration depends on order or shared state
+    # For independent iterations, consider await all with parallel activities instead
+    for (item in order.items):
+        activity ProcessItem(item)
+
+    # Parallel execution — use await all when tasks are independent and all results needed
+    await all:
+        activity ReserveInventory(order) -> inventory
+        activity ProcessPayment(order) -> payment
+
+    close complete(Result{inventory, payment})
+
+# Every referenced activity must be defined
+activity ValidateOrder(order: Order) -> (ValidateResult):
+    return validate(order)
+
+activity ExpediteOrder(order: Order):
+    expedite(order)
+
+activity StandardProcessing(order: Order):
+    process(order)
+
+activity ProcessItem(item: Item) -> (ItemResult):
+    return process(item)
+
+activity ReserveInventory(order: Order) -> (Inventory):
+    return reserve(order)
+
+activity ProcessPayment(order: Order) -> (Payment):
+    return charge(order)
+```
+
+## Temporal Primitives in Notation
+
+```twf
+workflow OrderFulfillment(orderId: string) -> (OrderResult):
+    # Handlers go before body
+    # signal = write (fire-and-forget)
+    signal PaymentReceived(transactionId: string, amount: decimal):
+        paymentStatus = "received"
+        lastTransactionId = transactionId
+
+    # query = read (caller gets result)
+    query GetOrderStatus() -> (OrderStatus):
+        return OrderStatus{status: status, payment: paymentStatus}
+
+    # update = read-write (caller sends data, gets result)
+    update UpdateShippingAddress(address: Address) -> (Result):
+        activity ValidateAddress(address) -> validation
+        if (validation.valid):
+            shippingAddress = address
+            return Result{success: true}
+        else:
+            return Result{success: false, error: validation.reason}
+
+    # Workflow body starts after handlers
+    activity GetOrder(orderId) -> order
+    paymentStatus = "pending"
+    status = "awaiting_payment"
+
+    # Durable timer
+    await timer(1h)
+
+    # Wait for signal with timeout
+    await one:
+        signal PaymentReceived:
+            status = "processing"
+        timer(24h):
+            activity CancelOrder(orderId)
+            close fail(OrderResult{status: "cancelled"})
+
+    # Child workflow
+    workflow ShipOrder(order) -> shipResult
+
+    # Cross-namespace nexus call
+    nexus NotificationsEndpoint NotificationsService.SendNotification(order.customer, "shipped")
+
+    close complete(OrderResult{status: "completed"})
+
+# Supporting definitions
+activity GetOrder(orderId: string) -> (Order):
+    return db.get(orderId)
+
+activity ValidateAddress(address: Address) -> (Validation):
+    return validate(address)
+
+activity CancelOrder(orderId: string):
+    cancel(orderId)
+
+workflow ShipOrder(order: Order) -> (ShipResult):
+    activity CreateShipment(order) -> shipment
+    close complete(ShipResult{shipment})
+
+activity CreateShipment(order: Order) -> (Shipment):
+    return ship(order)
+
+workflow SendNotification(customer: Customer, message: string):
+    activity Notify(customer, message)
+    close complete
+
+activity Notify(customer: Customer, message: string):
+    send(customer, message)
+
+nexus service NotificationsService:
+    async SendNotification workflow SendNotification
+
+worker orderFulfillmentWorker:
+    workflow OrderFulfillment
+    workflow ShipOrder
+    workflow SendNotification
+    activity GetOrder
+    activity ValidateAddress
+    activity CancelOrder
+    activity CreateShipment
+    activity Notify
+    nexus service NotificationsService
+
+namespace default:
+    worker orderFulfillmentWorker
+        options:
+            task_queue: "orderFulfillment"
+    nexus endpoint NotificationsEndpoint
+        options:
+            task_queue: "orderFulfillment"
+```
+
+## Async Patterns
+
+```twf
+workflow OrderPipeline(order: Order) -> (PipelineResult):
+    state:
+        condition paymentConfirmed
+
+    # Update handler — validates and confirms payment
+    update ConfirmPayment(txn: Transaction) -> (ConfirmResult):
+        activity ValidateTxn(txn) -> validation
+        if (validation.ok):
+            set paymentConfirmed
+            return ConfirmResult{accepted: true}
+        else:
+            return ConfirmResult{accepted: false, reason: validation.error}
+
+    # Promise — start async, await later
+    promise inventory <- activity CheckInventory(order)
+
+    # Detach — fire-and-forget, no result observation
+    detach workflow AuditLog(order)
+
+    # Await condition — blocks until handler sets it
+    await paymentConfirmed
+
+    # Await promise — get the result started earlier
+    await inventory -> stock
+
+    # Switch — multi-branch dispatch
+    switch (stock.level):
+        case "high":
+            activity ShipStandard(order) -> shipment
+        case "low":
+            activity ShipFromWarehouse(order, stock.warehouseId) -> shipment
+        case "none":
+            close fail(PipelineResult{error: "out of stock"})
+
+    close complete(PipelineResult{shipment})
+
+# Heartbeat — report progress from long-running activity
+activity ProcessLargeDataset(datasetId: string) -> (ProcessResult):
+    # Call heartbeat() periodically to report progress
+    # If worker dies, Temporal detects missed heartbeat and retries on another worker
+    heartbeat()
+    return process(datasetId)
+
+# Call-level options — override timeout, routing, retry for a specific call
+workflow DeployService(config: DeployConfig) -> (DeployResult):
+    activity BuildArtifact(config) -> artifact
+    activity Deploy(artifact) -> result
+        options:
+            start_to_close_timeout: 30m
+            heartbeat_timeout: 5m
+            retry_policy:
+                maximum_attempts: 3
+    close complete(DeployResult{result})
+
+# Supporting definitions
+activity CheckInventory(order: Order) -> (InventoryStatus):
+    return inventory.check(order)
+
+activity ValidateTxn(txn: Transaction) -> (TxnValidation):
+    return payments.validate(txn)
+
+workflow AuditLog(order: Order):
+    activity RecordAudit(order)
+    close complete
+
+activity RecordAudit(order: Order):
+    audit.record(order)
+
+activity ShipStandard(order: Order) -> (Shipment):
+    return shipping.standard(order)
+
+activity ShipFromWarehouse(order: Order, warehouseId: string) -> (Shipment):
+    return shipping.fromWarehouse(order, warehouseId)
+
+activity BuildArtifact(config: DeployConfig) -> (Artifact):
+    return build(config)
+
+activity Deploy(artifact: Artifact) -> (DeployStatus):
+    return deploy(artifact)
+
+worker pipelineWorker:
+    workflow OrderPipeline
+    workflow AuditLog
+    workflow DeployService
+    activity CheckInventory
+    activity ValidateTxn
+    activity RecordAudit
+    activity ShipStandard
+    activity ShipFromWarehouse
+    activity ProcessLargeDataset
+    activity BuildArtifact
+    activity Deploy
+
+namespace default:
+    worker pipelineWorker
+        options:
+            task_queue: "pipeline"
+```

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

@@ -0,0 +1,70 @@
+# TWF Notation Reference
+
+| Syntax | Meaning |
+|--------|---------|
+| `activity Name(args) -> result` | Call activity, bind result (default for single operations) |
+| `workflow Name(args) -> result` | Call child workflow, bind result (multi-step with own failure boundary) |
+| `nexus Endpoint Service.Op(args) -> result` | Nexus service operation call |
+| `detach nexus Endpoint Service.Op(args)` | Fire-and-forget nexus call (no result observation possible) |
+| `promise p <- nexus Endpoint Service.Op(args)` | Start async nexus call |
+| `promise p <- activity Name(args)` | Start async activity (use when you need the result later, not immediately) |
+| `promise p <- workflow Name(args)` | Start async child workflow (parallel child execution) |
+| `promise p <- timer(duration)` | Start async timer |
+| `promise p <- signal Name` | Promise for signal |
+| `await p -> result` | Await promise, bind result |
+| `state:` | Workflow state block (conditions and variable initializations) |
+| `condition name` | Named boolean awaitable (in `state:` block) |
+| `set name` | Set condition to true (coordinate between handlers and main body) |
+| `unset name` | Set condition to false |
+| `await name` | Await condition |
+| `detach workflow Name(args)` | Fire-and-forget child workflow (no result observation possible) |
+| `await timer(duration)` | Durable sleep |
+| `await signal Name` | Wait for signal |
+| `await update Name` | Wait for update |
+| `await nexus Endpoint Service.Op(args) -> result` | Wait for nexus call |
+| `await one:` | Race: first to complete wins (timeouts, signal-or-timer patterns). Non-winning operations are **not** cancelled — they keep running until the workflow run ends |
+| `await all:` | Join: wait for all (parallel execution) |
+| `heartbeat()` | Report progress from long-running activity (detect worker death) |
+| `options: key: value` | Options block for activity/workflow/nexus calls |
+| `-> (Type)` | Return type (always parenthesized) |
+| `-> result` | Bind preceding result |
+| `close complete\|fail\|continue_as_new(Value)` | End workflow with result, failure, or continuation |
+| `if (expr):` / `else:` | Conditional |
+| `for (x in collection):` | Bounded loop |
+| `for:` | Infinite loop (needs `close continue_as_new` or `close complete`) |
+| `switch (expr):` / `case val:` | Multi-branch conditional |
+| `close continue_as_new(args)` | Reset history and continue |
+| `signal Name(params):` | Signal handler (in workflow, before body) |
+| `query Name(params) -> (Type):` | Query handler (in workflow, before body) |
+| `update Name(params) -> (Type):` | Update handler (in workflow, before body) |
+| `nexus service Name:` | Nexus service definition (top-level) |
+| `async OpName workflow WorkflowName` | Async nexus operation (in service body) |
+| `sync OpName(params) -> (Type):` | Sync nexus operation (in service body) |
+| `worker name:` | Worker type set definition |
+| `nexus service Name` (in worker) | Register nexus service on worker |
+| `namespace name:` | Namespace definition (deployment with options) |
+| `nexus endpoint Name` (in namespace) | Nexus endpoint instantiation with task_queue |
+
+## Common `options:` Keys
+
+`options:` blocks attach operational config to a call. A clean `twf check` does not require any of these — but the design must reason about them (idempotency, history cost, failure behavior, routing). This is a lookup table; the *reasoning* lives in the worked example in [SKILL.md](../SKILL.md#design-flow) and the topic docs.
+
+| Key | Attaches to | Why it matters |
+|-----|-------------|----------------|
+| `task_queue` | activity, workflow | Routing — pins the call to a specific worker pool (capability, isolation, region) |
+| `start_to_close_timeout` | activity | Failure behavior — bounds a single attempt; required in practice for any real activity |
+| `schedule_to_close_timeout` | activity, nexus | Total time budget across queueing + attempts |
+| `schedule_to_start_timeout` | activity | Tolerance for queue wait before a worker picks it up |
+| `heartbeat_timeout` | activity | Worker-death detection for long activities (pairs with `heartbeat()`) |
+| `retry_policy` | activity, workflow, nexus | Failure behavior — `initial_interval`, `backoff_coefficient`, `maximum_interval`, `maximum_attempts`, `non_retryable_error_types` |
+| `workflow_execution_timeout` / `workflow_run_timeout` / `workflow_task_timeout` | workflow | Bounds for total / per-run / per-task duration |
+| `parent_close_policy` | workflow | Child lifecycle when parent closes: `TERMINATE` (default), `REQUEST_CANCEL`, `ABANDON` |
+| `workflow_id_reuse_policy` | workflow | Idempotency on retry: `ALLOW_DUPLICATE`, `ALLOW_DUPLICATE_FAILED_ONLY`, `REJECT_DUPLICATE`, `TERMINATE_IF_RUNNING` |
+| `cron_schedule` | workflow | Recurring child execution |
+| `priority` | activity, workflow, nexus | Relative dispatch priority |
+
+> The child-workflow **ID** itself is an SDK-level concern, not a TWF call option — see [child-workflows.md](../topics/child-workflows.md#workflow-id-design). `task_queue` is intentionally **not** a nexus-call option; nexus routing comes from the endpoint declaration.
+
+> **Worker-instantiation `options:` are a separate set** from the call options above — they attach to a `worker` (or `nexus endpoint`) inside a `namespace`, not to a call. `task_queue` is required; `versioning` (`none` / `build_id` / `deployment`) is the design-altitude strategy key. The set is the SDK union, accepted permissively — see [task-queues.md](../topics/task-queues.md#worker-options) and `twf spec`.
+
+Full grammar: [`tools/spec/sections/`](../../../tools/spec/sections/) (or run `twf spec`).

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

@@ -0,0 +1,65 @@
+# Temporal Primitives Reference
+
+## Workflow Execution
+
+| Primitive | Purpose | Details |
+|-----------|---------|---------|
+| `activity` | Side-effecting operation | Core primitive |
+| `workflow` | Child workflow | [child-workflows.md](../topics/child-workflows.md) |
+| `nexus` | Cross-namespace call | [nexus.md](../topics/nexus.md) |
+| `promise` | Async operation, await later | [promises-conditions.md](../topics/promises-conditions.md) |
+| `detach` | Fire-and-forget child/nexus | [child-workflows.md](../topics/child-workflows.md), [nexus.md](../topics/nexus.md) |
+| `close continue_as_new` | Reset history, continue | [long-running.md](../topics/long-running.md) |
+
+**Selection:** `activity` for single side-effecting operations. `workflow` for multi-step orchestration needing its own retry/failure boundary. `nexus` when crossing namespace or team boundaries. `promise` when you need the result later, not immediately. `detach` for fire-and-forget — you cannot observe the result. `close continue_as_new` when history grows unbounded (long-running or entity workflows).
+
+## Timing
+
+| Primitive | Purpose | Details |
+|-----------|---------|---------|
+| `timer` | Durable sleep (survives restarts) | [timers-scheduling.md](../topics/timers-scheduling.md) |
+| `schedule` | Cron-like recurring execution | [timers-scheduling.md](../topics/timers-scheduling.md) |
+| `timeout` | Deadline for operations | [timers-scheduling.md](../topics/timers-scheduling.md) |
+
+**Selection:** `timer` for durable waits inside workflow logic (survives replay). Activity-level timeouts (`heartbeat_timeout`, `start_to_close_timeout` in `options:`) for bounding activity execution. `schedule` for cron-like recurring workflow starts — this is platform configuration, not TWF notation.
+
+## External Communication
+
+Read, write, or read-write interaction with a running workflow:
+
+| Primitive | I/O | Purpose | Details |
+|-----------|-----|---------|---------|
+| `query` | Read | Sync read of workflow state | [signals-queries-updates.md](../topics/signals-queries-updates.md) |
+| `signal` | Write | Async fire-and-forget into workflow | [signals-queries-updates.md](../topics/signals-queries-updates.md) |
+| `update` | Read-write | Sync mutation with result | [signals-queries-updates.md](../topics/signals-queries-updates.md) |
+
+**Selection:** Use I/O direction as the decision rule. **Do not** use `query` to modify state — queries must be pure reads. **Do not** use `signal` when you need confirmation — signals have no return value. Prefer `update` over signal-then-query when the caller needs to know the mutation succeeded.
+
+## State and Conditions
+
+| Primitive | Purpose | Details |
+|-----------|---------|---------|
+| `state` | Workflow state declaration block | [promises-conditions.md](../topics/promises-conditions.md) |
+| `condition` | Named boolean awaitable | [promises-conditions.md](../topics/promises-conditions.md) |
+| `set` / `unset` | Set condition to true / false | [promises-conditions.md](../topics/promises-conditions.md) |
+
+**Selection:** Use `condition` when handlers and the main workflow body need to coordinate on a boolean flag (e.g., "payment received", "approved"). Use local variables for workflow-scoped state that doesn't need cross-handler coordination.
+
+## Activity Options
+
+| Primitive | Purpose | Details |
+|-----------|---------|---------|
+| `heartbeat` | Report progress, detect worker death | [activities-advanced.md](../topics/activities-advanced.md) |
+| `async_complete` | Complete from external system | [activities-advanced.md](../topics/activities-advanced.md) |
+
+## Infrastructure
+
+| Primitive | Purpose | Details |
+|-----------|---------|---------|
+| `task_queue` | Route work to specific workers | [task-queues.md](../topics/task-queues.md) |
+| `worker` | Defines a reusable type set (which workflows, activities, nexus services run together) | [task-queues.md](../topics/task-queues.md) |
+| `namespace` | Deployment topology — instantiates workers with `task_queue` and options | [task-queues.md](../topics/task-queues.md) |
+| `nexus service` | Typed operation group for cross-namespace calls | [nexus.md](../topics/nexus.md) |
+| `nexus endpoint` | Routes nexus calls to a target task queue | [nexus.md](../topics/nexus.md) |
+| `search_attribute` | Index workflow for queries | Core primitive |
+| `memo` | Attach metadata to workflow | Core primitive |

package/skills/temporal-architect-design/reference/project-discovery-subagent.md

@@ -0,0 +1,80 @@
+# Project-Discovery Subagent
+
+A single reusable primitive: **scan an existing repo on a bounded slice, return a compact summary.** Owned here (design-skill) and shared by every skill that has to understand a repo it didn't write:
+
+- **design reverse-engineering** — [reverse-engineering.md](./reverse-engineering.md) B1a bootstrap (no `.twf`) and B1b drift-check.
+- **author-go existing-repo Orient** — `temporal-architect-author-go/SKILL.md` (see `author-go-skill/REVISIONS_001` Group 1).
+- **author-infra** — repo/tooling discovery when that skill lands.
+
+Design once, reuse. This spec is the broadened, shared form of the `sdk-explorer` agent sketched in [SUBAGENT_ADOPTION.md](../../temporal-architect-author-go/SUBAGENT_ADOPTION.md) — it answers that doc's open question ("should it also scan the user's existing project code for conventions?") with **yes**: project-convention discovery is this subagent's job, not the orchestrator's.
+
+## Why a subagent
+
+Discovery is context-heavy and disposable. Reading a repo's tooling, layout, and registration wiring burns tokens the design conversation needs — and almost none of what it reads belongs in the main context, only the conclusions. Running discovery in an **isolated subagent that returns a summary** is the context-protection move: the orchestrator stays focused on design, the subagent absorbs the noise.
+
+## Trigger discipline
+
+Dispatch **deliberately, on a bounded slice** — never reflexively, never "scan the whole repo." The caller names the slice (a domain, a directory, a set of entry points). An unbounded scan defeats the purpose: it floods the subagent's own context and returns a summary too broad to act on. If the slice is unclear, the orchestrator narrows it *with the user* before dispatching.
+
+## Inputs
+
+| Input | Description |
+|-------|-------------|
+| Repo root | Absolute path to the project. |
+| Bounded slice | The paths / domain / entry points to scan. Required — no whole-repo scans. |
+| Focus | What the caller needs (e.g. "Temporal registration style", "codegen tooling", "existing `.twf` for this domain"). |
+
+## What it scans
+
+- **Build / codegen tooling** — `Makefile`, `buf.yaml` / `buf.gen.yaml`, `//go:generate` directives, `protoc` plugins. Identifies whether code is hand-written or generated, and by what.
+- **Package layout** — directory structure, where workflows/activities live, `proto/` → `gen/` → `lib/` style splits.
+- **Temporal SDK usage** — `go.temporal.io/sdk` imports, `workflow.ExecuteActivity` / `ExecuteChildWorkflow` / Nexus call sites, signal/query/update handlers.
+- **Registration style** — `worker.New` + `RegisterWorkflow`/`RegisterActivity`, generated `RegisterXxxActivities/Workflows` helpers, DI wiring (`fx`), struct-vs-func activities.
+- **`.twf` / `.tf` presence** — existing design files and Terraform/infra files for this slice.
+- **Comment conventions** — impl-link headers and cross-domain stub markers (see [twf-conventions.md](./twf-conventions.md)); these point discovery straight at the implementation.
+
+## Output
+
+A **compact structured summary** — conclusions, not raw dumps. Never paste whole files back. Cover:
+
+- Tooling: hand-written vs generated; generator stack if any.
+- Layout: where the relevant code lives for the scanned slice.
+- SDK usage: workflows/activities/nexus found, with their call sites.
+- Registration: how workers register the discovered types.
+- Existing `.twf`: present/absent, and what it covers.
+- Impl-links: any comment conventions found, and what they point to.
+- Open questions the caller must resolve.
+
+## Agent definition
+
+Copy-pastable subagent prompt (frontmatter style matches `sdk-explorer` in [SUBAGENT_ADOPTION.md](../../temporal-architect-author-go/SUBAGENT_ADOPTION.md)):
+
+```yaml
+---
+name: project-discovery
+description: Scan an existing repo on a bounded slice for tooling, layout, conventions, and Temporal usage. Returns a compact summary.
+tools: Read, Glob, Grep, Bash, WebFetch, WebSearch
+model: sonnet
+---
+```
+
+```
+You are scanning an existing repository on a BOUNDED SLICE. Do not scan the whole
+repo — stay within the slice the caller named.
+
+Inputs:
+- Repo root: <path>
+- Slice: <paths / domain / entry points>
+- Focus: <what the caller needs>
+
+Scan for: build/codegen tooling (Makefile, buf.gen.yaml, //go:generate), package
+layout, Temporal SDK usage (workflow/activity/nexus call sites, handlers),
+registration style (worker.New + Register*, generated helpers, fx wiring), .twf/.tf
+presence, and impl-link / cross-domain-stub comment conventions.
+
+Return a COMPACT STRUCTURED SUMMARY — conclusions only, never raw file dumps:
+tooling, layout, SDK usage, registration, existing .twf, impl-links, open questions.
+
+For SDK-symbol meaning, delegate to the relevant author skill's reference (e.g.
+author-go references read backward) rather than reconstructing it yourself.
+```

package/skills/temporal-architect-design/reference/reverse-engineering.md

@@ -0,0 +1,53 @@
+# Reverse Engineering: Code → `.twf`
+
+The dominant adoption path is not greenfield. Most teams already run Temporal code and want a `.twf` that captures what they have — to review it, refactor it, or hand it to the visualizer. Here the **implementation is the requirement** and the `.twf` is recovered from it.
+
+Treat the recovered `.twf` as the **central, living design medium** — the artifact the team will keep editing and reviewing — not a throwaway sketch of the code. That framing sets the bar: capture the design faithfully enough that it's worth keeping.
+
+This is a **parallel path** to the greenfield loop, kept separate on purpose. The main [SKILL.md](../SKILL.md) body carries only a thin trigger; the mechanics live here so the fast forward loop never pays for them. Discovery runs in an isolated [project-discovery subagent](./project-discovery-subagent.md) and returns a summary — the context-protection move.
+
+## Trigger discipline
+
+Reverse-engineer **deliberately, on a bounded slice** — one domain, one service, one set of entry points at a time. Never scan the whole repo reflexively. A slice keeps both the discovery subagent and the resulting `.twf` reviewable; a whole-repo sweep produces a `.twf` nobody can check.
+
+## Two cases
+
+### B1a — Bootstrap (no `.twf` yet)
+
+The repo has Temporal code but no design file. Recover one from scratch:
+
+1. **Discover** — dispatch the [project-discovery subagent](./project-discovery-subagent.md) on the bounded slice. It returns tooling, layout, SDK usage, registration style, and any impl-link comments.
+2. **Extract** — translate the discovered workflows/activities/nexus into `.twf` (see [Reading strategy](#reading-strategy)).
+3. **Fidelity check** — confirm the `.twf` matches what the code actually does (see [Fidelity first](#fidelity-first-then-design-review)).
+4. **Design Review** — only now run the standard [Design Review](../SKILL.md#design-review).
+
+Write the [impl-link header](./twf-conventions.md) as you extract, so the new `.twf` records where its implementation lives.
+
+### B1b — Drift / sync (`.twf` exists but is stale)
+
+A `.twf` exists but the code has moved on. Two halves, with different readiness:
+
+- **Check (available now):** on a bounded slice, compare the `.twf` against current code and report divergences — missing activities, changed boundaries, dropped signals. This needs no new tooling.
+- **Sync (deferred):** mechanically reconciling `.twf` ↔ implementation depends on the future twf↔impl mapping (`dsl/BACKLOG.md` → Reference Annotations / `@ref`). Until that lands, reconcile by hand: re-extract the drifted slice (B1a steps 2-4) and update the `.twf`, treating the code as the source of truth for *behavior* and the existing `.twf` as the source of truth for *intent*.
+
+## Reading strategy
+
+Read for **design structure**, not line-by-line behavior:
+
+- **Find entry points first** — client-started workflows, schedule-started workflows, Nexus-operation-backing workflows, handler-bearing workflows. These are the roots of the `.twf`.
+- **Follow call sites** — `workflow.ExecuteActivity`, `workflow.ExecuteChildWorkflow`, Nexus operation calls. Each is an `activity` / `workflow` / `nexus` call in TWF.
+- **Ignore the plumbing** — error wrapping, `context` threading, logging, options structs, retry/timeout boilerplate. None of it changes the design shape; capture only the options that express a real decision (a tuned timeout, a capped retry).
+- **Detect parallelism** — `workflow.Go`, selectors (`workflow.NewSelector`), futures held and `.Get` later → `await all` / `await one` / `promise` in TWF. Sequential `.Get` right after the call is just a synchronous call.
+
+### Delegate SDK reading to the author skill
+
+Do not reconstruct SDK semantics yourself. The author skills already hold the DSL↔SDK mapping — **read their symbol tables backward.** For Go, use the `temporal-architect-author-go` references (e.g. `activity-call.md`, `workflow-call.md`, `await-all.md`) and, for generated code, its forthcoming `reference/proto-driven.md` Rosetta Stone (generated `XxxActivities` iface, `RegisterXxxActivities`, `XxxFuture`, etc. → the underlying `activity`/`workflow`). Forward mappings (DSL → Go) read in reverse give you Go → DSL for free.
+
+## Fidelity first, then Design Review
+
+**Capture what the code does, faithfully — including its anti-patterns.** A wrapper workflow, a monolith, an unbounded loop: extract them *as they are*. The recovered `.twf` must mirror reality before it's worth reviewing; silently "fixing" during extraction produces a `.twf` that describes a system that doesn't exist, and hides the very problems the team needs to see.
+
+- **Do not** refactor, rename, or "improve" during extraction.
+- **Intent-fill only genuinely-unimplemented stubs** — a `// TODO` body, a panic-not-implemented, an empty handler. Mark these clearly; everything else is recovered, not invented.
+
+Once the `.twf` faithfully reflects the code, run the standard [Design Review](../SKILL.md#design-review). That pass is where anti-patterns get *named and proposed for change* — separately from extraction, so the record of "what exists" stays honest and the "what should change" is an explicit, reviewable diff.

package/skills/temporal-architect-design/reference/twf-conventions.md

@@ -0,0 +1,43 @@
+# `.twf` Conventions
+
+How to lay out `.twf` files and the small set of comment conventions that carry information the grammar doesn't yet express.
+
+## One package for all `.twf`
+
+**Recommendation: keep all of a project's `.twf` in one package** (one directory whose files resolve together). Cross-file references — an `activity` defined in one file and called in another, a `nexus service` provided in one file and called in another — resolve only within a shared file set. One package means every reference resolves and `twf check` sees the whole design at once.
+
+This decouples `.twf` layout from code layout: the files no longer mirror the directory structure of the implementation. That trade-off is worth it — resolution coverage matters more than co-location — and the [impl-link header](#impl-link-header) below restores the link to the code.
+
+## Comment conventions
+
+`.twf` comments (`#`) are free text to the parser, but a small **named set** carries conventional meaning the tooling and the reader rely on. Use these exact forms.
+
+### Impl-link header
+
+A top-of-file comment linking a `.twf` to the implementation directory (or directories) it describes:
+
+```twf
+# impl: order-service/workflows, order-service/activities
+workflow ProcessOrder(order: Order) -> (Result):
+    activity ChargePayment(order) -> receipt
+    close complete(Result{receipt})
+
+activity ChargePayment(order: Order) -> (Receipt):
+    charge(order.payment)
+```
+
+Because the one-package layout decouples `.twf` from code, the implementation link can no longer be inferred from location — it has to be explicit. The header is that link. It is also a [reverse-engineering](./reverse-engineering.md) aid: the [project-discovery subagent](./project-discovery-subagent.md) *reads* it to jump straight to the code, and extraction *writes* it when recovering a `.twf` from existing code.
+
+This is the interim form. The durable, machine-checkable version is per-symbol reference annotations (`@ref`), deferred in `dsl/BACKLOG.md` — when that lands, the header convention gives way to it.
+
+### Cross-domain stub marker
+
+A marker on a local stub definition that exists only to satisfy resolution for a symbol actually defined in another `.twf`:
+
+```twf
+# cross-domain stub — defined in payments.twf
+nexus service PaymentService:
+    sync ChargeCard(req: ChargeRequest) -> (Receipt)
+```
+
+Defining *one* local `nexus service` turns every other service reference in the file into a hard error — including genuinely external services in other namespaces (see [common-errors.md](./common-errors.md#nexus-resolution-external-warning-vs-local-error)). The stub marker documents that the definition is a local placeholder, not the real owner, so a partial / per-domain file can both call and provide services without tripping the resolution cliff. The marker makes the stub's intent obvious to readers and to the discovery subagent.

package/skills/temporal-architect-design/reference/workflow-boundaries.md

@@ -0,0 +1,43 @@
+# Workflow vs Activity Boundary
+
+## Use Activities When
+
+**Default granularity: one activity per network call / external interaction.** This is the right default because it makes Temporal's retry, timeout, and backoff land at exactly the unit that can fail independently — one activity per fallible boundary gives clean, granular retry semantics. Start here, then deviate only as an optimization (batching, local activities — see [core-principles.md](./core-principles.md#activities-are-for-io--not-in-memory-work)).
+
+- Single atomic operation
+- External system interaction (API, DB, file)
+- Short, predictable completion time (single timeout period)
+- No orchestration logic
+
+Conversely, do **not** create an activity for work that touches no external system — reads of already-held data, in-memory derivation, or accumulation are workflow code, not activities.
+
+## Use Child Workflows When
+
+- Multiple steps with independent retry/timeout policies
+- Reusable across parent workflows
+- Separate failure boundary needed
+- Very long operations (separate history)
+- Complex enough to warrant own tests
+
+**Rule of thumb:** Loops or conditionals inside an activity → should be a workflow.
+
+## Use Nexus When
+
+- Crosses namespace or team boundaries (separate deployment lifecycle)
+- Different team owns the target service
+- Target needs independent scaling, versioning, or failure isolation at the organizational level
+- You want a typed API contract between services
+
+**Child workflow vs nexus:** Child workflows share a namespace and are tightly coupled to the parent's lifecycle. Nexus calls are loosely coupled — the target is an independent service that may be owned by another team, deployed on a different schedule, or running in a different namespace.
+
+## Common Mistakes
+
+**Wrapper workflow:** A child workflow containing a single activity call adds orchestration overhead with no benefit. If there's only one step, use an activity directly.
+
+**Monolithic workflow:** All logic in one workflow with hundreds of history events. If a workflow has more than ~10 sequential activity calls, consider decomposing into child workflows.
+
+**Activity with orchestration:** If an activity contains retry logic, conditional branching, or calls to other services, it should be a workflow — these are orchestration concerns that benefit from Temporal's durability.
+
+See [child-workflows.md](../topics/child-workflows.md) for detailed child workflow patterns and the full decision table.
+
+For deployment topology and task queue routing, see [task-queues.md](../topics/task-queues.md).