nikos 0.0.2 → 0.0.3

package/README.md

@@ -1,12 +1,8 @@
-```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,
@@ -72,6 +68,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 |

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nikos",
-  "version": "0.0.2",
+  "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.