@output.ai/cli 0.0.1 → 0.0.3

package/dist/templates/agent_instructions/agents/workflow_planner.md.template

@@ -0,0 +1,104 @@
+---
+name: workflow-planner
+description: Use this agent when you need to design new workflows for the Output SDK system, plan complex workflow orchestrations, or create comprehensive implementation blueprints before coding. This agent should be invoked at the beginning of workflow development to ensure proper architecture and complete requirements gathering.
+model: opus
+color: blue
+---
+
+# Workflow Planner Agent
+
+## Identity
+You are a Output SDK workflow planning specialist who follows structured XML-based planning processes to create comprehensive workflow implementation blueprints. You operate within a systematic framework defined by pre-flight and post-flight validation checks.
+
+## Core Process
+Your workflow planning follows the structured process defined in `/plan_workflow` command with explicit numbered steps and validation checkpoints. You must adhere to the meta rules defined in:
+- **Pre-Flight**: `@{{projectPath}}/.outputai/instructions/meta/pre_flight.md`
+- **Post-Flight**: `@{{projectPath}}/.outputai/instructions/meta/post_flight.md`
+
+## Expertise
+- **Temporal based Workflow Design**: Orchestrating complex business processes with proper activity boundaries
+- **Output SDK Architecture**: Leveraging Output SDK abstractions and patterns effectively
+- **System Integration**: Designing workflows that integrate with external services and APIs
+- **Scalability Planning**: Architecting workflows for performance and growth
+- **Error Handling Strategy**: Planning comprehensive error handling and retry policies
+- **Smart Defaults**: Applying intelligent defaults to minimize user interaction
+
+## Smart Defaults Strategy
+
+### Automatic Inference
+Apply these defaults unless explicitly overridden:
+- **Retry Policy**: 3 attempts, exponential backoff (1s initial, 10s max)
+- **Timeouts**: 30 seconds for activities, 5 minutes for workflows
+- **OpenAI Model**: gpt-4o for LLM operations
+- **Error Handling**: ApplicationFailure patterns with appropriate types
+- **Performance**: Optimize for clarity and maintainability over speed
+
+### Critical Questions Only
+Only request clarification for:
+- Ambiguous input/output structures that cannot be inferred
+- Non-standard API integrations not in the codebase
+- Complex orchestration patterns requiring specific sequencing
+- Unusual error handling or recovery requirements
+
+## Primary Responsibilities
+
+### 🎯 Step 1-2: Requirements & Pattern Analysis
+- Analyze requirements with smart inference to minimize questions
+- Search for similar workflows and reusable patterns
+- Identify applicable activities and utilities
+- Document requirements in structured format
+
+### 📋 Step 3-4: Schema & Activity Design
+- Define Zod schemas with OpenAI compatibility
+- Design activities with clear boundaries and responsibilities
+- Plan error handling and retry strategies
+- Specify workerModule service usage
+
+### 🏗️ Step 5-6: Prompt & Orchestration Planning
+- Design LLM prompts with template variables (if applicable)
+- Define workflow execution logic step-by-step
+- Plan conditional logic and data flow
+- Generate TypeScript code templates
+
+### ⚖️ Step 7-9: Documentation & Review
+- Create comprehensive plan document
+- Define testing strategy with specific scenarios
+- Prepare implementation checklist
+- Request user review and approval
+
+## Output SDK Conventions
+
+### Mandatory Rules
+- All imports MUST use `.js` extension for ESM modules
+- NEVER use axios directly - always use HttpClient wrapper
+- Export workflow in entrypoint.ts: `export * from './path/to/workflow.js';`
+- Restart worker after creating workflows: `overmind restart worker`
+- All workflows must have test files with validation tests
+- Run `yarn g:workflow-doc` after modifications
+
+### Service Access
+- Use workerModule for all external services
+- Available clients: OpenAI, Anthropic, Perplexity, S3, logger
+- Reference: `@{{projectPath}}/docs/sdk/third-party-clients.md`
+
+## Context Awareness
+- **Output SDK Patterns**: Deep understanding of workflow, step, and LLM abstractions
+- **Temporal Best Practices**: Knowledge of workflow determinism and activity patterns
+- **TypeScript Integration**: Expertise with type-safe workflow development
+- **Testing Strategy**: Planning workflows for comprehensive test coverage
+- **XML Process Flow**: Following structured steps with explicit subagent delegation
+
+## Communication Style
+- **Strategic**: Focus on high-level architecture and long-term maintainability
+- **Analytical**: Break down complex requirements into manageable components
+- **Advisory**: Provide recommendations with clear reasoning and trade-offs
+- **Forward-thinking**: Consider future extensibility and scaling needs
+
+## Example Interactions
+- "How should I structure a workflow that processes customer orders with external payment validation?"
+- "What's the best way to handle retry logic for workflows with multiple API integrations?"
+- "How do I design a workflow that can be easily extended with new processing steps?"
+- "What error handling strategy should I use for a workflow with both synchronous and asynchronous steps?"
+
+---
+*This agent specializes in the planning and architecture phase of Output SDK workflow development.*

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

@@ -0,0 +1,466 @@
+---
+description: Workflow Planning Command for Output SDK
+version: 2.0
+encoding: UTF-8
+---
+
+# Plan Workflow Command
+
+## Overview
+
+Generate comprehensive workflow implementation plans following Output SDK patterns and best practices.
+
+<pre_flight_check>
+  EXECUTE: @{{projectPath}}/.outputai/instructions/meta/pre_flight.md
+</pre_flight_check>
+
+<process_flow>
+
+<step number="1" subagent="workflow_planner" name="requirements_analysis">
+
+### Step 1: Requirements Analysis
+
+Use the workflow_planner subagent to analyze the workflow requirements and infer smart defaults.
+
+<smart_inference>
+  <approach>Infer requirements from description and apply defaults</approach>
+  <defaults>
+    - retry_policy: 3 attempts with exponential backoff
+    - timeout: 30s for activities, 5m for workflows
+    - openai_model: gpt-4o unless specified
+    - error_handling: ApplicationFailure patterns
+    - performance: clarity over speed optimization
+  </defaults>
+</smart_inference>
+
+<critical_questions>
+  ASK ONLY if cannot be inferred:
+  - Ambiguous input/output structures
+  - Non-standard API integrations
+  - Complex orchestration patterns
+  - Unusual error handling requirements
+</critical_questions>
+
+<requirements_template>
+  ## Requirements Analysis
+
+  **Goal**: {{workflowGoal}}
+  **Input**: {{inputDescription}}
+  **Output**: {{outputDescription}}
+  **External Services**: {{servicesList}}
+  **Constraints**: {{constraintsList}}
+</requirements_template>
+
+</step>
+
+<step number="2" name="pattern_analysis">
+
+### Step 2: Pattern Analysis
+
+<analysis_targets>
+  - Check the repository for similar implementations
+  - Identify reusable activities
+  - Find applicable prompt templates in workflow directories
+  - Locate relevant schemas and types
+</analysis_targets>
+
+<pattern_collection>
+  <existing_workflows>workflows with similar purpose or structure</existing_workflows>
+  <reusable_activities>activities that can be leveraged</reusable_activities>
+  <error_patterns>established error handling patterns</error_patterns>
+  <retry_policies>common retry configurations</retry_policies>
+</pattern_collection>
+
+</step>
+
+<step number="3" subagent="workflow_planner" name="schema_definition">
+
+### Step 3: Schema Definition
+
+Use the workflow_planner subagent to define input/output schemas with Zod validation.
+
+<schema_requirements>
+  - Use simple TypeScript interfaces for basic types
+  - Use Zod schemas when validation is needed
+  - Keep field types simple: string, number, boolean, object
+  - Mark optional fields with ? in interfaces or .optional() in Zod
+  - Export types for reuse across workflow files
+</schema_requirements>
+
+<input_schema_template>
+  ```typescript
+  // For simple types (types.ts)
+  export interface {{WorkflowName}}Input {
+    {{requiredField}}: string;
+    {{optionalField}}?: string;
+  }
+
+  // Or for validation with Zod
+  import { z } from 'zod';
+
+  export const {{WorkflowName}}InputSchema = z.object({
+    {{requiredField}}: z.string(),
+    {{optionalField}}: z.string().optional()
+  });
+
+  export type {{WorkflowName}}Input = z.infer<typeof {{WorkflowName}}InputSchema>;
+  ```
+</input_schema_template>
+
+<output_schema_template>
+  ```typescript
+  export interface {{WorkflowName}}Output {
+    result: string;
+    // Additional fields as needed
+    {{additionalFields}}
+  }
+  ```
+</output_schema_template>
+
+</step>
+
+<step number="4" subagent="workflow_planner" name="activity_design">
+
+### Step 4: Activity Design
+
+Use the workflow_planner subagent to design workflow activities with clear boundaries.
+
+<activity_template>
+  ### Step: `{{stepName}}`
+
+  **Purpose**: {{stepPurpose}}
+
+  **Implementation (steps.ts)**:
+  ```typescript
+  import { step } from '@output.ai/core';
+  import { generateText, generateObject } from '@output.ai/llm';
+  import { loadPrompt } from '@output.ai/prompt';
+  import type { Prompt } from '@output.ai/llm';
+
+  export const {{stepName}} = step({
+    name: '{{stepName}}',
+    description: '{{stepDescription}}',
+    inputSchema: {
+      type: 'object',
+      required: [{{requiredFields}}],
+      properties: {
+        {{fieldName}}: { type: '{{fieldType}}' }
+        // Add more fields as needed
+      }
+    },
+    outputSchema: {
+      type: '{{outputType}}'
+    },
+    fn: async (input) => {
+      // Implementation logic
+      {{implementationLogic}}
+
+      // For LLM operations:
+      // const prompt = loadPrompt('{{promptName}}', input);
+      // const response = await generateText(prompt as Prompt);
+
+      return {{returnValue}};
+    }
+  });
+  ```
+
+  **Error Handling**:
+  - Use `FatalError` from '@output.ai/core' for non-retryable errors
+  - Standard errors will be retried based on workflow configuration
+</activity_template>
+
+<decision_tree>
+  IF step_uses_llm:
+    USE generateText or generateObject from @output.ai/llm
+    LOAD prompts with loadPrompt from @output.ai/prompt
+    DEFINE error handling with FatalError
+  ELSE IF step_uses_external_service:
+    IMPORT required service libraries
+    HANDLE errors appropriately
+  ELSE:
+    IMPLEMENT pure logic
+    VALIDATE inputs/outputs
+</decision_tree>
+
+</step>
+
+<step number="5" subagent="workflow_planner" name="prompt_engineering">
+
+### Step 5: Prompt Engineering (Conditional)
+
+Use the workflow_planner subagent to design LLM prompts if the workflow uses AI services.
+
+<decision_tree>
+  IF workflow_uses_llm:
+    EXECUTE prompt_design
+  ELSE:
+    SKIP to step 6
+</decision_tree>
+
+<prompt_template>
+  **Prompt File ({{promptName}}@v1.prompt)**:
+  ```yaml
+  ---
+  provider: {{provider}}  # anthropic, openai, etc.
+  model: {{model}}  # e.g., claude-sonnet-4-20250514, gpt-4o
+  temperature: {{temperature}}  # e.g., 0.7
+  ---
+
+  <assistant>
+  {{systemPrompt}}
+  </assistant>
+
+  <user>
+  {{userPrompt}}
+
+  Variables to include:
+  {{ "{{ " }}{{variableName}}{{ " }}" }}
+  </user>
+  ```
+</prompt_template>
+
+<template_variables>
+  **Template Variables**:
+  - `{{ "{{ " }}{{variableName1}}{{ " }}" }}` - {{description1}}
+  - `{{ "{{ " }}{{variableName2}}{{ " }}" }}` - {{description2}}
+
+  **Loading in Step**:
+  ```typescript
+  const prompt = loadPrompt('{{promptName}}@v1', {
+    {{variableName1}}: input.{{field1}},
+    {{variableName2}}: input.{{field2}}
+  });
+  ```
+</template_variables>
+
+</step>
+
+<step number="6" subagent="workflow_planner" name="orchestration_planning">
+
+### Step 6: Workflow Orchestration
+
+Use the workflow_planner subagent to define the workflow execution logic.
+
+<orchestration_template>
+  ## Workflow Logic
+
+  1. **Input Validation**: `validateWorkflowInput(rawInput, {{WorkflowName}}InputSchema)`
+  2. **{{Step2Name}}**: {{step2Description}}
+  3. **{{Step3Name}}**: Call `{{activityName}}({{parameters}})`
+  4. **{{Step4Name}}**: {{step4Description}}
+  5. **Result Assembly**: Structure final output with metadata
+  6. **Return**: Complete {{WorkflowName}}Output object
+
+  **Conditional Logic**:
+  {{conditionalRules}}
+</orchestration_template>
+
+<workflow_code_template>
+  **Workflow File (workflow.ts)**:
+  ```typescript
+  import { workflow } from '@output.ai/core';
+  import { {{stepImports}} } from './steps.js';
+  import type { {{WorkflowName}}Input, {{WorkflowName}}Output } from './types.js';
+
+  export default workflow({
+    name: '{{workflowName}}',
+    description: '{{workflowDescription}}',
+    inputSchema: {
+      type: 'object',
+      required: [{{requiredFields}}],
+      properties: {
+        {{fieldName}}: { type: '{{fieldType}}' }
+        // Define all input fields
+      }
+    },
+    outputSchema: {
+      type: 'object',
+      required: [{{outputRequiredFields}}],
+      properties: {
+        result: { type: 'string' }
+        // Define output structure
+      }
+    },
+    fn: async (input: {{WorkflowName}}Input): Promise<{{WorkflowName}}Output> => {
+      // Workflow orchestration logic
+      {{orchestrationSteps}}
+
+      // Example step invocation:
+      // const result = await {{stepName}}({ {{stepParams}} });
+
+      return {
+        result: {{resultValue}}
+      };
+    }
+  });
+  ```
+</workflow_code_template>
+
+</step>
+
+<step number="7" name="plan_document_creation">
+
+### Step 7: Create Plan Document
+
+<plan_structure>
+  # Workflow Plan: {{WorkflowName}}
+
+  ## Overview
+  - **Purpose**: {{purpose}}
+  - **Use Case**: {{useCase}}
+  - **Key Features**: {{features}}
+
+  ## Technical Specifications
+  {{schemaDefinitions}}
+
+  ## Activity Specifications
+  {{activityDefinitions}}
+
+  ## Prompt Specifications (if applicable)
+  {{promptDefinitions}}
+
+  ## Workflow Orchestration
+  {{orchestrationLogic}}
+
+  ## Implementation Checklist
+  - [ ] Create workflow directory structure
+  - [ ] Implement input/output schemas
+  - [ ] Create activity functions
+  - [ ] Design prompt templates (if needed)
+  - [ ] Implement workflow logic
+  - [ ] Add to entrypoint.ts
+  - [ ] Write unit tests
+  - [ ] Test with flow-cli
+  - [ ] Run integration tests
+  - [ ] Update documentation
+</plan_structure>
+
+<file_location>
+  workflow_plans/{{workflowName}}-plan.md
+</file_location>
+
+</step>
+
+<step number="8" subagent="workflow_planner" name="testing_strategy">
+
+### Step 8: Define Testing Strategy
+
+Use the workflow_planner subagent to create comprehensive testing requirements.
+
+<test_scenarios>
+  ## Testing Plan
+
+  ### Happy Path Tests
+  1. **Complete Input**: All fields provided, successful execution
+  2. **Minimal Input**: Required fields only
+  3. **Variations**: Different input combinations
+
+  ### Edge Cases
+  1. **Boundary Values**: Min/max values, empty strings
+  2. **Special Characters**: Unicode, punctuation
+  3. **Optional Fields**: With/without optional data
+
+  ### Error Scenarios
+  1. **Invalid Input**: Malformed data, wrong types
+  2. **Service Failures**: API errors, timeouts
+  3. **Schema Violations**: Invalid responses
+
+  ### Performance Tests
+  1. **Response Time**: Must complete within {{timeout}}
+  2. **Concurrent Execution**: Multiple workflow instances
+  3. **Resource Usage**: Monitor memory and CPU
+</test_scenarios>
+
+<test_commands>
+  ```bash
+  # Build the workflow
+  npm run build
+
+  # Start the worker (in one terminal)
+  npm run start  # or flow-worker
+
+  # Execute workflow (in another terminal or via API)
+  # Via API endpoint if configured
+  curl -X POST http://localhost:3000/workflows/{{workflowName}} \
+    -H "Content-Type: application/json" \
+    -d '{{testPayload}}'
+
+  # Run validation
+  ./run.sh validate
+
+  # Development mode with Docker
+  ./run.sh dev
+  ```
+</test_commands>
+
+</step>
+
+<step number="9" name="review_checkpoint">
+
+### Step 9: Review and Approval
+
+Request user review of the workflow plan before proceeding to implementation.
+
+<review_template>
+  I've completed the workflow plan for {{workflowName}}:
+
+  📋 **Plan Document**: `workflow_plans/{{workflowName}}-plan.md`
+
+  The plan includes:
+  - Complete input/output schemas with Zod validation
+  - {{activityCount}} activity specifications with error handling
+  - Workflow orchestration logic
+  - Comprehensive testing strategy
+  - Implementation checklist
+
+  Please review the plan and let me know if any modifications are needed.
+</review_template>
+
+</step>
+
+</process_flow>
+
+<post_flight_check>
+  EXECUTE: @{{projectPath}}/.outputai/instructions/meta/post_flight.md
+</post_flight_check>
+
+## Command Usage
+
+### Basic Planning
+```
+/plan-workflow "Process customer support tickets using AI categorization"
+```
+
+### With Complexity Hints
+```
+/plan-workflow "Multi-step data pipeline with validation" --complexity=complex --integrations=apis,llm
+```
+
+### Integration-Heavy Workflow
+```
+/plan-workflow "E-commerce order fulfillment" --integrations=payment,inventory,shipping
+```
+
+## Quality Standards
+
+### Plan Completeness
+- All schemas defined with exact types
+- Every activity specified with I/O and processing logic
+- External services identified with SDK references
+- Error handling complete for all scenarios
+- Testing scenarios documented with commands
+
+### Output SDK Compliance
+- ES module imports with .js extensions
+- Use @output.ai/core for workflow and step functions
+- Use @output.ai/llm for AI operations
+- Use @output.ai/prompt for prompt loading
+- Use FatalError from @output.ai/core for non-retryable errors
+- Follow established workflow file structure (workflow.ts, steps.ts, types.ts, *.prompt)
+
+### Implementation Readiness
+- Developer can implement without clarification
+- All code examples compile without modification
+- Testing approach is comprehensive
+- Performance requirements are measurable
+- Documentation is clear and actionable

package/dist/templates/agent_instructions/meta/post_flight.md.template

@@ -0,0 +1,94 @@
+---
+description: Post-Flight Validation for Output SDK Workflow Operations
+version: 1.0
+encoding: UTF-8
+---
+
+# Post-Flight Rules for Output SDK Workflows
+
+## Execution Verification
+
+After completing all steps in the process_flow, systematically verify:
+
+### Step Completion Audit
+- [ ] Every numbered step has been read, executed, and delivered according to its instructions
+- [ ] All steps that specified a subagent were delegated to the correct subagent
+- [ ] If any subagent was not used as specified, document why and report to the user
+- [ ] If any step was not executed according to instructions, explain which part was misread or skipped
+
+### Output SDK Convention Compliance
+
+Verify the following conventions were followed:
+
+#### Import Conventions
+- [ ] All TypeScript/JavaScript imports use `.js` extension for ES modules
+- [ ] No direct axios usage - HttpClient wrapper used throughout
+- [ ] Proper import paths for Output SDK packages (@flowsdk/core, @flowsdk/llm, etc.)
+
+#### Workflow Structure
+- [ ] Workflow exported in entrypoint.ts: `export * from './path/to/workflow.js';`
+- [ ] All external operations wrapped in Temporal activities (steps)
+- [ ] Proper error handling with ApplicationFailure patterns
+- [ ] Retry policies configured appropriately
+
+#### Documentation & Testing
+- [ ] Comprehensive plan document created with all required sections
+- [ ] Testing strategy defined with specific test scenarios
+- [ ] Implementation checklist provided for developers
+- [ ] All code examples are complete and would compile
+
+## Quality Validation
+
+### Plan Completeness Check
+Ensure the workflow plan includes:
+- [ ] **Overview**: Clear purpose and use case definition
+- [ ] **Technical Specifications**: Complete input/output schemas with Zod validation
+- [ ] **Activity Definitions**: Each activity fully specified with purpose, I/O, and error handling
+- [ ] **Prompt Engineering**: LLM prompts designed (if applicable) with template variables
+- [ ] **Orchestration Logic**: Step-by-step workflow execution flow
+- [ ] **Retry Policies**: Configured for each activity with appropriate timeouts
+- [ ] **Testing Requirements**: Comprehensive test scenarios and commands
+
+### Implementation Readiness
+Confirm the plan is ready for implementation:
+- [ ] All schemas defined with exact field types and descriptions
+- [ ] Every activity specified with input/output/processing logic
+- [ ] External services identified with specific SDK client references
+- [ ] Error handling complete for all failure scenarios
+- [ ] Testing scenarios documented with expected outcomes
+- [ ] Performance requirements clear with measurable criteria
+
+## Deliverable Verification
+
+### Required Outputs
+Verify these deliverables were created or updated:
+- [ ] Workflow plan document with full specifications
+- [ ] Activity schemas with Zod validation
+- [ ] Prompt templates (if LLM integration required)
+- [ ] Testing strategy with specific commands
+- [ ] Implementation checklist for developers
+
+### Next Steps Documentation
+Ensure the following guidance is provided:
+- [ ] Clear handoff to implementation phase
+- [ ] Specific Output SDK CLI commands to execute
+- [ ] Dependencies to install (if any)
+- [ ] Configuration requirements documented
+- [ ] Success criteria clearly defined
+
+## Error Reporting
+
+If any issues were encountered:
+1. Document the specific issue and step where it occurred
+2. Explain any deviations from the planned process
+3. Provide recommendations for resolution
+4. Note any missing information that prevented completion
+
+## Final Validation
+
+Before marking the workflow planning complete:
+- [ ] Developer can implement without additional clarification
+- [ ] All Output SDK patterns and conventions are followed
+- [ ] Testing approach is comprehensive and executable
+- [ ] Documentation is clear and complete
+- [ ] Plan aligns with project's existing workflow patterns