nikos 0.0.1 → 0.0.3

package/README.md

@@ -1,20 +1,24 @@
-```text
-           _   _        ___    ____
-   _ __   (_) | | __   / _ \  / ___|
-  | '_ \  | | | |/ /  | | | | \___ \
-  | | | | | | |   <   | |_| |  ___) |
-  |_| |_| |_| |_|\_\   \___/  |____/
+<p align="center">
+  <img src="https://raw.githubusercontent.com/nikovijay/NikOS/main/assets/header.svg" alt="nikOS" width="840">
+</p>
 
-  spec-driven development for AI coding agents
-```
+<p align="center"><b>Spec-driven development for AI coding agents</b></p>
+
+AI coding agents are quick to say "done". nikOS makes them prove it. Your
+story map, plans and acceptance criteria live in your repo as plain files,
+each criterion is a Cucumber scenario that runs as a test, and a story can't
+be marked done until its scenarios pass. Your agent follows a named playbook
+for each request instead of improvising, and every decision is written down
+where the next person (or agent) can find it.
 
-Your story map, plans and acceptance criteria live in your repo as plain
-files and executable Cucumber features, and the agent can't call a story done
-until its scenarios pass.
+> Early work in progress. Open source, MIT licensed.
 
-> Early work in progress. Start with [the intent/ format](docs/format.md).
+## Try it in 10 minutes
 
-## Install
+[docs/quickstart.md](docs/quickstart.md) takes an empty repo to one passing
+scenario, with every command and the output you should see.
+
+## Install in your agent tool
 
 | Tool | Command |
 | --- | --- |
@@ -23,11 +27,79 @@ until its scenarios pass.
 | Cursor | Add `https://github.com/nikovijay/NikOS` as a plugin marketplace |
 
 Then ask your agent to plan or build a story: the `nikos-mode` skill takes it
-from there. Details and the formats each tool expects: [docs/install.md](docs/install.md).
+from there. The skills run the `nikos` command through `npx`, so there's
+nothing else to install. More in [docs/install.md](docs/install.md).
+
+## The loop
+
+```bash
+npx -y nikos init                     # create intent/ with a starter story
+# write the story's scenarios in intent/features/
+npx -y nikos verify setup             # add a Cucumber runner for your stack
+npx -y nikos verify TC-1              # run the story: it fails until it's built
+# build it, then
+npx -y nikos state set TC-1 done      # refused unless its scenarios pass
+```
+
+With an agent, you only write the request ("add a story for X and build
+it"); the playbooks run these steps and stop at each point that needs you.
+
+## What lives in your repo
+
+```text
+intent/
+├── constitution.md      who it's for, the problem, what proves it works
+├── storymap.yaml        activities, releases, and the order to build stories in
+├── state.yaml           each story's status: todo, in_progress, needs_rework, done
+├── decisions.md         why things are the way they are, append-only
+├── features/            one .feature file per story; its scenarios are the criteria
+│   └── <activity>/<story>.feature
+├── plans/               how each story will be built, versioned: <story>.v<N>.md
+└── bets/                time-boxed bets and the stories that test them
+```
+
+Every file is plain text you can read, review and diff. The full format:
+[docs/format.md](docs/format.md). A worked example:
+[examples/hello-todo](examples/hello-todo/intent).
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `nikos init` | Create `intent/` in this repo |
+| `nikos validate` | Check `intent/` is well formed |
+| `nikos story add "<title>"` | Add a story to the map, state and a starter feature |
+| `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 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 |
+| `nikos next` | Print the next story to build |
+| `nikos show <id>` | Summarise a story: feature, status, plan, bets, decisions |
+| `nikos decide "<title>"` | Append a decision to `decisions.md` |
+| `nikos decisions "<q>"` | Quote the decisions about a topic or story |
+| `nikos bet new <id>` | Write a time-boxed bet card linked to its stories |
+
+## Working with a team: intentdocs
+
+When you want a visual story map, reviews and a team around the same specs,
+[intentdocs](https://www.intentdocs.com) reads the same `intent/` folder:
+
+```bash
+npx intentdocs push    # upload intent/ and link this repo
+npx intentdocs pull    # bring web edits back, shown as diffs first
+```
+
+The repo stays the source of truth for specs and plans; intentdocs runs the
+build and acceptance steps. What maps to what:
+[docs/intentdocs-mapping.md](docs/intentdocs-mapping.md).
+
+## Links
 
 - Home: https://nikos.tools
-- Format spec: [docs/format.md](docs/format.md)
-- Mapping to intentdocs: [docs/intentdocs-mapping.md](docs/intentdocs-mapping.md)
-- Worked example: [examples/hello-todo](examples/hello-todo/intent)
+- Quickstart: [docs/quickstart.md](docs/quickstart.md)
+- Install: [docs/install.md](docs/install.md)
+- Format: [docs/format.md](docs/format.md)
+- Writing stories as features: [docs/gherkin.md](docs/gherkin.md)
 
 MIT licensed.

package/dist/cli.js

@@ -10,6 +10,7 @@ import { runDecide } from "./commands/decide.js";
 import { runBet } from "./commands/bet.js";
 import { runShow } from "./commands/show.js";
 import { runDecisions } from "./commands/decisions.js";
+import { runStory } from "./commands/story.js";
 const commands = {
     init: runInit,
     validate: runValidate,
@@ -22,6 +23,7 @@ const commands = {
     bet: runBet,
     show: runShow,
     decisions: runDecisions,
+    story: runStory,
 };
 const help = `nikos — spec-driven development for AI coding agents
 
@@ -30,6 +32,8 @@ Usage: nikos <command> [options]
 Commands:
   init             Create intent/ in this repo (--name, --key)
   validate [dir]   Check the intent/ folder is well formed
+  story add "<title>"  Add a story to the map, state and a starter feature
+                   (--activity, --release, --priority)
   plan new <id>    Start the next version of a story's plan
   clear <id>       Check a story is Lean and Executable before building
   verify setup     Set up a Cucumber runner for this repo's stack

package/dist/commands/decide.js

@@ -2,7 +2,7 @@ import { appendFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { STORY_ID, findIntentDir, read } from "../lib/project.js";
 import { formatResult, validate } from "./validate.js";
-const CATEGORIES = ["product", "architecture", "design", "process"];
+const CATEGORIES = ["product", "architecture", "design", "interface", "process"];
 /** Append a dated entry to decisions.md. Earlier entries are never touched. */
 export function decide(input, dir) {
     const title = input.title.trim();
@@ -39,7 +39,7 @@ export function runDecide(args) {
         return i >= 0 ? rest[i + 1] : undefined;
     };
     if (!title || title.startsWith("--")) {
-        console.error('Usage: nikos decide "<title>" --why "<why>" [--story <id>] [--category product|architecture|design|process] [--supersedes "<title>"]');
+        console.error('Usage: nikos decide "<title>" --why "<why>" [--story <id>] [--category product|architecture|design|interface|process] [--supersedes "<title>"]');
         return 1;
     }
     const dir = opt("dir") ?? process.cwd();

package/dist/commands/story.js

@@ -0,0 +1,87 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseDocument, YAMLSeq } from "yaml";
+import { findIntentDir, read } from "../lib/project.js";
+import { slugify } from "./init.js";
+import { validate } from "./validate.js";
+const PRIORITIES = ["must", "should", "could"];
+const yamlOpts = { lineWidth: 0, flowCollectionPadding: false };
+/** Add a story to storymap.yaml and state.yaml, and write its starter feature file. */
+export function newStory(input, dir) {
+    const title = input.title?.trim();
+    if (!title)
+        throw new Error("A story needs a title");
+    const priority = input.priority ?? "must";
+    if (!PRIORITIES.includes(priority))
+        throw new Error(`'${priority}' is not a priority (must, should, could)`);
+    const intentDir = findIntentDir(dir);
+    const mapPath = join(intentDir, "storymap.yaml");
+    const statePath = join(intentDir, "state.yaml");
+    // Documents keep comments and the order of everything we don't touch.
+    const map = parseDocument(read(mapPath));
+    const state = parseDocument(read(statePath));
+    const plain = map.toJS();
+    const activities = (plain.activities ?? []).map((a) => a?.id);
+    if (!activities.includes(input.activity)) {
+        throw new Error(`'${input.activity}' is not an activity in storymap.yaml. Activities: ${activities.join(", ") || "none"}`);
+    }
+    const releases = plain.releases ?? [];
+    if (!releases.length)
+        throw new Error("storymap.yaml has no releases to add the story to");
+    const index = input.release === undefined ? releases.length - 1 : releases.findIndex((r) => r?.number === input.release);
+    if (index < 0)
+        throw new Error(`There is no release ${input.release}. Releases: ${releases.map((r) => r?.number).join(", ")}`);
+    const release = releases[index].number;
+    const key = plain.key;
+    const taken = releases.flatMap((r) => r?.stories ?? []).map((s) => Number(s.slice(key.length + 1)) || 0);
+    const id = `${key}-${Math.max(0, ...taken) + 1}`;
+    const feature = join(intentDir, "features", input.activity, `${slugify(title)}.feature`);
+    if (existsSync(feature))
+        throw new Error(`${feature} already exists; give the story a different title`);
+    const stories = map.getIn(["releases", index, "stories"], true);
+    if (stories instanceof YAMLSeq)
+        stories.add(id);
+    else
+        map.setIn(["releases", index, "stories"], map.createNode([id], { flow: true }));
+    state.setIn(["stories", id], state.createNode({ status: "todo" }));
+    const text = `@${id} @release-${release} @${priority} @activity-${input.activity}
+Feature: ${title}
+
+  As a <who it's for>
+  I want <what they can do>
+  So that <why it matters to them>
+
+  @AC1 @${priority}
+  Scenario: AC1 — <the first acceptance criterion>
+    Given <the starting situation>
+    When <the one action>
+    Then <what they see>
+`;
+    mkdirSync(dirname(feature), { recursive: true });
+    writeFileSync(feature, text, { flag: "wx" });
+    writeFileSync(mapPath, map.toString(yamlOpts));
+    writeFileSync(statePath, state.toString(yamlOpts));
+    return { id, release, feature, validation: validate(intentDir) };
+}
+export function runStory(args) {
+    const [sub, title, ...rest] = args;
+    const opt = (n) => {
+        const i = rest.indexOf(`--${n}`);
+        return i >= 0 ? rest[i + 1] : undefined;
+    };
+    if (sub !== "add" || !title || title.startsWith("--") || !opt("activity")) {
+        console.error('Usage: nikos story add "<title>" --activity <id> [--release <n>] [--priority must|should|could]');
+        return 1;
+    }
+    try {
+        const release = opt("release");
+        const r = newStory({ title, activity: opt("activity"), release: release === undefined ? undefined : Number(release), priority: opt("priority") }, opt("dir") ?? process.cwd());
+        console.log(`Added ${r.id} to release ${r.release}\nCreated ${r.feature}`);
+        console.log(`\nNext: write the user story and its scenarios in the feature file, then run nikos clear ${r.id}.`);
+        return 0;
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        return 1;
+    }
+}

package/dist/commands/verify.js

@@ -1,4 +1,4 @@
-import { copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
@@ -12,6 +12,8 @@ const INSTALL = {
     ts: "npm install --save-dev @cucumber/cucumber@^12 tsx",
     python: "pip install behave",
 };
+/** A step only the untouched example story has. */
+const EXAMPLE_STEP = "When I do the one thing this product is for";
 const CONFIG = { js: "cucumber.mjs", ts: "cucumber.mjs", python: "behave.ini" };
 function stackOrThrow(root) {
     const stack = detectStack(root);
@@ -25,8 +27,10 @@ export function setupVerify(root) {
     const src = join(templateDir, stack === "python" ? "python" : stack);
     const created = [];
     const skipped = [];
-    // Step stubs are for the example story `nikos init` creates; skip them once it's gone.
-    const hasExample = existsSync(join(root, "intent/features/getting-started/first-story.feature"));
+    // Step stubs are for the example story `nikos init` creates; skip them once
+    // it's gone or rewritten into a real story, whose steps they wouldn't match.
+    const example = join(root, "intent/features/getting-started/first-story.feature");
+    const hasExample = existsSync(example) && readFileSync(example, "utf8").includes(EXAMPLE_STEP);
     for (const file of walk(src)) {
         const rel = relative(src, file);
         if (!hasExample && /first[-_]story/.test(rel))

package/docs/format.md

@@ -109,6 +109,10 @@ Rules:
 - Every story id has exactly one feature file and one `state.yaml` entry.
 - Release numbers start at 1 and have no gaps.
 
+Add a story with `nikos story add "<title>" --activity <id>`. It takes the
+next free id, adds it to the last release (or `--release <n>`), gives it a
+`todo` entry in `state.yaml` and writes a starter feature file to fill in.
+
 ---
 
 ## features/&lt;activity&gt;/&lt;story-slug&gt;.feature
@@ -195,7 +199,9 @@ 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`.
+`design`, `interface`, `process`. Use `interface` for a choice other stories
+must keep to: a command's syntax, an output format, an API's shape. The
+build-a-story playbook reads these before planning.
 
 ---
 

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,6 @@
 {
   "name": "nikos",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "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",

package/skills/clear/SKILL.md

@@ -35,7 +35,22 @@ Read the story's `.feature` file, `intent/constitution.md` and
   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
+## 3. Fill small gaps, ask about big ones
+
+Every spec leaves some rules unstated. Sort each gap you find:
+
+- **Decide it** when it's a small rule any reasonable person would accept
+  and it's cheap to change later: how a tip rounds, the order a list sorts
+  in, the wording of a message. Pick the obvious choice, record it with
+  `nikos decide "<the rule>" --story <story-id> --why "<why this choice>"`,
+  and list it in the report. Recorded, it doesn't fail Clear.
+- **Stop and ask** when the gap affects users' money, personal data, access
+  (who can see or change what), safety, or messages to real people. These are
+  product decisions, not yours. Clear fails until the person answers; record
+  their answer with `nikos decide`.
+- **If you're not sure which it is, ask.**
+
+## 4. Report all five, in this order
 
 One line per check, every time, even when it passes:
 
@@ -47,9 +62,11 @@ Accurate: pass. <why>
 Responsible: pass. <why>
 ```
 
-Every fail names what's missing and the fix.
+Every fail names what's missing and the fix. After the five lines, list
+any rules you decided (`Decided: <rule>`) and any questions that block
+building (`Ask: <question>`).
 
-## 4. Stop on a fail
+## 5. 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/decisions/SKILL.md

@@ -38,7 +38,7 @@ 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>
+nikos decide "<title>" --why "<why>" --category <product|architecture|design|interface|process>
 ```
 
 Log it only once the person tells you the reason. Don't write a reason for

package/skills/nikos-mode/playbooks/build-a-story.md

@@ -5,10 +5,10 @@ scenarios pass, not that you say so.
 
 1. Run `nikos next` to pick the story, or use the story id the person named.
 2. Check the story with the clear skill, and stop if any of the five checks fails.
-3. Run `nikos plan new <story-id>` and write the approach into the plan file it creates.
+3. Run `nikos decisions interface`, then `nikos plan new <story-id>` and write the approach into the plan file it creates. Reuse every interface decision the story touches, and cite each in the step that uses it as `Reuses: <decision title> (intent/decisions.md:<lines>)`. If the story needs to change one, stop and ask.
 4. Run `nikos state set <story-id> in_progress`.
 5. Implement the story, with a step definition for each step in its scenarios (see the verify skill).
 6. Run `nikos verify <story-id>`, then `nikos verify` to check every other story still passes, and keep the output.
-7. Record each decision you made with `nikos decide "<title>" --story <story-id> --why "<why>"`.
+7. Record each decision you made with `nikos decide "<title>" --story <story-id> --why "<why>"`. Add `--category interface` for anything a later story must keep to: command syntax, output format, API shape.
 8. Run `nikos state set <story-id> done`. If it refuses, fix the failing scenarios and go back to step 6.
 9. Report every step with its evidence or its skip reason.

package/templates/intent/decisions.md

@@ -5,7 +5,7 @@ one that supersedes it.
 
 <!--
 ## YYYY-MM-DD — Decision title (STORY-ID)
-**Category:** product | architecture | design | process
+**Category:** product | architecture | design | interface | process
 **Supersedes:** none
 
 Why this, and what we rejected.