Stream Definition Reference

Complete reference for Orchex stream definitions — the atomic units of work in an orchestration.

Overview

A stream is the fundamental unit of execution in Orchex. Each stream represents a discrete, parallelizable task that an AI agent can execute autonomously. Streams are defined in YAML manifests and contain:

  1. Identity — Name and unique ID
  2. Dependencies — What must complete before this stream runs
  3. File Ownership — Files this stream creates or modifies
  4. Context — Files to read for context (but not modify)
  5. Plan — Instructions for the AI agent
  6. Verification — Commands to validate the output

Schema

interface StreamDefinition {
  name: string;                    // Human-readable name
  deps?: string[];                 // Stream IDs this depends on
  owns?: string[];                 // Files this stream creates/modifies
  reads?: string[];                // Files to read for context
  plan?: string;                   // Execution instructions
  setup?: string[];                // Commands to run before execution
  verify?: string[];               // Commands to run after execution
  status?: StreamStatus;           // Current execution status
  error?: string;                  // Error message if failed
  attempts?: number;               // Execution attempt count
  parentStreamId?: string;         // For fix streams: original stream ID
  appliedAt?: string;              // ISO timestamp when artifact was applied
  timeoutMs?: number;              // Per-stream timeout override
}

type StreamStatus =
  | 'pending'     // Not yet executed
  | 'in_progress' // Currently executing
  | 'complete'    // Successfully completed
  | 'failed'      // Execution failed
  | 'skipped'     // Skipped (optional stream)
  | 'blocked';    // Blocked by failed dependency

Field Reference

`name` (required)

Human-readable name for the stream. Displayed in progress output and logs.

streams:
  auth-routes:
    name: Authentication API Routes

Best practices:

  • Use descriptive names that explain what the stream accomplishes
  • Keep names concise (2-5 words)
  • Use title case for readability

`deps` (optional)

Array of stream IDs that must complete successfully before this stream can execute.

streams:
  auth-routes:
    name: Auth Routes
    deps: []  # No dependencies - Wave 1

  auth-middleware:
    name: Auth Middleware
    deps: [auth-routes]  # Depends on auth-routes

  auth-tests:
    name: Auth Tests
    deps: [auth-routes, auth-middleware]  # Multiple dependencies

Behavior:

  • Streams with no deps run in Wave 1 (parallel)
  • Streams run as soon as all their deps complete
  • If a dependency fails, this stream is marked blocked
  • Circular dependencies are detected at init and add_stream time via Kahn's algorithm and rejected
  • orchex learn auto-resolves file-ownership cycles (mutual context reads) but preserves and reports cycles from explicit deps

`owns` (optional)

Array of file paths this stream will create or modify. Used for:

  • Wave planning (avoiding parallel writes to same files)
  • Context building (reading owned files before execution)
  • Conflict detection
streams:
  auth-routes:
    name: Auth Routes
    owns:
      - src/routes/auth.ts
      - tests/auth.test.ts

Patterns supported:

  • Specific files: src/auth.ts
  • Directories: src/routes/ (all files in directory)
  • Glob patterns: src/**/*.ts (recursive matching)

Best practices:

  • Be specific about files to prevent parallel write conflicts
  • Include test files if the stream creates tests
  • Group related files in the same stream

`reads` (optional)

Array of file paths to include in context without modifying. The AI receives these files' contents to understand the codebase.

streams:
  auth-middleware:
    name: Auth Middleware
    owns: [src/middleware/auth.ts]
    reads:
      - src/routes/auth.ts     # Understand auth routes
      - src/types/user.ts      # Understand user types
      - src/config.ts          # Understand configuration

Best practices:

  • Include files the AI needs to understand the context
  • Keep reads minimal to reduce token usage
  • Use specific files rather than broad globs
  • High reads count (>4) increases timeout risk — consider splitting

`plan` (optional)

Step-by-step instructions for the AI agent. This is the most important field for execution quality.

streams:
  auth-routes:
    name: Auth Routes
    plan: |
      Create authentication API routes in src/routes/auth.ts:

      1. Create Express Router with the following endpoints:
         - POST /auth/login — Accept email/password, return JWT
         - POST /auth/logout — Invalidate session
         - POST /auth/refresh — Refresh JWT token
         - GET /auth/me — Return current user info

      2. Use bcrypt for password hashing (already in package.json)

      3. Use jsonwebtoken for JWT operations:
         - Sign tokens with process.env.JWT_SECRET
         - Token expiry: 1 hour for access, 7 days for refresh

      4. Return appropriate HTTP status codes:
         - 200 for success
         - 401 for invalid credentials
         - 400 for validation errors

      5. Export the router as default

Best practices:

  • Use numbered steps for clarity
  • Be specific about implementation details
  • Reference existing patterns in the codebase
  • Include expected behavior and edge cases
  • Mention specific libraries or utilities to use

`setup` (optional)

Array of shell commands to run before stream execution. Useful for installing dependencies or preparing the environment.

streams:
  new-feature:
    name: New Feature
    setup:
      - npm install lodash
      - npm install -D @types/lodash
    owns: [src/utils/helpers.ts]

Behavior:

  • Commands run sequentially in order
  • If any command fails, stream execution is aborted
  • Working directory is project root

`verify` (optional)

Array of shell commands to run after stream execution. Used to validate that the stream's output is correct.

streams:
  auth-routes:
    name: Auth Routes
    owns: [src/routes/auth.ts, tests/auth.test.ts]
    verify:
      - npm run build
      - npm test -- --testPathPattern=auth
      - npm run lint

Behavior:

  • Commands run sequentially after artifact is applied
  • All commands run even if earlier ones fail
  • Results are aggregated and reported
  • Stream is marked failed if critical verifications fail

Common verification commands:

verify:
  - npm run build           # TypeScript compilation
  - npm test                # Run all tests
  - npm run lint            # Linting
  - npm run typecheck       # Type checking (if separate)

`status` (optional)

Current execution status. Managed automatically by the orchestrator.

Status Description
pending Not yet executed (default)
in_progress Currently executing
complete Successfully completed
failed Execution failed
skipped Skipped (optional or user choice)
blocked Blocked by failed dependency

`error` (optional)

Error message if the stream failed. Set automatically by the orchestrator.

streams:
  failing-stream:
    name: Failing Stream
    status: failed
    error: "Test command failed: npm test exited with code 1"

`attempts` (optional)

Number of execution attempts. Incremented each time execution starts. Used for retry limiting.

streams:
  flaky-stream:
    name: Flaky Stream
    attempts: 2
    status: in_progress

Self-healing behavior:

  • Max attempts: 3 (configurable)
  • Fix streams are generated for retryable errors
  • Non-retryable errors (missing deps, syntax errors) don't retry

`parentStreamId` (optional)

For fix streams: the ID of the original stream being fixed. Used to prevent infinite fix chains.

streams:
  auth-routes:
    name: Auth Routes
    status: failed
    error: "Test failed"

  auth-routes-fix-2:
    name: Auth Routes (Fix #2)
    parentStreamId: auth-routes
    plan: |
      Previous error: Test failed
      Fix the issue and ensure tests pass.

`appliedAt` (optional)

ISO timestamp when the stream's artifact was successfully applied to the filesystem. Used to skip already-completed streams on re-runs.

streams:
  auth-routes:
    name: Auth Routes
    status: complete
    appliedAt: "2026-02-05T10:30:00Z"

`timeoutMs` (optional)

Per-stream timeout override in milliseconds. Useful for streams that need more time (e.g., complex documentation, large refactors).

streams:
  simple-fix:
    name: Simple Fix
    # Uses default timeout (10 minutes)

  complex-tutorial:
    name: Complex Tutorial
    timeoutMs: 900000  # 15 minutes for this stream
    owns: [docs/tutorials/advanced.md]

Default timeout: 600,000ms (10 minutes)

Manifest Structure

Streams are defined within a manifest file:

# .orchex/active/manifest.yaml
feature: user-authentication
created: "2026-02-05T10:00:00Z"
status: pending

streams:
  auth-types:
    name: Authentication Types
    owns: [src/types/auth.ts]
    plan: |
      Define TypeScript interfaces for authentication:
      - User, Session, Token types
      - Request/response types for auth endpoints
    verify: [npm run build]

  auth-routes:
    name: Authentication Routes
    deps: [auth-types]
    owns: [src/routes/auth.ts]
    reads: [src/types/auth.ts, src/config.ts]
    plan: |
      Create authentication API routes...
    verify: [npm run build, npm test]

  auth-tests:
    name: Authentication Tests
    deps: [auth-routes]
    owns: [tests/auth.test.ts]
    reads: [src/routes/auth.ts]
    plan: |
      Write comprehensive tests for auth routes...
    verify: [npm test]

Wave Calculation

Streams are automatically organized into waves based on dependencies:

Wave 1: Streams with no dependencies (parallel)
Wave 2: Streams depending only on Wave 1 (parallel)
Wave 3: Streams depending on Wave 1 or 2 (parallel)
...

Example:

streams:
  types:      { deps: [] }           # Wave 1
  utils:      { deps: [] }           # Wave 1 (parallel with types)
  service:    { deps: [types] }      # Wave 2
  routes:     { deps: [service] }    # Wave 3
  middleware: { deps: [types] }      # Wave 2 (parallel with service)
  tests:      { deps: [routes, middleware] }  # Wave 4
Wave 1: types, utils (parallel)
Wave 2: service, middleware (parallel)
Wave 3: routes
Wave 4: tests

Anti-Patterns to Avoid

Too Many Owned Files

# Bad: Stream owns too many unrelated files
streams:
  big-stream:
    owns:
      - src/auth.ts
      - src/billing.ts
      - src/users.ts
      - docs/api.md
      - tests/auth.test.ts

Fix: Split into focused streams:

streams:
  auth-impl:
    owns: [src/auth.ts, tests/auth.test.ts]
  billing-impl:
    owns: [src/billing.ts]
  users-impl:
    owns: [src/users.ts]
  docs-api:
    owns: [docs/api.md]

High Reads Count

# Bad: Too many files to read (>4) increases timeout risk
streams:
  complex-stream:
    reads:
      - src/file1.ts
      - src/file2.ts
      - src/file3.ts
      - src/file4.ts
      - src/file5.ts
      - src/file6.ts

Fix: Reduce reads or split the stream.

Vague Plans

# Bad: Vague plan
streams:
  auth:
    plan: Add authentication to the app

Fix: Be specific:

streams:
  auth:
    plan: |
      Create JWT-based authentication:
      1. Add login endpoint at POST /auth/login
      2. Validate credentials against UserStore
      3. Return signed JWT with 1-hour expiry
      4. Add middleware to verify tokens on protected routes

Missing Verification

# Bad: No verification
streams:
  feature:
    owns: [src/feature.ts]
    plan: Implement feature
    # No verify commands!

Fix: Always verify:

streams:
  feature:
    owns: [src/feature.ts, tests/feature.test.ts]
    plan: Implement feature with tests
    verify:
      - npm run build
      - npm test

See Also

Last updated: February 2026 • Orchex v5.0