mattvideoproductions/MVP-Prompts / skills/foreman
foreman
VerifiedBe the foreman on a big job. One lead model plans the work, hands pieces to helper agents in lanes that never share files, checks everything before accepting it and reports the cost; or runs a long solo build with an owner in the loop. Covers the North Star plan of record, briefs that carry the lead's reasoning, measured gates plus the owner's judgement, strike-based promotion between model tiers, a cost ledger and a mistake register every pass is checked against. Use it when the user types /foreman, says "be the foreman", "be the lead" or "orchestrate this", asks to delegate to subagents or run lanes or passes, or mentions a North Star, three strikes, tiers or promotion between models. Also load it when a task looks too big for one context or needs several agents or days, even if not asked by name; the skill then has you offer it and wait for a yes. Also use it to resume such a project, close a pass, report a session's cost or record a mistake. Not for a change one agent can finish in one sitting.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 32.2 KB |
| assets/NORTH_STAR.template.md | markdown | 4.3 KB |
| assets/brief.template.md | markdown | 1.8 KB |
| assets/config.default.json | config | 2.2 KB |
| assets/discovery-brief.template.md | markdown | 1.8 KB |
| assets/handoff.template.md | markdown | 611 B |
| assets/mistakes.seed.jsonl | other | 21.9 KB |
| assets/prices.json | config | 1.7 KB |
| assets/promoted-brief.addendum.md | markdown | 673 B |
| assets/report.template.md | markdown | 804 B |
| references/audit.md | markdown | 15.9 KB |
| references/briefs-and-handoffs.md | markdown | 10.9 KB |
| references/cost-and-mistakes.md | markdown | 16.5 KB |
| references/field-data.md | markdown | 9.1 KB |
| references/north-star.md | markdown | 11.0 KB |
| references/reference-build.md | markdown | 8.0 KB |
| references/skeleton.md | markdown | 4.3 KB |
| scripts/orch.py | script | 59.5 KB |
references/briefs-and-handoffs.md
View on GitHub# Briefs, reports, handoffs and evidence
Templates are in `assets/`: `brief.template.md`, `discovery-brief.template.md`, `promoted-brief.addendum.md`, `report.template.md`, `handoff.template.md`.
## Why the brief matters most
The brief is the only thing a worker knows. The first wave of briefs in this system's history were lists of deliverables, and first passes missed. The owner corrected that: the point of orchestration is to pass the lead's intellect down. Briefs after that carried the chosen architecture, the parameters and the pitfalls, and first passes landed more often. In later projects the lanes that landed first time had the owner's exact words, where to look, and the suspected causes.
So the lead thinks first and writes the thinking down. What that thinking looks like depends on whether the answer is known.
## Two kinds of brief
**Build brief.** The lead knows what should be built and has chosen how. The worker implements a design. It does not pick one.
**Discovery brief.** The answer is not known yet: a cause to find, a format to reverse engineer, a question to research. The lead cannot solve this in advance, and pretending to produces a worker that confirms the lead's guess. In one reverse-engineering project the decisive fact was found, not designed. Another had its diagnoses overturned by its lanes at least four times. So the lead writes its candidate explanations in order of likelihood and, for each, the test and result that would rule it out. Each worker gets one to try to disprove, and measures before changing anything.
| Part | Build brief | Discovery brief |
|---|---|---|
| GOAL | What the task is for, which line of the North Star it serves, the owner's exact words if it came from a note. | The question, and what evidence would count as an answer, decided before looking. |
| DESIGN / SUSPECTS | The approach the lead chose, with the reason. | The candidate explanations, each with the test that would rule it out, and which one is this worker's. |
| NUMBERS | Targets, budgets, sizes, limits. | (Usually none.) |
| EXPECTED FAILURES | How this usually goes wrong, and how to avoid each. | How this kind of search goes wrong. |
| ALREADY RULED OUT | What was tried or rejected. Write "nothing yet" on a first attempt. | What has been tested and excluded, with the evidence. |
| FILES | What the lane owns, what it must not touch, what to read first. | The same, plus where findings are written. |
| STANDING LIMITS | The environment-contract rules that apply, quoted, including exclusive resources and how to take a turn. | The same. |
| GATE | The exact command at the shipping configuration, the number, the bar, and the capture to attach. | The procedure that reproduces the finding from scratch. Pass is yes or no. |
| STOP AND REPORT IF | When to stop instead of grinding. | The same; plus "two tests in a row tell you nothing new". |
| KILL RULE | When to abandon the task and record why, or "not an experiment". | When to abandon this line of inquiry. |
| REPORT | The report format. | The same, with every fact found under FINDINGS. |
Lines in the templates that start with `>` are standing guidance for the worker. Leave them in.
## Before sending
1. **Cold-reader test.** Reread the brief as if it were the only message ever received. If any step needs something that exists only in the conversation, add it.
2. **Question, not conclusion.** If the brief says "confirm that X", rewrite it as "find out whether X".
3. **Run the check.** Save the brief to a file and run:
```bash
python3 <skill>/scripts/orch.py mistakes check --at brief --brief briefs/ui-pass2.md
```
It fails a brief whose DESIGN, NUMBERS, EXPECTED FAILURES or ALREADY RULED OUT is empty (for a discovery brief: SUSPECTS with a test for each, EXPECTED FAILURES, ALREADY RULED OUT), or that has no real `Run:` and `Pass:` line, no `Yours:` and `Do not touch:` line, no stop conditions, or no kill rule.
## Design decided, disagreement welcome
"Implement this design" and "tell me if the design is wrong" are both true. The worker does not choose a different design on its own, because then the lead is verifying something it never specified. It also does not implement a design it can see is wrong. It measures, and puts the measurement under DISAGREE in its report. The lead decides.
## File and resource ownership
- A lane owns a set of files and no other lane writes them.
- The "do not touch" list always includes the gate scripts, the North Star, `.orchestration/` and every other lane's files.
- Shared files that several lanes need changed belong to the lead. A worker who needs a change there describes the edit under NEEDS LEAD, and the lead makes it at integration.
- If several lanes must change one large file, split it first or run the lanes in turn. Ownership by region inside one file broke a project's build twice.
- If a worker's change touches a gate file, reject the change. If the gate really is wrong, the worker says so in its report and the lead fixes it.
- Anything only one agent can use at a time is named in STANDING LIMITS with how to take a turn: an emulator, a device, a browser, the owner's screen.
- Unfinished output that the owner might see carries a visible TEST mark, and captures are taken from a frozen copy of the project so half-done work from another lane is not in the frame.
## Stop conditions and the kill rule
Stop conditions end a worker's pass and send it back to the lead:
- the same failure survives two attempts
- the fix needs a file or resource outside the lane
- the worker's context passes the budget
- the gate itself looks wrong
Two attempts inside one worker's pass are not two strikes. A strike is counted by the lead, once per pass, after it has rerun the gate.
The kill rule ends the task. It is written before the work starts, for the same reason a bar is. Example: "if two hardware runs crash the same way, abandon the mode and record why." One project spent several crash cycles on real hardware, each costing the owner a manual test, before dropping a feature with no such rule. A dropped lane is recorded as `dropped` with its reason, and a failure that is told honestly is still a result.
## Promoted briefs
When a lane reaches its strike allowance or stalls, the task moves up one tier and the new agent gets the original brief plus two parts from `assets/promoted-brief.addendum.md`:
- **TRIED AT THE LOWER TIER**: each attempt, the gate number it reached against the bar, and why it failed as far as is known.
- **LEAD'S DIAGNOSIS**: why the lower tier could not do it, what in the original brief was wrong or missing, and the question the lead is least sure of.
Before promoting, decide who the failure belongs to. If a stronger model given the same brief would also have failed, the brief is the problem. Fix it and rerun at the same tier without adding a strike.
Sometimes the promotion is a reframing and not just a stronger model. A lane that stalled for four rounds on one defect was cleared in one round when a lead-strength agent recast the problem as a single solver.
## Fresh-checker briefs
A checker confirms or refutes a claim independently, so it must not be told the answer.
Give it: the work (paths), the gate command and bar, the North Star section that defines what the work is for, and the question "does this do what that section requires, and does the gate measure it?" Where the product takes input, tell it to drive the real input path.
Leave out: the lead's conclusion, the worker's report, and any statement that the gate passed.
Use one for the lead's own lane every pass, for the one thing, for any go or no-go milestone, for a result that surprised you, and for the claims in a report to the owner. A checker that never disagrees is not checking. If it disagrees, find out who is right before accepting the lane.
## Worker reports
```
CHANGED <files, one line each>
GATE <command> -> <number> against <bar>: PASS / FAIL
OTHER GATES <any that moved, with numbers>
LOOK <path to the small capture, for anything seen or heard>
STILL WRONG <open problems, stated plainly>
NOT CHECKED <what you did not or could not verify>
RISKY <what might break something else, and where>
GUESSED <anything unclear in the brief that you assumed, and what you assumed>
DISAGREE <where you think the brief's design or diagnosis is wrong, with the measurement>
FINDINGS <facts discovered, each with how it was verified>
NEEDS LEAD <edits you need outside your files; traps you hit in the tools>
PATHS <outputs and evidence>
```
The first four lines stay short. The rest get the room they need: a field lead found the "not done, risky, needs from others" lines were the most valuable part and that a 150-word cap squeezed them out.
A report is a claim. The lead reruns the gate, reads the changes and looks at the capture before accepting it. Tool traps under NEEDS LEAD go straight into Tool quirks. Anything under GUESSED goes into the owner notes log if it concerns what the owner meant.
## Handoffs
A handoff lets a new agent continue without the old agent's context. It is worth making when the context has grown past its budget or the scope is changing. For a follow-up in the same scope, resuming the same agent is cheaper and faster.
```
# Handoff - <lane or pass> - <date>
STATE <what works now, in two or three lines>
THIS PASS <what changed>
GATES <table: gate, number, bar, pass or fail>
OPEN <problems, each with what is known about the cause>
TRIED <approaches that did not work, so they are not repeated>
FINDINGS <facts that took work to find, each with how it was verified>
STRIKES <n at the <tier> tier; last two gate numbers>
NEXT <the single next step>
COMMANDS <exact build, run and check commands, including tool quirks>
```
- FINDINGS matters most in research work. Accumulated facts are the valuable part of a long context, and a handoff that drops them makes the next agent find the same addresses again.
- STRIKES carries the last two gate numbers so the next reader can see whether the lane is still improving.
- The lead writes one for the whole pass, and uses it to start a fresh lead session at each milestone and before any long break.
## Evidence for the owner
The owner decides whether the work is good, so build what goes to them for judging, not for reading.
- **Numbered items.** A reel of numbered sounds, a sheet of numbered frames. The owner answers "3 and 7 are wrong", and each answer maps to one thing. A numbered reel took one project's sound to approval in three rounds.
- **Before and after**, side by side, at the size they will be seen.
- **Short clips**, about twenty seconds, of the thing in ordinary use.
- **Something runnable**, every pass, with the list of what no person has checked.
- **A checklist** for anything only they can test, built so one session covers many items.
- **Nothing unmarked.** Test renders and stand-ins carry a visible TEST mark. About six of one owner's notes were about artefacts of unfinished work that had reached their screen.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |