Skip to main content

foreman-plane

Task governance outside your agent harness — personal-tool grade

PyPI version downloads Protocol Python License

English · 简体中文

One sentence

foreman-plane is a governance plane that runs outside the agent harness. DeepSeek Harness, Claude Code, Codex and any CLI agent are interchangeable execution bodies. What the plane owns is the part a session cannot own: dispatch, dependency gating, objective acceptance and an append-only ledger.

A promise the agent forgot is not a promise. The verdict is derived from files on disk, so it outlives the session that produced it.

It is sized for one person, one machine, one state directory — a personal tool, not an enterprise platform. See Scope.

Execution bodies talk to foreman-plane over MCP/stdio

┌──────────────────┐        ┌──────────────────────┐
│ execution bodies │        │ foreman-plane        │
│ Claude Code      │ ─────▶ │ dispatch             │
│ Codex            │        │ dependency gates     │
│ DeepSeek Harness │ ◀───── │ objective acceptance │
│ any CLI agent    │        │ append-only ledger   │
└──────────────────┘        └──────────────────────┘
  MCP / stdio — JSON-RPC 2.0, one JSON object per line
  • Cross session — the ledger outlives every conversation.
  • Cross instance — several agents share one task graph.
  • Cross day — a task dispatched today can be resumed tomorrow by any body.
  • Zero intrusion — the plane is a plain process, no agent framework has to be patched.

Zero third-party dependencies. Python ≥ 3.10, standard library only.

Why foreman-plane?

Capability What it changes
Two-level dependency gate A card with [depends_on] cannot start until every upstream is terminal, passed and accepted. [needs_api] is the soft level: a missing artefact is reported, the task still runs.
Objective acceptance Pass and fail are computed from the artefact — min_bytes, sha256, contains, exit_code. A task that promises a report but writes no file fails.
No ghost dispatch A card stopped by the gate writes a blocked event and no dispatch event, so the ledger can never show a task that never ran.
Append-only ledger One JSON line per decision. History is never rewritten or deleted, and it can be queried, diffed and audited by something that is not an LLM.
Pluggable execution bodies The plane picks no model and does not care which command runs a card. Swap the command, keep the governance.
Unparsed dependencies are fatal A dependency marker that cannot be parsed refuses the dispatch. It is never silently dropped.

Scope — a personal tool, not an enterprise platform

foreman-plane is deliberately small. It is designed for one person, one machine, one state directory — not for a team, a fleet or a regulated org. Saying this out loud is part of the design: a tool that pretends to be a platform costs you more in configuration than it saves.

What it is

  • A plain process. Start it when you need it, stop it when you are done.
  • One directory of state (FOREMAN_HOME) and one append-only JSONL ledger.
  • A handful of interchangeable CLI agents, a few repositories, one task graph.
  • State you can read with cat and jq — no service account, no proprietary store.

What it is not, and is not going to grow into

Not this Why — and what to use instead
A multi-tenant platform No tenancy, no RBAC, no SSO, no audit export. One FOREMAN_HOME belongs to one person.
A durable workflow engine No daemon, no queue broker, no timers, no HA, no retries at scale. For resumable long-running workflows use Temporal, Airflow or Argo Workflows.
A database The ledger is a JSONL file — fast and auditable at the scale of one person's tasks, not a sharded store with a query planner.
An enterprise audit product No retention policy engine, no signed reports, no compliance controls.
A place for business logic The plane decides nothing. Your agent owns the work; the plane owns the sequence, the gate and the verdict.
A dashboard The whole surface is CLI, MCP stdio and a Python API. There is no UI and no web server.

Why this is a feature

The tool fits in one directory, starts in milliseconds, and can be read end to end with a text editor. If your requirement is "our forty-person org needs approval workflows with SLA clocks and a Postgres-backed audit trail", this is the wrong tool and you should not spend an afternoon on it. If it is "my agents keep forgetting what they promised last week and I want a ledger that says so", it is exactly the right size.

Where it stops and something else starts

If you need Use
Durability across days, HA, thousands of concurrent tasks Temporal / Airflow / Argo Workflows
A team-wide approval and audit product Jira / ServiceNow / a workflow platform with a real admin model
Human task tracking and reporting Beads, or a plain issue tracker
A single-machine, dependency-aware, model-free task ledger for your own agents foreman-plane

What it feels like

You: Finish these reports first, then let the downstream job merge them.

foreman-plane: Three cards. The downstream one carries [depends_on], so it cannot even start while the upstream files are missing. When everything is done the artefacts get checked again, a missing field means fail, and the ledger records which file fell short.

Install

pip install foreman-plane

You get two identical commands — use whichever you like:

foreman-plane --help   # canonical
gongtou --help          # short alias (工头)

There is deliberately no foreman command. That name is already taken by other projects — an AI orchestration engine on npm, an infrastructure manager on GitHub — and two packages shipping the same binary name is a real conflict on PATH. The Python package is foreman_plane, so it does not collide with the unrelated foreman library on PyPI either.

Or run it straight from a checkout:

cd foreman-plane
export PYTHONPATH="$PWD/src"
export FOREMAN_HOME="$PWD/.foreman"

Ready to run it? Deployment below is the step-by-step: where the plane keeps its state, which command executes a card, the first card you hand in, and how to wire it into your harness.

Deployment

foreman-plane is a plain process, not a service. There is no daemon, no port, no database and no scheduler. "Deploying" it is three decisions, not a deployment guide:

Decision Where Default
Where the plane keeps its state FOREMAN_HOME $HOME/.foreman
Which command executes a card ${FOREMAN_HOME}/agents.json the built-in generic — empty, so it fails until you define it
Who may hand in cards the caller: a person, a script or an MCP client —

Deployment: three entry points, one core, one ledger

Step 0 — check the install

pip install foreman-plane
foreman-plane --help
foreman-plane config

foreman-plane and gongtou are the same program. The module entry points are python -m foreman_plane.cli and python -m foreman_plane.mcp_server.

foreman-plane config prints the effective home, the ledger path, the run directory and the known execution bodies. Nothing is written yet.

Step 1 — give the plane a home

export FOREMAN_HOME=/var/lib/foreman
foreman-plane config

Everything the plane owns lives under FOREMAN_HOME:

Path Written by Purpose
ledger.jsonl the plane the append-only audit ledger — the source of truth
runs/ the plane one log file per run: stdout, stderr, exit code
agents.json you the execution bodies

FOREMAN_HOME resolves as: the environment variable → $HOME/.foreman → <cwd>/.foreman. It works even when HOME is not set. The home and runs/ are created automatically; agents.json is only read, never written for you.

Step 2 — pick an execution body

cat > /var/lib/foreman/agents.json <<'JSON'
{
  "agents": {
    "dsh":    {"command": "dsh headless {task}"},
    "claude": {"command": "claude -p {task}"},
    "codex":  {"command": "codex exec {task}"},
    "mybot":  {"command": "mybot run --prompt {task}"}
  }
}
JSON

Two placeholders are available: {task} — replaced with the whole task card — and {workdir} — replaced with the working directory. A template without {task} is refused: the plane will not guess what the agent should be told, so the run ends with exit_code: 127 before anything starts.

The command is executed as a subprocess — no shell, so there is no quoting to get wrong — in the working directory you pass to dispatch, under a wall-clock limit of FOREMAN_TIMEOUT seconds (default 900).

The names claude, codex, dsh and generic already exist; your agents.json overrides or extends them. generic has an empty command, so a card dispatched to it ends with exit_code: 127 — the plane never guesses an agent for you.

Step 3 — hand in your first card

Every card needs an [id]; a card without one is refused (task_id_missing).

cat > /tmp/card.md <<'MD'
[id] T-20261109-01
[acceptance] reports/report.md::min_bytes=200::contains=Conclusion

Read the notes and write a summary. End it with a "Conclusion" section.
MD

foreman-plane dispatch --file /tmp/card.md --agent dsh --workdir /srv/work

The command runs the card to completion and then reports the verdict:

task_id: T-20261109-01
ok: true
verdict: pass
acceptance_ok: true
exit_code: 0

--json prints the whole receipt instead. Exit codes: 0 success, 2 blocked by the gate, 3 artefact acceptance failed, 1 anything else.

Step 4 — let an orchestrator drive it

This is the usual deployment: an agent decides what to run, the plane guarantees when and whether. The agent talks MCP over stdio — one JSON object per line, no port, no daemon to keep alive.

DeepSeek Harness — no plugin code, just point the profile at the server:

# ~/.dsh/profiles/headless/cordis.patch.yml
mcp:
  servers:
    - name: foreman
      command: python3
      args:
        - -m
        - foreman_plane.mcp_server
      env:
        FOREMAN_HOME: /var/lib/foreman

Claude Code, Codex or any MCP client:

{
  "mcpServers": {
    "foreman": {
      "command": "python3",
      "args": ["-m", "foreman_plane.mcp_server"],
      "env": { "FOREMAN_HOME": "/var/lib/foreman" }
    }
  }
}

The orchestrator gets three tools: foreman_dispatch, foreman_status, foreman_cancel.

Who decides what gets dispatched

The plane never decides. It has no planner, no model, no priority queue and no scheduler. It executes the cards it is handed and refuses the ones whose hard dependencies are not met yet.

decides → writes a card → hands it in (CLI / MCP) → plane gates, runs, accepts

A blocked card is not woken up automatically: once the upstream passes, the orchestrator (or you) submits the card again. blocked is deliberately not dispatched, so a blocked task stays re-dispatchable — otherwise the task graph would deadlock and the upstream could never unblock it.

Configuration reference

Variable Default Meaning
FOREMAN_HOME $HOME/.foreman plane home: ledger, run logs, agents.json
FOREMAN_TIMEOUT 900 execution timeout in seconds
FOREMAN_AGENT generic default execution body
FOREMAN_ACTOR foreman actor recorded in the ledger

What foreman-plane does not do

  • No daemon, no scheduler, no cron, no HTTP API, no port to open.
  • It does not choose an agent, a model or a priority.
  • It does not retry a blocked card for you.
  • It does not believe the model about the outcome — only files.

For where this stops being the right tool, see Scope.

Troubleshooting

Symptom What it means Fix
exit 2, dependency_pending the upstream has not finished yet wait for it, then submit the card again
exit 2, dependency_unaccepted the upstream ran but its artefact failed fix the upstream, then re-submit
exit 2, dependency_unknown that upstream id was never dispatched check the id
exit 2, dependency_unparsed the [depends_on] marker could not be parsed fix the card — the plane refuses to guess
exit 2, dependency_cycle the dependency graph loops break the cycle
exit 2, duplicate_task that id already has a dispatch event a new id, --force, or foreman-plane ledger replan
exit 2, task_id_missing the card has no [id] add one
exit 3 the artefact is missing, too small or missing the marker read the run log in runs/
exit_code: 127, no such agent, or its command template is empty the agent name is not in agents.json add the agent, or use one of the built-ins
exit_code: 127, command template has no {task} placeholder the template forgot the placeholder add {task}
exit_code: 127, executable is not on PATH the command cannot be found fix agents.json or PATH

The CLI exit code and the agent's exit code are different things: exit 2 and exit 3 are the CLI's, while exit_code: in the receipt is the execution body's. Every failed run — including the ones that never started — leaves a log under ${FOREMAN_HOME}/runs/, and the receipt carries the tail of stderr.

The task card

A task card is plain text. Four markers may appear anywhere in it:

Marker Meaning
[id] task id, shaped like T-YYYYMMDD-NN
[depends_on] hard dependency: the upstream must be terminal, passed and accepted
[needs_api] soft dependency: the artefact only has to exist, not be finished
[acceptance] acceptance artefact plus optional objective criteria
[id] T-20261109-20
[depends_on] T-20261109-01
[needs_api] T-20261109-01#/var/lib/foreman/api/order_book.json
[acceptance] reports/order_book_20261109.md::min_bytes=200::contains=Conclusion

Read order_book.json, produce the report and add a Conclusion section.

The half-width bracketed form above is the canonical one. The full-width variants such as 【id】 and the colon forms such as id: are still accepted, as are full-width spaces and colons. What never happens is a silent drop — a dependency marker that cannot be parsed refuses the dispatch with dependency_unparsed.

What the plane guarantees

How one card runs

How one task card runs through the plane

  task card
    │
    ├─ parse ──▶ contract: id / hard dependencies / soft dependencies / acceptance criteria
    │
    ├─ gate ───▶ every hard dependency terminal, passed and accepted?
    │              ├─ no  ──▶ blocked: one ledger line, nothing runs, no dispatch event
    │              └─ yes
    │                   ▼
    ├─ run ────▶ call the execution body: Claude Code / Codex / DSH / any command
    │
    ├─ accept ─▶ check the artefact: min_bytes / sha256 / contains / exit_code
    │
    └─ ledger ─▶ append one JSON line: dispatch / running / done / blocked / …

Hard gate — a task never runs too early

A card with [depends_on] is released only when every upstream task is terminal, verdict=pass and artefact acceptance passed. Otherwise the plane writes a blocked event and stops. There is no dispatch event for a task that did not run, so the ledger cannot show a ghost dispatch.

[depends_on] T-20261109-01  →  upstream done, verdict=pass   →  released
                             →  upstream still running        →  blocked(dependency_pending)
                             →  upstream unknown               →  blocked(dependency_unknown)
                             →  upstream verdict=fail          →  blocked(dependency_failed)
                             →  unparsable dependency marker   →  blocked(dependency_unparsed)

Soft gate — a task may start without a missing artefact

[needs_api] marks artefacts that must be ready but do not have to be finished. A missing artefact is reported as needs_api_pending and the task still runs.

Objective acceptance — the artefact decides, not the model

[acceptance] reports/report.md::min_bytes=200::sha256=<hex>::contains=Conclusion

Supported criteria: min_bytes, sha256, contains, exit_code. All criteria are ANDed, relative paths resolve against the working directory, and an unknown criterion fails closed.

Append-only audit trail

Every decision is one JSON line in ${FOREMAN_HOME}/ledger.jsonl:

{"ts":"2026-11-09T09:41:02.113456+00:00","event":"dispatch","task_id":"T-20261109-20","actor":"foreman","depends_on":["T-20261109-01"],"needs_api":[],"acceptance":"reports/report.md::min_bytes=200","needs_api_pending":false,"detail":{}}

Event types: dispatch, running, blocked, done, cancelled, replan. History is never rewritten or deleted.

MCP tools

Tool Purpose
foreman_dispatch dispatch a task card: parse, gate, run, accept
foreman_status ledger status of one task or of everything
foreman_cancel cancel a task; unknown ids are rejected

The tool names keep their foreman_ prefix: they are a namespace inside MCP, not a binary name, so the CLI rename does not touch them.

CLI

foreman-plane dispatch --file TASK.md [--agent NAME] [--workdir DIR] [--force] [--json]
foreman-plane status   [--task-id ID] [--json]
foreman-plane ledger   list | show | ready | blocked | cancel | replan
foreman-plane verify   --acceptance "<acceptance string>"
foreman-plane mcp
foreman-plane config

Exit codes: 0 success, 2 blocked by the gate, 3 artefact acceptance failed, 1 anything else.

Development

PYTHONPATH=src python3 -m unittest discover -s tests -v

The specification lives in docs/SPEC.md, the wire contract in docs/PROTOCOL.md.

License

MIT — see LICENSE.

Metadata

Release files for foreman-plane 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for foreman-plane 0.2.0
File Size Uploaded Provenance Actions
foreman_plane-0.2.0.tar.gz 788.4 kB Without provenance Details for foreman_plane-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for foreman-plane 0.2.0
File Interpreter ABI Platform Actions
foreman_plane-0.2.0-py3-none-any.whl Python 3 none any Details for foreman_plane-0.2.0-py3-none-any.whl

Total release size: 821.2 kB

Release files / foreman_plane-0.2.0.tar.gz

Download URL foreman_plane-0.2.0.tar.gz
Size 788.4 kB
Tags Source
SHA-256 checksum
How to use checksums
815f23807d05a2f7ee4cd739d9b28e924596c07bd4242b9471712c4030edca82
BLAKE2b-256 checksum
How to use checksums
c11e7f998613a5a4f5f4b78b35dceb58fcc8c2ee332ef7c626de8192cd034ea2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.12

Release files / foreman_plane-0.2.0-py3-none-any.whl

Download URL foreman_plane-0.2.0-py3-none-any.whl
Size 32.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e5ddefa9e5ac398294f8578860bc68a7abf9418981aa2ec9009bef473ede89e9
BLAKE2b-256 checksum
How to use checksums
9536d5ffa56704159e67d0fe4f6dbec606d70890d25690a32d540d0271fffd91
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.12

Security for foreman-plane 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page