oris-skills 3.0.1 → 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/README.md

@@ -30,7 +30,9 @@ fixes the colleague part with three rules baked into every interaction:
 
 `/oris-flow` reads your intent and enters the right route in the same chat — no other
 command exists. Say "the login button does nothing" and you are in **fix**; say "the
-client changed their mind about invoicing" and you are in **change**.
+client changed their mind about invoicing" and you are in **change**; say "a client
+reported this, park it" and **triage** captures it as a work item; say "I'm out of
+context" and **handoff** packages the session for the next one.
 
 ```text
         idea ──► discover ──► criteria ──► plan ──► implement ──► verify
@@ -42,6 +44,7 @@ client changed their mind about invoicing" and you are in **change**.
 |-------|---------|
 | **setup** | the repo made agent-ready: detected commands and structure confirmed into `AGENTS.md`; AI-readiness check |
 | **new** | a greenfield project born agent-native: sparse `AGENTS.md`, domain glossary, first ADR, red→green test observed |
+| **triage** | raw intake — an idea, a bug report — becomes a work item with an agent-ready brief, duplicates linked, routed onward |
 | **discover** | business-first interview → `functional-analysis.md` |
 | **criteria** | observable, stable-ID acceptance criteria → `acceptance-criteria.md` |
 | **plan** | technical interview → `implementation-plan.md` with bounded, verifiable steps — external APIs verified against their docs, sources recorded |
@@ -50,6 +53,7 @@ client changed their mind about invoicing" and you are in **change**.
 | **change** | spec delta interviewed, **all** documents updated in one approved pass → `change-log.md` |
 | **architecture / docs / help** | deepening review, doc alignment, answers |
 | **commit / pr** | Conventional Commits and English PRs, work item linked, always gated |
+| **handoff** | session state packaged outside the repo — decisions, evidence, next move — so a fresh session resumes exactly there |
 
 Every route follows one skeleton — what to do, what **Never** to do, and a **Done when**
 checklist — enforced by the test suite, so the discipline survives refactors.

package/docs/user-guide.md

@@ -6,9 +6,9 @@ Install once, remember one command:
 npx oris-skills@latest install     # detects Cursor / Claude Code / Codex / Copilot (VS Code)
 ```
 
-Then type **`/oris-flow`** in your agent chat. It routes your request or shows a short menu (setup, new project, discovery, criteria, plan, implement/fix, verify, spec change, architecture review, docs, commit, pull request, help). The skill never triggers itself — you invoke it. On Codex use the installed `/oris-flow` prompt; on Copilot Chat use `/oris-flow` too (enable the VS Code setting `chat.promptFiles` once). Any other agent: tell it to read `~/.oris/oris-flow.md`.
+Then type **`/oris-flow`** in your agent chat. It routes your request or shows a short menu (setup, new project, triage, discovery, criteria, plan, implement/fix, verify, spec change, architecture review, docs, commit, pull request, handoff, help). The skill never triggers itself — you invoke it. On Codex use the installed `/oris-flow` prompt; on Copilot Chat use `/oris-flow` too (enable the VS Code setting `chat.promptFiles` once). Any other agent: tell it to read `~/.oris/oris-flow.md`.
 
-The flow in one line: **discover → criteria → plan → implement → verify**, with `fix` for bugs and `change` when the spec changes mid-flight (it updates all task docs together and logs `CH-xxx` history). `new` bootstraps an AI-driven project from scratch; `architecture` maps deepening/refactor opportunities. Task documents live in `.oris-flow/tasks/` by default — your project's own docs stay untouched.
+The flow in one line: **discover → criteria → plan → implement → verify**, with `fix` for bugs and `change` when the spec changes mid-flight (it updates all task docs together and logs `CH-xxx` history). `new` bootstraps an AI-driven project from scratch; `architecture` maps deepening/refactor opportunities. `triage` turns raw ideas and bug reports into work items on your DevOps board before the flow starts; `handoff` packages a session's state — decisions, evidence, next move — so a fresh session resumes exactly where this one stopped. Task documents live in `.oris-flow/tasks/` by default — your project's own docs stay untouched.
 
 ## What setup leaves in your repo
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oris-skills",
-  "version": "3.0.1",
+  "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/clean-code-checklist.md

@@ -1,6 +1,6 @@
 # Clean Code Checklist
 
-Used by `oris-flow-implement` and `oris-flow-fix` while closing work: clean what YOU introduced, in the files you touched. Investigate before concluding; absence in one file is not proof of dead code.
+Used by `skills/oris-flow/references/implement.md` and `skills/oris-flow/references/fix.md` while closing work: clean what YOU introduced, in the files you touched. Investigate before concluding; absence in one file is not proof of dead code.
 
 ## Check, in the touched scope only
 
@@ -15,6 +15,6 @@ Used by `oris-flow-implement` and `oris-flow-fix` while closing work: clean what
 
 Before removing anything: search references and call sites (including DI registration, reflection, dynamic imports, routing, code generation, framework conventions). Tests, config, or registration may still require the symbol.
 
-## Never here
+## Never
 
 Bug fixes (→ `skills/oris-flow/references/fix.md`), architectural redesign, cross-feature refactors, DevOps, drive-by cleanup of code you did not touch.

package/references/conventions.md

@@ -27,26 +27,38 @@ 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
+  everything the answer depends on rides INSIDE the call: the recap/context in the
+  `question` text (compact — counted facts, not prose), each option's meaning and
+  consequence in its description. NEVER put a recap or summary in chat text and then call
+  the question tool in the same turn — the user may see the bare question and nothing else.
 - ALWAYS include, in the user's language:
-  - `Explain the options` / `Spiega le opzioni` — explain, then re-ask the same question.
+  - `Explain the options` / `Spiega le opzioni` — when picked, RE-ASK the same question
+    WITH the explanations embedded in the call itself: every option's description states
+    what it means and what happens if chosen; the `question` text may add one context
+    line. Re-asking the question unchanged, or explaining only in chat text before the
+    call, is a failure — the user reported seeing the bare question again. In text-fallback
+    menus: explanations first, then the full lettered list again, in ONE message.
   - During interviews: `Enough questions — proceed` / `Basta domande — procedi` (early exit → go to the generation gate; NOT approval to write).
 - NEVER ask what the workspace, docs, code, or setup map already answer. Explore first.
 
 ## Generation gates
 
 - Standard labels, localized: `Generate the document` / `Genera il documento`, `Approve document` / `Approva documento`, `Continue the interview` / `Continua l'intervista`, `Cancel` / `Annulla`.
-- NEVER write documents before the explicit gate choice. Exception: `oris-flow-criteria` writes first, then asks ONCE — the document is confirmed only on approval.
-- After a document is written: concise summary + contextual next-step menu. NEVER auto-start the next phase.
+- NEVER write documents before the explicit gate choice. Exception: `skills/oris-flow/references/criteria.md` writes first, then asks ONCE — the document is confirmed only on approval.
+- After a document is written: concise summary + contextual next-step menu. The summary
+  rides inside the next-step question (`## Questions` VISIBILITY rule) — never as chat
+  text the tool call can hide. NEVER auto-start the next phase.
 
 ## Language
 

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`/);
@@ -59,10 +103,17 @@ test("shared conventions centralize question, language, and gate rules", () => {
   assert.match(conventions, /`Continua l'intervista`/);
   assert.match(conventions, /`Approva documento`/);
   assert.match(conventions, /`Annulla`/);
-  assert.match(conventions, /oris-flow-criteria.*writes first/i, "the criteria write-first exception must live where skills read it");
+  assert.match(conventions, /skills\/oris-flow\/references\/criteria\.md`.*writes first/i, "the criteria write-first exception must live where skills read it");
+  assert.doesNotMatch(conventions, /oris-flow-(criteria|implement|fix)/, "destinations are named by file path, never by prose nickname");
   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

@@ -1,6 +1,6 @@
 ---
 name: oris-flow
-description: The one Oris skill - read the intent, pick ONE route, apply it in the same chat. Routes setup, new project, discovery, acceptance criteria, technical plan, implement, fix, verify, spec change, architecture review, docs, commit, pull request, and help.
+description: The one Oris skill - read the intent, pick ONE route, apply it in the same chat. Routes setup, new, triage, discover, criteria, plan, implement, fix, verify, change, architecture, docs, commit, pr, handoff, and help.
 disable-model-invocation: true
 ---
 
@@ -23,6 +23,7 @@ Match the desired outcome to ONE route, then apply its reference:
 |-------|----------------------|-------|
 | setup | prepare / map / refresh an existing repo for Oris and agents | `skills/oris-flow/references/setup.md` |
 | new | bootstrap a project from scratch, greenfield, empty directory | `skills/oris-flow/references/new.md` |
+| triage | capture an idea, bug report, or request as a work item with an agent-ready brief | `skills/oris-flow/references/triage.md` |
 | discover | understand or define product behavior, functional analysis | `skills/oris-flow/references/discover.md` |
 | criteria | acceptance criteria, QA checks, testable scenarios | `skills/oris-flow/references/criteria.md` |
 | plan | a technical implementation plan before coding | `skills/oris-flow/references/plan.md` |
@@ -34,6 +35,7 @@ Match the desired outcome to ONE route, then apply its reference:
 | docs | update task docs after a change | `skills/oris-flow/references/docs.md` |
 | commit | commit changes with the Oris standard — Conventional Commits, work item linked | `skills/oris-flow/references/commit.md` |
 | pr | open or update a pull request, English title/description linked to the work item | `skills/oris-flow/references/pr.md` |
+| handoff | package session state — decisions, evidence, next move — to resume in a fresh session | `skills/oris-flow/references/handoff.md` |
 | help | how Oris works, install, update, troubleshooting | `skills/oris-flow/references/help.md` |
 
 ## Precedence (the calls that look ambiguous)
@@ -43,37 +45,23 @@ Match the desired outcome to ONE route, then apply its reference:
 2. RETHINK beats build: analyze, question, or reshape existing work →
    route to the interview owner (discover / plan / change), NEVER straight to implement.
 3. CHANGED spec on a feature that already has task docs or code → change, not discover —
-   change owns the delta and the history.
-4. BROKEN behavior → fix. NEW planned work → implement. The menu answer "Implement or
-   fix" gets exactly one follow-up question to split them.
+   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.
 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
    → pr. Neither writes product code — they package and publish what implement/fix produced.
+7. CAPTURE work for later (an idea, a report, backlog intake) → triage — it creates the
+   work item and stops. DOING the work now → discover / fix / implement.
+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
-- 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
-- Help
-- Explain the options / Spiega le opzioni
-
-IF "Explain the options" → explain briefly, re-ask the same question.
-Every other label maps 1:1 to its route in the table above.
+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
 
@@ -81,9 +69,9 @@ Every other label maps 1:1 to its route in the table above.
 - 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 choose the right Oris workflow command."
+  short_description: "Route, build, and verify with Oris"
+  default_prompt: "Use $oris-flow to enter the right Oris route."

package/skills/oris-flow/references/architecture.md

@@ -37,10 +37,13 @@ WRITE a self-contained HTML file to the OS temp dir (`architecture-review-<times
 OPEN it (`start` | `open` | `xdg-open`), TELL the absolute path.
 
 FORMAT: Tailwind CDN + Mermaid CDN. Per candidate, one card:
-- title (names the deepening) + strength badge: `Strong` | `Worth exploring` | `Speculative`;
+- title (names the deepening) + strength badge — `Strong` (friction observed in the code,
+  fix shape clear) | `Worth exploring` (friction observed, fix shape uncertain) |
+  `Speculative` (pattern suggests it, not yet observed);
 - files (monospaced), Problem (one sentence), Solution (one sentence);
 - Before/After diagram side by side — Mermaid for graph-shaped, hand-built divs/SVG for
-  mass diagrams; if the diagram needs a paragraph, redraw the diagram;
+  mass diagrams; the diagram must explain itself without a caption — if it needs one,
+  simplify the diagram;
 - wins as bullets ≤6 words, glossary terms only — never "cleaner code";
 - ADR conflict → amber callout ("contradicts ADR-0007 — worth reopening because…").
 

package/skills/oris-flow/references/change.md

@@ -3,6 +3,9 @@
 Specs changed while the feature exists (documented, planned, or half-built). Understand
 the delta, update EVERYTHING together, keep the history traceable.
 
+BOUNDARY: the business spec MOVED → this route. Spec unchanged but code/reality moved on
+and the docs lag behind → `skills/oris-flow/references/docs.md`.
+
 RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
 
 ## Delta interview

package/skills/oris-flow/references/criteria.md

@@ -12,9 +12,13 @@ RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
    preferred, never required — say once when missing) > current UI > code and tests.
 2. DEDUCE create vs update: existing `acceptance-criteria.md` → update, PRESERVE IDs.
 3. IDs: `AC-001`, `AC-002`, … stable across revisions.
-4. Each scenario declares ALL of: role + starting state · deterministic data · numbered
-   user steps · observable outcome under the step that causes it · negative coverage ·
-   regressions to keep.
+4. Each scenario declares ALL of:
+   - role + starting state;
+   - deterministic data;
+   - numbered user steps;
+   - observable outcome under the step that causes it;
+   - negative coverage;
+   - regressions to keep.
 5. CLASSIFY each: `Verifiable` | `Needs setup/data` | `Blocked by Open QA`.
 6. DISCARD criteria not checkable through observable product behavior. Unbuilt features:
    only confirmed intended behavior.

package/skills/oris-flow/references/docs.md

@@ -3,6 +3,9 @@
 Bring `{tasksRoot}/{task}/` documents in line with a later change, keeping the change
 traceable ({tasksRoot} per doc-policy).
 
+BOUNDARY: the spec is unchanged but code/reality moved on → this route. The business spec
+itself changed → `skills/oris-flow/references/change.md` (it owns the delta and the history).
+
 RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
 
 ## Workflow
@@ -18,7 +21,8 @@ RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
    - add one change-history row per document: date | source | short change | reason;
    - keep unresolved risks in open points;
    - preserve acceptance-criteria IDs.
-7. CLOSE with a concise summary. Offer next steps without auto-starting them.
+7. CLOSE with a concise summary. OFFER next: commit the doc updates
+   (`skills/oris-flow/references/commit.md`) | stop — never auto-started.
 
 ## Never
 

package/skills/oris-flow/references/fix.md

@@ -5,7 +5,7 @@ any edit, evidence before done.
 
 RULES: `references/conventions.md`. Research: `references/research.md`.
 
-## Triage
+## Intake
 
 1. IF no details given → ask ONE question: what happens, what was expected, where
    (link/ID when one exists).
@@ -37,7 +37,8 @@ RULES: `references/conventions.md`. Research: `references/research.md`.
 1. RUN the reproduction + targeted tests; broaden if the surface is shared.
 2. SUMMARIZE: cause, change, verification, residual risk.
 3. RECOMMEND: `skills/oris-flow/references/verify.md` when criteria exist; docs update
-   (`skills/oris-flow/references/docs.md`) when documented behavior changed.
+   (`skills/oris-flow/references/docs.md`) when documented behavior changed; commit
+   (`skills/oris-flow/references/commit.md`) when the fix is verified and ready to package.
 
 ## Never
 

package/skills/oris-flow/references/handoff.md

@@ -0,0 +1,67 @@
+# Handoff
+
+Package this session's state so the next session — or another agent — resumes from the
+exact point: decisions, evidence, next move. The handoff is a bridge, not a store: task
+docs and `AGENTS.md` stay the truth, the handoff points at them and carries ONLY what
+lives nowhere else yet.
+
+RULES: `references/conventions.md`. Entering handoff IS the request to write it — no
+generation gate; the document lands outside the repo.
+
+## 1. Collect (silent)
+
+1. GATHER from this conversation: the active task and route, decisions the user
+   confirmed, evidence observed (commands seen green, verifications, reproductions),
+   open questions with their current best answer, and the next move.
+2. SPLIT what you gathered:
+   - already recorded in task docs or `AGENTS.md` → the handoff POINTS at the file;
+   - confirmed in chat but written nowhere → the handoff CARRIES it, marked with who
+     confirmed it;
+   - speculation → out, or listed as an open question.
+3. Durable project facts proved this session and missing from `AGENTS.md` → write them
+   back NOW (`references/conventions.md` `## Project facts`), so the handoff can point
+   instead of carry.
+
+## 2. Write (outside the repo)
+
+WRITE `handoff-{task-or-topic}-{timestamp}.md` to the OS temp directory — never inside
+the repo or `{tasksRoot}`. Language: `artifactLanguage` (another session reads this cold —
+never caveman-compressed). Structure:
+
+```markdown
+# Handoff — {task or topic}
+Date: … | Repo: {absolute path} | Route in progress: {route or none}
+## Where we are
+What was asked, what is done, what is verified — evidence, not claims.
+## Decisions confirmed in chat, not yet in docs
+- {decision} — confirmed by {user}, because {reason}
+## Read before acting
+- {file} — {why it matters first}
+## Open questions
+- {question} — current best answer: {answer or none}
+## Next move
+One imperative sentence: the first action the next session takes.
+## Resume with
+{the route reference to re-enter} — {one-line why}
+```
+
+TELL the absolute path + a one-line summary of the next move. OFFER: keep working here |
+stop.
+
+## Never
+
+- Write the handoff inside the repo or under `{tasksRoot}` — it is session luggage, not
+  a project document.
+- Duplicate task-doc or `AGENTS.md` content — point at the file.
+- Carry anything not observed in this session or confirmed by the user — a handoff that
+  guesses poisons the next session.
+- Include secrets or tokens — mask as `***`.
+- Auto-start the next route after writing.
+
+## Done when
+
+- [ ] Facts proved this session written back to `AGENTS.md` before the handoff.
+- [ ] Every item in the handoff is a pointer, an observed fact, or a user-confirmed
+      decision — nothing guessed.
+- [ ] Document written to the OS temp dir; absolute path and next move shown.
+- [ ] Resume route named; nothing auto-started.

package/skills/oris-flow/references/help.md

@@ -12,6 +12,8 @@ details on request.
 | Copilot / any other agent | Copilot Chat: enable `chat.promptFiles` once, then `/oris-flow`. Anything else that reads files: point it at `~/.oris/oris-flow.md`. |
 | Uninstall / reinstall | `npx oris-skills uninstall` / `npx oris-skills reinstall` (preview with `--dry-run`). |
 | Skill missing after install | Reload the agent; check `~/.oris/oris-skills/` exists; re-run install with `--force`. |
+| Capture an idea or bug without doing it now | `/oris-flow` → Triage — it becomes a work item with a brief, routed to its route. |
+| Context window full / continue in a new session | `/oris-flow` → Hand off — writes a resume doc and names the route to re-enter. |
 | Change document language / chat verbosity | `/oris-flow` → Setup (settings live in `.oris-flow/settings.json`). |
 | Ultra-short answers | `/oris-flow` → Setup → set `responseStyle: caveman` — chat shrinks to maximum token density; documents stay complete. |
 

package/skills/oris-flow/references/implement.md

@@ -34,7 +34,8 @@ RULES: `references/conventions.md`. Research: `references/research.md`.
 1. RUN targeted verification first; broaden when the touched surface is shared.
 2. SUMMARIZE: touched files, verification results, residual risk.
 3. RECOMMEND next: `skills/oris-flow/references/verify.md` when acceptance criteria exist;
-   otherwise update docs (`skills/oris-flow/references/docs.md`).
+   otherwise update docs (`skills/oris-flow/references/docs.md`) or commit
+   (`skills/oris-flow/references/commit.md`) when the change is verified and ready to package.
 
 ## Never
 

package/skills/oris-flow/references/pr.md

@@ -22,8 +22,8 @@ RULES: `references/conventions.md`. DevOps config: `references/devops.md`.
 ## Gate (never skipped)
 
 SHOW the title + description + target branch. ASK: open PR | edit | cancel.
-ON open → create via the provider (Azure DevOps MCP `oris-devops`, or `gh` for GitHub)
-read from `references/devops.md`. Missing provider auth → say so; never guess credentials.
+ON open → create via the configured provider (`references/devops.md` — read `provider`,
+act generically). Missing provider auth → say so; never guess credentials.
 
 ## After
 

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.

package/skills/oris-flow/references/setup.md

@@ -5,7 +5,8 @@ preferences in `.oris-flow/settings.json`, AI-readiness checked. ADAPT to what t
 IS; never force one structure. Writes ONLY after the user confirms the recap.
 
 RULES: `references/conventions.md`. Settings: `references/settings.md`.
-IF the repo is empty or brand-new → route to `skills/oris-flow/references/new.md` instead.
+IF the repo has no source files, or no commit beyond a scaffold-only init → route to
+`skills/oris-flow/references/new.md` instead.
 
 ## Mode
 
@@ -28,9 +29,9 @@ ELSE → create from scratch.
 4. FAN OUT parallel subagent scans (docs, frontend, backend/data, tests/build, local
    skills/rules) by DEFAULT whenever the repo has more than one of those areas —
    entering setup is the user's request to spawn (`references/conventions.md`
-   `## Subagents`). SKIP only when the repo is small enough that the baseline already
-   answers every §2 decision — say you skipped and why. No agent tool on the platform →
-   same scans inline, sequentially.
+   `## Subagents`). SKIP only when the baseline scan already answers EVERY §2 decision
+   (project type, tasks root, verify commands, version control) — say you skipped and
+   name the evidence. No agent tool on the platform → same scans inline, sequentially.
 
 ## 2. Present findings, decide one at a time
 

package/skills/oris-flow/references/triage.md

@@ -0,0 +1,69 @@
+# Triage
+
+Turn raw intake — an idea, a bug report, a request — into a work item on the DevOps
+provider with a brief the next route can act on. Capture, classify, route: the work
+itself stays with discover / fix / implement.
+
+RULES: `references/conventions.md`. Provider: `references/devops.md`.
+
+## 1. Understand the intake
+
+1. READ the resolved DevOps config (`references/devops.md`). Provider tools missing or
+   unauthenticated → degrade: compose everything below, show it, tell the user where to
+   paste it — never block on tooling.
+2. SEARCH the provider for existing work items matching the intake (title, keywords,
+   area) BEFORE composing anything. A match → propose linking/updating it, never a
+   duplicate.
+3. CLASSIFY on evidence: bug (behavior observed broken) | feature (new behavior) |
+   spec change on an existing feature | chore. Cheap checks against the repo or product
+   come before questions; a claim you could verify and didn't stays a claim.
+4. ASK one question at a time, only for gaps evidence cannot close: expected vs actual,
+   reproduction conditions, desired outcome, urgency. Early exit always available.
+
+## 2. Compose the work item
+
+BUILD title + description (language `artifactLanguage`; title says the behavior, not the
+solution). Description carries the brief:
+
+```markdown
+## Intake
+{verbatim request} — source: {who/where}, date: {date}
+## Type & evidence
+{bug|feature|spec change|chore} — {what was checked, what was observed}
+## Expected vs actual        ← bugs; features: ## Desired outcome
+…
+## Reproduction              ← bugs only
+1. …
+## Links
+{duplicates found, related items, task docs if any}
+## Next step
+{the Oris route that should pick this up}
+```
+
+Spec change on a feature that already has task docs → say so: the delta belongs to
+`skills/oris-flow/references/change.md`; the work item only tracks it.
+
+## 3. Gate, write, route
+
+1. SHOW the composed work item compactly (or the update to the existing one).
+2. ASK ONE question: Create the work item | Adjust | Stop. Update case: Update the
+   existing item | Adjust | Stop.
+3. ON approval → write via the provider; SHOW the id in the provider's `workItemSyntax`.
+   Degraded mode → deliver the composed item as text instead.
+4. OFFER next: enter the route named in the brief now | triage another intake | stop.
+
+## Never
+
+- Do the work here — no code, no task docs; triage captures and routes.
+- Write to the provider before the composed item is explicitly approved.
+- Recreate what exists — search first; duplicates get linked or updated.
+- Invent reporter, urgency, or behavior not present in the intake or observed.
+- Put secrets, tokens, or personal data beyond the reporter's name in a work item.
+
+## Done when
+
+- [ ] Intake classified with named evidence; duplicate search ran before composing.
+- [ ] Work item shown and explicitly approved before any provider write.
+- [ ] Work item created/updated with id shown in `workItemSyntax` — or degraded output
+      delivered and said so.
+- [ ] Next route offered, not auto-started.

package/skills/oris-flow/references/verify.md

@@ -41,6 +41,7 @@ Date: … | Source: acceptance-criteria.md | Verified by: oris-flow verify route
 
 ON fix → enter `skills/oris-flow/references/fix.md` with the failing AC as the bug report;
 re-verify the fixed criteria afterwards, as many fix-verify passes as the user approves.
+ON save with every AC Pass → also offer commit (`skills/oris-flow/references/commit.md`).
 
 ## Never