Multi-model orchestration · zero deps · Node ≥22

Your decision-making friend for heavy workloads.

Foreman is the pipe between you and a tiered workforce. You write tickets — a lead on a premium model judges the brief and writes gates, coders on standard implement under budgets, drones on economy write reports. The engine routes, enforces, and shows you everything.

npm i -g @mastaan66/foreman foreman init && foreman ticket hello

Quick start → Releases

director → lead (premium) coder/tester (standard) drone (economy)

foreman — 45s demo — macOS • Catppuccin Macchiato

vhs docs/demo.tape → docs/demo.gif · every command in one take

How to use — 30 seconds to first verified ticket

01 — Install & check

npm i -g @mastaan66/foreman
foreman doctor
# ✓ Node 22, opencode, workspace

02 — Write a ticket

foreman init --name myapp
foreman ticket auth --title "Add JWT auth"
$EDITOR .foreman/tickets/T001-auth.md
# Goal, Requirements, verify gates

→ See exemplary ticket

03 — Run & verify

foreman run T001 --verify
foreman tail T001
foreman report T001
foreman cost --by tier

Worker's word is never the gate — foreman runs verify itself.

Decision-heavy day? foreman decide "pg vs mongo?" --options "pg,mongo" --criteria "consistency,scale,cost" asks the lead for a matrix. foreman plan "build billing" breaks a vague goal into tickets. foreman companion --watch nudges you every 30s. foreman prioritize ranks what's ready.

Hierarchy management — who does what, and why

One interface, deep implementation. The expensive model never implements — it judges. Volume goes down-tier. Every hand-off is a capped brief, not a log.

ORG — foreman agents

AGENT      ROLE       TIER      MODEL
lead       lead       premium   minimax-m3       → director
coder      coder      standard  muse-spark-1.2   → lead
tester     tester     standard  muse-spark-1.2   → lead
drone      drone      economy   hy3-free         → lead
librarian  librarian  economy   hy3-free         → lead

routing[implement]=coder, routing[plan]=lead, routing[report]=drone. assignee in ticket overrides.

PIPELINE — foreman status / ui

● T001 scaffold ──┬─▶● T002 api ──┬─▶ ◐ T003 auth

queued ○ running ◐ review ◔ verified ● blocked ⊘

foreman ui → 1 STREAM 2 ORG 3 TASKS 4 COST

Escalation ladder: attempt 1 → fresh retry, 2 → lead review (FEEDBACK.md), 3 → blocked.

Memory management — budgets, caps, and checkpoint briefs

No session grows without limit. The engine, not the model, decides when enough is enough.

TIERS — .foreman/foreman.json

{
  "tiers": {
    "premium":  { "model":"minimax-m3", "ctxCap":90000, "ctxKill":180000, "maxOut":12000 },
    "standard": { "model":"muse-spark-1.2", "ctxCap":60000, "ctxKill":140000, "maxOut":30000 },
    "economy":  { "model":"hy3-free",     "ctxCap":40000, "ctxKill":90000,  "maxOut":8000 }
  }
}

ctxCap = continuation gate (never --continue past it). ctxKill = hard mid-run ceiling (≈2×).

BUDGET — lib.mjs:checkBudget()

// one deep seam, pure, testable
checkBudget(run, budget, tier) → {over, warn, usd}
// over: steps/outTokens/ctxKill/usd crossed → SIGTERM
// warn: ctx > ctxCap → finish but never resume, next run = fresh + brief

budget: {steps:60, outTokens:20k} ∩ tier.maxOut
foreman cost --by tier  # spend, stall rate per model

Checkpoint brief (6k cap): ticket + git diff + REPORT.md + gate tail — deterministic, no LLM.

Ticket example — the document that survives the run

A ticket is not a prompt. It's a brief the manager refines between runs, with verify commands that can FAIL on each criterion.

docs/example-ticket.md — JWT auth Open →

---
id: T001
title: Add JWT auth to the API
kind: implement
verify:
  - test -f src/auth/jwt.ts
  - node --test src/auth/jwt.test.ts | grep -E '^# pass ([3-9]|[1-9][0-9]+)$'
budget: {steps:60, outTokens:20000}
---
# Add JWT auth...
## Goal — POST /auth/login → {token}, GET /auth/me → user
## Requirements — 1. jwt.ts sign/verify 2. middleware.ts 3. wire server.ts
## Acceptance — 5 criteria, each verifiable
## Out of scope — no refresh, no OAuth

Packages — npm vs GitHub Packages

npmjs — primary

npm i -g @mastaan66/foreman
npx @mastaan66/foreman --version
# https://www.npmjs.com/package/@mastaan66/foreman

Scoped @mastaan66/foreman is auto-allowed (your username). Unscoped foreman is taken (strongloop/node-foreman).

GitHub Packages — also npm, via GitHub registry

# .npmrc for GitHub Packages
@mastaan66:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

npm publish --registry https://npm.pkg.github.com
# https://github.com/mastaan66/foreman/packages

Same tarball, different registry. Use npmjs for public discoverability, GitHub Packages for org-private or provenance.

All platforms & CLIs — it just works

Platforms

✓ macOS (Intel/ARM) — brew + npm
✓ Linux (x64/ARM) — npm, npx
✓ Windows — bin/foreman.cmd + bin/foreman.ps1
✓ Node ≥22, zero deps, pure ESM

CLIs

✓ opencode (substrate) — opencode --version
✓ claude, codex, gemini — via foreman ask
✓ Any shell — bash, zsh, fish, pwsh
✓ CI — foreman verify in GitHub Actions

Install

npm i -g @mastaan66/foreman
# or
npx @mastaan66/foreman doctor
# or from source
git clone https://github.com/mastaan66/foreman
./bin/foreman --version  # sh
.\bin\foreman.cmd --version  # cmd
pwsh bin/foreman.ps1 --version