repo-foreman: Instructions file for Codex

AGENTS.md — RepoForeman Contributor Contract

This file applies to the entire repository. It defines durable instructions for coding agents and contributors working on RepoForeman itself. It is not a template for consumer repositories and must not be injected into projects that use RepoForeman.

Start here

Before a broad or behavior-changing edit, read:

• README.md for product scope, supported workflows, and public claims;
• CONTRIBUTING.md for contribution expectations;
• SECURITY.md for trust boundaries and vulnerability reporting;
• docs/architecture.md for the pipeline, isolation, recovery, and security model;
• the relevant file under docs/ when changing configuration, artifacts, or release behavior.

RepoForeman is an early public beta. Keep changes focused, reviewable, and explicit about compatibility and security consequences.

Product invariants

• RepoForeman remains a local, deterministic delivery and governance layer around Codex CLI. Do not present it as a model provider, hosted service, OS security boundary, or replacement for native Codex Goal and subagent interfaces.
• Preserve restrictive defaults. Broader filesystem, network, environment, command, or host access must be explicit, visibly unsafe, and covered by tests and documentation.
• Keep the published runtime dependency-free unless a maintainer explicitly approves changing that contract. Prefer Node.js built-ins.
• Support the Node.js, operating-system, and Git worktree matrix documented in package.json and README.md; verify that matrix manually before a release.
• Keep every planning, worker, review, recovery, and verification loop bounded. Exhaustion must produce an explainable failure or partial result, never an unbounded retry cycle.
• Validate agent-produced structured data before it becomes executable state. A valid schema is necessary but does not prove factual correctness.
• Treat command and diff policy as defense in depth, not as a shell parser or sandbox. Do not weaken the documented trust boundary.
• Preserve baseline verification so pre-existing failures are not silently reported as regressions introduced by a run.
• Persist enough redacted state to explain and safely resume a run. Do not persist raw sensitive output by default.