Core Concepts

This guide explains how Orchex works using plain language and visual examples.

What is Orchex?

Orchex helps Claude (or other AI assistants) work on large projects by breaking them into smaller, manageable pieces. Think of it like a construction project manager:

  • You provide the blueprint (manifest)
  • Orchex coordinates the work
  • Claude does the actual building

The Big Picture

You write a manifest → Orchex plans the work → Claude executes it → You get results
     (blueprint)         (project manager)      (worker)         (finished product)

Streams: Individual Tasks

A stream is a single piece of work. Like "add a login button" or "fix the checkout bug."

Example:

streams:
  - id: add-login-button
    description: Add a login button to the header
    files:
      - src/components/Header.tsx

Stream Lifecycle

[pending] → [running] → [complete]
                ↓
            [failed]

Each stream:

  1. Starts as pending (waiting to run)
  2. Becomes running (Claude is working on it)
  3. Ends as complete (success!) or failed (needs attention)

Waves: Parallel Execution

A wave is a group of streams that can run at the same time. Like having multiple construction crews working on different floors simultaneously.

Wave 1: [database] [api]      ← These run together
          ↓          ↓
Wave 2: [frontend] ─────────── ← This waits for Wave 1

Example:

streams:
  # Wave 1 - independent tasks
  - id: database-schema
  - id: api-types
  
  # Wave 2 - depends on Wave 1
  - id: api-endpoints
    dependencies: [database-schema, api-types]

Why Waves Matter

Without waves:

[task-1] → [task-2] → [task-3] → [task-4]  (4 hours)

With waves:

[task-1] ┐
[task-2] ├→ [task-4]  (2 hours)
[task-3] ┘

Waves let independent work happen in parallel, saving time.

Dependencies: Task Order

Dependencies tell Orchex which tasks must finish before others can start.

Simple Dependency

[create-database] → [add-users-table]
streams:
  - id: create-database
  
  - id: add-users-table
    dependencies: [create-database]  # Waits for database

Multiple Dependencies

[schema] ┐
[types]  ├→ [api] → [tests]
[auth]   ┘
streams:
  - id: schema
  - id: types
  - id: auth
  
  - id: api
    dependencies: [schema, types, auth]  # Waits for all three
  
  - id: tests
    dependencies: [api]  # Waits for API

Diamond Dependencies

       [database]
          ↓    ↓
     [users] [products]
          ↓    ↓
       [checkout]

Orchex automatically figures out that checkout can't start until both users and products are done, even though you only specify direct dependencies.

Artifacts: Saving Progress

Artifacts are snapshots of your work at each step. Like taking photos during construction so you can see progress (or go back if needed).

Stream completes → Creates artifact → Saved to disk
                      (snapshot)        (.orchex/artifacts/)

Artifact Structure

.orchex/artifacts/
├── add-login-button.json       ← What files changed
├── fix-checkout-bug.json
└── update-tests.json

Each artifact contains:

  • Operations: What changed (create, edit, delete files)
  • Summary: What was accomplished
  • Timestamp: When it completed

Example artifact:

{
  "streamId": "add-login-button",
  "status": "complete",
  "operations": [
    {
      "type": "edit",
      "path": "src/components/Header.tsx",
      "edits": [...]
    }
  ],
  "summary": "Added login button to header component"
}

Why Artifacts Matter

  1. Resume work: If Orchex stops, it can pick up where it left off
  2. Track changes: See exactly what each stream did
  3. Debug issues: Understand what happened when something breaks

Verification: Checking Quality

After each stream completes, Orchex can verify the work meets your standards.

Stream completes → Run checks → Pass or fail
                     (tests)      ↓
                              Mark stream status

Verification Types

1. Commands (e.g., tests)

verification:
  commands:
    - npm test
    - npm run lint

2. File checks

verification:
  requiredFiles:
    - src/components/LoginButton.tsx
    - src/components/__tests__/LoginButton.test.tsx

3. Content validation

verification:
  rules:
    - All TypeScript files must have no type errors
    - Tests must have >80% coverage

Verification Flow

[Stream completes]
       ↓
[Run npm test] → Pass → [Mark complete] → [Continue]
       ↓
    Fail → [Mark failed] → [Stop/Retry]

Putting It All Together

Here's how all concepts work together:

feature: add-user-authentication

streams:
  # Wave 1: Foundation (run in parallel)
  - id: database-schema
    files: [migrations/001-users.sql]
    verification:
      commands: [npm run migrate:test]
  
  - id: auth-types
    files: [src/types/auth.ts]
  
  # Wave 2: Implementation (depends on Wave 1)
  - id: auth-service
    dependencies: [database-schema, auth-types]
    files: [src/services/auth.ts]
    verification:
      commands: [npm test src/services/auth.test.ts]
  
  # Wave 3: Integration (depends on Wave 2)
  - id: login-page
    dependencies: [auth-service]
    files: [src/pages/Login.tsx]
    verification:
      requiredFiles: [src/pages/Login.tsx]
      commands: [npm test src/pages/Login.test.tsx]

Execution Timeline

Time →

Wave 1:  [database-schema] ═══════╗
         [auth-types]      ═══════╣
                                   ↓
Wave 2:                      [auth-service] ════════╗
                                                     ↓
Wave 3:                                        [login-page] ════

         Each ═ represents verification checks

What Orchex Does

  1. Plans: Reads manifest, determines waves based on dependencies
  2. Executes: Runs streams in order, parallel when possible
  3. Verifies: Checks each stream's output
  4. Saves: Creates artifacts for completed work
  5. Reports: Shows progress and results

Mental Models

Construction Project

Manifest = Blueprint
Streams = Tasks ("install plumbing", "wire electricity")
Waves = Work crews (can work on different areas simultaneously)
Dependencies = "Must finish foundation before building walls"
Artifacts = Progress photos
Verification = Building inspection

Recipe

Manifest = Recipe card
Streams = Steps ("chop onions", "boil water")
Waves = Things you can do at once ("chop while water boils")
Dependencies = "Must boil water before adding pasta"
Artifacts = Photos of each step
Verification = Taste test

Assembly Line

Manifest = Product design
Streams = Stations ("attach wheels", "paint body")
Waves = Parallel stations
Dependencies = "Must build frame before attaching wheels"
Artifacts = Quality control checkpoints
Verification = Final inspection

Common Patterns

Sequential Work (One Thing at a Time)

streams:
  - id: step-1
  - id: step-2
    dependencies: [step-1]
  - id: step-3
    dependencies: [step-2]
[step-1] → [step-2] → [step-3]

Parallel Work (Multiple Things at Once)

streams:
  - id: task-a
  - id: task-b
  - id: task-c
  # No dependencies = all run together
[task-a]
[task-b]  ← All in Wave 1
[task-c]

Fork-Join (Split Then Merge)

streams:
  - id: setup
  
  - id: feature-a
    dependencies: [setup]
  - id: feature-b
    dependencies: [setup]
  
  - id: integration
    dependencies: [feature-a, feature-b]
      [setup]
        ↓  ↓
    [a]    [b]
        ↓  ↓
   [integration]

Key Takeaways

  1. Streams = Individual tasks Claude will work on
  2. Waves = Groups of streams that run in parallel
  3. Dependencies = Required order ("A must finish before B starts")
  4. Artifacts = Saved results from each stream
  5. Verification = Quality checks after each stream

Orchex handles the complexity of coordinating work, so you just describe what needs to be done (streams) and what order makes sense (dependencies). Everything else is automatic.

Next Steps