nikos 0.2.0 → 0.2.1

package/README.md

@@ -48,6 +48,7 @@ install. More in [docs/install.md](docs/install.md).
 
 You don't need to learn the commands. Your agent runs them and, after each
 request, says where things stand and offers a short menu of what to do next.
+In Claude Code, Codex and Cursor, it also does this when a session starts.
 Things you can say:
 
 - "Set up nikOS here", or "Map what this repo already does"
@@ -113,7 +114,7 @@ shell can use nikOS as a library: [docs/library.md](docs/library.md). A worked e
 | `nikos clear <id>` | Check a story is ready to build |
 | `nikos plan new <id>` | Start the next version of a story's plan |
 | `nikos verify setup` | Add a Cucumber runner for this repo's stack |
-| `nikos ci setup` | Run validate and every story's scenarios on each PR (GitHub Actions) or merge request (GitLab CI) |
+| `nikos ci setup` | Run validate and every story's scenarios on each PR (GitHub Actions) or merge request (GitLab CI), plus a release check you run by hand before shipping |
 | `nikos verify [id]` | Run a story's scenarios, or all of them |
 | `nikos state set <id> <status>` | Move a story; done only if its scenarios pass; cancelled needs a reason |
 | `nikos approve <id>...` | Sign off done stories, in your terminal or (`--via chat`) by answering your agent (writes `intent/approvals.yaml`) |

package/dist/commands/ci.d.ts

@@ -2,6 +2,7 @@ import { type Stack } from "../verify/detect.js";
 export type Host = "github" | "gitlab";
 /** github or gitlab, from the origin remote's url; undefined when it's neither or there's no remote. */
 export declare function detectHost(root: string): Host | undefined;
+export declare function githubReleaseWorkflow(stack: Stack, root: string): string;
 export declare function githubWorkflow(stack: Stack, root: string): string;
 export declare function gitlabJob(stack: Stack, root: string): string;
 export interface CiResult {

package/dist/commands/ci.js

@@ -1,6 +1,10 @@
 // `nikos ci setup`: run nikOS's checks on every pull request (GitHub) or merge request (GitLab).
 // The pipeline runs `nikos validate` and every story's scenarios with `nikos verify`, using the
 // nikos version that wrote it, so a red pipeline means the specs or the code broke, not nikos.
+// A second, run-on-demand pipeline checks a release is ready to ship (nikos release check <n>
+// --run): it fails while a story isn't done, its spec changed, or (when approval.policy is
+// required-for-release) a story isn't approved. It's started by hand, with the release number,
+// rather than on every change, because a release in progress is never ready.
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -20,12 +24,42 @@ export function detectHost(root) {
         return "gitlab";
     return undefined;
 }
+/** The shell steps that install the project and its scenario runner, for a stack. */
+const install = (stack, root) => stack === "python"
+    ? [existsSync(join(root, "requirements.txt")) ? "pip install -r requirements.txt" : "", "pip install behave"].filter(Boolean)
+    : [existsSync(join(root, "package-lock.json")) ? "npm ci" : "npm install"];
 /** The shell steps that install the runner and run the checks, for a stack. */
 function steps(stack, root, nikos) {
-    const install = stack === "python"
-        ? [existsSync(join(root, "requirements.txt")) ? "pip install -r requirements.txt" : "", "pip install behave"].filter(Boolean)
-        : [existsSync(join(root, "package-lock.json")) ? "npm ci" : "npm install"];
-    return [...install, `npx -y ${nikos} validate`, `npx -y ${nikos} verify`];
+    return [...install(stack, root), `npx -y ${nikos} validate`, `npx -y ${nikos} verify`];
+}
+/** The release check, run by hand with the release number. RELEASE comes in as an env var, never pasted into the script. */
+const releaseSteps = (stack, root, nikos, variable) => [...install(stack, root), `npx -y ${nikos} release check "$${variable}" --run`];
+export function githubReleaseWorkflow(stack, root) {
+    const nikos = `nikos@${version()}`;
+    const python = stack === "python" ? `      - uses: actions/setup-python@v5\n        with:\n          python-version: "3.12"\n` : "";
+    return `# Written by nikos ci setup: checks a release is ready to ship. Run it from the Actions tab
+# (Run workflow) with the release number. It fails while a story isn't done, a spec changed
+# after done, or a story needs an approval it doesn't have.
+name: nikos release check
+on:
+  workflow_dispatch:
+    inputs:
+      release:
+        description: The release number to check
+        required: true
+        type: number
+jobs:
+  release-check:
+    runs-on: ubuntu-latest
+    env:
+      RELEASE: \${{ inputs.release }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+${python}${releaseSteps(stack, root, nikos, "RELEASE").map((s) => `      - run: ${s}`).join("\n")}
+`;
 }
 export function githubWorkflow(stack, root) {
     const nikos = `nikos@${version()}`;
@@ -60,6 +94,15 @@ nikos:
     - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
   script:
 ${[...setup, ...steps(stack, root, nikos)].map((s) => `    - ${s}`).join("\n")}
+
+# Checks a release is ready to ship. Run a pipeline by hand (Build > Pipelines > New pipeline)
+# with the variable NIKOS_RELEASE set to the release number.
+nikos-release:
+  image: ${image}
+  rules:
+    - if: $NIKOS_RELEASE
+  script:
+${[...setup, ...releaseSteps(stack, root, nikos, "NIKOS_RELEASE")].map((s) => `    - ${s}`).join("\n")}
 `;
 }
 const GITLAB_JOB = ".gitlab/ci/nikos.yml";
@@ -84,17 +127,22 @@ export function setupCi(root, opts = {}) {
     };
     if (host === "github") {
         write(".github/workflows/nikos.yml", githubWorkflow(stack, root));
+        write(".github/workflows/nikos-release.yml", githubReleaseWorkflow(stack, root));
         return { host, created, skipped };
     }
     // GitLab reads one .gitlab-ci.yml, so the job lives in its own file and is included from it.
     write(GITLAB_JOB, gitlabJob(stack, root));
+    // A job file from before the release check: say what to add rather than rewrite it.
+    const old = skipped.includes(GITLAB_JOB) && !readFileSync(join(root, GITLAB_JOB), "utf8").includes("nikos-release:");
+    const releaseTodo = old ? `Add the release check job to ${GITLAB_JOB}:\n${gitlabJob(stack, root).slice(gitlabJob(stack, root).indexOf("# Checks a release"))}` : undefined;
     const main = join(root, ".gitlab-ci.yml");
     if (!existsSync(main)) {
         write(".gitlab-ci.yml", INCLUDE);
-        return { host, created, skipped };
+        return { host, created, skipped, ...(releaseTodo ? { todo: releaseTodo } : {}) };
     }
     const included = readFileSync(main, "utf8").includes(GITLAB_JOB);
-    return { host, created, skipped, todo: included ? undefined : `Add this to .gitlab-ci.yml:\n${INCLUDE}` };
+    const todo = [included ? "" : `Add this to .gitlab-ci.yml:\n${INCLUDE}`, releaseTodo ?? ""].filter(Boolean).join("\n");
+    return { host, created, skipped, ...(todo ? { todo } : {}) };
 }
 export function runCi(args) {
     const [sub, ...rest] = args;
@@ -114,6 +162,9 @@ export function runCi(args) {
         if (r.todo)
             console.log(`\n${r.todo}`);
         console.log(`\nEvery ${r.host === "github" ? "pull request" : "merge request"} now runs nikos validate and every story's scenarios.`);
+        console.log(r.host === "github"
+            ? "To check a release is ready to ship, run the \"nikos release check\" workflow from the Actions tab with its number."
+            : "To check a release is ready to ship, run a pipeline by hand with NIKOS_RELEASE set to its number.");
         return 0;
     }
     catch (err) {

package/docs/install.md

@@ -32,6 +32,10 @@ add the marketplace first, then install:
 From a terminal, the same commands are `claude plugin marketplace add
 nikovijay/NikOS` and `claude plugin install nikos@nikos`.
 
+At the start of each session in a repo with a story map, the plugin's hook
+(`hooks/hooks.json`) tells the agent where things stand and what to suggest
+next.
+
 ## Codex
 
 ```
@@ -41,6 +45,14 @@ codex plugin marketplace add nikovijay/NikOS
 Then install nikOS from the Plugins directory. Update it later with `codex
 plugin marketplace upgrade`.
 
+The plugin ships the same session-start hook as Claude Code
+(`hooks/hooks.json`). Codex runs a plugin's hooks only after you review and
+trust them, and asks again when they change. Until you trust it, nikOS works
+without it: the agent runs `nikos suggest` itself after each request. Codex's
+docs say plugin hooks run for plugins installed manually in the Codex desktop
+app, and that plugins with hooks can't be listed in its public plugin
+directory.
+
 ## Cursor
 
 Cursor installs plugins from a marketplace in its settings rather than a
@@ -50,6 +62,11 @@ then Add Marketplace, then Import from Repo), and install nikOS from it.
 To try it without a marketplace, copy the repo to
 `~/.cursor/plugins/local/nikos` and run "Developer: Reload Window".
 
+The plugin's `sessionStart` hook (`hooks/cursor-hooks.json`) adds where things
+stand and what to suggest next to each new conversation, in a repo with a story
+map. Cursor runs it without waiting, so on a slow first run (while `npx` fetches
+nikos) it can land after your first message. It doesn't run in cloud agents.
+
 ## Packs
 
 Packs are extra tools that install on their own, next to nikOS or without it.
@@ -126,6 +143,12 @@ name fields again on 2026-11-05 (no page showed a version):
 - Codex: https://developers.openai.com/plugins/build/plugins. The plugin
   title is `interface.displayName` in `.codex-plugin/plugin.json`. The
   marketplace title is the same field on `.agents/plugins/marketplace.json`.
+- Hooks, read on 2026-11-06: Cursor's https://cursor.com/docs/agent/hooks
+  (`sessionStart`, JSON output with `additional_context`, `timeout` in seconds;
+  a plugin points at its hooks with `hooks` in `.cursor-plugin/plugin.json`),
+  and Codex's plugin page above and https://learn.chatgpt.com/docs/hooks
+  (`SessionStart`, the same format as Claude Code, plain stdout added as
+  context, hooks run only once trusted).
 
 All three find skills as `skills/<name>/SKILL.md` at the plugin root.
 `test/install.test.ts` checks the manifests agree with each other and with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nikos",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Spec-driven development for AI coding agents: story maps, Gherkin acceptance criteria and a done gate for Claude Code, Codex and Cursor",
   "license": "MIT",
   "author": "Niko Vijay",

package/skills/verify/SKILL.md

@@ -56,3 +56,10 @@ GitLab CI (`.gitlab/ci/nikos.yml`, included from `.gitlab-ci.yml`). Pass
 `--github` or `--gitlab` when there's no remote yet. If the repo already has a
 `.gitlab-ci.yml`, it prints the `include:` lines to add: add them, and show the
 person the change.
+
+It also adds a release check the person runs by hand when a release is meant to
+ship: the "nikos release check" workflow on GitHub (Actions tab, Run workflow,
+with the release number), or on GitLab a pipeline run with `NIKOS_RELEASE` set to
+it. It fails while a story isn't done, a spec changed after done, or (when
+`approval.policy` is `required-for-release`) a story isn't approved. Tell the
+person how to run it; don't run it on every change.