Foreman

Foreman: Multi-Model Orchestration for AI Coding Agents
Foreman provides an innovative framework for managing a tiered team of AI coding agents operating under hard budgets and gates, utilizing the power of opencode. This system is structured around a director, who writes comprehensive tickets, which are then executed by a skilled workforce stratified into different roles:

director ─▶ lead (premium: plan · review · gates)
              ├─▶ coder   (standard: implement)
              ├─▶ tester  (standard: tests)
              ├─▶ drone   (economy: reports, chores)
              └─▶ librarian (economy: retrieval)

Key Features

• Structured Ticketing System: Utilize a robust model that focuses on tickets rather than fleeting prompts, allowing for detailed planning and execution.
• Independent Verification: Ensures that the worker's reports are verified by the system, promoting accountability.
• Budget Constraints: The engine enforces budgetary limitations across various metrics, ensuring efficient resource allocation.

How It Works

Foreman acts as a middleman between the manager (Claude/you) and the AI workers, managing the flow from ticket creation through task execution:

   MANAGER (Claude/you)            FOREMAN                     WORKER (opencode, headless)
   ─────────────────                ───────                     ──────────────────────────
   writes ticket  ─────────────▶  run <id>  ──────────────▶  reads PROTOCOL + ticket
                                  streams JSONL to disk  ◀──  edits, runs, tests
   tails digest   ◀─────────────  digests events
   reads REPORT   ◀─────────────  report <id>  ◀───────────  writes REPORT.md, stops
   runs gate      ─────────────▶  verify <id>   (runs gates itself)
   writes feedback ────────────▶  run <id> --continue  ───▶  SAME session
   commits when verified

Command Line Interface

A simple command line interface enables seamless interaction with the system:

foreman ticket hello --title "Add a hello test"
foreman run T001 --verify
foreman report T001      # Check worker's claims
foreman tail T001        # Live digest of worker activity

Real-Time dashboard

A live dashboard is available to monitor the status of tasks and worker performance:

foreman               # display live status of tasks and workers
foreman ui --once      # one-time snapshot for CI or screenshots

This project boasts zero dependencies and is designed for Node ≥22. It's particularly useful for teams looking to harness AI for coding tasks under stringent requirements. Explore the detailed design documentation and review the example ticket to fully leverage Foreman in your projects.

For further insights, visit the official site at GitHub Page for Foreman and watch the demo showcasing its capabilities.