nikos 0.0.2 → 0.0.4

package/README.md

@@ -1,12 +1,17 @@
-```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>
+
+I'm [@nikovijay](https://x.com/nikovijay), a Product Director with 20 years
+of experience in software delivery. nikOS is my personal framework for
+building products with AI coding agents. I'm sharing it to help others get
+started with agentic programming practices. For where I think this is going,
+see my thoughts on
+[the software factory of the near future](https://www.nikovijay.com/software-factory).
+
+## What it does
 
 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,
@@ -15,6 +20,10 @@ 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.
 
+It works with Claude Code, Codex and Cursor, and brings spec-driven
+development, behaviour-driven development (BDD) with Gherkin and Cucumber,
+user story mapping and acceptance criteria to agentic coding.
+
 > Early work in progress. Open source, MIT licensed.
 
 ## Try it in 10 minutes
@@ -72,6 +81,7 @@ Every file is plain text you can read, review and diff. The full format:
 | --- | --- |
 | `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 |
@@ -83,20 +93,6 @@ Every file is plain text you can read, review and diff. The full format:
 | `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

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/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/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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nikos",
-  "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.",
+  "version": "0.0.4",
+  "description": "Spec-driven development for AI coding agents: story maps, Gherkin acceptance criteria and a done gate for Claude Code, Codex and Cursor",
   "license": "MIT",
   "author": "Niko Vijay",
   "homepage": "https://nikos.tools",
@@ -42,5 +42,19 @@
     "@cucumber/messages": "^26.0.1",
     "ajv": "^8.17.1",
     "yaml": "^2.6.1"
-  }
+  },
+  "keywords": [
+    "spec-driven-development",
+    "ai-coding-agents",
+    "agentic-coding",
+    "claude-code",
+    "codex",
+    "cursor",
+    "bdd",
+    "gherkin",
+    "cucumber",
+    "acceptance-criteria",
+    "user-story-mapping",
+    "agent-skills"
+  ]
 }

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.