@temporal-architect/claude-plugin 0.9.0

package/skills/temporal-architect/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: temporal-architect
+description: Entry point for designing, building, adopting, or evolving Temporal systems — start here. Coordinates the temporal-architect skill set (design, Go authoring, infrastructure): orients the design↔code direction, decomposes a `.twf` design into independently-implementable chunks at contract boundaries, and dispatches the right specialist skills. Use at the start of any Temporal architecture, workflow, worker, or Temporal-adoption task.
+---
+
+# Temporal Architect
+
+The front door to the `temporal-architect` skill set. This skill does not design or author directly — it **orients** the work, **decomposes** it at contract boundaries, and **routes** to the specialists:
+
+| Skill | Owns |
+|-------|------|
+| `temporal-architect-design` | The `.twf` design (workflows, activities, namespaces, Nexus). Produces/reviews `.twf`; never SDK code. |
+| `temporal-architect-author-go` | Go SDK implementation of a `.twf`. |
+| `temporal-architect-author-infra` | Control-plane provisioning (namespaces, Nexus endpoints, search attributes). Orthogonal to language authoring. |
+
+---
+
+## North Star
+
+`.twf` exists to **extend the complexity horizon of AI execution** — to let AI work at *system* scale, not code scale. (You don't cross a country on square-mile maps.) The largest gains in AI-assisted development came from wiring AIs into **deterministic tooling** — compilers, linters, testers. `temporal-architect` is that deterministic harness for **Temporal architecture**: it keeps the AI out of the weeds — error handling, library choices, application-code pedantics — so it can focus on the large scale: **workloads, scaling, reliability, availability**.
+
+The product is a **context-protecting harness for the main agent**: fit a bigger problem into the same context window. Decompose at `.twf` contract boundaries, dispatch the heavy authoring to subagents that each see only their chunk, and keep the main context on the architecture. (The "main agent" is not always the *design* agent — sometimes it is authoring or reverse-engineering. Don't assume.)
+
+Everything below serves that: protect context, raise the level of abstraction, and resist being dragged back down into code-scale busywork.
+
+---
+
+## Orient — which direction, which situation
+
+The design↔code edge is traversed in **two directions**. Identify which one the task needs before doing anything else.
+
+- **Direction A — `.twf` → application code** (forward authoring). The steady-state ideal: once a project has a `.twf`, *changes are made in the `.twf` first, then propagated forward* to the authors. Most work lives here.
+- **Direction B — application code → `.twf`** (recovery / reconciliation). Bootstraps a `.twf` from an existing app, and reconciles drift back into the `.twf`.
+
+Detect the **situation** cheaply (no subagent needed) and enter the matching path:
+
+| Situation | Cheap signal | Path |
+|-----------|--------------|------|
+| **Greenfield** | No `.twf`, no Temporal SDK usage in the repo | Design (A) → author forward |
+| **Existing app, no `.twf`** (dominant adoption path) | Temporal SDK imports / worker code, but no `.twf` | Recover `.twf` (B, design's reverse path) → then forward |
+| **`.twf` exists — implement / evolve** | `.twf` present | Edit the `.twf` first → propagate forward (A) |
+| **Drift** | Code and `.twf` disagree | Reconcile into the `.twf` (B) → then forward (A) |
+
+**On drift:** the steady state keeps the `.twf` authoritative, so drift should be rare — but the *hard problem is catching it*. There is no first-class detector yet. Lean on the feedback surfaces that exist: the author skills' build/test verify against the linked implementation, and (for production divergence) sampler-driven `twf graph --history` checks. When drift is found, route the fix **through the `.twf`** (B), then re-author forward — never patch the code and leave the `.twf` stale.
+
+Always check for prior artifacts first (existing `.twf`, `DESIGN.md`); the design skill's Orient covers this in depth. The detection-signal style here mirrors `temporal-architect-author-infra`'s Orient.
+
+---
+
+## Decompose — `twf graph chunks`
+
+Once a `.twf` exists (or has been recovered), decompose it into independently-implementable units before dispatching. The unit of decomposition is a **contract boundary** — `.twf` *is* the contract — **never finer**.
+
+Use **`twf graph chunks`**, which computes the decomposition from the design. **The tool informs; it does not impose** — you decide how to act on it. Its output has two cleanly-typed parts:
+
+- **#1 hard boundaries — you MUST dispatch separate subagents across these.** Discovered facts: isolated components today (a `nexusCall` is the cleanest contract cut, cross-namespace by construction), language boundaries later. Every definition lands in exactly one hard chunk.
+- **#2 soft divisions — you MAY use these.** Only emitted for a chunk that exceeds a complexity **ceiling** you instruct: ranked candidate cuts plus an inter-section **dependency DAG**.
+
+Other knobs: a **floor** flags chunks too granular for their own subagent (merge them up); loops are collapsed into one chunk and never cut; roots are heuristic. Run `twf graph chunks --help` for the exact flags.
+
+**Fallback (pre-tool):** if `twf graph chunks` is unavailable, enumerate chunks by hand from `twf symbols` / the `.twf` — heuristic roots (handler-bearing and Nexus-op-backing workflows, plus any with no inbound call edge) and their reachable children form connected components. Same dispatch logic, coarser input.
+
+The detailed protocol for reading the tool's output — hard/soft handling, floor/ceiling, the dependency DAG, selective dispatch against existing code, and contract pinning — is in [reference/decomposition.md](reference/decomposition.md). Read it before dispatching a non-trivial design.
+
+---
+
+## Dispatch — progressive, not a waterfall freeze
+
+Dispatch authoring **progressively**, in the dependency-DAG order the decomposition gives you:
+
+- **Don't freeze every signature up front.** A global type freeze recreates waterfall's failure modes. Pin contracts rigidly **only** at the hard-boundary / cross-language cuts the decomposition surfaces (these are exactly the expensive-to-renegotiate interfaces). Everywhere else, start from a **loose API suggestion** and let constraints discovered during authoring feed back and refine it.
+- **Don't parallelize everything.** Build independent chunks first, then the now-unblocked dependents — a PERT walk over the dependency DAG, not a blind fan-out.
+- **Only dispatch what needs altering.** The decomposition is over the *design*; the tool doesn't know what's already implemented. For each chunk, resolve its code via the `# impl: <dirs>` link (see the design skill's `twf-conventions.md`) and **skip chunks that are new-free and unchanged** — never spin up an author for a component that doesn't need it. Use the relevant author skill's fast verify (e.g. `author-go`'s `go build`/`go test` on the linked package) as the cheap changed-vs-unchanged signal. A first-class chunk↔impl staleness check does not exist yet.
+
+---
+
+## Route — which skills to load
+
+Routing is **advice with a sensible default, not a rigid rule**. Load the minimum that fits the work.
+
+**Default:** `temporal-architect-design` + the **one** author for the chunk's language, plus `temporal-architect-author-infra` if the topology needs control-plane resources (it is orthogonal to language authoring).
+
+Named exceptions:
+
+- **Skip design** when there is no design change — a pure implementation of a settled `.twf`. Load only the author(s).
+- **Design in the main agent.** Because the whole point is an elevated surface to design *from*, the user often wants to be integrated in the design loop. For design-heavy or collaborative work, load `temporal-architect-design` **into the main agent** rather than dispatching it to a subagent. Dispatch authoring to subagents to protect context.
+- **A language boundary wants both authors.** A workflow in one language calling an activity in another is a genuine (not rare) case. Pin the boundary contract once, then prefer **isolated per-language author subagents that exchange only that contract** — this keeps two SDK-language authors out of a single context, where their overlapping vocabulary is *confusable*. Co-loading both is acceptable when the boundary is small and the isolation overhead isn't worth it; the confusability concern is the reason to default to separating them, not a hard prohibition.
+
+`@lang` annotations (coming to the spec) will become the explicit dispatch key per chunk — don't over-engineer language routing before then; the heuristic + boundary handling above is enough.
+
+---
+
+## Reference Index
+
+| Topic | When to consult | File |
+|-------|-----------------|------|
+| Decomposition + dispatch protocol | Reading `twf graph chunks` output; planning subagent breakout | [decomposition.md](reference/decomposition.md) |
+
+The specialist skills carry their own references for design, Go authoring, and infrastructure — load the skill, not its internals, from here.

package/skills/temporal-architect/reference/decomposition.md

@@ -0,0 +1,78 @@
+# Decomposition + Dispatch Protocol
+
+How to turn a `.twf` design into a dispatch plan for author subagents, using `twf graph chunks`. Read this before breaking out a non-trivial design.
+
+The governing rule: **cut at `.twf` contract boundaries, never finer.** `.twf` *is* the contract. The tool **informs; it does not impose** — every output below is input to your judgment, not a command.
+
+## The command
+
+Run `twf graph chunks --help` for the exact, current flag set — that help is
+generated from the binary, so it never drifts from this prose. What the flags
+*mean* for dispatch:
+
+- `twf graph chunks` (no flags) — emits the **#1 hard partition** (every definition in exactly one chunk) + a per-chunk complexity score + floor-merge recommendations.
+- the **ceiling** flag — additionally emits **#2 soft divisions** (ranked candidate cuts + a dependency DAG) for any chunk scoring over it.
+- the **floor** flag — chunks below it are flagged "too granular for their own subagent."
+- the **by** flag — biases which soft-division strategy is suggested (reachable-subtree, `nexusCall`-boundary, worker, namespace).
+
+See [Complexity floor + ceiling](#complexity-floor--ceiling) below for how to choose the thresholds. If the subcommand is absent, use the [manual fallback](#manual-fallback).
+
+## #1 Hard boundaries — MUST dispatch separately
+
+Hard boundaries are discovered **facts** about the graph, not suggestions. Dispatch a **separate** author subagent per hard chunk:
+
+- **Isolated components** — disconnected pieces of the call structure are independent work.
+- **`nexusCall` cuts** — the cleanest contract boundary (cross-namespace/worker by construction). The Nexus operation signature *is* the contract; pin it.
+- **Language boundaries** — once `@lang` lands, a hard split keyed on per-node language. Until then, infer language from project layout / the user.
+
+Each definition belongs to exactly one hard chunk. A node reachable from two roots is reported as **overlap** (listed once, referenced by each root) — implement it once and let both chunks consume it; do not duplicate it across subagents.
+
+## #2 Soft divisions — MAY use
+
+Soft divisions appear only when a chunk exceeds the ceiling you set. They are **options** over an oversized chunk:
+
+- Treat the **ranked candidate cuts** as suggestions; pick the one that matches a real boundary in the domain, or decline to cut.
+- The **inter-section dependency DAG is the build order.** Author independent sections first, then the sections they unblock. This is the PERT walk — not a blind parallel fan-out.
+- **Loops are never cut.** An SCC-collapsed chunk (workflow-call cycle) is exempt regardless of score — implement it as one unit.
+
+## Complexity floor + ceiling
+
+A single deterministic AST-derived score drives both thresholds:
+
+- **Floor** — a chunk below the floor is too small to justify its own subagent. Merge it into the chunk that dispatches into it. Don't spin up an author per one-activity fragment.
+- **Ceiling** — caller-instructed; triggers #2. Set it to the largest chunk you want a single subagent to take on.
+
+Defaults ship documented and tunable; adjust per design rather than treating them as fixed.
+
+## Roots
+
+Roots are **heuristic**: in-degree-0 in the binding subgraph, `asyncBacking` targets (external entries despite an in-edge), handler-bearing workflows (signal/query/update), and in-cycle workflows with no external binding in-edge. Each root is tagged `source: heuristic|declared`. Today all are heuristic; that is acceptable. Declared inbound roots will later seed at higher priority without changing this protocol.
+
+Edge semantics worth knowing when reading output: `nexusCall` = contract cut; `asyncBacking` target = a root; `signalSend` = a *soft* edge that keeps two workflows in one blob but as **separate** roots/chunks (never treat it as a binding call edge).
+
+## Selective dispatch against existing work
+
+The decomposition is computed over the **design**. It does not know what is already implemented. Before dispatching any chunk:
+
+1. Resolve the chunk's definitions to code via the `# impl: <dirs>` link header (see `temporal-architect-design`'s `twf-conventions.md`).
+2. If there is **no linked code**, the chunk is new → dispatch an author.
+3. If there **is** linked code, run the author skill's fast verify on it as a cheap changed-vs-unchanged signal — e.g. `author-go`'s `go build` / `go test` on the linked package. Treat a clean build/test against the current `.twf` as "unchanged, skip"; a failure or a `.twf` edit touching that chunk as "changed, dispatch."
+4. **Skip unchanged chunks.** Never re-author a component that doesn't need altering — that is wasted context and risks churning working code.
+
+This is a stopgap: there is no first-class chunk↔impl staleness check (chunk identity + impl link + a quick verify). The build/test signal is coarse but cheap. Tracked as a chunks-consumer backlog item.
+
+## Pin contracts only where it pays
+
+Pin types/signatures **rigidly only at the hard-boundary and cross-language cuts** — the interfaces that are expensive to renegotiate and that multiple subagents depend on. Everywhere else, hand the author a **loose API suggestion** and let it refine the shape as it implements, feeding genuine constraints back. Freezing everything up front is waterfall; it caps the authors' autonomy and produces conflicting rework, not less of it.
+
+## Manual fallback
+
+When `twf graph chunks` is unavailable:
+
+1. Run `twf symbols` (or read the `.twf`) to list workflows, activities, and Nexus operations.
+2. Seed roots heuristically: handler-bearing workflows, Nexus-op-backing workflows, and any workflow with no inbound call.
+3. Walk call edges from each root to gather its reachable children; each connected component is a chunk.
+4. Treat `nexus` operations as contract cuts (separate chunks either side).
+5. Apply the same selective-dispatch and contract-pinning logic above.
+
+This is coarser (no complexity score, no ranked cuts) but follows the identical dispatch discipline, so adopting the tool later changes the *input*, not the protocol.

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

@@ -0,0 +1,16 @@
+# Skill: Temporal Architect — Go Authoring
+
+**Goal:** Translate a validated TWF design into correct, idiomatic Temporal Go SDK code.
+
+**Primary focus:** Translation fidelity. Design decisions are already made. The hard part is mapping DSL constructs to Go SDK patterns precisely — respecting determinism constraints, context propagation, error handling, and SDK idioms.
+
+**Scope:**
+- Produces: compilable Temporal Go SDK code
+- Consumes: a validated `.twf` file produced by the `design` skill
+- Does not: make workflow design decisions, modify the DSL, or produce code for other languages
+
+**Authoritative references:**
+- Temporal docs MCP server — consult for current Go SDK API, especially for patterns that change across SDK versions
+- `tools/spec/sections/` — source of truth for DSL construct semantics when mapping to Go (also `twf spec` / `twf spec <slug>`)
+
+**Entry point:** `SKILL.md` → `reference/` for specific construct mappings → consult Temporal docs MCP for SDK specifics

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

@@ -0,0 +1,191 @@
+---
+name: temporal-architect-author-go
+description: Generate Go code from .twf workflow designs using the Temporal Go SDK. Use when implementing workflows defined in TWF, producing compilable Go packages from DSL specifications.
+---
+
+# Temporal Architect: Go Authoring
+
+Generate functioning Go code from `.twf` (Temporal Workflow Format) files using the Temporal Go SDK. The primary goal is producing code that compiles, runs, and correctly implements the workflow design. Always produce `.go` files as deliverables.
+
+---
+
+## Core Principles
+
+**Root-down generation.** Start from root workflows (no parent), work down to children, then activities, then types. Each layer is constrained by what the layer above needs. Defer unknowns, revisit later.
+
+**Write only what is needed.** No speculative fields, no extra types, no over-generation. The minimum bridge between DSL intent and working Go.
+
+**Prefer imports over generation.** Check `go.mod` and existing project code first. Use well-known libraries when types match. Only generate stubs for application-specific types.
+
+**Iterative type resolution.** Work from certainty outward. Explicit signatures first, then derive from constructors/field access, then defer the rest. Revisit deferred types as surrounding code solidifies. See [types.md](./reference/types.md).
+
+**User as decision-maker.** The skill owns execution; the user owns consequential choices. Handle mechanical mappings, SDK boilerplate, and compilation fixes autonomously. Surface dependency choices, ambiguous domain logic, and architectural direction to the user — present specific options with tradeoffs, not open-ended questions. Revising a previously confirmed decision always requires user approval.
+> Example: "For ChargePayment, should I use stripe-go (official SDK, matches your existing stripe dependency) or a generic HTTP client (more flexible, but more boilerplate)?"
+
+---
+
+## Process
+
+### Orient
+
+Before generating, resolve **where the code lands** along two independent axes. Greenfield is the easy case; adoption into an existing repo is the common one, and an existing repo's conventions are **requirements to match**, not defaults to pick.
+
+| Axis | Existing repo | Greenfield |
+|------|---------------|------------|
+| **1. Greenfield vs. existing** | *Detect* — cheap signals below; if any fire, you are in an existing repo | *Ask* the user |
+| **2. Codegen variant** (proto-first vs. hand-written) | *Detect from the repo* and conform to it | *Ask*; default = hand-written |
+
+**Cheap detection signals** (check these first — no subagent needed):
+
+- `buf.gen.yaml` with a `protoc-gen-go_temporal` plugin → **proto-first**
+- generated `*_temporal.pb.go` files → **proto-first**
+- `(temporal.v1.activity)` / `(temporal.v1.workflow)` annotations in `.proto` files → **proto-first**
+- none of the above, hand-written `workflow.ExecuteActivity` call sites → **hand-written**
+
+**Variant → reference routing:**
+
+| Variant | Load |
+|---------|------|
+| proto-first | [proto-driven.md](./reference/proto-driven.md) (alias: "PFI") — read in addition to the construct references below |
+| hand-written | the construct references below (default) |
+
+Route on concrete repo signals, never on a name or acronym. Adding a new variant later = one reference file + one routing row.
+
+**For an existing repo, dispatch the shared `project-discovery` subagent** to scan a **bounded slice** (the domain or directory in scope — never the whole repo) and return a compact summary of tooling, layout, Temporal SDK usage, registration style, and existing `.twf`. Trigger it deliberately, not reflexively; 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). Project-convention discovery is the subagent's job, not the orchestrator's — consume its summary, don't re-scan in the main context.
+
+### 1. Context Gathering
+
+- Read `.twf` files in scope
+- Examine `go.mod`, existing project code, and conventions (for an existing repo, this is the discovery subagent's summary from Orient)
+- Ask the user about project context, domain, key dependencies — brief, targeted questions
+
+### 2. Dependency Resolution
+
+Identify external integration points for each activity and resolve to concrete types. See [dependency-resolution.md](./reference/dependency-resolution.md) for the full process. Deliverable: a dependency map confirmed by the user before generation begins.
+
+### 3. Planning
+
+- Identify root workflows (not called as children by other workflows in the `.twf` file)
+- Outline the generation order: roots → children → activities → types
+- Review the dependency map against planned type signatures — flag any conflicts
+- If the dependency map is incomplete, note which decisions are deferred
+- Surface ambiguities to the user
+
+### 4. Generate + Verify Incrementally
+
+Root-down, with build checks between layers. Consult [reference files](#reference-index) for DSL→Go mapping at each layer.
+
+| Layer | What | Check | Key references |
+|-------|------|-------|----------------|
+| 1a. Types + signatures | Structs, interfaces, function signatures (empty bodies, zero-value returns). Dependency map informs interface shapes | `go build` | [types.md](./reference/types.md) |
+| 1b. Activity stubs | Forward-declare all activity functions/methods with correct signatures, empty bodies, zero-value returns. This makes activity functions available as references for Layer 2 and enables the nil-pointer method pattern (`var a *Activities; workflow.ExecuteActivity(ctx, a.Foo, ...)`) | `go build` | [activity-def.md](./reference/activity-def.md) |
+| 2. Workflow bodies | Orchestration logic: activity calls, child workflows, signals, timers, selectors | `go build` | [workflow-def.md](./reference/workflow-def.md), [activity-call.md](./reference/activity-call.md) |
+| 3. Activity impl | Thin activity methods + concrete implementations behind interfaces | `go build` | [activity-def.md](./reference/activity-def.md) |
+| 4. Worker wiring | `cmd/` entry point: construct dependencies, wire activity struct, register types, start worker | `go build` | [worker.md](./reference/worker.md), [nexus-service-def.md](./reference/nexus-service-def.md) |
+| 5. Tests | At minimum, one happy-path test per workflow using `testsuite.WorkflowTestSuite`. Recommended: the three-layer approach below. Catches: activity name resolution failures, serialization round-trip issues, update handler races, missing activity options | `go test` | [three-layer-testing.md](./reference/three-layer-testing.md) |
+| 6. Final | Full correctness check | `go vet` | — |
+
+**Recommended: three-layer testing.** A happy-path workflow test is the floor, not the ceiling. For any non-trivial design, test in three layers — workflows (mock the activities interface), activities (mock the client interface), and clients (real system, behind a build tag) — because each layer catches bugs the others structurally cannot: workflow tests can't see inside activities, activity tests can't see the real client, and they also guard replay safety by pinning the activity-call sequence. Mechanics and patterns are in [three-layer-testing.md](./reference/three-layer-testing.md).
+
+After generation: present the code to the user for review.
+
+---
+
+## Activity Implementation Pattern
+
+See [activity-def.md](./reference/activity-def.md#activity-implementation-pattern) for the full pattern (struct, methods, interfaces, concrete implementations).
+
+### Implementation Depth
+
+Activity bodies in `.twf` are pseudocode that may describe richer logic than the generated code implements. When simplifying an activity relative to its TWF description, emit a `// TODO:` comment referencing the elided logic so the gap is visible:
+
+```go
+func (a *Activities) ValidateExtraction(ctx context.Context, doc Document) (ValidationResult, error) {
+    // TODO: format conformance checks, cross-field consistency, external reference lookups (see TWF)
+    if doc.Text == "" {
+        return ValidationResult{Valid: false, Reason: "empty text"}, nil
+    }
+    return ValidationResult{Valid: true}, nil
+}
+```
+
+For **examples and prototypes**, shallow implementations with `// TODO:` markers are appropriate — the goal is demonstrating workflow orchestration, not domain logic. For **production code**, ask the user which activities need full implementations and which are stubs.
+
+---
+
+## Output Conventions
+
+- Each `.twf` maps to a Go package; Go files live alongside `.twf` sources or where the user specifies
+- One file per workflow, shared types file if needed, activity files grouped logically
+- One `_test.go` file per workflow (at minimum) with happy-path workflow tests
+- Package names derived from `.twf` filename (snake_case)
+- Worker entry point in `cmd/`
+
+---
+
+## Reference Index
+
+Read only what the current generation step requires.
+
+### Definitions
+
+| DSL Construct | Go Mapping | File |
+|---------------|------------|------|
+| `workflow Name(...)` | Workflow function | [workflow-def.md](./reference/workflow-def.md) |
+| `activity Name(...)` | Activity function | [activity-def.md](./reference/activity-def.md) |
+| `worker Name:` | Worker entry point | [worker.md](./reference/worker.md) |
+| `nexus service Name:` | Nexus service + handlers | [nexus-service-def.md](./reference/nexus-service-def.md) |
+
+### Calls
+
+| DSL Construct | Go Mapping | File |
+|---------------|------------|------|
+| `activity Name(args) -> result` | `workflow.ExecuteActivity` | [activity-call.md](./reference/activity-call.md) |
+| `workflow Name(args) -> result` | `workflow.ExecuteChildWorkflow` | [workflow-call.md](./reference/workflow-call.md) |
+| `nexus Endpoint Service.Op(args) -> result` | `NexusClient.ExecuteOperation` | [nexus.md](./reference/nexus.md) |
+
+### Handlers
+
+| DSL Construct | Go Mapping | File |
+|---------------|------------|------|
+| `signal Name(params):` | Signal channel + selector | [signal-handler.md](./reference/signal-handler.md) |
+| `query Name(params) -> (Type):` | `workflow.SetQueryHandler` | [query-handler.md](./reference/query-handler.md) |
+| `update Name(params) -> (Type):` | `workflow.SetUpdateHandler` | [update-handler.md](./reference/update-handler.md) |
+
+### Async Primitives
+
+| DSL Construct | Go Mapping | File |
+|---------------|------------|------|
+| `await timer(duration)` | `workflow.Sleep` | [await-timer.md](./reference/await-timer.md) |
+| `promise p <- ...` | Future (deferred `.Get`) | [promise.md](./reference/promise.md) |
+| `state:` / `condition` / `set` / `unset` | `bool` + `workflow.Await` | [condition.md](./reference/condition.md) |
+
+### Compound Async
+
+| DSL Construct | Go Mapping | File |
+|---------------|------------|------|
+| `await all:` | `workflow.Go` + futures | [await-all.md](./reference/await-all.md) |
+| `await one:` | `workflow.NewSelector` | [await-one.md](./reference/await-one.md) |
+
+### Modifiers & Control Flow
+
+| DSL Construct | Go Mapping | File |
+|---------------|------------|------|
+| `options: ...` | `ActivityOptions` / `ChildWorkflowOptions` | [options.md](./reference/options.md) |
+| `detach workflow ...` | Fire-and-forget child (confirm start, skip result) | [detach.md](./reference/detach.md) |
+| `if`/`for`/`switch`/`break`/`continue` | Go equivalents | [control-flow.md](./reference/control-flow.md) |
+| `close complete`/`fail`/`continue_as_new` | `return` / `workflow.NewContinueAsNewError` | [close.md](./reference/close.md) |
+| `x = expr` | Variable declaration/assignment | [assignment.md](./reference/assignment.md) |
+| `heartbeat(details)` | `activity.RecordHeartbeat` | [heartbeat.md](./reference/heartbeat.md) |
+
+### Composite Patterns
+
+| Topic | File |
+|-------|------|
+| Update + condition + selector, signal + sleep + await | [composite-patterns.md](./reference/composite-patterns.md) |
+
+### Types
+
+| Topic | File |
+|-------|------|
+| Type resolution strategy | [types.md](./reference/types.md) |

package/skills/temporal-architect-author-go/SUBAGENT_ADOPTION.md

@@ -0,0 +1,161 @@
+# Subagent Adoption Plan
+
+Notes on splitting the author-go skill into an orchestrator + worker subagents.
+
+---
+
+## Why subagents
+
+The author-go skill has two kinds of work:
+
+1. **Interactive** -- context gathering, ambiguity resolution, activity body clarification, review. Requires user dialog.
+2. **Mechanical** -- SDK exploration, type generation, workflow body generation, build verification. Self-contained, parallelizable, context-heavy.
+
+Mixing both in one context window means the 20 reference files, SDK source, and build output compete for tokens with the user conversation. Subagents isolate the mechanical work and return only summaries.
+
+### Supporting data
+
+- Google Research (180 agent configs): multi-agent excels on **parallelizable/decomposable** tasks (80.9% improvement), but **degrades 39-70%** on sequential reasoning. Architecture should match task structure.
+- Anthropic guidance: start with single agent + skills, add subagents when context isolation or parallelism justifies it. Orchestrator-worker is the sanctioned pattern (no peer-to-peer).
+- Anthropic Agent SDK: subagents get isolated context windows, return summaries to orchestrator. Cannot spawn nested subagents.
+
+---
+
+## Architecture
+
+```
+author-go/SKILL.md (orchestrator, inline)
+  Owns all user dialog
+  Runs in main conversation context
+  Spawns subagents for mechanical work
+  │
+  ├── sdk-explorer (Explore agent)
+  │   Reads SDK source / docs to identify available types and imports
+  │   Returns: dependency manifest (types, imports, patterns available)
+  │
+  ├── go-codegen (general-purpose agent)
+  │   Preloads reference skills for TWF → Go mapping
+  │   Generates types, signatures, workflow bodies
+  │   Returns: generated .go files
+  │
+  └── build-verifier (Bash agent)
+      Runs go build / go vet
+      Diagnoses errors
+      Returns: pass/fail summary with actionable fixes
+```
+
+### Phase mapping
+
+| Phase | Owner | Why |
+|-------|-------|-----|
+| Phase 1: Context gathering | Orchestrator + sdk-explorer | Orchestrator asks user about project context. sdk-explorer runs in parallel scanning SDK/dependencies. |
+| Phase 2: Planning | Orchestrator | Requires ambiguity resolution with user. Consumes sdk-explorer's manifest. |
+| Phase 3 Layer 1: Types + signatures | go-codegen | Mechanical. Reference-heavy. Parallelizable per workflow tree. |
+| Phase 3 Layer 2: Workflow bodies | go-codegen | Mechanical TWF → Go SDK mapping. |
+| Phase 3 Layer 3: Activity bodies | Orchestrator | Pseudocode in .twf requires user clarification. |
+| Phase 3 Layer 4: Build verification | build-verifier | Verbose output stays isolated. Returns summary. |
+| Phase 4: Review | Orchestrator | User feedback loop. |
+
+---
+
+## Subagent definitions
+
+### sdk-explorer
+
+**Purpose:** Scan SDK and project dependencies to build a manifest of available types, imports, and patterns. Answers "what already exists?" so the orchestrator can follow the "prefer imports over generation" principle.
+
+**Critical:** Don't just `go doc` individual types in isolation. Trace the actual call chain from activity code to SDK method and verify every type in the signature. SDK types often have union/wrapper variants (e.g., `ToolParam` vs `ToolUnionParam`) that only surface when you check the struct field that accepts them. The manifest must reflect the types the code will actually compile against, not the types that look right by name.
+
+**Sources (suggest both, don't constrain):**
+- Local module cache: `$GOPATH/pkg/mod/go.temporal.io/sdk@version/`
+- Web: SDK docs, godoc, GitHub source
+
+**Returns:** Structured summary -- available types, import paths, relevant SDK patterns. For each SDK call site, include the exact method signature and the concrete types of every parameter and return value.
+
+```yaml
+---
+name: sdk-explorer
+description: Explore Temporal SDK and project dependencies to identify available types and imports.
+tools: Read, Glob, Grep, Bash, WebFetch, WebSearch
+model: sonnet
+---
+```
+
+### go-codegen
+
+**Purpose:** Generate Go code from TWF designs using the reference material. Handles Layers 1-2 (types, signatures, workflow bodies). Can run one instance per independent workflow tree for parallelism.
+
+**Preloads:** The author-go reference files via the `skills` field. This keeps the 20 reference docs out of the main conversation's context.
+
+```yaml
+---
+name: go-codegen
+description: Generate Go Temporal workflow code from TWF designs. Use for types, signatures, and workflow bodies.
+tools: Read, Write, Edit, Glob, Grep
+model: sonnet
+skills:
+  - temporal-go-reference
+---
+```
+
+### build-verifier
+
+**Purpose:** Run `go build` and `go vet`, diagnose errors, return actionable summary. Keeps verbose compiler output out of the main context.
+
+```yaml
+---
+name: build-verifier
+description: Run Go build and vet, diagnose errors, return summary.
+tools: Bash, Read, Glob, Grep
+model: haiku
+---
+```
+
+---
+
+## Skill composition
+
+Claude Code supports two composition directions:
+
+| Direction | Mechanism | Use case |
+|-----------|-----------|----------|
+| Skill spawns subagent | `context: fork` in skill frontmatter | Entire skill runs as isolated subagent |
+| Subagent loads skills | `skills` field in agent frontmatter | Subagent gets domain knowledge injected at startup |
+
+For author-go, we use **both**:
+- The main skill runs **inline** (no `context: fork`) because it needs user dialog
+- The go-codegen subagent **loads reference skills** so it has the TWF → Go mapping knowledge
+- The orchestrator (main conversation with skill loaded) spawns subagents via the Task tool
+
+---
+
+## Per-workflow-tree parallelism
+
+After Phase 2 identifies independent root workflows, each root + its children + its activities can be a separate go-codegen subagent invocation. They don't share state and can generate in parallel.
+
+Example: a .twf file with 3 independent root workflows → 3 parallel go-codegen subagents, each producing its own .go files.
+
+---
+
+## Cross-language generalization
+
+This pattern generalizes to other language targets:
+
+```
+.claude/agents/
+├── sdk-explorer.md          # shared, parameterized by language/SDK
+├── go-codegen.md            # Go-specific, loads go reference skills
+├── python-codegen.md        # Python-specific, loads python reference skills
+└── build-verifier.md        # parameterized (go build vs pytest vs tsc)
+```
+
+Each codegen agent loads only its language's reference material. The orchestrator skill per language (author-go, author-python, etc.) handles the dialog. A user request like "implement in Go and Python" spawns both codegen agents in parallel with full context isolation.
+
+---
+
+## Open questions
+
+- **Skill splitting granularity:** Should reference files become a separate skill (`temporal-go-reference`) that the codegen agent preloads, or should they stay as files the agent reads on demand?
+- **sdk-explorer scope:** Should it also scan the user's existing project code for conventions, or is that the orchestrator's job during Phase 1?
+- **Error recovery:** When build-verifier reports failures, should the orchestrator fix them directly or re-invoke go-codegen with the error context?
+- **Activity body generation:** Some activity bodies are unambiguous (simple SDK calls). Could a heuristic route "clear" bodies to a subagent and only surface "ambiguous" ones to the user?

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

@@ -0,0 +1,73 @@
+# activity call
+
+## DSL
+
+```twf
+activity ValidateOrder(order) -> validated
+```
+
+## Common Mistakes
+
+```go
+// WRONG: string activity name — loses compile-time safety, breaks test discovery
+err := workflow.ExecuteActivity(ctx, "ValidateOrder", order).Get(ctx, &validated)
+
+// RIGHT: function reference — compiler verifies the function exists
+err := workflow.ExecuteActivity(ctx, ValidateOrder, order).Get(ctx, &validated)
+
+// RIGHT: method reference via nil pointer (struct pattern)
+var a *Activities
+err := workflow.ExecuteActivity(ctx, a.ValidateOrder, order).Get(ctx, &validated)
+```
+
+## Go
+
+```go
+var validated ValidateResult
+err := workflow.ExecuteActivity(ctx, ValidateOrder, order).Get(ctx, &validated)
+if err != nil {
+    return Result{}, err
+}
+```
+
+## With inline options
+
+### DSL
+
+```twf
+activity ValidateOrder(order) -> validated
+    options:
+        start_to_close_timeout: 30s
+```
+
+### Go
+
+```go
+actCtx := workflow.WithActivityOptions(ctx, workflow.ActivityOptions{
+    StartToCloseTimeout: 30 * time.Second,
+})
+var validated ValidateResult
+err := workflow.ExecuteActivity(actCtx, ValidateOrder, order).Get(ctx, &validated)
+if err != nil {
+    return Result{}, err
+}
+```
+
+For the full options reference, see [options.md](./options.md).
+
+## Notes
+
+- No return value: omit the `Get` target variable, still check `err`
+- The activity function is passed by reference (not a string) — `workflow.ExecuteActivity(ctx, FuncName, args...)`
+- When using the struct method pattern (see [Activity Implementation Pattern](./activity-def.md#activity-implementation-pattern)), pass a method reference via nil pointer: `var a *Activities; workflow.ExecuteActivity(ctx, a.ValidateOrder, order)`
+- `ctx` must carry activity options; see [options.md](./options.md) for setting `ActivityOptions`
+
+## When to use inline options vs shared context
+
+- **Shared default context** (set `ActivityOptions` on `ctx` once near the top of the workflow): use when most activities share the same timeout and retry settings. This is the common case
+- **Per-activity inline options** (create a new context with `workflow.WithActivityOptions`): use when a specific activity needs different timeouts or retry behavior (e.g., a long-running activity alongside short ones)
+- When the DSL has an `options:` block on an activity call, always use per-activity inline options
+
+## Pitfalls
+
+- `ctx` must carry `ActivityOptions` with at least one of `StartToCloseTimeout` or `ScheduleToCloseTimeout`. Omitting both produces a runtime error when the activity is scheduled