# Setup > Scaffold .nightshift/ and propose quality gates for this stack; asks, never imposes. - Skill: `hashgraph-online-awesome-codex-plugins/setup` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add hashgraph-online-awesome-codex-plugins/setup` - Raw SKILL.md: https://api.skillmd.com/api/skills/hashgraph-online-awesome-codex-plugins/setup/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: hashgraph-online (https://skillmd.com/u/hashgraph-online-awesome-codex-plugins) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/hashgraph-online-awesome-codex-plugins/setup --- Set up Nightshift in this project. Do the scaffolding first, then the gates conversation, then print a summary. The four state files and what each holds are in `$NIGHTSHIFT_PLUGIN_ROOT/skills/nightshift/references/shift/state-map.md`. Ordinary plans belong in the drafting table, never in Hunt or the parking lot. 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/setup/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. Once the workspace and work target are resolved, the bundled mechanical scaffold is `ns setup --work-target "$WORK_TARGET" --mode "$WORK_MODE"`, which exists on native Windows only; on every other host this skill writes the same templates itself, as below. It copies only absent files, writes state version 1 for a new site, persists the work target and work mode (`-Mode repository` or `-Mode artifact`), and keeps `$NS/` private. It refuses a notes folder under default repository mode: `pass -Mode artifact for a notes folder that is not a Git repository`. Read its output back rather than restating it. The skill still owns every owner choice below; the script asks nothing and never invents gates, permissions, profiles, migration approval, a receipts choice, or a tooling policy. If the user explicitly identifies a different existing workspace containing `.nightshift/`, show both absolute paths and ask for confirmation. On yes, run `"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" link-workspace --host-root "$TASK_ROOT" --workspace "$PROPOSED_WORKSPACE"`. The pointer is local-only and state remains in the authoritative workspace; never copy it. ## 0. Reject disposable ChatGPT scratch workspaces Before creating or changing any file, resolve the project root to an absolute path. If it is under `/workspace/scratch/`, this is a disposable ChatGPT scratch workspace that cannot affect the user's repository. **Stop immediately: create no `$NS/` directory, rules, settings, receipts repo, or other files.** Tell the user directly: > Nightshift needs a persistent software project workspace. This ChatGPT conversation is using a > temporary workspace, so files created here will not affect your repository. > > Open your project in Codex (a Git repository or a persistent local folder), or start Codex connected to its GitHub repository. Then mention > Nightshift and say: “Set up Nightshift in this project.” Do not mention Claude Code in this ChatGPT-specific redirect: the user is already in an OpenAI product, so give them the shortest OpenAI-native route. Do not infer “temporary” merely because the project is not a git repository — local non-git projects and the recommended parent-workspace layout remain valid. The explicit disposable scratch path is the stop signal. Detect the work mode, explain it, and ask before persisting it. Use `ns_propose_work_mode` (POSIX) or `Get-NSProposedWorkMode` after importing `Nightshift.psm1` (native Windows): - `repository` — the workspace is a Git repository, or exactly one immediate non-hidden child is. Skip a symlink or reparse child; it is not a nested checkout. several child repositories still mean repository mode; show the choices and require an explicit target, never guess. - `artifact` — there is no Git repository here. The persistent folder itself is the work target (research, docs, audits, planning). Say so plainly: gates, commits, and stack detection that require Git do not apply; complete each item with `"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" write-receipt`. Completion in that folder is `$NS/receipts/`, not a git log. When `$NS/receipts` exists but is not a usable directory, say so and do not treat artifact setup as complete. - scratch (`ns_propose_work_mode` status 2, or `Get-NSProposedWorkMode` throwing) — stop; create nothing. Never persist a mode until the owner confirms. Never `git init` a notes folder to change an artifact proposal into repository mode. Then write `$NS/work-mode` as `repository` or `artifact` (one word, one newline) and `$NS/work-target` as the absolute canonical path of the chosen folder. On POSIX: `ns_record_work_target "$NIGHTSHIFT_WORKSPACE" "$WORK_TARGET" "$WORK_MODE"`. On later setup runs, validate and retain that mode and target unless the owner explicitly changes them. Repository mode: stack detection, Git checks, gates, commits, and verification operate in the work target. Artifact mode: inspection, edits, and verification operate in that folder without pretending it is a repository. ## 1. Scaffold `$NS/` (never clobber an existing shift) ```bash "$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" scaffold ``` It writes each state file that is not already there and reports `wrote ` or `kept `, so a name the owner already has is left exactly as it is and a second run is a safe repair. Read its output back. The copies carry resolved absolute paths — a person pasting a command out of their own punch list has no `$NS` — and the shipped templates are unchanged. Never write those tokens into `rules.json`: revival and clock-out text stay owner-editable, and the gate qualifies bare `.nightshift/` mentions at injection time. Create `$NS/shift-log.md` with a one-line header if absent. **State version.** `$NS/state-version` is the schema marker. This plugin supports integer `1`. If this run created `$NS/` (the directory did not exist when setup started), write exactly `1` followed by a newline to `$NS/state-version` after the templates. If `$NS/` already existed and the marker is missing, that workspace is legacy version `0` — offer `"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" migrate-state` and run it only after an explicit yes; the script writes only the marker and refuses while armed. On native Windows the scaffold's `--migrate-legacy` switch is the same idempotent marker write. A marker newer than `1`, or a malformed file, fails closed: print the diagnostic, do not rewrite or downgrade it, and do not continue scaffolding as if the site were current. ## 2. Private by default - Keep run state out of git. If `$NIGHTSHIFT_WORKSPACE` is itself a git repo, append a line `.nightshift/` to `$NIGHTSHIFT_WORKSPACE/.gitignore` (create the file if needed; do not duplicate the line). If it is not one — the recommended layout, where the code repo sits a level below — `.nightshift/` is already outside every repo, so write no `.gitignore` there. Run history is the owner's; it never enters the project repo. - **Receipts repo — ask, default no.** The run state can be versioned in its own local-only git repo inside `$NS/`, so every punch-list change and log line has history. Most people don't want a git repo living inside their project, so ask — *"version the run state in a local receipts repo? (never pushed, never touches your project's history)"* — and on anything but a clear yes, skip it: the receipts still exist as plain files. Present the question neutrally — never describe the repo as recommended; the default is no. On yes: if `$NS/.git` does not exist, run `git -C "$NS" init` rather than `cd`-ing there. Ensure `$NS/.gitignore` contains the transient markers `STOP`, `.stall`, `.notified`, `deadline`, `.session-end`, `.shift-pulse`, `.mint-failed`, `.shift-session`, `.shift-session.tmp.*`, `.shift-worker`, `.shift-lease`, `.shift-lease.tmp.*`, `.mutex-scope`, `.mutex-scope.tmp.*`, `.watchman`, `.watchman-tick`, `.lock.d/`, and `.lease-lock.d/`; preserve existing lines. Make one initial commit only when setup created the receipts repository. Creating the repo does **not** turn on headless auto-commit — that is `receiptsAutoCommit` in `rules.json`, shipped `false`; the owner commits the receipts tree when they want. **Never add a remote to it, never push it.** On native Windows, after a clear yes, rerun the bundled scaffold with the same `--work-target` plus `--receipts`; the idempotent pass creates only this local receipts repo. - **Cursor CLI file hooks — ask, default no.** The installed Cursor plugin already holds the IDE Agent tab. The Cursor CLI (`agent`) currently ignores marketplace and local plugin hooks and only runs project file hooks — a Cursor limitation, not a Nightshift skip. Ask — *"write a project `.cursor/hooks.json` so the Cursor CLI is held by the same Nightshift hooks?"* — and on anything but a clear yes, skip it. Present the question neutrally; the default is no. The IDE plugin keeps working either way. On yes: if `$NIGHTSHIFT_WORKSPACE/.cursor/hooks.json` does not exist, create `.cursor/` if needed and copy `$NIGHTSHIFT_PLUGIN_ROOT/hooks/cursor/hooks.json` there. That file execs the same plugin scripts via `${CURSOR_PLUGIN_ROOT}`. If a `.cursor/hooks.json` already exists, show the diff against the shipped file and write only on an explicit yes to replace; never merge unknown owner hooks silently. Never create a second `.nightshift/`. ## 3. Gates — ask, never impose Detect the stack in the persisted work target from the table in `$NIGHTSHIFT_PLUGIN_ROOT/skills/nightshift/references/compose/gates-catalog.md` (monorepo-aware). A plugin or marketplace manifest may sit at the work-target root or one directory down at `plugins//.claude-plugin/` / `plugins//.codex-plugin/`; that nested layout is a match when no language-stack row already won. Then ask the user, showing the detected proposal, with three first-class answers: - **accept** the proposal as-is, - **edit** it — add, remove, or replace with THEIR own commands (any shell command is a valid gate), - **none** — fully respected: the shift runs without automated checks. If gates were accepted or edited, also ask the **site-inspection interval** (every N items or every H hours). Write the result into the `## Gates` block of `$NS/punch-list.md`, replacing the placeholder. If the answer was none, leave the placeholder as-is. The `## Gates` block is plain markdown the owner may edit anytime — run Setup again (`/nightshift:setup` on Claude Code, or ask Nightshift to set up on Codex) to re-detect after a stack change. The contract's immutability binds the agent, not the owner. **Project defaults — ask once.** Independent from gates. Ask one question covering the verification profile (`fast`, `balanced`, `strict`, or `custom`), typical hours, and tooling policy (existing tools only, review missing tools first, or automatically add standard development tools). Persist the answer with `"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" shift-policy defaults-set --verificationProfile --hours --toolingPolicy --execution review-first|run-direct`. The helper writes the `shift` block of `$NS/rules.json` — the one file the owner edits — and reports what it stored; never put the answer in the punch list. It only prefills the one question Hunt and Quality ask before composing — it decides nothing on its own, and either skill may change it for a single shift. - **Artifact** — do not ask. Persist `fast` and existing-tools only, without prompting. A notes folder has no repository toolchain to add; repository-tool policies (`auto-add` and `review-missing`) are invalid there. - **Repository** — ask the full question above (including review-first vs run-direct), then persist the answer. ## 4. Permissions — the night cannot click Allow An unattended shift stalls forever on a permission prompt, and a watchman revival runs headless — denied means denied. Ask one question: > Overnight runs can't answer permission prompts. Enable frictionless permissions for this > project's unattended runs? (recommended — Nightshift's guards stay armed in every permission > mode) - **Yes, on Claude Code** → merge `{"permissions": {"defaultMode": "bypassPermissions"}}` into `$TASK_ROOT/.claude/settings.local.json` (create the file if absent; never clobber keys the owner already has). Write the full path: a copy that lands in a nested code repo grants the project nothing, and the first prompt of the night proves it. Settings on disk are what revivals inherit — a mode picked at launch dies with the process. - **Yes, on Codex** → there is no settings file to write: approvals are per launch. Tell the owner that unattended execution and sandbox scope are two separate choices, and say the trade plainly: a contract that does not commit runs unattended under `-a never -s workspace-write` — ticks alone finish a night, in the gate and the stall guard alike, and the commit rule is theirs to strip from the punch list and `clockOutMessage`. Under Codex's `workspace-write` sandbox `.git` is protected, so the default contract, which commits once per item, cannot run under it and is started with the launch command on the Codex host page, `$NIGHTSHIFT_PLUGIN_ROOT/skills/nightshift/references/hosts/codex.md`. The fence around that access is nightshift's own guards, which hold in every mode — the same trade `bypassPermissions` makes on Claude Code. - **No** → respect it and say the cost plainly: *"a permission prompt mid-shift freezes the night until morning — if the shift stalls on one, that was tonight's trade."* Suggest the narrower alternative: pre-allow just the punch list's tools (test runner, linter, git) in the same file. ## 5. The rules file — every knob in one place Copy `$NIGHTSHIFT_PLUGIN_ROOT/skills/nightshift/references/nightshift-rules-template.json` to `$NS/rules.json` as-is, if it does not already exist — the owner's one config file, defaults inline. It lives in nightshift's own folder on purpose: everything nightshift is in one place, kept out of repo history by the same `.nightshift/` gitignore, versioned by the receipts repo when one exists — and deleting `$NS/` removes all of nightshift, rules included. Validate the file with `jq -e 'type == "object"'` and report a broken one plainly — never half-apply it. On native Windows, validate with `Get-Content -Raw -LiteralPath "$NS\rules.json" | ConvertFrom-Json`; PowerShell's JSON parser is built in, so native setup has no `jq` or Python prerequisite. The template's `$schema` field points at `$NIGHTSHIFT_PLUGIN_ROOT/skills/nightshift/references/nightshift-rules.schema.json` so editors catch invalid names, types, and values; it is ignored at runtime. Editor discovery is documented in https://github.com/orwa-mahmoud/nightshift/blob/main/docs/knobs.md. The rules file is portable across hosts, so never generate a host-specific copy. Its `toolDeny` map carries three native question names: `AskUserQuestion` for Claude Code, `request_user_input` for Codex, and `AskQuestion` for Cursor. A non-empty value denies that exact tool with the owner's message; an empty value allows it. All three entries stay present so deleting a key can never activate an invisible default. JSON has no comments; the schema descriptions and https://github.com/orwa-mahmoud/nightshift/blob/main/docs/knobs.md#tool-rules are the inline help. The hooks read this file directly on every tool call: an owner's edit applies from their very next action. Nothing is synced anywhere, nothing needs a restart, and there is no second copy. Env vars of the matching names (`NIGHTSHIFT_FORBIDDEN_COMMANDS`, `NIGHTSHIFT_TOOL_RULES`, …) remain session-start overrides for tests and one-off exceptions — say so only if asked. If Claude Code's `$TASK_ROOT/.claude/settings.local.json` still carries `NIGHTSHIFT_*` env keys an earlier version synced from this file, offer to remove them: the file is the one copy. **Local rule profiles — offer, never impose.** Setup may list the shipped examples in `$NIGHTSHIFT_PLUGIN_ROOT/skills/nightshift/references/profiles/` (every version-1 or version-2 JSON file there) and preview one with `"$NIGHTSHIFT_PLUGIN_ROOT/runtime/ns" apply-profile --profile --mode fill|replace`. The helper prints the preview and the complete next file; read it out rather than describing it. Applying requires an explicit yes and `--apply`. Refuse `--apply` while armed. Profiles are a one-time local copy — no network, no subscription. After applying a profile, write a preset receipt from `$NIGHTSHIFT_PLUGIN_ROOT/skills/nightshift/references/receipts/cycle-specialist-evidence.md` so branch mode, allowed sources, verification profile, receipt retention, resource limits, and direct-mode boundaries trace to `rules.json`. Owner rules remain authoritative; presets never capture hidden policy. **Template evolution — offer, never impose.** On a re-run with the file already present, compare the shipped template's top-level keys and its nested `toolDeny` keys to the owner's file (read the JSON in the skill; do not ask the owner to install `jq` or Python; on native Windows, `(Get-Content -Raw -LiteralPath "$NS\rules.json" | ConvertFrom-Json).PSObject.Properties.Name` and the same for `.toolDeny`): offer any missing key with its default — "this version added `request_user_input`; add it?" — and never touch a value the owner already has. A missing native question key is a configuration error, not permission to invent a fallback. Same posture for the contract: if the shipped punch-list template's contract (the text above `## Items`) has changed since the owner's copy was scaffolded, show the diff and offer a merge — the owner's wording wins every conflict, and a punch list with open boxes is never touched at all. The same offer applies when the owner's contract is leftover campaign text (a finished branch, release, or issue-close list) even if the shipped template has not changed: show the diff and offer to restore the template contract, or keep theirs. Never rewrite without an explicit yes. ## 6. Summarize Print the workspace-state path and resolved work target, what was scaffolded, whether a receipts repo was created, the gates that were written (or that none were), and the project defaults stored in the `shift` block of `$NS/rules.json`. Tell the user to draft items in `$NS/drafting-table.md`, promote them into the punch list, then start the shift (`/nightshift:start` on Claude Code, or ask Nightshift to start on Codex). Mention that the open-ended product-evolution shift keeps its evidence and ranked work in `$NS/product-research.md` and `$NS/opportunity-map.md`, while the quality skill can turn existing lint/type debt into proposed items whenever they want it.