@output.ai/cli 0.0.0 → 0.0.2

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

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

@@ -0,0 +1,60 @@
+---
+description: Pre-Flight Checks for Output SDK Workflow Operations
+version: 1.0
+encoding: UTF-8
+---
+
+# Pre-Flight Rules for Output SDK Workflows
+
+## Execution Requirements
+
+- **CRITICAL**: For any step that specifies a subagent in the `subagent=""` XML attribute, you MUST use the specified subagent to perform the instructions for that step
+- Process all XML blocks sequentially and completely
+- Execute every numbered step in the process_flow EXACTLY as specified
+
+## Output SDK Conventions Check
+
+Before proceeding with any workflow operation, verify:
+
+- **ES Modules**: All imports MUST use `.js` extension for ESM modules
+- **HTTP Client**: NEVER use axios directly - always use @output.ai/http wrapper
+- **LLM Client**: NEVER use a direct llm call - always use @output.ai/llm wrapper
+- **Worker Restarts**: Remember to restart worker after creating workflows: `overmind restart worker`
+- **Documentation**: Run `yarn g:workflow-doc` after modifications
+
+## Requirements Gathering Strategy
+
+### Smart Defaults Application
+When information is not explicitly provided, apply these defaults:
+- **Retry Policies**: 3 attempts with exponential backoff (1s initial, 10s max)
+- **OpenAI Models**: Use `gpt-4o` unless specified otherwise
+- **Error Handling**: ApplicationFailure patterns with appropriate error types
+- **Performance**: Optimize for clarity and maintainability over raw speed
+- **Timeouts**: 30 seconds for activities, 5 minutes for workflows
+
+### Critical Information Requirements
+Only stop to ask for clarification on:
+- Ambiguous input/output structures that cannot be inferred from context
+- Specific API keys or services not commonly used in the project
+- Non-standard error handling or recovery requirements
+- Complex orchestration patterns requiring specific sequencing
+- External dependencies not already in the project
+
+## Template Processing Rules
+
+- Use exact templates as provided in each step
+- Replace all template variables with actual values:
+  - `{{workflowName}}` - The workflow being planned
+  - `{{projectPath}}` - Root project directory path
+  - `{{requirements}}` - User-provided requirements
+  - `{{currentDate}}` - Current date in YYYY-MM-DD format
+  - `{{sdkVersion}}` - Current Output SDK version
+
+## Quality Gates
+
+Before proceeding past pre-flight:
+1. Confirm all required context is available
+2. Verify understanding of the workflow's purpose
+3. Check for existing similar workflows to use as patterns
+4. Ensure Output SDK conventions are understood
+5. Validate that necessary subagents are available

package/dist/templates/workflow/README.md.template

@@ -4,7 +4,7 @@
 
 ## Overview
 
-This workflow was generated using the Flow SDK CLI. It provides a starting point for building Temporal-based workflows with LLM integration.
+This workflow was generated using the Output SDK CLI. It provides a starting point for building Temporal-based workflows with LLM integration.
 
 ## Files
 
@@ -63,7 +63,7 @@ Example:
 
 ### Workflow Structure
 
-The workflow follows the new Flow SDK conventions:
+The workflow follows the new Output SDK conventions:
 
 ```typescript
 import { workflow } from '@output.ai/core';
@@ -159,8 +159,8 @@ export const llmStep = step( {
   },
   outputSchema: { type: 'string' },
   fn: async ( input: { userInput: string } ) => {
-    const prompt = loadPrompt( 'prompt@v1', { 
-      userInput: input.userInput 
+    const prompt = loadPrompt( 'prompt@v1', {
+      userInput: input.userInput
     } );
     const response = await generateText( prompt as Prompt );
     return response;
@@ -193,7 +193,7 @@ To test your workflow:
 
 1. Build the parent project containing this workflow
 2. Start the Flow worker
-3. Execute the workflow using the Flow SDK API
+3. Execute the workflow using the Output SDK API
 
 Example execution:
 ```bash
@@ -210,6 +210,6 @@ curl -X POST http://localhost:3001/workflow \
 
 ## Resources
 
-- [Flow SDK Documentation](https://github.com/growthxai/flow-sdk)
+- [Output SDK Documentation](https://github.com/growthxai/flow-sdk)
 - [Temporal Documentation](https://docs.temporal.io)
 - [AI SDK Documentation](https://sdk.vercel.ai/docs)

package/dist/templates/workflow/workflow.ts.template

@@ -5,7 +5,7 @@ import { exampleLLMStep, processDataStep } from './steps.js';
 const inputSchema = {
   type: 'object',
   properties: {
-    prompt: { 
+    prompt: {
       type: 'string',
       description: 'The prompt to send to the LLM'
     },
@@ -60,7 +60,7 @@ export default workflow( {
     } );
 
     // Process data if provided, otherwise use defaults
-    const processedData = await processDataStep( 
+    const processedData = await processDataStep(
       input.data || { value: 42, type: 'default' }
     );
 

package/dist/utils/paths.d.ts

@@ -3,6 +3,7 @@
  */
 export declare const TEMPLATE_DIRS: {
     readonly workflow: string;
+    readonly agent_instructions: string;
 };
 /**
  * Default output directories
@@ -22,3 +23,7 @@ export declare function createTargetDir(outputDir: string, workflowName: string)
  * Get the template directory for a specific template type
  */
 export declare function getTemplateDir(templateType: keyof typeof TEMPLATE_DIRS): string;
+/**
+ * Get the agent instruction directory for a specific category
+ */
+export declare function getAgentInstructionDir(category: 'agents' | 'commands'): string;