claudeers.
// Claude Skills

foreman

Turn an agreed plan into milestones, stages and gates, built by delegated coding agents and reviewed by you. Works in Claude Code and any other agent harness.

// Claude Skills[ cli ][ api ][ web ][ mobile ][ claude ]#claude#agent-skills#ai-agents#claude-code#codex#coding-agents#opencode#orchestration#skills◷ MIT$open-sourceupdated 19 days ago
Actively maintained
100/100
last commit 15 days ago
last release 13 days ago
releases 2
open issues 0

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up foreman (claude-skill project) into my current project.
Found on https://claudeers.com/foreman-4
Repo: https://github.com/MarioMagdy/foreman
Homepage/docs: —
Detected install method: claude-skill → # copy this skill into .claude/skills/foreman/
Category: skills. Platforms: cli, api, web, mobile.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
active; community-verified: false. Confirm the source before running anything.
// or install directly (claude-skill)
# copy the skill dir into your project:
# .claude/skills/foreman/   (or ~/.claude/skills/foreman/ for all projects)
// or clone
git clone https://github.com/MarioMagdy/foreman

// compatibility

Platformscli, api, web, mobile
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageHTML

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

foreman

An agent skill for running an agreed plan through delegated AI agents while you stay in charge.

The foreman splits the plan into milestones and stages, routes each stage to the right worker, checks every piece itself, and hands you something you can try: a test plan, and at each milestone a review packet. It never writes the product code, and nothing reaches your base branch without your word.

Written for Claude Code; it also runs under codex, opencode and Gemini CLIs with the fallbacks below.

See it first

git clone https://github.com/MarioMagdy/foreman.git && cd foreman
python -m pip install pyyaml    # for the same python you run the scripts with
python track-mode/live.py serve --coord track-mode/sample-run/_coord

Open the printed http://127.0.0.1:8765/. That is the live tracker drawn from a recorded sample run: milestones, the stage map, managers and their agents, open questions. Open dashboard/packet.html in a browser for the review packet with its built-in sample.

The live tracker: what needs you, what is running, each milestone

The stage map: builds, AI gates and your review gate per milestone

Install

From the clone (Python 3.10+):

python install.py                      # Claude Code -> ~/.claude/skills/foreman
python install.py --harness agents     # codex, opencode -> ~/.agents/skills/foreman
python install.py --harness all        # both
python install.py --dest <dir>         # any other harness: the folder that will hold SKILL.md

It copies only the files a session uses (not tests or the sample run), never touches your LOCAL.md, and re-running it updates the install. Start a new session afterwards.

It triggers on requests like "take this plan and build it", "foreman init", "orchestrate this", "run it overnight", "where is the work?" or "give me a test plan".

Optional: copy LOCAL.md.example to LOCAL.md beside SKILL.md and put your own worker routing, accounts (env var names only) and house rules there. The skill reads it first. It is gitignored.

Workers inherit your environment. Every worker Foreman starts gets the environment variables of the shell you started from, API keys included. Start your session from a shell that holds only the keys the workers should have; delegation/prepare_worktree.py also lists the secret-looking variable names to blank per worker.

Requirements

ForYou need
The skill itselfan agent harness that can start subagents or other agent CLIs; git
Stage and milestone PRsthe GitHub CLI (gh), signed in
evals/plan_check.py, track-mode/live.pyPython 3.9+ (tested on 3.12) and PyYAML
track-mode/launcher.py (worker pool for long runs)Windows, and the opencode CLI signed in. It drives opencode workers only.
The phone-friendly tracker and answering questions on the pageClaude Code with claude.ai Artifacts (dashboard/SCHEMA.md)

How a run goes

PLAN ──► MILESTONE 1 ──► MILESTONE 2 ──► ...        each milestone = one PR you review, stacked
           ├── stage M1-S1                           each stage = one PR into its milestone
           ├── stage M1-S2
           ├── gate  M1-G1  (AI review)
           └── gate  M1-G2  (your review)
  1. foreman init. It reads your plan, does an architect pass (critical path, parallel tracks, who builds what), writes a run sheet from defaults.yaml, _coord/plan.yaml, PLAN.md and one M<n>_PLAN.md per milestone, asks its setup questions in one batch, and stops until you say yes. Say "init and start" to skip only that wait.
  2. Milestones are working slices: each one is a feature you can use end to end, with adds and done_when in your words. Uncertain work goes into an explore milestone off to the side (references/explore.md).
  3. Stage loop. One worker per stage, from a copy-paste brief → the foreman verifies from git and by running things (never from the worker's report) → stage review, findings posted on the PR → a fix round is a new brief carrying the foreman's rulings → once the gate passes, the stage merges into its milestone branch.
  4. Gates. Each milestone ends with an AI gate, then your gate (references/gates.md). At your gate you get a review packet (references/packet.md) and a test plan whose every step is labelled free, paid (~$X) or do-not-run. The foreman runs the whole test plan itself first.
  5. You merge milestones. The foreman never merges a milestone or touches the base branch on its own judgment, and never writes to production without your say-so, every time.

Long runs with several parallel tracks switch to track mode: the session becomes an orchestrator, each track gets a manager, and workers start through the launcher (track-mode/CHARTER.md, track-mode/LAUNCHER.md). Every hand-off is one JSON line in _coord/events/, which is what the live view draws.

One core, one file per harness

SKILL.md holds every rule and names no harness tool. Seven steps depend on the harness: starting a worker or manager, waking when a job hands back, scheduled check-ins, showing you the run, taking your answers, resuming a manager and sending you updates, and naming models. The skill reads one file for those:

FileForHow it does the seven
harness/claude-code.mdClaude Codesubagents, Monitor, scheduled check-ins, the tracker as a claude.ai Artifact you can answer on
harness/generic.mdeverything elseseparate agent CLI runs, polling between steps, live.py serve, answers in chat or questions.md

On other harnesses the run moves only while a session is open. A native file for another harness (say codex) is one more page in harness/ holding the same seven steps; the rules never move out of SKILL.md.

Companion skills (optional)

The foreman uses these when they are installed and does their job by hand when they are not. They are separate skills, not part of this repo.

SkillUsed forWithout it
subagent-disciplineWriting briefs and grading each worker afterwardsBriefs follow SKILL.md; a few lines per worker in the run's reports/
council-judgeMulti-model review for large gatesOne strong reviewer that did not build the stage
verified-prPR mechanicsPlain gh pr create, findings as a PR comment

Files

PathWhat it is
SKILL.mdThe skill: rules, flow, red flags. This is what loads into a session.
harness/How the seven harness-dependent steps work in Claude Code, and everywhere else.
install.pyCopies the run-time files into a harness's skills folder.
defaults.yamlThe run-sheet template.
profiles/default.yamlExample model routing with pre-approved fallbacks; fill in your own.
references/Read on demand: gates and plan shape, explore milestones, the review packet, delegation (worker setup, mailbox, stops, handback).
delegation/prepare_worktree.py (a ready worktree plus the harness hooks per worker), mailbox.py (talk to a running worker, progress, hang check), hook.py (the hook every harness calls).
dashboard/tracker.html (live tracker), packet.html (review packet), SCHEMA.md (data contract and Artifact recipe), seed-example.json.
track-mode/live.py (builds and serves the tracker data), launcher.py (worker pool), CHARTER.md, LAUNCHER.md, usage_split.py (Claude Code usage per session), sample-run/.
evals/plan_check.py (checks a plan.yaml), scenarios.py (scripted gate scenarios), study.py (compare skill versions), rehearsal notes.
LOCAL.md.exampleShape of your private overlay.

Tests

python -m pip install pyyaml pytest   # scenarios.py runs pytest on its fixtures
python track-mode/test_live.py
python track-mode/test_launcher.py     # Windows only
python evals/scenarios.py selftest
python evals/plan_check.py track-mode/sample-run/_coord/plan.yaml
python install.py selftest
python delegation/mailbox.py selftest
python delegation/hook.py selftest
python delegation/prepare_worktree.py selftest

License

MIT, see LICENSE.

// faq

What is foreman?

Turn an agreed plan into milestones, stages and gates, built by delegated coding agents and reviewed by you. Works in Claude Code and any other agent harness.. It is open-source on GitHub.

Is foreman free to use?

foreman is open-source under the MIT license, so it is free to use.

What category does foreman belong to?

foreman is listed under skills in the Claudeers registry of Claude-compatible tools.

3 views
★ 41 stars
unclaimed
updated 19 days ago

// embed badge

foreman on Claudeers
[![Claudeers](https://claudeers.com/api/badge/foreman-4.svg)](https://claudeers.com/foreman-4)

// retro hit counter

foreman hit counter
[![Hits](https://claudeers.com/api/counter/foreman-4.svg)](https://claudeers.com/foreman-4)

// reviews

// guestbook

0/500

// related in Claude Skills

🔓

An agentic skills framework & software development methodology that works.

// skillsobra/⟨Shell⟩★ 314,126◷ MIT[ claude ]
🔓

Public repository for Agent Skills

// skillsanthropics/⟨Python⟩★ 188,182[ claude ]
🔓

AI coding assistant skill (Claude Code, Codex, OpenCode, Cursor, Gemini CLI, and more). Turn any folder of code, SQL schemas, R scripts, shell scripts, docs,…

// skillsGraphify-Labs/⟨Python⟩★ 149,064◷ MIT[ claude ]
🔓

💫 Toolkit to help you get started with Spec-Driven Development

// skillsgithub/⟨Python⟩★ 148,200◷ MIT[ claude ]
→ see how foreman connects across the ecosystem