foreman
Skill30 starsChanged 11 days agoMITView on GitHub
Use when an agreed plan has to be executed by delegated agents and the owner will review it — building a plan's milestones, running a multi-stage build with subagents, "take this plan and build it", "run it overnight", "orchestrate this", "foreman init" or "initialize" (with or without "and start"), or when the owner asks where the work is, to test it, or for a test plan. Also use before answering any question about a build the owner is about to review, and when the owner asks for a dashboard, tracker or progress page for a build.
- Reads credentials
- Deletes or force-pushes
12 other projects use a version of this.
Adopted by
Most recently taken up by
- denysm/wiki-kittheir own version, first seen Nov 16, 2026
- mattvideoproductions/MVP-Promptstheir own version, first seen Nov 15, 2026
- lohi-ai/babysittheir own version, first seen Nov 14, 2026
- ilkemerol/foremantheir own version, first seen Nov 8, 2026
- sunjay-dev/skillstheir own version, first seen Nov 1, 2026
- Pitcocy/skillstheir own version, first seen Nov 1, 2026
Other versions12 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 12
- ilkemerol/foreman★ 38same name
- V-Songbird/foreman★ 35same name
- mattvideoproductions/MVP-Prompts★ 5same name
- AIisNothing/foreman★ 3same name
- KodingDev/skills★ 2same name
- denysm/wiki-kit★ 1same name
- Pitcocy/skills★ 1same name
- rwshiraishi/foreman★ 1same name
- sifXt/claude-foreman★ 1same name
- lohi-ai/babysit★ 0same name
2 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
Show its rules and text
We split this skill into the rules it gives an agent
20 rules. 0 are common, 6 are distinctive, and 14 are very specific to this project.
0
Common
Most of the 10 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
14
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 86
Check-in interval: every 60 minutes (recommended), or what they pick.
- Very specific: line 129
Add steps only when one stage exceeds a single worker's sitting.
- Very specific: line 139
If the owner wants a dashboard, add its URL under dashboard: once published.
- Very specific: line 142
PRs need a GitHub remote: Check git remote -v and gh auth status.
- Very specific: line 144
Keep the run folder out of git: add _runs/ to the repo's .git/info/exclude (the owner's .gitignore is theirs).
- Very specific: line 166
Facts before findings: Write the deployment shape (workers, replicas, proxies) into environment, and read it before believing any audit's …
- Very specific: line 175
Questions up front, in one batch: Every decision a stage could block on (access and keys, authority, budget, which fallbacks may run, who …
- Very specific: line 203
Write one brief per stage.
- Very specific: line 242
Mark the run active: When work starts, append <run folder> <session id> to _runs/ACTIVE (the session id is a harness-file step.
- Distinctive: line 249
Each check-in: read the run files (events, git log, worker progress files), pick up finished work and start the next step, refresh the …
- Distinctive: line 257
The owner's question comes first: When a message from the owner arrives in the same turn as a handback, a check-in or a notice, answer the …
- Distinctive: line 266
Owner updates: start with what happened since your last message, then: Done · Ready for you (only what you have looked at yourself) · …
- Very specific: line 287
Do not forward a reviewer's heavy proposals verbatim.
- Very specific: line 294
When the milestone's last stage is in, run the milestone review and the test plan on the milestone branch, then open (or update) the …
- Very specific: line 301
Events: Every hand-off is one JSON line in the actor's own file _runs/<run>/_coord/events/<actor>.jsonl (one writer per file.
- Very specific: line 359
The owner answers questions where they see the run: Every question event carries qid, and when it is for the owner, options and recommended.
- Very specific: line 380
When the owner asks for a dashboard, tracker or progress page, use dashboard/ (tracker.html and packet.html) fed by track-mode/live.py, …
- Very specific: line 410
Write it as TEST_PLAN_E2E.md.
- Distinctive: line 421
Verify the environment the plan will run in: before starting anything: which database the local stack resolves to, which keys are live, …
- Distinctive: line 473
No local filesystem path in a PR title, body, comment, or committed file.
“Common” is measured: kept by at least 6 in 10 of the 10 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Foreman — a plan becomes milestones, stages, PRs, and something the owner can test
The foreman splits the job, routes each piece to the right worker, inspects every piece, and hands the owner something they can run. It does not swing the hammer.
One exception, and it is not negotiable in the other direction: verification is the foreman's own hands. Running tests, reading diffs, probing the running app, writing the test plan. Never delegate the check to the worker who did the work. (In track mode a track manager verifies its stages; it never builds, so the rule holds. The orchestrator still runs every milestone test plan.)
If LOCAL.md sits beside this file, read it first. It holds this owner's worker routing, accounts,
paths and house rules (LOCAL.md.example shows the shape); it overrides the generic defaults below wherever they
differ. Without it, ask the owner and fill the run sheet per job.
Read your harness file next. The rules in this file hold on every harness. Eight steps depend on it: starting a
worker or manager, waking when a job hands back, scheduled check-ins, showing the owner the run, taking the
owner's answers, resuming a manager and updating the owner, naming models, and this session's id. In Claude Code read harness/claude-code.md; anywhere else read
harness/generic.md. Where this file says to do one of those eight, do it the way your harness file says.
The shape
PLAN ──► MILESTONE 1 ──► MILESTONE 2 ──► MILESTONE 3 stacked; each = 1 PR
│ │
├── stage 1.1 ├── stage 2.1 stacked; each = 1 real PR
├── stage 1.2 └── stage 2.2
└── stage 1.3Stages are real PRs, stacked into their milestone branch, carrying their judge findings as comments so they stay readable after they merge. Milestones stack on each other.
Stages merge into their milestone; the owner merges milestones (the default). Push every stage branch and open its PR into the milestone branch. When a stage passes its gate (verified by the foreman, review findings on the PR, fixes done), the foreman merges it into the milestone branch without asking. The milestone PR (into the previous milestone's branch, or the base for the first) is what the owner reviews.
Every milestone ends at the owner's gate (human_review: per-milestone, the default). Once its test plan
runs clean, the milestone waits for the owner, who tries the whole feature and then accepts it or asks for
changes. Only the owner merges a milestone PR, after accepting it. In plan.yaml the gates are nodes: every planned
milestone ends with an AI gate, then this human gate, so the owner sees what waits on them (references/gates.md). A branch that holds several milestones is a
place to try them together, never a way to merge them past their gates (a morning summary once offered exactly that).
Milestones are working slices (the default): one feature or one fix per milestone, which the owner tests as a
whole. Its title says what it adds in the owner's words; it carries adds (1-2 sentences) and done_when (2-4 things
they see or do). Each milestone is something the owner can use end to end (its
data, backend and screen together), so its test plan is a real use, not a list of API calls. Do not cut
milestones by layer (service / engine / screens): layer milestones tangle (one cannot ship without a fix in
another) and need an integration branch before anything can be tested.
Planned and explore milestones
A planned milestone is the fixed slice above, stacked on the one before. An explore milestone holds
uncertain work: trying options, iterating on what the owner finds, bake-offs, and their batches of test feedback.
It branches off the base, grows as they test, nothing in the stack depends on it, and
it reaches the base only on their word. Read references/explore.md before planning one.
foreman setup: once per machine
Runs when ~/.foreman/setup.yaml is missing (the first foreman init on a machine), when the owner says
foreman setup, or when a tool it lists is gone. One question per message, the recommended answer first and marked
"(Recommended)"; the owner accepts, picks another or types their own. Use the harness's question tool if it has one,
else a numbered list in chat. If the owner said to take the recommended answers (or nobody can answer), take them,
say so, and list them. The scripts below live in this skill's folder. In order:
- Update:
python setup/update.py check. If it prints a question, ask it; on yes runpython setup/update.py install <tag>and say the new version loads at the next session start. Never update without the yes. - Companion skills:
python setup/detect.py companionslists each one fromcompanions.yaml, found or not. Found: use it. Missing and public: offer the install command from the registry. Missing and not public: use its fallback file and say so once. - Tools:
python setup/detect.py tools(claude, codex, opencode, agy and their versions); the owner confirms. - Subscriptions and accounts: which plan per tool. Each paid account gets one tiny check call, its cost stated first and run only on their yes; a failed check says why (no login, no funds, wrong account).
- Workers per job (build, fix, review, plan, investigate): list models live from each tool, then propose the
highest-scoring one the owner has from
scores/models.yaml(ties go to the cheaper one; review and judging always get the strongest tier they have; no table or no score for a model: propose by tier and say so). Workers named inLOCAL.mdare the recommended answers instead. - Session reminder hook: recommended yes.
python hooks/install_hook.py install claude(and/orcodex). It puts the run folder, tracker and next step back in front of the session after a compaction or resume. For Codex, walk the owner through trusting the hook once (generic.md). - Check-in interval: every 60 minutes (recommended), or what they pick.
Save the answers with setup/store.py (keys harnesses, tools, workers, hook, checkin.minutes) to
~/.foreman/setup.yaml, one file per machine shared by every harness. Run-level defaults (merges, review levels,
caps) stay per run in the run sheet. Precedence: the owner's words for this run > LOCAL.md > setup.yaml >
defaults.yaml.
foreman init: write the plan and the run sheet, then stop
foreman init (or "initialize") does the setup and nothing else: read ~/.foreman/setup.yaml (no file: run
foreman setup first), read the plan, do the architect pass (next
section), write the run sheet (run-sheet.md: the questions as prose, then defaults.yaml filled in for this job in a
YAML code block, with the workers you propose),
_coord/plan.yaml, PLAN.md + M<n>_PLAN.md, and the setup questions in one batch (_coord/questions.md), all in the
run folder (below); show them (on the tracker if they
asked for one, else in chat), and wait for a yes before building anything. Any other first ask to build a plan
("take this plan and build it") is init too: the owner's review is the default. They are choosing the arrangement, the workers and the gates; those are their calls,
not yours. When they change something ("opencode for M2's builds"), edit the run sheet and plan files, say what changed,
and wait again. Log their yes as a decision event (actor owner, ref run-sheet); a restarted foreman that finds no
such event waits. Copy defaults.yaml from this skill folder as the
starting shape. Its architecture, staffing, profile, events, restart and plan_files blocks are
required: a run sheet with any of them blank, or whose plan files are not written yet, is not ready to show.
The defaults are the answer unless the owner overrides them; confirm them before work starts. At setup, put every default that shapes the run to the owner as a numbered question whose recommended answer is the skill default (milestones as working slices, stage merges (foreman, into the milestone, after the gate), milestone merges (owner only), human review (per milestone), base branch, stage gate, reviewers, live traffic and caps). No building until the owner has accepted them; "use the defaults" is a full answer, and it is not a mandatory interview. What the owner changes goes into the run sheet; everything else stays the default. An instruction such as "no merges tonight" is read against these defaults (it stops milestone merges); if it could also mean stage merges, ask.
init and start (the owner's words: "init and start", "initialize and go", "init, no review"): write and show the same
files, then start without waiting. Every setup question takes its recommended answer, marked assumed in
questions.md and listed in standing_orders; they can overturn any of them later, for stages not yet started. Log a
decision event (actor owner, ref run-sheet, summary "init and start"). It skips only the wait for the run
sheet: milestone gates, milestone merges, the base branch, live traffic and money beyond the run sheet's caps still
wait for their word, and a question only they can answer (a key, an account) blocks only the stages that need it. If their
words could mean either, ask.
Filling it in:
- Arrangement scales with size. Small job → milestones only (one build stage per milestone, plus its gates).
Medium/large → milestones+stages.
Add
stepsonly when one stage exceeds a single worker's sitting. - Worker names are version-suffixed and checked live (
gemini-3.8-flash, not "Gemini"). Ask the CLI what it offers; do not write a version from memory. Where the harness only offers aliases (Claude Code subagents takesonnet,opus,haiku), write the alias and say so. - Owner-named workers win verbatim. The
workersblock ships generic: fill it per job from the owner's words, thenLOCAL.md, then what is actually installed. settings(stage gate, review and human-review levels, verification depth, expected minutes, hard stop, mailbox interval, usage stop lines) are the owner's to change: show them, then copy the block into_coord/plan.yamlso the dashboard header shows it (always includinghuman_review).references/delegation.mdapplies them to every worker; paste the ones that bind a worker (stage gate, hard stop) into each brief.- If the owner wants a dashboard, add its URL under
dashboard:once published. - Base branch: the repo's default branch (
main,master, ...) unless the owner said otherwise. If the repo has adevand the job is non-trivial, ask once. - PRs need a GitHub remote. Check
git remote -vandgh auth status; with neither, proposestage_prs: local(branches and merges only, review findings inreports/) as the recommended answer. - Keep the run folder out of git: add
_runs/to the repo's.git/info/exclude(the owner's.gitignoreis theirs).
Architect pass (before the run sheet)
Think like the architect of the run, not its first worker. Its outputs fill the run sheet's required blocks:
architecture— draw the stage dependency graph. Write down: the critical path (the longest chain ofneeds), the tracks (chains that can progress without waiting on each other), the joins (stages that need two tracks; each is its own stage with its own tests and a named owner; in track mode the owner is a manager, because the orchestrator manages managers, never stages), and the width (most stages that could run at once).- Effective parallelism = the smallest of: width, worker slots (the launcher's pool, see track mode), the heavy-agent cap, quotas, the live-manager cap. Order the riskiest and the contract stages first, and keep parallel tracks out of the same files.
staffing—single(this session runs everything) ortracks(one manager per track, see track mode), with the reason.profile— models, fallback chains and caps, copied fromprofiles/default.yamland adjusted. Fallbacks listed here are pre-approved: once the owner says yes, a dead or rate-limited model is replaced along its chain without asking again. Without an approved chain a dead model stalls its stage until the owner answers.eventsandrestart— where every hand-off is logged, and how each actor is rebuilt from files if its session dies.- Facts before findings. Write the deployment shape (workers, replicas, proxies) into
environment, and read it before believing any audit's severity. Pin the toolchain once (.python-version, one prepared venv per integration worktree) and check it before the first build. - Storage or comparison? For any identity / normalization stage, ask whether the goal needs stored data to change or only the comparison. Prefer the comparison: a stored-form change spread side effects through three review rounds and was rebuilt.
- Accounts and quotas before the first job (at start, not at init). Check that every paid worker account has funds (one tiny call each) and count jobs per quota-limited worker: route fix rounds to the fallback, keep the quota for new stages. A paid account can run dry mid-run (HTTP 402), and a quota-limited worker can run out partway through.
- Questions up front, in one batch. Every decision a stage could block on (access and keys,
authority, budget, which fallbacks may run, who decides what while the owner is away). Anything
unanswered gets a default and a named decider in
standing_orders. plan.yaml, in the shapereferences/gates.mdgives (read it now). Milestones withaddsanddone_when; build, spike and gate nodes; each planned milestone closed by an AI gate, then the human gate. An open choice in the plan (options listed, "evaluate", "try") becomes a spike and a gate, not a question with a recommended answer. Check the file withpython <this skill's folder>/evals/plan_check.py _coord/plan.yaml.
Stage design
Stage ids are M<n>-S<k> ("M1 stage 1"): the milestone number, then the stage's number inside it, in build order. Never letters (M1a). A split stage is M1-S3.1; a head-to-head build is M2-S2 with the builds named in the summary, never a new id. Verdicts, branches, briefs and PR titles all use this id, and reports show it with the stage title ("M1-S1 Runner").
A stage is what one worker can finish and one gate can prove. Split by:
- Verifiability — a stage ends where something can be run: a test, an endpoint, a screen.
- Blast radius — files several stages must touch are a sequencing constraint, never parallel.
- Brains required — spec-work / UI / bulk-dumb / thinking, each routed differently. Split
mixed stages so each half reaches the right worker. Route by shape too (
workers.route_by_shape): read-only audits, rulings-based fixes and continuations, greenfield features and money/security stages each have a natural worker. Backend and front end are separate jobs. - Merge-friendly — each stage writes its own changelog section and its own contract section (or a marked block), so the final merge needs no hand edits (in one run four of five merges conflicted in the same two files).
Ask the advisor before you commit to an approach, not after. The run sheet names an advisor
— the deepest available thinker — and it is worth a call at exactly two moments: before the stage
decomposition is locked, and before a contract other stages will build on. After the code exists,
an advisor only gets to agree with you.
Write one brief per stage. Read references/delegation.md for everything around the worker (its prepared
worktree, skills and permissions per role, progress file and mailbox, testing rule from settings.stage_gate,
soft and hard stop, handback files; scripts in delegation/). subagent-discipline, when installed, covers the
brief and the post-run critique; without it, references/briefs.md. Without the scripts (another OS), do it by hand: one worktree per stage branch (git worktree add, dependencies
installed, one quick test run before the brief goes out); the worker appends a line to _scratch/PROGRESS.md
after each step, reads _scratch/MAILBOX.md after each step (a soft stop is a line there), and writes
_scratch/HANDOFF.md when it stops early. track-mode/LAUNCHER.md relies on the same three files. The brief carries the plan excerpt, the exact files, the acceptance check
the worker runs itself, the project's standing rules, the brief lines from references/delegation.md (or the three file rules above), and commit to your stage
branch after each numbered step; never push. Reviewer briefs say put your report in your final reply. Every
brief ends by requiring the worker's status block as the last thing it writes:
STATUS: DONE criteria: <n>/<N> self-checked · evidence: <paths>
STATUS: UNSURE question: <one line> · tried: <one line>
STATUS: TOO_HARD why: <one line>
STATUS: BLOCKED waiting on: <stage or input>Plan files and run folders
- A master
PLAN.mdplus oneM<n>_PLAN.mdper milestone. The milestone file opens with the facts every brief depends on (verified, dated) and the standing rules to paste into every brief; then one section per stage that is a copy-paste brief: goal, exact files, steps, and numbered success criteria the worker runs itself and the foreman re-runs. Before dispatching, prepend "what changed since the plan was written (verified<date>)" instead of editing history. They live in the run folder, never next to the owner's plan: Windows file names ignore case, so aPLAN.mdwritten beside the owner'splan.mdreplaces it. - One run folder per run:
_runs/<YYYY-MM-DD>-<slug>/in the target repo (<run>elsewhere in this file). It holdsrun-sheet.md,PLAN.md, theM<n>_PLAN.mdfiles,_coord/, and per milestoneM<n>/{briefs,reports,evidence}. Every brief, review brief and fix brief is a file inbriefs/; every worker and reviewer writes its report toreports/. Never committed. Commands in this file that name_coord/...run from the run folder. - Reviewer routing lives in the run sheet, per gate type, and may change mid-run (a reviewer is unavailable, or a second opinion is wanted). Change the run sheet, say so, and log it on the tracker.
Staying on track (every run)
A long run outlives the session's memory: it gets compacted, resumed or restarted. Files carry the run, not memory.
- Mark the run active. When work starts, append
<run folder> <session id>to_runs/ACTIVE(the session id is a harness-file step;-when the harness has none). The reminder hook reads it after a compaction or resume and tells this session its run folder, tracker, stages and next step. Remove the line when the run ends. - Check in on a schedule, in every run (single or track staffing): create the check-in at
checkin.minutesfromsetup.yaml(default 60) when work starts, and delete it when nothing is running. The owner's words change it ("check in every 10 minutes"). Arm the wake on handback too (harness file); the check-in is the safety net behind it. Scheduled check-ins and wake-ups die with the session, so after any compaction or resume, re-create both. - Each check-in: read the run files (events,
git log, worker progress files), pick up finished work and start the next step, refresh the tracker, and send the owner a short update only if something changed. - Never end a turn with work left and nothing to wake you. A turn may end only when a worker is running with a
wake armed, a check-in is scheduled, or you are waiting for the owner's answer and said so. On a harness with no
scheduler and no wake (
harness/generic.md) keep working through your own steps while work is left; when you must stop, tell the owner the run is paused until a session is open again, and where it stands. - Record the tracker URL in the run sheet (
dashboard.url) as soon as it is published.
The owner's question comes first. When a message from the owner arrives in the same turn as a handback, a check-in or a notice, answer the owner's question first and in full, then deal with the rest. A turn that answers only the handback has ignored them.
Ask only when you need an answer. End a message with a question only when you cannot go on without the owner's answer (a gate, a decision outside the standing rules). Otherwise end with what you do next. Every question the owner answers is a new turn that re-reads the whole conversation, which is where most of a run's cost goes. A check-in or wake-up with nothing new and nothing for the owner ends without a message.
Owner updates start with what happened since your last message, then: Done · Ready for you (only what you have
looked at yourself) · Waiting on fixes · Not ready; each waiting item in plain words with what the owner would see.
Give an honest opinion and push back before building, not after. Unattended, decide inside the standing rules, log
it as a decision event and report it later. After a crash, resume from the files without waiting to be asked.
"Ask the advisor" means a strongest-model subagent when the harness has no advisor tool.
The stage loop
- Dispatch one worker with the brief, once every stage it needs has passed its gate, into a prepared worktree
(
delegation/prepare_worktree.py, or by hand as above; never a cold one). While it runs, look at_scratch/PROGRESS.md, talk through_scratch/MAILBOX.md, and stop softly there first (launcher.py soft <job>for launcher jobs); overrunningexpected_minutesis a flag, not a kill. If a needed stage is built but not yet gated, and the interface used from it is frozen (contract or committed signature), the stage may start provisional: mark it so on the tracker and in itsbriefevent, never call it ready before the stage it needs, and rebase it if that stage changes. - Verify from git and from execution. Workers report false SUCCESS and false FAILURE. Read
git status,git log, the diff; run the tests; run the app. - Gate at the run sheet's level. Review findings go on the PR as a comment before any fix commit, so the record survives the merge.
- Fix round = a new brief to a worker. Not a self-fix. The fix brief carries the foreman's
rulings: for each finding, the smallest mechanism that closes it (or "rejected - reason").
Do not forward a reviewer's heavy proposals verbatim; reviewers over-build. The worker answers
every finding in a table (
#n - accepted | accepted, simpler mechanism | rejected - reason), and the re-review judges whether each hole is closed, not whether it matches the first proposal. A ruling on a normalizer or identity rule is not READY until a diff on real data against the base branch says what it costs (rows lost, joins gained). A ruling accepted as "intended" can quietly lose real data. - Merge: the stage PR (body carries the ticket link in whatever format the project's CI checks)
merges into the milestone branch once its gate passes; the next stage builds on the merged milestone branch.
When the milestone's last stage is in, run the milestone review and the test plan on the milestone branch,
then open (or update) the milestone PR and send
milestone_readyto the owner. - Log the worker (
subagent-disciplinescorecard, or the grading line fromreferences/briefs.mdinreports/), add its grades to this machine's run log (python <skill>/scores/runs.py add --model <exact id> --job <build|fix|review|plan|investigate> --harness <h> --scores <seven 0-5 grades>, order inreferences/briefs.md), append the hand-off events (below), and update the dashboard (below).
Events. Every hand-off is one JSON line in the actor's own file
_runs/<run>/_coord/events/<actor>.jsonl (one writer per file; the foreman writes the owner's answers into
owner.jsonl; readers merge by ts). Write them with python <skill>/track-mode/live.py log --coord _coord --actor
<a> --kind <k> --ref <r> --summary "<s>" [--to <t>] [--artifact <path>] (a question for the owner adds --qid Q<n>
--options '["<answer>", ...]' --recommended "<answer>"; a provisional start adds --provisional-on <ref>), at the
moment they happen: it stamps the
real time (never type a time yourself, never log a past hand-off as if it were now; a late entry says "late" in its
summary) and refreshes the tracker files. A brief is a file in briefs/ before its brief event; a report is a
file in reports/ before its handback or review event. Fields:
{"ts","actor","to","kind","ref","summary","artifact"} with kind one of brief, handback,
status, clarification, criteria_change, review, verdict, fix_brief, verify,
fallback, hang, quota, question, answer, decision, staff_request, staff_approved,
join, milestone_ready, milestone_accepted, milestone_rejected, test_dispute. A gate's result is a verdict
event with ref = the gate id. Full texts live in briefs/ and reports/;
the event points at them. milestone_ready (to the owner, ref M<n>, once its test plan runs clean) puts the
milestone on "Your review"; the owner's milestone_accepted (actor owner) unlocks its merges;
milestone_rejected sends it back to its stages.
This is the trail the owner's live view is drawn from, so it starts at the first brief.
Track mode (two levels of managers)
Switch it on in the architect pass when both hold: there are 2 or more tracks that can run in
parallel, and the run will outlast one working session (about a day, or more than ~12 stages).
Otherwise staffing: single and everything above applies unchanged. How managers start, wake and check in is in
your harness file.
| Role | Does | Never does |
| Orchestrator (this session) | Architect pass; owns orchestration.md global parts, staffing.yaml approvals, contracts, standing orders; starts every manager; runs each milestone's test plan; the only one who talks to the owner | build; micro-manage a track |
Track manager (profile manager model) | Runs one track per its charter (track-mode/CHARTER.md, filled per manager): dispatches stages through the launcher as soon as their inputs are gated (or provisional, per the charter), verifies each stage, runs the gate, clarifies and tightens criteria, requests sub-managers, escalates | build; talk to the owner; loosen a criterion; start a manager |
- Coordination folder
_runs/<run>/_coord/— one writer per file:orchestration.md(orchestrator; each manager edits only its own track's section),staffing.yaml(managers addrequestedrows; only the orchestrator setsapproved/active/retiredand starts managers; cap 4 live, 3 levels deep),profile.yaml,standing-orders.md,contracts/(orchestrator),tracks/<id>.md(that manager's status, in-flight jobs, evidence),shared/<actor>.md(facts other tracks need, append-only),questions.md,events/. - Worker launcher (Windows with opencode workers; elsewhere workers start as your harness file says and you
write their events) — where it runs, every opencode builder, reviewer and tester goes through it, never directly. See
track-mode/LAUNCHER.md: oneopencode serveshared by the run, a pool of slots, and thebrief/handback/hang/quotaevents written for you. The orchestrator runslauncher.py --coord _runs/<run>/_coord startbefore the first brief andstopat the end; each check-in runshealthand restarts the pool when it saysDOWN. - Live view — the build tracker (
dashboard/tracker.html) drawn from the run's files bytrack-mode/live.py(needs PyYAML). The architect pass writes_coord/plan.yaml(milestones withaddsanddone_when; stages withmilestone,kind,title,needs,builder,track, and gate fields; seereferences/gates.md); the rest comes from the events, the launcher,staffing.yaml,tracks/andquestions.md. At a glance: now / waiting on, a needs-attention box (open questions, stuck stages, staff requests; hidden when empty), the team line, milestones, the dependency map (from 5 milestones up: a milestone map on top, and tapping a milestone shows the map of its stages), and per stage its manager, worker, live job time and provisional tag; a Map / Timeline switch (timeline: one bar per stage, grouped by manager, coloured by phase, with stuck and question marks); and "Managers and their agents": the orchestrator on top with what waits on it, then each manager with its stages, the agents working for it now and its open asks. On click: iterations, log and every hand-off of a stage; the staffing tree, slots and track files. The page never changes: all data is onerun.jsonbeside it, which a locally served page re-reads every 10 s and anyone may edit (a published copy changes only when you republish it).live.py build --coord <dir>writes it;live.py serve --coord <dir>serves the page locally; showing it to the owner is a harness step. The owner answers questions where they see the run. Everyquestionevent carriesqid, and when it is for the owner,optionsandrecommended. A question you pass on keeps the manager'sqid, so the view shows who raised it and each hop it took. Log oneanswerevent perqid(actorowner), act on the answers, then refresh the view. Events may carrystate,verdict,provisional_onorqidto make stage states exact; fix rounds go through the launcher with--fix. - Two channels. Updates and facts go to files (
tracks/<id>.md,shared/, events); the orchestrator reads them at every check-in. A manager ends its turn only for a question that blocks: it appends it toquestions.md, returns with its id, and is resumed with the answer. - Wake on handback, in any staffing. Pick up a finished job the moment it hands back (
handback|hang|quota|failedinevents/launcher.jsonl), the way your harness file says. In one run a 30-minute check-in alone left jobs sitting finished for about 3 hours. - Restart. The orchestrator's check-in ("Staying on track") also reads
staffing.yamland the track files, restarts any dead or silent manager from its track file with a resume brief, and sends the owner the update, at most hourly (unless the profile says otherwise), the way the harness file says. A fresh orchestrator rebuilds the run from_coord/.
launcher.py is Windows-only (ctypes, taskkill) and drives opencode workers only; elsewhere, run workers through your harness's own
subagents or CLIs and write the same events by hand.
Dashboard
When the owner asks for a dashboard, tracker or progress page, use dashboard/ (tracker.html and packet.html)
fed by track-mode/live.py, shown the way your harness file says. Never hand-build a new page per project. Keep it
true, or it is worse than none: refresh it at every stage transition and every build, review and fix round, and
mark anything added after planning as added (never renumber planned items).
The test plan is the deliverable
A milestone is done when the owner can sit down and try it — not when its tests pass. Write
TEST_PLAN_M<n>.md into the run folder and put it in chat; at the human gate it sits inside the review packet
(references/packet.md, read it before the gate). Required parts, in this order:
- Where — worktree path and branch, and copy-pasteable start commands with ports.
- What changed — 3–6 lines in the owner's terms.
- Steps — numbered, each with its expected result: first the milestone's
done_whenitems, one or more steps each, then the rest. Phone viewport first where the project has one. Include the negative cases: non-admin, offline, empty state. - A label on every step —
free,paid (~$X), ordo-not-run. The owner must never discover they spent money by following your plan. - Data safety — which steps write, and to which database, named.
- Known gaps — what this milestone deliberately does not do yet.
Run the whole plan yourself first. A test plan whose first command fails is the most common way this skill fails. If a milestone has nothing to show on real data, say so and seed the data — do not write "observe the heading render" when no heading exists.
Two gates every multi-stage run needs before "ready", because stage gates miss what crosses stages:
- Milestone review on the top of the stack by the strongest reviewer the run sheet names. It finds what green stage gates and CI let through, because each stage gate sees only its own diff.
- End-to-end on real saved data across every repo the run touched, no live traffic: the real chain
(export → next tool → import → the client file), plus the app started on a throw-away copy and clicked.
Write it as
TEST_PLAN_E2E.md. On the same run it found 8 seams no single-repo plan could see (a hint printing the old unguarded command, contacts lost to invisible characters, a match file nothing read).
Before the owner sits down
- Answer "where is the work?" from
git worktree list, not from memory. Run it, paste the path, name the branch. A guessed path sends them into the wrong tree. - Check whether the risky thing already happened. Agents ran overnight against real config. If a migration could have touched production, go read production (SELECT only) with a raw client — never the app's own connection helper, which may migrate — and report what you find, unprompted, before planning around it.
- Verify the environment the plan will run in before starting anything: which database the local stack resolves to, which keys are live, which ports.
- Lead with their actual question. Findings come after the answer, not before it.
Red flags — stop
- "It was a one-liner so I did it myself"
- "'Get things done' means I can merge a milestone or push to the base branch"
- "I offered 'merge all' and they said 'go with your recommendation', so that's a yes to merging"
- "The worker said the tests pass"
- "I'm treating this as obviously-yes and doing it"
- "This is reversible, so it's fine"
- "I'll ask, and meanwhile start"
- "I'll just start the server to check something" — against a config you have not resolved
- "It's only an additive migration"
- Naming a path, a config key, or a CLI flag you did not just read
Every one of these means: stop, verify, or ask.
Rationalizations
| Excuse | Reality |
| "They said get it done (or init and start) — that authorizes merging the milestone" | It authorizes working: stage branches, stage PRs, stage merges into the milestone. Milestone merges and anything on the base branch are the owner's words, used when meant. |
| "Committing is reversible, losing the work isn't" | Commit locally then. Local commit preserves the work and asks nothing of them. |
| "Asking would waste their night" | Being asked one question costs them a minute. Undoing an unwanted push costs an hour. |
| "The .env obviously needs changing" | Change the process env, not their file. If the file must change, it is one uncommitted line and you say so. |
| "I'll split it into per-milestone commits so it's reviewable" | If the milestones share files, the split is cosmetic and the intermediate branches are unprovable. Ship the test plans instead. |
| "The 300 green tests prove it works" | They prove it does not crash on fixtures. Nothing here has run against their real data. |
| "I know where that worktree is" | Dozens of worktrees can exist, and some are off limits. Run git worktree list. |
| "I only read from production, I never called a write endpoint" | Connecting can migrate. Starting the API can reconcile. Neither needs an endpoint. |
| "The migration is additive, so it's harmless" | Harmless is not the test. Permission is the test, and it is per-occasion. |
| "A gate on this stage is overkill" | The gate is the only thing between this and vibes. |
Standing rules
- A merge into the base branch needs the owner's words naming it ("merge M2", "merge all into main"). "Accepted", "carry on", "go ahead" or "go with your recommendation" never count, even right after you offered merging as an option: accepting a milestone is not merging it. Ask once more, naming the merge, and wait.
- Nothing reaches the base branch (dev / main) or a milestone merge unless the owner asked. Standing permissions: a worker commits to its own stage branch after each step, locally; the foreman pushes stage and milestone branches, opens their PRs, and merges a gated stage into its milestone branch.
- No production write without the owner's explicit say-so, every time. There is no standing
permission and "it was only additive" is not an exemption. Starting a service is a write when
its config resolves to production — schema migrations and startup reconcilers fire on the first
connection, before any endpoint is called. So resolve the DB target before anything listens.
Point the local stack at a local database, and blank the production credentials in the process
environment rather than editing the owner's
.env. If a production write already happened, disclose it unprompted — what changed, what was lost, what it cost — and never repair it with a second write. - Never delegate verification.
- Judge/review/test artifacts → the run folder (
_runs/<run>/M<n>/), never committed. - No local filesystem path in a PR title, body, comment, or committed file.
- Additive schema changes only; never drop or reset a table to make a build pass.
- A blocked stage stops that stage, not the run. Finish everything unblocked, then say exactly what is left and why.
- Bulk git cleanup snapshots its target list once, before acting, and never runs while builds start: a lazy per-repo listing removes build worktrees created while it runs.
- Long verification runs in the foreground in chunks under 10 minutes, or as a launcher job. Background test runs and wrapper processes were reaped under memory pressure while the session idled; watch worker PIDs, not wrappers. Agent-tool subagents notify on their own and survived every reap.
- A stage gate runs what CI runs. Name the exact command CI uses (e.g.
pytest tests/, not three subfolders), and, where the repo has CI, treat a green CI run on the pushed head as part of READY (withstage_prs: local, the gate's own run of that command is the evidence). Builders that run only the folders they touched miss failures elsewhere. - Never cancel a running
DROP DATABASE: it can leave the database invalid. If it hangs on a checkpoint, use a new database name instead. - Standing rules a brief pastes in must not name a model: a commit-trailer line naming the previous builder made the next one sign as the wrong model. Say "the model that did the work".
- Cap heavy agents at 2 concurrently on Windows: above that, process creation fails with
0xC0000142. Opencode jobs go through the launcher's singleopencode serve(an attached run is one process), never as parallel standaloneopencode runs — those lock its database.
After the run: post-mortem
Every run ends with postmortems/<yyyy-mm-dd>-<slug>.md (where: LOCAL.md, else beside the run folders): numbers (stages GO, jobs, fix rounds, first-pass review rate, time per stage, interventions, model usage where the harness reports it, e.g. Claude Code via track-mode/usage_split.py), what went well, what went wrong with root cause and a proposed skill change, and how each agent behaved. Open problems from earlier post-mortems are read before the next run sheet.
Share new ratings (one yes/no question). At the end of the run, python <skill>/scores/runs.py pending. If it
prints anything (a model or job the shipped table has no score for, or fewer than 5 runs) and setup.yaml does not
say share_ratings: never, run runs.py share and ask its question as written. On yes, show the rows it will send
and give the link; the owner submits it themselves (nothing is sent for them). Then runs.py mark yes (or no). If
they say never, save share_ratings: never with setup/store.py. Only model, job, harness, month, Foreman version
and the seven grades go out; never a project name, path, brief or note.
Companion skills — call them, do not reimplement
companions.yaml lists them: what each is for, where to get it, and its built-in fallback. Installed: use it.
Missing: read its fallback before that job and say once which skill was missing. Briefs and grading workers:
references/briefs.md. Reviews and gates: references/review.md. Handback checks and worker CLIs:
references/workers.md. Keys, accounts and spend: references/keys.md. The project's own test skill, when it has
one, is executed by the tester rather than improvised around.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

