codehava-agent-kit 1.0.1 → 2.0.0

package/templates/.agent/skills/dbos-golang/references/queue-rate-limiting.md

@@ -0,0 +1,50 @@
+---
+title: Rate Limit Queue Execution
+impact: HIGH
+impactDescription: Prevents overwhelming external APIs with too many requests
+tags: queue, rate-limit, throttle, api
+---
+
+## Rate Limit Queue Execution
+
+Set rate limits on a queue to control how many workflows start in a given period. Rate limits are global across all DBOS processes.
+
+**Incorrect (no rate limiting):**
+
+```go
+queue := dbos.NewWorkflowQueue(ctx, "llm_tasks")
+// Could send hundreds of requests per second to a rate-limited API
+```
+
+**Correct (rate-limited queue):**
+
+```go
+queue := dbos.NewWorkflowQueue(ctx, "llm_tasks",
+	dbos.WithRateLimiter(&dbos.RateLimiter{
+		Limit:  50,
+		Period: 30 * time.Second,
+	}),
+)
+```
+
+This queue starts at most 50 workflows per 30 seconds.
+
+**Combining rate limiting with concurrency:**
+
+```go
+// At most 5 concurrent and 50 per 30 seconds
+queue := dbos.NewWorkflowQueue(ctx, "api_tasks",
+	dbos.WithWorkerConcurrency(5),
+	dbos.WithRateLimiter(&dbos.RateLimiter{
+		Limit:  50,
+		Period: 30 * time.Second,
+	}),
+)
+```
+
+Common use cases:
+- LLM API rate limiting (OpenAI, Anthropic, etc.)
+- Third-party API throttling
+- Preventing database overload
+
+Reference: [Rate Limiting](https://docs.dbos.dev/golang/tutorials/queue-tutorial#rate-limiting)

package/templates/.agent/skills/dbos-golang/references/step-basics.md

@@ -0,0 +1,81 @@
+---
+title: Use Steps for External Operations
+impact: HIGH
+impactDescription: Steps enable recovery by checkpointing results
+tags: step, external, api, checkpoint
+---
+
+## Use Steps for External Operations
+
+Any function that performs complex operations, accesses external APIs, or has side effects should be a step. Step results are checkpointed, enabling workflow recovery.
+
+**Incorrect (external call in workflow):**
+
+```go
+func myWorkflow(ctx dbos.DBOSContext, input string) (string, error) {
+	// External API call directly in workflow - not checkpointed!
+	resp, err := http.Get("https://api.example.com/data")
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+	body, _ := io.ReadAll(resp.Body)
+	return string(body), nil
+}
+```
+
+**Correct (external call in step using `dbos.RunAsStep`):**
+
+```go
+func fetchData(ctx context.Context) (string, error) {
+	resp, err := http.Get("https://api.example.com/data")
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+	body, _ := io.ReadAll(resp.Body)
+	return string(body), nil
+}
+
+func myWorkflow(ctx dbos.DBOSContext, input string) (string, error) {
+	data, err := dbos.RunAsStep(ctx, fetchData, dbos.WithStepName("fetchData"))
+	if err != nil {
+		return "", err
+	}
+	return data, nil
+}
+```
+
+`dbos.RunAsStep` can also accept an inline closure:
+
+```go
+func myWorkflow(ctx dbos.DBOSContext, input string) (string, error) {
+	data, err := dbos.RunAsStep(ctx, func(ctx context.Context) (string, error) {
+		resp, err := http.Get("https://api.example.com/data")
+		if err != nil {
+			return "", err
+		}
+		defer resp.Body.Close()
+		body, _ := io.ReadAll(resp.Body)
+		return string(body), nil
+	}, dbos.WithStepName("fetchData"))
+	return data, err
+}
+```
+
+Step type signature: `type Step[R any] func(ctx context.Context) (R, error)`
+
+Step requirements:
+- The function must accept a `context.Context` parameter — use the one provided, not the workflow's context
+- Inputs and outputs must be serializable to JSON
+- Cannot start or enqueue workflows from within steps
+- Calling a step from within another step makes the inner call part of the outer step's execution
+
+When to use steps:
+- API calls to external services
+- File system operations
+- Random number generation
+- Getting current time
+- Any non-deterministic operation
+
+Reference: [DBOS Steps](https://docs.dbos.dev/golang/tutorials/step-tutorial)

package/templates/.agent/skills/dbos-golang/references/step-concurrency.md

@@ -0,0 +1,79 @@
+---
+title: Run Concurrent Steps with Go and Select
+impact: HIGH
+impactDescription: Enables parallel execution of steps with durable checkpointing
+tags: step, concurrency, goroutine, select, parallel
+---
+
+## Run Concurrent Steps with Go and Select
+
+Use `dbos.Go` to run steps concurrently in goroutines and `dbos.Select` to durably select the first completed result. Both operations are checkpointed for recovery.
+
+**Incorrect (raw goroutines without checkpointing):**
+
+```go
+func myWorkflow(ctx dbos.DBOSContext, input string) (string, error) {
+	// Raw goroutines are not checkpointed - recovery breaks!
+	ch := make(chan string, 2)
+	go func() { ch <- callAPI1() }()
+	go func() { ch <- callAPI2() }()
+	return <-ch, nil
+}
+```
+
+**Correct (using dbos.Go for concurrent steps):**
+
+```go
+func myWorkflow(ctx dbos.DBOSContext, input string) (string, error) {
+	// Start steps concurrently
+	ch1, err := dbos.Go(ctx, func(ctx context.Context) (string, error) {
+		return callAPI1(ctx)
+	}, dbos.WithStepName("api1"))
+	if err != nil {
+		return "", err
+	}
+
+	ch2, err := dbos.Go(ctx, func(ctx context.Context) (string, error) {
+		return callAPI2(ctx)
+	}, dbos.WithStepName("api2"))
+	if err != nil {
+		return "", err
+	}
+
+	// Wait for the first result (durable select)
+	result, err := dbos.Select(ctx, []<-chan dbos.StepOutcome[string]{ch1, ch2})
+	if err != nil {
+		return "", err
+	}
+	return result, nil
+}
+```
+
+**Waiting for all concurrent steps:**
+
+```go
+func myWorkflow(ctx dbos.DBOSContext, input string) ([]string, error) {
+	ch1, _ := dbos.Go(ctx, step1, dbos.WithStepName("step1"))
+	ch2, _ := dbos.Go(ctx, step2, dbos.WithStepName("step2"))
+	ch3, _ := dbos.Go(ctx, step3, dbos.WithStepName("step3"))
+
+	// Collect all results
+	results := make([]string, 3)
+	for i, ch := range []<-chan dbos.StepOutcome[string]{ch1, ch2, ch3} {
+		outcome := <-ch
+		if outcome.Err != nil {
+			return nil, outcome.Err
+		}
+		results[i] = outcome.Result
+	}
+	return results, nil
+}
+```
+
+Key behaviors:
+- `dbos.Go` starts a step in a goroutine and returns a channel of `StepOutcome[R]`
+- `dbos.Select` durably selects the first completed result and checkpoints which channel was selected
+- On recovery, `Select` replays the same selection, maintaining determinism
+- Steps started with `Go` follow the same retry and checkpointing rules as `RunAsStep`
+
+Reference: [Concurrent Steps](https://docs.dbos.dev/golang/tutorials/workflow-tutorial#concurrent-steps)

package/templates/.agent/skills/dbos-golang/references/step-retries.md

@@ -0,0 +1,66 @@
+---
+title: Configure Step Retries for Transient Failures
+impact: HIGH
+impactDescription: Automatic retries handle transient failures without manual code
+tags: step, retry, exponential-backoff, resilience
+---
+
+## Configure Step Retries for Transient Failures
+
+Steps can automatically retry on failure with exponential backoff. This handles transient failures like network issues.
+
+**Incorrect (manual retry logic):**
+
+```go
+func fetchData(ctx context.Context) (string, error) {
+	var lastErr error
+	for attempt := 0; attempt < 3; attempt++ {
+		resp, err := http.Get("https://api.example.com")
+		if err == nil {
+			defer resp.Body.Close()
+			body, _ := io.ReadAll(resp.Body)
+			return string(body), nil
+		}
+		lastErr = err
+		time.Sleep(time.Duration(math.Pow(2, float64(attempt))) * time.Second)
+	}
+	return "", lastErr
+}
+```
+
+**Correct (built-in retries with `dbos.RunAsStep`):**
+
+```go
+func fetchData(ctx context.Context) (string, error) {
+	resp, err := http.Get("https://api.example.com")
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+	body, _ := io.ReadAll(resp.Body)
+	return string(body), nil
+}
+
+func myWorkflow(ctx dbos.DBOSContext, input string) (string, error) {
+	data, err := dbos.RunAsStep(ctx, fetchData,
+		dbos.WithStepName("fetchData"),
+		dbos.WithStepMaxRetries(10),
+		dbos.WithBaseInterval(500*time.Millisecond),
+		dbos.WithBackoffFactor(2.0),
+		dbos.WithMaxInterval(5*time.Second),
+	)
+	return data, err
+}
+```
+
+Retry parameters:
+- `WithStepMaxRetries(n)`: Maximum retry attempts (default: `0` — no retries)
+- `WithBaseInterval(d)`: Initial delay between retries (default: `100ms`)
+- `WithBackoffFactor(f)`: Multiplier for exponential backoff (default: `2.0`)
+- `WithMaxInterval(d)`: Maximum delay between retries (default: `5s`)
+
+With defaults, retry delays are: 100ms, 200ms, 400ms, 800ms, 1.6s, 3.2s, 5s, 5s...
+
+If all retries are exhausted, a `DBOSError` with code `MaxStepRetriesExceeded` is returned to the calling workflow.
+
+Reference: [Configurable Retries](https://docs.dbos.dev/golang/tutorials/step-tutorial#configurable-retries)

package/templates/.agent/skills/dbos-golang/references/test-setup.md

@@ -0,0 +1,90 @@
+---
+title: Use Proper Test Setup for DBOS
+impact: LOW-MEDIUM
+impactDescription: Ensures consistent test results with proper DBOS lifecycle management
+tags: testing, go-test, setup, integration, mock
+---
+
+## Use Proper Test Setup for DBOS
+
+DBOS applications can be tested with unit tests (mocking DBOSContext) or integration tests (real Postgres database).
+
+**Incorrect (no lifecycle management between tests):**
+
+```go
+// Tests share state - results are inconsistent!
+func TestOne(t *testing.T) {
+	myWorkflow(ctx, "input")
+}
+func TestTwo(t *testing.T) {
+	// Previous test's state leaks into this test
+	myWorkflow(ctx, "input")
+}
+```
+
+**Correct (unit testing with mocks):**
+
+The `DBOSContext` interface is fully mockable. Use a mocking library like `testify/mock` or `mockery`:
+
+```go
+func TestWorkflow(t *testing.T) {
+	mockCtx := mocks.NewMockDBOSContext(t)
+
+	// Mock RunAsStep to return a canned value
+	mockCtx.On("RunAsStep", mockCtx, mock.Anything, mock.Anything).
+		Return("mock-result", nil)
+
+	result, err := myWorkflow(mockCtx, "input")
+	assert.NoError(t, err)
+	assert.Equal(t, "expected", result)
+
+	mockCtx.AssertExpectations(t)
+}
+```
+
+**Correct (integration testing with Postgres):**
+
+```go
+func setupDBOS(t *testing.T) dbos.DBOSContext {
+	t.Helper()
+	databaseURL := os.Getenv("DBOS_TEST_DATABASE_URL")
+	if databaseURL == "" {
+		t.Skip("DBOS_TEST_DATABASE_URL not set")
+	}
+
+	ctx, err := dbos.NewDBOSContext(context.Background(), dbos.Config{
+		AppName:     "test-" + t.Name(),
+		DatabaseURL: databaseURL,
+	})
+	require.NoError(t, err)
+
+	dbos.RegisterWorkflow(ctx, myWorkflow)
+
+	err = dbos.Launch(ctx)
+	require.NoError(t, err)
+
+	t.Cleanup(func() {
+		dbos.Shutdown(ctx, 10*time.Second)
+	})
+	return ctx
+}
+
+func TestWorkflowIntegration(t *testing.T) {
+	ctx := setupDBOS(t)
+
+	handle, err := dbos.RunWorkflow(ctx, myWorkflow, "test-input")
+	require.NoError(t, err)
+
+	result, err := handle.GetResult()
+	require.NoError(t, err)
+	assert.Equal(t, "expected-output", result)
+}
+```
+
+Key points:
+- Use `t.Cleanup` to ensure `Shutdown` is called after each test
+- Use unique `AppName` per test to avoid collisions
+- Mock `DBOSContext` for fast unit tests without Postgres
+- Use real Postgres for integration tests that verify durable behavior
+
+Reference: [Testing DBOS](https://docs.dbos.dev/golang/tutorials/testing)

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

@@ -0,0 +1,64 @@
+---
+title: Start Workflows in Background
+impact: CRITICAL
+impactDescription: Background workflows enable reliable async processing
+tags: workflow, background, handle, async
+---
+
+## Start Workflows in Background
+
+Use `dbos.RunWorkflow` to start a workflow and get a handle to track it. The workflow is guaranteed to run to completion even if the app is interrupted.
+
+**Incorrect (no way to track background work):**
+
+```go
+func processData(ctx dbos.DBOSContext, data string) (string, error) {
+	// ...
+	return "processed: " + data, nil
+}
+
+// Fire and forget in a goroutine - no durability, no tracking
+go func() {
+	processData(ctx, data)
+}()
+```
+
+**Correct (using RunWorkflow):**
+
+```go
+func processData(ctx dbos.DBOSContext, data string) (string, error) {
+	return "processed: " + data, nil
+}
+
+func main() {
+	// ... setup and launch ...
+
+	// Start workflow, get handle
+	handle, err := dbos.RunWorkflow(ctx, processData, "input")
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Get the workflow ID
+	fmt.Println(handle.GetWorkflowID())
+
+	// Wait for result
+	result, err := handle.GetResult()
+
+	// Check status
+	status, err := handle.GetStatus()
+}
+```
+
+Retrieve a handle later by workflow ID:
+
+```go
+handle, err := dbos.RetrieveWorkflowstring
+result, err := handle.GetResult()
+```
+
+`GetResult` supports options:
+- `dbos.WithHandleTimeout(timeout)`: Return a timeout error if the workflow doesn't complete within the duration
+- `dbos.WithHandlePollingInterval(interval)`: Control how often the database is polled for completion
+
+Reference: [Workflows](https://docs.dbos.dev/golang/tutorials/workflow-tutorial)

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

@@ -0,0 +1,68 @@
+---
+title: Follow Workflow Constraints
+impact: CRITICAL
+impactDescription: Violating constraints breaks recovery and durability guarantees
+tags: workflow, constraints, rules, best-practices
+---
+
+## Follow Workflow Constraints
+
+Workflows have specific constraints to maintain durability guarantees. Violating them can break recovery.
+
+**Incorrect (starting workflows from steps):**
+
+```go
+func myStep(ctx context.Context) (string, error) {
+	// Don't start workflows from steps!
+	// The step's context.Context does not support workflow operations
+	return "", nil
+}
+
+func myWorkflow(ctx dbos.DBOSContext, input string) (string, error) {
+	// Starting a child workflow inside a step breaks determinism
+	dbos.RunAsStep(ctx, func(ctx context.Context) (string, error) {
+		handle, _ := dbos.RunWorkflow(ctx.(dbos.DBOSContext), otherWorkflow, "data") // WRONG
+		return handle.GetWorkflowID(), nil
+	})
+	return "", nil
+}
+```
+
+**Correct (workflow operations only from workflows):**
+
+```go
+func fetchData(ctx context.Context) (string, error) {
+	// Steps only do external operations
+	resp, err := http.Get("https://api.example.com")
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+	body, _ := io.ReadAll(resp.Body)
+	return string(body), nil
+}
+
+func myWorkflow(ctx dbos.DBOSContext, input string) (string, error) {
+	data, err := dbos.RunAsStep(ctx, fetchData, dbos.WithStepName("fetchData"))
+	if err != nil {
+		return "", err
+	}
+	// Start child workflows from the parent workflow
+	handle, err := dbos.RunWorkflow(ctx, otherWorkflow, data)
+	if err != nil {
+		return "", err
+	}
+	// Receive messages from the workflow
+	msg, err := dbos.Recvstring
+	// Set events from the workflow
+	dbos.SetEvent(ctx, "status", "done")
+	return data, nil
+}
+```
+
+Additional constraints:
+- Don't modify global variables from workflows or steps
+- All workflows and queues must be registered **before** `Launch()`
+- Concurrent steps must start in deterministic order using `dbos.Go`/`dbos.Select`
+
+Reference: [Workflow Guarantees](https://docs.dbos.dev/golang/tutorials/workflow-tutorial#workflow-guarantees)

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

@@ -0,0 +1,48 @@
+---
+title: Cancel, Resume, and Fork Workflows
+impact: MEDIUM
+impactDescription: Enables operational control over long-running workflows
+tags: workflow, cancel, resume, fork, management
+---
+
+## Cancel, Resume, and Fork Workflows
+
+DBOS provides functions to cancel, resume, and fork workflows for operational control.
+
+**Incorrect (no way to handle stuck or failed workflows):**
+
+```go
+// Workflow is stuck or failed - no recovery mechanism
+handle, _ := dbos.RunWorkflow(ctx, processTask, "data")
+// If the workflow fails, there's no way to retry or recover
+```
+
+**Correct (using cancel, resume, and fork):**
+
+```go
+// Cancel a workflow - stops at its next step
+err := dbos.CancelWorkflow(ctx, workflowID)
+
+// Resume from the last completed step
+handle, err := dbos.ResumeWorkflowstring
+result, err := handle.GetResult()
+```
+
+Cancellation sets the workflow status to `CANCELLED` and preempts execution at the beginning of the next step. Cancelling also cancels all child workflows.
+
+Resume restarts a workflow from its last completed step. Use this for workflows that are cancelled or have exceeded their maximum recovery attempts. You can also use this to start an enqueued workflow immediately, bypassing its queue.
+
+Fork a workflow from a specific step:
+
+```go
+// List steps to find the right step ID
+steps, err := dbos.GetWorkflowSteps(ctx, workflowID)
+
+// Fork from a specific step
+forkHandle, err := dbos.ForkWorkflowstring
+result, err := forkHandle.GetResult()
+```
+
+Forking creates a new workflow with a new ID, copying the original workflow's inputs and step outputs up to the selected step.
+
+Reference: [Workflow Management](https://docs.dbos.dev/golang/tutorials/workflow-management)

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

@@ -0,0 +1,51 @@
+---
+title: Keep Workflows Deterministic
+impact: CRITICAL
+impactDescription: Non-deterministic workflows cannot recover correctly
+tags: workflow, determinism, recovery, reliability
+---
+
+## Keep Workflows Deterministic
+
+Workflow functions must be deterministic: given the same inputs and step return values, they must invoke the same steps in the same order. Non-deterministic operations must be moved to steps.
+
+**Incorrect (non-deterministic workflow):**
+
+```go
+func exampleWorkflow(ctx dbos.DBOSContext, input string) (string, error) {
+	// Random value in workflow breaks recovery!
+	// On replay, rand.Intn returns a different value,
+	// so the workflow may take a different branch.
+	if rand.Intn(2) == 0 {
+		return stepOne(ctx)
+	}
+	return stepTwo(ctx)
+}
+```
+
+**Correct (non-determinism in step):**
+
+```go
+func exampleWorkflow(ctx dbos.DBOSContext, input string) (string, error) {
+	// Step result is checkpointed - replay uses the saved value
+	choice, err := dbos.RunAsStep(ctx, func(ctx context.Context) (int, error) {
+		return rand.Intn(2), nil
+	}, dbos.WithStepName("generateChoice"))
+	if err != nil {
+		return "", err
+	}
+	if choice == 0 {
+		return stepOne(ctx)
+	}
+	return stepTwo(ctx)
+}
+```
+
+Non-deterministic operations that must be in steps:
+- Random number generation
+- Getting current time (`time.Now()`)
+- Accessing external APIs (`http.Get`, etc.)
+- Reading files
+- Database queries
+
+Reference: [Workflow Determinism](https://docs.dbos.dev/golang/tutorials/workflow-tutorial#determinism)

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

@@ -0,0 +1,64 @@
+---
+title: List and Inspect Workflows
+impact: MEDIUM
+impactDescription: Enables monitoring and debugging of workflow executions
+tags: workflow, list, inspect, status, monitoring
+---
+
+## List and Inspect Workflows
+
+Use `dbos.ListWorkflows` to query workflow executions by status, name, time range, and other criteria.
+
+**Incorrect (no monitoring of workflow state):**
+
+```go
+// Start workflow with no way to check on it later
+dbos.RunWorkflow(ctx, processTask, "data")
+// If something goes wrong, no way to find or debug it
+```
+
+**Correct (listing and inspecting workflows):**
+
+```go
+// List workflows by status
+erroredWorkflows, err := dbos.ListWorkflows(ctx,
+	dbos.WithStatus([]dbos.WorkflowStatusType{dbos.WorkflowStatusError}),
+)
+
+for _, wf := range erroredWorkflows {
+	fmt.Printf("Workflow %s: %s - %v\n", wf.ID, wf.Name, wf.Error)
+}
+```
+
+List workflows with multiple filters:
+
+```go
+workflows, err := dbos.ListWorkflows(ctx,
+	dbos.WithName("processOrder"),
+	dbos.WithStatus([]dbos.WorkflowStatusType{dbos.WorkflowStatusSuccess}),
+	dbos.WithLimit(100),
+	dbos.WithSortDesc(),
+	dbos.WithLoadOutput(true),
+)
+```
+
+List workflow steps:
+
+```go
+steps, err := dbos.GetWorkflowSteps(ctx, workflowID)
+for _, step := range steps {
+	fmt.Printf("Step %d: %s\n", step.StepID, step.StepName)
+	if step.Error != nil {
+		fmt.Printf("  Error: %v\n", step.Error)
+	}
+	if step.ChildWorkflowID != "" {
+		fmt.Printf("  Child: %s\n", step.ChildWorkflowID)
+	}
+}
+```
+
+Workflow status values: `WorkflowStatusPending`, `WorkflowStatusEnqueued`, `WorkflowStatusSuccess`, `WorkflowStatusError`, `WorkflowStatusCancelled`, `WorkflowStatusMaxRecoveryAttemptsExceeded`
+
+To optimize performance, avoid loading inputs/outputs when you don't need them (they are not loaded by default).
+
+Reference: [Workflow Management](https://docs.dbos.dev/golang/tutorials/workflow-management#listing-workflows)