nikos 0.0.0-stage → 0.0.2

package/dist/lint/gherkin.js

@@ -0,0 +1,99 @@
+import { AstBuilder, GherkinClassicTokenMatcher, Parser } from "@cucumber/gherkin";
+import { IdGenerator } from "@cucumber/messages";
+import { STORY_ID } from "../lib/project.js";
+/** Tags that describe progress, which belongs in state.yaml, not the spec. */
+const STATUS_TAGS = /^@(todo|done|wip|in[-_]?progress|doing|blocked|needs[-_]?rework|ready|review|approved|complete[d]?|skip|pending)$/i;
+const PRIORITY = /^@(must|should|could)$/;
+const AC_TAG = /^@AC\d+$/;
+const KNOWN_FEATURE_TAG = [STORY_ID, /^release-\d+$/, /^(must|should|could)$/, /^activity-[a-z0-9-]+$/, /^effort-(XS|S|M|L|XL)$/];
+function parser() {
+    return new Parser(new AstBuilder(IdGenerator.uuid()), new GherkinClassicTokenMatcher());
+}
+/** Parse a feature file. Throws on invalid Gherkin. */
+export function parseFeature(text) {
+    return parser().parse(text).feature;
+}
+/** Every scenario in a feature, including those inside Rules. */
+export function scenariosOf(feature) {
+    return feature.children.flatMap((c) => (c.scenario ? [c.scenario] : c.rule ? c.rule.children.flatMap((rc) => (rc.scenario ? [rc.scenario] : [])) : []));
+}
+export function lintFeature(text) {
+    const issues = [];
+    const featureLines = text.split("\n").filter((l) => /^\s*Feature:/.test(l)).length;
+    if (featureLines > 1) {
+        issues.push({ level: "error", message: `has ${featureLines} Features`, hint: "one Feature per file, one file per story" });
+    }
+    let doc;
+    try {
+        doc = parser().parse(text);
+    }
+    catch (err) {
+        issues.push({ level: "error", message: `isn't valid Gherkin: ${err.message.split("\n")[0]}` });
+        return issues;
+    }
+    const feature = doc.feature;
+    if (!feature) {
+        issues.push({ level: "error", message: "has no Feature", hint: "start the file with a story id tag and `Feature: <title>`" });
+        return issues;
+    }
+    const tags = feature.tags.map((t) => t.name);
+    for (const tag of tags) {
+        if (STATUS_TAGS.test(tag)) {
+            issues.push({ level: "error", message: `uses status tag ${tag}`, hint: "status lives in state.yaml, not in the feature" });
+        }
+        else if (!KNOWN_FEATURE_TAG.some((re) => re.test(tag.slice(1)))) {
+            issues.push({ level: "warning", message: `has unrecognised tag ${tag}`, hint: "allowed: story id, @release-N, @must/@should/@could, @activity-<id>, @effort-<size>" });
+        }
+    }
+    if (tags.filter((t) => PRIORITY.test(t)).length !== 1) {
+        issues.push({ level: "error", message: "needs exactly one priority tag on the Feature", hint: "add @must, @should or @could" });
+    }
+    if (!tags.some((t) => /^@release-\d+$/.test(t))) {
+        issues.push({ level: "error", message: "has no @release-N tag" });
+    }
+    const desc = feature.description ?? "";
+    // "As a", "As an" and "As the" all name a role; I want and So that are fixed.
+    const parts = [["As a", /^\s*As (?:an?|the)\s+\S/im], ["I want", /^\s*I want\b/im], ["So that", /^\s*So that\b/im]];
+    const missing = parts.filter(([, re]) => !re.test(desc)).map(([label]) => label);
+    if (missing.length) {
+        issues.push({
+            level: "error",
+            message: `user story is missing ${missing.map((m) => `"${m}"`).join(", ")}`,
+            hint: "put As a … / I want … / So that … on separate lines under Feature:",
+        });
+    }
+    const scenarios = scenariosOf(feature);
+    if (scenarios.length === 0) {
+        issues.push({ level: "warning", message: "has no scenarios yet", hint: "add one Scenario per acceptance criterion" });
+    }
+    const labels = new Set();
+    for (const s of scenarios) {
+        const sTags = s.tags.map((t) => t.name);
+        const ac = sTags.find((t) => AC_TAG.test(t));
+        for (const tag of sTags) {
+            if (STATUS_TAGS.test(tag)) {
+                issues.push({ level: "error", message: `scenario "${s.name}" uses status tag ${tag}`, hint: "status lives in state.yaml, not in the feature" });
+            }
+        }
+        if (!ac) {
+            issues.push({ level: "error", message: `scenario "${s.name}" has no @AC<n> tag`, hint: "tag each scenario with its criterion label, e.g. @AC1" });
+            continue;
+        }
+        if (labels.has(ac))
+            issues.push({ level: "error", message: `${ac} is used by more than one scenario` });
+        labels.add(ac);
+        if (!s.name.startsWith(`${ac.slice(1)} `)) {
+            issues.push({ level: "warning", message: `scenario "${s.name}" should start with its label`, hint: `e.g. "${ac.slice(1)} — ${s.name}"` });
+        }
+        if (sTags.filter((t) => PRIORITY.test(t)).length > 1) {
+            issues.push({ level: "error", message: `scenario "${s.name}" has more than one priority tag` });
+        }
+        // Given is optional (a scenario can start from nothing); When and Then are not.
+        const keywords = new Set(s.steps.map((st) => st.keyword.trim()));
+        for (const k of ["When", "Then"]) {
+            if (!keywords.has(k))
+                issues.push({ level: "error", message: `scenario "${s.name}" has no ${k} step` });
+        }
+    }
+    return issues;
+}

package/dist/lint/portable.js

@@ -0,0 +1,66 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { parse } from "yaml";
+/** The only frontmatter keys every harness (Claude Code, Cursor, Codex) understands. */
+const ALLOWED_KEYS = ["name", "description"];
+/** Tool names that exist in one harness only. A portable skill describes the action instead. */
+const HARNESS_TOOLS = [
+    "TodoWrite", "TodoRead", "TaskCreate", "TaskUpdate", "TaskList", "AskUserQuestion",
+    "EnterPlanMode", "ExitPlanMode", "NotebookEdit", "SlashCommand", "todo_write", "update_plan",
+    "apply_patch", "$ARGUMENTS", "allowed-tools",
+];
+/** Lint one SKILL.md (or a file it links to) for harness-specific features. */
+export function lintSkill(text, { isEntry = true } = {}) {
+    const issues = [];
+    let body = text;
+    if (isEntry) {
+        const m = /^---\n([\s\S]*?)\n---\n/.exec(text);
+        if (!m) {
+            issues.push({ level: "error", message: "has no frontmatter", hint: "start with ---, name: and description:, then ---" });
+        }
+        else {
+            body = text.slice(m[0].length);
+            let meta = {};
+            try {
+                meta = parse(m[1]) ?? {};
+            }
+            catch (err) {
+                issues.push({ level: "error", message: `frontmatter isn't valid YAML: ${err.message.split("\n")[0]}` });
+            }
+            for (const key of Object.keys(meta)) {
+                if (!ALLOWED_KEYS.includes(key)) {
+                    issues.push({ level: "error", message: `frontmatter key '${key}' isn't portable`, hint: "use only name and description" });
+                }
+            }
+            for (const key of ALLOWED_KEYS) {
+                if (typeof meta[key] !== "string" || !meta[key].trim()) {
+                    issues.push({ level: "error", message: `frontmatter is missing '${key}'` });
+                }
+            }
+        }
+    }
+    for (const tool of HARNESS_TOOLS) {
+        if (body.includes(tool)) {
+            issues.push({ level: "error", message: `names the harness-only tool '${tool}'`, hint: "describe the action (\"your task list\") instead" });
+        }
+    }
+    return issues;
+}
+/** Lint every Markdown file under a skills/ folder. SKILL.md files are entry points and need frontmatter. */
+export function lintSkills(dir) {
+    const issues = [];
+    const walk = (d) => {
+        for (const name of readdirSync(d)) {
+            const path = join(d, name);
+            if (statSync(path).isDirectory())
+                walk(path);
+            else if (name.endsWith(".md")) {
+                const file = relative(dir, path);
+                for (const i of lintSkill(readFileSync(path, "utf8"), { isEntry: name === "SKILL.md" }))
+                    issues.push({ ...i, file });
+            }
+        }
+    };
+    walk(dir);
+    return issues;
+}

package/dist/verify/detect.js

@@ -0,0 +1,21 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const PYTHON_MARKERS = ["pyproject.toml", "requirements.txt", "setup.py", "setup.cfg", "Pipfile"];
+/** Pick the Cucumber runner's stack from the files at the repo root. Undefined means ask the person. */
+export function detectStack(root) {
+    const pkgPath = join(root, "package.json");
+    if (existsSync(pkgPath)) {
+        let pkg = {};
+        try {
+            pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        }
+        catch {
+            // An unreadable package.json is still a JS project.
+        }
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        return existsSync(join(root, "tsconfig.json")) || "typescript" in deps ? "ts" : "js";
+    }
+    if (PYTHON_MARKERS.some((f) => existsSync(join(root, f))))
+        return "python";
+    return undefined;
+}

package/docs/format.md

@@ -0,0 +1,296 @@
+# The intent/ format
+
+Format version: **1**
+
+nikOS keeps a project's intent — what it's for, what to build, how it's going —
+in an `intent/` folder at the root of the repo. Everything is plain text, so
+agents, humans, git and code review all see the same thing.
+
+```
+intent/
+  constitution.md        the project's vision
+  storymap.yaml          activities, releases and story order
+  features/
+    <activity>/
+      <story-slug>.feature   one story, its criteria as scenarios
+  plans/
+    <story-id>.v<N>.md   versioned implementation plans
+  decisions.md           append-only decision log
+  state.yaml             status, blockers and the run queue
+  outreach/              optional, drafts from the validate playbook
+    <date>-<channel>.md
+  bets/                  optional, time-boxed bets (see Bets)
+    <bet-id>.md
+```
+
+Two rules hold across every file:
+
+1. **Specs describe intent, not implementation.** Feature files and the
+   constitution say what and why. File paths, frameworks and code belong in
+   plans and decisions.
+2. **Changing state never edits a spec.** Status, owners, blockers and dates
+   live in `state.yaml`, so a spec's diff only changes when the intent does.
+
+Every file below is listed with its **purpose**, **path** and **format**.
+
+---
+
+## constitution.md
+
+**Purpose:** the project's vision, answered once and refined as you learn.
+Every story should trace back to it.
+
+**Path:** `intent/constitution.md`
+
+**Format:** Markdown with YAML front matter and exactly these five `##`
+sections, in this order:
+
+```markdown
+---
+name: Hello Todo
+idea: A todo list that only shows today's three most important tasks.
+---
+
+## Users
+Who it's for.
+
+## Problem
+What hurts today, in their words.
+
+## Switch
+What makes them switch now, and from what.
+
+## First
+The smallest first version that proves it.
+
+## Proof
+How you'll know it's working.
+```
+
+Further `##` sections may follow the five required ones. The
+idea-to-blueprint playbook writes `## Jobs to be done` and
+`## Founding hypothesis`; the validate playbook writes `## Validation`, one entry per round of
+outreach, and keeps its drafts in `intent/outreach/`. A draft is marked
+`Status: draft, not sent` until the founder signs it off; the founder sends it.
+`nikos validate` checks the front matter has `name` and `idea`, and that the
+five vision sections come first, in order, and aren't empty.
+
+---
+
+## storymap.yaml
+
+**Purpose:** the shape of the product: activities (columns), releases (rows)
+and the order stories should be built in. It is an index; the stories
+themselves live in feature files.
+
+**Path:** `intent/storymap.yaml`
+
+**Format:** YAML.
+
+```yaml
+format_version: 1
+project: hello-todo
+key: HT                     # story id prefix: HT-1, HT-2 …
+activities:
+  - id: tasks               # slug, matches the features/<activity>/ folder
+    title: Manage tasks
+releases:
+  - number: 1
+    title: MVP
+    stories: [HT-1, HT-2]   # build order within the release
+  - number: 2
+    title: Enhancements
+    stories: [HT-3]
+```
+
+Rules:
+
+- Every story id appears in exactly one release.
+- Every story id has exactly one feature file and one `state.yaml` entry.
+- Release numbers start at 1 and have no gaps.
+
+---
+
+## features/&lt;activity&gt;/&lt;story-slug&gt;.feature
+
+**Purpose:** one user story and its acceptance criteria, written so they
+run as tests.
+
+**Path:** `intent/features/<activity-id>/<story-slug>.feature`, where the
+activity id matches `storymap.yaml` and the slug is the story title in
+kebab-case.
+
+**Format:** Gherkin. One `Feature` per file. The description holds the user
+story; each acceptance criterion is a `Scenario` (or `Scenario Outline`)
+titled with its label. Full rules are in [gherkin.md](gherkin.md).
+
+```gherkin
+@HT-1 @release-1 @must @activity-tasks
+Feature: Add a task
+
+  As a busy person
+  I want to add a task in one step
+  So that capturing it is faster than forgetting it
+
+  @AC1 @must
+  Scenario: AC1 — Adding a task shows it at the top
+    Given my list is empty
+    When I add the task "Call the bank"
+    Then I see "Call the bank" at the top of my list
+```
+
+---
+
+## plans/&lt;story-id&gt;.v&lt;N&gt;.md
+
+**Purpose:** how a story will be built. Plans are versioned: a new approach
+is a new file, so history is never lost.
+
+**Path:** `intent/plans/<story-id>.v<N>.md`, for example
+`intent/plans/HT-1.v2.md`. `N` starts at 1 and increases by one.
+
+**Format:** Markdown with front matter, then one `##` section per step:
+
+```markdown
+---
+story: HT-1
+version: 2
+created: 2026-11-03
+supersedes: 1          # omit for v1
+summary: One to three plain sentences on the approach.
+---
+
+## 1. Store tasks locally
+**Why:** tasks survive a refresh.
+**Criteria:** AC1
+**Files:** src/store.ts
+
+Notes for the agent.
+```
+
+These fields match intentdocs plans one to one (see the mapping doc).
+
+Start a new version with `nikos plan new <story-id>`. It writes the next
+`v<N>` from a template, sets `supersedes`, and refuses to overwrite an
+existing file.
+
+---
+
+## decisions.md
+
+**Purpose:** why things are the way they are. Append-only; never rewrite an
+entry, add a new one that supersedes it.
+
+**Path:** `intent/decisions.md`
+
+**Format:** Markdown. One `##` entry per decision, newest last:
+
+```markdown
+## 2026-11-03 — Store tasks in localStorage (HT-1)
+**Category:** architecture
+**Supersedes:** none
+
+Why this, and what we rejected.
+```
+
+The heading is `date — title (story id)`; the story id is optional for
+project-wide decisions. Category is one of `product`, `architecture`,
+`design`, `process`.
+
+---
+
+## state.yaml
+
+**Purpose:** everything that changes as work happens: status, who's on it,
+blockers, and the run queue. Kept apart so specs stay clean.
+
+**Path:** `intent/state.yaml`
+
+**Format:** YAML.
+
+```yaml
+format_version: 1
+stories:
+  HT-1:
+    status: done            # todo | in_progress | needs_rework | done
+    claimed_by: claude-code # optional
+    plan_version: 2         # optional, the plan in use
+    blockers: []            # optional, plain sentences
+    updated: 2026-11-03
+  HT-2:
+    status: todo
+run:                        # optional, an ordered build queue
+  queue: [HT-2]
+```
+
+Status moves `todo → in_progress → done`, or `in_progress → needs_rework →
+in_progress`. Only a passing verification can set `done` (see the
+build-a-story playbook).
+
+---
+
+## outreach/&lt;date&gt;-&lt;channel&gt;.md (optional)
+
+**Purpose:** outreach drafted to test the idea with real people, kept so the
+founder can review it and the results can be traced back to it.
+
+**Path:** `intent/outreach/<yyyy-mm-dd>-<channel>.md`
+
+**Format:** Markdown. The first line is the status: `Status: draft, not sent`
+until the founder signs it off, then `Status: signed off <date>, for the
+person to send`. Then who it's for, the message, the questions to ask and,
+optionally, a demo or reel script. Written by the validate playbook; the
+founder sends it, never the agent.
+
+---
+
+## bets/&lt;bet-id&gt;.md (optional)
+
+**Purpose:** a time-boxed bet that a set of stories will move a measure.
+
+**Path:** `intent/bets/<bet-id>.md`, where `<bet-id>` is lowercase words
+joined by hyphens.
+
+**Format:** Markdown with YAML front matter, then free-form notes. Create one
+with `nikos bet new`; the bet playbook frames and closes it.
+
+```markdown
+---
+id: faster-reorder
+hypothesis: We believe drag to reorder will make people plan their day in the app because they reorder on paper today.
+key_result: Share of daily users who reorder at least once
+expected_uplift: from 10% to 30%
+time_box: 2026-12-01
+blockers: []
+stories: [HT-3]
+status: open
+---
+
+## Why we think so
+The evidence behind the hypothesis.
+
+## Outcome
+Filled in when the time box ends.
+```
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `id` | yes | Matches the file name |
+| `hypothesis` | yes | What you believe and why |
+| `key_result` | yes | The one measure that says whether it worked |
+| `expected_uplift` | yes | How far you expect it to move, from what to what |
+| `time_box` | yes | End date, `YYYY-MM-DD` |
+| `blockers` | yes | What stands in the way; `[]` if nothing |
+| `stories` | yes | At least one story id; each must be in `storymap.yaml` |
+| `status` | yes | `open \| won \| lost \| killed` |
+
+`nikos validate` checks every field against `schemas/bet.schema.json`, that
+the id matches the file name, and that every linked story exists.
+
+---
+
+## Versioning this format
+
+`format_version` in `storymap.yaml` and `state.yaml` is the version of this
+document. Breaking changes bump it; `nikos validate` reads it and explains
+any migration needed.

package/docs/gherkin.md

@@ -0,0 +1,81 @@
+# Writing stories as feature files
+
+Every story is one Gherkin `.feature` file in
+`intent/features/<activity>/<story-slug>.feature`. The file is both the spec
+and the test: each acceptance criterion is a scenario that Cucumber can run.
+`nikos validate` checks all the rules on this page.
+
+## The shape of a story
+
+```gherkin
+@HT-1 @release-1 @must @activity-tasks @effort-S
+Feature: Add a task
+
+  As a busy person
+  I want to add a task in one step
+  So that capturing it is faster than forgetting it
+
+  @AC1 @must
+  Scenario: AC1 — Adding a task shows it at the top
+    Given my list is empty
+    When I add the task "Call the bank"
+    Then I see "Call the bank" at the top of my list
+
+  @AC2 @should
+  Scenario: AC2 — Blank tasks are ignored
+    Given my list is empty
+    When I add the task ""
+    Then my list is still empty
+```
+
+## Rules
+
+**One story per file.** Exactly one `Feature`, and exactly one story id tag.
+
+**The user story goes in the Feature description.** Three lines under
+`Feature:`, starting `As a`, `I want` and `So that`.
+
+**Each acceptance criterion is a scenario.** Tag it `@AC1`, `@AC2` … and
+start its title with the same label (`AC1 — …`). Labels are unique within
+the file. A `Scenario Outline` counts as one criterion. Scenarios may sit
+inside a `Rule:` block.
+
+**Every scenario has a When and a Then.** `Given` is optional.
+
+**Priority is a tag.** Exactly one of `@must`, `@should` or `@could` on the
+Feature (the story's priority), and optionally one on each scenario (the
+criterion's priority).
+
+## Allowed Feature tags
+
+| Tag | Meaning | Required |
+|---|---|---|
+| `@HT-1` | story id, using the project key | yes |
+| `@release-N` | release the story is in | yes |
+| `@must` / `@should` / `@could` | story priority | yes |
+| `@activity-<id>` | activity, matching the folder name | no |
+| `@effort-XS` … `@effort-XL` | size estimate | no |
+
+Anything else is a warning, so you notice typos.
+
+## Never put status in a feature
+
+Tags like `@todo`, `@wip`, `@in-progress`, `@done`, `@blocked` or `@ready`
+are errors. Status, owners, blockers and dates live in `intent/state.yaml`,
+so a feature file only changes when the intent changes and its git history
+reads as a history of decisions about the product.
+
+## Keep it about behaviour, not implementation
+
+Write steps the way a user would describe what happens: "When I add the task
+'Call the bank'", not "When I POST to /api/tasks". Implementation detail
+belongs in the story's plan. `nikos clear` flags file paths, endpoints and
+framework names in feature text.
+
+## Checking your work
+
+```sh
+npx nikos validate
+```
+
+Errors block (exit code 1); warnings are shown but don't fail.

package/docs/install.md

@@ -0,0 +1,72 @@
+# Installing nikOS in your agent tool
+
+nikOS is one set of skills in `skills/`. Each tool reads its own small
+manifest, and every manifest points at that same folder, so no skill file is
+copied per tool.
+
+| Tool | Manifest | Install |
+| --- | --- | --- |
+| Claude Code | `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` | `/plugin install nikos --marketplace nikovijay/NikOS` |
+| Codex | `.codex-plugin/plugin.json`, `.agents/plugins/marketplace.json` | `codex plugin marketplace add nikovijay/NikOS` |
+| Cursor | `.cursor-plugin/plugin.json` | Add the repo as a marketplace (below) |
+
+After installing, ask the agent to plan, build or check a story. The
+`nikos-mode` skill picks the playbook.
+
+## Claude Code
+
+In a session:
+
+```
+/plugin install nikos --marketplace nikovijay/NikOS
+```
+
+That works in one step on Claude Code 2.1.275 or later. On older versions,
+add the marketplace first, then install:
+
+```
+/plugin marketplace add nikovijay/NikOS
+/plugin install nikos@nikos
+```
+
+From a terminal, the same commands are `claude plugin marketplace add
+nikovijay/NikOS` and `claude plugin install nikos@nikos`.
+
+## Codex
+
+```
+codex plugin marketplace add nikovijay/NikOS
+```
+
+Then install nikOS from the Plugins directory. Update it later with `codex
+plugin marketplace upgrade`.
+
+## Cursor
+
+Cursor installs plugins from a marketplace in its settings rather than a
+command. Add `https://github.com/nikovijay/NikOS` as a marketplace (Plugins,
+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 command-line tool
+
+The skills run the `nikos` command. When it isn't installed, they run it
+through `npx -y nikos`, so nothing has to be installed globally. To install
+it anyway: `npm install -g nikos`.
+
+## Formats checked
+
+Plugin formats change often. These were read on 2026-11-04 (no page showed a
+version):
+
+- Claude Code: https://code.claude.com/docs/en/plugins-reference and
+  https://code.claude.com/docs/en/plugins/marketplace-reference. Checked with
+  `claude plugin validate .` on Claude Code 2.1.318.
+- Cursor: https://cursor.com/docs/reference/plugins
+- Codex: https://developers.openai.com/plugins/build/plugins
+
+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
+the skills folder. `evals/install.md` records each install tried.