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/north-star.md

View on GitHub
# The North Star

The North Star is the plan of record: one file, `NORTH_STAR.md` at the project root, that holds the intent, the decisions and the current state. It is written so that an agent with no history can pick up the present state from the top and the reasons from below. The lead is the only writer. Everyone else reads it before working.

It is a living file. It changes every pass, and three things keep those changes honest: the owner's words are never reworded, the Status log only grows, and `orch.py pass-end` saves a snapshot each pass and compares the next version against it.

Start from `assets/NORTH_STAR.template.md`. `orch.py init` copies it in.

## Sections

| Section | Contents | What it does for an agent |
|---|---|---|
| One sentence | The whole project in a line. | Any decision can be checked against it. |
| Current state | Works, Fails (gate, number, bar), Next, Unverified by a person, Waiting on the owner, Spend. Fifteen lines at most. Rewritten every pass. | The present state in the first screen, without reading the log. |
| Mandate | The owner's direction in their own words, dated. Below each quote, the lead's reading, marked as the lead's. | Separates what the owner asked for from what the lead inferred. |
| The one thing | The single quality that must be excellent, and who owns it. | Shows where refinement time goes when time is short. |
| Pillars | Three to six rules that settle arguments. | An agent can resolve a design question without asking. |
| Scope | What is being built, with counts. | Stops scope from growing by accident. |
| Decisions and why | Each technical choice with its reason. | Stops a later agent from reversing a choice it does not understand. |
| Environment contract | Do not disturb, exclusive resources, the owner's time, storage, irreversible actions, honesty limits, privacy, and a living Tool quirks list. | Facts about the owner's machine and time that no gate catches. |
| Team and working rules | Which tier does which kind of work, each tier's strike allowance, the context budgets. | Sets the default tier. Briefs inherit the rules by reference. |
| Milestones | Ordered stages, one marked as the go or no-go point. | Says when to stop and fix instead of building further. |
| Gates and bars | A table of every gate: command or checklist, bar, who set it, date, status. Then Known failures, Bar changes and Owner checklists. | The shared definition of done, and proof that it has not moved. |
| Lane ledger | One row per lane per tier: task, tier, why this tier, strikes, gate, status, agents. | Makes tiers and strikes countable, and maps transcripts and cost to work. |
| Owner notes | Every note from the owner, verbatim, with an id, where it was routed and its status. Then Approved and locked. | Nothing the owner said is lost, guessed silently or undone. |
| Budget | The pass cap and who set it. The cost ceiling, if any. | A stopping point. |
| Status log | Dated entries: what closed, the measured numbers, what is open, then the cost and mistake-check lines. Append only. Always the last section. | The history, in order, with nothing tidied. |

## Rules for keeping it

- Every agent reads it before working. Briefs quote the relevant section instead of restating the vision.
- Owner statements are dated and attributed. If the owner withdraws one, add a new dated line saying so. Do not delete the old one.
- Every decision has its reason next to it. In the first reference build the core engine ran on the processor and not the graphics card because other code had to read its state every frame without delay. With that written down, no agent tried to move it.
- Current state is rewritten each pass. Everything else is edited in place except the Status log, which is appended.
- Failing checks and open problems go in the log in the same plain terms as the successes.
- Add a tool quirk the moment it is found. Each one cost at least one wasted run before it was written down, and one lead hit a known trap twice more after that.

## Gates and bars

```
| Gate      | Command or checklist  | Bar           | Set by | Set on     | Status  |
|-----------|-----------------------|---------------|--------|------------|---------|
| sim-speed | ./gates/sim.sh --ship | 15            | owner  | 2026-11-12 | FAIL 12 |
| frame     | ./gates/frame.sh      | 12 ms         | lead   | 2026-11-12 | PASS 11 |
| hw-boot   | owner: checklist H1   | boots to menu | owner  | 2026-11-12 | not run |
```

- Write the bar before the work starts. For a discovery task the bar is the evidence that would count as an answer.
- **Set by** is `owner` when the bar comes from the owner's words and `lead` when the lead chose the target. Do not present a lead's target as the owner's requirement.
- Status begins with `PASS`, `FAIL` or `not run`, followed by the number.
- Every gate whose status begins with `FAIL` is also listed under **Known failures** with its number, bar, date and what is known about the cause. One field project re-derived the same pre-existing failures several times for want of this list.

### Bar changes

A bar changes in exactly three ways. Each is a dated line under **Bar changes** that names the gate, keeps the old bar and gives the reason. Only then is the table edited.

1. **The owner changes it**, in their words.
2. **The owner changes the design**, so a test no longer describes the product. Log it as `spec change:` with the owner's words.
3. **The owner accepts a result that missed a lead's target.** Until they do, the miss is a miss.

Two things that are bar changes even though they do not touch the table: a product change made so that a check passes more easily, and a worker adjusting a limit in its own lane. Log the first as a bar change. Reject the second.

If the table changes without a new line under Bar changes that names the gate, `pass-end` reports a moved bar and refuses to snapshot.

### Owner checklists

When the configuration that ships exists only in the owner's hands (a device, a real input device, their account), the owner is a gate. Write a checklist per build:

```
- H1: build <version>, checksum <first 8 characters>. Boot with the plugin on -> reaches the menu. Open the layer test -> each layer shows alone.
      Result: <date>, <pass or fail>, "<the owner's words>"
```

Design the build so one session covers many items, and record the result with the owner's words. Count how often the owner is asked; their time is the scarcest thing in the project.

## Lane ledger

```
| Lane | Task          | Tier     | Why this tier                                   | Strikes | Gate   | Status   | Agent      |
|------|---------------|----------|-------------------------------------------------|---------|--------|----------|------------|
| find | find the cause | standard |                                                 | 1       | emu    | promoted | a94fe5e5   |
| find | find the cause | senior   | promoted: no evidence after 1 pass at standard  | 0       | emu    | done     | b1c2d3     |
| docs | help pages    | standard |                                                 | 0       | docs   | verify   | c3d4, e5f6 |
```

- **One row per lane per tier.** When a lane is promoted, set its row's status to `promoted` and open a new row with the same lane name at the next tier. Each row then shows what one tier spent and whether it finished, which is what `orch.py cost lanes` reports.
- **Tier**: `light`, `standard`, `senior` or `lead`.
- **Why this tier**: required for `senior` and `lead`. The reason the task could not start lower (judgement across files, a failed attempt would cost a hardware test), or the promotion history with the numbers each attempt reached.
- **Strikes**: lead-verified failed passes at this tier.
- **Status**: `open`, `running`, `verify`, `done`, `promoted`, `handed-down`, `owner` or `dropped`. A lane at its strike allowance that is still `open`, `running` or `verify` is reported as struck out and not acted on. A `dropped` lane has its reason in the Status log.
- **Agent**: the id of every agent that worked the row, added as each one starts. The cost reader matches these to worker transcripts and asks about any it cannot place.
- A row marked `done` needs an accept check on record (`mistakes check --at accept --lane NAME`). `pass-end` lists any that do not have one.

## Owner notes

```
| Id    | Date       | Owner's words               | Routed to | Status                          |
|-------|------------|-----------------------------|-----------|---------------------------------|
| N-014 | 2026-11-12 | the clicks sound too harsh  | sound     | done pass 3                     |
| N-015 | 2026-11-12 | 4 of each                   | lead      | guessed: four of each item type |
| N-016 | 2026-11-12 | top left, about halfway in  | layout    | open                            |
```

- Log every note the moment it arrives, in the owner's exact words. Sensory comparisons and pointers ("top left, about halfway in") are the most useful things an owner says, and they do not survive paraphrase.
- Route each one to a lane, or to the lead. A note about an area a lane is already working goes to that lane.
- Status says what happened: `open`, `done pass n`, `asked` (waiting for the owner to clarify), or `guessed:` with what was assumed.
- Confirm back to the owner in a line.

A row with no route or no status is reported by `pass-end`.

**Approved and locked.** When the owner approves something explicitly, record the approval verbatim with the date, what it covers and how the lock is checked (a checksum list, a gate). After that, changing it needs the owner's yes. One project pinned several hundred approved files byte-identical the moment the owner approved them.

## What the script reads

`orch.py` finds sections by heading. Keep these names: `One sentence`, `Current state`, `Mandate`, `The one thing`, `Decisions and why`, `Environment contract` (with `### Tool quirks`), `Gates and bars` (with `### Known failures` and `### Bar changes`), `Lane ledger`, `Owner notes`, `Budget`, `Status log`. Text in brackets after a heading is ignored. Other sections can be added freely, anywhere above the Status log.

It also reads:

- `Pass cap: <number>` and `Cost ceiling: $<number>` in Budget.
- Lines starting `Works:`, `Fails:`, `Next:` and `Unverified by a person:` in Current state.
- A line starting `Exclusive resources:` in the Environment contract. Write `none` if there are none.
- The `Spend:` line in Current state, which `pass-end` rewrites. It is the only line the script edits in place.

Anything written as `<like this>` is treated as an unfilled placeholder.

## Snapshots

`pass-end` copies the North Star to `.orchestration/snapshots/pass-N.md` after each pass. The next pass is compared with it for moved bars, removed gates, changed log lines and missing owner quotes. If a bar moved without an entry or history was rewritten, no snapshot is taken, so the last honest version stays the baseline until the record is restored or the change is entered.

The snapshots also show how the plan changed over the life of the project:

```bash
diff .orchestration/snapshots/pass-2.md .orchestration/snapshots/pass-3.md
```
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