@output.ai/cli 0.3.1-dev.pr156.0 → 0.4.0

package/dist/templates/agent_instructions/AGENTS.md.template

@@ -1,30 +1,220 @@
+# Output.ai Based Project Guide
+
+## Overview
+
+This project uses Output Framework to build durable, LLM-powered workflows orchestrated by Temporal. Output Framework provides abstractions for creating reliable AI workflows with automatic retry, tracing, and error handling. Developers use it to build workflows like fact checkers, content generators, data extractors, research assistants, and multi-step AI agents.
+
+### Project Overview
+
+Each workflow lives in its own folder under `src/workflows/` and follows a consistent structure. Workflows define the orchestration logic, calling steps to perform external operations like API calls, database queries, and LLM inference. The system automatically handles retries, timeouts, and distributed execution through Temporal.
+
+### Key Concepts
+
+#### Built on Top of Temporal
+
+Temporal provides durable execution guarantees - if a workflow fails mid-execution, it resumes from the last successful step rather than restarting. Output Framework wraps Temporal's workflow and activity primitives with higher-level abstractions (`workflow`, `step`, `evaluator`) that enforce best practices and provide automatic tracing.
+
+#### Single Folder Project Structure
+
+Each workflow is self-contained in a single folder with a predictable structure: `workflow.ts` contains the deterministic orchestration logic, `steps.ts` contains I/O operations (API calls, LLM inference), `evaluators.ts` contains analysis logic returning confidence-scored results, and `prompts/*.prompt` files define LLM prompts using Liquid.js templates with YAML frontmatter for model configuration.
+
+## Critical Conventions
+
+- **HTTP**: Never use axios → use `@output.ai/http` (traced, auto-retry)
+- **LLM**: Never call LLM APIs directly → use `@output.ai/llm`
+- **Workflows**: Must be deterministic - only call steps/evaluators, no direct I/O
+- **Steps**: All external operations (APIs, DBs, LLMs) must be wrapped in steps
+- **Schemas**: Use Zod (`z`) from `@output.ai/core` to define input/output schemas
+
+## Project Structure
+
+```
+src/workflows/{name}/
+  workflow.ts          # Orchestration logic (deterministic)
+  steps.ts             # I/O operations (APIs, LLM, DB)
+  evaluators.ts        # Analysis steps returning EvaluationResult
+  prompts/*.prompt             # LLM prompts (name@v1.prompt)
+  scenarios/*.json             # Test scenarios
+```
+
+## Commands
+
+```bash
+output dev                                      # Start dev (Temporal:8080, API:3001)
+output workflow list                            # List workflows
+
+# Sync execution (waits for result)
+output workflow run <name> --input <JSON|JSON_FILE>      # Execute and wait
+
+# Async execution
+output workflow start <name> --input <JSON|JSON_FILE>    # Start workflow, returns ID
+output workflow status <workflowId>             # Check execution status
+output workflow result <workflowId>             # Get result when complete
+output workflow stop <workflowId>               # Cancel running workflow
+```
+
+## Workflow Pattern
+
+Workflows orchestrate steps. They must be deterministic (no direct I/O).
+
+```typescript
+import { workflow, z } from '@output.ai/core';
+import { processData, callApi } from './steps.js';
+
+export default workflow({
+  name: 'my-workflow',
+  description: 'What this workflow does',
+  inputSchema: z.object({ query: z.string() }),
+  outputSchema: z.object({ result: z.string() }),
+  fn: async (input) => {
+    const data = await processData(input);
+    const result = await callApi(data);
+    return { result };
+  }
+});
+```
+
+**Allowed imports**: steps.ts, evaluators.ts, shared_steps.ts, types.ts, consts.ts, utils.ts
+
+**Forbidden in workflows**: Direct API calls, Math.random(), Date.now(), dynamic imports
+
+## Step Pattern
+
+Steps contain all I/O operations. They are automatically retried on failure.
+
+```typescript
+import { step, z } from '@output.ai/core';
+import { httpClient } from '@output.ai/http';
+
+const client = httpClient({ prefixUrl: 'https://api.example.com' });
+
+export const fetchData = step({
+  name: 'fetchData',
+  description: 'Fetch data from external API',
+  inputSchema: z.object({ id: z.string() }),
+  outputSchema: z.object({ data: z.any() }),
+  fn: async ({ id }) => {
+    const response = await client.get(`items/${id}`).json();
+    return { data: response };
+  },
+  options: {
+    retry: { maximumAttempts: 3 }
+  }
+});
+```
+
+## LLM Pattern
+
+Use `@output.ai/llm` for all LLM operations. Prompts are defined in `.prompt` files.
+
+**Prompt file** (`summarize@v1.prompt`):
+```yaml
 ---
-generated_by: "@output.ai/cli"
-version: "{{cliVersion}}"
-generated_on: "{{date}}"
+provider: anthropic
+model: claude-sonnet-4-20250514
+temperature: 0.7
+maxTokens: 2000
 ---
+<system>You are a helpful assistant.</system>
+<user>Summarize: \{{ content }}</user>
+```
+
+**Step using prompt**:
+```typescript
+import { step, z } from '@output.ai/core';
+import { generateText, generateObject } from '@output.ai/llm';
+
+export const summarize = step({
+  name: 'summarize',
+  inputSchema: z.object({ content: z.string() }),
+  outputSchema: z.string(),
+  fn: async ({ content }) => {
+    return generateText({
+      prompt: 'summarize@v1',
+      variables: { content }
+    });
+  }
+});
+
+// For structured output
+export const extractInfo = step({
+  name: 'extractInfo',
+  inputSchema: z.object({ text: z.string() }),
+  outputSchema: z.object({ title: z.string(), summary: z.string() }),
+  fn: async ({ text }) => {
+    return generateObject({
+      prompt: 'extract@v1',
+      variables: { text },
+      schema: z.object({ title: z.string(), summary: z.string() })
+    });
+  }
+});
+```
+
+**Available functions**: `generateText`, `generateObject`, `generateArray`, `generateEnum`
+
+**Providers**: anthropic, openai, azure
+
+## HTTP Pattern
+
+Use `@output.ai/http` for traced HTTP requests with automatic retry.
+
+```typescript
+import { httpClient } from '@output.ai/http';
+
+const client = httpClient({
+  prefixUrl: 'https://api.example.com',
+  timeout: 30000,
+  retry: { limit: 3 }
+});
+
+// In a step:
+const data = await client.get('endpoint').json();
+const result = await client.post('endpoint', { json: payload }).json();
+```
+
+## Evaluator Pattern
+
+Evaluators analyze data and return confidence-scored results.
+
+```typescript
+import { evaluator, EvaluationStringResult } from '@output.ai/core';
 
-# Output SDK Workflow Planning Agent Configuration
+export const judgeQuality = evaluator({
+  name: 'judgeQuality',
+  inputSchema: z.string(),
+  fn: async (content) => {
+    // Analysis logic
+    return new EvaluationStringResult({
+      value: 'good',
+      confidence: 0.95
+    });
+  }
+});
+```
 
-This directory contains AI agent configuration for workflow planning assistance in Output SDK development. Claude Code will automatically detect and use this configuration when planning workflows in your project.
+## Error Handling
 
-## Available Agent
+```typescript
+import { FatalError, ValidationError } from '@output.ai/core';
 
-### 🤖 workflow_planner
-- **Purpose**: Assists with workflow architecture and planning
-- **Capabilities**: System design, workflow structure, step organization, requirements analysis
-- **Usage**: Planning new workflows, architectural decisions, creating implementation blueprints
+// Non-retryable error (workflow fails immediately)
+throw new FatalError('Critical failure - do not retry');
 
-## Integration
+// Validation error (input/output schema failure)
+throw new ValidationError('Invalid input format');
+```
 
-This agent configuration integrates with:
-- **Claude Code**: AI-powered development assistant
-- **Output SDK**: Temporal-based workflow orchestration framework
-- **TypeScript**: Type-safe development patterns
-- **XML Process Flow**: Structured planning with validation checkpoints
+## Agent System
 
-## Usage
+For workflow planning and implementation:
+- `.claude/agents/workflow_planner.md` - Workflow architecture specialist
+- `.claude/agents/workflow_quality.md` - Workflow quality and best practices specialist
+- `.claude/agents/prompt_writer.md` - Prompt file creation and review specialist
+- `.claude/agents/context_fetcher.md` - Efficient context retrieval (used by other agents)
+- `.claude/commands/plan_workflow.md` - Planning command
+- `.claude/commands/build_workflow.md` - Implementation command
 
-The workflow planning agent is automatically available when using Claude Code in projects with this configuration. It provides specialized expertise for the planning and architecture phase of Output SDK workflow development.
+## Configuration
 
-To regenerate this configuration: `output-cli agents init --force`
+See `.env` file for required environment variables (API keys, etc.)

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

@@ -0,0 +1,82 @@
+---
+name: context-fetcher
+description: Use proactively to retrieve and extract relevant information from Output SDK project documentation files. Checks if content is already in context before returning.
+tools: Read, Grep, Glob
+model: haiku
+color: blue
+---
+
+# Output SDK Context Fetcher Agent
+
+You are a specialized information retrieval agent for Output SDK workflows. Your role is to efficiently fetch and extract relevant content from documentation and configuration files while avoiding duplication.
+
+## Core Responsibilities
+
+1. **Context Check First**: Determine if requested information is already in the main agent's context
+2. **Selective Reading**: Extract only the specific sections or information requested
+3. **Smart Retrieval**: Use grep to find relevant sections rather than reading entire files
+4. **Return Efficiently**: Provide only new information not already in context
+
+## Supported File Types
+
+### Configuration & Meta
+- `.outputai/meta/pre_flight.md` - Pre-execution validation rules
+- `.outputai/meta/post_flight.md` - Post-execution validation checks
+- `.outputai/AGENTS.md` - Main project context (CLAUDE.md)
+
+### Agent Instructions
+- `.outputai/agents/*.md` - Specialist agent definitions
+- `.outputai/commands/*.md` - Command definitions
+
+### Workflow Files
+- `src/workflows/*/workflow.ts` - Workflow definitions
+- `src/workflows/*/steps.ts` - Step implementations
+- `src/workflows/*/evaluators.ts` - Evaluator definitions
+- `src/workflows/*/prompts/*.prompt` - LLM prompt templates
+- `src/workflows/*/scenarios/*.json` - Test scenarios
+
+## Workflow
+
+1. Check if the requested information appears to be in context already
+2. If not in context, locate the requested file(s)
+3. Extract only the relevant sections
+4. Return the specific information needed
+
+## Output Format
+
+For new information:
+```
+📄 Retrieved from [file-path]
+
+[Extracted content]
+```
+
+For already-in-context information:
+```
+✓ Already in context: [brief description of what was requested]
+```
+
+## Smart Extraction Examples
+
+Request: "Get the pre-flight rules"
+→ Extract only `.outputai/meta/pre_flight.md`, not other meta files
+
+Request: "Find existing workflow patterns"
+→ Scan `src/workflows/*/workflow.ts` for patterns
+
+Request: "Get retry policy defaults"
+→ Use grep to find retry-related sections in pre_flight.md or AGENTS.md
+
+Request: "Find how existing steps use httpClient"
+→ Search `src/workflows/*/steps.ts` for httpClient patterns
+
+## Important Constraints
+
+- Never return information already visible in current context
+- Extract minimal necessary content
+- Use grep for targeted searches
+- Never modify any files
+- Keep responses concise
+
+---
+*This agent specializes in efficient context retrieval for Output SDK projects.*