nikos 0.0.5 → 0.0.7

package/dist/cli.js

@@ -11,6 +11,7 @@ import { runBet } from "./commands/bet.js";
 import { runShow } from "./commands/show.js";
 import { runDecisions } from "./commands/decisions.js";
 import { runStory } from "./commands/story.js";
+import { runVideo } from "./commands/video.js";
 const commands = {
     init: runInit,
     validate: runValidate,
@@ -24,6 +25,7 @@ const commands = {
     show: runShow,
     decisions: runDecisions,
     story: runStory,
+    video: runVideo,
 };
 const help = `nikos — spec-driven development for AI coding agents
 
@@ -46,6 +48,8 @@ Commands:
                    (--why, --story, --category, --supersedes)
   bet new <bet-id> Write a time-boxed bet card linked to its stories
                    (--hypothesis, --kr, --uplift, --time-box, --story, --blocker)
+  video            Draft a video brief and storyboard from the done stories
+                   (--out, default marketing/storymap-video)
 
 Docs: https://nikos.tools`;
 async function main(argv) {

package/dist/commands/video.js

@@ -0,0 +1,116 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { parse } from "yaml";
+import { findIntentDir, featureStoryIds, read, walk } from "../lib/project.js";
+import { parseFeature, scenariosOf } from "../lint/gherkin.js";
+// Timing: a title card, then each beat holds longer for more stories, then the close.
+const INTRO = 4.5, BEAT = 2.6, PER_STORY = 1.8, CLOSE = 6;
+/** The constitution's front matter and its "## Section" bodies. */
+function constitution(intentDir) {
+    const path = join(intentDir, "constitution.md");
+    if (!existsSync(path))
+        throw new Error("No intent/constitution.md: run the idea-to-blueprint playbook first");
+    const text = read(path);
+    const fm = /^---\n([\s\S]*?)\n---\n/.exec(text);
+    const meta = (fm ? parse(fm[1]) : {});
+    const sections = {};
+    for (const m of text.slice(fm?.[0].length ?? 0).matchAll(/^## (.+)\n([\s\S]*?)(?=^## |(?![\s\S]))/gm))
+        sections[m[1].trim()] = m[2].trim();
+    return { name: meta.name ?? "", idea: meta.idea ?? "", users: sections.Users ?? "", problem: sections.Problem ?? "" };
+}
+/** Draft a video storyboard from intent/: only stories marked done, one beat per activity. */
+export function storyboard(dir) {
+    const intentDir = findIntentDir(dir);
+    const c = constitution(intentDir);
+    const map = parse(read(join(intentDir, "storymap.yaml")));
+    const state = (parse(read(join(intentDir, "state.yaml"))) ?? {});
+    const stories = walk(join(intentDir, "features"), ".feature").flatMap((path) => {
+        const text = read(path);
+        const id = featureStoryIds(text)[0];
+        const feature = parseFeature(text);
+        if (!id || !feature)
+            return [];
+        const activity = feature.tags.map((t) => t.name).find((t) => t.startsWith("@activity-"))?.slice(10) ?? "";
+        // "AC1 — A new plant shows its next watering day" → "A new plant shows its next watering day"
+        const outcomes = scenariosOf(feature).map((s) => s.name.replace(/^AC\d+\s*[—–-]\s*/, ""));
+        return [{ id, title: feature.name, activity, outcomes, done: state.stories?.[id]?.status === "done" }];
+    });
+    const byNumber = (a, b) => Number(a.id.split("-")[1]) - Number(b.id.split("-")[1]);
+    const done = stories.filter((s) => s.done).sort(byNumber);
+    if (!done.length)
+        throw new Error("No story is done yet. A video shows only what's built: finish a story first (nikos next)");
+    let t = INTRO;
+    const beats = (map.activities ?? []).flatMap((a) => {
+        const shown = done.filter((s) => s.activity === a.id).map(({ id, title, outcomes }) => ({ id, title, outcomes }));
+        if (!shown.length)
+            return [];
+        const from = t;
+        t += BEAT + PER_STORY * Math.min(shown.length, 4);
+        return [{ activity: a.title ?? a.id, from, to: t, stories: shown }];
+    });
+    return {
+        product: { name: c.name, idea: c.idea },
+        users: c.users,
+        problem: c.problem,
+        beats,
+        notBuilt: stories.filter((s) => !s.done).sort(byNumber).map(({ id, title }) => ({ id, title })),
+        intro: [0, INTRO],
+        close: [t, t + CLOSE],
+        total: Math.ceil(t + CLOSE),
+    };
+}
+const sec = (n) => `${Math.round(n * 10) / 10}s`;
+/** The brief a person approves before anything renders. */
+export function briefOf(sb) {
+    const rows = sb.beats.map((b, i) => `| ${sec(b.from)}–${sec(b.to)} | ${String(i + 1).padStart(2, "0")} ${b.activity} | ${b.stories.map((s) => `${s.id} ${s.title}`).join("; ")} |`);
+    return [
+        `# Brief: ${sb.product.name}`,
+        "",
+        "Drafted by `nikos video` from intent/. Approve the beats before rendering; change anything here first.",
+        "",
+        `- **Product:** ${sb.product.name}. ${sb.product.idea}`,
+        `- **For:** ${sb.users}`,
+        `- **Problem:** ${sb.problem}`,
+        `- **Length:** about ${sb.total} seconds, 1080p, music only. Plays muted, so the labels carry the story.`,
+        "- **In:** only stories marked done in state.yaml, each with the outcomes its passing scenarios check.",
+        `- **Out:** ${sb.notBuilt.length ? `anything not built yet: ${sb.notBuilt.map((s) => `${s.id} ${s.title}`).join("; ")}.` : "nothing; every story is done."}`,
+        `- **Close:** ${sb.product.name}, and its idea in one line.`,
+        "",
+        "## Beats",
+        "",
+        "One beat per activity with done stories.",
+        "",
+        "| Time | Label | Stories shown |",
+        "| --- | --- | --- |",
+        `| ${sec(sb.intro[0])}–${sec(sb.intro[1])} | Title | ${sb.product.name}: ${sb.product.idea} |`,
+        ...rows,
+        `| ${sec(sb.close[0])}–${sec(sb.close[1])} | Close | ${sb.product.name} |`,
+        "",
+    ].join("\n");
+}
+/** Write brief.md and storyboard.js (read by the Video pack's storyboard template) into `out`. */
+export function writeVideo(dir, out) {
+    const sb = storyboard(dir);
+    mkdirSync(out, { recursive: true });
+    writeFileSync(join(out, "brief.md"), briefOf(sb));
+    writeFileSync(join(out, "storyboard.js"), `// Drafted by nikos video from intent/. The storyboard template reads it.\nwindow.STORYBOARD = ${JSON.stringify(sb, null, 2)};\n`);
+    return sb;
+}
+export function runVideo(args) {
+    const i = args.indexOf("--out");
+    const out = resolve(i >= 0 && args[i + 1] ? args[i + 1] : "marketing/storymap-video");
+    try {
+        const sb = writeVideo(process.cwd(), out);
+        const shown = sb.beats.reduce((n, b) => n + b.stories.length, 0);
+        const r = relative(process.cwd(), out), where = !r ? "." : r.startsWith("..") ? out : r;
+        console.log(`Wrote ${where}/brief.md and ${where}/storyboard.js: ${sb.beats.length} beat${sb.beats.length === 1 ? "" : "s"}, ${shown} done ${shown === 1 ? "story" : "stories"}, about ${sb.total}s`);
+        if (sb.notBuilt.length)
+            console.log(`Left out, not done yet: ${sb.notBuilt.map((s) => s.id).join(", ")}`);
+        console.log("\nNext: approve the beats in brief.md, then render them with the Video pack's storyboard template.");
+        return 0;
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        return 1;
+    }
+}

package/docs/install.md

@@ -50,6 +50,20 @@ then Add Marketplace, then Import from Repo), and install nikOS from it.
 To try it without a marketplace, copy the repo to
 `~/.cursor/plugins/local/nikos` and run "Developer: Reload Window".
 
+## Packs
+
+Packs are extra tools that install on their own, next to nikOS or without it.
+Each lives in `tools/<pack>/` with its own manifests and skills, and both
+marketplaces list it.
+
+| Pack | Folder | Claude Code |
+| --- | --- | --- |
+| Video | `tools/video/` | `/plugin install nikos-video@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
+install command when the pack is missing.
+
 ## The command-line tool
 
 The skills run the `nikos` command. When it isn't installed, they run it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nikos",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "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",
@@ -38,8 +38,8 @@
     "vitest": "^2.1.9"
   },
   "dependencies": {
-    "@cucumber/gherkin": "^30.0.4",
-    "@cucumber/messages": "^26.0.1",
+    "@cucumber/gherkin": "^42.0.1",
+    "@cucumber/messages": "^34.2.1",
     "ajv": "^8.17.1",
     "yaml": "^2.6.1"
   },

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

@@ -6,6 +6,7 @@ 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. |
+| 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. |
 | 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. |

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

@@ -0,0 +1,14 @@
+# video
+
+Make a short product explainer video from a brief. The work is done by the
+`product-tour-video` skill, which ships in the Video pack, not in nikOS
+itself. This playbook checks the pack is there, pins down the brief, and
+hands over to that skill's workflow.
+
+1. Check the Video pack is installed: the `product-tour-video` skill is in your skills list. If it isn't, tell the person to install it (Claude Code: `/plugin install nikos-video@nikos`; Codex and Cursor: install `nikos-video` from the nikOS marketplace), say the video can't be made until they do, and stop.
+2. Write the brief down before anything else. If the repo has an `intent/` folder with done stories, run `nikos video --out marketing/<name>`: it drafts `brief.md` and `storyboard.js` from `intent/constitution.md` and the stories marked done, one beat per activity, and leaves out everything not built yet. Otherwise write the product, who the video is for, its length, where it will live, the story it tells in one line, and what's in or out. Ask for anything missing.
+3. Make it with the `product-tour-video` skill. From a drafted storyboard, render its storyboard template (the skill's "From a nikOS story map" section). For a tour of the product's real screens, follow the skill's workflow, every step in its order: find out what's real, storyboard for sign-off, the style test, the full build, the contact sheet, the score, then render and mix.
+4. STOP at the storyboard (the beats in `brief.md`, or the skill's storyboard table) and, for a screen tour, again at the style test, and wait for the person's yes each time. A yes to one isn't a yes to the other.
+5. Check the encoded `final.mp4`: extract a few frames with ffmpeg and look at them, and give its length and size.
+6. Deliver `final.mp4` with the brief it was made from. Commit the video's sources only; the rendered files stay ignored.
+7. Report every step with its evidence or its skip reason.