/start

name: start
description: Begin the shift from the punch list without asking, so scheduled and headless runs behave like interactive ones.
license: MIT

Start a Nightshift run in the host-opened project.

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/start/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.

When a verdict names your host — permission modes, resume commands, the sandbox and identity rules that belong to it — open `$NIGHTSHIFT_PLUGIN_ROOT/skills/nightshift/references/hosts/<host>.md` for the host you are on, and no other. Not before a verdict names it.

1. Preflight — one helper, one verdict per line

**With work in the punch list, this command asks nothing.** It reads the list, arms the site and works — which is what lets cron run it at 04:00 and lets the watchman revive it after a crash. It promotes nothing on its own: what is in the punch list is the shift, exactly as the owner left it.

The one time it speaks is when the punch list is **empty**. Then there is no work to do silently, so it looks at staged drafts and pending Hunt orders and asks which to promote.

"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" start-preflight --host claude

Pass the host you are actually running on (`claude`, `codex`, or `cursor`). Every line it prints is one verdict, and it explains itself:

• **`ok <topic> <detail>`** — a resolved fact. Report it if the owner asked; otherwise continue.
• **`warn <topic> <detail>`** — say it once in plain English, then arm anyway. The choice stays the

owner's.

• **`refuse <topic> <detail>`** — do not arm. Print the `explain` and `repair` lines that follow it

verbatim and stop.

Exit status 0 means the shift may arm; non-zero is a refusal; 2 is a usage error in the call you just made. An `explain` line says what the verdict means and a `repair` line is the exact action — relay them, do not restate them, and never invent an explanation the helper did not print.

Two rules are policy rather than mechanics, so they are yours to hold whatever a verdict says: never kill a live watchman and never start a second shift beside one; and never clear `STOP` or invent a time budget for a paused shift whose deadline has passed.

2. The punch list is the shift

**Inspect capabilities in the skill.** Read manifests, lockfiles, and `## Gates` in the work target. `$NS/capabilities.json` is a cache the model may update after a successful tooling commit only; no detector is required.

**Permission gaps are parked, never asked.** Run `"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" preflight-needs` against every item now in `## Items`. For each item with a gap, run `"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" park-needs` to add its entry to `$NS/parking-lot.md` naming the missing category, then append one `$NS/shift-log.md` line listing every gapped item. Work everything else. If either helper exits because no JSON parser is installed, park the gaps in the skill and continue; neither is on the armed path.

If `$NS/punch-list.md` has at least one open `- [ ]` under `## Items`, that is the work — start it. Do not promote, cut, or add anything: parked orders and drafts stay exactly where the owner left them. An empty `## Items` section still keeps the Shift contract and Gates; they bind whatever Hunt or Start cuts next.

**Resume the active product cycle before rediscovery.** When the open item is product evolution, inspect `$NS/opportunity-map.md` for its single `Status: building` entry before doing new research or selecting work. Its `Next` action and `Verify remaining` are the continuation point. More than one building entry is inconsistent state: keep the earliest one active, mark the others `candidate`, record the repair in `$NS/shift-log.md`, and continue.

**Only when the punch list is empty, offer what is staged.** The `ok staged` verdict already counts `$NS/work-orders.md` and `$NS/drafting-table.md`. Read both, show what they hold in one short list, and ask which to work now. On the owner's choice, **cut it — move, never copy**: the item goes under `## Items` and is removed from the file it came from, so it never exists in two places. An imported draft (`Status: proposed` and a canonical `Source:` GitHub URL) is cut the same way in the skill — move the item under `## Items` and remove it from the drafting table. The import-issues helper is optional. Do not require Python. A flagged import stays refused unless the owner overrides after seeing the flags. From a work order, remove the whole `## Work order` section (heading, hours, and item), not just the checkbox, then write `$NS/deadline` as a UNIX epoch from the recorded hours (`now + hours*3600`; compute now with `date +%s` on POSIX, or `Get-NSUnixTime` after importing the module on native Windows); an order marked finite with no hours writes no deadline.

If the punch list is empty and nothing is staged, stop and say so: Setup if the project is new, Hunt to compose a shift, or write an item by hand. Give host-native invocation when needed: slash commands on Claude Code, or ask Nightshift for the named skill on Codex.

The working tree should be clean enough to commit per item; warn if it is not.

3. Deadline — read, never asked

The deadline value is decided when the work is composed (Hunt's cut, the owner's own edit, or Start's own start-defaults), never asked here. **The deadline is cleared only if it has alr