@wildorder/nightshift 0.1.0 → 0.2.0

package/skills/init-project/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: init-project
+description: Initialize a new repository or adopt an existing one into the nightshift structure, including deriving the vision and as-built docs from existing code. Use when a user asks to set up, initialize, or onboard a project for nightshift.
+argument-hint: "[project-root]"
+disable-model-invocation: true
+---
+
+# Initialize or adopt a project
+
+Use the supplied argument as the project root. When omitted, use the current
+working directory.
+
+## Step 1 — Detect project type
+
+Inspect the root. If it contains source code, a populated README, or other
+project documentation, treat this as a **brownfield adoption**. An empty or
+near-empty directory is a **greenfield initialization**.
+
+## Step 2 — Ask about version control upfront
+
+Check whether the root is inside a git repository
+(`git rev-parse --is-inside-work-tree`). Ask these questions now, alongside
+the project questions — never defer them to a suggested next step:
+
+1. If it is **not** a repository: "Initialize a git repository here?" If yes,
+   run `git init` before any scaffolding so everything that follows is
+   tracked from the start.
+2. In all cases: "Commit the nightshift setup when finished?" If yes, plan to
+   commit at the end of this workflow.
+3. Brownfield with uncommitted changes: point out the dirty tree and confirm
+   that the final commit should include only the files this setup created or
+   modified, keeping the user's in-progress work out of it.
+
+Record the answers and apply them in Step 6. Git is not optional decoration
+for nightshift: the decision ledger tags commits and replays roll back to
+them, so if the user declines a repository entirely, warn that decision
+replay, rollback, and per-workstream checkpoints will all be unavailable,
+then proceed.
+
+## Step 3 — Gather project information
+
+The initializer resolves defaults on its own: name and description from
+`package.json`, and the stack by scanning manifests (package.json,
+tsconfig.json, pyproject.toml, go.mod, Cargo.toml).
+
+- Greenfield: ask for the project name, stack, and one-line description, and
+  wait for the response.
+- Brownfield: state the values you expect detection to produce and ask only
+  about gaps or corrections. Do not re-ask for what the repository already
+  declares.
+
+### Agent roles
+
+Also ask which agent CLI (and model) fills each of nightshift's roles. Never
+leave this implicit — it is the most consequential configuration in the
+project. Each block in `nightshift.config.json` declares a command, args, and
+prompt mode, spelled in that CLI's own vocabulary:
+
+1. **Implementer** (`agent`) — executes each workstream. A cheaper model is
+   usually the right call, for example
+   `{ "command": "claude", "args": ["-p", "--model", "sonnet"], "promptMode": "stdin" }`.
+2. **Decider** (`deciderAgent`) — makes, ratifies, or escalates the decisions
+   agents surface during a run, and composes the human notification when one
+   is warranted. Decisions are the highest-leverage, lowest-token work in a
+   run, so recommend the most capable model available here — and a
+   **different provider than the implementer**, because ratifying the
+   implementer's own choices with the implementer's own model re-creates the
+   self-grading conflict this role exists to remove. If the user picks the
+   same provider anyway, note the tradeoff and respect the choice.
+3. **Reviewer** (`reviewerAgent`) — the independent second opinion: spec
+   critique before build, test critique after each workstream, whole-program
+   review at the end. Recommend a different provider than the implementer.
+   Leave the model flag out of its args and let the external CLI run its own
+   default — the role wants an uncorrelated second opinion, which that
+   default already is, and a named model is one more thing to go stale.
+4. **Recovery** (`recoveryAgent`, optional) — retries failed workstreams. A
+   distinct provider also lets a run survive a primary quota, token, or
+   session failure. Skip it if the user has no second implementer available.
+
+An absent `deciderAgent` does not break runs — implementer defaults simply
+stand unratified, and the run report says so — but recommend configuring it:
+it is the difference between "decisions were made" and "decisions were
+reviewed". An absent `reviewerAgent` disables the review passes entirely and
+is reported, never silently substituted.
+
+If the user has no preference, record the host's current model for the
+implementer and recommend a distinct decider and reviewer. Roles can be
+filled in later, but say so explicitly in the report — a run started before
+`agent` is set aborts immediately.
+
+Ask the Step 2 and Step 3 questions together in one message when possible.
+
+## Step 4 — Run the deterministic initializer
+
+```sh
+npx --yes @wildorder/nightshift init --cwd "{project-root}"
+```
+
+Always invoke the CLI by its full package name. The executable is named
+`nightshift`, but the package is `@wildorder/nightshift` — a bare
+`npm exec nightshift` only resolves when the *shell's* working directory
+already has the package installed, and otherwise queries the registry for the
+unscoped name, which is not this package. That is the common case here,
+because `init` usually targets a project root that has no `node_modules` yet.
+
+Add `--name`, `--stack`, or `--description` only for values the user supplied
+or detection cannot provide. Do not manually reproduce the templates; the CLI
+is the canonical write path. It:
+
+- creates the standard directories and any missing starter files without
+  overwriting existing ones;
+- merges the universal directives into an existing `AGENTS.md` by adding or
+  refreshing only the marked `BEGIN/END UNIVERSAL` block, leaving all other
+  content untouched;
+- prefills `verify` commands from `package.json` scripts and records existing
+  markdown documentation as `contextDocs` in `nightshift.config.json`.
+
+The universal directives come from the packaged template by default; a user
+override is honored from `~/.nightshift/universal-directives.md`, or pass
+`--directives <path>` when the user names a directives file.
+
+After the initializer runs, write the role decisions from Step 3 into
+`nightshift.config.json`, for example:
+
+```json
+"agent": { "command": "claude", "args": ["-p", "--model", "sonnet"], "promptMode": "stdin" },
+"deciderAgent": { "command": "codex", "args": ["exec", "--model", "gpt-5.4"], "promptMode": "stdin" },
+"reviewerAgent": { "command": "codex", "args": ["exec"] }
+```
+
+Before moving on, re-read the file and confirm the blocks the user chose are
+all present. When adopting a project whose `nightshift.config.json` already
+existed, check it for the same blocks and add whichever the user asked for.
+
+## Step 5 — Confirm workflow skills are present
+
+Check whether the project already contains installed nightshift skills
+(`.cursor/skills/`, `.claude/skills/`, `skills/`, `.agents/skills/`, or
+`.gemini/skills/`). If any target is present, the team has already chosen
+its targets — do not install more, and do not re-run the installer.
+
+Only when no target is installed at all (for example, when initializing a
+different project root than the one this skill is running from), ask the
+user which targets they want and run:
+
+```sh
+npx --yes @wildorder/nightshift install --cwd "{project-root}" --targets {chosen}
+```
+
+Never use `--force` unless the user explicitly approves replacing a reported
+skill conflict.
+
+## Step 6 — Brownfield enrichment
+
+Skip this step for greenfield projects.
+
+1. **Snapshot reality.** Scan the codebase — entry points, schema files,
+   route registrations, shared contracts, infrastructure config — and write
+   `docs/as-built.md`, noting it as the initial adoption snapshot. This
+   grounds all later planning in what actually exists.
+2. **Author the vision.** The CLI scaffolded `docs/vision.md` as a template.
+   Draft its real content from the as-built snapshot plus a short interview:
+   what the product is for, target users, where it is heading, and what is
+   explicitly out of scope. Write the draft directly to `docs/vision.md` —
+   the file is the review surface; do not paste the content into the
+   conversation for approval. Summarize briefly and invite edits, applying
+   them to the file in place.
+3. **Complete `AGENTS.md`.** Fill the project Conventions section from
+   observed practice — lint and formatter configs, test layout, naming
+   patterns — and confirm the generated dependency table reflects the
+   packages that matter.
+4. **Curate `contextDocs`.** Review the detected list in
+   `nightshift.config.json`: remove documents that are stale or irrelevant
+   and add any the user names. Planning reads every listed document, so the
+   list should be signal, not bulk.
+
+## Step 7 — Apply the version-control decisions
+
+Execute what the user approved in Step 2:
+
+- If a commit was approved, stage exactly the files this setup created or
+  modified and commit with a message like `chore: adopt nightshift`.
+  Do not stage unrelated in-progress changes.
+- If the user declined, leave the working tree as is.
+
+## Step 8 — Report
+
+Report:
+
+1. Files created, updated, and skipped.
+2. Skill conflicts, if any.
+3. Warnings from the initializer.
+4. The configured agent roles, and which roles were deferred.
+5. Brownfield: the as-built and vision drafts produced and any assumptions.
+6. Git actions taken (repository initialized, setup committed) or declined.
+7. Next step: invoke `/plan-program` for the first program.

package/skills/plan-program/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: plan-program
+description: Plan a new engineering program or product phase, define architecture changes and workstreams, and produce the canonical program document and manifest. Use when turning a feature set into an executable program plan.
+argument-hint: "[program-id] [feature-set-or-phase]"
+disable-model-invocation: true
+---
+
+# Plan a program
+
+Plan a new feature set or phase for the current project. This is one of the
+two places a human exercises judgment in nightshift; everything downstream is
+a walk-away run, so the plan you produce here is the last routine chance to
+shape the work interactively. Write every artifact for a human reader first —
+the run's trust surface is its artifacts.
+
+## 1. Load project context
+
+Read:
+
+- The vision document at `visionPath` from `nightshift.config.json`, the
+  anchor product vision. Use `docs/vision.md` only when no configuration
+  exists.
+- `docs/as-built.md`, when present, for current system state.
+- `AGENTS.md` for repository directives and conventions.
+- Every document listed in `contextDocs` from `nightshift.config.json`, when
+  present.
+- When re-planning after a run, the program's run report and decision ledger
+  under `docs/programs/` — a prior run's parked workstreams, risk-accepted
+  findings, and recorded decisions are planning input, not noise. Plan from
+  the repository state that exists now, not from the original pre-program
+  design; treat work a prior run verified and committed as current
+  architecture rather than scheduling it again, and give replacement work new
+  workstream IDs and task-file paths so nothing overwrites the historical
+  record.
+
+If no vision document exists at the resolved path, stop. Explain that it
+should contain the product description, architecture, target users, API
+surface, data model, phase scope, and technology stack. For a new repository,
+suggest the `init-project` skill.
+
+If `docs/as-built.md` is absent, note that this is likely the first program
+and proceed.
+
+## 2. Gather requirements
+
+Resolve these values from the arguments or ask for anything missing:
+
+1. The feature set or phase to build.
+2. A lowercase, hyphenated program ID, such as `phase-2-durable`.
+
+Wait for the user's response when questions are required.
+
+### Select the execution mode
+
+Choose the mode before decomposing the work and record the decision in both
+artifacts. Default to `atomic` unless there is positive causal evidence that
+orchestration is necessary.
+
+- **`atomic`** — one cohesive agent working set, one implementation brief,
+  and one green commit. Choose this when a capable coding agent can own the
+  whole change coherently and intermediate checkpoints add no material safety
+  or parallelism.
+- **`orchestrated`** — multiple independently-green workstreams executed as a
+  dependency graph. Choose this when the minimum static context physically
+  cannot fit one agent session, independent work provides material
+  parallelism, independently deployable service boundaries matter, or a
+  shared-contract migration requires expand → migrate consumers →
+  contract/delete ordering.
+
+Do not choose orchestrated merely because the feature is important, spans
+many files, or has a high estimated token count. State the concrete evidence
+in `program.executionModeReason`. In atomic mode create exactly one
+workstream covering the entire program, with no dependencies and task file
+`tasks/{program-id}/implementation.md`. In orchestrated mode use the
+decomposition and checkpoint rules below.
+
+## 3. Draft the program document
+
+Inspect `docs/programs/` for an existing `*-program.md`. Match its structure
+when one exists. Otherwise use:
+
+```markdown
+# {Project Name} — Program Plan ({Program Name})
+
+## Program Overview
+**Product:** [From the vision.]
+**Program scope:** [What this program delivers.]
+
+## Execution Mode
+**Mode:** atomic | orchestrated
+**Reason:** [Concrete causal evidence for the choice.]
+
+## Strategic Goals
+[Three to five outcome-focused bullets.]
+
+## Architecture Changes
+[Changes from the system in as-built.md. For the first program, describe the full architecture.]
+
+## Technology Choices
+[Only new choices. If none: "No new technology — uses existing stack."]
+
+## Anticipated Decisions
+[Choices you can already see the run will face — API shapes, data-model
+tradeoffs, library picks — with your leaning and why. The decider reads
+these; a decision anticipated here is a decision the run handles better.]
+
+## Risk Register
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+[Key risks.]
+
+## Success Criteria, Workstreams, and Scope
+Canonical in `docs/programs/{program-id}-manifest.json`: success-criteria
+text, the workstream roster, dependencies, sizes, scope, and exclusions live
+there and only there. This document refers to them by id (`SC-xx`, `WS-xx`)
+and never restates their text.
+```
+
+The program document carries only what the manifest cannot: narrative
+architecture, causal reasoning, anticipated decisions, and risks. Success
+criteria, the workstream table, the dependency graph, and scope in/out lists
+are manifest data — do not reproduce them here. Two copies of the same fact
+drift apart; one canonical home per fact is a founding rule of this system.
+When this section's rule and an older program document's structure conflict,
+this rule wins: delete the duplicated sections rather than matching them.
+
+Write the draft directly to `docs/programs/{program-id}-program.md`. Do not
+paste the document into the conversation or ask for approval before saving —
+the file is the review surface, not the chat window.
+
+## 4. Generate the manifest
+
+If `docs/programs/` contains an existing `*-manifest.json`, match its schema
+exactly. Otherwise use:
+
+```json
+{
+  "program": {
+    "id": "{program-id}",
+    "name": "{Program Name}",
+    "description": "{one-line description}",
+    "status": "planning",
+    "created": "{YYYY-MM-DD}",
+    "executionMode": "atomic|orchestrated",
+    "executionModeReason": "{concrete causal evidence}"
+  },
+  "technology": {},
+  "successCriteria": [
+    { "id": "SC-01", "description": "{verifiable outcome}" }
+  ],
+  "packages": [
+    {
+      "name": "{package-name}",
+      "path": "{relative-path}",
+      "description": "{purpose}"
+    }
+  ],
+  "workstreams": [
+    {
+      "id": "WS-01",
+      "name": "{Workstream Name}",
+      "taskFile": "tasks/{program-id}/{ws-id}-{slug}.md",
+      "status": "not_started",
+      "size": "S|M|L",
+      "scope": {
+        "summary": "{one line: what this workstream owns}",
+        "includes": ["{specific thing it covers}"],
+        "excludes": ["{specific thing it deliberately does not cover}"]
+      },
+      "dependencies": [],
+      "packages": []
+    }
+  ],
+  "outOfScope": []
+}
+```
+
+Save it directly to `docs/programs/{program-id}-manifest.json`.
+Keep the manifest, program document, and every referenced `taskFile`
+trackable by Git — nightshift tags decisions to commits and replays roll back
+to them, so a plan that exists only in an ignored working tree is neither
+reproducible nor replayable. If the repository ignores `tasks/` or
+`docs/programs/`, remove those ignore rules or explicitly force-add these
+canonical artifacts.
+
+For `atomic`, the `workstreams` array contains exactly one whole-program
+workstream (`WS-01`) whose `taskFile` is
+`tasks/{program-id}/implementation.md`. For `orchestrated`, it contains the
+dependency graph described in the program document.
+
+### Scope is load-bearing, not decoration
+
+`scope` is required on every workstream, and the reason is worth
+understanding before you write them.
+
+Authoring spawns one clean agent per workstream, and every one of those
+agents is handed the roster of the whole program — each workstream's id,
+name, and scope, and nothing else. That roster is how an author discovers
+that another workstream already owns something it was about to build, or
+produces something it needs. An author that cannot tell what `WS-12` covers
+will not merely omit a dependency; it will reimplement WS-12's work.
+
+So write these for a reader who has no other information about that
+workstream:
+
+- **`summary`** — one line naming what it owns. "Auth improvements" tells an
+  author nothing. "Issues, rotates, and validates auth tokens" tells it
+  everything it needs to decide whether to depend on this.
+- **`includes`** — the specific capabilities inside the boundary.
+- **`excludes`** — the specific capabilities deliberately outside it. These
+  carry more weight than they look. An exclusion tells every other author
+  that something is *not* covered here, which prevents both duplicated work
+  and a requirement that silently belongs to nobody. If a workstream's
+  neighbors might reasonably assume it handles something, say that it does
+  not.
+
+### Every orchestrated workstream is an independently green checkpoint
+
+Design the roster so that, starting from a green repository containing only
+its declared dependencies, each workstream can finish with every configured
+build, typecheck, test, and lint command still green. A later workstream must
+never be required to repair an earlier checkpoint — and in nightshift this
+matters doubly, because a failed workstream is parked while everything
+outside its downstream cone still builds; a roster whose checkpoints lean on
+later repair work turns one parked workstream into a broken partial build.
+
+For a shared contract migration, prefer an explicit sequence:
+
+1. **Expand** — introduce the new contract while preserving compatibility.
+2. **Migrate** — move bounded consumer groups in independently green batches.
+3. **Contract/delete** — remove the compatibility surface only after every
+   consumer migration is complete.
+
+The destructive cleanup depends on every migration workstream. Do not place
+foundational deletion first merely because it is conceptually central.
+
+## 5. Hand off for review
+
+Both files now exist on disk. Reply with a short summary only — program
+scope in a sentence, selected execution mode and reason, workstream count,
+critical path, and links to the two file paths — and invite the user to
+review the files and request changes. Apply any requested edits to the files
+in place.
+
+Do not create workstream specs in this workflow, and do not offer to. Specs
+are written by the packaged runner, one clean agent per workstream, as
+narrative documents a human can review. Point the user at the run command
+and stop:
+
+```sh
+npx --yes @wildorder/nightshift run "{program-id}"
+```
+
+Authoring a spec inside this session would write it in a context already
+carrying the whole planning conversation, compose its own instructions, and
+then grade its own output — which is what the command exists to prevent.
+
+## Rules
+
+- Describe only new behavior. Reference `docs/as-built.md` for unchanged
+  capabilities.
+- Keep each workstream completable in one agent session and independently
+  green; use causal boundaries instead of hard line-count or file-count
+  rules.
+- List every package or directory each workstream touches.
+- Use stable `SC-xx` success-criteria IDs for downstream traceability.
+- The manifest is the single source of truth for success criteria,
+  workstreams, dependencies, and scope. The program document references them
+  by id and never restates their text.
+- Give every workstream a `scope` with a specific `summary`, and state
+  `excludes` wherever a neighbor might reasonably assume coverage.
+- Record anticipated decisions in the program document — the decider reads
+  them, and a decision anticipated at planning time is handled better at run
+  time.

package/templates/AGENTS.md

@@ -0,0 +1,29 @@
+<!-- BEGIN UNIVERSAL — source: {{UNIVERSAL_SOURCE}} -->
+{{UNIVERSAL_DIRECTIVES}}
+<!-- END UNIVERSAL -->
+
+---
+
+## Project: {{PROJECT_NAME}}
+
+See `docs/vision.md` for the full product vision.
+See `docs/programs/` for program plans and manifests.
+See `tasks/{program-id}/` for workstream specs.
+
+### Tech Stack
+
+{{STACK}}
+
+### Product
+
+{{DESCRIPTION}}
+
+### Conventions
+
+[Document project-specific module structure, naming, IDs, validation, testing, and delivery conventions.]
+
+### Dependency Versions (pin these)
+
+| Package | Version |
+|---------|---------|
+{{DEPENDENCY_ROWS}}

package/templates/CLAUDE.md

@@ -0,0 +1,7 @@
+# Agent Directives
+
+The canonical agent directives, project context, conventions, and constraints for
+{{PROJECT_NAME}} live in **`AGENTS.md`**.
+
+**Read `AGENTS.md` now and follow it.** Do not maintain instructions in this file—
+update `AGENTS.md` instead to keep a single source of truth.

package/templates/universal-directives.md

@@ -0,0 +1,50 @@
+# Agent Directives: Universal
+
+These directives apply to every agent working in this repository, regardless
+of provider or harness.
+
+## Scope and depth
+
+1. SPEC-FIRST: When a workstream spec exists under `tasks/`, read it before
+   implementing. Do not invent architecture that contradicts the spec or
+   `docs/vision.md`. If the spec is ambiguous, ask — do not guess.
+
+2. ROOT CAUSE OVER SYMPTOM: Prefer the smallest diff that fully solves the
+   root cause, not the smallest diff that makes symptoms disappear. When the
+   proper fix is out of scope, say so explicitly and propose it as a
+   follow-up instead of silently shipping a band-aid.
+
+3. STRUCTURAL FIXES STAY IN SCOPE: If architecture is flawed, state is
+   duplicated, or patterns are inconsistent inside the files the task already
+   touches, fix it. Do not expand into unrelated modules without asking. On
+   question-only or review-only tasks, answer — do not rewrite code unless
+   asked.
+
+## Verification
+
+4. VERIFY BEFORE CLAIMING COMPLETION: A successful file write proves nothing
+   about correctness. Before reporting a task complete, run the project's
+   configured build, type-check, test, and lint commands and fix every
+   resulting error. If one of those commands is not configured, state that
+   explicitly instead of claiming it passed.
+
+## Edit safety
+
+5. READ BEFORE EDITING: Read a file before modifying it, and re-read any file
+   you have not seen recently in a long session before editing it again.
+
+6. EXHAUSTIVE RENAMES: When renaming any function, type, or variable, search
+   for direct references, type-level references, string literals, dynamic
+   imports, re-exports, and test files. Do not assume one search pass caught
+   everything.
+
+## Large tasks
+
+7. WORK IN VERIFIABLE PHASES: Break multi-file work into phases that each
+   pass verification on their own. In interactive sessions, pause between
+   phases for review; in automated pipeline runs, complete and verify each
+   phase before starting the next.
+
+8. PARALLELIZE INDEPENDENT WORK: When the harness supports sub-agents and the
+   task spans many independent files, split the work rather than degrading a
+   single context; keep tightly coupled changes together.

package/templates/vision.md

@@ -0,0 +1,46 @@
+# {{PROJECT_NAME}} — Vision Document
+
+## What Is {{PROJECT_NAME}}?
+[One paragraph: what the product is and why it exists.]
+
+**One-liner:** {{DESCRIPTION}}
+
+## The Problem
+[What pain point does this solve? Who has this problem?]
+
+## The Solution
+[High-level description of the approach.]
+
+## Architecture
+[System architecture diagram or description. ASCII art is fine.]
+
+## Core Concepts
+[Key abstractions, entities, or domain concepts.]
+
+## API Surface
+[Public-facing interfaces: SDK methods, REST endpoints, CLI commands, etc.]
+
+## Data Model
+[Key entities and their relationships.]
+
+## Target Users
+[Primary and secondary personas.]
+
+## Technology Stack
+
+**Primary stack:** {{STACK}}
+
+| Layer | Choice | Rationale |
+|-------|--------|-----------|
+| [Layer] | [Technology] | [Why it fits] |
+
+## Scope: Phase 1
+
+**Build:**
+- [Phase 1 deliverable]
+
+**Do not build in Phase 1:**
+- [Explicitly deferred item]
+
+## Scope: Phase 2+
+[Brief notes on future direction—enough to inform architectural decisions.]