nikos 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niko Vijay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+```text
+           _   _        ___    ____
+   _ __   (_) | | __   / _ \  / ___|
+  | '_ \  | | | |/ /  | | | | \___ \
+  | | | | | | |   <   | |_| |  ___) |
+  |_| |_| |_| |_|\_\   \___/  |____/
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+  spec-driven development for AI coding agents
+```
+
+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
+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.
+
+> Early work in progress. Open source, MIT licensed.
+
+## Try it in 10 minutes
+
+[docs/quickstart.md](docs/quickstart.md) takes an empty repo to one passing
+scenario, with every command and the output you should see.
+
+## Install in your agent tool
+
+| Tool | Command |
+| --- | --- |
+| Claude Code | `/plugin install nikos --marketplace nikovijay/NikOS` |
+| Codex | `codex plugin marketplace add nikovijay/NikOS` |
+| Cursor | Add `https://github.com/nikovijay/NikOS` as a plugin marketplace |
+
+Then ask your agent to plan or build a story: the `nikos-mode` skill takes it
+from there. The skills run the `nikos` command through `npx`, so there's
+nothing else to install. More in [docs/install.md](docs/install.md).
+
+## The loop
+
+```bash
+npx -y nikos init                     # create intent/ with a starter story
+# write the story's scenarios in intent/features/
+npx -y nikos verify setup             # add a Cucumber runner for your stack
+npx -y nikos verify TC-1              # run the story: it fails until it's built
+# build it, then
+npx -y nikos state set TC-1 done      # refused unless its scenarios pass
+```
+
+With an agent, you only write the request ("add a story for X and build
+it"); the playbooks run these steps and stop at each point that needs you.
+
+## What lives in your repo
+
+```text
+intent/
+├── constitution.md      who it's for, the problem, what proves it works
+├── storymap.yaml        activities, releases, and the order to build stories in
+├── state.yaml           each story's status: todo, in_progress, needs_rework, done
+├── decisions.md         why things are the way they are, append-only
+├── features/            one .feature file per story; its scenarios are the criteria
+│   └── <activity>/<story>.feature
+├── plans/               how each story will be built, versioned: <story>.v<N>.md
+└── bets/                time-boxed bets and the stories that test them
+```
+
+Every file is plain text you can read, review and diff. The full format:
+[docs/format.md](docs/format.md). A worked example:
+[examples/hello-todo](examples/hello-todo/intent).
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `nikos init` | Create `intent/` in this repo |
+| `nikos validate` | Check `intent/` is well formed |
+| `nikos clear <id>` | Check a story is ready to build |
+| `nikos plan new <id>` | Start the next version of a story's plan |
+| `nikos verify setup` | Add a Cucumber runner for this repo's stack |
+| `nikos verify [id]` | Run a story's scenarios, or all of them |
+| `nikos state set <id> <status>` | Move a story; done only if its scenarios pass |
+| `nikos next` | Print the next story to build |
+| `nikos show <id>` | Summarise a story: feature, status, plan, bets, decisions |
+| `nikos decide "<title>"` | Append a decision to `decisions.md` |
+| `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
+- Quickstart: [docs/quickstart.md](docs/quickstart.md)
+- Install: [docs/install.md](docs/install.md)
+- Format: [docs/format.md](docs/format.md)
+- Writing stories as features: [docs/gherkin.md](docs/gherkin.md)
+
+MIT licensed.

package/dist/cli.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { runValidate } from "./commands/validate.js";
+import { runPlan } from "./commands/plan.js";
+import { runInit } from "./commands/init.js";
+import { runClear } from "./commands/clear.js";
+import { runVerify } from "./commands/verify.js";
+import { runNext } from "./commands/next.js";
+import { runState } from "./commands/state.js";
+import { runDecide } from "./commands/decide.js";
+import { runBet } from "./commands/bet.js";
+import { runShow } from "./commands/show.js";
+import { runDecisions } from "./commands/decisions.js";
+const commands = {
+    init: runInit,
+    validate: runValidate,
+    plan: runPlan,
+    clear: runClear,
+    verify: runVerify,
+    next: runNext,
+    state: runState,
+    decide: runDecide,
+    bet: runBet,
+    show: runShow,
+    decisions: runDecisions,
+};
+const help = `nikos — spec-driven development for AI coding agents
+
+Usage: nikos <command> [options]
+
+Commands:
+  init             Create intent/ in this repo (--name, --key)
+  validate [dir]   Check the intent/ folder is well formed
+  plan new <id>    Start the next version of a story's plan
+  clear <id>       Check a story is Lean and Executable before building
+  verify setup     Set up a Cucumber runner for this repo's stack
+  verify [id]      Run a story's scenarios (or all of them)
+  show <id>        Summarise a story: feature, status, plan, bets, decisions
+  decisions "<q>"  Quote the decisions.md entries that mention a topic or story
+  next             Print the next story to build
+  state set <id> <status>  Move a story; done only if its scenarios pass
+  decide "<title>" Append a decision to decisions.md
+                   (--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)
+
+Docs: https://nikos.tools`;
+async function main(argv) {
+    const [cmd, ...rest] = argv;
+    if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
+        console.log(help);
+        return 0;
+    }
+    const run = commands[cmd];
+    if (!run) {
+        console.error(`Unknown command '${cmd}'.\n\n${help}`);
+        return 1;
+    }
+    return run(rest);
+}
+main(process.argv.slice(2)).then((code) => process.exit(code));

package/dist/commands/bet.js

@@ -0,0 +1,97 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { Document, parse } from "yaml";
+import { STORY_ID, findIntentDir, read } from "../lib/project.js";
+export const BET_ID = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/** Story ids in any release of storymap.yaml, or undefined if there is no story map. */
+function mapStories(intentDir) {
+    const path = join(intentDir, "storymap.yaml");
+    if (!existsSync(path))
+        return undefined;
+    const map = parse(read(path));
+    return new Set((map?.releases ?? []).flatMap((r) => r?.stories ?? []));
+}
+/** Split a bet card into its front matter and body. */
+export function parseBet(text) {
+    const m = /^---\n([\s\S]*?)\n---\n?/.exec(text);
+    if (!m)
+        return undefined;
+    return { meta: parse(m[1]), body: text.slice(m[0].length) };
+}
+/** Write intent/bets/<id>.md with every field filled in, linked to stories that exist. */
+export function newBet(input, dir) {
+    if (!BET_ID.test(input.id))
+        throw new Error(`'${input.id}' is not a bet id (lowercase words joined by hyphens, e.g. faster-payment)`);
+    const fields = [
+        ["hypothesis", input.hypothesis],
+        ["key result (--kr)", input.keyResult],
+        ["expected uplift (--uplift)", input.expectedUplift],
+    ];
+    for (const [name, value] of fields)
+        if (!value?.trim())
+            throw new Error(`A bet needs a ${name}`);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(input.timeBox ?? ""))
+        throw new Error("A bet needs a time box end date (--time-box YYYY-MM-DD)");
+    if (!input.stories.length)
+        throw new Error("A bet needs at least one story (--story <id>)");
+    const bad = input.stories.filter((s) => !STORY_ID.test(s));
+    if (bad.length)
+        throw new Error(`Not story ids: ${bad.join(", ")} (expected e.g. HT-1)`);
+    const intentDir = findIntentDir(dir);
+    const known = mapStories(intentDir);
+    const unknown = known ? input.stories.filter((s) => !known.has(s)) : [];
+    if (unknown.length)
+        throw new Error(`Not in storymap.yaml: ${unknown.join(", ")}`);
+    const meta = {
+        id: input.id,
+        hypothesis: input.hypothesis.trim(),
+        key_result: input.keyResult.trim(),
+        expected_uplift: input.expectedUplift.trim(),
+        time_box: input.timeBox,
+        blockers: input.blockers ?? [],
+        stories: [...new Set(input.stories)],
+        status: "open",
+    };
+    const body = "\n## Why we think so\nThe evidence behind the hypothesis.\n\n## Outcome\nFilled in when the time box ends: the key result as measured, and won, lost or killed.\n";
+    const path = join(intentDir, "bets", `${input.id}.md`);
+    mkdirSync(dirname(path), { recursive: true });
+    // "wx" fails if the file exists, so an existing bet is never overwritten.
+    try {
+        const doc = new Document(meta);
+        for (const key of ["blockers", "stories"])
+            doc.get(key, true).flow = true;
+        writeFileSync(path, `---\n${doc.toString({ flowCollectionPadding: false, lineWidth: 0 })}---\n${body}`, { flag: "wx" });
+    }
+    catch (err) {
+        if (err.code === "EEXIST")
+            throw new Error(`A bet called '${input.id}' already exists`);
+        throw err;
+    }
+    return path;
+}
+export function runBet(args) {
+    const [sub, id, ...rest] = args;
+    const all = (n) => rest.flatMap((a, i) => (a === `--${n}` && rest[i + 1] !== undefined ? [rest[i + 1]] : []));
+    const opt = (n) => all(n)[0];
+    if (sub !== "new" || !id || id.startsWith("--")) {
+        console.error('Usage: nikos bet new <bet-id> --hypothesis "<…>" --kr "<key result>" --uplift "<expected uplift>" --time-box YYYY-MM-DD --story <id> [--story <id>] [--blocker "<…>"]');
+        return 1;
+    }
+    try {
+        const path = newBet({
+            id,
+            hypothesis: opt("hypothesis") ?? "",
+            keyResult: opt("kr") ?? "",
+            expectedUplift: opt("uplift") ?? "",
+            timeBox: opt("time-box") ?? "",
+            stories: all("story"),
+            blockers: all("blocker"),
+        }, opt("dir") ?? process.cwd());
+        console.log(`Created ${path}`);
+        return 0;
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        return 1;
+    }
+}

package/dist/commands/clear.js

@@ -0,0 +1,100 @@
+import { join } from "node:path";
+import { featureStoryIds, findIntentDir, read, rel, walk } from "../lib/project.js";
+import { parseFeature, scenariosOf } from "../lint/gherkin.js";
+const CHECKS = ["Clear", "Lean", "Executable", "Accurate", "Responsible"];
+/** Implementation detail that doesn't belong in a spec. Case-sensitive names avoid ordinary English words. */
+const LEAN_RULES = [
+    { what: "a file path", re: /\b[\w-]+(?:\/[\w.-]+)*\.(?:ts|tsx|js|jsx|py|rb|go|java|kt|swift|sql|json|ya?ml|css|html)\b/ },
+    { what: "SQL", re: /\b(?:SELECT\s+[\w*, ]+\s+FROM|INSERT\s+INTO|UPDATE\s+\w+\s+SET|DELETE\s+FROM|CREATE\s+TABLE|ALTER\s+TABLE)\b/i },
+    {
+        what: "a framework or storage name",
+        re: /\b(?:React|Vue|Angular|Svelte|Next\.js|Django|Flask|Laravel|PostgreSQL|Postgres|MySQL|MongoDB|Redis|SQLite|localStorage|sessionStorage|IndexedDB|GraphQL|Kafka|DynamoDB|Firebase|Supabase|Docker|Kubernetes)\b/,
+    },
+];
+const JUDGED = {
+    Clear: "needs a reader: one reading, no ambiguity",
+    Accurate: "needs a reader: matches constitution.md and decisions.md",
+    Responsible: "needs a reader: privacy, safety and accessibility considered",
+};
+/** Run CLEAR's mechanical checks (Lean, Executable) on a feature file and report all five checks. */
+export function clear(text) {
+    const results = new Map();
+    for (const check of ["Clear", "Accurate", "Responsible"]) {
+        results.set(check, { check, status: "agent", message: JUDGED[check] });
+    }
+    let feature;
+    try {
+        feature = parseFeature(text);
+    }
+    catch (err) {
+        feature = undefined;
+        results.set("Executable", {
+            check: "Executable",
+            status: "fail",
+            message: `isn't valid Gherkin: ${err.message.split("\n")[0]}`,
+            fix: "Fix the Gherkin syntax so the feature can run",
+        });
+    }
+    if (feature) {
+        const scenarios = scenariosOf(feature);
+        // Given is optional (docs/gherkin.md); When and Then are what make a scenario runnable.
+        const incomplete = scenarios.filter((s) => {
+            const keywords = new Set(s.steps.map((st) => st.keyword.trim()));
+            return !keywords.has("When") || !keywords.has("Then");
+        });
+        if (scenarios.length === 0) {
+            results.set("Executable", { check: "Executable", status: "fail", message: "has no scenarios", fix: "Add at least one Scenario for each acceptance criterion" });
+        }
+        else if (incomplete.length) {
+            results.set("Executable", {
+                check: "Executable",
+                status: "fail",
+                message: `${incomplete.map((s) => `"${s.name}"`).join(", ")} ${incomplete.length === 1 ? "is" : "are"} missing a When or Then step`,
+                fix: "Give every Scenario a When (the action) and a Then (the outcome)",
+            });
+        }
+        else {
+            results.set("Executable", { check: "Executable", status: "pass", message: `${scenarios.length} scenario${scenarios.length === 1 ? "" : "s"}, each with When and Then` });
+        }
+        // Only the prose: names, descriptions and steps. Tags are metadata.
+        const prose = [feature.name, feature.description, ...scenarios.flatMap((s) => [s.name, s.description, ...s.steps.map((st) => st.text)])].join("\n");
+        const found = LEAN_RULES.flatMap(({ what, re }) => {
+            const m = re.exec(prose);
+            return m ? [`${what} ("${m[0]}")`] : [];
+        });
+        results.set("Lean", found.length
+            ? { check: "Lean", status: "fail", message: `names ${found.join(", ")}`, fix: "Describe what the user sees and does; move implementation detail to the plan" }
+            : { check: "Lean", status: "pass", message: "no implementation detail found" });
+    }
+    else {
+        results.set("Lean", { check: "Lean", status: "fail", message: "can't be checked until the feature parses", fix: "Fix the Gherkin syntax first" });
+    }
+    return CHECKS.map((c) => results.get(c));
+}
+export function formatClear(results) {
+    const mark = { pass: "✓", fail: "✗", agent: "?" };
+    return results.map((r) => `${mark[r.status]} ${r.check.padEnd(11)} ${r.message}${r.fix ? `. Fix: ${r.fix}` : ""}`).join("\n");
+}
+/** Find the feature file that carries a story id. */
+export function featureFor(story, dir) {
+    return walk(join(findIntentDir(dir), "features"), ".feature").find((f) => featureStoryIds(read(f)).includes(story));
+}
+export function runClear(args) {
+    const [story, ...rest] = args;
+    if (!story) {
+        console.error("Usage: nikos clear <story-id> [--dir <path>]");
+        return 1;
+    }
+    const i = rest.indexOf("--dir");
+    const dir = i >= 0 ? rest[i + 1] : process.cwd();
+    const file = featureFor(story, dir);
+    if (!file) {
+        console.error(`✗ No feature file is tagged @${story}`);
+        return 1;
+    }
+    const results = clear(read(file));
+    console.log(`CLEAR ${story} (${rel(process.cwd(), file)})\n${formatClear(results)}`);
+    if (results.some((r) => r.status === "agent"))
+        console.log("\n? = judged by the agent with the clear skill");
+    return results.some((r) => r.status === "fail") ? 1 : 0;
+}

package/dist/commands/decide.js

@@ -0,0 +1,60 @@
+import { appendFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { STORY_ID, findIntentDir, read } from "../lib/project.js";
+import { formatResult, validate } from "./validate.js";
+const CATEGORIES = ["product", "architecture", "design", "process"];
+/** Append a dated entry to decisions.md. Earlier entries are never touched. */
+export function decide(input, dir) {
+    const title = input.title.trim();
+    if (!title)
+        throw new Error("A decision needs a title");
+    if (!input.why.trim())
+        throw new Error("Say why: what you chose and what you rejected (--why)");
+    if (input.story && !STORY_ID.test(input.story))
+        throw new Error(`'${input.story}' is not a story id (expected e.g. HT-1)`);
+    const category = input.category ?? "architecture";
+    if (!CATEGORIES.includes(category))
+        throw new Error(`Category must be one of ${CATEGORIES.join(", ")}`);
+    const path = join(findIntentDir(dir), "decisions.md");
+    if (!existsSync(path))
+        throw new Error("No intent/decisions.md. Run `nikos init` first.");
+    const date = input.date ?? new Date().toISOString().slice(0, 10);
+    const entry = [
+        `## ${date} — ${title}${input.story ? ` (${input.story})` : ""}`,
+        `**Category:** ${category}`,
+        `**Supersedes:** ${input.supersedes ?? "none"}`,
+        "",
+        input.why.trim(),
+        "",
+    ].join("\n");
+    const existing = read(path);
+    const gap = existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+    appendFileSync(path, gap + entry);
+    return entry;
+}
+export function runDecide(args) {
+    const [title, ...rest] = args;
+    const opt = (n) => {
+        const i = rest.indexOf(`--${n}`);
+        return i >= 0 ? rest[i + 1] : undefined;
+    };
+    if (!title || title.startsWith("--")) {
+        console.error('Usage: nikos decide "<title>" --why "<why>" [--story <id>] [--category product|architecture|design|process] [--supersedes "<title>"]');
+        return 1;
+    }
+    const dir = opt("dir") ?? process.cwd();
+    try {
+        decide({ title, why: opt("why") ?? "", story: opt("story"), category: opt("category"), supersedes: opt("supersedes") }, dir);
+        console.log(`Added to decisions.md: ${title}`);
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        return 1;
+    }
+    const v = validate(dir);
+    if (v.errors.length) {
+        console.error(formatResult(v));
+        return 1;
+    }
+    return 0;
+}

package/dist/commands/decisions.js

@@ -0,0 +1,71 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { findIntentDir, read } from "../lib/project.js";
+const STOP = new Set(["the", "and", "for", "why", "did", "was", "were", "are", "you", "how", "what", "with", "this", "that", "not", "use", "using", "instead", "of", "we", "our", "decide", "decided", "choose", "chose", "rather", "than"]);
+/** Every "## " entry in decisions.md, with its line range. HTML comments are skipped. */
+export function decisionEntries(dir) {
+    const path = join(findIntentDir(dir), "decisions.md");
+    if (!existsSync(path))
+        return [];
+    const lines = read(path).split("\n");
+    const entries = [];
+    let inComment = false;
+    let current;
+    lines.forEach((line, i) => {
+        if (line.trim().startsWith("<!--"))
+            inComment = true;
+        const commented = inComment;
+        if (line.includes("-->"))
+            inComment = false;
+        if (commented)
+            return;
+        if (line.startsWith("## ")) {
+            current = { start: i + 1, end: i + 1, title: line.slice(3).trim(), text: line };
+            entries.push(current);
+        }
+        else if (current && !line.startsWith("# ")) {
+            current.text += `\n${line}`;
+            if (line.trim())
+                current.end = i + 1;
+        }
+    });
+    for (const e of entries)
+        e.text = e.text.trimEnd();
+    return entries;
+}
+export function queryTerms(query) {
+    return [...new Set(query.toLowerCase().split(/[^\p{L}\p{N}-]+/u).filter((w) => w.length >= 3 && !STOP.has(w)))];
+}
+/** Entries that mention the query, best match first. Entries matching under half as many terms as the best are dropped. */
+export function findDecisions(query, dir) {
+    const terms = queryTerms(query);
+    if (!terms.length)
+        return [];
+    const scored = decisionEntries(dir)
+        .map((e) => {
+        const text = e.text.toLowerCase();
+        return { e, hits: terms.filter((t) => new RegExp(`(^|[^\\p{L}\\p{N}])${t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "u").test(text)).length };
+    })
+        .filter((m) => m.hits > 0);
+    const best = Math.max(0, ...scored.map((m) => m.hits));
+    return scored
+        .filter((m) => m.hits * 2 >= best)
+        .sort((a, b) => b.hits - a.hits || a.e.start - b.e.start)
+        .map((m) => m.e);
+}
+export function formatDecisions(query, found) {
+    if (!found.length)
+        return `No decision in intent/decisions.md mentions "${query}".`;
+    return found.map((e) => `intent/decisions.md:${e.start}-${e.end}\n${e.text}`).join("\n\n");
+}
+export function runDecisions(args) {
+    const i = args.indexOf("--dir");
+    const dir = i >= 0 ? args[i + 1] : process.cwd();
+    const query = (i >= 0 ? [...args.slice(0, i), ...args.slice(i + 2)] : args).join(" ").trim();
+    if (!query) {
+        console.error('Usage: nikos decisions "<topic or story id>" [--dir <path>]');
+        return 1;
+    }
+    console.log(formatDecisions(query, findDecisions(query, dir)));
+    return 0;
+}

package/dist/commands/init.js

@@ -0,0 +1,72 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { walk } from "../lib/project.js";
+import { validate, formatResult } from "./validate.js";
+const here = dirname(fileURLToPath(import.meta.url));
+const templateDir = [join(here, "../../templates/intent"), join(here, "../templates/intent")].find((d) => existsSync(d));
+export function slugify(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "project";
+}
+/** "Hello Todo" → "HT", "nikos" → "NIK". */
+export function keyFor(name) {
+    const words = name.replace(/[^A-Za-z0-9 ]+/g, " ").trim().split(/\s+/).filter(Boolean);
+    const key = words.length > 1 ? words.map((w) => w[0]).join("") : (words[0] ?? "P").slice(0, 3);
+    const clean = key.toUpperCase().replace(/^[0-9]+/, "");
+    return (clean || "P").slice(0, 6);
+}
+export function init(root, opts = {}) {
+    const name = opts.name ?? basename(resolve(root));
+    const key = (opts.key ?? keyFor(name)).toUpperCase();
+    if (!/^[A-Z][A-Z0-9]{0,9}$/.test(key))
+        throw new Error(`'${key}' isn't a valid project key (letters and digits, starting with a letter)`);
+    const values = { project_name: name, project_slug: slugify(name), key };
+    const intentDir = join(root, "intent");
+    const created = [];
+    const skipped = [];
+    for (const src of walk(templateDir)) {
+        const rel = relative(templateDir, src);
+        const dest = join(intentDir, rel);
+        if (existsSync(dest)) {
+            skipped.push(rel);
+            continue;
+        }
+        mkdirSync(dirname(dest), { recursive: true });
+        if (rel.endsWith(".gitkeep")) {
+            copyFileSync(src, dest);
+        }
+        else {
+            const text = readFileSync(src, "utf8").replace(/\{\{(\w+)\}\}/g, (_, k) => values[k] ?? `{{${k}}}`);
+            // "wx" guards against a race where the file appears between the check and the write.
+            writeFileSync(dest, text, { flag: "wx" });
+        }
+        created.push(rel);
+    }
+    return { intentDir, created, skipped, validation: validate(intentDir) };
+}
+export function runInit(args) {
+    const opt = (n) => {
+        const i = args.indexOf(`--${n}`);
+        return i >= 0 ? args[i + 1] : undefined;
+    };
+    try {
+        const r = init(opt("dir") ?? process.cwd(), { name: opt("name"), key: opt("key") });
+        if (r.skipped.length === 0) {
+            console.log(`Created intent/ (${r.created.length} files)`);
+        }
+        else {
+            if (r.created.length)
+                console.log(`Created:\n${r.created.map((f) => `  + intent/${f}`).join("\n")}`);
+            console.log(`Skipped (already there):\n${r.skipped.map((f) => `  = intent/${f}`).join("\n")}`);
+        }
+        console.log(formatResult(r.validation));
+        if (r.validation.errors.length === 0 && r.skipped.length === 0) {
+            console.log("\nNext: fill in intent/constitution.md, then write your first story in intent/features/.");
+        }
+        return r.validation.errors.length ? 1 : 0;
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        return 1;
+    }
+}

package/dist/commands/next.js

@@ -0,0 +1,35 @@
+import { join } from "node:path";
+import { parse } from "yaml";
+import { findIntentDir, read } from "../lib/project.js";
+/** The first todo story in run.queue, then in story map order. */
+export function next(dir) {
+    const intentDir = findIntentDir(dir);
+    const map = parse(read(join(intentDir, "storymap.yaml")));
+    const state = parse(read(join(intentDir, "state.yaml")));
+    const stories = state?.stories ?? {};
+    const mapOrder = (map?.releases ?? [])
+        .slice()
+        .sort((a, b) => a.number - b.number)
+        .flatMap((r) => r.stories ?? []);
+    const order = [...new Set([...(state?.run?.queue ?? []), ...mapOrder])];
+    const open = order.filter((id) => ["in_progress", "needs_rework"].includes(stories[id]?.status ?? "")).map((id) => ({ id, status: stories[id].status }));
+    return { story: order.find((id) => (stories[id]?.status ?? "todo") === "todo"), open };
+}
+export function runNext(args) {
+    const i = args.indexOf("--dir");
+    try {
+        const r = next(i >= 0 ? args[i + 1] : process.cwd());
+        for (const o of r.open)
+            console.log(`! ${o.id} is ${o.status}; finish it first`);
+        if (!r.story) {
+            console.log("Nothing left to do: every story is started or done.");
+            return 0;
+        }
+        console.log(r.story);
+        return 0;
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        return 1;
+    }
+}