nikos 0.0.0-stage → 0.0.1

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.

package/docs/intentdocs-mapping.md

@@ -0,0 +1,117 @@
+# Mapping intent/ to intentdocs
+
+`intentdocs push` and `intentdocs pull` translate between the local
+`intent/` folder and an intentdocs project. This table is the contract: every
+local field maps to an intentdocs field, or is marked **local-only**.
+Fields that exist only in intentdocs are listed at the end.
+
+## Project and vision
+
+| Local | intentdocs | Notes |
+|---|---|---|
+| `constitution.md` front matter `name` | project name | |
+| `constitution.md` front matter `idea` | project idea | |
+| `## Users` | vision `users` | |
+| `## Problem` | vision `problem` | |
+| `## Switch` | vision `switch` | |
+| `## First` | vision `first` | |
+| `## Proof` | vision `proof` | |
+| extra `##` sections (e.g. `## Validation`) | **local-only** | pushed as a project note in a later format version |
+| `storymap.yaml` `key` | project story key prefix | e.g. `HT` → `HT-1` |
+| `storymap.yaml` `project` | **local-only** | slug used for paths |
+| `storymap.yaml` `format_version` | **local-only** | |
+
+## Activities and releases
+
+| Local | intentdocs | Notes |
+|---|---|---|
+| `activities[].title` | story `activity` | intentdocs groups by activity name |
+| `activities[].id` | **local-only** | folder slug under `features/` |
+| `releases[].number` | release order | |
+| `releases[].title` | release label | |
+| `releases[].stories` order | build sequence within the release | |
+
+## Stories (feature files)
+
+| Local | intentdocs | Notes |
+|---|---|---|
+| story id tag, e.g. `@HT-1` | story `key` | |
+| `Feature:` title | story `title` | |
+| description `As a …` | `as_a` | |
+| description `I want …` | `i_want` | |
+| description `So that …` | `so_that` | |
+| `@must` / `@should` / `@could` on the Feature | story `priority` | |
+| `@release-N` | story `release` | must agree with `storymap.yaml` |
+| `@activity-<id>` | story `activity` | resolved to the activity title |
+| `@effort-XS` … `@effort-XL` (optional) | story `effort` | |
+| file path | **local-only** | |
+
+## Acceptance criteria (scenarios)
+
+| Local | intentdocs | Notes |
+|---|---|---|
+| `@AC<n>` tag and scenario title prefix | criterion `label` | |
+| scenario title after the label + its steps | criterion `text` | pushed as one Given/When/Then sentence |
+| `@must` / `@should` / `@could` on the Scenario | criterion `priority` | |
+| scenario pass/fail from `nikos verify` | criterion `last_result` | sent via report_criteria |
+| step definition file and test name | linked tests | sent via save_tests |
+
+## Plans
+
+| Local | intentdocs | Notes |
+|---|---|---|
+| file `plans/<id>.v<N>.md` | plan `version` N | |
+| front matter `summary` | plan `summary` | |
+| `## <n>. <title>` | step `title` | |
+| `**Why:**` | step `why` | |
+| `**Criteria:**` | step `criteria` | labels resolved to criterion ids |
+| `**Files:**` | step `files` | |
+| `**Tests:**` (optional) | step `tests` | |
+| `**Needs you:**` (optional) | step `needs_you.question` | |
+| body text | step `agent_notes` | |
+| front matter `risk` (optional) | plan `risk` | |
+| front matter `introduces` (optional) | plan `introduces` | new dependencies |
+| front matter `supersedes`, `created` | **local-only** | intentdocs keeps its own history |
+
+## Decisions
+
+| Local | intentdocs | Notes |
+|---|---|---|
+| entry heading title | decision `title` | |
+| entry body | decision `description` | |
+| `**Category:**` | decision `category` | |
+| entry date | decision created date | |
+| story id in heading | decision linked story | |
+| `**Supersedes:**` | **local-only** | intentdocs amends instead |
+
+## State
+
+Status isn't pushed: intentdocs sets it. New stories start as To do,
+existing ones keep theirs, and they move through build and acceptance in
+intentdocs. `intentdocs push` still sends the local status, and says how
+many it ignored.
+
+| Local | intentdocs | Notes |
+|---|---|---|
+| `status: todo` | **not pushed** | intentdocs sets status |
+| `status: in_progress` | **not pushed** | intentdocs sets status |
+| `status: needs_rework` | **not pushed** | intentdocs sets status |
+| `status: done` | **not pushed** | intentdocs sets status; its own done needs acceptance after build |
+| `blockers` | raised blockers | |
+| `plan_version` | current plan version | |
+| `claimed_by` | story claim | |
+| `run.queue` | build run story order | |
+| `updated` | **local-only** | |
+
+## Bets
+
+| Local | intentdocs | Notes |
+|---|---|---|
+| `outreach/*.md`, `## Validation` | **local-only** | intentdocs keeps the vision answers, not outreach drafts or results |
+| `bets/*.md` | **local-only** | intentdocs has no bet object yet |
+
+## intentdocs-only (not pulled into files)
+
+Comments, design references, plan approvals, story approval after build,
+founder to-dos, releases readiness checks, collaborators and workspace
+settings stay in intentdocs. `intentdocs pull` never writes them to the repo.