Skip to content
Back to search

foreman

A Boris-style agentic orchestrator TUI that supervises headless Claude Code agents through a gated software-delivery pipeline — pointed at any repository.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/visionforge-ou--foreman/badge.svg)](/listings/visionforge-ou--foreman)

HTML

<a href="/listings/visionforge-ou--foreman"><img src="/api/listings/visionforge-ou--foreman/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 1. Install (exposes a single `foreman` command)
pipx install .            # or:  uv tool install .

# 2. Point it at any repo
cd /path/to/your/repo
foreman init              # scaffolds .foreman/ and installs the foreman-* skills
                          #   into .claude/skills/

# 3. See the whole thing work end-to-end with NO tokens spent
foreman demo              # runs the full pipeline against a throwaway sample repo
                          #   using a mocked agent backend (canned stream-json)

# 4. Launch the TUI for real work
foreman                   # (same as `foreman tui`)
foreman --demo            # launch the TUI against a throwaway sample repo

<details> <summary><b>Other CLI commands</b></summary>

foreman status            # show vendored-skill + agent status + features for the repo
foreman init --force      # re-create config and reinstall the foreman-* skills/agents
foreman build             # resume/continue the autonomous build of a feature
foreman retro             # cluster recurring failures → gated skill/prompt patch drafts
foreman bench             # replay the eval set; report success-rate/cost/turn deltas
foreman --version

</details>

Requirements

- Python 3.11+ - The `claude` CLI installed and authenticated (`claude --version`) - `git` - Linux / WSL2 (developed and tested on Ubuntu under WSL2)

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 524 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # Foreman
  3. **A Boris-style agentic orchestrator TUI that supervises headless [Claude Code](https://claude.com/claude-code) agents through a _gated_ software-delivery pipeline — pointed at any repository.**
  4. `plan → ADR/PRD → issues → TDD build → e2e`
  5. [![CI](https://github.com/VisionForge-OU/foreman/actions/workflows/ci.yml/badge.svg)](https://github.com/VisionForge-OU/foreman/actions/workflows/ci.yml)
  6. [![Coverage](https://codecov.io/gh/VisionForge-OU/foreman/branch/main/graph/badge.svg)](https://codecov.io/gh/VisionForge-OU/foreman)
  7. [![PyPI version](https://img.shields.io/pypi/v/foreman-orchestrator.svg)](https://pypi.org/project/foreman-orchestrator/)
  8. [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/foreman-orchestrator.svg)](https://pypi.org/project/foreman-orchestrator/)
  9. [![PyPI - Downloads](https://img.shields.io/pypi/dm/foreman-orchestrator.svg)](https://pypi.org/project/foreman-orchestrator/)
  10. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
  11. [![TUI: Textual](https://img.shields.io/badge/TUI-Textual-5a3fd6.svg)](https://textual.textualize.io/)
  12. [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)
  13. [Why Foreman?](#why-foreman) · [Demo](#demo) · [Quickstart](#5-minute-quickstart) · [Guide](#guide--driving-the-tui) · [How it works](#how-it-works) · [Roadmap](#roadmap) · [Contributing](#contributing)
  14. </div>
  15. > _"I don't prompt Claude anymore; I have loops that prompt Claude."_
  16. Foreman spawns the locally-installed `claude` CLI in headless stream-json mode,
  17. parses its event stream, enforces budgets, and drives your delivery workflow with
  18. a human-in-the-loop review gate for the design phases and guardrailed autonomy for
  19. the build. **All state is human-readable files committed inside the target repo** —
  20. no database; kill it and restart and it fully recovers from disk.
  21. ---
  22. ## Table of contents
  23. - [Why Foreman?](#why-foreman)
  24. - [Demo](#demo)
  25. - [5-minute quickstart](#5-minute-quickstart)
  26. - [Guide — driving the TUI](#guide--driving-the-tui)
  27. - [How it works](#how-it-works)
  28. - [Roadmap](#roadmap)
  29. - [File layout](#file-layout)
  30. - [Configuration](#configuration-foremanconfigyaml)
  31. - [The vendored skills](#the-vendored-skills)
  32. - [Development](#development)
  33. - [Contributing](#contributing)
  34. - [FAQ](#faq)
  35. - [Acknowledgements](#acknowledgements)
  36. - [License](#license)
  37. ---
  38. ## Why Foreman?
  39. Running a coding agent in a `while` loop is easy. Running one you can **trust to
  40. merge** is not. Foreman is the supervisor in between: it keeps a human at the design
  41. gates, then hands the build to agents that are **boxed in by the orchestrator, not
  42. by their own good behaviour**.
  43. - 🚦 **Gated pipeline** — `plan → ADR/PRD → issues → TDD build → e2e`, with human review gates on every design phase and a hash-sealed approval that auto-reverts if a doc changes.
  44. - 🤖 **Real headless agents** — spawns the locally-installed `claude` CLI in stream-json mode, parses its events, and enforces per-run turn/cost/time budgets.
  45. - 💾 **No database** — all state is human-readable files committed inside the target repo. Crash-safe: kill it mid-build and it recovers from disk.
  46. - ⌨️ **Keyboard-driven TUI** — drive the entire workflow from a Textual terminal UI ([full keymap below](#guide--driving-the-tui)).
  47. - 🧰 **Worktree isolation** — parallel workers each run in their own git worktree, footprint-gated by a declared `touches` set so they never collide.
  48. - 🛡️ **Guardrails Foreman enforces (not the agent)** — per-run caps, a daily cost ceiling with a hard stop, and a `PreToolUse` deny hook that blocks workers from writing their own verification.
  49. - 🔁 **Evals flywheel** — every run is outcome-labelled; `foreman retro` clusters failures into gated skill/prompt patches that must pass `foreman bench` before they can land.
  50. ---
  51. ## Demo
  52. ```bash
  53. foreman --demo # launch the full TUI against a throwaway sample repo,
  54. # driven by a mocked agent backend — ZERO tokens spent
  55. ```
  56. `foreman demo` (non-interactive) and `foreman --demo` (the live TUI) run the entire
  57. `plan → … → e2e` pipeline on canned stream-json, so you can explore every gate and
  58. screen before spending a cent.
  59. <!-- Tip: drop a real terminal recording or screenshot here, e.g. an asciinema cast or a docs/demo.gif -->
  60. Dashboard at a glance _(illustrative layout — run `foreman --demo` to see it live)_:
  61. ```
  62. ┌ Foreman ─────────────────────────────────── agentic delivery orchestrator ──┐
  63. │ Features (n) │ daily-plan — phase: building cost: $0.41 ●2 wk │
  64. │ ▸ daily-plan │ Press b to (re)start · w workers · x attention │
  65. │ backlog-aging │ │
  66. │ │ Issue board │
  67. │ Vendored skills │ queued in_progress done merged │
  68. │ ✓ foreman-tdd v4 │ ISS-004 ISS-002 ISS-001 ISS-003 │
  69. │ ✓ foreman-grill… v3 │ ISS-005 │
  70. │ Read-only agents │ │
  71. │ ✓ foreman-evaluator │ [ global activity log … ] │
  72. ├─────────────────────────┴────────────────────────────────────────────────┤
  73. │ ⠹ ACTIVE ISS-002 worker · turn 12/30 · $0.18 · running pytest │
  74. │ n New p Plan g Grill s Slice c Confirm b Build v Review w Workers … │
  75. └────────────────────────────────────────────────────────────────────────────┘
  76. ```
  77. ---
  78. ## 5-minute quickstart
  79. ```bash
  80. # 1. Install (exposes a single `foreman` command)
  81. pipx install . # or: uv tool install .
  82. # 2. Point it at any repo
  83. cd /path/to/your/repo
  84. foreman init # scaffolds .foreman/ and installs the foreman-* skills
  85. # into .claude/skills/
  86. # 3. See the whole thing work end-to-end with NO tokens spent
  87. foreman demo # runs the full pipeline against a throwaway sample repo
  88. # using a mocked agent backend (canned stream-json)
  89. # 4. Launch the TUI for real work
  90. foreman # (same as `foreman tui`)
  91. foreman --demo # launch the TUI against a throwaway sample repo
  92. ```
  93. <details>
  94. <summary><b>Other CLI commands</b></summary>
  95. ```bash
  96. foreman status # show vendored-skill + agent status + features for the repo
  97. foreman init --force # re-create config and reinstall the foreman-* skills/agents
  98. foreman build # resume/continue the autonomous build of a feature
  99. foreman retro # cluster recurring failures → gated skill/prompt patch drafts
  100. foreman bench # replay the eval set; report success-rate/cost/turn deltas
  101. foreman --version
  102. ```
  103. </details>
  104. ### Requirements
  105. - Python 3.11+
  106. - The `claude` CLI installed and authenticated (`claude --version`)
  107. - `git`
  108. - Linux / WSL2 (developed and tested on Ubuntu under WSL2)
  109. ---
  110. ## Guide — driving the TUI
  111. Foreman is **fully keyboard-driven**. Launch it with `foreman` (or `foreman --demo`
  112. to try it with a mocked backend and zero token spend). Every screen also shows its
  113. keys in the footer; the reference below is the complete map.
  114. <details>
  115. <summary><b>📖 Click to expand the full TUI guide</b></summary>
  116. ### The shape of a session
  117. You spend almost all of your time on the **Dashboard**. It lists your features on
  118. the left, shows the selected feature's current phase + cost + a live issue board on
  119. the right, and tells you the single next key to press in its hint line. The other
  120. screens (Review, Workers, Attention, Metrics, Retro, Settings) are pushed on top
  121. with a single key and dismissed with <kbd>Esc</kbd>.
  122. A feature moves through phases; the Dashboard hint tells you what to press at each:
  123. | Phase | Hint shown | You press |
  124. |-------|------------|-----------|
  125. | `request` | Run the planner | <kbd>p</kbd> |
  126. | `plan_review` | Review the plan (a=approve, r=request changes) | <kbd>v</kbd> |
  127. | `grilling` | Run the grill (ADR + PRD) | <kbd>g</kbd> |
  128. | `doc_review` | Review ADR / PRD | <kbd>v</kbd> |
  129. | `slicing` | Run the slicer | <kbd>s</kbd> |
  130. | `queue_review` | Confirm the queue, then build | <kbd>c</kbd> then <kbd>b</kbd> |
  131. | `building` | (Re)start the build · workers · attention | <kbd>b</kbd> · <kbd>w</kbd> · <kbd>x</kbd> |
  132. | `done` | Feature complete 🎉 — see `report.md` | — |
  133. ### Dashboard — global keys
  134. The home screen. Select a feature with the arrow keys, then act on it.
  135. | Key | Action |
  136. |-----|--------|
  137. | <kbd>↑</kbd> / <kbd>↓</kbd> | Select a feature in the list |
  138. | <kbd>n</kbd> | **New** feature (opens the create modal) |
  139. | <kbd>p</kbd> | Run the **planner** → `plan.md` |
  140. | <kbd>g</kbd> | Run the **grill** → ADR + PRD |
  141. | <kbd>s</kbd> | Run the **slicer** → issue files |
  142. | <kbd>c</kbd> | **Confirm** the queue (final gate before build) |
  143. | <kbd>b</kbd> | Start / resume the **build** loop |
  144. | <kbd>v</kbd> | Open the **Review** screen (plan / ADR / PRD) |
  145. | <kbd>w</kbd> | Open the **Worker** view (live agent logs) |
  146. | <kbd>x</kbd> | Open the **Attention** queue (escalations) |
  147. | <kbd>m</kbd> | Open the **Metrics** pane |
  148. | <kbd>t</kbd> | Open the **Retro** patch gate |
  149. | <kbd>,</kbd> | Open **Settings** (read-only config view) |
  150. | <kbd>q</kbd> | Quit |
  151. ### New-feature modal (<kbd>n</kbd>)
  152. A small form: type a **title**, <kbd>Tab</kbd> into the **request** box (description
  153. + product requirements), then click **Create** (or **Cancel**). Submitting writes
  154. `request.md` and selects the new feature.
  155. ### Review screen (<kbd>v</kbd>) — the design gate
  156. Where you approve or push back on the `plan`, `adr`, and `prd` drafts. The top of
  157. the screen surfaces the grill's **"decisions made on your behalf"** digest and any
  158. **open questions**; the body renders the document; a comment box at the bottom is
  159. used as your **answers** to those open questions.
  160. | Key | Action |
  161. |-----|--------|
  162. | <kbd>a</kbd> | **Approve** the current doc |
  163. | <kbd>r</kbd> | **Request changes** — uses the comment box as answers / change requests |
  164. | <kbd>Tab</kbd> | Cycle to the next doc (`plan` → `adr` → `prd`) |
  165. | <kbd>Esc</kbd> | Back to the dashboard |
  166. - A draft with **open questions cannot be approved** — answer them via a
  167. request-changes comment first, then re-run the grill/planner to revise.
  168. - **Approval is hash-sealed**: editing an approved doc's body auto-invalidates its
  169. approval (a SHA-256 of the body is re-checked on every load).
  170. - Requesting changes on a PRD **amendment** can spin off concrete fix issues — the
  171. notification tells you how many and to press <kbd>b</kbd> to build them.
  172. ### Worker view (<kbd>w</kbd>) — watch the build
  173. A sidebar of running workers (`id [status] $cost turns`) and a live, scrolling log
  174. of the selected worker's raw agent output, with a budget bar on top.
  175. | Key | Action |
  176. |-----|--------|
  177. | <kbd>↑</kbd> / <kbd>↓</kbd> | Select a worker (log follows the highlight) |
  178. | <kbd>Tab</kbd> | Jump to the next worker |
  179. | <kbd>k</kbd> | **Kill** the selected worker |
  180. | <kbd>Esc</kbd> | Back to the dashboard |
  181. ### Attention queue (<kbd>x</kbd>) — rescue escalations
  182. When a worker escalates (uncertainty, repeated evaluator disagreement, …) it lands
  183. here and the terminal bells. Select an escalation, read its detail, type your answer,
  184. and resume the worker — which picks up your answer in a fresh context.
  185. | Key | Action |
  186. |-----|--------|
  187. | <kbd>↑</kbd> / <kbd>↓</kbd> | Select an escalation |
  188. | <kbd>Ctrl</kbd>+<kbd>N</kbd> | Next escalation |
  189. | <kbd>Enter</kbd> | Newline **inside** the answer box (does _not_ submit) |
  190. | <kbd>Ctrl</kbd>+<kbd>S</kbd> | **Submit your answer & resume** the worker |
  191. | <kbd>Esc</kbd> | Back to the dashboard |
  192. > Submit is <kbd>Ctrl</kbd>+<kbd>S</kbd>, not <kbd>Enter</kbd>, so <kbd>Enter</kbd> stays free for
  193. > multi-line answers. The submit binding fires even while the answer box has focus.
  194. ### Metrics pane (<kbd>m</kbd>)
  195. Success rate, mean retries/issue, cost/issue, an escalation histogram, and trends
  196. across runs for the selected feature. <kbd>Esc</kbd> returns to the dashboard.
  197. ### Retro patch gate (<kbd>t</kbd>) — the human side of the flywheel
  198. Lists the gated skill/prompt patch proposals in `.foreman/retro/`. Select one to see
  199. its diff + rationale + attached bench delta. **A patch lands only with both your
  200. approval and a `foreman bench` report** — the gate is enforced here.
  201. | Key | Action |
  202. |-----|--------|
  203. | <kbd>↑</kbd> / <kbd>↓</kbd> | Select a proposal |
  204. | <kbd>Tab</kbd> | Next proposal |
  205. | <kbd>a</kbd> | **Approve** the proposal |
  206. | <kbd>r</kbd> | **Reject** the proposal |
  207. | <kbd>l</kbd> | **Land** it (requires approval **and** a bench report) |
  208. | <kbd>Esc</kbd> | Back to the dashboard |
  209. > Generating proposals (`foreman retro`) and benchmarking them (`foreman bench`) are
  210. > long, token-spending agent runs and stay on the CLI; only the review/approve/
  211. > reject/land gate lives in the TUI.
  212. ### Settings (<kbd>,</kbd>)
  213. A read-only render of the active configuration. Edit `.foreman/config.yaml`
  214. directly — it is validated on load. <kbd>Esc</kbd> returns to the dashboard.
  215. ### Cheat-sheet
  216. | Screen | Keys |
  217. |--------|------|
  218. | **Dashboard** | <kbd>n</kbd> new · <kbd>p</kbd> plan · <kbd>g</kbd> grill · <kbd>s</kbd> slice · <kbd>c</kbd> confirm · <kbd>b</kbd> build · <kbd>v</kbd> review · <kbd>w</kbd> workers · <kbd>x</kbd> attention · <kbd>m</kbd> metrics · <kbd>t</kbd> retro · <kbd>,</kbd> settings · <kbd>q</kbd> quit |
  219. | **Review** | <kbd>a</kbd> approve · <kbd>r</kbd> request changes · <kbd>Tab</kbd> next doc · <kbd>Esc</kbd> back |
  220. | **Workers** | <kbd>k</kbd> kill · <kbd>Tab</kbd> next · <kbd>↑</kbd>/<kbd>↓</kbd> select · <kbd>Esc</kbd> back |
  221. | **Attention** | <kbd>Ctrl</kbd>+<kbd>S</kbd> answer & resume · <kbd>Ctrl</kbd>+<kbd>N</kbd> next · <kbd>Esc</kbd> back |
  222. | **Retro** | <kbd>a</kbd> approve · <kbd>r</kbd> reject · <kbd>l</kbd> land · <kbd>Tab</kbd> next · <kbd>Esc</kbd> back |
  223. | **Metrics / Settings** | <kbd>Esc</kbd> back |
  224. </details>
  225. ---
  226. ## How it works
  227. ### Phase A — the gated pipeline (human in the loop)
  228. 1. **Create a feature** in the TUI (title + description + product requirements) →
  229. `request.md`.
  230. 2. **Plan** — a high-reasoning planner agent (`--effort` from config) turns the
  231. request into a deep implementation plan → `plan.md` (status `in_review`).
  232. 3. **Grill** — the vendored `foreman-grill-docs` skill challenges the *approved*
  233. plan against the codebase and domain model and writes an **ADR** and a **PRD**.
  234. Because there is no live user, it self-answers everything it can and surfaces
  235. the rest under an **"Open questions for reviewer"** block.
  236. 4. **Review** — you review each draft in the TUI: **a** approve, **r** request
  237. changes (your comments answer the open questions), **tab** to switch docs.
  238. A draft with open questions **cannot** be approved. Editing an approved doc
  239. automatically invalidates its approval (a SHA-256 of the body is checked on
  240. every load).
  241. 5. **Slice** — once the ADR and PRD are both approved, `foreman-to-issues` breaks
  242. the PRD into small, dependency-ordered, vertically-sliced issue files with PRD
  243. traceability.
  244. 6. **Confirm the queue** — the final gate. The queue view shows each issue's
  245. runnable `acceptance_check`, `touches`, `prd_refs`, dependencies, and conflict
  246. graph. Nothing downstream runs until you confirm.
  247. ### Phase B — the autonomous build loop ("Boris loop")
  248. A one-time **initializer** writes `init.sh` + `feature-state.md`. Then, for each
  249. ready issue (queued + dependencies done) whose declared **`touches`** footprint
  250. doesn't overlap a running one, up to `max_parallel` workers run concurrently, each
  251. in its **own git worktree**:
  252. - A `foreman-tdd` worker implements the slice (red-green-refactor), runs tests via
  253. the installed **`foreman-test`** wrapper, saves **evidence** under
  254. `runs/<id>/evidence/`, updates **`progress.md`**, and emits a `FOREMAN-SUMMARY`.
  255. - The **merge gate** (Foreman runs it itself, never trusting the agent) requires:
  256. the worker's **evidence** is real, the issue's runnable **`acceptance_check`**
  257. passes, the full **test/lint/typecheck** pass, and the **regression ratchet** is
  258. green (no previously-passing test now fails — bounces name the regressed tests).
  259. - A read-only **evaluator** (a separate `--agent`, fresh context) then grades the
  260. diff on a 1–5 rubric; objections **bounce to a fresh worker** (with a distilled
  261. failure report), uncertainty/repeated disagreement **escalate**. Two further
  262. opt-in read-only graders — **code-review** and **security-review** — can run on
  263. the committed slice and bounce/escalate on a blocking verdict.
  264. - Pass → Foreman flips the issue's entry in `verification.json` (workers are
  265. **hook-blocked** from writing it), commits + merges. After every N merges a
  266. **janitor** pass (dedup / conventions / docs) runs through the same gate.
  267. - When all issues land, an **e2e** agent runs, then a read-only **auditor** walks
  268. the PRD requirement-by-requirement; a divergence drafts a **PRD amendment** that
  269. re-enters the hash-sealed review gate.
  270. ### Guardrails (enforced by Foreman, not the agent)
  271. Per-run `max_turns`, `max_cost_usd`, `timeout_min`; per-issue `max_retries`;
  272. global `max_parallel` and a daily cost ceiling with a hard stop. Workers can't
  273. write `verification.json` / issue files (a `PreToolUse` deny hook, proven to hold
  274. under `acceptEdits`); crash-safe per-issue **locks** with heartbeat reclaim prevent
  275. double-claiming. Every enforcement event is logged and surfaced.
  276. ### The evals flywheel
  277. Every run is **outcome-labelled** (`success_first_try | success_after_retry(n) |
  278. evaluator_bounce | escalated(reason) | …`); the TUI metrics pane (press **m**)
  279. renders success rate, mean retries/issue, cost/issue, and an escalation histogram.
  280. `foreman retro` clusters recurring failures and drafts patches to the vendored
  281. skills / rubric / prompts — drafts that pass the **same hash-sealed review gate** as
  282. a PRD; **no patch lands without a `foreman bench` report** showing it doesn't
  283. regress the eval set.
  284. ---
  285. ## Roadmap
  286. Foreman ships **Phase 1 + Phase 2** today. Phase 3 is planned, not yet implemented.
  287. - ✅ **Phase 1 — the gated pipeline.** `plan → ADR/PRD → issues → TDD → e2e`,
  288. worktree-isolated parallel build, Foreman-owned merge gate + regression ratchet,
  289. read-only evaluator/auditor, crash-safe file state, and the full Textual TUI.
  290. - ✅ **Phase 2 — the evals flywheel.** Run outcome taxonomy, the metrics pane,
  291. `foreman retro` / `foreman bench`, and hash-sealed skill/prompt patch landing.
  292. _(0.6.0 adds opt-in code-review & security-review gate agents — see [`CHANGELOG.md`](./CHANGELOG.md).)_
  293. - 🚧 **Phase 3 — hardening (planned).** Training-data exporter, worker sandboxing,
  294. CLI-contract probes, and a chaos suite.
  295. ---
  296. ## File layout
  297. <details>
  298. <summary>What <code>foreman init</code> creates inside your repo</summary>
  299. ```
  300. .foreman/
  301. schema_version # on-disk schema version (2); Phase-1 trees migrate additively
  302. config.yaml daily_cost.json SKILL_CHANGELOG.md
  303. retro/ # gated skill/prompt patch proposals + bench reports
  304. features/<slug>/
  305. request.md plan.md adr.md prd.md report.md
  306. feature-state.md init.sh # initializer outputs (WS3)
  307. verification.json baseline.json # Foreman-owned structural-done + ratchet baseline
  308. reviews/ plan-v1-review.md prd-v1-body.md ...
  309. issues/ ISS-001.md ISS-001.check/ ... # each issue ships a runnable acceptance check
  310. escalations/ISS-001.md ...
  311. runs/<timestamp>-ISS-001/{transcript.jsonl, summary.md, usage.json,
  312. progress.md, verdict.json, evidence/}
  313. .claude/skills/ foreman-grill-docs/ foreman-to-prd/ foreman-to-issues/ foreman-tdd/
  314. .claude/agents/ foreman-evaluator.md foreman-auditor.md foreman-retro.md
  315. ```
  316. Document statuses: `drafting → in_review → changes_requested → approved`
  317. (approval auto-reverts if the body changes). Issue statuses:
  318. `queued | in_progress | tests_failing | awaiting_evaluation | needs_human | done | merged`.
  319. </details>
  320. ## Configuration (`.foreman/config.yaml`)
  321. See `config.sample.yaml` for the annotated template. Key fields: `model_planner`,
  322. `model_worker`, `model_evaluator`, `model_auditor`, `effort`, `required_skills`,
  323. `required_agents`, `commands` (test/lint/typecheck/e2e), `git`, `limits`,
  324. `run_budget`, `evaluator_*`, `auditor_enabled`, `notify_command`, `retry_strategy`
  325. (`fresh`|`resume`), `janitor_enabled`/`janitor_every`/`janitor_kinds`,
  326. `bench_eval_set`/`bench_cost_ceiling_usd`, `e2e_enabled`, `permission_mode`.
  327. ## The vendored skills
  328. Foreman ships forked, namespaced copies of skills from
  329. [mattpocock/skills](https://github.com/mattpocock/skills),
  330. [obra/superpowers](https://github.com/obra/superpowers), and Anthropic — e.g.
  331. `foreman-grill-docs`, `foreman-to-prd`, `foreman-to-issues`, `foreman-tdd`,
  332. `foreman-debug`, `foreman-verify` — rewritten for headless, non-interactive
  333. orchestration with a local (non-GitHub) issue layer. The pipeline references
  334. **only** these names, so it never resolves to a user-installed upstream copy; your
  335. other installed skills remain available to workers. See [`NOTICE`](./NOTICE) for
  336. attribution and [`DECISIONS.md`](./DECISIONS.md) §8 for the per-skill changelog.
  337. ## Development
  338. ```bash
  339. uv venv && uv pip install -e ".[dev]"
  340. pytest -q # full suite (uses mocked agents + real git/pytest)
  341. ```
  342. The whole system is exercised offline via a mocked agent backend
  343. (`foreman demo` / the test suite) so the state machine and TUI are testable without
  344. burning tokens. The single seam is `AgentBackend` (`backend.py`): `ClaudeBackend`
  345. spawns the real CLI; `MockBackend` replays canned stream-json.
  346. Design rationale lives in [`DECISIONS.md`](./DECISIONS.md); release history in
  347. [`CHANGELOG.md`](./CHANGELOG.md).
  348. ## Contributing
  349. Contributions are welcome. Foreman is developed in the open at
  350. [`n1arash/foreman`](https://github.com/n1arash/foreman).
  351. 1. **Open an issue** for a bug or proposal:
  352. [github.com/n1arash/foreman/issues](https://github.com/n1arash/foreman/issues).
  353. 2. **Set up the dev env** (see [Development](#development)) and branch off `main`.
  354. 3. **Keep the suite green** — `pytest -q` runs fully offline on the mocked backend,
  355. so no tokens are spent in CI or locally. Add tests for new behaviour.
  356. 4. **Follow the conventions** — state lives in human-readable files; the only seam
  357. to the real agent is `AgentBackend`; gates are enforced by Foreman, never trusted
  358. to the agent. New cross-cutting decisions get an entry in [`DECISIONS.md`](./DECISIONS.md).
  359. 5. **Open a PR** against `main` with a clear description and a `CHANGELOG.md` note.
  360. ## FAQ
  361. <details>
  362. <summary><b>Does trying it cost tokens?</b></summary>
  363. No. `foreman demo` and `foreman --demo` run the entire pipeline on a **mocked**
  364. agent backend (canned stream-json), so you can explore every gate and screen with
  365. zero token spend. Only real feature work against your repo spawns the `claude` CLI.
  366. </details>
  367. <details>
  368. <summary><b>Do I need a database or a server?</b></summary>
  369. No. Every bit of state is a human-readable file committed inside your target repo
  370. under `.foreman/`. There is no daemon and no database — kill Foreman mid-build and
  371. restart, and it recovers from disk.
  372. </details>
  373. <details>
  374. <summary><b>Which models does it use?</b></summary>
  375. Whatever you configure per role in `.foreman/config.yaml` — `model_planner`,
  376. `model_worker`, `model_evaluator`, `model_auditor` — plus an `effort` knob for the
  377. planner. Different stages can run different models.
  378. </details>
  379. <details>
  380. <summary><b>Is my repo safe from a runaway agent?</b></summary>
  381. Workers run in **isolated git worktrees** under per-run turn/cost/time caps and a
  382. daily cost ceiling with a hard stop, and are **hook-blocked** from writing their own
  383. verification. For unsupervised runs, use the strictest `permission_mode` (and ideally
  384. a container). Foreman never trusts the agent's self-report — it re-runs the gates.
  385. </details>
  386. <details>
  387. <summary><b>Does it work outside Linux?</b></summary>
  388. It's developed and tested on Linux / WSL2 (Ubuntu). It should run anywhere the
  389. `claude` CLI, `git`, and Python 3.11+ are available, but Linux/WSL2 is the tested path.
  390. </details>
  391. ## Star History
  392. [![Star History Chart](https://api.star-history.com/chart?repos=VisionForge-OU/foreman&type=date&legend=top-left)](https://www.star-history.com/?repos=VisionForge-OU%2Fforeman&type=date&legend=top-left)
  393. ## Acknowledgements
  394. - Built on [Textual](https://textual.textualize.io/) for the TUI and the
  395. [Claude Code](https://claude.com/claude-code) CLI for the agents.
  396. - Vendored, headless-rewritten skills are forked from
  397. [mattpocock/skills](https://github.com/mattpocock/skills) (MIT),
  398. [obra/superpowers](https://github.com/obra/superpowers) (MIT), and Anthropic's
  399. skills — see [`NOTICE`](./NOTICE) for full attribution.
  400. ## License
  401. [MIT](./LICENSE). Portions derived from [mattpocock/skills](https://github.com/mattpocock/skills)
  402. and others (MIT) — see [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE) for attribution.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.