codehava-agent-kit 1.0.1 → 3.0.0

package/templates/.agent/skills/dbos-golang/references/workflow-timeout.md

@@ -0,0 +1,38 @@
+---
+title: Set Workflow Timeouts
+impact: CRITICAL
+impactDescription: Prevents workflows from running indefinitely
+tags: workflow, timeout, cancellation, duration
+---
+
+## Set Workflow Timeouts
+
+Set a timeout for a workflow by using Go's `context.WithTimeout` or `dbos.WithTimeout` on the DBOS context. When the timeout expires, the workflow and all its children are cancelled.
+
+**Incorrect (no timeout for potentially long workflow):**
+
+```go
+// No timeout - could run indefinitely
+handle, err := dbos.RunWorkflow(ctx, processTask, "data")
+```
+
+**Correct (with timeout):**
+
+```go
+// Create a context with a 5-minute timeout
+timedCtx, cancel := dbos.WithTimeout(ctx, 5*time.Minute)
+defer cancel()
+
+handle, err := dbos.RunWorkflow(timedCtx, processTask, "data")
+if err != nil {
+	log.Fatal(err)
+}
+```
+
+Key timeout behaviors:
+- Timeouts are **start-to-completion**: the timeout begins when the workflow starts execution, not when it's enqueued
+- Timeouts are **durable**: they persist across restarts, so workflows can have very long timeouts (hours, days, weeks)
+- Cancellation happens at the **beginning of the next step** - the current step completes first
+- Cancelling a workflow also cancels all **child workflows**
+
+Reference: [Workflow Timeouts](https://docs.dbos.dev/golang/tutorials/workflow-tutorial#workflow-timeouts)

package/templates/.agent/skills/dbos-python/AGENTS.md

@@ -0,0 +1,95 @@
+# dbos-python
+
+> **Note:** `CLAUDE.md` is a symlink to this file.
+
+## Overview
+
+DBOS Python SDK for building reliable, fault-tolerant applications with durable workflows. Use this skill when writing Python code with DBOS, creating workflows and steps, using queues, using DBOSClient from external applications, or building applications that need to be resilient to failures.
+
+## Structure
+
+```
+dbos-python/
+  SKILL.md       # Main skill file - read this first
+  AGENTS.md      # This navigation guide
+  CLAUDE.md      # Symlink to AGENTS.md
+  references/    # Detailed reference files
+```
+
+## Usage
+
+1. Read `SKILL.md` for the main skill instructions
+2. Browse `references/` for detailed documentation on specific topics
+3. Reference files are loaded on-demand - read only what you need
+
+## Reference Categories
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Lifecycle | CRITICAL | `lifecycle-` |
+| 2 | Workflow | CRITICAL | `workflow-` |
+| 3 | Step | HIGH | `step-` |
+| 4 | Queue | HIGH | `queue-` |
+| 5 | Communication | MEDIUM | `comm-` |
+| 6 | Pattern | MEDIUM | `pattern-` |
+| 7 | Testing | LOW-MEDIUM | `test-` |
+| 8 | Client | MEDIUM | `client-` |
+| 9 | Advanced | LOW | `advanced-` |
+
+Reference files are named `{prefix}-{topic}.md` (e.g., `query-missing-indexes.md`).
+
+## Available References
+
+**Advanced** (`advanced-`):
+- `references/advanced-async.md`
+- `references/advanced-patching.md`
+- `references/advanced-versioning.md`
+
+**Client** (`client-`):
+- `references/client-enqueue.md`
+- `references/client-setup.md`
+
+**Communication** (`comm-`):
+- `references/comm-events.md`
+- `references/comm-messages.md`
+- `references/comm-streaming.md`
+
+**Lifecycle** (`lifecycle-`):
+- `references/lifecycle-config.md`
+- `references/lifecycle-fastapi.md`
+
+**Pattern** (`pattern-`):
+- `references/pattern-classes.md`
+- `references/pattern-debouncing.md`
+- `references/pattern-idempotency.md`
+- `references/pattern-scheduled.md`
+- `references/pattern-sleep.md`
+
+**Queue** (`queue-`):
+- `references/queue-basics.md`
+- `references/queue-concurrency.md`
+- `references/queue-deduplication.md`
+- `references/queue-listening.md`
+- `references/queue-partitioning.md`
+- `references/queue-priority.md`
+- `references/queue-rate-limiting.md`
+
+**Step** (`step-`):
+- `references/step-basics.md`
+- `references/step-retries.md`
+- `references/step-transactions.md`
+
+**Testing** (`test-`):
+- `references/test-fixtures.md`
+
+**Workflow** (`workflow-`):
+- `references/workflow-background.md`
+- `references/workflow-constraints.md`
+- `references/workflow-control.md`
+- `references/workflow-determinism.md`
+- `references/workflow-introspection.md`
+- `references/workflow-timeout.md`
+
+---
+
+*32 reference files across 9 categories*

package/templates/.agent/skills/dbos-python/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: dbos-python
+description: "Guide for building reliable, fault-tolerant Python applications with DBOS durable workflows. Use when adding DBOS to existing Python code, creating workflows and steps, or using queues for concurrency control."
+risk: safe
+source: "https://docs.dbos.dev/"
+date_added: "2026-02-27"
+---
+
+# DBOS Python Best Practices
+
+Guide for building reliable, fault-tolerant Python applications with DBOS durable workflows.
+
+## When to Use
+Reference these guidelines when:
+- Adding DBOS to existing Python code
+- Creating workflows and steps
+- Using queues for concurrency control
+- Implementing workflow communication (events, messages, streams)
+- Configuring and launching DBOS applications
+- Using DBOSClient from external applications
+- Testing DBOS applications
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Lifecycle | CRITICAL | `lifecycle-` |
+| 2 | Workflow | CRITICAL | `workflow-` |
+| 3 | Step | HIGH | `step-` |
+| 4 | Queue | HIGH | `queue-` |
+| 5 | Communication | MEDIUM | `comm-` |
+| 6 | Pattern | MEDIUM | `pattern-` |
+| 7 | Testing | LOW-MEDIUM | `test-` |
+| 8 | Client | MEDIUM | `client-` |
+| 9 | Advanced | LOW | `advanced-` |
+
+## Critical Rules
+
+### DBOS Configuration and Launch
+
+A DBOS application MUST configure and launch DBOS inside its main function:
+
+```python
+import os
+from dbos import DBOS, DBOSConfig
+
+@DBOS.workflow()
+def my_workflow():
+    pass
+
+if __name__ == "__main__":
+    config: DBOSConfig = {
+        "name": "my-app",
+        "system_database_url": os.environ.get("DBOS_SYSTEM_DATABASE_URL"),
+    }
+    DBOS(config=config)
+    DBOS.launch()
+```
+
+### Workflow and Step Structure
+
+Workflows are comprised of steps. Any function performing complex operations or accessing external services must be a step:
+
+```python
+@DBOS.step()
+def call_external_api():
+    return requests.get("https://api.example.com").json()
+
+@DBOS.workflow()
+def my_workflow():
+    result = call_external_api()
+    return result
+```
+
+### Key Constraints
+
+- Do NOT call `DBOS.start_workflow` or `DBOS.recv` from a step
+- Do NOT use threads to start workflows - use `DBOS.start_workflow` or queues
+- Workflows MUST be deterministic - non-deterministic operations go in steps
+- Do NOT create/update global variables from workflows or steps
+
+## How to Use
+
+Read individual rule files for detailed explanations and examples:
+
+```
+references/lifecycle-config.md
+references/workflow-determinism.md
+references/queue-concurrency.md
+```
+
+## References
+
+- https://docs.dbos.dev/
+- https://github.com/dbos-inc/dbos-transact-py

package/templates/.agent/skills/dbos-python/references/_sections.md

@@ -0,0 +1,41 @@
+# Section Definitions
+
+This file defines the rule categories for DBOS Python best practices. Rules are automatically assigned to sections based on their filename prefix.
+
+---
+
+## 1. Lifecycle (lifecycle)
+**Impact:** CRITICAL
+**Description:** DBOS configuration, initialization, and launch patterns. Foundation for all DBOS applications.
+
+## 2. Workflow (workflow)
+**Impact:** CRITICAL
+**Description:** Workflow creation, determinism requirements, background execution, and workflow IDs.
+
+## 3. Step (step)
+**Impact:** HIGH
+**Description:** Step creation, retries, transactions, and when to use steps vs workflows.
+
+## 4. Queue (queue)
+**Impact:** HIGH
+**Description:** Queue creation, concurrency limits, rate limiting, partitioning, and priority.
+
+## 5. Communication (comm)
+**Impact:** MEDIUM
+**Description:** Workflow events, messages, and streaming for inter-workflow communication.
+
+## 6. Pattern (pattern)
+**Impact:** MEDIUM
+**Description:** Common patterns including idempotency, scheduled workflows, debouncing, and classes.
+
+## 7. Testing (test)
+**Impact:** LOW-MEDIUM
+**Description:** Testing DBOS applications with pytest, fixtures, and best practices.
+
+## 8. Client (client)
+**Impact:** MEDIUM
+**Description:** DBOSClient for interacting with DBOS from external applications.
+
+## 9. Advanced (advanced)
+**Impact:** LOW
+**Description:** Async workflows, workflow versioning, patching, and code upgrades.

package/templates/.agent/skills/dbos-python/references/advanced-async.md

@@ -0,0 +1,101 @@
+---
+title: Use Async Workflows Correctly
+impact: LOW
+impactDescription: Enables non-blocking I/O in workflows
+tags: async, coroutine, await, asyncio
+---
+
+## Use Async Workflows Correctly
+
+Coroutine (async) functions can be DBOS workflows. Use async-specific methods and patterns.
+
+**Incorrect (mixing sync and async):**
+
+```python
+@DBOS.workflow()
+async def async_workflow():
+    # Don't use sync sleep in async workflow!
+    DBOS.sleep(10)
+
+    # Don't use sync start_workflow for async workflows
+    handle = DBOS.start_workflow(other_async_workflow)
+```
+
+**Correct (async patterns):**
+
+```python
+import asyncio
+import aiohttp
+
+@DBOS.step()
+async def fetch_async():
+    async with aiohttp.ClientSession() as session:
+        async with session.get("https://example.com") as response:
+            return await response.text()
+
+@DBOS.workflow()
+async def async_workflow():
+    # Use async sleep
+    await DBOS.sleep_async(10)
+
+    # Await async steps
+    result = await fetch_async()
+
+    # Use async start_workflow
+    handle = await DBOS.start_workflow_async(other_async_workflow)
+
+    return result
+```
+
+### Running Async Steps In Parallel
+
+You can run async steps in parallel if they are started in **deterministic order**:
+
+**Correct (deterministic start order):**
+
+```python
+@DBOS.workflow()
+async def parallel_workflow():
+    # Start steps in deterministic order, then await together
+    tasks = [
+        asyncio.create_task(step1("arg1")),
+        asyncio.create_task(step2("arg2")),
+        asyncio.create_task(step3("arg3")),
+    ]
+    # Use return_exceptions=True for proper error handling
+    results = await asyncio.gather(*tasks, return_exceptions=True)
+    return results
+```
+
+**Incorrect (non-deterministic order):**
+
+```python
+@DBOS.workflow()
+async def bad_parallel_workflow():
+    async def seq_a():
+        await step1("arg1")
+        await step2("arg2")  # Order depends on step1 timing
+
+    async def seq_b():
+        await step3("arg3")
+        await step4("arg4")  # Order depends on step3 timing
+
+    # step2 and step4 may run in either order - non-deterministic!
+    await asyncio.gather(seq_a(), seq_b())
+```
+
+If you need concurrent sequences, use child workflows instead of interleaving steps.
+
+For transactions in async workflows, use `asyncio.to_thread`:
+
+```python
+@DBOS.transaction()
+def sync_transaction(data):
+    DBOS.sql_session.execute(...)
+
+@DBOS.workflow()
+async def async_workflow():
+    result = await asyncio.to_thread(sync_transaction, data)
+```
+
+Reference: [Async Workflows](https://docs.dbos.dev/python/tutorials/workflow-tutorial#coroutine-async-workflows)

package/templates/.agent/skills/dbos-python/references/advanced-patching.md

@@ -0,0 +1,68 @@
+---
+title: Use Patching for Safe Workflow Upgrades
+impact: LOW
+impactDescription: Deploy breaking changes without disrupting in-progress workflows
+tags: patching, upgrade, versioning, migration
+---
+
+## Use Patching for Safe Workflow Upgrades
+
+Use `DBOS.patch()` to safely deploy breaking workflow changes. Breaking changes alter what steps run or their order.
+
+**Incorrect (breaking change without patch):**
+
+```python
+# Original
+@DBOS.workflow()
+def workflow():
+    foo()
+    bar()
+
+# Updated - breaks in-progress workflows!
+@DBOS.workflow()
+def workflow():
+    baz()  # Replaced foo() - checkpoints don't match
+    bar()
+```
+
+**Correct (using patch):**
+
+```python
+# Enable patching in config
+config: DBOSConfig = {
+    "name": "my-app",
+    "enable_patching": True,
+}
+DBOS(config=config)
+
+@DBOS.workflow()
+def workflow():
+    if DBOS.patch("use-baz"):
+        baz()  # New workflows use baz
+    else:
+        foo()  # Old workflows continue with foo
+    bar()
+```
+
+Deprecating patches after all old workflows complete:
+
+```python
+# Step 1: Deprecate (runs all workflows, stops inserting marker)
+@DBOS.workflow()
+def workflow():
+    DBOS.deprecate_patch("use-baz")
+    baz()
+    bar()
+
+# Step 2: Remove entirely (after all deprecated workflows complete)
+@DBOS.workflow()
+def workflow():
+    baz()
+    bar()
+```
+
+`DBOS.patch(name)` returns:
+- `True` for new workflows (started after patch deployed)
+- `False` for old workflows (started before patch deployed)
+
+Reference: [Patching](https://docs.dbos.dev/python/tutorials/upgrading-workflows#patching)

package/templates/.agent/skills/dbos-python/references/advanced-versioning.md

@@ -0,0 +1,66 @@
+---
+title: Use Versioning for Blue-Green Deployments
+impact: LOW
+impactDescription: Safely deploy new code with version tagging
+tags: versioning, blue-green, deployment, recovery
+---
+
+## Use Versioning for Blue-Green Deployments
+
+DBOS versions workflows to prevent unsafe recovery. Use blue-green deployments to safely upgrade.
+
+**Incorrect (deploying breaking changes without versioning):**
+
+```python
+# Deploying new code directly kills in-progress workflows
+# because their checkpoints don't match the new code
+
+# Old code
+@DBOS.workflow()
+def workflow():
+    step_a()
+    step_b()
+
+# New code replaces old immediately - breaks recovery!
+@DBOS.workflow()
+def workflow():
+    step_a()
+    step_c()  # Changed step - old workflows can't recover
+```
+
+**Correct (using versioning with blue-green deployment):**
+
+```python
+# Set explicit version in config
+config: DBOSConfig = {
+    "name": "my-app",
+    "application_version": "2.0.0",  # New version
+}
+DBOS(config=config)
+
+# Deploy new version alongside old version
+# New traffic goes to v2.0.0, old workflows drain on v1.0.0
+
+# Check for remaining old workflows before retiring v1.0.0
+old_workflows = DBOS.list_workflows(
+    app_version="1.0.0",
+    status=["PENDING", "ENQUEUED"]
+)
+
+if len(old_workflows) == 0:
+    # Safe to retire old version
+    pass
+```
+
+Fork a workflow to run on a new version:
+
+```python
+# Fork workflow from step 5 on version 2.0.0
+new_handle = DBOS.fork_workflow(
+    workflow_id="old-workflow-id",
+    start_step=5,
+    application_version="2.0.0"
+)
+```
+
+Reference: [Versioning](https://docs.dbos.dev/python/tutorials/upgrading-workflows#versioning)

package/templates/.agent/skills/dbos-python/references/client-enqueue.md

@@ -0,0 +1,54 @@
+---
+title: Enqueue Workflows from External Applications
+impact: HIGH
+impactDescription: Enables decoupled architecture with separate API and worker services
+tags: client, enqueue, workflow, external
+---
+
+## Enqueue Workflows from External Applications
+
+Use `client.enqueue()` to submit workflows from outside the DBOS application. Must specify workflow and queue names explicitly.
+
+**Incorrect (missing required options):**
+
+```python
+from dbos import DBOSClient
+
+client = DBOSClient(system_database_url=db_url)
+
+# Missing workflow_name and queue_name!
+handle = client.enqueue({}, task_data)
+```
+
+**Correct (with required options):**
+
+```python
+from dbos import DBOSClient, EnqueueOptions
+
+client = DBOSClient(system_database_url=db_url)
+
+options: EnqueueOptions = {
+    "workflow_name": "process_task",  # Required
+    "queue_name": "task_queue",       # Required
+}
+handle = client.enqueue(options, task_data)
+result = handle.get_result()
+client.destroy()
+```
+
+With optional parameters:
+
+```python
+options: EnqueueOptions = {
+    "workflow_name": "process_task",
+    "queue_name": "task_queue",
+    "workflow_id": "custom-id-123",
+    "workflow_timeout": 300,
+    "deduplication_id": "user-123",
+    "priority": 1,
+}
+```
+
+Limitation: Cannot enqueue workflows that are methods on Python classes.
+
+Reference: [DBOSClient.enqueue](https://docs.dbos.dev/python/reference/client#enqueue)

package/templates/.agent/skills/dbos-python/references/client-setup.md

@@ -0,0 +1,57 @@
+---
+title: Initialize DBOSClient for External Access
+impact: HIGH
+impactDescription: Enables external applications to interact with DBOS
+tags: client, setup, initialization, external
+---
+
+## Initialize DBOSClient for External Access
+
+Use `DBOSClient` to interact with DBOS from external applications (API servers, CLI tools, etc.).
+
+**Incorrect (no cleanup):**
+
+```python
+from dbos import DBOSClient
+
+client = DBOSClient(system_database_url=db_url)
+handle = client.enqueue(options, data)
+# Connection leaked - no destroy()!
+```
+
+**Correct (with cleanup):**
+
+```python
+import os
+from dbos import DBOSClient
+
+client = DBOSClient(
+    system_database_url=os.environ["DBOS_SYSTEM_DATABASE_URL"]
+)
+
+try:
+    handle = client.enqueue(options, data)
+    result = handle.get_result()
+finally:
+    client.destroy()
+```
+
+Constructor parameters:
+- `system_database_url`: Connection string to DBOS system database
+- `serializer`: Must match the DBOS application's serializer (default: pickle)
+
+## API Reference
+
+Beyond `enqueue`, DBOSClient mirrors the DBOS API. Use the same patterns from other reference files:
+
+| DBOSClient method | Same as DBOS method |
+|-------------------|---------------------|
+| `client.send()` | `DBOS.send()` - add `idempotency_key` for exactly-once |
+| `client.get_event()` | `DBOS.get_event()` |
+| `client.read_stream()` | `DBOS.read_stream()` |
+| `client.list_workflows()` | `DBOS.list_workflows()` |
+| `client.cancel_workflow()` | `DBOS.cancel_workflow()` |
+| `client.resume_workflow()` | `DBOS.resume_workflow()` |
+| `client.retrieve_workflow()` | `DBOS.retrieve_workflow()` |
+
+Reference: [DBOSClient](https://docs.dbos.dev/python/reference/client)

package/templates/.agent/skills/dbos-python/references/comm-events.md

@@ -0,0 +1,61 @@
+---
+title: Use Events for Workflow Status Publishing
+impact: MEDIUM
+impactDescription: Enables real-time workflow status monitoring
+tags: events, set_event, get_event, status
+---
+
+## Use Events for Workflow Status Publishing
+
+Workflows can publish key-value events that clients can read. Events are persisted and useful for status updates.
+
+**Incorrect (no way to monitor progress):**
+
+```python
+@DBOS.workflow()
+def long_workflow():
+    step_one()
+    step_two()  # Client can't see progress
+    step_three()
+    return "done"
+```
+
+**Correct (publishing events):**
+
+```python
+@DBOS.workflow()
+def long_workflow():
+    DBOS.set_event("status", "starting")
+
+    step_one()
+    DBOS.set_event("status", "step_one_complete")
+
+    step_two()
+    DBOS.set_event("status", "step_two_complete")
+
+    step_three()
+    DBOS.set_event("status", "finished")
+    return "done"
+
+# Client code to read events
+@app.post("/start")
+def start_workflow():
+    handle = DBOS.start_workflow(long_workflow)
+    return {"workflow_id": handle.get_workflow_id()}
+
+@app.get("/status/{workflow_id}")
+def get_status(workflow_id: str):
+    status = DBOS.get_event(workflow_id, "status", timeout_seconds=0) or "not started"
+    return {"status": status}
+```
+
+Get all events from a workflow:
+
+```python
+all_events = DBOS.get_all_events(workflow_id)
+# Returns: {"status": "finished", "other_key": "value"}
+```
+
+Events can be called from `set_event` from workflows or steps.
+
+Reference: [Workflow Events](https://docs.dbos.dev/python/tutorials/workflow-communication#workflow-events)