{"id":17848,"plugin_id":"plugins_6a7c58f65d708191b3a705a8625baffe","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:14:24.436Z","digest":"86eb853466b7f5fd5d28341242f62436f9c41d049e9dfa977e5bc29328da11a3","against":null,"payload":{"description":"Compose a shift from the ready catalog under one time budget, guided or automatic, reviewed first or run directly.","included_files":[],"name":"hunt","skill_md_contents":"---\nname: hunt\ndescription: Compose a shift from the ready catalog under one time budget, guided or automatic, reviewed first or run directly.\nlicense: MIT\n---\n\nCompose a shift for the host-opened project: settle the work, the ending, and the hours, then\neither show it for approval or cut it and start.\n\nResolve the installed plugin root to an absolute `$NIGHTSHIFT_PLUGIN_ROOT` — `${CLAUDE_PLUGIN_ROOT}`\non Claude Code, `$PLUGIN_ROOT` on Codex when set, otherwise the absolute path this skill was\nattached from (`skills/hunt/SKILL.md`). Run every command below through\n`\"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns\"` — native Windows: `& \"$NIGHTSHIFT_PLUGIN_ROOT\\runtime\\windows\\ns.ps1\"`\nin the PowerShell tool, same verbs — which resolves the host and the workspace; `ns help` lists the\nverbs, and `ns bind` prints the six resolved facts (`TASK_ROOT`, `NIGHTSHIFT_WORKSPACE`, `NS`,\n`NIGHTSHIFT_PLUGIN_ROOT`, `HOST`, `SOURCE`); `$NS` below is that `NS`. Never a bare relative path: the working\ndirectory persists between calls. Each `$NS/...` path below is where the current layout keeps that file;\n`ns path <key>` prints where this workspace keeps it, and `ns path --list` names every key.\n\nRead `$NIGHTSHIFT_PLUGIN_ROOT/skills/nightshift/references/compose/execution-modes.md` before composing: it\ncarries the state map, who selects work, when the clock starts, direct-mode authority, the tooling\npolicy, and how several entries become one shift. If `$NS/` does not exist yet, tell the owner to\nrun Setup, then return.\n\n## 0. Read the sentence first\n\nThe owner's sentence is binding intent. There is no keyword list.\n\nA time budget, an actionable objective, and clear direct-execution intent — regardless of\nwording — are a complete prompt: compose it and run it. Examples of a complete prompt:\n*\"use the next 20 hours adding features and enhancing existing ones\"*;\n*\"8 hours clear lint and test debt\"*; *\"make checkout less ugly, run it\"*.\n\n- Complete → Automatic, run directly. Do not offer catalog cards. Do not ask who selects, when to\n  start, or \"same as last time.\" Write the shift policy from existing tools, no new elevation, and\n  remembered verification, unless the sentence already granted a policy or allowance.\n- Incomplete → Ask only a field that is still missing, then continue.\n- The owner asked to pick from the menu, or named Guided → section 1.\n\n## 1. Ask who selects\n\nEntries live one per file in `$NIGHTSHIFT_PLUGIN_ROOT/skills/nightshift/references/compose/shifts/`.\n**Start with what the catalog holds, not with every contract in it:**\n\n```bash\n\"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns\" catalog-index\n```\n\nOne line per entry — slug, ending, title, purpose — read straight from the files.\nAn entry added today is discovered today, and one that was deleted stops being offered. There is no second list to keep in\nstep, and the helper ranks nothing: which entries suit the objective is your judgement.\n\n**Then read in full only the entries you are actually going to use.** A complete objective needs\nthe two or three contracts it names, not thirty. Read a contract before you compose it — its\nending, refusals, verification and supported stacks bind the shift, and none of that is in the\nindex line. `shift-catalog.md` beside the folder explains the two endings and\ncarries the Maintainer night preset; it does not list the entries.\n\nIf the helper is missing or fails, list the directory and read the entries yourself: discovery is\nthe point, and a job that exists in the folder but never reaches the owner is the failure to\navoid.\n\nOffer two first-class modes when the prompt did not already choose:\n\n- **Guided** — one offer line per entry, with its ending marked, plus one line for any\n  preset `shift-catalog.md` names. The index gives you every one of them; read a contract in full\n  when the owner picks it, not before.\n- **Automatic** — inspect the work target per `execution-modes.md` (in artifact mode that includes\n  `$NS/receipts/`, not a git log) and compose the entries that support the stated objective.\n  Quality, coverage, and dependency work do not hijack a feature or design objective. Show evidence\n  only in review-first mode; run-direct does not pause.\n\n**More than one may be chosen** — a night can clear the lint backlog and then hunt coverage until\nthe whistle. Respect every entry's compatibility restrictions when combining; never combine\nentries that claim the same single-writer state.\n\nCompose, cut and arm only through the Start preflight; it refuses, and names the repair, when the\nwork target cannot be resolved, work-mode is missing or malformed, or `$NS/receipts` exists but is\nnot a usable directory. Never `git init` a notes folder to get past a refusal.\n\nThe GitHub issue-hunt entry is offered with the rest of the catalog. It consumes only\ndrafting-table entries the Import issues skill created (canonical Source URL and\n`Status: proposed`); list them by reading `$NS/staging/drafting-table.md`. Promote a selection by cutting\nthe item — never a copy — with\n`\"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns\" import-issues --promote …`,\nor do the cut here when that helper cannot parse the file.\nIt does not replace defect hunt or product evolution, and never searches or writes back to GitHub.\nNever select it when work mode is artifact.\n\nThe other repository-shaped jobs are out of scope there too:\nNever select defect hunt when work mode is artifact.\nNever select documentation drift when work mode is artifact.\nNever select TODO and FIXME debt when work mode is artifact.\nNever select coverage hunt when work mode is artifact.\nNever select tooling quality-debt entries when work mode is artifact.\n\n`ns normalize-output` and `ns inventory` are read-only reports a shift may\nlean on when the host carries them — if present, optional, never required. The first turns a\nsupported tool format into one compact summary for the receipt and the ledger; the second lists\neach workspace package's manager, lockfile, declared scripts, configs, and which named tools are\nrunnable. Automatic composes and works a shift without either.\n\n## 2. Ask when execution starts\n\nWhen the prompt did not already carry clear direct-execution intent, ask\n**review first, or run directly?** — a choice independent from Guided or Automatic.\n\n- **Review first** — discovery stays read-only and the clock starts only after approval.\n- **Run directly** — start the clock once the tooling policy is settled and do not pause after\n  discovery, under the direct-mode decision policy in `execution-modes.md`. Review-missing holds\n  the clock until that plan is approved.\n\n## 3. Ask the tooling policy and confirm tonight's shift policy\n\nThis is composition's one question for tonight's policy — Start never asks it. On a complete\nAutomatic prompt, skip the question and write the safe defaults from `execution-modes.md`, parking\nany elevation gap. **The tooling policy is the owner's standing answer, not a default to re-pick:**\nread the resolved value and carry it. Only when the owner has no explicit persistent choice does a\ncomplete prompt run under existing tools. A saved `auto-add` or `review-missing` survives an\nobjective that says nothing about tooling; a tonight-only `existing-tools` in the prompt overrides\nit for that shift alone and changes nothing persistent. Carrying a policy forward grants no new\nelevation — an allowance is still the owner's to give. Otherwise ask **before scanning**, and\nbefore any compose, cut, or arm.\n\nRead `$NS/run/work-mode` and the remembered project default with\n`\"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns\" shift-policy defaults-get`,\nand run the permission preflight\n`\"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns\" preflight-needs`\nagainst the entries this compose would select. Ask the single prefilled question in\n`execution-modes.md`, folding every capability gap into it, then write the resolved policy with\n`\"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns\" shift-policy set --from-json -`. Persist a change as the new project default only when\nthe owner says to remember it (`defaults-set`). In review-first mode that policy is the only file\nwritten before approval; in run-direct mode, arm as soon as it lands.\n\nArtifact mode refuses repository-tool policies (`auto-add`, `review-missing`) and explains why — a\nnotes folder has no repository toolchain to add. Only existing-tools is valid there; if the\nremembered default holds a repository-tool policy, keep existing-tools.\n\nUnder auto-add, capture the write surface before writing with\n`\"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns\" provision baseline --surface <rel> [<rel>...]` (one flag takes several paths, or repeat `--surface` per path), then install, smoke, `diff`, and\n`rollback` when smoke or the tooling commit fails.\n\nThen inspect, compose, cut, or arm. Under existing-tools, skip unavailable contracts even when\nGuided selected them.\n\n## 4. Establish the ending\n\nPer the entry's declared ending:\n\n- **Open-ended** — hours are REQUIRED. These have no natural end but the clock; a walkthrough may\n  not start without a deadline. The entry's declared open-ended title is the source of truth.\n- **Finite** — when hours were not already given, ask the ending as an explicit either/or: *until\n  every finding is clear, or capped at N hours?* Both are valid; the work ends when the list is\n  empty either way, and hours are only a safeguard against a backlog bigger than the night.\n\nOne deadline governs the whole shift, and Automatic always requires hours. On a mixed selection say\nso in one line: the finite work runs first, and the open-ended job soaks up whatever time is left.\n\n## 5. Ask for guided scope\n\n> Anything specific about scope or approach?\n\nAsk this in Guided mode; in Automatic the owner's sentence is the scope. Free text is skippable and\nis where the useful shift is made: *\"only `packages/api/`\"*, *\"use `getTestInstance()` from the\ntest package\"*, *\"one module — this becomes a single reviewable PR\"*.\nIf a selected entry declares Owner instructions required, it is not skippable: ask, and refuse to\ncompose, cut, or arm that entry until the owner supplies a non-empty answer. Those entries are\nGuided-only and are never selected in Automatic mode. Never edit the entry's own contract to fit\nit; the owner's words become their own sub-bullet:\n\n```text\n - **Owner instructions:** <verbatim, as written>\n```\n\nThe entry's rules stay above it untouched. They enforce the shift contract — assert behaviour\nrather than counts, gate green at every commit or artifact receipt, never silence instead of\nfixing — and owner text adds constraints rather than replacing them.\n\n## 6. Review or cut\n\nIn **review first**, print the items exactly as they will be written, with evidence, order, hours,\nand ending, then ask for one approval. The preview is model prose: a no-write, no-clock simulation\nof the resolved workspace and work target, the shift policy, why each entry serves the stated\nobjective, overlaps removed, rejected alternatives, and the stopping rule.\nThis is the last look before anything is armed. Write nothing before approval.\n\nIn **run directly**, do not ask again: write the order and immediately cut it into the active\nshift. Record significant discovery and selection decisions in `$NS/inbox/parking-lot.md`.\n\nOn approval, run `\"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns\" scaffold work-orders`, which creates\n`$NS/staging/work-orders.md` from its template the first time and keeps it after, then append to it —\nhunt's own file; the drafting table stays the owner's room. Never clobber orders already sitting\nthere — append below them:\n\n```text\n## Work order — <ISO date time>\nHours: <N, or \"none — finite\">\n\n- [ ] **<entry item, verbatim>**\n - **Owner instructions:** <if any>\n```\n\nThe hours are inert while a review-first order sits here — the clock starts only at the cut, after\napproval. In run-direct mode the order is cut immediately, so its clock starts now.\n\n## 7. Start or park after review\n\nAfter review-first approval, ask **start now, or park it for later?** Run-direct skips this\nquestion and always starts now; choosing it was already explicit authorization.\n\nOn **now** — start the shift yourself, here, without making the owner type another command. Follow\nthe Start skill exactly, including its whole preflight and the unsupported-permission report\ndescribed in `execution-modes.md`. Then clear the stale markers and\n**cut** the whole `## Work order` section out of `$NS/staging/work-orders.md` (heading, hours, and item —\ndo not leave an empty order heading behind), put only the item under `## Items` in the punch list\n(a cut, never a copy — it must not exist in two places), and:\n\n- for a product-evolution item (the standing loop or the owner walkthrough), run\n  `\"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns\" scaffold product`, which creates\n  `$NS/product/opportunity-map.md` and `$NS/product/product-research.md` from their templates and\n  keeps any already there;\n\n- write `$NS/run/deadline` as a UNIX epoch from the recorded hours — `date +%s` plus hours*3600 on\n  POSIX, or `Get-NSUnixTime` plus hours*3600 after\n  `Import-Module \"$NIGHTSHIFT_PLUGIN_ROOT\\lib\\Nightshift.psm1\" -Force` on native Windows;\n- **arm the gate** with `touch \"$(\"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns\" path armed)\"` on POSIX, or\n  `New-Item -ItemType File -Force (& \"$NIGHTSHIFT_PLUGIN_ROOT\\runtime\\windows\\ns.ps1\" path armed)` in native Windows PowerShell;\n- log the start and run the binding probe (`: nightshift-binding-probe` on POSIX,\n  `$null = 'nightshift-binding-probe'` on native Windows);\n- classify Codex `$NS/run/.shift-session` line 1 with `ns_codex_identity_kind` from\n  `$NIGHTSHIFT_PLUGIN_ROOT/lib/lib.sh`, or `Get-NSCodexIdentityKind` after importing\n  `Nightshift.psm1` on native Windows, before arming the watchman or beginning item work;\n- **arm the watchman** as the Start skill requires, with `ns start-watchman` for this host; never\n  begin item work unless it reports the watchman armed.\n\nAn empty `## Items` section still keeps the Shift contract and Gates; they bind the cut item.\nRecord leftover campaign rules in `$NS/inbox/parking-lot.md` when they are not this order's.\n\nOn **later** — the order stays parked in `$NS/staging/work-orders.md` with its hours, costing nothing. It\narms nothing and the gate stays inert. Start (`/nightshift:start` on Claude Code, or ask Nightshift\nto start on Codex) will offer it when the owner is ready.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}