/hunt

name: hunt
description: Turn a request like "improve this project for 5 hours" into a shift from the ready catalog and start it, asking only for the hours when they are missing.
license: MIT
metadata:
  internal: true

Compose a shift for the host-opened project: settle the work, the ending, and the hours, then either show it for approval or cut it and start.

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

Read `$NIGHTSHIFT_PLUGIN_ROOT/skills/nightshift/references/compose/execution-modes.md` before composing: it carries the state map, who selects work, when the clock starts, direct-mode authority, the tooling policy, and how several entries become one shift. If `$NS/` does not exist yet, run Setup's flow (`skills/setup/SKILL.md`, at most four questions) first, then continue with the same sentence. Never send the owner away to run Setup.

0. Read the sentence first

The owner's sentence is binding intent. There is no keyword list.

An actionable objective with a number of hours, regardless of wording, is a complete prompt: compose it and run it. Examples of a complete prompt: *"enhance my project for 5 hours"*; *"use the next 20 hours adding features and enhancing existing ones"*; *"8 hours clear lint and test debt"*.

• Complete → Automatic. Do not offer catalog cards. Do not ask who selects, when to start, or "same

as last time." It runs directly under the resolved `shift.execution` (`run-direct` unless the owner chose otherwise, or the sentence asks to see it first). Write the shift policy from the resolved tooling policy, no new elevation, and remembered verification, unless the sentence already granted a policy or allowance.

• An objective with no hours → ask exactly one question, *"How many hours?"*, and offer nothing

else in it. The hours are the owner's; never choose them. Then continue as a complete prompt.

• Any other incomplete prompt → Ask only a field that is still missing, then continue.
• The owner asked to pick from the menu, or named Guided → section 1.

1. Ask who selects

Entries live one per file: the shipped ones in `$NIGHTSHIFT_PLUGIN_ROOT/skills/nightshift/references/compose/shifts/`, and the owner's in the catalog folders [Owner knobs](https://github.com/orwa-mahmoud/nightshift/blob/main/docs/knobs.md#catalogs) describes. **Start with what the catalog holds, not with every contract in it:**

"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" catalog-index

One line per entry — slug, ending, title, purpose — read straight from the files. An entry added today is discovered today, and one that was deleted stops being offered. There is no second list to keep in step, and the helper ranks nothing: which entries suit the objective is your judgement.

**Then read in full only the entries you are actually going to use** — `ns catalog-index --path <slug>` prints the file in force, an owner's entry included. A complete objective needs the two or three contracts it names, not thirty. Read a contract before you compose it — its ending, refusals, verification and supported stacks bind the shift, and none of that is in the index line. `shift-catalog.md` beside the folder explains the two endings and carries the Maintainer night preset; it does not list the entries.

If the helper is missing or fails, list the directory and read the entries yourself: discovery is the point, and a job that exists in the folder but never reaches the owner is the failure to avoid.

Offer two first-class modes when the prompt did not already choose:

• **Guided** — one offer line per entry, with its ending marked, plus one line for any

preset `shift-catalog.md` names. The index gives you every one of them; read a contract in full when the owner picks it, not before.

• **Automatic** — inspect the work target per `execution-modes.md` (in artifact mode that includes

`$NS/receipts/`, not a git log) and compose the entries that support the stated objective. Quality, coverage, and dependency work do not hijack a feature or design objective. Show evidence only in review-first mode; run-direct does not pause.

**More than one may be chosen** — a night can clear the lint backlog and then hunt coverage until the whistle. Respect every entry's compatibility restrictions when combining; never combine entries that claim the same single-writer state.

Compose, cut and arm only through the Start preflight; it refuses, and names the repair, when the work target cannot be resolved, work-mode is missing or malformed, or `$NS/receipts` exists but is not a usable directory. Never `git init` a notes folder to get past a refusal.

The GitHub issue-hunt entry is offered with the rest of the catalog. It consumes only drafting-table entries the Import issues skill created (canonical Source URL and `Status: proposed`); list them by reading `$NS/staging/drafting-table.md`. Promote a selection by cutting the item — never a copy — with `"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" import-issues --promote …`, or do the cut here when that helper cannot parse the file. It does not replace defect hunt or product evolution, and never searches or writes back to GitHub. Never select it when work