Skip to main content

foreman-plane

A task governance plane that runs outside your agent harness.

foreman-plane (the "foreman") is the layer above the agent, not inside it. Claude Code, Codex, DeepSeek Harness or any CLI agent are pluggable execution bodies; the plane owns the parts an agent session cannot own: dispatch, dependency gating, objective acceptance and an append-only audit trail.

        ┌───────────────────────────────────────────┐
        │            foreman-plane (the foreman)    │
        │  contract → gate → ledger → acceptance    │
        └───┬───────────────┬───────────────┬───────┘
            │ MCP/stdio     │ MCP/stdio     │ MCP/stdio
       ┌────▼─────┐    ┌────▼─────┐    ┌────▼─────┐
       │ Claude   │    │  Codex   │    │   DSH    │      ← execution bodies
       └──────────┘    └──────────┘    └──────────┘
  • 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.
  • Outside the harness — the plane is a plain process; no agent framework has to be patched to use it.

Zero third-party dependencies. Python ≥ 3.10. Standard library only.


Quick start

# 1. run it straight from the checkout
cd foreman-plane
export PYTHONPATH="$PWD/src"
export FOREMAN_HOME="$PWD/.foreman"

# 2. declare one execution body
cat > "$FOREMAN_HOME/agents.json" <<'JSON'
{"agents": {"mybot": {"command": "mybot run --prompt {task}"}}}
JSON

# 3. dispatch a task card
cat > card.md <<'MD'
【id】T-20261109-20
【depends_on】T-20261109-01
【验收】reports/report.md::min_bytes=200
写一份报告。
MD

python3 -m foreman.cli dispatch --file card.md --agent mybot --json

python -m foreman.cli and the foreman console script are equivalent.


The task card

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

marker meaning
【id】 task id, T-YYYYMMDD-NN
【depends_on】 hard dependency — the upstream must be done and pass
【needs_api】 soft dependency — an artefact that only has to exist
【验收】 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
【验收】reports/order_book_20261109.md::min_bytes=200::contains=结论

请读取 order_book.json,产出分析报告并给出结论小节。

Marker syntax is forgiving (【id】, [id], ID:, full-width spaces and colons all work), but a dependency that cannot be parsed is never silently dropped: the dispatch is refused with dependency_unparsed.


What the plane guarantees

Hard gate — a task never runs too early

A task with 【depends_on】 only starts when every upstream task is terminal, passed and accepted. 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  →  T-20261109-01 done, verdict=pass  →  dispatch
                             →  T-20261109-01 still running       →  blocked(dependency_pending)
                             →  T-20261109-01 unknown              →  blocked(dependency_unknown)
                             →  T-20261109-01 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

【验收】reports/report.md::min_bytes=200::sha256=<hex>::contains=结论

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 integration

The plane ships an MCP server that speaks JSON-RPC 2.0 over stdio with NDJSON framing (one JSON object per line). Point any MCP client at it:

python3 -m foreman.mcp_server

For a harness that loads MCP servers from a patch file, the entry looks like this (the exact field names follow the MCP client in use — only the stdio JSON-RPC handshake is fixed by the plane):

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

Three tools are exposed:

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)

CLI

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

Exit codes: 0 success · 2 blocked by the gate · 3 artefact acceptance failed · 1 any other error.


Configuration

variable meaning
FOREMAN_HOME plane home (ledger, runs, agents.json)
FOREMAN_TIMEOUT execution timeout in seconds (default 900)
FOREMAN_AGENT default execution body (default generic)
FOREMAN_ACTOR actor recorded in the ledger (default foreman)

FOREMAN_HOME is resolved as: the environment variable → $HOME/.foreman → <cwd>/.foreman. When HOME is not set the plane still works.


How this differs from other approaches

  • Against "the agent will remember" — a session that forgets cannot enforce a dependency. The gate is a separate process with its own durable state, so it keeps working across sessions, agents and days.
  • Against "the agent will self-report" — the verdict is derived from an artefact on disk (min_bytes, sha256, contains, exit_code), not from a sentence in the transcript. A task that promises a report but writes no report fails.
  • Against "one big agent" — the plane does not choose a model and does not care which agent runs a task. Execution bodies are interchangeable commands; governance stays in one place.
  • Against "a workflow engine" — there is no DAG runtime, no scheduler and no background worker. The plane is a ledger plus a gate: it decides whether a task may start, and leaves how to the body that is wired in.
  • Against "a chat transcript as state" — the ledger is append-only and machine readable, so it can be queried, diffed and audited by something that is not an LLM.

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.1.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.1.0
File Size Uploaded Provenance Actions
foreman_plane-0.1.0.tar.gz 55.1 kB Without provenance Details for foreman_plane-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 83.0 kB

Release files / foreman_plane-0.1.0.tar.gz

Download URL foreman_plane-0.1.0.tar.gz
Size 55.1 kB
Tags Source
SHA-256 checksum
How to use checksums
54eb4746e38ee8175da16d29cba10780bdde610bebdd415cea3ebc9eb197e566
BLAKE2b-256 checksum
How to use checksums
c35ded7ef006ce9d9bef91e5ae91958c7536bb49aa5b61dbc6026a5f617cb765
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.1.0-py3-none-any.whl

Download URL foreman_plane-0.1.0-py3-none-any.whl
Size 27.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
91dbf014409c300da160d7bbf59190e2c4c531e1faacf7e7b4f4a070a9128c37
BLAKE2b-256 checksum
How to use checksums
eb0f9180205d36bbb124cbe756f39775c803b4a53e29bb32b967291a8ddc80af
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.1.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