OMO Workflow Orchestrator

A phase-gated workflow orchestrator for oh-my-opencode (omo). Adds macro-level control, context isolation, and human approval gates to omo's multi-agent parallel execution engine.

Overview

omo excels at parallel multi-agent execution (PM/Architect/Coder/QA), but lacks:

• Macro timeline control — agents scatter across the project
• Token management — context grows O(N²) with parallel agents
• Scope enforcement — agents may modify files outside their phase

Workflow Orchestrator adds:

• Phase State Machine — serial phases with strict boundaries
• Context Isolation — agents only see current phase scope
• Human Gates — [PASS]/[FAIL] approval between phases
• Fix Loop — automated retry on failures, capped at 5 attempts

Architecture

┌─────────────────────────────────────────────────┐
│           Workflow Orchestrator (新增)            │
│  ┌─────────────────────────────────────────────┐ │
│  │ roadmap.yaml ◄──── 状态机                   │ │
│  │ (阶段流转、上下文隔离、闸门)                 │ │
│  └──────────────────┬──────────────────────────┘ │
│                     │                            │
│  ┌──────────────────▼──────────────────────────┐ │
│  │ Phase 1 激活  │  Phase 2 激活               │ │
│  │ omo Context   │  omo Context                │ │
│  │ (严格裁剪)   │  (严格裁剪)                │ │
│  │ omo Agents   │  omo Agents                │ │
│  └──────────────┘  └──────────────────────────┘ │
└─────────────────────────────────────────────────┘

Installation

npm install @omo/workflow-orchestrator

Or install from source:

git clone <repo>
cd workflow-orchestrator
npm install
npm run build

Quick Start

# 1. Initialize from a master spec
omo roadmap-init --spec ./docs/master-spec.md

# 2. Review and customize roadmap.yaml
nano roadmap.yaml

# 3. Bootstrap first phase
omo phase-bootstrap

# 4. Run your omo workflow (agents execute within phase scope)

# 5. Run gate review
omo gate-review

# 6. If PASS, advance to next phase
omo phase-advance

Commands

| Command | Description | |---------|-------------| | omo roadmap-init --spec <file> | Initialize roadmap from spec | | omo phase-bootstrap | Bootstrap current phase | | omo gate-review | Run gate review | | omo phase-advance | Advance to next phase | | omo fix-loop | Show fix loop status | | omo expend --spec <file> | Append new phases | | omo insert --spec <file> | Insert phases before pending | | omo delete <phase-id> | Delete pending phase | | omo status | Show roadmap status |

Core Concepts

Phase

A named stage of development with:

• id: Unique identifier (e.g., phase-0)
• name: Human-readable name
• status: pending | executing | done | failed
• outputs: Files produced by this phase
• scope.include: Glob patterns agents MAY modify
• scope.exclude: Glob patterns agents MUST NOT modify

Roadmap

Stored in roadmap.yaml at project root:

currentPhase: phase-0
phases:
  - id: phase-0
    name: Foundation
    status: done
    outputs: []
    scope:
      include: [src/**]
      exclude: [src/features/**, src/auth/**]
  - id: phase-1
    name: Authentication
    status: pending
    outputs: [src/auth/jwt.rs]
    scope:
      include: [src/auth/**, src/features/login/**]
      exclude: [src/features/payment/**]

Gate Review

Three-step process at end of each phase:

1. Scope Scan — git diff against scope.exclude
2. Functional Tests — Run phase test scripts
3. Human Approval — [PASS] or [FAIL: feedback]

Fix Loop

When gate review fails:

1. System creates fix subtask with QA feedback
2. Coder applies fixes
3. QA re-verifies
4. Loop until pass OR 5 retries exhausted

If retries exhausted, human chooses:

• [PASS override] — Force advance
• [ABORT] — Mark phase failed

Roadmap Mutations

• Expend — Append new phases after current
• Insert — Insert phases before next pending
• Delete — Remove pending phases only

File Structure

├── src/
│   ├── core/
│   │   ├── types.ts          # Type definitions
│   │   └── RoadmapStateMachine.ts  # State machine
│   ├── tools/
│   │   ├── phase-bootstrap.ts    # Context isolation
│   │   ├── phase-parallel-execute.ts  # Parallel execution
│   │   ├── phase-gate-review.ts  # Gate review
│   │   ├── phase-advance.ts     # Phase advancement
│   │   ├── roadmap-init.ts      # Init from spec
│   │   ├── fix-loop.ts         # Fix retry loop
│   │   ├── expend.ts           # Append phases
│   │   ├── insert.ts           # Insert phases
│   │   └── delete.ts           # Delete phases
│   └── utils/
│       └── ScopeFilter.ts       # Scope matching
├── .claude/skills/          # Claude Code skills
├── .omo/phase-context/      # Phase state (gitignored)
├── roadmap.yaml.example      # Example roadmap
├── package.json
└── tsconfig.json

Context Isolation

Agents can only see files matching scope.include. Files matching scope.exclude return:

Access Denied: Out of current phase scope (file: src/features/payment/order.rs)

Previous phase outputs are injected as read-only Context API.

Token Optimization

| Without Orchestrator | With Orchestrator | |---------------------|-------------------| | O(N²) context growth | O(N) context per phase | | Global project感知 | Phase-limited感知 | | Cross-phase contamination | Isolated phases |

Dependencies

• Node.js >= 18
• oh-my-opencode (omo)
• Git

License

MIT