Skip to content

mattvideoproductions/MVP-Prompts / skills/foreman

foreman

Verified

Be 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.

references/audit.md

View on GitHub
# Audit record

The skill was built in two rounds. Round 1 audited the draft manual, titled "Lead-and-lanes orchestration", of 12 November 2026. Round 2 audited three field reports, written by the leads of three other projects after reading that manual, plus an independent recount of the first build. This file records what each round kept, changed and declined, how well each rule is supported, and what is still open.

Contents: [nothing removed](#nothing-was-removed) · [round 1](#round-1-the-draft-manual) · [round 2](#round-2-the-field-reports) · [evidence status](#evidence-status) · [open questions](#open-questions) · [not verified](#not-verified)

## Nothing was removed

Every rule, table, template, reference-build note and recommendation in the draft is still in the skill. Three were reshaped by round 2 and are marked below: the turn budget became a token budget, "three strikes" became a ceiling with a price-aware allowance under it, and "numbers before pictures" became "numbers first, then one cheap look".

## Round 1: the draft manual

1. **"Start low" and "default to standard" said different things.** Settled on standard as the default with a written reason for anything higher. (Refined again in round 2.)
2. **A strike was not defined.** It is one lead-verified failed pass at the current tier. A worker's attempts inside its own pass are not strikes.
3. **A bad brief could cause a promotion.** Before each strike the lead asks whether a stronger model with the same brief would have passed. If not, the brief is fixed and the count does not move.
4. **"Improves little" had no measure.** A plateau is less than about a quarter of the remaining gap closed, or the same rows failing the same way.
5. **The ladder had no top.** A lead that strikes out goes to the owner with the numbers and five named choices.
6. **The worker being measured could change the measure.** Gate files are the lead's, and a worker diff that touches one is rejected.
7. **"Never loosened" left no honest way to correct a bar.** The owner changes it, dated, with the old bar kept. A snapshot comparison flags any other change.
8. **Shared files had no owner.** They belong to the lead.
9. **The lead's own lane had no second reader.** It always gets a fresh checker.
10. **There was no rule for when not to use the system.** The skill opens with a size check.
11. **The recommendations depended on the lead remembering them.** They are checked by `orch.py pass-end`.
12. **Nothing limited how many lanes ran at once.** Start only as many as can be verified.
13. **The plan of record had no place for the gates.** Gates, known failures and bar changes are sections.
14. **The worker report had no place to ask for an outside edit or report a tool trap.**

Two features were added: the per-pass cost ledger and the mistake register.

## Round 2: the field reports

Three leads read the manual against their own projects: reverse engineering on a real hardware device with a media production (B), an interactive product built mostly by the lead and the owner (C), and an interactive product with 75 worker transcripts and continuous owner feedback (D). One of them also recounted the first build's cost. The first build is Project A. The projects are anonymised in this published copy.

### Checks on the reports' own numbers

Before using a report, its arithmetic was checked.

| Claim | Check |
|---|---|
| The first build's worker costs match an independent recount exactly. | The recount used the same price method as `orch.py`, written separately. Accepted. |
| Trying Sonnet first costs 0.5 + (1 − p) Opus-units and wins only when p is above 0.5. | Correct if both attempts use about the same tokens and a failed attempt leaves nothing behind. General form: with price ratio r, cheaper-first wins when p is above r. |
| Three Sonnet strikes can burn 1.5 Opus-equivalents. | 3 × 0.5. Correct under the same assumption. |
| A standard-tier response cost 28% less than a senior-tier response in the first build. | Recomputed from the tier totals and response counts. Correct. But these are different tasks at different context sizes, so it is a caution about the ratio, not a measurement of it. |
| In C a lead response cost more than twice a senior worker's. | Recomputed from the tier totals and response counts. Correct. |
| D: the senior tier was 76% of worker cost. | Recomputed from the tier totals. Correct. |
| B: lead share 33%. | Correct for the development sessions only. |

One figure was derived here and is not in the reports: C's senior-or-above share of worker responses is (1,400 + 125) / 1,551, or 98%.

### Adopted as proposed

| Finding | From | What changed |
|---|---|---|
| Budget context by size, not turns. | B, C, D | Worker budget is 200K tokens. `orch.py` measures the largest context and fails the pass check past the budget. The 60-turn figure is gone. |
| The lead's own session is a major cost and has no budget. | B, C, D | Lead budget of 300K tokens, a fresh lead session per milestone, a handoff before any long break. The script reports the lead's share, its largest context, and what was spent rewriting context after idle gaps. |
| Check the deployed copy, not only the build. | B, D | Freshness is a chain: source, build, the copy running. |
| Test what ships means the real input path and the real hardware. | B, C, D | Stated in Verification, the brief's GATE line and register entry M05. All four projects had a test path that differed from the shipping one. |
| Lanes need locks on exclusive resources. | B, D | A required line in the environment contract, checked by the script. |
| Every experimental task needs a kill rule. | B | A KILL RULE part in both brief templates, checked before sending. |
| On hardware projects the owner is a correctness gate. | B | Owner-run gates in the gate table, owner checklists, batching, a cap on asks. |
| Evidence built for the owner's judgement converges fastest; get a build to the owner every pass. | C, D | Step 7 of the pass loop, and a section on evidence. |
| Log owner notes verbatim with an id, route them, confirm back. | D | An Owner notes section, checked by the script. |
| A rule for guessing versus asking. | C, D | Guess when a wrong guess is cheap to undo and flag it; otherwise ask. GUESSED line in reports. |
| Keep the owner informed during long turns. | C | In Working with the owner. |
| Explicit approvals lock things. | D | Approved and locked list. |
| 150-word reports squeeze out the most useful lines. | D | The top of a report stays short and the bottom has no cap. |
| The lead's worst errors were false claims in its own reports. | B | Register entry M22 at the owner-report checkpoint; fresh checker for owner reports. |
| A short look at ordinary use each pass. | D | Step 6 of the pass loop; register entry M21. |
| The process needs a solo mode and a way to skip itself for small changes. | B, C | "Pick the weight first." |
| Raw session totals double-count continued sessions. | B | The script already counted each response once across files. Now documented. |

### Adopted with changes

**One strike from standard to senior (B).** Adopted as the default at a 2x price gap, with a second attempt allowed only when the first closed most of the gap, and a hard stop at two. Three strikes stays as the ceiling and as the allowance at the light tier, where the gap is 20x. Two things kept this from being adopted as a flat "one strike". First, the argument assumes a failed attempt leaves nothing useful, and the promoted brief exists to carry what it learned. Second, the argument turns on how often the standard tier succeeds, and none of the four projects measured that. `orch.py cost lanes` now does. D's experience points the same way as the argument: an Opus lane went four rounds before a stronger model cleared it in one.

**"Default to standard is an experiment" (C).** Kept as the default, for work that is well specified and cheap to check, because that is exactly where Sonnet lanes finished in two projects. Made conditional on what a miss costs: where a failed attempt reaches the owner's hardware, start at the tier most likely to be right, and write that as the reason. The per-finished-row cost in `cost lanes` is the measurement C asked for.

**"The lead solves the hard part first does not fit research" (B), and "design decided is too strong" (D).** Adopted as a second kind of brief for discovery, where the lead's thinking is the list of suspects and the test for each. "Design decided" is kept for build work, because a worker that picks its own design leaves the lead verifying something it never specified, and because design-carrying briefs are what made first passes land. What changed for build briefs is that disagreement is now asked for on the record.

**"The lead reads conclusions, not files, would have been wrong here" (C).** Scoped. Searching and surveying are delegated. Code the lead will change or verify, it reads.

**"Numbers before pictures is too strong" (C, D).** Now "numbers first, then one cheap look", every round, for anything seen or heard. Small pictures are kept.

**"Quality is decided by checks is wrong for this kind of product" (D).** Adopted more broadly than proposed, since it holds for anything a person perceives. Verification is now three questions with three owners, and rule 5 says a gate is necessary and not sufficient.

**"Bars never move needs two classes" (C, D).** Adopted the labelling: each bar is marked as the owner's or the lead's, and a design change is logged as a spec change. Not adopted: letting the lead revise a target it has missed. D's missed targets were "acceptable", and the one who accepts is the owner, so that is the third legitimate route. The reports themselves supply the reason for caution: one lane loosened its own limit mid-work, and one product change was made partly to steady a test.

**"A 60-turn cap would have hurt; resume the same agent" (D).** Adopted the resume rule for same-scope follow-ups. The budget itself stays, in tokens, because D's own figures show the cost of long agents: 17 transcripts past 150 responses, the longest 375, and re-reading at 54% to 57% of worker cost.

**"Side questions belong in a separate cheap session" (B).** This is the owner's habit to change, not the lead's, and refusing a question costs the same turn as answering it. The skill has the lead say so once, with the per-response figure, and send its own side lookups to a light worker.

**"Cost is really plan limits" (B).** The API-equivalent figure is kept as the yardstick because it is the only one that can be counted, and is labelled as not a bill wherever it appears. The owner's messages per pass are now counted as a measure of their time. Usage windows cannot be measured from transcripts.

**"Tasks under about 30 minutes skip the ledger and briefs" (B).** Adopted. They keep their gate and a Status log line. The 30 minutes is one lead's estimate.

### Not adopted

- **Lanes sharing one file by region (D)** as a pattern. It mostly held and still broke the build twice. The rule stays; the guidance is to split the file or run the lanes in turn. The two fixes that worked there, frozen-copy captures and TEST marks, are adopted.
- **Dropping the re-reading measure because cached reads are cheap per token (C).** Per token, yes. In total it was still 32% to 58% of cost everywhere it was measured, so it stays in the report beside the rewrite figure. The trade between them is what the context budget tunes.

### Where the reports disagreed with each other

| Question | One view | Another | Resolution |
|---|---|---|---|
| Does start-low work? | C: weaker than it looks. | B: clearly worked for an editing task. D: Sonnet carried six areas. | It works where the task is well briefed and cheap to check. That is now the stated condition. |
| Should agents be retired early? | D: resuming was faster. | A, B, C: long contexts were the main waste. | Resume within scope and budget. Hand off past either. |
| Should the brief decide the design? | D: lanes overturned it four times. | A: deciding it is what made first passes land. | Decide it for build work and ask for disagreement. Do not decide it for discovery. |

## Evidence status

**Held** means it was practised and worked. **Seen** means the opposite was observed to fail, in the number of projects shown, but the rule itself has not been run. **Untested** means it rests on argument.

| Rule or feature | Status | Projects |
|---|---|---|
| State in files, reasons beside decisions | Held | 4 |
| Briefs carry reasoning and the owner's words | Held | 3 |
| Misses reported as misses | Held | 2 |
| Environment contract, tool quirks written down | Held | 3 |
| Pass cap set by the owner | Held | 1 |
| Unverified-by-a-person stated | Held | 2 |
| Standard tier finishes well-briefed, easily checked work | Held | 2 |
| Evidence built for the owner's judgement | Held | 2 |
| Approvals lock the approved thing | Held | 1 |
| Test what ships, through the real input path | Seen | 4 |
| Fresh checker; the lead's work is the least checked | Seen | 4 |
| Cost metered each pass | Seen | 3 |
| Work starts too high | Seen | 4 |
| Contexts grow too large, the lead's most of all | Seen | 4 |
| Checks pass while the product is visibly wrong | Seen | 2 |
| Freshness of build and deployed copy | Seen | 3 |
| Lane ledger kept current | Seen | 2 |
| Known-failures list | Seen | 2 |
| Exclusive-resource rules | Seen | 2 |
| Promote early at a small price gap | Seen once, argued | 1 |
| Owner notes log, guess-or-ask rule | Seen | 2 |
| Kill rule | Seen | 1 |
| Strike and plateau definitions, charging the brief | Untested | |
| Token budgets of 200K and 300K | Untested | |
| Strike allowances of 3, 2, 2, 3 | Untested | |
| The cost ledger and mistake register as working practice | Untested | The cost arithmetic is verified. |

## Open questions

Each names the number that would settle it. The first four can now be read from `orch.py`.

1. **How often does each tier finish what it is given?** `cost lanes`, "finished here". This decides the strike allowances and the default tier.
2. **What does a finished task cost by starting tier?** `cost lanes`, "cost per finished row", compared across similar lanes.
3. **Where should the context budgets sit?** Compare re-read%, the cost of starting agents and worker context across passes run at different budgets.
4. **Does a fresh lead session per milestone cut the lead's share?** Compare lead% and rewrite% before and after.
5. **How often is a failure the brief's fault?** Count strikes withheld. A high count says the briefs need work more than the tiers do.
6. **Does the fresh checker earn its cost?** Count disagreements, and how many were right. D's real-input lane found seven bugs; that is one data point.
7. **Is the overhead worth it?** No project has run the bookkeeping. Watch whether lead% rises without the total falling.
8. **Which questions get answered lazily?** Read the evidence notes in `mistake_log.jsonl`.
9. **How much owner time does a pass take, and does batching reduce it?** Owner messages per pass, and the count of owner test sessions.
10. **Do discovery briefs shorten searches?** Compare rounds to a finding with and without suspects and tests written first.
11. **What did the four projects cost per pass?** Only totals are known. If the transcripts still exist, running `orch.py cost record` over them pass by pass would give the first real trend lines.

## Not verified

- The skill has not been run on a project. `orch.py` has been tested against one real session with one sub-agent, and against synthetic projects built to trip each check.
- The three field projects' figures are quoted from their leads' reports. Only the first build's were recounted independently, and that recount is also quoted.
- Cache-write prices for Opus 5.5, Sonnet 5.5 and Haiku 5.5, and the Haiku 5.5 cache-read price, are derived from the published multipliers. The field recount used the same assumptions.
- Rewrite detection and the owner-message count have been tested on synthetic transcripts and on one real session with no idle gaps.
- The cost reader has been tested only on Claude Code transcripts from one version.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall