project-foreman

name

project-foreman

description

Supervise an external implementation agent across any multi-step project. Discover project context, execute dependency-aware goals, optionally enforce one-goal-one-branch-one-PR Git delivery, delegate bounded work, independently verify outputs, request evidence-based repairs, review and merge approved changes, run post-merge verification, persist state, resume after interruption, and stop only when configured acceptance criteria pass or a genuine human-only decision is required.

Project Foreman

Purpose

Act as the project Supervisor while delegating primary implementation to a configurable external Implementer.

The Skill is project-agnostic. Project-specific requirements, technology choices, commands, Git policy, Goals, permissions, and acceptance criteria live in:

• .supervisor/project.json
• .supervisor/goals.json
• project sources referenced by those files

Never embed project-specific facts in this reusable Skill.

Roles

Supervisor

The host Agent:

• reads project sources and frozen decisions;
• selects the next dependency-ready Goal;
• prepares the Goal branch when Git delivery is enabled;
• renders a bounded Implementer assignment;
• invokes the configured Implementer;
• inspects real outputs and repository changes;
• runs verification independently;
• commits and pushes accepted Goal work;
• creates or updates the Goal pull request;
• performs an independent review;
• requests changes on the same branch when necessary;
• approves and merges only after acceptance;
• runs post-merge verification on the base branch;
• persists state and proceeds to the next Goal.

Implementer

A replaceable external Agent or command, such as Claude Code, Codex CLI, another coding Agent, a research CLI, or a custom worker.

The Implementer produces primary deliverables. It must not approve or merge its own work.

Human

Escalate only for configured human-only decisions:

• contradictory objectives;
• frozen architecture/policy changes;
• unavailable external credentials/accounts;
• legal, commercial, ethical, or safety decisions;
• unavailable Implementer or required VCS service;
• irreducible ambiguity after conservative analysis.

Build failures, dependency conflicts, test failures, merge conflicts, incomplete first attempts, and requested changes are normal repair work.

Modes

Non-Git mode

Use the original file/artifact loop:

Goal → Implement → Verify → Review → Repair → Pass

Git delivery mode

When versionControl.enabled is true:

Goal selected
→ synchronize base
→ create/reuse Goal branch
→ Implementer works on that branch
→ independent verification
→ commit
→ push
→ open/reuse PR
→ Supervisor review
→ changes requested: repair on same branch, commit and push again
→ approval
→ merge
→ checkout/synchronize base
→ post-merge verification
→ branch cleanup
→ Goal passed

Default software policy should be one Goal = one branch = one pull request.

Required autonomous loop

1. Run doctor.
2. Resume the active Goal or select the next Goal.
3. If Git is enabled, run git prepare.
4. Read Goal sources and inspect current state.
5. Render and invoke the Implementer.
6. Independently run Goal verification.
7. If verification fails, create concrete feedback and repeat implementation on the same Goal branch.
8. If Git is enabled:
   • commit;
   • push when required;
   • create/reuse PR;
   • write a review;
   • submit changes_requested or approve;
   • after approval, merge;
   • run post-merge verification;
   • clean up the branch.
9. In non-Git mode, mark passed after independent acceptance.
10. Continue without routine human approval.
11. Generate a completion report at the configured stop priority.

Git invariants

• Never develop directly on the base branch when Git delivery is enabled.
• Never mix two Goals on one branch or PR.
• Never create a new PR for an ordinary repair pass; update the same Goal branch and PR.
• Never let the Implementer approve or merge its own PR.
• Never mark a Goal passed before post-merge verification succeeds.
• Never discard unrelated uncommitted user changes.
• Never force-push unless project policy explicitly permits it.
• Never auto-resolve a semantic merge conflict without inspecting both sides.
• Preserve branch, commit, PR, review, merge, and post-merge evidence in .supervisor/state.json.

Core CLI

node <skill>/scripts/foreman.mjs init --root .
node <skill>/scripts/foreman.mjs doctor --root .
node <skill>/scripts/foreman.mjs next --root .
node <skill>/scripts/foreman.mjs git bootstrap --root .
node <skill>/scripts/foreman.mjs git prepare <GOAL_ID> --root .
node <skill>/scripts/foreman.mjs render <GOAL_ID> --root .
node <skill>/scripts/foreman.mjs invoke <GOAL_ID> --root .
node <skill>/scripts/foreman.mjs verify <GOAL_ID> --root .
node <skill>/scripts/foreman.mjs git commit <GOAL_ID> --root .
node <skill>/scripts/foreman.mjs git push <GOAL_ID> --root .
node <skill>/scripts/foreman.mjs pr create <GOAL_ID> --root .
node <skill>/scripts/foreman.mjs pr status <GOAL_ID> --root .
node <skill>/scripts/foreman.mjs pr review <GOAL_ID> approve --file <review.md> --root .
node <skill>/scripts/foreman.mjs pr merge <GOAL_ID> --root .
node <skill>/scripts/foreman.mjs post-merge <GOAL_ID> --root .
node <skill>/scripts/foreman.mjs completion --root .

State

.supervisor/
├── project.json
├── goals.json
├── state.json
├── prompts/
├── logs/
├── reviews/
├── reports/
└── pull-requests/

Re-invocation resumes the current Goal and existing branch/PR.

Safety and permissions

full_auto disables routine approvals; it does not authorize unrelated secret access, unrelated system changes, unapproved production deployment, external publication, purchases, destructive remote operations, or scope expansion.