oris-skills 3.0.2 → 3.0.3

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "oris-skills",
   "description": "Oris Skills: one entry point (/oris-flow) and a guided discovery-to-implementation flow. Cross-model: Cursor, Claude Code, Codex.",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "author": {
     "name": "Davide Baldassarre"
   },

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 3.0.3 - 2026-07-14
+
+- **Native route questions restored.** Ambiguous `/oris-flow` requests now traverse a
+  bounded, outcome-based navigator through Cursor `AskQuestion` or Claude
+  `AskUserQuestion`; text fallback is used only when no question tool is available.
+- **Question capability is detected, not inferred from mode.** Cursor Agent Mode can use
+  its native question UI when the runtime exposes it.
+- **Release drift is blocked.** Package and Cursor plugin versions must match, and real
+  temporary Cursor and Claude installs verify self-contained references and version
+  markers.
+
 ## 3.0.1 - 2026-07-10
 
 The lean core: one skill, one durable store, evidence on both sides of the repo boundary.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oris-skills",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "description": "Oris Skills: one entry point (/oris-flow) and a guided discovery-to-implementation flow for Cursor, Claude Code, and Codex.",
   "license": "MIT",
   "author": "Davide Baldassarre",

package/references/conventions.md

@@ -27,15 +27,14 @@ The `oris-skills` CLI is NOT installed globally. ALWAYS invoke it as `npx oris-s
 ## Questions
 
 - ASK through the platform's question tool — Claude `AskUserQuestion`, Cursor `AskQuestion`
-  (Plan Mode). A question turn = ONE call to it. Chat text is a fallback, NOT a choice: use
-  it ONLY when no such tool is available (e.g. Cursor Agent Mode) or the question cannot fit
-  the tool's schema (open-ended, or more options than it allows) — then present the options
-  as a lettered list.
+  — whenever it is present in the current tool list. Never infer availability from the
+  platform mode. A question turn = ONE call to it. Chat text is a fallback, NOT a choice:
+  use it ONLY when no question tool is present or the question is open-ended.
 - Oris gates and interview questions ALWAYS qualify for the tool: the answer decides the
   next step. NEVER skip the tool because an answer "looks like a sensible default".
-- FIT the schema: question tools cap the options (typically 4, meta-options included).
-  MORE options → split into a two-level question (category first) or use the deliberate
-  text fallback above.
+- FIT both platforms: every question has 2–4 explicit options, including meta-options.
+  MORE choices → split them into successive native questions; never flatten them to chat
+  text while the tool is present.
 - ONE question per turn. Recommended answer FIRST.
 - VISIBILITY: assume the user sees ONLY what the question tool itself renders — chat text
   emitted in the same turn as the tool call can be hidden by the platform UI. Therefore

package/scripts/tests/test-routing-lifecycle.mjs

@@ -17,6 +17,22 @@ function exists(relativePath) {
   return fs.existsSync(path.join(root, relativePath));
 }
 
+function routeDestinations(text) {
+  return [...text.matchAll(/^\|\s*[a-z-]+\s*\|[^\n]*\|\s*`(skills\/oris-flow\/references\/[a-z-]+\.md)`\s*\|$/gm)]
+    .map((match) => match[1]);
+}
+
+function navigatorNodes(text) {
+  const nodes = new Map();
+  const matches = [...text.matchAll(/^### `([a-z-]+)`\r?\n([\s\S]*?)(?=^### `|^## |(?![\s\S]))/gm)];
+  for (const match of matches) {
+    const options = [...match[2].matchAll(/^- `[^`]+` → `(node|route|explain):([a-z-]+)`/gm)]
+      .map((option) => ({ type: option[1], target: option[2] }));
+    nodes.set(match[1], options);
+  }
+  return nodes;
+}
+
 function runCli(args, homeDir) {
   return childProcess.spawnSync(process.execPath, ["scripts/oris-skills.mjs", ...args], {
     cwd: root,
@@ -40,18 +56,46 @@ test("plugin manifest skills all exist and match front-matter names", () => {
 
 test("oris-flow route table destinations exist and routing stays in-chat", () => {
   const text = read("skills/oris-flow/SKILL.md");
-  const destinations = [...text.matchAll(/`(skills\/oris-flow\/references\/[a-z-]+\.md)`/g)].map((match) => match[1]);
-  assert.ok(destinations.length >= 13, "route table must list at least 13 destinations");
+  const destinations = routeDestinations(text);
+  assert.equal(destinations.length, 16, "route table must list all 16 destinations");
   for (const destination of destinations) assert.equal(exists(destination), true, destination);
   assert.deepEqual(destinations, [...new Set(destinations)], "route destinations must be unique");
   assert.match(text, /NEVER tell the user to type another command/i);
   assert.match(text, /route to the interview owner/i);
   assert.match(text, /references\/conventions\.md/);
+  assert.match(text, /references\/question-navigator\.md/);
+  assert.doesNotMatch(text, /plain-text lettered list|present it as a plain-text/i);
+});
+
+test("question navigator covers every route within the portable option cap", () => {
+  const skill = read("skills/oris-flow/SKILL.md");
+  const navigator = read("skills/oris-flow/references/question-navigator.md");
+  const routes = routeDestinations(skill).map((destination) => path.basename(destination, ".md")).sort();
+  const nodes = navigatorNodes(navigator);
+  assert.ok(nodes.has("root"), "navigator starts at root");
+
+  const leaves = [];
+  for (const [name, options] of nodes) {
+    assert.ok(options.length >= 2 && options.length <= 4, `${name} has 2-4 options`);
+    assert.deepEqual(
+      options.filter((option) => option.type === "explain"),
+      [{ type: "explain", target: name }],
+      `${name} has one explain option returning to itself`,
+    );
+    for (const option of options) {
+      if (option.type === "node") assert.ok(nodes.has(option.target), `${name} targets existing node ${option.target}`);
+      if (option.type === "route") leaves.push(option.target);
+    }
+  }
+  assert.deepEqual(leaves.sort(), routes, "every route appears exactly once as a navigator leaf");
 });
 
 test("shared conventions centralize question, language, and gate rules", () => {
   const conventions = read("references/conventions.md");
   assert.match(conventions, /ONE question per turn/i);
+  assert.match(conventions, /whenever it is present in the current tool list/i);
+  assert.match(conventions, /2–4 explicit options/i);
+  assert.doesNotMatch(conventions, /Cursor Agent Mode|Cursor `AskQuestion`\s*\(Plan Mode\)/i);
   assert.match(conventions, /Explain the options.*Spiega le opzioni/s);
   assert.match(conventions, /NEVER write documents, code, settings, Git, or DevOps without explicit user confirmation/i);
   assert.match(conventions, /`Basta domande — procedi`/);
@@ -64,6 +108,12 @@ test("shared conventions centralize question, language, and gate rules", () => {
   assert.equal(exists("references/questions.md"), false, "questions.md was merged into conventions.md");
 });
 
+test("package and plugin expose one release version", () => {
+  const packageJson = JSON.parse(read("package.json"));
+  const plugin = JSON.parse(read(".cursor-plugin/plugin.json"));
+  assert.equal(plugin.version, packageJson.version);
+});
+
 test("every skill points at conventions instead of repeating shared rules", () => {
   const manifest = JSON.parse(read(".cursor-plugin/plugin.json"));
   for (const entry of manifest.skills) {

package/scripts/tests/test-skill-self-contained.mjs

@@ -28,38 +28,56 @@ function markdownFiles(dir) {
 // A standalone skill (Claude/Cursor) has no bundle root above it, so every reference it
 // points to must resolve inside the skill folder — the regression that broke
 // `references/conventions.md` at runtime.
-test("installed Claude skill is self-contained", () => {
+test("installed Cursor and Claude skills are self-contained and version-aligned", () => {
   const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "oris-self-contained-"));
   try {
+    fs.mkdirSync(path.join(homeDir, ".cursor"), { recursive: true });
     fs.mkdirSync(path.join(homeDir, ".claude"), { recursive: true });
-    const result = runCli(["install", "--force"], homeDir);
+    const result = runCli(["install", "--force", "--no-mcp", "--agents", "cursor,claude"], homeDir);
     assert.equal(result.status, 0, result.stderr);
 
-    const skill = path.join(homeDir, ".claude", "skills", "oris-flow");
-    assert.ok(fs.existsSync(skill), "oris-flow skill was installed");
+    const packageVersion = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version;
+    const installManifest = JSON.parse(
+      fs.readFileSync(path.join(homeDir, ".oris", "oris-skills", ".oris-skills-install.json"), "utf8"),
+    );
+    assert.equal(installManifest.version, packageVersion, "bundle manifest matches package version");
 
-    // The shared references that used to dangle must now be present.
-    for (const name of ["conventions.md", "doc-policy.md"]) {
-      assert.ok(
-        fs.existsSync(path.join(skill, "references", name)),
-        `shared reference ${name} is bundled into the skill`,
-      );
-    }
+    for (const agent of ["cursor", "claude"]) {
+      const skill = path.join(homeDir, `.${agent}`, "skills", "oris-flow");
+      assert.ok(fs.existsSync(skill), `${agent} oris-flow skill was installed`);
+
+      for (const name of ["conventions.md", "doc-policy.md", "question-navigator.md"]) {
+        assert.ok(
+          fs.existsSync(path.join(skill, "references", name)),
+          `${agent} bundles ${name}`,
+        );
+      }
 
-    const files = markdownFiles(skill);
-    const pathToken = /(?:references|templates|agents)\/[A-Za-z0-9._/-]+\.(?:md|json|toml)/g;
-    const missing = [];
-    let bundlePrefixLeaks = 0;
-    for (const file of files) {
-      const text = fs.readFileSync(file, "utf8");
-      // No bundle-root-relative pointer may survive in a standalone skill.
-      if (text.includes("skills/oris-flow/")) bundlePrefixLeaks += 1;
-      for (const cited of text.match(pathToken) ?? []) {
-        if (!fs.existsSync(path.join(skill, cited))) missing.push(`${path.basename(file)} → ${cited}`);
+      const files = markdownFiles(skill);
+      const pathToken = /(?:references|templates|agents)\/[A-Za-z0-9._/-]+\.(?:md|json|toml)/g;
+      const missing = [];
+      let bundlePrefixLeaks = 0;
+      for (const file of files) {
+        const text = fs.readFileSync(file, "utf8");
+        if (text.includes("skills/oris-flow/")) bundlePrefixLeaks += 1;
+        for (const cited of text.match(pathToken) ?? []) {
+          if (!fs.existsSync(path.join(skill, cited))) missing.push(`${path.basename(file)} → ${cited}`);
+        }
       }
+      assert.equal(bundlePrefixLeaks, 0, `${agent} has no bundle-root path leaks`);
+      assert.deepEqual(missing, [], `${agent} cited references resolve`);
+
+      const navigator = fs.readFileSync(path.join(skill, "references", "question-navigator.md"), "utf8");
+      const leaves = [...navigator.matchAll(/`route:([a-z-]+)`/g)].map((match) => match[1]);
+      assert.equal(leaves.length, 16, `${agent} navigator keeps all route leaves`);
+      for (const match of navigator.matchAll(/^### `([a-z-]+)`\r?\n([\s\S]*?)(?=^### `|^## |(?![\s\S]))/gm)) {
+        const options = match[2].match(/^- `[^`]+` → `/gm) ?? [];
+        assert.ok(options.length >= 2 && options.length <= 4, `${agent} ${match[1]} keeps 2-4 options`);
+      }
+
+      const marker = JSON.parse(fs.readFileSync(path.join(skill, ".oris-skills-managed.json"), "utf8"));
+      assert.equal(marker.version, packageVersion, `${agent} marker matches package version`);
     }
-    assert.equal(bundlePrefixLeaks, 0, "no `skills/oris-flow/` paths remain in the standalone skill");
-    assert.deepEqual(missing, [], "every cited reference resolves inside the skill");
   } finally {
     fs.rmSync(homeDir, { recursive: true, force: true });
   }

package/scripts/tests/test-skill-style.mjs

@@ -50,8 +50,9 @@ test("skill style: oris-flow", () => {
 
 test("every route reference carries the style and resolves its handles", () => {
   const skillText = fs.readFileSync(path.join(skillsRoot, "oris-flow", "SKILL.md"), "utf8");
-  const routes = [...skillText.matchAll(/`skills\/oris-flow\/references\/([a-z-]+\.md)`/g)].map((match) => match[1]);
-  assert.ok(routes.length >= 13, `router table lists all routes (found ${routes.length})`);
+  const routes = [...skillText.matchAll(/^\|\s*[a-z-]+\s*\|[^\n]*\|\s*`skills\/oris-flow\/references\/([a-z-]+\.md)`\s*\|$/gm)]
+    .map((match) => match[1]);
+  assert.equal(routes.length, 16, `router table lists all routes (found ${routes.length})`);
   assert.deepEqual(routes, [...new Set(routes)], "route destinations are unique");
   const referencesDir = path.join(skillsRoot, "oris-flow", "references");
   for (const file of routes) {

package/skills/oris-flow/SKILL.md

@@ -47,8 +47,7 @@ Match the desired outcome to ONE route, then apply its reference:
 3. CHANGED spec on a feature that already has task docs or code → change, not discover —
    change owns the delta and the history. Spec unchanged but code/reality moved on and the
    task docs lag behind → docs, not change.
-4. BROKEN behavior → fix. NEW planned work → implement. The menu answer "Implement or
-   fix" gets exactly one follow-up question to split them.
+4. BROKEN behavior → fix. NEW planned work → implement.
 5. EMPTY directory or from-scratch intent → new. Existing repo never touched by Oris
    (no `AGENTS.md`, no `.oris-flow/`) → recommend setup first; respect the user's choice.
 6. COMMIT staged/working changes with the standard → commit. OPEN or update a pull request
@@ -58,34 +57,11 @@ Match the desired outcome to ONE route, then apply its reference:
 8. CONTINUE elsewhere — session ending, context full, "pass this to another agent" →
    handoff.
 
-## Menu (low confidence)
+## Low-confidence navigator
 
-ASK "What do you want to do?" in the user's language. This menu exceeds every
-question tool's option cap — present it as a plain-text lettered list (the deliberate
-fallback in `references/conventions.md` `## Questions`), options:
-
-- Setup repository
-- New project from scratch
-- Capture an idea or bug as a work item (triage)
-- Understand / define behavior (discovery)
-- Acceptance criteria
-- Technical plan
-- Implement or fix
-- Verify acceptance criteria
-- Spec changed: update feature docs
-- Architecture review
-- Update docs
-- Commit changes
-- Open a pull request
-- Hand off this session (continue elsewhere)
-- Help
-- Explain the options / Spiega le opzioni
-
-IF "Explain the options" → ONE message that contains BOTH: one explanation line per
-option, THEN the full lettered list again below the explanations. Re-asking without the
-explanations visible in that same message is the failure this rule exists to prevent.
-Every other label maps to its route in the table above; "Implement or fix" is the one
-label that splits, with exactly one follow-up question (Precedence 4).
+IF intent is unclear → READ `skills/oris-flow/references/question-navigator.md` and APPLY
+it in the same chat. It owns the native, outcome-based route selection; the router does
+not carry or flatten its menu.
 
 ## Never
 
@@ -93,9 +69,9 @@ label that splits, with exactly one follow-up question (Precedence 4).
 - Write anything — the route's reference owns every gate.
 - Hand the user a command or skill name to type — enter the route yourself.
 - Route to implement while the plan itself is in question.
-- Keep interviewing here: one menu question maximum, then enter.
+- Keep interviewing here: unclear intent belongs to the question navigator.
 
 ## Done when
 
-- [ ] One route entered and applied in the same chat, or the menu was asked exactly once.
+- [ ] One route entered and applied in the same chat.
 - [ ] No writes happened before the route's own gate.

package/skills/oris-flow/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Oris Flow"
-  short_description: "Start the Oris workflow menu"
-  default_prompt: "Use $oris-flow to enter the right Oris workflow."
+  short_description: "Route, build, and verify with Oris"
+  default_prompt: "Use $oris-flow to enter the right Oris route."

package/skills/oris-flow/references/question-navigator.md

@@ -0,0 +1,82 @@
+# Question Navigator
+
+Choose one route when the user's intent is unclear. This is a deep routing module, not
+a route: selecting a leaf enters that route in the same chat.
+
+RULES: `references/conventions.md`.
+
+## Protocol
+
+START at `root`. ASK exactly the options of the current node through the platform's
+question tool. A `node:` target opens that node; a `route:` target enters the referenced
+route immediately.
+
+IF no question tool is present → show only the current node as a lettered list, accept
+one answer, then continue through the same tree. Never flatten multiple nodes.
+
+IF `explain` is selected → re-ask the same node with every option's description and
+consequence visible inside the question call.
+
+## Tree
+
+### `root`
+- `Understand or decide` → `node:understand` — Clarify behavior, code, or planned work.
+- `Build or verify` → `node:build` — Implement, repair, or check real behavior.
+- `Manage or deliver` → `node:manage` — Start, document, publish, continue, or get help.
+- `Explain the options` → `explain:root` — Describe these groups, then re-ask this node.
+
+### `understand`
+- `Understand behavior` → `node:behavior` — Define, test, or change product behavior.
+- `Decide the solution` → `node:solution` — Plan implementation or review architecture.
+- `Capture work for later` → `route:triage` — Create an agent-ready work item without doing it.
+- `Explain the options` → `explain:understand` — Describe these outcomes, then re-ask this node.
+
+### `behavior`
+- `Define desired behavior` → `route:discover` — Interview and document product behavior.
+- `Define acceptance criteria` → `route:criteria` — Write testable business scenarios.
+- `Update a changed specification` → `route:change` — Apply a confirmed behavior delta.
+- `Explain the options` → `explain:behavior` — Describe these routes, then re-ask this node.
+
+### `solution`
+- `Create a technical plan` → `route:plan` — Produce an execution-ready implementation plan.
+- `Review architecture` → `route:architecture` — Find deepening and refactor opportunities.
+- `Explain the options` → `explain:solution` — Describe these routes, then re-ask this node.
+
+### `build`
+- `Implement planned work` → `route:implement` — Build from a plan or confirmed scope.
+- `Fix broken behavior` → `route:fix` — Diagnose and repair a regression or failed check.
+- `Verify acceptance criteria` → `route:verify` — Check criteria against the real product.
+- `Explain the options` → `explain:build` — Describe these routes, then re-ask this node.
+
+### `manage`
+- `Start or prepare a project` → `node:start` — Bootstrap or map a repository.
+- `Document or deliver work` → `node:deliver` — Update docs, commit, or open a pull request.
+- `Continue or get help` → `node:continue` — Transfer context or troubleshoot Oris.
+- `Explain the options` → `explain:manage` — Describe these outcomes, then re-ask this node.
+
+### `start`
+- `New project from scratch` → `route:new` — Bootstrap an empty or scaffold-only repository.
+- `Set up an existing repository` → `route:setup` — Map an existing repository for Oris.
+- `Explain the options` → `explain:start` — Describe these routes, then re-ask this node.
+
+### `deliver`
+- `Update task documentation` → `route:docs` — Align task docs with current reality.
+- `Commit changes` → `route:commit` — Package changes with the Oris Git standard.
+- `Open or update a pull request` → `route:pr` — Publish the branch for review.
+- `Explain the options` → `explain:deliver` — Describe these routes, then re-ask this node.
+
+### `continue`
+- `Hand off this session` → `route:handoff` — Package state for another session or agent.
+- `Get Oris help` → `route:help` — Explain installation, usage, or troubleshooting.
+- `Explain the options` → `explain:continue` — Describe these routes, then re-ask this node.
+
+## Never
+
+- Ask about a route the user's clear intent already selected.
+- Present options from more than one node in a single question.
+- Enter two routes, or stop between a leaf selection and its route.
+
+## Done when
+
+- [ ] One leaf selected through native questions, or the same node-by-node text fallback.
+- [ ] The selected route entered in the same chat.