/output-meta-project-context

name: output-meta-project-context
description: Comprehensive guide to Output.ai Framework for building durable, LLM-powered workflows orchestrated by Temporal. Covers project structure, workflow patterns, steps, LLM integration, HTTP clients, CLI commands, and the full inventory of available agents and skills.
allowed-tools: [Read]

Output.ai Framework - Complete Project Context

What is Output.ai?

Output.ai provides infrastructure for building production-grade AI workflows: fact checkers, content generators, data extractors, research assistants, and multi-step agents. Built on Temporal, it guarantees **durable execution** - if execution fails mid-run, it resumes from the last successful step.

Core Philosophy

**Separation of orchestration from I/O:**

• **Workflows** orchestrate execution (must be deterministic - no I/O)
• **Steps/Evaluators** handle all I/O operations (HTTP, LLM, database calls)

This separation enables automatic retries, resumption, and debugging.

Component Taxonomy

| Component | Purpose | Key Rule | |-----------|---------|----------| | **Workflow** | Orchestrates step execution | Must be deterministic (no I/O, no Date.now(), no Math.random()) | | **Step** | Handles all I/O operations | Where HTTP, LLM, DB calls happen | | **Evaluator** | Quality assessment | Returns confidence-scored results for validation loops | | **Scenario** | Test input data | JSON files matching workflow's inputSchema | | **Prompt** | LLM templates | Liquid.js templating with YAML frontmatter config | | **Eval Test** | Offline quality testing | Dataset-driven verification with `verify()` from `@outputai/evals` |

Project Structure

config/
├── credentials.yml.enc          # Global encrypted credentials
├── credentials.key              # Global decryption key (DO NOT COMMIT)
└── credentials/                 # Environment-specific credentials
    ├── production.yml.enc
    └── production.key
src/
├── shared/                      # Shared code across workflows
│   ├── clients/                 # API clients (e.g., jina.ts, stripe.ts)
│   └── utils/                   # Utility functions (e.g., string.ts)
└── workflows/                   # Workflow definitions
    └── {workflow_name}/
        ├── workflow.ts          # Orchestration logic (deterministic)
        ├── steps.ts             # I/O operations
        ├── types.ts             # Zod schemas (input, output, internal)
        ├── evaluators.ts        # Quality checks (optional)
        ├── utils.ts             # Local utilities (optional)
        ├── credentials.yml.enc  # Workflow-specific credentials (optional)
        ├── prompts/             # LLM templates (optional)
        │   └── generate@v1.prompt
        ├── scenarios/           # Test inputs (optional)
        │   └── happy_path.json
        └── tests/               # Offline eval tests (optional)
            ├── datasets/        # YAML test datasets
            │   └── happy_path.yml
            └── evals/           # Eval evaluators and workflow
                ├── evaluators.ts
                └── workflow.ts

Code Reuse Rules

**Shared directory** (`src/shared/`):

• `shared/clients/` - API clients using `@outputai/http` for external services
• `shared/utils/` - Helper functions and utilities

**Allowed imports:**

• Workflows/steps can import from `../../shared/clients/*.js` and `../../shared/utils/*.js`
• Workflows/steps can import from local files (`./types.js`, `./utils.js`)

**Forbidden:**

• Importing from sibling workflow folders (`../other_workflow/steps.js`)
• Steps importing other steps (activity isolation requirement)

Critical Rules

| Rule | Correct | Incorrect | |------|---------|-----------| | Zod import | `import { z } from '@outputai/core'` | `import { z } from 'zod'` | | HTTP client | `import { createKyClient } from '@outputai/http'` | `import axios from 'axios'` | | HTTP bodies | Read with `.json()`/`.text()` or cancel unused non-HEAD bodies | Read only `response.url`/`status` and leave body open | | Credentials | `import { credentials } from '@outputai/credentials'` | `process.env.SECRET` | | LLM calls | `import { generateText, Output } from '@outputai/llm'` | Direct provider SDK | | ES imports | `import { fn } from './file.js'` | `import { fn } from './file'` | | Workflow I/O | Call steps for any I/O | Direct fetch/http in workflow |

**Determinism violations (never in workflows):**

• `Date.now()`, `new Date()`
• `Math.random()`, `crypto.randomUUID()`
• Direct HTTP/fetch calls
• File system operations
• Environment variable reads

---

Available Tools Inventory

Agents

| Agent | Purpose | |-------|---------| | `workflow-planner` | Designs workflow architecture, creates implementation blueprints | | `workflow-debugger` | Analyzes workflow execution traces, identifies issues | | `workflow-quality` | Reviews code quality, validates implementations | | `workflow-prompt-writer` | Creates and optimizes LLM prompt templates | | `workflow-context-fetcher` | Gathers documentation and existing patterns |

Skills

Workflow Authoring

| Skill | Purpose | |-------|---------| | `output-plan-workflow` | Plan workflow architecture - **ALWAYS FIRST**, creates implementation blueprint | | `output-build-workflow` | Build/implement workflows from a plan, or for modifications | | `output-debug-workflow` | Debug workflow issues when workflows fail or behave unexpectedly | | `output-migrate` | Upgrade a project between Output framework versions |

Workflow Operations

| Skill | Purpose | |-------|---------| | `output-workflow-run` | Synchronous workflow execution (waits for result) | | `output-workflow-start` | Asynchronous workflow execution (returns ID) | | `output-workflow-list` | List available workflows | | `output-workflow-status` | Check async workflow status | | `output-workflow-result` | Get async workflow result | | `output-workflow-reset` | Rerun a workflow from after a completed step |

Monitoring & Debugging