nikos 0.0.0-stage → 0.0.2

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]

package/templates/plan.md

@@ -0,0 +1,13 @@
+---
+story: {{story}}
+version: {{version}}
+created: {{date}}
+{{supersedes}}summary: {{summary}}
+---
+
+## 1. {{first_step}}
+**Why:** what changes for the user.
+**Criteria:** AC1
+**Files:** 
+
+Notes for the agent.

package/templates/verify/js/cucumber.mjs

@@ -0,0 +1,6 @@
+// Created by `nikos verify setup`. Runs the stories in intent/ as tests.
+export default {
+  paths: ["intent/features/**/*.feature"],
+  import: ["test/steps/**/*.steps.mjs"],
+  format: ["progress"],
+};

package/templates/verify/js/test/steps/first-story.steps.mjs

@@ -0,0 +1,16 @@
+// Step definitions for intent/features/getting-started/first-story.feature.
+// Replace each "pending" with a real check against your app. Never edit the
+// feature to make a step pass.
+import { Given, When, Then } from "@cucumber/cucumber";
+
+Given("I am a new user", function () {
+  return "pending";
+});
+
+When("I do the one thing this product is for", function () {
+  return "pending";
+});
+
+Then("I see the result I came for", function () {
+  return "pending";
+});

package/templates/verify/python/behave.ini

@@ -0,0 +1,4 @@
+# Created by `nikos verify setup`. Runs the stories in intent/ as tests.
+# Step definitions live in steps/ at the repo root.
+[behave]
+paths = intent/features

package/templates/verify/python/steps/first_story_steps.py

@@ -0,0 +1,19 @@
+# Step definitions for intent/features/getting-started/first-story.feature.
+# Replace each NotImplementedError with a real check against your app. Never
+# edit the feature to make a step pass.
+from behave import given, when, then
+
+
+@given("I am a new user")
+def step_new_user(context):
+    raise NotImplementedError("STEP: Given I am a new user")
+
+
+@when("I do the one thing this product is for")
+def step_core_action(context):
+    raise NotImplementedError("STEP: When I do the one thing this product is for")
+
+
+@then("I see the result I came for")
+def step_result(context):
+    raise NotImplementedError("STEP: Then I see the result I came for")

package/templates/verify/ts/cucumber.mjs

@@ -0,0 +1,6 @@
+// Created by `nikos verify setup`. Runs the stories in intent/ as tests.
+export default {
+  paths: ["intent/features/**/*.feature"],
+  import: ["test/steps/**/*.steps.ts"],
+  format: ["progress"],
+};

package/templates/verify/ts/test/steps/first-story.steps.ts

@@ -0,0 +1,16 @@
+// Step definitions for intent/features/getting-started/first-story.feature.
+// Replace each "pending" with a real check against your app. Never edit the
+// feature to make a step pass.
+import { Given, When, Then } from "@cucumber/cucumber";
+
+Given("I am a new user", function (): string {
+  return "pending";
+});
+
+When("I do the one thing this product is for", function (): string {
+  return "pending";
+});
+
+Then("I see the result I came for", function (): string {
+  return "pending";
+});