@output.ai/cli 0.4.2 → 0.5.1

package/dist/templates/agent_instructions/commands/debug_workflow.md.template

@@ -0,0 +1,198 @@
+---
+argument-hint: [problem-description-and-optional-workflow-id]
+description: Debug Output SDK workflow issues
+version: 0.0.1
+model: claude-opus-4-1
+---
+
+Your task is to systematically debug an Output SDK workflow issue in a local development environment.
+
+The first argument is a textual description of the problem you're experiencing. If you have a specific workflow ID, include it in your description.
+
+Use the todo tool to track your progress through the debugging process.
+
+# Debugging Process
+
+## Overview
+
+Follow a systematic approach to identify and resolve workflow execution issues: verify infrastructure, gather evidence, analyze traces, and apply targeted fixes.
+
+<pre_flight_check>
+  EXECUTE: @.outputai/instructions/meta/pre_flight.md
+</pre_flight_check>
+
+<process_flow>
+
+<step number="1" name="verify_services">
+
+### Step 1: Verify Services Running
+
+Before debugging, confirm that all required services are operational. The `output-services-check` skill provides comprehensive guidance.
+
+<verification_commands>
+```bash
+# Check Docker containers are running
+docker ps | grep output
+
+# Verify Output services respond
+curl -s http://localhost:3001/health || echo "API not responding"
+
+# Check Temporal UI is accessible
+curl -s http://localhost:8080 > /dev/null && echo "Temporal UI accessible" || echo "Temporal UI not accessible"
+```
+</verification_commands>
+
+<decision_tree>
+  IF docker_not_running:
+    RUN: docker compose up -d
+    WAIT: for services to start (30-60 seconds)
+  IF output_dev_not_running:
+    RUN: npx output dev
+    WAIT: for services to initialize
+  IF all_services_running:
+    PROCEED: to step 2
+</decision_tree>
+
+**Expected State**:
+- Docker containers for `output` are running
+- API server responds at `http://localhost:3001`
+- Temporal UI accessible at `http://localhost:8080`
+
+</step>
+
+<step number="2" name="list_workflow_runs">
+
+### Step 2: List Workflow Runs
+
+Identify the failing workflow execution by listing recent runs. The `output-workflow-runs-list` skill provides detailed filtering guidance.
+
+<list_commands>
+```bash
+# List all recent workflow runs
+npx output workflow runs list
+
+# Filter by specific workflow type (if known)
+npx output workflow runs list <workflowName>
+
+# Get detailed JSON output for analysis
+npx output workflow runs list --format json
+
+# Limit results to most recent
+npx output workflow runs list --limit 10
+```
+</list_commands>
+
+<identification_criteria>
+Look for:
+- Status: FAILED or TERMINATED
+- Recent timestamp matching when the issue occurred
+- Workflow type matching the problem description
+</identification_criteria>
+
+<decision_tree>
+  IF user_provided_workflow_id:
+    USE: provided workflow ID
+    PROCEED: to step 3
+  IF failed_runs_found:
+    SELECT: most recent failed run
+    NOTE: workflow ID from output
+    PROCEED: to step 3
+  IF no_runs_found:
+    CHECK: workflow exists with `npx output workflow list`
+    IF workflow_not_found:
+      REPORT: workflow doesn't exist
+      SUGGEST: verify workflow name and location
+    ELSE:
+      SUGGEST: run the workflow with `npx output workflow run <name>`
+</decision_tree>
+
+</step>
+
+<step number="3" name="debug_workflow" subagent="workflow-debugger">
+
+### Step 3: Debug Specific Workflow
+
+Retrieve and analyze the execution trace for the identified workflow. The `output-workflow-trace` skill provides analysis techniques.
+
+<debug_commands>
+```bash
+# Display execution trace (text format)
+npx output workflow debug <workflowId>
+
+# Display full untruncated trace (JSON format) - recommended for detailed analysis
+npx output workflow debug <workflowId> --format json
+```
+</debug_commands>
+
+**Tip**: Use `--format json` for complete trace data without truncation.
+
+<analysis_checklist>
+1. Identify which step failed
+2. Examine the error message and stack trace
+3. Check input data passed to the failing step
+4. Check output data from preceding steps
+5. Look for patterns matching common error types
+</analysis_checklist>
+
+<temporal_ui_guidance>
+For visual workflow inspection, open the Temporal Web UI at **http://localhost:8080**:
+- Find your workflow execution by ID
+- View the event history timeline
+- Inspect individual step inputs and outputs
+</temporal_ui_guidance>
+
+</step>
+
+<step number="4" name="suggest_fixes" subagent="workflow-quality">
+
+### Step 4: Suggest Fixes
+
+Based on the trace analysis, identify the error pattern and suggest targeted fixes. Claude will invoke the relevant error skill based on symptoms.
+
+<error_matching>
+
+| Symptom | Skill |
+|---------|-------|
+| "incompatible schema" errors, type errors | `output-error-zod-import` |
+| Replay failures, inconsistent results | `output-error-nondeterminism` |
+| Retries not working, errors swallowed | `output-error-try-catch` |
+| Type errors, undefined properties at step boundaries | `output-error-missing-schemas` |
+| Workflow hangs, determinism errors | `output-error-direct-io` |
+| Untraced requests, axios errors | `output-error-http-client` |
+
+</error_matching>
+
+<decision_tree>
+  IF error_matches_known_pattern:
+    INVOKE: relevant error skill for detailed fix
+  ELSE:
+    CONSULT: workflow-quality subagent for additional patterns
+    SUGGEST: Manual trace inspection in Temporal UI
+</decision_tree>
+
+<verification>
+After applying fix:
+```bash
+# Re-run the workflow to verify
+npx output workflow run <workflowName> <input>
+
+# Or start asynchronously and check result
+npx output workflow start <workflowName> <input>
+npx output workflow status <workflowId>
+npx output workflow result <workflowId>
+```
+</verification>
+
+</step>
+
+</process_flow>
+
+<post_flight_check>
+  EXECUTE: @.outputai/instructions/meta/post_flight.md
+</post_flight_check>
+
+---- START ----
+
+Problem Description and Optional Workflow ID:
+
+$ARGUMENTS

package/dist/templates/agent_instructions/commands/plan_workflow.md.template

@@ -25,7 +25,7 @@ Generate detailed specifications for implementation of a new workflow.
 
 <process_flow>
 
-<step number="1" name="context_gathering" subagent="context-fetcher">
+<step number="1" name="context_gathering" subagent="workflow-context-fetcher">
 
 ### Step 1: Context Gathering
 
@@ -130,7 +130,7 @@ export const sumValues = step( {
 
 </step>
 
-<step number="5" name="prompt_engineering" subagent="prompt-writer">
+<step number="5" name="prompt_engineering" subagent="workflow-prompt-writer">
 
 ### Step 5: Prompt Engineering
 
@@ -213,7 +213,7 @@ Design the testing strategy for the workflow.
 
 Generate the complete plan in markdown format.
 
-Note that every implementation should start with running the cli command `output workflow generate --skeleton` to create the workflow directory structure.
+Note that every implementation should start with running the cli command `npx output workflow generate --skeleton` to create the workflow directory structure.
 
 <file_template>
   <header>

package/dist/templates/agent_instructions/skills/output-error-direct-io/SKILL.md.template

@@ -0,0 +1,249 @@
+---
+name: output-error-direct-io
+description: Fix direct I/O in Output SDK workflow functions. Use when workflow hangs, returns undefined, shows "workflow must be deterministic" errors, or when HTTP/API calls are made directly in workflow code.
+allowed-tools: [Bash, Read]
+---
+
+# Fix Direct I/O in Workflow Functions
+
+## Overview
+
+This skill helps diagnose and fix a critical error pattern where I/O operations (HTTP calls, database queries, file operations) are performed directly in workflow functions instead of in steps. This violates Temporal's determinism requirements.
+
+## When to Use This Skill
+
+You're seeing:
+- Workflow hangs indefinitely
+- Undefined or empty responses
+- "workflow must be deterministic" errors
+- Network operations failing silently
+- Timeouts without clear cause
+
+## Root Cause
+
+Workflow functions must be **deterministic** - they should only orchestrate steps, not perform I/O directly. When you make HTTP calls, database queries, or any external operations directly in a workflow function:
+
+1. **Hangs**: The workflow may hang because I/O isn't properly handled
+2. **Determinism violations**: Temporal replays workflows, and I/O results differ
+3. **No retry logic**: Direct calls bypass Output SDK's retry mechanisms
+4. **No tracing**: Operations aren't recorded in the workflow trace
+
+## Symptoms
+
+### Direct fetch/axios in Workflow
+
+```typescript
+// WRONG: I/O directly in workflow
+export default workflow({
+  fn: async (input) => {
+    const response = await fetch('https://api.example.com/data');  // BAD!
+    const data = await response.json();
+    return { data };
+  }
+});
+```
+
+### Direct Database Calls
+
+```typescript
+// WRONG: Database I/O in workflow
+export default workflow({
+  fn: async (input) => {
+    const user = await db.users.findById(input.userId);  // BAD!
+    return { user };
+  }
+});
+```
+
+### File System Operations
+
+```typescript
+// WRONG: File I/O in workflow
+import fs from 'fs/promises';
+
+export default workflow({
+  fn: async (input) => {
+    const data = await fs.readFile(input.path, 'utf-8');  // BAD!
+    return { data };
+  }
+});
+```
+
+## Solution
+
+Move ALL I/O operations to step functions. Steps are designed to handle non-deterministic operations.
+
+### Before (Wrong)
+
+```typescript
+export default workflow({
+  fn: async (input) => {
+    const response = await fetch('https://api.example.com/data');
+    const data = await response.json();
+    return { data };
+  }
+});
+```
+
+### After (Correct)
+
+```typescript
+import { z, step, workflow } from '@output.ai/core';
+import { httpClient } from '@output.ai/http';
+
+// Create a step for the I/O operation
+export const fetchData = step({
+  name: 'fetchData',
+  inputSchema: z.object({
+    endpoint: z.string(),
+  }),
+  outputSchema: z.object({
+    data: z.unknown(),
+  }),
+  fn: async (input) => {
+    const client = httpClient({ prefixUrl: 'https://api.example.com' });
+    const data = await client.get(input.endpoint).json();
+    return { data };
+  },
+});
+
+// Workflow only orchestrates steps
+export default workflow({
+  inputSchema: z.object({}),
+  outputSchema: z.object({ data: z.unknown() }),
+  fn: async (input) => {
+    const result = await fetchData({ endpoint: 'data' });
+    return result;
+  },
+});
+```
+
+## Complete Example: Database Operation
+
+### Before (Wrong)
+
+```typescript
+export default workflow({
+  fn: async (input) => {
+    const user = await prisma.user.findUnique({
+      where: { id: input.userId }
+    });
+    const orders = await prisma.order.findMany({
+      where: { userId: input.userId }
+    });
+    return { user, orders };
+  }
+});
+```
+
+### After (Correct)
+
+```typescript
+import { z, step, workflow } from '@output.ai/core';
+import { prisma } from '../lib/db';
+
+export const fetchUser = step({
+  name: 'fetchUser',
+  inputSchema: z.object({ userId: z.string() }),
+  outputSchema: z.object({
+    user: z.object({
+      id: z.string(),
+      name: z.string(),
+      email: z.string(),
+    }).nullable(),
+  }),
+  fn: async (input) => {
+    const user = await prisma.user.findUnique({
+      where: { id: input.userId }
+    });
+    return { user };
+  },
+});
+
+export const fetchOrders = step({
+  name: 'fetchOrders',
+  inputSchema: z.object({ userId: z.string() }),
+  outputSchema: z.object({
+    orders: z.array(z.object({
+      id: z.string(),
+      total: z.number(),
+    })),
+  }),
+  fn: async (input) => {
+    const orders = await prisma.order.findMany({
+      where: { userId: input.userId }
+    });
+    return { orders };
+  },
+});
+
+export default workflow({
+  inputSchema: z.object({ userId: z.string() }),
+  outputSchema: z.object({
+    user: z.unknown(),
+    orders: z.array(z.unknown()),
+  }),
+  fn: async (input) => {
+    const { user } = await fetchUser({ userId: input.userId });
+    const { orders } = await fetchOrders({ userId: input.userId });
+    return { user, orders };
+  },
+});
+```
+
+## Finding Direct I/O in Workflows
+
+Search for common I/O patterns in workflow files:
+
+```bash
+# Find fetch calls
+grep -rn "await fetch" src/workflows/
+
+# Find axios calls
+grep -rn "axios\." src/workflows/
+
+# Find database operations
+grep -rn "prisma\.\|db\.\|mongoose\." src/workflows/
+
+# Find file system operations
+grep -rn "fs\.\|readFile\|writeFile" src/workflows/
+```
+
+Then review each match to see if it's in a workflow function vs a step function.
+
+## What CAN Be in Workflow Functions
+
+Workflow functions should contain:
+- **Step calls**: `await myStep(input)`
+- **Orchestration logic**: conditionals, loops (over step calls)
+- **Data transformation**: Pure functions on step results
+- **Constants**: Static values and configuration
+
+Workflow functions should NOT contain:
+- HTTP/API calls
+- Database operations
+- File system operations
+- External service calls
+- Anything that talks to the network or filesystem
+
+## Verification
+
+After moving I/O to steps:
+
+1. **Run the workflow**: `npx output workflow run <name> '<input>'`
+2. **Check the trace**: `npx output workflow debug <id> --format json`
+3. **Verify steps appear**: Look for your I/O steps in the trace
+4. **Confirm no errors**: No determinism warnings or hangs
+
+## Benefits of Steps for I/O
+
+1. **Retry logic**: Steps can be retried on failure
+2. **Tracing**: I/O operations appear in workflow traces
+3. **Timeouts**: Steps can have individual timeouts
+4. **Determinism**: Replays use recorded results
+5. **Debugging**: Clear visibility into what happened
+
+## Related Issues
+
+- For HTTP client best practices, see `output-error-http-client`
+- For non-determinism from other causes, see `output-error-nondeterminism`