Use claude to merge Steve's, Max's, and Mason's skills. (#2)

* Use claude to merge Steve's, Max's, and Mason's skills. Did a review pass using claude's skill devlopment skills

* Add missing things from Steve

* trigger tweaks

* Add in common gotchas from Johann

README.md

@@ -1 +1,112 @@
-# skill-temporal-dev
+# Temporal Development Skill
+
+A comprehensive skill for building Temporal applications in Python and TypeScript.
+
+## Overview
+
+This skill provides multi-language guidance for Temporal development, combining:
+- **Core concepts** shared across languages (determinism, patterns, versioning)
+- **Language-specific references** for Python and TypeScript
+- **Operational scripts** for worker and workflow management
+- **AI/LLM integration patterns** for building durable AI applications
+
+## Structure
+
+```
+temporal-dev/
+├── SKILL.md                    # Core architecture, quick references (always loaded)
+├── references/
+│   ├── core/                   # Language-agnostic concepts
+│   │   ├── determinism.md      # Why determinism matters, replay mechanics
+│   │   ├── patterns.md         # Signals, queries, saga, child workflows
+│   │   ├── versioning.md       # Patching, workflow types, worker versioning
+│   │   ├── troubleshooting.md  # Decision trees, recovery procedures
+│   │   ├── error-reference.md  # Common error types, workflow status
+│   │   ├── interactive-workflows.md # Testing signals, updates, queries
+│   │   ├── tool-reference.md   # Script options, worker management
+│   │   ├── logs.md             # Log file locations, search patterns
+│   │   └── ai-integration.md   # AI/LLM integration concepts
+│   ├── python/                 # Python SDK references
+│   │   ├── python.md           # SDK overview, quick start
+│   │   ├── sandbox.md          # Python sandbox mechanics
+│   │   ├── sync-vs-async.md    # Activity type selection
+│   │   ├── patterns.md         # Python implementations
+│   │   ├── testing.md          # WorkflowEnvironment, mocking
+│   │   ├── error-handling.md   # ApplicationError, retries
+│   │   ├── data-handling.md    # Pydantic, encryption
+│   │   ├── observability.md    # Logging, metrics
+│   │   ├── versioning.md       # Python patching API
+│   │   ├── advanced-features.md # Continue-as-new, interceptors
+│   │   └── ai-patterns.md      # Python AI Cookbook patterns
+│   └── typescript/             # TypeScript SDK references
+│       ├── typescript.md       # SDK overview, quick start
+│       ├── patterns.md         # TypeScript implementations
+│       ├── testing.md          # TestWorkflowEnvironment
+│       ├── error-handling.md   # ApplicationFailure
+│       ├── data-handling.md    # Data converters
+│       ├── observability.md    # Sinks, logging
+│       ├── versioning.md       # TypeScript patching API
+│       └── advanced-features.md # Cancellation scopes
+├── scripts/                    # Operational utilities
+│   ├── ensure-server.sh        # Start Temporal dev server
+│   ├── ensure-worker.sh        # Start worker for project
+│   ├── list-workers.sh         # List running workers
+│   ├── kill-worker.sh          # Stop specific worker
+│   ├── kill-all-workers.sh     # Stop ALL workers
+│   ├── monitor-worker-health.sh # Check worker health
+│   ├── list-recent-workflows.sh # Show recent executions
+│   ├── get-workflow-result.sh  # Get workflow output
+│   ├── find-stalled-workflows.sh # Find stuck workflows
+│   ├── analyze-workflow-error.sh # Diagnose failures
+│   ├── bulk-cancel-workflows.sh # Cancel multiple workflows
+│   ├── wait-for-workflow-status.sh # Poll workflow status
+│   ├── wait-for-worker-ready.sh # Poll worker startup
+│   └── find-project-workers.sh # Helper: find worker PIDs
+```
+
+## Progressive Disclosure
+
+The skill uses progressive loading to manage context efficiently:
+
+1. **SKILL.md** - Always loaded when skill triggers
+   - Core architecture diagram
+   - Determinism quick reference
+   - Pattern index with links
+   - Troubleshooting quick reference
+
+2. **Core references** - Loaded when discussing concepts
+   - Language-agnostic theory and patterns
+   - Versioning strategies
+   - Troubleshooting decision trees
+
+3. **Language references** - Loaded when working in that language
+   - SDK-specific implementations
+   - Language-specific gotchas
+   - Testing patterns
+
+## Content Sources
+
+This skill merges content from multiple sources:
+- **Steve's temporal-dev skill** - Operational scripts, troubleshooting
+- **Max's temporal-claude-skill** - Multi-SDK structure, AI integration
+- **Mason's python-sdk skill** - Python deep-dive, sandbox, sync/async
+- **Mason's typescript-sdk skill** - TypeScript patterns, V8 isolation
+
+## Trigger Phrases
+
+The skill activates on phrases like:
+- "create a Temporal workflow"
+- "write a Temporal activity"
+- "debug workflow stuck"
+- "fix non-determinism error"
+- "Temporal Python" / "Temporal TypeScript"
+- "workflow replay"
+- "activity timeout"
+- "signal workflow" / "query workflow"
+- "worker not starting"
+- "activity keeps retrying"
+- "Temporal heartbeat"
+- "continue-as-new"
+- "child workflow"
+- "saga pattern"
+- "workflow versioning"

SKILL.md

@@ -1,117 +1,188 @@
 ---
-name: temporal-dev
-description: "Start, stop, debug, and troubleshoot Temporal workflows for Python projects. Use when: starting workers, executing workflows, workflow is stalled/failed, non-determinism errors, checking workflow status, or managing temporal server start-dev lifecycle."
-version: 0.1.0
-allowed-tools: "Bash(.claude/skills/temporal/scripts/*:*), Read"
+name: Temporal Development
+description: This skill should be used when the user asks to "create a Temporal workflow", "write a Temporal activity", "debug stuck workflow", "fix non-determinism error", "Temporal Python", "Temporal TypeScript", "workflow replay", "activity timeout", "signal workflow", "query workflow", "worker not starting", "activity keeps retrying", "Temporal heartbeat", "continue-as-new", "child workflow", "saga pattern", "workflow versioning", "durable execution", "reliable distributed systems", or mentions Temporal SDK development. Provides multi-language guidance for Python and TypeScript with operational scripts.
+version: 1.0.0
 ---
 
-# Temporal Skill
+# Temporal Development
 
-Manage Temporal workflows using local development server (Python SDK, `temporal server start-dev`).
+## Overview
 
-## Environment Variables
+Temporal is a durable execution platform that makes workflows survive failures automatically. This skill provides guidance for building Temporal applications in Python and TypeScript.
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `CLAUDE_TEMPORAL_LOG_DIR` | `/tmp/claude-temporal-logs` | Worker log directory |
-| `CLAUDE_TEMPORAL_PID_DIR` | `/tmp/claude-temporal-pids` | Worker PID directory |
-| `TEMPORAL_ADDRESS` | `localhost:7233` | Temporal server gRPC address |
-| `TEMPORAL_WORKER_CMD` | `uv run worker` | Command to start worker |
+## Core Architecture
 
----
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Temporal Cluster                            │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌────────────────┐  │
+│  │  Event History  │  │   Task Queues   │  │   Visibility   │  │
+│  │  (Durable Log)  │  │  (Work Router)  │  │   (Search)     │  │
+│  └─────────────────┘  └─────────────────┘  └────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+                              ▲
+                              │ Poll / Complete
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                         Worker                                   │
+│  ┌─────────────────────────┐  ┌──────────────────────────────┐  │
+│  │   Workflow Definitions  │  │   Activity Implementations   │  │
+│  │   (Deterministic)       │  │   (Non-deterministic OK)     │  │
+│  └─────────────────────────┘  └──────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+```
 
-## Quick Start
+**Components:**
+- **Workflows** - Durable, deterministic functions that orchestrate activities
+- **Activities** - Non-deterministic operations (API calls, I/O) that can fail and retry
+- **Workers** - Long-running processes that poll task queues and execute code
+- **Task Queues** - Named queues connecting clients to workers
 
-```bash
-# 1. Start server
-./scripts/ensure-server.sh
+## History Replay: Why Determinism Matters
 
-# 2. Start worker (kills old workers, starts fresh)
-./scripts/ensure-worker.sh
+Temporal achieves durability through **history replay**:
 
-# 3. Execute workflow
-uv run starter  # Capture workflow_id from output
+1. **Initial Execution** - Worker runs workflow, generates Commands, stored as Events in history
+2. **Recovery** - On restart/failure, Worker re-executes workflow from beginning
+3. **Matching** - SDK compares generated Commands against stored Events
+4. **Restoration** - Uses stored Activity results instead of re-executing
 
-# 4. Wait for completion
-./scripts/wait-for-workflow-status.sh --workflow-id <id> --status COMPLETED
+**If Commands don't match Events = Non-determinism Error = Workflow blocked**
 
-# 5. Get result (verify it's correct, not an error message)
-./scripts/get-workflow-result.sh --workflow-id <id>
+| Workflow Code | Command | Event |
+|--------------|---------|-------|
+| Execute activity | `ScheduleActivityTask` | `ActivityTaskScheduled` |
+| Sleep/timer | `StartTimer` | `TimerStarted` |
+| Child workflow | `StartChildWorkflowExecution` | `ChildWorkflowExecutionStarted` |
 
-# 6. CLEANUP: Kill workers when done
-./scripts/kill-worker.sh
-```
+See `references/core/determinism.md` for detailed explanation.
 
----
+## Determinism Quick Reference
 
-## Common Recipes
+| Forbidden | Python | TypeScript |
+|-----------|--------|------------|
+| Current time | `workflow.now()` | `Date.now()` (auto-replaced) |
+| Random | `workflow.random()` | `Math.random()` (auto-replaced) |
+| UUID | `workflow.uuid4()` | `uuid4()` from workflow |
+| Sleep | `asyncio.sleep()` | `sleep()` from workflow |
 
-### Clean Start
-```bash
-./scripts/kill-all-workers.sh
-./scripts/ensure-server.sh
-./scripts/ensure-worker.sh
-uv run starter
-```
+**Python sandbox**: Explicit protection, use `workflow.unsafe.imports_passed_through()` for libraries
+**TypeScript sandbox**: V8 isolation, automatic replacements, use type-only imports for activities
 
-### Debug Stalled Workflow
-```bash
-./scripts/find-stalled-workflows.sh
-./scripts/analyze-workflow-error.sh --workflow-id <id>
-tail -100 $CLAUDE_TEMPORAL_LOG_DIR/worker-$(basename "$(pwd)").log
-# See references/troubleshooting.md for decision tree
-```
+## Language Selection
 
-### Clear Stalled Environment
-```bash
-./scripts/find-stalled-workflows.sh
-./scripts/bulk-cancel-workflows.sh
-./scripts/kill-worker.sh
-./scripts/ensure-worker.sh
-```
+### Python
+- Decorators: `@workflow.defn`, `@workflow.run`, `@activity.defn`
+- Async/await throughout
+- Explicit sandbox with pass-through pattern
+- **Critical**: Separate workflow and activity files for performance
+- See `references/python/python.md`
 
-### Check Recent Results
-```bash
-./scripts/list-recent-workflows.sh --minutes 30
-./scripts/get-workflow-result.sh --workflow-id <id>
-```
+### TypeScript
+- Functions exported from workflow file
+- `proxyActivities()` with type-only imports
+- V8 sandbox with automatic replacements
+- Webpack bundling for workflows
+- See `references/typescript/typescript.md`
 
----
+## Pattern Index
 
-## Key Scripts
+| Pattern | Use Case | Python | TypeScript |
+|---------|----------|--------|------------|
+| **Signals** | Fire-and-forget events to running workflow | `references/python/patterns.md` | `references/typescript/patterns.md` |
+| **Queries** | Read-only state inspection | `references/python/patterns.md` | `references/typescript/patterns.md` |
+| **Updates** | Synchronous state modification with response | `references/python/patterns.md` | `references/typescript/patterns.md` |
+| **Child Workflows** | Break down large workflows, isolate failures | `references/python/patterns.md` | `references/typescript/patterns.md` |
+| **Continue-as-New** | Prevent unbounded history growth | `references/python/advanced-features.md` | `references/typescript/advanced-features.md` |
+| **Saga** | Distributed transactions with compensation | `references/python/patterns.md` | `references/typescript/patterns.md` |
 
-| Script | Purpose |
-|--------|---------|
-| `ensure-server.sh` | Start dev server if not running |
-| `ensure-worker.sh` | Kill old workers, start fresh one |
-| `kill-worker.sh` | Kill current project's worker |
-| `kill-all-workers.sh` | Kill all workers (`--include-server` option) |
-| `find-stalled-workflows.sh` | Detect stalled workflows |
-| `analyze-workflow-error.sh` | Extract errors from history |
-| `wait-for-workflow-status.sh` | Block until status reached |
-| `get-workflow-result.sh` | Get workflow output |
+## Troubleshooting Quick Reference
 
-See `references/tool-reference.md` for full details.
+| Symptom | Likely Cause | Action |
+|---------|--------------|--------|
+| Workflow stuck (RUNNING but no progress) | Worker not running or wrong task queue | Check worker, verify task queue name |
+| `NondeterminismError` | Code changed mid-execution | Use patching API or reset workflow |
+| Activity keeps retrying | Activity throwing errors | Check activity logs, fix root cause |
+| Workflow FAILED | Unhandled exception in workflow | Check workflow error, fix code |
+| Timeout errors | Timeout too short or activity stuck | Increase timeout or add heartbeats |
 
----
+See `references/core/troubleshooting.md` for decision trees and detailed recovery steps.
 
-## References (Load When Needed)
+## Versioning
 
-| Reference | When to Read |
-|-----------|--------------|
-| `references/concepts.md` | Understanding workflow vs activity tasks, component architecture |
-| `references/troubleshooting.md` | Workflow stalled, failed, or misbehaving - decision tree and fixes |
-| `references/error-reference.md` | Looking up specific error types and recovery steps |
-| `references/tool-reference.md` | Script options and worker management details |
-| `references/interactive-workflows.md` | Signals, updates, queries for human-in-the-loop workflows |
-| `references/logs.md` | Log file locations and search commands |
+To safely change workflow code while workflows are running:
 
----
+1. **Patching API** - Code-level branching for old vs new paths
+2. **Workflow Type Versioning** - New workflow type for incompatible changes
+3. **Worker Versioning** - Deployment-level control with Build IDs
+
+See `references/core/versioning.md` for concepts, language-specific files for implementation.
 
-## Critical Rules
+## Scripts (Operational)
 
-1. **Always kill workers when done** - Don't leave stale workers running
-2. **One worker instance only** - Multiple workers cause non-determinism
-3. **Capture workflow_id** - You need it for all monitoring/troubleshooting
-4. **Verify results** - COMPLETED status doesn't mean correct result; check payload
-5. **Non-determinism: analyze first** - Use `analyze-workflow-error.sh` to understand the mismatch. If accidental: fix code to match history. If intentional v2 change: terminate and start fresh. See `references/troubleshooting.md`
+Available scripts in `scripts/` for worker and workflow management:
+
+### Server & Worker Lifecycle
+| Script | Purpose |
+|--------|---------|
+| `ensure-server.sh` | Start Temporal dev server if not running |
+| `ensure-worker.sh` | Start worker for project (kills existing first) |
+| `list-workers.sh` | List running workers |
+| `kill-worker.sh` | Stop a specific worker |
+| `kill-all-workers.sh` | Stop ALL workers (cleanup) |
+| `monitor-worker-health.sh` | Check worker health, uptime, recent errors |
+
+### Workflow Operations
+| Script | Purpose |
+|--------|---------|
+| `list-recent-workflows.sh` | Show recent workflow executions |
+| `get-workflow-result.sh` | Get output/result from completed workflow |
+| `find-stalled-workflows.sh` | Find workflows not making progress |
+| `analyze-workflow-error.sh` | Diagnose workflow failures |
+| `bulk-cancel-workflows.sh` | Cancel multiple workflows by ID or pattern |
+
+### Utilities (used by other scripts)
+| Script | Purpose |
+|--------|---------|
+| `wait-for-workflow-status.sh` | Poll until workflow reaches target status |
+| `wait-for-worker-ready.sh` | Poll log file for worker startup |
+| `find-project-workers.sh` | Helper to find worker PIDs for a project |
+
+## Additional Resources
+
+### Core References (Language-Agnostic)
+- **`references/core/determinism.md`** - Why determinism matters, replay mechanics
+- **`references/core/patterns.md`** - Conceptual patterns (signals, queries, saga)
+- **`references/core/versioning.md`** - Versioning strategies and concepts
+- **`references/core/troubleshooting.md`** - Decision trees, recovery procedures
+- **`references/core/error-reference.md`** - Common error types, workflow status reference
+- **`references/core/common-gotchas.md`** - Anti-patterns and common mistakes
+- **`references/core/interactive-workflows.md`** - Testing signals, updates, queries
+- **`references/core/tool-reference.md`** - Script options and worker management details
+- **`references/core/logs.md`** - Log file locations and search patterns
+- **`references/core/ai-integration.md`** - AI/LLM integration patterns
+
+### Python References
+- **`references/python/python.md`** - Python SDK overview, quick start
+- **`references/python/sandbox.md`** - Python sandbox mechanics
+- **`references/python/sync-vs-async.md`** - Activity type selection, event loop
+- **`references/python/patterns.md`** - Python pattern implementations
+- **`references/python/testing.md`** - WorkflowEnvironment, mocking
+- **`references/python/error-handling.md`** - ApplicationError, retries
+- **`references/python/data-handling.md`** - Pydantic, encryption
+- **`references/python/observability.md`** - Logging, metrics, tracing
+- **`references/python/versioning.md`** - Python patching API
+- **`references/python/advanced-features.md`** - Continue-as-new, interceptors
+- **`references/python/ai-patterns.md`** - Python AI Cookbook patterns
+- **`references/python/gotchas.md`** - Python-specific anti-patterns
+
+### TypeScript References
+- **`references/typescript/typescript.md`** - TypeScript SDK overview, quick start
+- **`references/typescript/patterns.md`** - TypeScript pattern implementations
+- **`references/typescript/testing.md`** - TestWorkflowEnvironment
+- **`references/typescript/error-handling.md`** - ApplicationFailure, retries
+- **`references/typescript/data-handling.md`** - Data converters
+- **`references/typescript/observability.md`** - Sinks, logging
+- **`references/typescript/versioning.md`** - TypeScript patching API
+- **`references/typescript/advanced-features.md`** - Cancellation scopes, interceptors
+- **`references/typescript/gotchas.md`** - TypeScript-specific anti-patterns