nikos 0.0.0-stage → 0.0.1

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "nikos",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "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",
+  "homepage": "https://nikos.tools",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nikovijay/NikOS.git"
+  },
+  "type": "module",
+  "bin": {
+    "nikos": "dist/cli.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "templates",
+    "skills",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build && npm test",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test:ci": "vitest run --reporter=default --reporter=junit --outputFile.junit=reports/junit.xml"
+  },
+  "devDependencies": {
+    "@cucumber/cucumber": "^12.9.0",
+    "@types/node": "^22.20.5",
+    "tsx": "^4.23.15",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.9"
+  },
+  "dependencies": {
+    "@cucumber/gherkin": "^30.0.4",
+    "@cucumber/messages": "^26.0.1",
+    "ajv": "^8.17.1",
+    "yaml": "^2.6.1"
+  }
+}

package/schemas/bet.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nikos.tools/schemas/bet.schema.json",
+  "title": "nikOS bet card front matter",
+  "type": "object",
+  "required": ["id", "hypothesis", "key_result", "expected_uplift", "time_box", "blockers", "stories", "status"],
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
+    "hypothesis": { "type": "string", "minLength": 1 },
+    "key_result": { "type": "string", "minLength": 1 },
+    "expected_uplift": { "type": "string", "minLength": 1 },
+    "time_box": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    "blockers": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "stories": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9]{0,9}-[0-9]+$" }
+    },
+    "status": { "enum": ["open", "won", "lost", "killed"] }
+  }
+}

package/schemas/state.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nikos.tools/schemas/state.schema.json",
+  "title": "nikOS state",
+  "type": "object",
+  "required": ["format_version", "stories"],
+  "additionalProperties": false,
+  "properties": {
+    "format_version": { "const": 1 },
+    "stories": {
+      "type": "object",
+      "propertyNames": { "pattern": "^[A-Z][A-Z0-9]{0,9}-[0-9]+$" },
+      "additionalProperties": {
+        "type": "object",
+        "required": ["status"],
+        "additionalProperties": false,
+        "properties": {
+          "status": { "enum": ["todo", "in_progress", "needs_rework", "done"] },
+          "claimed_by": { "type": "string" },
+          "plan_version": { "type": "integer", "minimum": 1 },
+          "blockers": { "type": "array", "items": { "type": "string" } },
+          "updated": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }
+        }
+      }
+    },
+    "run": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "queue": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/schemas/storymap.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nikos.tools/schemas/storymap.schema.json",
+  "title": "nikOS story map",
+  "type": "object",
+  "required": ["format_version", "project", "key", "activities", "releases"],
+  "additionalProperties": false,
+  "properties": {
+    "format_version": { "const": 1 },
+    "project": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "key": { "type": "string", "pattern": "^[A-Z][A-Z0-9]{0,9}$" },
+    "activities": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "title"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+          "title": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "releases": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["number", "title", "stories"],
+        "additionalProperties": false,
+        "properties": {
+          "number": { "type": "integer", "minimum": 1 },
+          "title": { "type": "string", "minLength": 1 },
+          "stories": {
+            "type": "array",
+            "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9]{0,9}-[0-9]+$" }
+          }
+        }
+      }
+    }
+  }
+}

package/skills/clear/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: clear
+description: Check a story is Clear, Lean, Executable, Accurate and Responsible before anyone plans or builds it. Use before building any story, or when asked to review or check a spec.
+---
+
+# clear
+
+A story must pass all five checks before it's built. Bad specs caught here
+never become bad code.
+
+## 1. Run the mechanical checks
+
+Run `nikos clear <story-id>` in the repo. It finds the story's `.feature` file
+and decides **Lean** and **Executable**, which a script can check better than
+a person. Use its result for those two checks; don't overrule it.
+
+If the command isn't available, check them by hand:
+
+- **Executable:** the feature has at least one Scenario, and every Scenario
+  has a When step and a Then step.
+- **Lean:** the feature names no file paths, SQL, frameworks, databases or
+  storage mechanisms.
+
+## 2. Judge the other three
+
+Read the story's `.feature` file, `intent/constitution.md` and
+`intent/decisions.md`.
+
+- **Clear:** every sentence has one reading. Two people would build the same
+  thing from it. Vague words ("fast", "easy", "some", "etc.") fail.
+- **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.
+
+## 3. Report all five, in this order
+
+One line per check, every time, even when it passes:
+
+```
+Clear: pass. <why>
+Lean: pass. <why>
+Executable: fail. <what's missing>. Fix: <the change to make>
+Accurate: pass. <why>
+Responsible: pass. <why>
+```
+
+Every fail names what's missing and the fix.
+
+## 4. 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/clear-review/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: clear-review
+description: Get a sceptical second review of a story's spec before building it, from another model or a fresh agent when one is available. Use when a spec is about to be built and the person wants it challenged, or when CLEAR passed but something feels off.
+---
+
+# clear-review
+
+One reviewer misses things. A second one, with no stake in the spec, finds
+more.
+
+## 1. Run CLEAR first
+
+Check the story with the clear skill. If a check fails, stop and report it.
+There's no point reviewing a spec that already fails.
+
+## 2. Ask a second reviewer to attack it
+
+If you can hand work to another model or a fresh agent with no memory of this
+conversation, give it only:
+
+- the story's `.feature` file,
+- `intent/constitution.md`,
+- the entries from `nikos decisions "<story-id>"`,
+
+and this brief: "You are a sceptical reviewer. Find what's ambiguous,
+missing, contradictory, untestable or risky in this spec. For each problem,
+quote the line and say what could go wrong. Don't suggest code."
+
+Don't share your own CLEAR results or opinion with it, so its read isn't
+anchored on yours.
+
+If you can't hand work off, do the review yourself as a separate pass: reread
+the feature as that sceptical reviewer, line by line, and say in the report
+that it was a single-model review.
+
+## 3. Merge into one list
+
+Combine your CLEAR results and the reviewer's findings into one list. Drop
+duplicates, and say who raised each finding. For each one, say whether it
+blocks building (the spec is wrong or untestable) or is a note.
+
+## 4. Stop for the person
+
+Show the list. Change the spec only once the person agrees to each change.
+A finding is a question for them, not a fix for you.

package/skills/decisions/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: decisions
+description: Show why something was decided by quoting the decision log, or say plainly that no decision is recorded. Use when someone asks why a choice was made, what was rejected, or whether something was ever decided.
+---
+
+# decisions
+
+The reason for a choice is whatever `intent/decisions.md` says. Never invent
+one.
+
+## 1. Search the log
+
+```
+nikos decisions "<the question or topic>"
+```
+
+It quotes every entry that mentions the topic, best match first, each with
+its `intent/decisions.md:<first>-<last>` line range. A story id (e.g. HT-1)
+finds the entries tagged with it.
+
+If nothing matches, try again with the words the spec would use: the name
+of the feature, the library or the setting, and other spellings (colour and
+color).
+
+## 2. Answer from the entries
+
+Quote the lines that answer the question, cite them as
+`intent/decisions.md:<lines>`, and give the date and story id. If an entry
+says it supersedes another, quote both and say which one stands.
+
+Only cite an entry that actually answers the question. A match on a shared
+word isn't an answer.
+
+## 3. When nothing is recorded
+
+Say: "No decision about <topic> is recorded in intent/decisions.md." You may
+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>
+```
+
+Log it only once the person tells you the reason. Don't write a reason for
+them.

package/skills/intent/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: intent
+description: Explain what a story is meant to do and where it stands, from the repo's specs. Use when someone asks what a story is for, what it covers, or what state it's in, by its id (e.g. HT-2) or by topic.
+---
+
+# intent
+
+Say what the spec says, not what the code happens to do.
+
+## 1. Find the story
+
+If you have a story id, use it. If you only have a topic, search the
+`Feature:` lines under `intent/features/` and pick the story that matches.
+If more than one could match, list them and ask which one.
+
+## 2. Read everything recorded about it
+
+```
+nikos show <story-id>
+```
+
+It prints the feature (user story and scenarios), its status from
+`intent/state.yaml`, its release, the latest plan, any bets it's linked to,
+and decisions tagged with its id. Open the feature file and the plan it
+names when you need more than the summary.
+
+## 3. Answer in plain words
+
+Say, in a few sentences:
+
+- who it's for and what they get (the "As a / I want / So that" lines),
+- what has to be true for it to be done (each scenario, by its AC label),
+- where it stands: status, who has it (`claimed_by`), blockers, and the latest
+  plan. A story in the run queue but unclaimed is waiting, not being worked
+  on.
+
+Cite each claim as `path:line`, including the bet and plan files `nikos show`
+names. If the spec doesn't say something, say so.
+Don't fill the gap from the code or from guesswork.

package/skills/nikos-mode/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: nikos-mode
+description: Entry point for nikOS spec-driven work. Use at the start of any request in a repo with an intent/ folder, or when asked to plan, build, change, check or explain a story. Picks the matching playbook and runs every step of it.
+---
+
+# nikos-mode
+
+You follow a named playbook for every request instead of improvising. Run
+these five steps in order, every time.
+
+The playbooks run the `nikos` command. When it isn't installed (`nikos
+--version` fails), run it as `npx -y nikos` instead: `npx -y nikos validate`
+for `nikos validate`, and so on.
+
+## 1. Read the principles
+
+Read `principles/index.md` next to this file. Keep each principle in mind for
+the rest of the request. When one applies, say which.
+
+## 2. Pick a playbook and say which
+
+Read `playbooks/index.md`. Match the request against the "Use when" column and
+pick exactly one playbook. Then tell the person, before doing anything else:
+
+> Playbook: **<name>** (`playbooks/<file>`), because <one-line reason>.
+
+If two rows match, pick the first and say which other one you passed over. If
+nothing matches, say "No playbook matches", then use `change` when the request
+edits files in the repo and `answer` when it doesn't.
+
+## 3. Copy every step into the task list
+
+Open the chosen playbook file. Copy each numbered step into your task list,
+word for word and in order, one item per step.
+
+- If your tool has a built-in task or todo list, use it.
+- If it has none, write the list in your reply as a Markdown checklist
+  (`- [ ] 1. …`) and repeat it, updated, whenever a step changes state.
+
+Don't merge, reword, reorder or summarise steps. Don't add steps of your own
+to the playbook's list; put extra work under the step it belongs to.
+
+## 4. Never drop a step
+
+Every step ends as done or skipped. A step you don't do stays on the list,
+marked skipped, with the reason:
+
+> ~~5. Run the story's scenarios~~ skipped: the repo has no Cucumber runner yet.
+
+"Not needed" is not a reason. Say what makes it not needed.
+
+## 5. Show evidence before you say done
+
+Finish with a report that lists every step with its outcome:
+
+- **done**, with the evidence: the command you ran and its result, the file
+  and line you changed, or the passage you quoted.
+- **skipped**, with the reason from step 4.
+
+Never call the request done, fixed or passing without that evidence. If a
+check fails, say so and show the output.

package/skills/nikos-mode/playbooks/answer.md

@@ -0,0 +1,9 @@
+# answer
+
+Answer a question from what the repo's specs actually say.
+
+1. Restate the question in one sentence.
+2. Find the files in `intent/` that answer it: constitution, story map, features, plans or decisions.
+3. Answer in plain words, citing each claim as `path:line`.
+4. If the specs don't answer it, say so and name the file where the answer belongs.
+5. Report every step with its evidence or its skip reason.

package/skills/nikos-mode/playbooks/bet.md

@@ -0,0 +1,14 @@
+# bet
+
+Frame work as a time-boxed bet you can judge: what you believe, how you'll
+measure it, how much you expect it to move, by when, and which stories
+deliver it. The person decides the bet and calls the outcome.
+
+1. Ask what the person wants to move and why they think this work will move it, and read Proof, Founding hypothesis and Validation in `intent/constitution.md` and the related entries in `intent/decisions.md`.
+2. Frame the bet with the person and confirm it: a hypothesis ("We believe <change> will <effect> for <users> because <evidence>"), a key result (one measure with a number), the expected uplift (from what to what), a time box end date, and any known blockers.
+3. Pick the stories that deliver it from `intent/storymap.yaml`; if one is missing, propose it and add it only once the person agrees, following the story conventions in the idea-to-blueprint playbook.
+4. Run `nikos bet new <bet-id> --hypothesis "<…>" --kr "<…>" --uplift "<…>" --time-box <yyyy-mm-dd> --story <id>` (one `--story` per story, one `--blocker` per blocker).
+5. Fill in the card's `## Why we think so` with the evidence from step 1, quoting where it came from.
+6. Run `nikos validate` and fix every error.
+7. When the time box ends, or the person asks to close the bet: measure the key result, write it under `## Outcome`, propose won, lost or killed, set `status` once the person agrees, and record it with `nikos decide "<title>" --why "<why>" --category product`.
+8. Report every step with its evidence or its skip reason.

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

@@ -0,0 +1,14 @@
+# build-a-story
+
+Take a story from its feature file to passing scenarios. Done means the
+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.
+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>"`.
+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/skills/nikos-mode/playbooks/change.md

@@ -0,0 +1,12 @@
+# change
+
+Make a change to the repo and prove it works.
+
+1. Restate the request in one sentence and name the story id it belongs to, or say it has none.
+2. Read the story's `.feature` file and its latest plan in `intent/plans/`.
+3. If the change alters behaviour, start a new plan version with `nikos plan new <story-id>` and write the approach in it.
+4. Make the change.
+5. Run the story's scenarios and the project's tests, and keep the output.
+6. Append each decision you made to `intent/decisions.md`.
+7. Set the story's status in `intent/state.yaml`, using `done` only if step 5 passed.
+8. Report every step with its evidence or its skip reason.

package/skills/nikos-mode/playbooks/idea-to-blueprint.md

@@ -0,0 +1,16 @@
+# idea-to-blueprint
+
+Turn a one-line idea into a spec that's ready to build: a constitution, a
+story map and a feature file per story, all passing CLEAR. The person
+decides; you ask, propose and write it down.
+
+1. Capture the idea in one sentence, ask for the product's name, and confirm both with the person.
+2. If the repo has no `intent/` folder, run `nikos init --name "<product name>"`, then put the one-sentence idea in the `idea:` line at the top of `intent/constitution.md`.
+3. Ask the five vision questions one at a time (Users, Problem, Switch, First, Proof), wait for each answer, and write it into its section of `intent/constitution.md`. If an answer contradicts the idea or an earlier answer, point it out and ask which one wins.
+4. Write a `## Jobs to be done` section ("When …, I want to …, so I can …") and a `## Founding hypothesis` section ("We believe <users> will <behaviour> because <reason>. We'll know we're right when <the Proof measure>."), then confirm both with the person.
+5. Propose activities and releases, with the First answer as release 1, and write them into `intent/storymap.yaml` once the person agrees.
+6. Write each story as `intent/features/<activity>/<story-slug>.feature`: tag it with its id, release and priority, put "As a … / I want … / So that …" under `Feature:`, and make each acceptance criterion a Scenario tagged and titled with its label (`@AC1`). Add each story to `intent/state.yaml` as `todo`, and remove the example story and its `getting-started` activity that `nikos init` created.
+7. Check every story with the clear skill. For each failed check, propose the fix to the person and change the spec only once they agree.
+8. Record every choice you made on the person's behalf (anything their answers didn't settle) with `nikos decide "<title>" --why "<why>" --category product`.
+9. Run `nikos validate` and fix every error.
+10. Report every step with its evidence or its skip reason.

package/skills/nikos-mode/playbooks/index.md

@@ -0,0 +1,13 @@
+# Playbooks
+
+nikos-mode matches the request against "Use when", top to bottom, and runs the
+first match. Packs add rows here as they ship new playbooks.
+
+| Playbook | File | Use when |
+| --- | --- | --- |
+| idea-to-blueprint | `idea-to-blueprint.md` | The person has a new product idea, or wants to start a project from scratch and there is no story map yet. |
+| validate | `validate.md` | The person wants to test or validate an idea with real people, or draft outreach, a post or a demo script for it. |
+| bet | `bet.md` | The person wants to frame work as a bet, set a key result or time box for some stories, or close a bet and call its outcome. |
+| build-a-story | `build-a-story.md` | The person asks to build, do or pick up the next story, or a story by its id. |
+| answer | `answer.md` | The person asks a question about the product, a story, a plan or a decision, and nothing in the repo needs to change. |
+| change | `change.md` | The person asks to add, fix, change or remove something in the repo: code, tests, docs or specs. |

package/skills/nikos-mode/playbooks/validate.md

@@ -0,0 +1,17 @@
+# validate
+
+Test an idea with real people before building it: agree who to reach and
+what counts as proof, draft the outreach, and write what comes back into the
+constitution. You draft; the person signs off and sends. You never send,
+post, email, message or schedule anything to anyone outside the repo, even
+when a tool could.
+
+1. Read `intent/constitution.md` (Users, Problem, Switch, Proof and, if present, Founding hypothesis); if there's no constitution yet, say so and run the idea-to-blueprint playbook first.
+2. Agree with the person who to reach (which people, where to find them, how many) and the signal that counts as proof (a number with a threshold, drawn from the Proof answer; if it can only stand in for Proof, such as stated intent before there's a product, say so), and write both down before drafting anything.
+3. Draft the outreach in `intent/outreach/<yyyy-mm-dd>-<channel>.md`: one message per channel in the person's voice, the questions to ask, and, if it would help, a short demo or reel script. Mark the top of each file `Status: draft, not sent`.
+4. STOP. Show every draft with where it would go, add "Needs your sign-off: <file>" to the task list for each one, and wait for an explicit yes per draft. Change a draft only as the person asks. Silence, "looks fine" about something else, or a yes to a different draft is not sign-off.
+5. Once the person has signed off a draft, change its status to `Status: signed off <date>, for the person to send` and hand it over; the person sends it. Ask them to paste or summarise replies as they come in.
+6. Record the results under a `## Validation` section at the end of `intent/constitution.md`: for each round, the date, channel, how many were reached, how many replied, the signal against its threshold (met or not), and two or three replies in their words.
+7. Compare the results with Proof and the Founding hypothesis. Propose any change to them and make it only once the person agrees, then record it with `nikos decide "<title>" --why "<why>" --category product`.
+8. Run `nikos validate` and fix every error.
+9. Report every step with its evidence or its skip reason.

package/skills/nikos-mode/principles/index.md

@@ -0,0 +1,14 @@
+# Principles
+
+One line each: the principle, then when it applies. nikos-mode reads this on
+every request.
+
+| Principle | Applies when |
+| --- | --- |
+| **CLEAR before build.** A story must be Clear, Lean, Executable, Accurate and Responsible before anyone builds it. | You're about to plan or build a story. |
+| **Criteria are the loss function.** The acceptance criteria decide done, not the agent's opinion. | You're judging whether work is finished. |
+| **Demos, not memos.** Show it working (a passing scenario, a command and its output) rather than describing it. | You're reporting progress or claiming done. |
+| **Specs stay implementation-agnostic.** Features and criteria describe behaviour, never code, tables or libraries. | You're writing or editing a `.feature` file or story text. |
+| **Bets are time boxes.** Work is framed as a bet with an end date; when time's up, decide to ship, extend or kill. | You're scoping a chunk of work or it's running long. |
+| **Bets are grounded in evidence.** A bet cites what we saw (user quotes, numbers, results), not what we hope. | You're writing a hypothesis or a key result. |
+| **The founder signs off outreach.** Nothing is sent to real people without the founder's explicit yes. | You've drafted a message, post or email to anyone outside the repo. |

package/skills/verify/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: verify
+description: Make a story's .feature file run as a test, and prove it passes. Use when a story's scenarios can't run yet, when setting up Cucumber in a repo, or before calling a story done.
+---
+
+# verify
+
+A story is done when its scenarios pass, not when the code looks right.
+
+## 1. Set up the runner once
+
+If the repo has no `cucumber.mjs` (JavaScript or TypeScript) or `behave.ini`
+(Python), run:
+
+```
+nikos verify setup
+```
+
+It picks cucumber-js or behave from the repo's files and writes the config
+plus step stubs for the example story. It never overwrites a file. Then run
+the install command it prints.
+
+If it says it couldn't tell the stack, ask the person which runner they want.
+Don't guess.
+
+## 2. Write step definitions for the story
+
+Step definitions go in `test/steps/` (JavaScript or TypeScript) or `steps/`
+(Python). Write one for each step in the story's scenarios, and make each one
+check the real behaviour of the app: click, call or read what a user would.
+
+Never edit a `.feature` file to make a scenario pass. The feature is the spec.
+If a scenario is wrong, say so and stop. Fixing it is a spec change for the
+person to approve.
+
+## 3. Run the story
+
+```
+nikos verify <story-id>
+```
+
+It runs only that story's scenarios and fails if no feature carries the tag.
+Pending or unimplemented steps count as not passing.
+
+## 4. Report what ran
+
+Report the command and the runner's summary line, such as
+`2 scenarios (2 passed)`. If anything failed or is pending, show the output
+and don't call the story done.

package/templates/intent/constitution.md

@@ -0,0 +1,19 @@
+---
+name: {{project_name}}
+idea: One sentence on what this is and who it's for.
+---
+
+## Users
+Who it's for. Be specific: a role, a situation, a moment.
+
+## Problem
+What hurts today, in their words.
+
+## Switch
+What makes them switch now, and from what.
+
+## First
+The smallest first version that proves it.
+
+## Proof
+How you'll know it's working.

package/templates/intent/decisions.md

@@ -0,0 +1,12 @@
+# Decisions
+
+Append one entry per decision, newest last. Never rewrite an entry; add a new
+one that supersedes it.
+
+<!--
+## YYYY-MM-DD — Decision title (STORY-ID)
+**Category:** product | architecture | design | process
+**Supersedes:** none
+
+Why this, and what we rejected.
+-->

package/templates/intent/features/getting-started/first-story.feature

@@ -0,0 +1,12 @@
+@{{key}}-1 @release-1 @must @activity-getting-started
+Feature: First story
+
+  As a first user
+  I want to do the one thing this product is for
+  So that I get the value it promises
+
+  @AC1 @must
+  Scenario: AC1 — The core action works
+    Given I am a new user
+    When I do the one thing this product is for
+    Then I see the result I came for

package/templates/intent/state.yaml

@@ -0,0 +1,4 @@
+format_version: 1
+stories:
+  {{key}}-1:
+    status: todo

package/templates/intent/storymap.yaml

@@ -0,0 +1,10 @@
+format_version: 1
+project: {{project_slug}}
+key: {{key}}
+activities:
+  - id: getting-started
+    title: Getting started
+releases:
+  - number: 1
+    title: MVP
+    stories: [{{key}}-1]