@output.ai/cli 0.5.6 → 0.7.0

package/dist/templates/agent_instructions/skills/output-workflow-start/SKILL.md.template

@@ -1,201 +0,0 @@
----
-name: output-workflow-start
-description: Start an Output SDK workflow asynchronously without waiting for completion. Use when starting long-running workflows, getting a workflow ID for later monitoring, running workflows in the background, or executing multiple workflows in parallel.
-allowed-tools: [Bash, Read, Write]
----
-
-# Start Workflow Asynchronously
-
-## Overview
-
-This skill starts a workflow asynchronously, meaning the command returns immediately with a workflow ID while the workflow executes in the background. Use this for long-running workflows or when you need to run multiple workflows in parallel.
-
-## When to Use This Skill
-
-- Starting workflows that take minutes or hours
-- Running multiple workflows in parallel
-- When you need to disconnect and check results later
-- Monitoring workflow progress separately
-- When you need the workflow ID immediately for tracking
-
-## When to Use Sync Instead
-
-Consider using `npx output workflow run` (sync) when:
-- Workflow completes quickly (seconds)
-- You need the result immediately in your terminal
-- Simple testing during development
-- You want a single command with the result
-
-## Instructions
-
-### Basic Syntax
-
-```bash
-npx output workflow start <workflowName> --input '<json-input>'
-npx output workflow start <workflowName> --input <path-to-json-file>
-```
-
-The `--input` flag is required when the workflow expects input data.
-
-### Input Methods
-
-#### 1. Inline JSON
-
-Pass JSON directly on the command line:
-
-```bash
-npx output workflow start data-migration --input '{"batchSize": 1000}'
-```
-
-#### 2. File Path (Recommended)
-
-Reference a JSON file containing the input:
-
-```bash
-npx output workflow start data-migration --input src/data_migration/scenarios/large_batch.json
-```
-
-This is the recommended approach because:
-- Input is version controlled and reproducible
-- Complex inputs are easier to read and edit
-- Scenarios can be shared and reused
-
-### Getting the Workflow ID
-
-The command outputs the workflow ID which you'll need for:
-- Checking status: `npx output workflow status <id>`
-- Getting results: `npx output workflow result <id>`
-- Debugging: `npx output workflow debug <id>`
-
-## Examples
-
-**Scenario**: Start a long-running workflow with scenario file
-
-```bash
-npx output workflow start data-migration --input src/data_migration/scenarios/full_migration.json
-
-# Output:
-# Started workflow: data-migration
-# Workflow ID: abc123xyz
-# Use 'npx output workflow status abc123xyz' to check progress
-```
-
-**Scenario**: Start multiple workflows in parallel using scenario files
-
-```bash
-# Start several workflows with different scenario files
-npx output workflow start process-batch --input src/process_batch/scenarios/batch_1.json
-npx output workflow start process-batch --input src/process_batch/scenarios/batch_2.json
-npx output workflow start process-batch --input src/process_batch/scenarios/batch_3.json
-
-# Note: Save the workflow IDs to check them later
-```
-
-**Scenario**: Create scenario then start workflow
-
-```bash
-# Create a scenario file
-mkdir -p src/generate_report/scenarios
-cat > src/generate_report/scenarios/annual_2024.json << 'EOF'
-{
-  "year": 2024,
-  "includeCharts": true,
-  "format": "pdf"
-}
-EOF
-
-# Start the workflow
-npx output workflow start generate-report --input src/generate_report/scenarios/annual_2024.json
-# Output: Workflow ID: report-2024-abc
-
-# Check status periodically
-npx output workflow status report-2024-abc
-# Output: Status: RUNNING
-
-# Later, check again
-npx output workflow status report-2024-abc
-# Output: Status: COMPLETED
-
-# Get the result
-npx output workflow result report-2024-abc
-```
-
-**Scenario**: Quick inline test for development
-
-```bash
-npx output workflow start quick-job --input '{"test": true}'
-```
-
-**Scenario**: Script for parallel execution
-
-```bash
-# Start workflows and capture IDs
-ID1=$(npx output workflow start job --input src/job/scenarios/type_a.json | grep "Workflow ID" | cut -d: -f2 | tr -d ' ')
-ID2=$(npx output workflow start job --input src/job/scenarios/type_b.json | grep "Workflow ID" | cut -d: -f2 | tr -d ' ')
-
-# Wait and check results
-npx output workflow result $ID1
-npx output workflow result $ID2
-```
-
-## Following Up After Starting
-
-### Check Status
-
-```bash
-npx output workflow status <workflowId>
-```
-
-Status values:
-- **RUNNING**: Still executing
-- **COMPLETED**: Finished successfully
-- **FAILED**: Encountered an error
-- **TERMINATED**: Was manually stopped
-
-### Get Result
-
-```bash
-npx output workflow result <workflowId>
-```
-
-Only works for COMPLETED workflows. For FAILED workflows, use debug.
-
-### Debug If Failed
-
-```bash
-npx output workflow debug <workflowId> --format json
-```
-
-### Stop If Needed
-
-```bash
-npx output workflow stop <workflowId>
-```
-
-## Workflow ID Management
-
-When starting multiple workflows, keep track of IDs:
-
-```bash
-# Log IDs to a file
-npx output workflow start batch-job --input src/batch_job/scenarios/id_1.json >> workflow-ids.txt
-npx output workflow start batch-job --input src/batch_job/scenarios/id_2.json >> workflow-ids.txt
-
-# Or use a naming convention in your workflow that makes IDs predictable
-```
-
-## Best Practices
-
-1. **Use scenario files**: Store inputs in `src/<workflow>/scenarios/` for reproducibility
-2. **Save the workflow ID**: Always note the ID for later reference
-3. **Monitor long workflows**: Use `npx output workflow status` to check progress
-4. **Handle failures**: Check status before getting results
-5. **Clean up**: Stop any stuck workflows with `npx output workflow stop`
-
-## Related Commands
-
-- `npx output workflow run <name> --input` - Execute synchronously
-- `npx output workflow status <id>` - Check execution status
-- `npx output workflow result <id>` - Get execution result
-- `npx output workflow stop <id>` - Stop a running workflow
-- `npx output workflow debug <id>` - Debug a workflow execution

package/dist/templates/agent_instructions/skills/output-workflow-status/SKILL.md.template

@@ -1,151 +0,0 @@
----
-name: output-workflow-status
-description: Check the status of an Output SDK workflow execution. Use when monitoring a running workflow, checking if a workflow completed, or determining workflow state (RUNNING, COMPLETED, FAILED, TERMINATED).
-allowed-tools: [Bash]
----
-
-# Check Workflow Execution Status
-
-## Overview
-
-This skill checks the current execution status of a workflow. Use it to monitor running workflows, verify completion, or determine if a workflow failed before attempting to get its result.
-
-## When to Use This Skill
-
-- Monitoring a workflow started asynchronously
-- Checking if a workflow has completed
-- Determining why you can't get a workflow result
-- Verifying workflow state before taking action
-- Polling for completion in scripts
-
-## When to Use Other Commands
-
-- **Getting results**: Use `npx output workflow result` after confirming COMPLETED status
-- **Debugging failures**: Use `npx output workflow debug` for FAILED workflows
-- **Execution history**: Use `npx output workflow runs list` for multiple runs
-
-## Instructions
-
-### Check Status
-
-```bash
-npx output workflow status <workflowId>
-```
-
-Replace `<workflowId>` with the ID from `npx output workflow start` or `npx output workflow runs list`.
-
-## Understanding Status Values
-
-| Status | Meaning | Next Action |
-|--------|---------|-------------|
-| RUNNING | Workflow is currently executing | Wait and check again |
-| COMPLETED | Workflow finished successfully | Get result with `npx output workflow result` |
-| FAILED | Workflow encountered an error | Debug with `npx output workflow debug` |
-| TERMINATED | Workflow was manually stopped | Review if expected, restart if needed |
-| TIMED_OUT | Workflow exceeded time limit | Check for long operations, adjust timeout |
-
-## Examples
-
-**Scenario**: Monitor a running workflow
-
-```bash
-# Start a workflow
-npx output workflow start data-sync '{"source": "external"}'
-# Output: Workflow ID: sync-abc123
-
-# Check status
-npx output workflow status sync-abc123
-# Output: Status: RUNNING
-
-# Wait and check again
-sleep 30
-npx output workflow status sync-abc123
-# Output: Status: COMPLETED
-```
-
-**Scenario**: Poll for completion in a script
-
-```bash
-WORKFLOW_ID="abc123xyz"
-
-while true; do
-  STATUS=$(npx output workflow status $WORKFLOW_ID)
-  echo "Current status: $STATUS"
-
-  if [[ "$STATUS" == *"COMPLETED"* ]]; then
-    echo "Workflow completed!"
-    npx output workflow result $WORKFLOW_ID
-    break
-  elif [[ "$STATUS" == *"FAILED"* ]]; then
-    echo "Workflow failed!"
-    npx output workflow debug $WORKFLOW_ID --format json
-    break
-  fi
-
-  sleep 10
-done
-```
-
-**Scenario**: Check before getting result
-
-```bash
-# Verify status first
-npx output workflow status my-workflow-123
-
-# If COMPLETED, get result
-npx output workflow result my-workflow-123
-
-# If FAILED, debug instead
-npx output workflow debug my-workflow-123 --format json
-```
-
-**Scenario**: Batch status check
-
-```bash
-# Check multiple workflows
-for id in abc123 def456 ghi789; do
-  echo "Workflow $id: $(npx output workflow status $id)"
-done
-```
-
-## Status Transitions
-
-Workflows typically follow these paths:
-
-```
-RUNNING -> COMPLETED (success)
-RUNNING -> FAILED (error occurred)
-RUNNING -> TERMINATED (manually stopped)
-RUNNING -> TIMED_OUT (exceeded limit)
-```
-
-## Interpreting Status Output
-
-The status command returns information including:
-- **Status**: Current state (RUNNING, COMPLETED, FAILED, etc.)
-- **Duration**: How long the workflow has been running or ran
-- **Start Time**: When the workflow began
-
-## Troubleshooting
-
-### "Workflow not found"
-- The workflow ID may be incorrect
-- The workflow may have been deleted from history
-- Check `npx output workflow runs list` to find the correct ID
-
-### Status stays RUNNING too long
-1. Check if the workflow is stuck: `npx output workflow debug <id>`
-2. Look for infinite loops or waiting operations
-3. Consider stopping: `npx output workflow stop <id>`
-
-### Unexpected TERMINATED status
-- Someone may have manually stopped the workflow
-- Check with `npx output workflow debug` for context
-- Restart if needed: `npx output workflow start`
-
-## Related Commands
-
-- `npx output workflow result <id>` - Get execution result (after COMPLETED)
-- `npx output workflow debug <id>` - Debug execution (after FAILED)
-- `npx output workflow stop <id>` - Stop a running workflow
-- `npx output workflow runs list` - View execution history

package/dist/templates/agent_instructions/skills/output-workflow-stop/SKILL.md.template

@@ -1,164 +0,0 @@
----
-name: output-workflow-stop
-description: Stop a running Output SDK workflow execution. Use when cancelling a workflow, stopping a long-running process, terminating a stuck workflow, or when you need to abort a workflow in progress.
-allowed-tools: [Bash]
----
-
-# Stop Running Workflow
-
-## Overview
-
-This skill stops a running workflow execution. The workflow will be marked as TERMINATED and will not complete its remaining steps. Use this carefully as it cannot be undone.
-
-## When to Use This Skill
-
-- Cancelling a workflow that's no longer needed
-- Stopping a workflow that appears stuck
-- Terminating a long-running workflow to free resources
-- Aborting a workflow with incorrect input
-- Emergency stop during unexpected behavior
-
-## When NOT to Use This
-
-- If the workflow is about to complete (let it finish)
-- If you're unsure whether stopping is safe
-- For debugging (use `npx output workflow debug` instead)
-- If the workflow has side effects that may leave data in an inconsistent state
-
-## Instructions
-
-### Stop a Workflow
-
-```bash
-npx output workflow stop <workflowId>
-```
-
-### Safety Considerations
-
-Before stopping, consider:
-
-1. **Side effects**: Has the workflow made changes that need to be rolled back?
-2. **Partial completion**: Are there steps that completed with side effects?
-3. **Dependencies**: Are other workflows or systems waiting on this result?
-4. **Recovery**: Do you need to restart or clean up after stopping?
-
-## Examples
-
-**Scenario**: Stop a stuck workflow
-
-```bash
-# Check status - workflow has been running too long
-npx output workflow status abc123xyz
-# Status: RUNNING (for 2 hours)
-
-# Decide to stop it
-npx output workflow stop abc123xyz
-# Workflow abc123xyz has been stopped
-
-# Verify it's terminated
-npx output workflow status abc123xyz
-# Status: TERMINATED
-```
-
-**Scenario**: Cancel a workflow started with wrong input
-
-```bash
-# Realized input was wrong immediately after starting
-npx output workflow start expensive-job '{"wrong": "input"}'
-# Workflow ID: job-abc123
-
-# Stop before it processes too much
-npx output workflow stop job-abc123
-
-# Start again with correct input
-npx output workflow start expensive-job '{"correct": "input"}'
-```
-
-**Scenario**: Stop multiple workflows
-
-```bash
-# Get list of running workflows
-npx output workflow runs list --format json | jq '.[] | select(.status == "RUNNING") | .workflowId'
-
-# Stop each one (carefully review first!)
-for id in abc123 def456; do
-  echo "Stopping $id"
-  npx output workflow stop $id
-done
-```
-
-## After Stopping a Workflow
-
-### Check the State
-
-```bash
-npx output workflow status <workflowId>
-# Status: TERMINATED
-```
-
-### Review What Happened
-
-```bash
-npx output workflow debug <workflowId> --format json
-```
-
-This shows:
-- Which steps completed before termination
-- Any partial results or side effects
-- The point at which the workflow was stopped
-
-### Clean Up If Needed
-
-If the workflow made partial changes:
-1. Review the debug output to see what completed
-2. Manually revert any side effects if necessary
-3. Consider creating a cleanup workflow for this scenario
-
-### Restart If Appropriate
-
-```bash
-# Start a fresh execution
-npx output workflow start <workflowName> '<input>'
-```
-
-## What Happens When You Stop
-
-1. The Temporal server receives the termination request
-2. The currently executing step may complete or abort
-3. No further steps are executed
-4. The workflow status changes to TERMINATED
-5. The result will not be available (workflow didn't complete)
-
-## Troubleshooting
-
-### "Workflow not found"
-- Check the workflow ID is correct
-- Use `npx output workflow runs list` to find valid IDs
-
-### "Workflow already completed"
-- The workflow finished before the stop command
-- Check status and get result if needed
-
-### "Workflow already terminated"
-- The workflow was already stopped
-- No action needed
-
-### Stop command hangs
-- The Temporal server may be unresponsive
-- Check if services are running: `docker ps | grep output`
-- May need to restart services
-
-## Best Practices
-
-1. **Always check status first**: Confirm the workflow is actually RUNNING
-2. **Review before stopping**: Use `npx output workflow debug` to understand state
-3. **Document why**: Note why you stopped the workflow for future reference
-4. **Plan for cleanup**: Know what side effects may need manual handling
-5. **Consider alternatives**: Sometimes waiting is better than stopping
-
-## Related Commands
-
-- `npx output workflow status <id>` - Check current status
-- `npx output workflow debug <id>` - Review execution details
-- `npx output workflow start <name>` - Start a new execution
-- `npx output workflow runs list` - View execution history

package/dist/templates/agent_instructions/skills/output-workflow-trace/SKILL.md.template

@@ -1,134 +0,0 @@
----
-name: output-workflow-trace
-description: Analyze Output SDK workflow execution traces. Use when debugging a specific workflow, examining step failures, analyzing input/output data, understanding execution flow, or when you have a workflow ID to investigate.
-allowed-tools: [Bash, Read]
----
-
-# Workflow Trace Analysis
-
-## Overview
-
-This skill provides guidance on retrieving and analyzing workflow execution traces using the Output CLI. Traces show the complete execution history including step inputs, outputs, errors, and timing information.
-
-## When to Use This Skill
-
-- You have a workflow ID and need to understand what happened
-- A workflow failed and you need to identify which step failed
-- You need to examine the input/output data at each step
-- You want to understand the execution flow and timing
-- You need to find error messages and stack traces
-- Debugging retry behavior or unexpected results
-
-## Instructions
-
-### Step 1: Retrieve the Execution Trace
-
-**Basic trace (text format, may be truncated):**
-```bash
-npx output workflow debug <workflowId>
-```
-
-**Full trace (JSON format, recommended for detailed analysis):**
-```bash
-npx output workflow debug <workflowId> --format json
-```
-
-**Tip**: Always use `--format json` when you need complete trace data. The text format truncates long values which can hide important debugging information.
-
-### Step 2: Analyze the Trace
-
-Follow this checklist when examining a trace:
-
-1. **Identify the failed step**: Look for steps with error status or failure indicators
-2. **Examine error messages**: Find the exact error message and stack trace
-3. **Check step inputs**: Verify the data passed to the failing step was correct
-4. **Check step outputs**: Look at outputs from preceding steps
-5. **Review retry attempts**: Note how many retries occurred and their outcomes
-6. **Check timing**: Look for unusual delays that might indicate timeouts
-
-### Step 3: Use the Temporal UI for Visual Analysis
-
-Open **http://localhost:8080** in your browser for a visual workflow inspection:
-
-1. Search for your workflow by ID
-2. View the event history timeline
-3. Click on individual events to see details
-4. Inspect step inputs and outputs
-5. See retry attempts and timing information
-6. Export trace data if needed
-
-## What to Look For in Traces
-
-### Error Patterns
-
-| Error Message | Likely Cause |
-|---------------|--------------|
-| "incompatible schema" | Zod import issue - using `zod` instead of `@output.ai/core` |
-| "non-deterministic" | Using Math.random(), Date.now(), etc. in workflow code |
-| "FatalError" with retry context | Try-catch wrapping step calls |
-| "undefined is not a function" | Missing schema definitions |
-| "workflow must be deterministic" | Direct I/O in workflow function |
-| "ECONNREFUSED" or timeout | Services not running or network issues |
-
-### Step Status Values
-
-- **COMPLETED**: Step finished successfully
-- **FAILED**: Step threw an error (may retry)
-- **RETRYING**: Step is being retried after a failure
-- **TIMED_OUT**: Step exceeded its timeout
-- **CANCELLED**: Workflow was stopped before step completed
-
-### Key Trace Fields
-
-When examining JSON traces, focus on these fields:
-
-- `steps[].name`: Step identifier
-- `steps[].status`: Execution result
-- `steps[].input`: Data passed to the step
-- `steps[].output`: Data returned from the step
-- `steps[].error`: Error details if failed
-- `steps[].attempts`: Number of execution attempts
-- `steps[].duration`: How long the step took
-
-## Examples
-
-**Scenario**: Debug a failed workflow
-
-```bash
-# Get the workflow ID from runs list
-npx output workflow runs list --limit 5 --format json
-
-# Get detailed trace
-npx output workflow debug abc123xyz --format json
-
-# Look for the failing step in the output
-# Example output structure:
-# {
-#   "workflowId": "abc123xyz",
-#   "status": "FAILED",
-#   "steps": [
-#     { "name": "fetchData", "status": "COMPLETED", ... },
-#     { "name": "processData", "status": "FAILED", "error": "..." }
-#   ]
-# }
-```
-
-**Scenario**: Investigate retry behavior
-
-```bash
-npx output workflow debug abc123xyz --format json | jq '.steps[] | select(.attempts > 1)'
-```
-
-**Scenario**: Check inputs to a specific step
-
-```bash
-npx output workflow debug abc123xyz --format json | jq '.steps[] | select(.name == "processData") | .input'
-```
-
-## Next Steps After Analysis
-
-1. Match the error to common patterns (see error skills)
-2. Consult the `workflow-quality` subagent for best practices
-3. Make code fixes based on identified issues
-4. Re-run the workflow: `npx output workflow run <workflowName> <input>`
-5. Verify the fix with a new trace