nikos 0.0.0-stage → 0.0.2

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.

package/docs/quickstart.md

@@ -0,0 +1,153 @@
+# Quickstart: your first passing scenario in 10 minutes
+
+You'll make a tiny tip calculator in an empty repo and finish with one story
+whose acceptance criterion runs as a test and passes. You need Node 20 or
+later and npm. Nothing is installed globally: every `nikos` command runs
+through `npx`.
+
+## 1. Make a repo (1 minute)
+
+```bash
+mkdir tip-calculator && cd tip-calculator
+git init
+npm init -y
+npm pkg set type=module
+```
+
+## 2. Create the intent/ folder (1 minute)
+
+```bash
+npx -y nikos init --name "Tip Calculator" --key TC
+```
+
+You should see:
+
+```text
+Created intent/ (6 files)
+✓ intent/ is valid — 1 story, 1 release
+
+Next: fill in intent/constitution.md, then write your first story in intent/features/.
+```
+
+`intent/` now holds your story map, a state file, a decision log and one
+starter story, TC-1. [docs/format.md](format.md) explains each file.
+
+## 3. Write the story (2 minutes)
+
+Replace the starter story with a real one. Save this as
+**`intent/features/getting-started/first-story.feature`**:
+
+```gherkin
+@TC-1 @release-1 @must @activity-getting-started
+Feature: Add a tip to the bill
+
+  As a diner
+  I want to add a tip to my bill
+  So that I know what to pay
+
+  @AC1 @must
+  Scenario: AC1 — A 20% tip on a 50 bill
+    Given a bill of 50
+    When I add a 20% tip
+    Then the total is 60.00
+```
+
+The scenario is the acceptance criterion: TC-1 isn't done until it passes.
+Check the folder is still well formed, and start the story:
+
+```bash
+npx -y nikos validate
+npx -y nikos state set TC-1 in_progress
+```
+
+```text
+✓ intent/ is valid — 1 story, 1 release
+TC-1: todo → in_progress
+```
+
+## 4. Set up the runner (2 minutes)
+
+```bash
+npx -y nikos verify setup
+npm install --save-dev @cucumber/cucumber@^12
+```
+
+`verify setup` notices this is a JavaScript repo and adds `cucumber.mjs`,
+which runs every story in `intent/` as a test. Now run TC-1:
+
+```bash
+npx -y nikos verify TC-1
+```
+
+It fails, and says why: none of the three steps has any code behind it yet.
+
+```text
+1 scenario (1 undefined)
+3 steps (3 undefined)
+```
+
+## 5. Make it pass (3 minutes)
+
+Write the code. Save this as **`tip.js`**:
+
+```js
+export function totalWithTip(bill, percent) {
+  return (bill * (1 + percent / 100)).toFixed(2);
+}
+```
+
+Connect each step to the code. Save this as **`test/steps/tip.steps.mjs`**:
+
+```js
+import { Given, When, Then } from "@cucumber/cucumber";
+import assert from "node:assert/strict";
+import { totalWithTip } from "../../tip.js";
+
+Given("a bill of {int}", function (bill) {
+  this.bill = bill;
+});
+
+When("I add a {int}% tip", function (percent) {
+  this.total = totalWithTip(this.bill, percent);
+});
+
+Then("the total is {float}", function (expected) {
+  assert.equal(this.total, expected.toFixed(2));
+});
+```
+
+Run it again:
+
+```bash
+npx -y nikos verify TC-1
+```
+
+```text
+1 scenario (1 passed)
+3 steps (3 passed)
+```
+
+## 6. Call it done (1 minute)
+
+```bash
+npx -y nikos state set TC-1 done
+```
+
+```text
+TC-1: in_progress → done
+```
+
+`state set … done` runs the scenarios first and refuses if any fail, so a
+story can't be marked done on the agent's word alone.
+
+That's the whole loop: write the story, run it, make it pass, mark it done.
+
+## Next: let your agent do it
+
+Install nikOS in your agent tool ([docs/install.md](install.md)), then ask:
+
+> Add a story for splitting the bill between people, and build it.
+
+The `nikos-mode` skill picks the right playbook: it writes the story,
+checks it, plans it, builds it, and stops at "done" only when the new
+scenario passes.

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "nikos",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "nikOS \u2014 an open-source agent skill stack for spec-driven development. Specs, plans and Cucumber features live in your repo.",
+  "license": "MIT",
+  "author": "Niko Vijay",
+  "homepage": "https://nikos.tools",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nikovijay/NikOS.git"
+  },
+  "type": "module",
+  "bin": {
+    "nikos": "dist/cli.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "templates",
+    "skills",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build && npm test",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test:ci": "vitest run --reporter=default --reporter=junit --outputFile.junit=reports/junit.xml"
+  },
+  "devDependencies": {
+    "@cucumber/cucumber": "^12.9.0",
+    "@types/node": "^22.20.5",
+    "tsx": "^4.23.15",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.9"
+  },
+  "dependencies": {
+    "@cucumber/gherkin": "^30.0.4",
+    "@cucumber/messages": "^26.0.1",
+    "ajv": "^8.17.1",
+    "yaml": "^2.6.1"
+  }
+}

package/schemas/bet.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nikos.tools/schemas/bet.schema.json",
+  "title": "nikOS bet card front matter",
+  "type": "object",
+  "required": ["id", "hypothesis", "key_result", "expected_uplift", "time_box", "blockers", "stories", "status"],
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
+    "hypothesis": { "type": "string", "minLength": 1 },
+    "key_result": { "type": "string", "minLength": 1 },
+    "expected_uplift": { "type": "string", "minLength": 1 },
+    "time_box": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    "blockers": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "stories": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9]{0,9}-[0-9]+$" }
+    },
+    "status": { "enum": ["open", "won", "lost", "killed"] }
+  }
+}

package/schemas/state.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nikos.tools/schemas/state.schema.json",
+  "title": "nikOS state",
+  "type": "object",
+  "required": ["format_version", "stories"],
+  "additionalProperties": false,
+  "properties": {
+    "format_version": { "const": 1 },
+    "stories": {
+      "type": "object",
+      "propertyNames": { "pattern": "^[A-Z][A-Z0-9]{0,9}-[0-9]+$" },
+      "additionalProperties": {
+        "type": "object",
+        "required": ["status"],
+        "additionalProperties": false,
+        "properties": {
+          "status": { "enum": ["todo", "in_progress", "needs_rework", "done"] },
+          "claimed_by": { "type": "string" },
+          "plan_version": { "type": "integer", "minimum": 1 },
+          "blockers": { "type": "array", "items": { "type": "string" } },
+          "updated": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }
+        }
+      }
+    },
+    "run": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "queue": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/schemas/storymap.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nikos.tools/schemas/storymap.schema.json",
+  "title": "nikOS story map",
+  "type": "object",
+  "required": ["format_version", "project", "key", "activities", "releases"],
+  "additionalProperties": false,
+  "properties": {
+    "format_version": { "const": 1 },
+    "project": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "key": { "type": "string", "pattern": "^[A-Z][A-Z0-9]{0,9}$" },
+    "activities": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "title"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+          "title": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "releases": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["number", "title", "stories"],
+        "additionalProperties": false,
+        "properties": {
+          "number": { "type": "integer", "minimum": 1 },
+          "title": { "type": "string", "minLength": 1 },
+          "stories": {
+            "type": "array",
+            "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9]{0,9}-[0-9]+$" }
+          }
+        }
+      }
+    }
+  }
+}

package/skills/clear/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: clear
+description: Check a story is Clear, Lean, Executable, Accurate and Responsible before anyone plans or builds it. Use before building any story, or when asked to review or check a spec.
+---
+
+# clear
+
+A story must pass all five checks before it's built. Bad specs caught here
+never become bad code.
+
+## 1. Run the mechanical checks
+
+Run `nikos clear <story-id>` in the repo. It finds the story's `.feature` file
+and decides **Lean** and **Executable**, which a script can check better than
+a person. Use its result for those two checks; don't overrule it.
+
+If the command isn't available, check them by hand:
+
+- **Executable:** the feature has at least one Scenario, and every Scenario
+  has a When step and a Then step.
+- **Lean:** the feature names no file paths, SQL, frameworks, databases or
+  storage mechanisms.
+
+## 2. Judge the other three
+
+Read the story's `.feature` file, `intent/constitution.md` and
+`intent/decisions.md`.
+
+- **Clear:** every sentence has one reading. Two people would build the same
+  thing from it. Vague words ("fast", "easy", "some", "etc.") fail.
+- **Accurate:** it agrees with the constitution (who it's for, the problem,
+  the proof) and with every decision in `decisions.md`. Name the line it
+  contradicts.
+- **Responsible:** where the story touches personal data, money, safety,
+  outreach to real people or accessibility, a scenario or the description
+  covers it. A story that touches none of these passes and says so.
+
+## 3. Report all five, in this order
+
+One line per check, every time, even when it passes:
+
+```
+Clear: pass. <why>
+Lean: pass. <why>
+Executable: fail. <what's missing>. Fix: <the change to make>
+Accurate: pass. <why>
+Responsible: pass. <why>
+```
+
+Every fail names what's missing and the fix.
+
+## 4. Stop on a fail
+
+If any check fails, don't plan or build the story. Report the failures and
+the fixes, and wait for the spec to change.

package/skills/clear-review/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: clear-review
+description: Get a sceptical second review of a story's spec before building it, from another model or a fresh agent when one is available. Use when a spec is about to be built and the person wants it challenged, or when CLEAR passed but something feels off.
+---
+
+# clear-review
+
+One reviewer misses things. A second one, with no stake in the spec, finds
+more.
+
+## 1. Run CLEAR first
+
+Check the story with the clear skill. If a check fails, stop and report it.
+There's no point reviewing a spec that already fails.
+
+## 2. Ask a second reviewer to attack it
+
+If you can hand work to another model or a fresh agent with no memory of this
+conversation, give it only:
+
+- the story's `.feature` file,
+- `intent/constitution.md`,
+- the entries from `nikos decisions "<story-id>"`,
+
+and this brief: "You are a sceptical reviewer. Find what's ambiguous,
+missing, contradictory, untestable or risky in this spec. For each problem,
+quote the line and say what could go wrong. Don't suggest code."
+
+Don't share your own CLEAR results or opinion with it, so its read isn't
+anchored on yours.
+
+If you can't hand work off, do the review yourself as a separate pass: reread
+the feature as that sceptical reviewer, line by line, and say in the report
+that it was a single-model review.
+
+## 3. Merge into one list
+
+Combine your CLEAR results and the reviewer's findings into one list. Drop
+duplicates, and say who raised each finding. For each one, say whether it
+blocks building (the spec is wrong or untestable) or is a note.
+
+## 4. Stop for the person
+
+Show the list. Change the spec only once the person agrees to each change.
+A finding is a question for them, not a fix for you.

package/skills/decisions/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: decisions
+description: Show why something was decided by quoting the decision log, or say plainly that no decision is recorded. Use when someone asks why a choice was made, what was rejected, or whether something was ever decided.
+---
+
+# decisions
+
+The reason for a choice is whatever `intent/decisions.md` says. Never invent
+one.
+
+## 1. Search the log
+
+```
+nikos decisions "<the question or topic>"
+```
+
+It quotes every entry that mentions the topic, best match first, each with
+its `intent/decisions.md:<first>-<last>` line range. A story id (e.g. HT-1)
+finds the entries tagged with it.
+
+If nothing matches, try again with the words the spec would use: the name
+of the feature, the library or the setting, and other spellings (colour and
+color).
+
+## 2. Answer from the entries
+
+Quote the lines that answer the question, cite them as
+`intent/decisions.md:<lines>`, and give the date and story id. If an entry
+says it supersedes another, quote both and say which one stands.
+
+Only cite an entry that actually answers the question. A match on a shared
+word isn't an answer.
+
+## 3. When nothing is recorded
+
+Say: "No decision about <topic> is recorded in intent/decisions.md." You may
+add what the git history of `intent/` shows (`git log -p -- intent/`), marked
+clearly as history, not a recorded decision. Then offer to log one:
+
+```
+nikos decide "<title>" --why "<why>" --category <product|architecture|design|process>
+```
+
+Log it only once the person tells you the reason. Don't write a reason for
+them.

package/skills/intent/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: intent
+description: Explain what a story is meant to do and where it stands, from the repo's specs. Use when someone asks what a story is for, what it covers, or what state it's in, by its id (e.g. HT-2) or by topic.
+---
+
+# intent
+
+Say what the spec says, not what the code happens to do.
+
+## 1. Find the story
+
+If you have a story id, use it. If you only have a topic, search the
+`Feature:` lines under `intent/features/` and pick the story that matches.
+If more than one could match, list them and ask which one.
+
+## 2. Read everything recorded about it
+
+```
+nikos show <story-id>
+```
+
+It prints the feature (user story and scenarios), its status from
+`intent/state.yaml`, its release, the latest plan, any bets it's linked to,
+and decisions tagged with its id. Open the feature file and the plan it
+names when you need more than the summary.
+
+## 3. Answer in plain words
+
+Say, in a few sentences:
+
+- who it's for and what they get (the "As a / I want / So that" lines),
+- what has to be true for it to be done (each scenario, by its AC label),
+- where it stands: status, who has it (`claimed_by`), blockers, and the latest
+  plan. A story in the run queue but unclaimed is waiting, not being worked
+  on.
+
+Cite each claim as `path:line`, including the bet and plan files `nikos show`
+names. If the spec doesn't say something, say so.
+Don't fill the gap from the code or from guesswork.

package/skills/nikos-mode/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: nikos-mode
+description: Entry point for nikOS spec-driven work. Use at the start of any request in a repo with an intent/ folder, or when asked to plan, build, change, check or explain a story. Picks the matching playbook and runs every step of it.
+---
+
+# nikos-mode
+
+You follow a named playbook for every request instead of improvising. Run
+these five steps in order, every time.
+
+The playbooks run the `nikos` command. When it isn't installed (`nikos
+--version` fails), run it as `npx -y nikos` instead: `npx -y nikos validate`
+for `nikos validate`, and so on.
+
+## 1. Read the principles
+
+Read `principles/index.md` next to this file. Keep each principle in mind for
+the rest of the request. When one applies, say which.
+
+## 2. Pick a playbook and say which
+
+Read `playbooks/index.md`. Match the request against the "Use when" column and
+pick exactly one playbook. Then tell the person, before doing anything else:
+
+> Playbook: **<name>** (`playbooks/<file>`), because <one-line reason>.
+
+If two rows match, pick the first and say which other one you passed over. If
+nothing matches, say "No playbook matches", then use `change` when the request
+edits files in the repo and `answer` when it doesn't.
+
+## 3. Copy every step into the task list
+
+Open the chosen playbook file. Copy each numbered step into your task list,
+word for word and in order, one item per step.
+
+- If your tool has a built-in task or todo list, use it.
+- If it has none, write the list in your reply as a Markdown checklist
+  (`- [ ] 1. …`) and repeat it, updated, whenever a step changes state.
+
+Don't merge, reword, reorder or summarise steps. Don't add steps of your own
+to the playbook's list; put extra work under the step it belongs to.
+
+## 4. Never drop a step
+
+Every step ends as done or skipped. A step you don't do stays on the list,
+marked skipped, with the reason:
+
+> ~~5. Run the story's scenarios~~ skipped: the repo has no Cucumber runner yet.
+
+"Not needed" is not a reason. Say what makes it not needed.
+
+## 5. Show evidence before you say done
+
+Finish with a report that lists every step with its outcome:
+
+- **done**, with the evidence: the command you ran and its result, the file
+  and line you changed, or the passage you quoted.
+- **skipped**, with the reason from step 4.
+
+Never call the request done, fixed or passing without that evidence. If a
+check fails, say so and show the output.

package/skills/nikos-mode/playbooks/answer.md

@@ -0,0 +1,9 @@
+# answer
+
+Answer a question from what the repo's specs actually say.
+
+1. Restate the question in one sentence.
+2. Find the files in `intent/` that answer it: constitution, story map, features, plans or decisions.
+3. Answer in plain words, citing each claim as `path:line`.
+4. If the specs don't answer it, say so and name the file where the answer belongs.
+5. Report every step with its evidence or its skip reason.