nikos 0.0.3 → 0.0.5

package/README.md

@@ -4,6 +4,15 @@
 
 <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,
 each criterion is a Cucumber scenario that runs as a test, and a story can't
@@ -11,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
@@ -80,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/package.json

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

@@ -31,9 +31,23 @@ Read the story's `.feature` file, `intent/constitution.md` and
 - **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.
+- **Responsible:** for each area below that the story touches, every item
+  in its row is covered by a scenario (or, where the row says so, stated in
+  the description). Any missing item fails Responsible: name the item and give
+  the scenario to add. A story that touches none of these areas passes and
+  says so.
+
+  | Area | The story must cover |
+  | --- | --- |
+  | Money | A scenario for invalid amounts (zero, negative, more decimals than the currency has); a scenario for how amounts round; the currency, in the description or a scenario |
+  | Personal data | Who can see it, in the description or a scenario; a scenario for deleting it |
+  | Safety (health, physical harm, locks, children) | A scenario for what happens when it fails, and what the user sees then |
+  | Outreach to real people | A scenario for consent or opting out; nothing is sent without the person's sign-off |
+  | A screen people use | A scenario or description line saying it works by keyboard and with a screen reader |
+
+  For example, a story that charges a card but has no scenario for a zero or
+  negative amount reports:
+  `Responsible: fail. Money: no scenario for invalid amounts. Fix: add "AC3 — A zero or negative amount is refused".`
 
 ## 3. Fill small gaps, ask about big ones
 

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

@@ -6,7 +6,7 @@ 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 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`.
+4. Run `nikos state set <story-id> in_progress --by <agent>`, where `<agent>` names your tool (`claude-code`, `codex`, `cursor`), never a person, so `state.yaml` shows who is building it.
 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>"`. Add `--category interface` for anything a later story must keep to: command syntax, output format, API shape.