nikos 0.0.1 → 0.0.2

package/README.md

@@ -8,13 +8,21 @@
   spec-driven development for AI coding agents
 ```
 
-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.
+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.
 
-> Early work in progress. Start with [the intent/ format](docs/format.md).
+> Early work in progress. Open source, MIT licensed.
 
-## Install
+## Try it in 10 minutes
+
+[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 +31,78 @@ 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 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/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/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.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",