/nightshift

name: nightshift
description: Work a punch list to completion autonomously, overnight, through a todo list or until a product is polished, parking decisions instead of asking and leaving receipts.
license: MIT
metadata:
  internal: true

nightshift — the brain

If no shift is armed, run Start first; it asks nothing. This skill is the work, not the door. A plain request that names work and a time budget — *"improve this project for 5 hours"*, or the same with no hours at all — is a Hunt request: follow Hunt (`skills/hunt/SKILL.md`), which sets the project up first when it is new.

A **shift** is a stretch of autonomous work with a punch list you cannot walk away from. The list lives in `.nightshift/punch-list.md`: a contract that binds you for the whole night, then `## Items` — one checkbox per task, each with its own Verify and Commit lines. The clock-out gate holds the session until every box is `- [x]`, a stop-work order lands, or the whistle blows. That is the push model: the list pushes the work forward item by item, and finishing it is the ordinary way out.

Nothing interrupts the owner while they sleep. A decision that is genuinely theirs gets a sensible production default and a written note, so the morning is a review rather than a pile of questions.

**What the owner reads in the morning**, all plain markdown under `.nightshift/`, each folder named for what it holds:

• `punch-list.md` — what was agreed, and which boxes are ticked.
• `receipts/` — what the night delivered, one file per item, written as the work happens.
• `inbox/parking-lot.md` — unresolved owner decisions and the default chosen so work continued.
• `inbox/snag-log.md` — findings with dispositions, so a later pass never re-reports an earlier one.
• `staging/drafting-table.md` — known work the owner stages for a later shift.
• `staging/work-orders.md` — timed catalog work composed only through Hunt.
• `run/shift-log.md` — the journal: one line per cycle, plus a handover line if the night ended

early. Everything else under `run/` is the runtime's own.

Never route an ordinary plan through Hunt, call later work "parked," or put a known task in the parking lot. Repository mode leaves commits as the punch-list contract says — one per item unless the contract above `## Items` says otherwise; artifact mode completes an item with its receipt under `$NS/receipts/`.

**Three ways a shift gets composed**, after Setup has scaffolded the site once:

• **Start** works whatever is already in the punch list. It asks nothing, so a scheduled or

headless run behaves exactly like an interactive one.

• **Hunt** composes a shift from the ready catalog — guided or automatic, reviewed first or run

directly — then cuts and starts it.

• **Quality** does the same for the project's quality debt, and hands a feature objective to Hunt.

Those skills own scaffolding, composition, and preflight. This skill owns the work itself.

Resolve `$NIGHTSHIFT_PLUGIN_ROOT` to the copy this host installed, as an absolute path. On Claude Code that is `${CLAUDE_PLUGIN_ROOT}`, on Cursor `${CURSOR_PLUGIN_ROOT}`, and on Codex `$PLUGIN_ROOT` when set. A skill loaded from a copy another host installed is the wrong runtime — use the copy under this host's plugins directory. When none of those is set, use the absolute path this skill was attached from (`skills/nightshift/SKILL.md`). Run every command below through `"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns"` — native Windows: `& "$NIGHTSHIFT_PLUGIN_ROOT\runtime\windows\ns.ps1"` in the PowerShell tool, same verbs — which resolves the host and the workspace; `ns help` lists the verbs, and `ns bind` prints the six resolved facts (`TASK_ROOT`, `NIGHTSHIFT_WORKSPACE`, `NS`, `NIGHTSHIFT_PLUGIN_ROOT`, `HOST`, `SOURCE`); `$NS` below is that `NS`. Never a bare relative path: the working directory persists between calls. Each `$NS/...` path below is where the current layout keeps that file; `ns path <key>` prints where this workspace keeps it, and `ns path --list` names every key.

Persistent-workspace boundary

Nightshift is an engineering workflow for a persistent project workspace. If the resolved project root is under `/workspace/scratch/`, stop before setup or shift work and give the OpenAI-native redirect from the setup skill: open the project you want Nightshift to change in Codex (or connect Codex to its GitHub repository), then mention Nightshift there. Never create durable-looking run state in a disposable ChatGPT scratch workspace, and never claim those temporary files affect or preserve the user's repository. A non-git project outside that explicit scratch path remains valid.

The contract is above `## Items`

`$NS/punch-list.md` has a contract section, then `## Items`. Read `$NS/punch-list.md` in full once, when the shift starts and before the first item; after that, each item reaches you through the helper in step 1. The contract binds YOU for the whole shift: **never edit, trim, or reword it, and never delete an item** — not even to end the shift. Step 1 of every item is the helper, which gives you that item and the current `## Gates` block, so a mid-shift change to the gates reaches you without re-reading the file. The gate holds the contract and the items to what they were at arming and blocks with the repair named if either moves, so watching for that is not your job.

What the owner chose

Read the resolved policy once at the start of the shift and follow it:

"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" shift-policy resolve --table

Two rows decide how the loop below runs. `verificationLevel` is the gate cadence: `none` runs the `## Gates` block never, `final` once before clock-out, `per-item` before every tick, and `custom` on the cadence the punch list itself names. `toolingPolicy` says what to do about tooling the project does not have. The rest of the table is guards and the owner's preference blocks — `receipts.*`, `handoff.*`, `archive.*`, `recovery.*` and `shift.*` — and they