temporalio · donald-pinckney · Feb 13, 2026 · Feb 13, 2026 · Feb 13, 2026 · Feb 13, 2026
diff --git a/README.md b/README.md
@@ -7,7 +7,6 @@ A comprehensive skill for building Temporal applications in Python and TypeScrip
 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
@@ -23,7 +22,7 @@ temporal-dev/
 │   │   ├── 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
+│   │   ├── dev-management.md   # Dev cycle & management of server and workers
 │   │   ├── logs.md             # Log file locations, search patterns
 │   │   └── ai-integration.md   # AI/LLM integration concepts
 │   ├── python/                 # Python SDK references
@@ -36,7 +35,7 @@ temporal-dev/
 │   │   ├── data-handling.md    # Pydantic, encryption
 │   │   ├── observability.md    # Logging, metrics
 │   │   ├── versioning.md       # Python patching API
-│   │   ├── advanced-features.md # Continue-as-new, interceptors
+│   │   ├── advanced-features.md # Continue-as-new, updates, schedules, and more
 │   │   └── ai-patterns.md      # Python AI Cookbook patterns
 │   └── typescript/             # TypeScript SDK references
 │       ├── typescript.md       # SDK overview, quick start
@@ -46,22 +45,7 @@ temporal-dev/
 │       ├── 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
+│       └── advanced-features.md # Sinks, updates, schedules and more
 ```
 
 ## Progressive Disclosure
@@ -84,14 +68,6 @@ The skill uses progressive loading to manage context efficiently:
    - 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:

diff --git a/SKILL.md b/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: temporal-developer
-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.
+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.
 version: 1.0.0
 ---
 
@@ -118,36 +118,6 @@ To safely change workflow code while workflows are running:
 
 See `references/core/versioning.md` for concepts, language-specific files for implementation.
 
-## Scripts (Operational)
-
-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)
@@ -158,7 +128,7 @@ Available scripts in `scripts/` for worker and workflow management:
 - **`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/dev-management.md`** - Dev cycle & management of server and workers
 - **`references/core/logs.md`** - Log file locations and search patterns
 - **`references/core/ai-integration.md`** - AI/LLM integration patterns
 
@@ -172,7 +142,7 @@ Available scripts in `scripts/` for worker and workflow management:
 - **`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/advanced-features.md`** - Continue-as-new, updates, schedules, and more
 - **`references/python/ai-patterns.md`** - Python AI Cookbook patterns
 - **`references/python/gotchas.md`** - Python-specific anti-patterns
 
@@ -184,7 +154,7 @@ Available scripts in `scripts/` for worker and workflow management:
 - **`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/advanced-features.md`** - Sinks, updates, schedules and more
 - **`references/typescript/gotchas.md`** - TypeScript-specific anti-patterns
 
 ## Feedback

diff --git a/references/core/ai-integration.md b/references/core/ai-integration.md
@@ -4,7 +4,9 @@
 
 Temporal provides durable execution for AI/LLM applications, handling retries, rate limits, and long-running operations automatically. These patterns apply across languages, with Python being the most mature for AI integration.
 
-For Python-specific implementation details and code examples, see `references/python/ai-patterns.md`.
+For Python-specific implementation details and code examples, see `references/python/ai-patterns.md`. Temporal's Python SDK also provides pre-built integrations with several LLM and agent SDKs, which can be leveraged to create agentic workflows with minimal effort (when working in Python).
+
+The remainder of this document describes general principles to follow when building AI/LLM applications in Temporal, particularly when from scratch instead of with an integration.
 
 ## Why Temporal for AI?
 
@@ -19,28 +21,24 @@ For Python-specific implementation details and code examples, see `references/py
 
 ## Core Patterns
 
-### Pattern 1: Generic LLM Activity
-
-Create flexible, reusable activities for LLM calls:
+### Pattern 1: Activities should Wrap LLM Calls
 
-```
-Activity: call_llm_generic(
-    model: string,
-    system_instructions: string,
-    user_input: string,
-    tools?: list,
-    response_format?: schema
-) -> response
-```
+- activity: call_llm
+  - inputs:
+    - model_id -> internally activity can route to different models, so we don't need 1 activity per unique model.
+    - prompt / chat history
+    - tools
+    - etc.
+  - returns model response, as a typed structured output
 
 **Benefits**:
 - Single activity handles multiple use cases
 - Consistent retry handling
 - Centralized configuration
 
-### Pattern 2: Activity-Based Separation
+### Pattern 2: Non-deterministic / heavy tools in Activities
 
-Isolate each operation in its own activity:
+Tools which are non-deterministic and/or heavy actions (file system, hitting APIs, etc.) should be placed in activities:
 
 ```
 Workflow:
@@ -55,55 +53,32 @@ Workflow:
 - Easier testing and mocking
 - Failure isolation
 
-### Pattern 3: Centralized Retry Management
+### Pattern 3: Tools that Mutate Agent State can be in the Workflow directly
 
-**Critical**: Disable retries in LLM client libraries, let Temporal handle retries.
+Generally, agent state is in bijection with workflow state. Thus, tools which mutate agent state and are deterministic (like TODO tools, just updating a hash map) typically belong in the workflow code rather than an activity.
 
 ```
-LLM Client Config:
-  max_retries = 0  ← Disable client retries
-
-Activity Retry Policy:
-  initial_interval = 1s
-  backoff_coefficient = 2.0
-  maximum_attempts = 5
-  maximum_interval = 60s
+Workflow:
+  ├── Activity: call_llm (tool selection: todos_write tool)
+  ├── Write new TODOs to workflow state (not in activity)
+  └── Activity: call_llm (continuing agent flow...)
 ```
 
+### Pattern 4: Centralized Retry Management
+
+Disable retries in LLM client libraries, let Temporal handle retries.
+
+- LLM Client Config:
+  - max_retries = 0  ← Disable client retries at the LLM client level
+
+Use either the default activity retry policy, or customize it as needed for the situation.
+
 **Why**:
 - Temporal retries are durable (survive crashes)
 - Single retry configuration point
 - Better visibility into retry attempts
 - Consistent backoff behavior
 
-### Pattern 4: Tool-Calling Agent
-
-Three-phase workflow for LLM agents with tools:
-
-```
-┌─────────────────────────────────────────────┐
-│ Phase 1: Tool Selection                      │
-│   Activity: Present tools to LLM             │
-│   LLM returns: tool_name, arguments          │
-└─────────────────────────────────────────────┘
-                    │
-                    ▼
-┌─────────────────────────────────────────────┐
-│ Phase 2: Tool Execution                      │
-│   Activity: Execute selected tool            │
-│   (Separate activity per tool type)          │
-└─────────────────────────────────────────────┘
-                    │
-                    ▼
-┌─────────────────────────────────────────────┐
-│ Phase 3: Result Interpretation               │
-│   Activity: Send results back to LLM         │
-│   LLM returns: final response or next tool   │
-└─────────────────────────────────────────────┘
-                    │
-                    ▼
-        Loop until LLM returns final answer
-```
 
 ### Pattern 5: Multi-Agent Orchestration
 
@@ -127,21 +102,6 @@ Deep Research Example:
 
 **Key Pattern**: Use parallel execution with `return_exceptions=True` to continue with partial results when some searches fail.
 
-### Pattern 6: Structured Outputs
-
-Define schemas for LLM responses:
-
-```
-Input: Raw LLM prompt
-Schema: { action: string, confidence: float, reasoning: string }
-Output: Validated, typed response
-```
-
-**Benefits**:
-- Type safety
-- Automatic validation
-- Easier downstream processing
-
 ## Timeout Recommendations
 
 | Operation Type | Recommended Timeout |
@@ -165,27 +125,14 @@ Output: Validated, typed response
 
 Parse rate limit info from API responses:
 
-```
-Response Headers:
-  Retry-After: 30
-  X-RateLimit-Remaining: 0
-
-Activity:
-  If rate limited:
-    Raise retryable error with retry_after hint
-    Temporal handles the delay
-```
-
-### Retry Policy Configuration
+- Response Headers:
+  - Retry-After: 30
+  - X-RateLimit-Remaining: 0
 
-```
-Retry Policy:
-  initial_interval: 1s (or from Retry-After header)
-  backoff_coefficient: 2.0
-  maximum_interval: 60s
-  maximum_attempts: 10
-  non_retryable_errors: [InvalidAPIKey, InvalidInput]
-```
+- Activity:
+  - If rate limited:
+    - Raise retryable error with retry_after hint
+    - Temporal handles the delay
 
 ## Error Handling
 
@@ -209,15 +156,13 @@ Retry Policy:
 4. **Use structured outputs** - For type safety and validation
 5. **Handle partial failures** - Continue with available results
 6. **Monitor costs** - Track LLM calls at activity level
-7. **Version prompts** - Track prompt changes in code
-8. **Test with mocks** - Mock LLM responses in tests
+7. **Test with mocks** - Mock LLM responses in tests
 
 ## Observability
 
-- **Activity duration**: Track LLM latency
-- **Retry counts**: Monitor rate limiting
-- **Token usage**: Log in activity output
-- **Cost attribution**: Tag workflows with cost centers
+See `references/python/observability.md` (or the language you are working in) for documentation on observability in Temporal. It is generally recommended to add observability for:
+- Token usage, via activity logging
+- any else to help track LLM usage and debug agentic flows, within moderation.
 
 ## Language-Specific Resources