/nightshift

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

nightshift — the brain

If no shift is armed, run Start first; it asks nothing. This skill is the work, not the door.

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/`:

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

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 the installed plugin root to an absolute `$NIGHTSHIFT_PLUGIN_ROOT` — `${CLAUDE_PLUGIN_ROOT}` on Claude Code, `$PLUGIN_ROOT` on Codex when set, otherwise 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.

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 apply whatever this skill says.

The table is the whole surface: every preference this skill tells you to honour is a row in it, so nothing here needs the owner's rules file opened. Reading is always permitted; writing it is not, and stays denied while the shift is armed.

The level chooses **when** the gate runs, never whether its result is honest. A gate that runs must be green before the tick; a level of `none` means no gate ran, and the receipt says exactly that rather than calling the item verified. A profile name is not evidence.

One item at a time

Top to bottom, one item:

1. **Read** the item and the current `## Gates` block — one call, and the only punch-list read an item needs:

  "$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" punch-list nex