Project Foreman

Project Foreman is a reusable Agent Skill for supervising multi-step projects. A host Agent acts as Supervisor, delegates bounded Goals to an external Implementer, verifies real outputs, and optionally manages one branch and pull request per Goal.

What it does

• selects dependency-ready Goals;
• invokes a configurable external Agent or command;
• independently runs acceptance checks;
• requests repairs with concrete evidence;
• manages branch, commit, PR, review, merge, and post-merge verification;
• persists progress and resumes after interruption;
• supports GitHub, GitLab, local Git review, custom providers, and non-Git work.

The Supervisor and Implementer must be separate roles. Do not configure a host to recursively invoke itself.

Requirements

• Node.js 18 or newer;
• Git only when Git delivery is enabled;
• gh or glab only for the corresponding hosted provider;
• an Agent host and a separately invokable Implementer.

Project Foreman has no npm runtime dependencies.

Start here

git clone https://github.com/lichman0405/project-foreman.git
node /path/to/project-foreman/scripts/foreman.mjs init --root /path/to/your-project

Configure these generated files:

.supervisor/project.json  # Implementer, permissions, execution, Git policy
.supervisor/goals.json    # Goal DAG, acceptance, verification

Then run the preflight:

node /path/to/project-foreman/scripts/foreman.mjs doctor --root /path/to/your-project

The legacy scripts/aps.mjs entry remains available for existing integrations.

Read QUICKSTART.md for the first-run walkthrough and references/security-and-permissions.md before enabling unattended execution.