codehava-agent-kit 1.0.0 → 2.0.0

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

@@ -0,0 +1,56 @@
+---
+title: Use Messages for Workflow Notifications
+impact: MEDIUM
+impactDescription: Enables external signals to control workflow execution
+tags: messages, send, recv, notifications
+---
+
+## Use Messages for Workflow Notifications
+
+Send messages to workflows to signal or notify them while running. Messages are persisted and queued per topic.
+
+**Incorrect (polling external state):**
+
+```python
+@DBOS.workflow()
+def payment_workflow():
+    # Polling is inefficient and not durable
+    while True:
+        status = check_payment_status()
+        if status == "paid":
+            break
+        time.sleep(1)
+```
+
+**Correct (using messages):**
+
+```python
+PAYMENT_STATUS = "payment_status"
+
+@DBOS.workflow()
+def payment_workflow():
+    # Process order...
+    DBOS.set_event("payment_id", payment_id)
+
+    # Wait for payment notification (60 second timeout)
+    payment_status = DBOS.recv(PAYMENT_STATUS, timeout_seconds=60)
+
+    if payment_status == "paid":
+        fulfill_order()
+    else:
+        cancel_order()
+
+# Webhook endpoint to receive payment notification
+@app.post("/payment_webhook/{workflow_id}/{status}")
+def payment_webhook(workflow_id: str, status: str):
+    DBOS.send(workflow_id, status, PAYMENT_STATUS)
+    return {"ok": True}
+```
+
+Key points:
+- `DBOS.recv()` can only be called from workflows
+- Messages are queued per topic
+- `recv()` returns `None` on timeout
+- Messages are persisted for exactly-once delivery
+
+Reference: [Workflow Messaging](https://docs.dbos.dev/python/tutorials/workflow-communication#workflow-messaging-and-notifications)

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

@@ -0,0 +1,57 @@
+---
+title: Use Streams for Real-Time Data
+impact: MEDIUM
+impactDescription: Enables real-time progress and LLM streaming
+tags: streaming, write_stream, read_stream, realtime
+---
+
+## Use Streams for Real-Time Data
+
+Workflows can stream data in real-time to clients. Useful for LLM responses, progress reporting, or long-running results.
+
+**Incorrect (returning all data at end):**
+
+```python
+@DBOS.workflow()
+def llm_workflow(prompt):
+    # Client waits for entire response
+    response = call_llm(prompt)
+    return response
+```
+
+**Correct (streaming results):**
+
+```python
+@DBOS.workflow()
+def llm_workflow(prompt):
+    for chunk in call_llm_streaming(prompt):
+        DBOS.write_stream("response", chunk)
+    DBOS.close_stream("response")
+    return "complete"
+
+# Client reads stream
+@app.get("/stream/{workflow_id}")
+def stream_response(workflow_id: str):
+    def generate():
+        for value in DBOS.read_stream(workflow_id, "response"):
+            yield value
+    return StreamingResponse(generate())
+```
+
+Stream characteristics:
+- Streams are immutable and append-only
+- Writes from workflows happen exactly-once
+- Writes from steps happen at-least-once (may duplicate on retry)
+- Streams auto-close when workflow terminates
+
+Close streams explicitly when done:
+
+```python
+@DBOS.workflow()
+def producer():
+    DBOS.write_stream("data", {"step": 1})
+    DBOS.write_stream("data", {"step": 2})
+    DBOS.close_stream("data")  # Signal completion
+```
+
+Reference: [Workflow Streaming](https://docs.dbos.dev/python/tutorials/workflow-communication#workflow-streaming)

package/templates/.agent/skills/dbos-python/references/lifecycle-config.md

@@ -0,0 +1,74 @@
+---
+title: Configure and Launch DBOS Properly
+impact: CRITICAL
+impactDescription: Application won't function without proper setup
+tags: configuration, launch, setup, initialization
+---
+
+## Configure and Launch DBOS Properly
+
+Every DBOS application must configure and launch DBOS inside the main function.
+
+**Incorrect (configuration at module level):**
+
+```python
+from dbos import DBOS, DBOSConfig
+
+# Don't configure at module level!
+config: DBOSConfig = {
+    "name": "my-app",
+}
+DBOS(config=config)
+
+@DBOS.workflow()
+def my_workflow():
+    pass
+
+if __name__ == "__main__":
+    DBOS.launch()
+    my_workflow()
+```
+
+**Correct (configuration in main):**
+
+```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()
+    my_workflow()
+```
+
+For scheduled-only applications (no HTTP server), block the main thread:
+
+```python
+import os
+import threading
+from dbos import DBOS, DBOSConfig
+
+@DBOS.scheduled("* * * * *")
+@DBOS.workflow()
+def scheduled_task(scheduled_time, actual_time):
+    pass
+
+if __name__ == "__main__":
+    config: DBOSConfig = {
+        "name": "my-app",
+        "system_database_url": os.environ.get("DBOS_SYSTEM_DATABASE_URL"),
+    }
+    DBOS(config=config)
+    DBOS.launch()
+    threading.Event().wait()  # Block forever
+```
+
+Reference: [DBOS Configuration](https://docs.dbos.dev/python/reference/configuration)

package/templates/.agent/skills/dbos-python/references/lifecycle-fastapi.md

@@ -0,0 +1,66 @@
+---
+title: Integrate DBOS with FastAPI
+impact: CRITICAL
+impactDescription: Proper integration ensures workflows survive server restarts
+tags: fastapi, http, server, integration
+---
+
+## Integrate DBOS with FastAPI
+
+When using DBOS with FastAPI, configure and launch DBOS inside the main function before starting uvicorn.
+
+**Incorrect (configuration at module level):**
+
+```python
+from fastapi import FastAPI
+from dbos import DBOS, DBOSConfig
+
+app = FastAPI()
+
+# Don't configure at module level!
+config: DBOSConfig = {"name": "my-app"}
+DBOS(config=config)
+
+@app.get("/")
+@DBOS.workflow()
+def endpoint():
+    return {"status": "ok"}
+
+if __name__ == "__main__":
+    DBOS.launch()
+    uvicorn.run(app)
+```
+
+**Correct (configuration in main):**
+
+```python
+import os
+from fastapi import FastAPI
+from dbos import DBOS, DBOSConfig
+import uvicorn
+
+app = FastAPI()
+
+@DBOS.step()
+def process_data():
+    return "processed"
+
+@app.get("/")
+@DBOS.workflow()
+def endpoint():
+    result = process_data()
+    return {"result": result}
+
+if __name__ == "__main__":
+    config: DBOSConfig = {
+        "name": "my-app",
+        "system_database_url": os.environ.get("DBOS_SYSTEM_DATABASE_URL"),
+    }
+    DBOS(config=config)
+    DBOS.launch()
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+The workflow decorator can be combined with FastAPI route decorators. The FastAPI decorator should come first (outermost).
+
+Reference: [DBOS with FastAPI](https://docs.dbos.dev/python/tutorials/workflow-tutorial)

package/templates/.agent/skills/dbos-python/references/pattern-classes.md

@@ -0,0 +1,61 @@
+---
+title: Use DBOS Decorators with Classes
+impact: MEDIUM
+impactDescription: Enables stateful workflow patterns with class instances
+tags: classes, dbos_class, instance, oop
+---
+
+## Use DBOS Decorators with Classes
+
+DBOS decorators work with class methods. Workflow classes must inherit from `DBOSConfiguredInstance`.
+
+**Incorrect (missing class setup):**
+
+```python
+class MyService:
+    def __init__(self, url):
+        self.url = url
+
+    @DBOS.workflow()  # Won't work without proper setup
+    def fetch_data(self):
+        return self.fetch()
+```
+
+**Correct (proper class setup):**
+
+```python
+from dbos import DBOS, DBOSConfiguredInstance
+
+@DBOS.dbos_class()
+class URLFetcher(DBOSConfiguredInstance):
+    def __init__(self, url: str):
+        self.url = url
+        # instance_name must be unique and passed to super()
+        super().__init__(instance_name=url)
+
+    @DBOS.workflow()
+    def fetch_workflow(self):
+        return self.fetch_url()
+
+    @DBOS.step()
+    def fetch_url(self):
+        return requests.get(self.url).text
+
+# Instantiate BEFORE DBOS.launch()
+example_fetcher = URLFetcher("https://example.com")
+api_fetcher = URLFetcher("https://api.example.com")
+
+if __name__ == "__main__":
+    DBOS.launch()
+    print(example_fetcher.fetch_workflow())
+```
+
+Requirements:
+- Class must be decorated with `@DBOS.dbos_class()`
+- Class must inherit from `DBOSConfiguredInstance`
+- `instance_name` must be unique and passed to `super().__init__()`
+- All instances must be created before `DBOS.launch()`
+
+Steps can be added to any class without these requirements.
+
+Reference: [Python Classes](https://docs.dbos.dev/python/tutorials/classes)

package/templates/.agent/skills/dbos-python/references/pattern-debouncing.md

@@ -0,0 +1,59 @@
+---
+title: Debounce Workflows to Prevent Wasted Work
+impact: MEDIUM
+impactDescription: Reduces redundant executions during rapid input
+tags: debounce, throttle, input, optimization
+---
+
+## Debounce Workflows to Prevent Wasted Work
+
+Debouncing delays workflow execution until some time has passed since the last trigger. Useful for user input processing.
+
+**Incorrect (processing every input):**
+
+```python
+@DBOS.workflow()
+def process_input(user_input):
+    # Expensive processing
+    analyze(user_input)
+
+@app.post("/input")
+def on_input(user_id: str, input: str):
+    # Every keystroke triggers processing!
+    DBOS.start_workflow(process_input, input)
+```
+
+**Correct (debounced processing):**
+
+```python
+from dbos import Debouncer
+
+@DBOS.workflow()
+def process_input(user_input):
+    analyze(user_input)
+
+# Create a debouncer for the workflow
+debouncer = Debouncer.create(process_input)
+
+@app.post("/input")
+def on_input(user_id: str, input: str):
+    # Wait 5 seconds after last input before processing
+    debounce_key = user_id  # Debounce per user
+    debounce_period = 5.0   # Seconds
+    handle = debouncer.debounce(debounce_key, debounce_period, input)
+    return {"workflow_id": handle.get_workflow_id()}
+```
+
+Debouncer with timeout (max wait time):
+
+```python
+# Process after 5s idle OR 60s max wait
+debouncer = Debouncer.create(process_input, debounce_timeout_sec=60)
+
+def on_input(user_id: str, input: str):
+    debouncer.debounce(user_id, 5.0, input)
+```
+
+When workflow executes, it uses the **last** inputs passed to `debounce`.
+
+Reference: [Debouncing Workflows](https://docs.dbos.dev/python/tutorials/workflow-tutorial#debouncing-workflows)

package/templates/.agent/skills/dbos-python/references/pattern-idempotency.md

@@ -0,0 +1,52 @@
+---
+title: Use Workflow IDs for Idempotency
+impact: MEDIUM
+impactDescription: Prevents duplicate executions of critical operations
+tags: idempotency, workflow-id, deduplication, exactly-once
+---
+
+## Use Workflow IDs for Idempotency
+
+Set workflow IDs to make operations idempotent. A workflow with the same ID executes only once.
+
+**Incorrect (duplicate payments possible):**
+
+```python
+@app.post("/pay/{order_id}")
+def process_payment(order_id: str):
+    # Multiple clicks = multiple payments!
+    handle = DBOS.start_workflow(payment_workflow, order_id)
+    return handle.get_result()
+```
+
+**Correct (idempotent with workflow ID):**
+
+```python
+from dbos import SetWorkflowID
+
+@app.post("/pay/{order_id}")
+def process_payment(order_id: str):
+    # Same order_id = same workflow ID = only one execution
+    with SetWorkflowID(f"payment-{order_id}"):
+        handle = DBOS.start_workflow(payment_workflow, order_id)
+    return handle.get_result()
+
+@DBOS.workflow()
+def payment_workflow(order_id: str):
+    charge_customer(order_id)
+    send_confirmation(order_id)
+    return "success"
+```
+
+Access the workflow ID inside workflows:
+
+```python
+@DBOS.workflow()
+def my_workflow():
+    current_id = DBOS.workflow_id
+    DBOS.logger.info(f"Running workflow {current_id}")
+```
+
+Workflow IDs must be globally unique. Duplicate IDs return the existing workflow's result without re-executing.
+
+Reference: [Workflow IDs and Idempotency](https://docs.dbos.dev/python/tutorials/workflow-tutorial#workflow-ids-and-idempotency)

package/templates/.agent/skills/dbos-python/references/pattern-scheduled.md

@@ -0,0 +1,56 @@
+---
+title: Create Scheduled Workflows
+impact: MEDIUM
+impactDescription: Run workflows exactly once per time interval
+tags: scheduled, cron, recurring, timer
+---
+
+## Create Scheduled Workflows
+
+Use `@DBOS.scheduled` to run workflows on a schedule. Workflows run exactly once per interval.
+
+**Incorrect (manual scheduling):**
+
+```python
+# Don't use external cron or manual timers
+import schedule
+schedule.every(1).minute.do(my_task)
+```
+
+**Correct (DBOS scheduled workflow):**
+
+```python
+@DBOS.scheduled("* * * * *")  # Every minute
+@DBOS.workflow()
+def run_every_minute(scheduled_time, actual_time):
+    print(f"Running at {scheduled_time}")
+    do_maintenance_task()
+
+@DBOS.scheduled("0 */6 * * *")  # Every 6 hours
+@DBOS.workflow()
+def periodic_cleanup(scheduled_time, actual_time):
+    cleanup_old_records()
+```
+
+Scheduled workflow requirements:
+- Must have `@DBOS.scheduled` decorator with crontab syntax
+- Must accept two arguments: `scheduled_time` and `actual_time` (both `datetime`)
+- Main thread must stay alive for scheduled workflows
+
+For apps with only scheduled workflows (no HTTP server):
+
+```python
+import threading
+
+if __name__ == "__main__":
+    DBOS.launch()
+    threading.Event().wait()  # Block forever
+```
+
+Crontab format: `minute hour day month weekday`
+- `* * * * *` = every minute
+- `0 * * * *` = every hour
+- `0 0 * * *` = daily at midnight
+- `0 0 * * 0` = weekly on Sunday
+
+Reference: [Scheduled Workflows](https://docs.dbos.dev/python/tutorials/scheduled-workflows)

package/templates/.agent/skills/dbos-python/references/pattern-sleep.md

@@ -0,0 +1,58 @@
+---
+title: Use Durable Sleep for Delayed Execution
+impact: MEDIUM
+impactDescription: Survives restarts and can span days or weeks
+tags: sleep, delay, schedule, durable
+---
+
+## Use Durable Sleep for Delayed Execution
+
+Use `DBOS.sleep()` for durable delays that survive restarts. The wakeup time is persisted in the database.
+
+**Incorrect (regular sleep):**
+
+```python
+import time
+
+@DBOS.workflow()
+def delayed_task(delay_seconds, task):
+    # Regular sleep is lost on restart!
+    time.sleep(delay_seconds)
+    run_task(task)
+```
+
+**Correct (durable sleep):**
+
+```python
+@DBOS.workflow()
+def delayed_task(delay_seconds, task):
+    # Durable sleep - survives restarts
+    DBOS.sleep(delay_seconds)
+    run_task(task)
+```
+
+Use cases for durable sleep:
+- Schedule a task for the future
+- Wait between retries
+- Implement delays spanning hours, days, or weeks
+
+Example: Schedule a reminder:
+
+```python
+@DBOS.workflow()
+def send_reminder(user_id: str, message: str, delay_days: int):
+    # Sleep for days - survives any restart
+    DBOS.sleep(delay_days * 24 * 60 * 60)
+    send_notification(user_id, message)
+```
+
+For async workflows, use `DBOS.sleep_async()`:
+
+```python
+@DBOS.workflow()
+async def async_delayed_task():
+    await DBOS.sleep_async(60)
+    await run_async_task()
+```
+
+Reference: [Durable Sleep](https://docs.dbos.dev/python/tutorials/workflow-tutorial#durable-sleep)

package/templates/.agent/skills/dbos-python/references/queue-basics.md

@@ -0,0 +1,60 @@
+---
+title: Use Queues for Concurrent Workflows
+impact: HIGH
+impactDescription: Queues provide managed concurrency and flow control
+tags: queue, concurrency, enqueue, workflow
+---
+
+## Use Queues for Concurrent Workflows
+
+Queues run many workflows concurrently with managed flow control. Use them when you need to control how many workflows run at once.
+
+**Incorrect (uncontrolled concurrency):**
+
+```python
+@DBOS.workflow()
+def process_task(task):
+    pass
+
+# Starting many workflows without control
+for task in tasks:
+    DBOS.start_workflow(process_task, task)  # Could overwhelm resources
+```
+
+**Correct (using queue):**
+
+```python
+from dbos import Queue
+
+queue = Queue("task_queue")
+
+@DBOS.workflow()
+def process_task(task):
+    pass
+
+@DBOS.workflow()
+def process_all_tasks(tasks):
+    handles = []
+    for task in tasks:
+        # Queue manages concurrency
+        handle = queue.enqueue(process_task, task)
+        handles.append(handle)
+    # Wait for all tasks
+    return [h.get_result() for h in handles]
+```
+
+Queues process workflows in FIFO order. You can enqueue both workflows and steps.
+
+```python
+queue = Queue("example_queue")
+
+@DBOS.step()
+def my_step(data):
+    return process(data)
+
+# Enqueue a step
+handle = queue.enqueue(my_step, data)
+result = handle.get_result()
+```
+
+Reference: [DBOS Queues](https://docs.dbos.dev/python/tutorials/queue-tutorial)

package/templates/.agent/skills/dbos-python/references/queue-concurrency.md

@@ -0,0 +1,57 @@
+---
+title: Control Queue Concurrency
+impact: HIGH
+impactDescription: Prevents resource exhaustion with concurrent limits
+tags: queue, concurrency, worker_concurrency, limits
+---
+
+## Control Queue Concurrency
+
+Queues support worker-level and global concurrency limits to prevent resource exhaustion.
+
+**Incorrect (no concurrency control):**
+
+```python
+queue = Queue("heavy_tasks")  # No limits - could exhaust memory
+
+@DBOS.workflow()
+def memory_intensive_task(data):
+    # Uses lots of memory
+    pass
+```
+
+**Correct (worker concurrency):**
+
+```python
+# Each process runs at most 5 tasks from this queue
+queue = Queue("heavy_tasks", worker_concurrency=5)
+
+@DBOS.workflow()
+def memory_intensive_task(data):
+    pass
+```
+
+**Correct (global concurrency):**
+
+```python
+# At most 10 tasks run across ALL processes
+queue = Queue("limited_tasks", concurrency=10)
+```
+
+**In-order processing (sequential):**
+
+```python
+# Only one task at a time - guarantees order
+queue = Queue("sequential_queue", concurrency=1)
+
+@DBOS.step()
+def process_event(event):
+    pass
+
+def handle_event(event):
+    queue.enqueue(process_event, event)
+```
+
+Worker concurrency is recommended for most use cases. Global concurrency should be used carefully as pending workflows count toward the limit.
+
+Reference: [Managing Concurrency](https://docs.dbos.dev/python/tutorials/queue-tutorial#managing-concurrency)