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/cost-and-mistakes.md
View on GitHub# The cost ledger and the mistake register
Both are kept by `scripts/orch.py`, which needs only Python 3 and its standard library. Run it from the project root, or pass `--root PATH` before the command.
Contents: [state folder](#state-folder) · [closing a pass](#closing-a-pass) · [cost ledger](#the-cost-ledger) · [mistake register](#the-mistake-register) · [thresholds](#thresholds) · [adding a scripted check](#adding-a-scripted-check) · [limits](#known-limits)
## State folder
`orch.py init` creates `.orchestration/` in the project:
| File | Contents |
|---|---|
| `config.json` | Start time, thresholds, strike allowances, extra transcript locations, the "not counted" list. |
| `prices.json` | The price list this project is costed at, copied from the skill so that a later price change does not rewrite history. |
| `cost_ledger.jsonl` | One row per pass, plus any manual rows. Append only. |
| `mistakes.jsonl` | The register: the skill's seed list, lessons from earlier projects, and this project's own. |
| `mistake_log.jsonl` | Every check result, answer and promotion, with timestamps. Append only. |
| `snapshots/pass-N.md` | The North Star as it stood at the end of each pass. |
Commit this folder with the project. It is the project's memory of what it cost and what went wrong.
## Closing a pass
Do the lead's part of step 7 first: rewrite Current state, update the lane ledger, gate table and owner notes, append your Status log entry. Then:
```bash
python3 <skill>/scripts/orch.py pass-end --pass 3
```
In order, it:
1. Records the pass's cost from the transcripts (everything since the last recorded pass).
2. Prints the cost table for the pass and the trend over all passes, with a projection.
3. Rewrites the `Spend:` line in Current state.
4. Checks the North Star and compares it with the last snapshot.
5. Runs every register entry tagged `pass-end`.
6. Appends two lines to the Status log: the cost line and the mistake-check line.
7. Saves a snapshot, unless a bar moved without an entry or history was rewritten.
It can be run again. The cost is recorded once per pass (`--force` re-measures it). A new mistake-check line is appended only when the result has changed, so the log shows the first result and the corrected one.
Exit code 1 means a mistake repeated. Fix what can be fixed and run it again; the repeat stays on record. Exit code 2 means questions are waiting:
```bash
python3 <skill>/scripts/orch.py mistakes answer --id M13 --pass 3 --result clear \
--note "fresh checker a94f read the sim lane; disagreed on frame pacing; lead reran gate, checker was right, fixed"
```
## The cost ledger
### What is measured
Each model response in a Claude Code transcript carries its token usage. The script reads every transcript for the project and keeps one record per response. Streamed responses are written on several lines with the same id, and a session continued from an earlier one carries that session's history, so counting lines or adding raw session totals overcounts; one field project found its raw totals about a quarter too high. It prices four kinds of token separately: fresh input, output, cache writes (5-minute and 1-hour) and cache reads. It follows the per-iteration usage breakdown when one is present, so compaction and advisor calls are included.
A response from the main conversation counts as the lead's own. A response from a sub-agent transcript counts as a worker's. The tier comes from the model, through `prices.json`. Messages the owner typed are counted too.
By default it reads `~/.claude/projects/<project path with slashes as dashes>/`, including the `subagents/` folders. To read other locations, list them in `config.json` under `transcripts` or pass `--transcripts PATH ...`.
### Commands
| Command | Use |
|---|---|
| `cost now` | Cost since the last recorded pass. Records nothing. Use it mid-pass, and before deciding whether to hand the lead's session off. |
| `cost record --pass N` | Records a pass without the other checks. `pass-end` does this for you. |
| `cost add --pass N --label codex --cost 3.50 --tier independent --note "vendor invoice"` | Adds spend the transcripts cannot show. |
| `cost report` | Per-pass table, totals by tier, projection, ceiling, and what is not counted. |
| `cost lanes` | Cost of each lane-ledger row, cost per finished task, and how often each tier finished its work. |
### Reading the report
```
pass lead senior standard light other total running lead% senior% re-read% rewrite% workers worker ctx lead ctx owner msgs
1 $14.74 $4.43 $1.47 $0.01 $0.00 $20.65 $20.65 71% 43% 25% 27% 4 254K 379K 3
```
| Column | Meaning | Seen in the field | If it is high |
|---|---|---|---|
| lead% | The lead's own conversation as a share of the pass. | 17%, 27%, 33%, 52% | The lead is working alone in a large context. Hand off, or delegate. |
| senior% | Share of worker responses from the senior tier or above. | 61%, 78%, 89%, 98% | Look for ledger rows with no "Why this tier". |
| re-read% | Share of cost spent re-reading cached context. | 45% to 58% on worker tiers | Contexts are large. Check the two context columns. |
| rewrite% | Share of cost spent writing a context to the cache again after an idle gap, a compaction or a broken cache. | One project: about 16% of its cost on six cold resumes | Do not leave a large session idle. Hand off before a break. |
| worker ctx | The largest context any worker reached. | 232K to 384K re-read per response, with no budget | Compare with `context_budget_tokens`. |
| lead ctx | The largest context the lead reached. | 966K in two projects | Compare with `lead_context_budget_tokens`. Start a fresh lead session from the North Star. |
| owner msgs | Messages the owner typed in the pass. | 48 and about 114 over whole projects | How much of the owner's time the pass used. |
The lines under the pass table also give the cost of starting agents. Every new agent writes its starting context at the full rate, so that figure is what handoffs cost. Set it against re-read% when tuning the context budget: one falls as the other rises.
The projection is the mean cost of the last three passes times the passes left under the cap.
### Cost per lane, and the tier question
```
lane tier status strikes agents responses cost
hook standard promoted 1 1 30 $0.73
hook senior done 0 1 50 $4.43
tier rows done promoted dropped finished here cost cost per finished row
standard 2 0 1 0 0% $1.47 -
senior 1 1 0 0 100% $4.43 $4.43
```
`cost lanes` matches the ids in each row's Agent column to worker transcripts. "Finished here" is the share of closed rows at a tier that ended `done` and not `promoted` or `dropped`.
This is the number the strike allowances depend on. Trying a cheaper tier first costs its attempt and, when it fails, the dearer attempt as well. With a price ratio r between the two tiers (cheaper over dearer), trying the cheaper one first is worth it only when it finishes more often than r. Standard is half the price of senior per token, so standard-first pays when standard finishes more than half of what it is given. Per task the ratio is usually worse than the token prices suggest, because a weaker model may need more turns: in the first reference build a standard-tier response cost 0.71 of a senior-tier one, not 0.5. So use "cost per finished row" from this table, not the price list, when you retune.
Nobody had this number before the script existed. After a project or two it will say whether default-standard is earning its place for your kind of work.
### Honesty rules for cost
- The figure is API-equivalent at list prices on the date in `prices.json`. On a subscription it is not a bill, and the limits that bind are usage windows and the owner's time. Say so when reporting it.
- A model with no price entry is printed as `NOT PRICED` with its response count, on the pass and in every report. Add it to `prices.json` and run `cost record --pass N --force`.
- Anything billed outside the transcripts goes in `config.json` under `not_counted`, in plain words. It prints on every cost line. Leaving out another vendor's agent hides a real share of the work.
- Check `prices.json` against the current pricing page at the start of a project. Prices change, and cache-read rates differ by model.
## The mistake register
### An entry
```json
{"id": "M04", "title": "A stale build, or a stale deployed copy, was tested as if it were the new one",
"what": "A build command failed without an error and two test runs went against the old program.",
"cause": "The gate did not check that the thing under test was newer than the last source change.",
"rule": "Every gate first confirms the whole chain is fresh: source, build, and the copy actually running or deployed.",
"when": ["accept"], "checks": [{"kind": "manual"}],
"question": "What shows the gate ran against a build made after the last source change, and that the copy tested is that build?",
"level": "prose", "source": "reference build, observed twice",
"field": "Project B: the step that bit was the deployed copy against the build. Project D: some scripts only loaded because of a leftover cache file.",
"first_seen": "2026-11-12"}
```
`when` lists the checkpoints: `brief`, `accept`, `pass-end`, `owner-report`. `checks` lists how it is tested. `level` is how strongly the lesson is currently enforced. `field` is what later projects added.
The seed register has 27 entries: 19 from the first reference build and 8 from the three later projects.
### Commands
| Command | Use |
|---|---|
| `mistakes check --at brief --brief FILE` | Before sending a brief. |
| `mistakes check --at accept --pass N --lane NAME` | Before accepting a lane's result. This is also the record that the lane was verified. |
| `mistakes check --at owner-report --pass N` | Before reporting to the owner. |
| `mistakes answer --id ID --pass N [--at accept --lane NAME] --result clear\|repeat --note "evidence"` | Answers a question. The note must be evidence. |
| `mistakes add --title ... --what ... --cause ... --rule ... --question ... --when pass-end [--pass N]` | Registers a new mistake. With `--pass` it also records the first occurrence. |
| `mistakes report` | Each lesson's level, times checked, repeats, strikes, and which passes. |
| `mistakes promote --id ID --level template\|scripted\|owner --note "what changed"` | Strengthens a lesson. |
| `mistakes export [--to FILE]` | Merges this project's lessons into `~/.claude/foreman/mistakes.jsonl` for the next project's `init`. |
### Results
- **clear**: the check ran and the mistake is not present.
- **REPEATED**: the mistake is present. It is logged and stays logged, even after it is fixed.
- **ANSWER NEEDED**: a script cannot tell. The lead answers with evidence. A threshold that was crossed but may be legitimate also arrives as a question.
A scripted REPEATED cannot be answered away. Fix the thing and run the check again.
Questions per checkpoint are kept few on purpose: one at `brief`, two at `accept`, four at `pass-end`, two at `owner-report`. A question that always gets a one-word answer should be scripted or dropped.
### When to add a mistake
When a result that looked true was false. When a worker wasted a pass. When the owner corrected something. When a number in the cost report was a surprise. When a tool trap cost a run. When the lead itself claimed something it had not checked.
Write what happened and what caused it. Then write the rule and a question that a future lead can only answer by looking: "Does any lane's diff touch gates/?" is useful, "Was care taken with gates?" is not.
### Lesson levels
| Level | The lesson lives in | Move up after |
|---|---|---|
| `prose` | A sentence in this skill or the North Star, plus a question at a checkpoint. | 3 repeats |
| `template` | A line in a brief, report, handoff or North Star template, so it cannot be skipped. | 3 repeats |
| `scripted` | A check in `orch.py` or a project gate. | 3 passes closed with it still failing |
| `owner` | The owner's hands. The process needs changing, not the reminder. | |
`promote` is a record that you strengthened the lesson, so do the strengthening first: add the template line or write the check, then record what you changed in `--note`. Strike counts start again at the new level.
At the scripted level a repeat that the check caught and the lead fixed before the pass closed does not count as a strike. That is the check doing its job.
## Thresholds
All of these are in `.orchestration/config.json`. All are starting guesses. Tune them from `cost report`, `cost lanes` and `mistakes report`, and write the reason in the North Star under Decisions and why.
| Key | Default | Meaning |
|---|---|---|
| `context_budget_tokens` | 200000 | A worker whose context passes this should have handed off. Three field reports asked for a size budget in place of a turn count. |
| `lead_context_budget_tokens` | 300000 | Past this, the lead is asked whether to start a fresh session. |
| `rewrite_share_ask_above` | 0.15 | Ask when rewriting context is more than this share of a pass's cost. |
| `idle_gap_minutes` | 5 | A rewrite after a gap this long counts as an idle rewrite. |
| `rewrite_min_tokens` | 50000 | Smaller contexts are not counted as rewrites. |
| `senior_share_ask_above` | 0.5 | Ask the lead to justify the pass when more than this share of worker responses came from senior or above. |
| `cache_read_share_ask_above` | 0.5 | Ask when re-reading is more than this share of a pass's cost. |
| `strike_allowance` | light 3, standard 2, senior 2, lead 3 | The most strikes a lane may collect at a tier before it must move up. See below. |
| `current_state_max_lines` | 15 | Limit on the Current state block. |
| `lesson_strike_limit` | 3 | Strikes before a lesson must be promoted. |
**Strike allowances.** Three is the ceiling. A tier gets all three only when the next tier costs many times more, as light to standard does (20x). At a 2x gap (standard to senior, senior to lead) the default is to promote after the first strike and allow a second only when the first pass closed most of the gap; the allowance of 2 is the hard stop that `pass-end` enforces. Recompute from `cost lanes` when you have data, and whenever prices change.
## Adding a scripted check
Check kinds in a register entry:
| Kind | Fields | Tests |
|---|---|---|
| `manual` | | Asks the entry's `question`. |
| `northstar` | `name` | A named result from `lint_north` in `orch.py`. |
| `brief` | `name` | A named result from `lint_brief`. |
| `ledger` | `name` | A named result from `ledger_checks`. |
| `metric` | `name`, `config`, `on_fail` (`repeat` or `ask`) | A cost metric from the pass's ledger row, at most the config value. |
Any check can carry `"at": ["pass-end"]` to run at only some of the entry's checkpoints.
To promote a lesson to `scripted`, either write a project gate and add it to Gates and bars, or add a result to one of those three functions (each returns a dictionary of `name: (result, evidence)`) and reference it from the entry's `checks`. Keep the check about facts in files.
Metrics available: `workers`, `worker_responses`, `senior_share_of_worker_responses`, `max_responses_per_worker`, `avg_responses_per_worker`, `max_context_per_worker`, `avg_context_per_worker_response`, `cache_read_cost_share`, `cache_write_cost_share`, `rewrites`, `idle_rewrites`, `rewrite_cost`, `idle_rewrite_cost`, `rewrite_cost_share`, `agent_start_cost`, `main_cost_share`, `main_responses`, `main_peak_context`, `owner_messages`.
## Known limits
- The cost reader understands Claude Code transcripts. For any other harness, record usage yourself and use `cost add`.
- A pass's cost is everything between two `pass-end` runs, so run `pass-end` at the pass boundary, not later.
- The default transcript folder holds every session started in that project directory. Sessions before `init` are excluded by the start time in `config.json`. Unrelated sessions after it are not.
- A rewrite is detected by its effect: most of a large prompt written to the cache instead of read from it. That catches idle gaps and compaction but cannot tell the two apart except by the length of the gap.
- The fast-mode multiplier is applied to cache tokens as well as input and output. Only the input and output rates are published, so treat fast-mode cache figures as an estimate.
- Matching worker transcripts to lanes, and so cost per lane, depends on agent ids being written in the ledger's Agent column.
- Owner messages are counted from the transcript's own marking of human-typed turns. A harness that does not mark them will show a rough count.
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 |