codehava-agent-kit 1.0.1 → 3.0.0

package/templates/.agent/skills/temporal-golang-pro/resources/testing-strategies.md

@@ -0,0 +1,145 @@
+# Temporal Go Testing Strategies
+
+Testing workflows and activities in Go requires a deep understanding of the `testsuite` package, which provides a mocked environment with deterministic time-skipping.
+
+## The Test Suite Setup
+
+Always use the `WorkflowTestSuite` to maintain state across multiple tests in a file.
+
+```go
+// Requires: "github.com/stretchr/testify/suite", "go.temporal.io/sdk/testsuite"
+type MyTestSuite struct {
+    suite.Suite
+    testsuite.WorkflowTestSuite
+    env *testsuite.TestWorkflowEnvironment
+}
+
+func (s *MyTestSuite) SetupTest() {
+    s.env = s.NewTestWorkflowEnvironment()
+}
+
+func TestMyTestSuite(t *testing.T) {
+    suite.Run(t, new(MyTestSuite))
+}
+```
+
+## 1. Unit Testing Workflows
+
+The most powerful feature of the Go SDK is **Time-skipping**. A workflow that sleeps for 30 days will finish in milliseconds in your test.
+
+### Mocking Activities
+
+You must register activity mocks before running the workflow.
+
+```go
+func (s *MyTestSuite) Test_SuccessfulWorkflow() {
+    // Mock the activity
+    s.env.OnActivity(MyActivity, mock.Anything, "input").Return("output", nil)
+
+    s.env.ExecuteWorkflow(MyWorkflow, "input")
+
+    s.True(s.env.IsWorkflowCompleted())
+    s.NoError(s.env.GetWorkflowError())
+
+    var result string
+    s.env.GetWorkflowResult(&result)
+    s.Equal("Completed", result)
+}
+```
+
+### Mocking Child Workflows
+
+Similar to activities, use `OnChildWorkflow`.
+
+```go
+s.env.OnChildWorkflow(MyChildWorkflow, mock.Anything, "args").Return("result", nil)
+```
+
+## 2. Unit Testing Activities
+
+Use `TestActivityEnvironment` to test activities in isolation.
+
+```go
+// Requires: "go.temporal.io/sdk/testsuite", "github.com/stretchr/testify/assert"
+func Test_Activity(t *testing.T) {
+    testSuite := &testsuite.WorkflowTestSuite{}
+    env := testSuite.NewTestActivityEnvironment()
+
+    env.RegisterActivity(MyActivity)
+
+    val, err := env.ExecuteActivity(MyActivity, "input")
+    assert.NoError(t, err)
+
+    var result string
+    val.Get(&result)
+    assert.Equal(t, "expected", result)
+}
+```
+
+## 3. Replay Testing (Determinism Check)
+
+Replay testing ensures that new code changes won't break existing, running workflows.
+
+```go
+func Test_ReplayStaticHistory(t *testing.T) {
+    replayer := worker.NewWorkflowReplayer()
+
+    replayer.RegisterWorkflow(MyWorkflow)
+
+    // Load history from JSON file (exported from Temporal Web UI or CLI).
+    // Web UI: Workflow Detail -> Download History (JSON)
+    // CLI:    temporal workflow show --workflow-id <id> --namespace <ns> --output json > history.json
+    err := replayer.ReplayWorkflowHistoryFromJSONFile(
+        worker.ReplayWorkflowHistoryFromJSONFileOptions{},
+        "history.json",
+    )
+    assert.NoError(t, err)
+}
+```
+
+## 4. Testing Signals and Queries
+
+You can send signals during a test at specific points in time.
+
+```go
+func (s *MyTestSuite) Test_WorkflowWithSignal() {
+    // Delayed signal
+    s.env.RegisterDelayedCallback(func() {
+        s.env.SignalWorkflow("my-signal", "data")
+    }, time.Hour) // This hour passes instantly!
+
+    s.env.ExecuteWorkflow(MyWorkflow)
+
+    // Query state after signal
+    res, err := s.env.QueryWorkflow("get-state")
+    s.NoError(err)
+    var state string
+    res.Get(&state)
+    s.Equal("SignalReceived", state)
+}
+```
+
+## Best Practices for Testing
+
+- **>=80% Coverage**: Aim for high coverage on workflow logic since activities are often just wrappers around DB/API calls.
+- **Assertion-based**: Use `testify/assert` or `testify/suite` for clean assertions.
+- **Mock Everything External**: Never call a real database or API in a unit test.
+- **Test Failure Paths**: Explicitly test what happens when an activity returns an error or when a heartbeat times out.
+
+### Example: Testing an Activity Failure Path
+
+```go
+func (s *MyTestSuite) Test_WorkflowHandlesActivityError() {
+    // Mock the activity to return a non-retryable error
+    s.env.OnActivity(ChargePaymentActivity, mock.Anything, mock.Anything).
+        Return("", temporal.NewNonRetryableApplicationError("card declined", "PaymentError", nil))
+
+    s.env.ExecuteWorkflow(SubscriptionWorkflow, "user-123")
+
+    s.True(s.env.IsWorkflowCompleted())
+    // Verify the workflow correctly surfaces the error
+    err := s.env.GetWorkflowError()
+    s.Error(err)
+    s.Contains(err.Error(), "card declined")
+}
+```

package/templates/.agent/skills/temporal-python-pro/SKILL.md

@@ -0,0 +1,368 @@
+---
+name: temporal-python-pro
+description: Master Temporal workflow orchestration with Python SDK. Implements durable workflows, saga patterns, and distributed transactions. Covers async/await, testing strategies, and production deployment.
+risk: unknown
+source: community
+date_added: '2026-02-27'
+---
+
+## Use this skill when
+
+- Working on temporal python pro tasks or workflows
+- Needing guidance, best practices, or checklists for temporal python pro
+
+## Do not use this skill when
+
+- The task is unrelated to temporal python pro
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+You are an expert Temporal workflow developer specializing in Python SDK implementation, durable workflow design, and production-ready distributed systems.
+
+## Purpose
+
+Expert Temporal developer focused on building reliable, scalable workflow orchestration systems using the Python SDK. Masters workflow design patterns, activity implementation, testing strategies, and production deployment for long-running processes and distributed transactions.
+
+## Capabilities
+
+### Python SDK Implementation
+
+**Worker Configuration and Startup**
+
+- Worker initialization with proper task queue configuration
+- Workflow and activity registration patterns
+- Concurrent worker deployment strategies
+- Graceful shutdown and resource cleanup
+- Connection pooling and retry configuration
+
+**Workflow Implementation Patterns**
+
+- Workflow definition with `@workflow.defn` decorator
+- Async/await workflow entry points with `@workflow.run`
+- Workflow-safe time operations with `workflow.now()`
+- Deterministic workflow code patterns
+- Signal and query handler implementation
+- Child workflow orchestration
+- Workflow continuation and completion strategies
+
+**Activity Implementation**
+
+- Activity definition with `@activity.defn` decorator
+- Sync vs async activity execution models
+- ThreadPoolExecutor for blocking I/O operations
+- ProcessPoolExecutor for CPU-intensive tasks
+- Activity context and cancellation handling
+- Heartbeat reporting for long-running activities
+- Activity-specific error handling
+
+### Async/Await and Execution Models
+
+**Three Execution Patterns** (Source: docs.temporal.io):
+
+1. **Async Activities** (asyncio)
+   - Non-blocking I/O operations
+   - Concurrent execution within worker
+   - Use for: API calls, async database queries, async libraries
+
+2. **Sync Multithreaded** (ThreadPoolExecutor)
+   - Blocking I/O operations
+   - Thread pool manages concurrency
+   - Use for: sync database clients, file operations, legacy libraries
+
+3. **Sync Multiprocess** (ProcessPoolExecutor)
+   - CPU-intensive computations
+   - Process isolation for parallel processing
+   - Use for: data processing, heavy calculations, ML inference
+
+**Critical Anti-Pattern**: Blocking the async event loop turns async programs into serial execution. Always use sync activities for blocking operations.
+
+### Error Handling and Retry Policies
+
+**ApplicationError Usage**
+
+- Non-retryable errors with `non_retryable=True`
+- Custom error types for business logic
+- Dynamic retry delay with `next_retry_delay`
+- Error message and context preservation
+
+**RetryPolicy Configuration**
+
+- Initial retry interval and backoff coefficient
+- Maximum retry interval (cap exponential backoff)
+- Maximum attempts (eventual failure)
+- Non-retryable error types classification
+
+**Activity Error Handling**
+
+- Catching `ActivityError` in workflows
+- Extracting error details and context
+- Implementing compensation logic
+- Distinguishing transient vs permanent failures
+
+**Timeout Configuration**
+
+- `schedule_to_close_timeout`: Total activity duration limit
+- `start_to_close_timeout`: Single attempt duration
+- `heartbeat_timeout`: Detect stalled activities
+- `schedule_to_start_timeout`: Queuing time limit
+
+### Signal and Query Patterns
+
+**Signals** (External Events)
+
+- Signal handler implementation with `@workflow.signal`
+- Async signal processing within workflow
+- Signal validation and idempotency
+- Multiple signal handlers per workflow
+- External workflow interaction patterns
+
+**Queries** (State Inspection)
+
+- Query handler implementation with `@workflow.query`
+- Read-only workflow state access
+- Query performance optimization
+- Consistent snapshot guarantees
+- External monitoring and debugging
+
+**Dynamic Handlers**
+
+- Runtime signal/query registration
+- Generic handler patterns
+- Workflow introspection capabilities
+
+### State Management and Determinism
+
+**Deterministic Coding Requirements**
+
+- Use `workflow.now()` instead of `datetime.now()`
+- Use `workflow.random()` instead of `random.random()`
+- No threading, locks, or global state
+- No direct external calls (use activities)
+- Pure functions and deterministic logic only
+
+**State Persistence**
+
+- Automatic workflow state preservation
+- Event history replay mechanism
+- Workflow versioning with `workflow.get_version()`
+- Safe code evolution strategies
+- Backward compatibility patterns
+
+**Workflow Variables**
+
+- Workflow-scoped variable persistence
+- Signal-based state updates
+- Query-based state inspection
+- Mutable state handling patterns
+
+### Type Hints and Data Classes
+
+**Python Type Annotations**
+
+- Workflow input/output type hints
+- Activity parameter and return types
+- Data classes for structured data
+- Pydantic models for validation
+- Type-safe signal and query handlers
+
+**Serialization Patterns**
+
+- JSON serialization (default)
+- Custom data converters
+- Protobuf integration
+- Payload encryption
+- Size limit management (2MB per argument)
+
+### Testing Strategies
+
+**WorkflowEnvironment Testing**
+
+- Time-skipping test environment setup
+- Instant execution of `workflow.sleep()`
+- Fast testing of month-long workflows
+- Workflow execution validation
+- Mock activity injection
+
+**Activity Testing**
+
+- ActivityEnvironment for unit tests
+- Heartbeat validation
+- Timeout simulation
+- Error injection testing
+- Idempotency verification
+
+**Integration Testing**
+
+- Full workflow with real activities
+- Local Temporal server with Docker
+- End-to-end workflow validation
+- Multi-workflow coordination testing
+
+**Replay Testing**
+
+- Determinism validation against production histories
+- Code change compatibility verification
+- Continuous integration replay testing
+
+### Production Deployment
+
+**Worker Deployment Patterns**
+
+- Containerized worker deployment (Docker/Kubernetes)
+- Horizontal scaling strategies
+- Task queue partitioning
+- Worker versioning and gradual rollout
+- Blue-green deployment for workers
+
+**Monitoring and Observability**
+
+- Workflow execution metrics
+- Activity success/failure rates
+- Worker health monitoring
+- Queue depth and lag metrics
+- Custom metric emission
+- Distributed tracing integration
+
+**Performance Optimization**
+
+- Worker concurrency tuning
+- Connection pool sizing
+- Activity batching strategies
+- Workflow decomposition for scalability
+- Memory and CPU optimization
+
+**Operational Patterns**
+
+- Graceful worker shutdown
+- Workflow execution queries
+- Manual workflow intervention
+- Workflow history export
+- Namespace configuration and isolation
+
+## When to Use Temporal Python
+
+**Ideal Scenarios**:
+
+- Distributed transactions across microservices
+- Long-running business processes (hours to years)
+- Saga pattern implementation with compensation
+- Entity workflow management (carts, accounts, inventory)
+- Human-in-the-loop approval workflows
+- Multi-step data processing pipelines
+- Infrastructure automation and orchestration
+
+**Key Benefits**:
+
+- Automatic state persistence and recovery
+- Built-in retry and timeout handling
+- Deterministic execution guarantees
+- Time-travel debugging with replay
+- Horizontal scalability with workers
+- Language-agnostic interoperability
+
+## Common Pitfalls
+
+**Determinism Violations**:
+
+- Using `datetime.now()` instead of `workflow.now()`
+- Random number generation with `random.random()`
+- Threading or global state in workflows
+- Direct API calls from workflows
+
+**Activity Implementation Errors**:
+
+- Non-idempotent activities (unsafe retries)
+- Missing timeout configuration
+- Blocking async event loop with sync code
+- Exceeding payload size limits (2MB)
+
+**Testing Mistakes**:
+
+- Not using time-skipping environment
+- Testing workflows without mocking activities
+- Ignoring replay testing in CI/CD
+- Inadequate error injection testing
+
+**Deployment Issues**:
+
+- Unregistered workflows/activities on workers
+- Mismatched task queue configuration
+- Missing graceful shutdown handling
+- Insufficient worker concurrency
+
+## Integration Patterns
+
+**Microservices Orchestration**
+
+- Cross-service transaction coordination
+- Saga pattern with compensation
+- Event-driven workflow triggers
+- Service dependency management
+
+**Data Processing Pipelines**
+
+- Multi-stage data transformation
+- Parallel batch processing
+- Error handling and retry logic
+- Progress tracking and reporting
+
+**Business Process Automation**
+
+- Order fulfillment workflows
+- Payment processing with compensation
+- Multi-party approval processes
+- SLA enforcement and escalation
+
+## Best Practices
+
+**Workflow Design**:
+
+1. Keep workflows focused and single-purpose
+2. Use child workflows for scalability
+3. Implement idempotent activities
+4. Configure appropriate timeouts
+5. Design for failure and recovery
+
+**Testing**:
+
+1. Use time-skipping for fast feedback
+2. Mock activities in workflow tests
+3. Validate replay with production histories
+4. Test error scenarios and compensation
+5. Achieve high coverage (≥80% target)
+
+**Production**:
+
+1. Deploy workers with graceful shutdown
+2. Monitor workflow and activity metrics
+3. Implement distributed tracing
+4. Version workflows carefully
+5. Use workflow queries for debugging
+
+## Resources
+
+**Official Documentation**:
+
+- Python SDK: python.temporal.io
+- Core Concepts: docs.temporal.io/workflows
+- Testing Guide: docs.temporal.io/develop/python/testing-suite
+- Best Practices: docs.temporal.io/develop/best-practices
+
+**Architecture**:
+
+- Temporal Architecture: github.com/temporalio/temporal/blob/main/docs/architecture/README.md
+- Testing Patterns: github.com/temporalio/temporal/blob/main/docs/development/testing.md
+
+**Key Takeaways**:
+
+1. Workflows = orchestration, Activities = external calls
+2. Determinism is mandatory for workflows
+3. Idempotency is critical for activities
+4. Test with time-skipping for fast feedback
+5. Monitor and observe in production

package/templates/.agent/skills/temporal-python-testing/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: temporal-python-testing
+description: "Comprehensive testing approaches for Temporal workflows using pytest, progressive disclosure resources for specific testing scenarios."
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# Temporal Python Testing Strategies
+
+Comprehensive testing approaches for Temporal workflows using pytest, progressive disclosure resources for specific testing scenarios.
+
+## Do not use this skill when
+
+- The task is unrelated to temporal python testing strategies
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Use this skill when
+
+- **Unit testing workflows** - Fast tests with time-skipping
+- **Integration testing** - Workflows with mocked activities
+- **Replay testing** - Validate determinism against production histories
+- **Local development** - Set up Temporal server and pytest
+- **CI/CD integration** - Automated testing pipelines
+- **Coverage strategies** - Achieve ≥80% test coverage
+
+## Testing Philosophy
+
+**Recommended Approach** (Source: docs.temporal.io/develop/python/testing-suite):
+
+- Write majority as integration tests
+- Use pytest with async fixtures
+- Time-skipping enables fast feedback (month-long workflows → seconds)
+- Mock activities to isolate workflow logic
+- Validate determinism with replay testing
+
+**Three Test Types**:
+
+1. **Unit**: Workflows with time-skipping, activities with ActivityEnvironment
+2. **Integration**: Workers with mocked activities
+3. **End-to-end**: Full Temporal server with real activities (use sparingly)
+
+## Available Resources
+
+This skill provides detailed guidance through progressive disclosure. Load specific resources based on your testing needs:
+
+### Unit Testing Resources
+
+**File**: `resources/unit-testing.md`
+**When to load**: Testing individual workflows or activities in isolation
+**Contains**:
+
+- WorkflowEnvironment with time-skipping
+- ActivityEnvironment for activity testing
+- Fast execution of long-running workflows
+- Manual time advancement patterns
+- pytest fixtures and patterns
+
+### Integration Testing Resources
+
+**File**: `resources/integration-testing.md`
+**When to load**: Testing workflows with mocked external dependencies
+**Contains**:
+
+- Activity mocking strategies
+- Error injection patterns
+- Multi-activity workflow testing
+- Signal and query testing
+- Coverage strategies
+
+### Replay Testing Resources
+
+**File**: `resources/replay-testing.md`
+**When to load**: Validating determinism or deploying workflow changes
+**Contains**:
+
+- Determinism validation
+- Production history replay
+- CI/CD integration patterns
+- Version compatibility testing
+
+### Local Development Resources
+
+**File**: `resources/local-setup.md`
+**When to load**: Setting up development environment
+**Contains**:
+
+- Docker Compose configuration
+- pytest setup and configuration
+- Coverage tool integration
+- Development workflow
+
+## Quick Start Guide
+
+### Basic Workflow Test
+
+```python
+import pytest
+from temporalio.testing import WorkflowEnvironment
+from temporalio.worker import Worker
+
+@pytest.fixture
+async def workflow_env():
+    env = await WorkflowEnvironment.start_time_skipping()
+    yield env
+    await env.shutdown()
+
+@pytest.mark.asyncio
+async def test_workflow(workflow_env):
+    async with Worker(
+        workflow_env.client,
+        task_queue="test-queue",
+        workflows=[YourWorkflow],
+        activities=[your_activity],
+    ):
+        result = await workflow_env.client.execute_workflow(
+            YourWorkflow.run,
+            args,
+            id="test-wf-id",
+            task_queue="test-queue",
+        )
+        assert result == expected
+```
+
+### Basic Activity Test
+
+```python
+from temporalio.testing import ActivityEnvironment
+
+async def test_activity():
+    env = ActivityEnvironment()
+    result = await env.run(your_activity, "test-input")
+    assert result == expected_output
+```
+
+## Coverage Targets
+
+**Recommended Coverage** (Source: docs.temporal.io best practices):
+
+- **Workflows**: ≥80% logic coverage
+- **Activities**: ≥80% logic coverage
+- **Integration**: Critical paths with mocked activities
+- **Replay**: All workflow versions before deployment
+
+## Key Testing Principles
+
+1. **Time-Skipping** - Month-long workflows test in seconds
+2. **Mock Activities** - Isolate workflow logic from external dependencies
+3. **Replay Testing** - Validate determinism before deployment
+4. **High Coverage** - ≥80% target for production workflows
+5. **Fast Feedback** - Unit tests run in milliseconds
+
+## How to Use Resources
+
+**Load specific resource when needed**:
+
+- "Show me unit testing patterns" → Load `resources/unit-testing.md`
+- "How do I mock activities?" → Load `resources/integration-testing.md`
+- "Setup local Temporal server" → Load `resources/local-setup.md`
+- "Validate determinism" → Load `resources/replay-testing.md`
+
+## Additional References
+
+- Python SDK Testing: docs.temporal.io/develop/python/testing-suite
+- Testing Patterns: github.com/temporalio/temporal/blob/main/docs/development/testing.md
+- Python Samples: github.com/temporalio/samples-python