nikos 0.0.7 → 0.1.1

package/docs/format.md

@@ -19,8 +19,6 @@ intent/
   state.yaml             status, blockers and the run queue
   outreach/              optional, drafts from the validate playbook
     <date>-<channel>.md
-  bets/                  optional, time-boxed bets (see Bets)
-    <bet-id>.md
 ```
 
 Two rules hold across every file:
@@ -79,8 +77,8 @@ five vision sections come first, in order, and aren't empty.
 
 ## storymap.yaml
 
-**Purpose:** the shape of the product: activities (columns), releases (rows)
-and the order stories should be built in. It is an index; the stories
+**Purpose:** the shape of the product: activities and their steps (columns),
+releases (rows) and the order stories should be built in. It is an index; the stories
 themselves live in feature files.
 
 **Path:** `intent/storymap.yaml`
@@ -94,9 +92,15 @@ key: HT                     # story id prefix: HT-1, HT-2 …
 activities:
   - id: tasks               # slug, matches the features/<activity>/ folder
     title: Manage tasks
+    steps:                  # optional: the steps a person takes in this activity
+      - id: capture         # slug, unique across the map; a story tags it @step-capture
+        title: Capture a task
+      - id: focus
+        title: Focus on today
 releases:
   - number: 1
     title: MVP
+    goal: Capture tasks and see only today's top three.   # optional, one line
     stories: [HT-1, HT-2]   # build order within the release
   - number: 2
     title: Enhancements
@@ -108,10 +112,49 @@ Rules:
 - Every story id appears in exactly one release.
 - Every story id has exactly one feature file and one `state.yaml` entry.
 - Release numbers start at 1 and have no gaps.
+- Step ids are unique across the map. A story's `@step-<id>` must name a step
+  of its own activity. A story with no step sits under the activity's first
+  step on the map.
+- A story's `@release-N` tag should match the release that lists it;
+  `nikos validate` warns when they differ.
 
-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.
+### Bet links (optional)
+
+A release can name the bets it delivers, and a single story can override its
+release's list. The bets themselves live outside `intent/`, in `planning/`
+(the Planning pack, see [planning.md](planning.md)).
+
+```yaml
+releases:
+  - number: 1
+    title: MVP
+    bets: [fewer-missed-tasks]                 # a bet in planning/bets/
+    stories: [HT-1, HT-2]
+story_bets:
+  HT-2: [acme/company-plan#focus-mode]         # this story serves another repo's bet
+```
+
+- A bet id must have a `planning/bets/<id>.md` in the same repo.
+- `owner/repo#id` names another repo's bet. `nikos validate` checks its form
+  only and never fetches it.
+- A story's `story_bets` entry replaces its release's `bets` for that story.
+
+Add a story with `nikos story add "<title>" --activity <id> [--step <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.
+
+The map's shape has commands too, so nobody has to hand-edit the YAML. Each
+keeps comments and leaves the rest of the file as it was:
+
+| Command | What it does |
+| --- | --- |
+| `nikos step add "<title>" --activity <id>` | Add a step under an activity (`--id` to choose its id) |
+| `nikos release add "<title>" [--goal "<goal>"]` | Add the next numbered release, with no stories yet (titles must be unique) |
+| `nikos release rename <n> ["<title>"] [--goal "<goal>"]` | Change a release's title or goal (`--goal ""` removes it) |
+| `nikos release move <story-id> <n>` | Move a story to the end of another release and retag its feature |
+| `nikos release reorder <n> <position>` | Move a release, renumber them all from 1 and retag every moved story |
+| `nikos release remove <n>` | Remove a release with no stories or bets, renumber the rest and retag their stories |
 
 ---
 
@@ -129,7 +172,7 @@ story; each acceptance criterion is a `Scenario` (or `Scenario Outline`)
 titled with its label. Full rules are in [gherkin.md](gherkin.md).
 
 ```gherkin
-@HT-1 @release-1 @must @activity-tasks
+@HT-1 @release-1 @must @activity-tasks @step-capture
 Feature: Add a task
 
   As a busy person
@@ -172,8 +215,6 @@ summary: One to three plain sentences on the approach.
 Notes for the agent.
 ```
 
-These fields match intentdocs plans one to one (see the mapping doc).
-
 Start a new version with `nikos plan new <story-id>`. It writes the next
 `v<N>` from a template, sets `supersedes`, and refuses to overwrite an
 existing file.
@@ -250,51 +291,6 @@ founder sends it, never the agent.
 
 ---
 
-## bets/&lt;bet-id&gt;.md (optional)
-
-**Purpose:** a time-boxed bet that a set of stories will move a measure.
-
-**Path:** `intent/bets/<bet-id>.md`, where `<bet-id>` is lowercase words
-joined by hyphens.
-
-**Format:** Markdown with YAML front matter, then free-form notes. Create one
-with `nikos bet new`; the bet playbook frames and closes it.
-
-```markdown
----
-id: faster-reorder
-hypothesis: We believe drag to reorder will make people plan their day in the app because they reorder on paper today.
-key_result: Share of daily users who reorder at least once
-expected_uplift: from 10% to 30%
-time_box: 2026-12-01
-blockers: []
-stories: [HT-3]
-status: open
----
-
-## Why we think so
-The evidence behind the hypothesis.
-
-## Outcome
-Filled in when the time box ends.
-```
-
-| Field | Required | Meaning |
-| --- | --- | --- |
-| `id` | yes | Matches the file name |
-| `hypothesis` | yes | What you believe and why |
-| `key_result` | yes | The one measure that says whether it worked |
-| `expected_uplift` | yes | How far you expect it to move, from what to what |
-| `time_box` | yes | End date, `YYYY-MM-DD` |
-| `blockers` | yes | What stands in the way; `[]` if nothing |
-| `stories` | yes | At least one story id; each must be in `storymap.yaml` |
-| `status` | yes | `open \| won \| lost \| killed` |
-
-`nikos validate` checks every field against `schemas/bet.schema.json`, that
-the id matches the file name, and that every linked story exists.
-
----
-
 ## Versioning this format
 
 `format_version` in `storymap.yaml` and `state.yaml` is the version of this

package/docs/gherkin.md

@@ -8,7 +8,7 @@ and the test: each acceptance criterion is a scenario that Cucumber can run.
 ## The shape of a story
 
 ```gherkin
-@HT-1 @release-1 @must @activity-tasks @effort-S
+@HT-1 @release-1 @must @activity-tasks @step-capture @effort-S
 Feature: Add a task
 
   As a busy person
@@ -54,6 +54,7 @@ criterion's priority).
 | `@release-N` | release the story is in | yes |
 | `@must` / `@should` / `@could` | story priority | yes |
 | `@activity-<id>` | activity, matching the folder name | no |
+| `@step-<id>` | step within that activity, from `storymap.yaml` | no |
 | `@effort-XS` … `@effort-XL` | size estimate | no |
 
 Anything else is a warning, so you notice typos.

package/docs/install.md

@@ -59,6 +59,7 @@ marketplaces list it.
 | Pack | Folder | Claude Code |
 | --- | --- | --- |
 | Video | `tools/video/` | `/plugin install nikos-video@nikos` |
+| Planning | `tools/planning/` | `/plugin install nikos-planning@nikos` |
 
 In Codex and Cursor, install the pack from the same marketplace as nikOS.
 nikOS's router hands requests to an installed pack's skill, and gives the
@@ -72,14 +73,20 @@ it anyway: `npm install -g nikos`.
 
 ## Formats checked
 
-Plugin formats change often. These were read on 2026-11-04 (no page showed a
-version):
+Plugin formats change often. These were read on 2026-11-04, and the display
+name fields again on 2026-11-05 (no page showed a version):
 
 - Claude Code: https://code.claude.com/docs/en/plugins-reference and
   https://code.claude.com/docs/en/plugins/marketplace-reference. Checked with
-  `claude plugin validate .` on Claude Code 2.1.318.
-- Cursor: https://cursor.com/docs/reference/plugins
-- Codex: https://developers.openai.com/plugins/build/plugins
+  `claude plugin validate .` on Claude Code 2.1.318. `displayName` is the
+  name shown in the UI. A marketplace entry's `displayName` wins over the
+  plugin's. The marketplace `name` stays the install id (`nikos@nikos`).
+- Cursor: https://cursor.com/docs/reference/plugins. That page does not list
+  `displayName`. `.cursor-plugin/plugin.json` still sets it so a listing can
+  show nikOS, and `name` stays the kebab-case id.
+- Codex: https://developers.openai.com/plugins/build/plugins. The plugin
+  title is `interface.displayName` in `.codex-plugin/plugin.json`. The
+  marketplace title is the same field on `.agents/plugins/marketplace.json`.
 
 All three find skills as `skills/<name>/SKILL.md` at the plugin root.
 `test/install.test.ts` checks the manifests agree with each other and with

package/docs/planning.md

@@ -0,0 +1,124 @@
+# The planning/ format
+
+The Planning pack keeps objectives, key results and bets in a `planning/`
+folder at the repo root, next to `intent/`. Planning sets direction; the
+story map in `intent/` handles delivery. Everything is plain text and only
+changes when you (or your agent, with your yes) change it.
+
+```
+planning/
+  plan.yaml              period, level, pillars and objectives
+  krs/<kr-id>.yaml       key results and their check-ins
+  bets/<bet-id>.md       bet cards
+  upstream.yaml          optional: plans in other repos this one works toward
+  upstream.lock          written by `nikos planning sync`
+  views/<name>.html      optional: custom dashboard views
+```
+
+`nikos planning validate` checks every file against `schemas/planning/`.
+
+## plan.yaml
+
+**Purpose:** the planning context: the period, the level being planned
+(company, department, group or team), its strategic pillars and objectives.
+
+```yaml
+period: Q1 2027
+level: team
+pillars: [Retention]
+objectives:
+  - id: keep-plants-alive
+    title: People keep their plants alive
+    aligns_to: acme/company-plan#plants-alive   # optional
+```
+
+## krs/&lt;kr-id&gt;.yaml
+
+**Purpose:** one key result, with dated check-ins that are only ever added to.
+
+```yaml
+id: reminders-acted-on
+title: Reminders acted on the same day
+objective: keep-plants-alive
+owner: Reminders team
+unit: "%"
+baseline: 41
+target: 60
+original_target: 60        # kept when the target is revised
+by: 2027-03-31
+aligns_to: acme/company-plan#kr-2   # optional, another repo's key result
+stale_after_days: 14       # optional, default 14
+checkins:
+  - date: 2027-01-20
+    value: 44
+    note: First week of the new reminder time.
+    evidence: https://analytics.example.com/reminders
+```
+
+Add one with `nikos planning kr new`, check in with `nikos planning checkin`,
+and revise a target with `nikos planning kr target` (the original stays).
+
+## bets/&lt;bet-id&gt;.md
+
+**Purpose:** a bet: what we believe, the key results it should move, when we
+review it, and every review decision since.
+
+```markdown
+---
+id: reminders-that-stick
+owner: Reminders team
+team: Reminders
+hypothesis: We believe reminders at each plant's real watering time get acted on the same day.
+krs:
+  primary: reminders-acted-on
+  also: [acme/company-plan#kr-2]
+starts: 2027-01-06
+review_on: 2027-02-14
+deadline: 2027-03-31        # optional: only a hard deadline
+confidence: medium          # low | medium | high
+dependencies: [Push notifications (Platform team)]
+outcome: open               # open | awaiting evidence | won | lost | stopped
+reviews:
+  - date: 2027-02-17
+    decision: continue      # continue | change | stop | complete
+    reason: 55% against 60%. Keep going; review again 3 Mar.
+---
+
+## Why we think so
+41% of reminders are acted on the same day; most misses arrive at night.
+```
+
+- A bet card has no `stories` field. The story map names the bets each
+  release delivers (`bets:` on a release, `story_bets:` for one story; see
+  [format.md](format.md)).
+- `krs` may be empty for maintenance or risk-reduction work.
+- Delivery (Shipped, Building, Not started) is worked out from the stories
+  that deliver the bet. The outcome only changes at a review: stop sets
+  `stopped`; complete sets `won` or `lost` from the key result evidence.
+
+Write one with `nikos planning bet new`; review it with
+`nikos planning bet review`.
+
+## upstream.yaml and upstream.lock
+
+**Purpose:** the plans in other repos this one works toward, read without
+ever writing to them.
+
+```yaml
+- repo: acme/company-plan
+  ref: main
+  # url: https://git.example.com/acme/company-plan.git   (optional; defaults to GitHub)
+```
+
+`nikos planning sync` clones each into `.nikos/upstream/<owner>/<repo>/`
+(gitignored; sync adds it to `.gitignore`) and writes the commit it read to
+`upstream.lock`. A repo it can't reach is reported as unresolved and planning
+carries on. `nikos planning sync --check` says whether an upstream has moved
+past its locked commit. This repo only stores references like
+`owner/repo#id`, never upstream content.
+
+## views/&lt;name&gt;.html
+
+**Purpose:** a custom dashboard view, served by `nikos planning serve` at
+`/views/<name>`. It reads and writes only through the view contract in the
+pack's dashboard playbook.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nikos",
-  "version": "0.0.7",
+  "version": "0.1.1",
   "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",
@@ -24,6 +24,7 @@
     "docs"
   ],
   "scripts": {
+    "prebuild": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "build": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build && npm test",
     "test": "vitest run",

package/schemas/planning/bet.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nikos.tools/schemas/planning/bet.schema.json",
+  "title": "nikOS Planning bet card front matter",
+  "type": "object",
+  "required": ["id", "owner", "hypothesis", "krs", "review_on", "confidence", "dependencies", "outcome", "reviews"],
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
+    "owner": { "type": "string", "minLength": 1 },
+    "team": { "type": "string", "minLength": 1 },
+    "hypothesis": { "type": "string", "minLength": 1 },
+    "krs": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "primary": { "type": "string", "minLength": 1 },
+        "also": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "starts": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    "review_on": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    "deadline": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    "confidence": { "enum": ["low", "medium", "high"] },
+    "dependencies": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "outcome": { "enum": ["open", "awaiting evidence", "won", "lost", "stopped"] },
+    "reviews": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["date", "decision", "reason"],
+        "additionalProperties": false,
+        "properties": {
+          "date": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+          "decision": { "enum": ["continue", "change", "stop", "complete"] },
+          "reason": { "type": "string", "minLength": 1 },
+          "outcome": { "enum": ["won", "lost", "stopped"] }
+        }
+      }
+    }
+  }
+}

package/schemas/planning/kr.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nikos.tools/schemas/planning/kr.schema.json",
+  "title": "nikOS Planning key result",
+  "type": "object",
+  "required": ["id", "title", "owner", "baseline", "target", "original_target", "by", "checkins"],
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
+    "title": { "type": "string", "minLength": 1 },
+    "objective": { "type": "string", "minLength": 1 },
+    "owner": { "type": "string", "minLength": 1 },
+    "unit": { "type": "string" },
+    "baseline": { "type": "number" },
+    "target": { "type": "number" },
+    "original_target": { "type": "number" },
+    "by": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    "aligns_to": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+#[a-z0-9]+(-[a-z0-9]+)*$" },
+    "stale_after_days": { "type": "integer", "minimum": 1 },
+    "checkins": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["date", "value"],
+        "additionalProperties": false,
+        "properties": {
+          "date": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+          "value": { "type": "number" },
+          "note": { "type": "string" },
+          "evidence": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/schemas/planning/plan.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nikos.tools/schemas/planning/plan.schema.json",
+  "title": "nikOS Planning context",
+  "type": "object",
+  "required": ["period", "level", "pillars"],
+  "additionalProperties": false,
+  "properties": {
+    "name": { "type": "string", "minLength": 1 },
+    "period": { "type": "string", "minLength": 1 },
+    "level": { "enum": ["company", "department", "group", "team"] },
+    "pillars": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "objectives": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "title"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
+          "title": { "type": "string", "minLength": 1 },
+          "owner": { "type": "string" },
+          "aligns_to": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/schemas/storymap.schema.json

@@ -3,22 +3,66 @@
   "$id": "https://nikos.tools/schemas/storymap.schema.json",
   "title": "nikOS story map",
   "type": "object",
-  "required": ["format_version", "project", "key", "activities", "releases"],
+  "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}$" },
+    "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"],
+        "required": [
+          "id",
+          "title"
+        ],
         "additionalProperties": false,
         "properties": {
-          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
-          "title": { "type": "string", "minLength": 1 }
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1
+          },
+          "steps": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "id",
+                "title"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "pattern": "^[a-z0-9][a-z0-9-]*$"
+                },
+                "title": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              }
+            }
+          }
         }
       }
     },
@@ -27,17 +71,56 @@
       "minItems": 1,
       "items": {
         "type": "object",
-        "required": ["number", "title", "stories"],
+        "required": [
+          "number",
+          "title",
+          "stories"
+        ],
         "additionalProperties": false,
         "properties": {
-          "number": { "type": "integer", "minimum": 1 },
-          "title": { "type": "string", "minLength": 1 },
+          "number": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1
+          },
+          "goal": {
+            "type": "string",
+            "minLength": 1
+          },
           "stories": {
             "type": "array",
-            "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9]{0,9}-[0-9]+$" }
+            "items": {
+              "type": "string",
+              "pattern": "^[A-Z][A-Z0-9]{0,9}-[0-9]+$"
+            }
+          },
+          "bets": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "uniqueItems": true
           }
         }
       }
+    },
+    "story_bets": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[A-Z][A-Z0-9]{0,9}-[0-9]+$"
+      },
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "minLength": 1
+        },
+        "uniqueItems": true
+      }
     }
   }
 }

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

@@ -8,7 +8,7 @@ decides; you ask, propose and write it down.
 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.
+5. Propose activities, the steps a person takes in each, and releases with a one-line goal, with the First answer as release 1. Once the person agrees, write them into `intent/storymap.yaml` (`nikos step add` and `nikos release add` do this without hand-editing).
 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`.

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

@@ -8,7 +8,7 @@ first match. Packs add rows here as they ship new playbooks.
 | 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. |
 | video | `video.md` | The person asks for a video: an explainer, product tour, demo, launch or social clip, or to edit or re-render one. Needs the Video pack. |
 | 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. |
+| planning | `planning.md` | The person wants to plan a period, set OKRs or key results, frame or review a bet, check in on key results, or see a planning dashboard. Needs the Planning pack. |
 | 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/planning.md

@@ -0,0 +1,11 @@
+# planning
+
+Plan a period, frame or review a bet, check in on key results or open the
+planning dashboard. The work is done by the `nikos-planning` skill, which
+ships in the Planning pack, not in nikOS itself. This playbook checks the
+pack is there and hands over to it.
+
+1. Check the Planning pack is installed: the `nikos-planning` skill is in your skills list. If it isn't, tell the person to install it (Claude Code: `/plugin install nikos-planning@nikos`; Codex and Cursor: install `nikos-planning` from the nikOS marketplace), say planning can't run until they do, and stop.
+2. Hand over to the `nikos-planning` skill: say which of its playbooks matches the request, and run every step of it in order.
+3. Bets are linked from the story map, not the other way round: when a release or story delivers a bet, it's named in `intent/storymap.yaml` (`bets:` on the release, or `story_bets:`), and `nikos validate` checks the link.
+4. Report every step with its evidence or its skip reason.

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

@@ -9,6 +9,4 @@ every request.
 | **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. |