oris-skills 2.0.0 → 2.2.0

package/scripts/tests/test-oris-loop-run.mjs

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { buildRoleInvocation, doctorDecisionToState, extractJson } from "../loop/oris-loop-run.mjs";
+import { buildRoleInvocation, doctorDecisionToState, extractJson, verifierVerdictToState } from "../loop/oris-loop-run.mjs";
 import { readTemplate, stripTemplateHeading, substitutePlaceholders } from "../loop/oris-loop-templates.mjs";
 
 test("buildRoleInvocation maps roles to codex and claude CLI calls with per-role models", () => {
@@ -16,21 +16,47 @@ test("buildRoleInvocation maps roles to codex and claude CLI calls with per-role
   assert.ok(!inherit.args.includes("--model"), "inherit must not pass an explicit model");
 });
 
+test("readonly roles never get write access at the harness level", () => {
+  const claude = buildRoleInvocation("claude", { prompt: "check", model: "inherit", root: "/repo", readonly: true });
+  assert.ok(claude.args.includes("plan"), "claude readonly roles run in plan permission mode");
+  assert.ok(!claude.args.includes("acceptEdits"));
+
+  const codex = buildRoleInvocation("codex", { prompt: "check", model: "inherit", root: "/repo", readonly: true });
+  assert.ok(codex.args.includes("read-only"), "codex readonly roles run in the read-only sandbox");
+  assert.ok(!codex.args.includes("workspace-write"));
+});
+
 test("extractJson pulls the last valid JSON object from noisy output", () => {
   const output = 'thinking...\n{"broken": \nand then {"role":"doctor","decision":"complete"} trailing';
   assert.deepEqual(extractJson(output), { role: "doctor", decision: "complete" });
   assert.equal(extractJson("no json here"), null);
 });
 
-test("doctorDecisionToState maps decisions to loop states", () => {
+test("extractJson prefers the fenced json block over stray braces", () => {
+  const output = 'prose with {braces} everywhere\n```json\n{"role":"verifier","state":"pass","goalMet":true}\n```\nmore {noise}';
+  assert.deepEqual(extractJson(output), { role: "verifier", state: "pass", goalMet: true });
+});
+
+test("doctorDecisionToState maps the canonical decision enum to loop states", () => {
   assert.equal(doctorDecisionToState("complete"), "complete");
   assert.equal(doctorDecisionToState("continue"), "continue");
   assert.equal(doctorDecisionToState("retry"), "continue");
   assert.equal(doctorDecisionToState("advance"), "advance");
+  assert.equal(doctorDecisionToState("ask-user"), "ask-user", "ask-user must pause, never fail");
+  assert.equal(doctorDecisionToState("propose-patch"), "ask-user", "a proposed patch awaits approval");
   assert.equal(doctorDecisionToState("stop"), "blocked");
   assert.equal(doctorDecisionToState(undefined), "blocked");
 });
 
+test("verifierVerdictToState drives two-role loops without a doctor", () => {
+  assert.equal(verifierVerdictToState({ state: "pass", goalMet: true }), "complete");
+  assert.equal(verifierVerdictToState({ state: "pass", goalMet: false }), "continue");
+  assert.equal(verifierVerdictToState({ state: "fail" }), "continue");
+  assert.equal(verifierVerdictToState({ state: "blocked" }), "ask-user");
+  assert.equal(verifierVerdictToState({ state: "inconclusive" }), "ask-user");
+  assert.equal(verifierVerdictToState(null), "ask-user", "unparseable verifier output pauses the loop");
+});
+
 test("orchestrator template resolves from the skill templates and substitutes placeholders", () => {
   const template = readTemplate("orchestrator", import.meta.url);
   assert.match(template, /ORIS LOOP RUN/);

package/scripts/tests/test-oris-loop-smoke.mjs

@@ -27,7 +27,7 @@ test("same-chat verify passes on temporary repository", () => {
   assert.match(result.stdout, /Same-chat verification passed\./);
 });
 
-test("phase advance does not consume repair-cycle limit", () => {
+test("phase advance moves through declared phases", () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-loop-advance-"));
   try {
     const task = initSmokeRepository(root, {
@@ -36,7 +36,7 @@ test("phase advance does not consume repair-cycle limit", () => {
       phases: ["test", "fix", "clean"],
     });
     const chat = path.join(scriptsRoot, "oris-loop-chat.mjs");
-    const common = ["--repository-root", root, "--task", task.taskPath, "--max-repair-cycles", "2"];
+    const common = ["--repository-root", root, "--task", task.taskPath];
     const start = spawnSync(process.execPath, [chat, "--action", "start", ...common], { encoding: "utf8" });
     assert.equal(start.status, 0, `${start.stdout}\n${start.stderr}`);
 
@@ -45,6 +45,7 @@ test("phase advance does not consume repair-cycle limit", () => {
         chat,
         "--action", "set-state",
         "--state", "advance",
+        "--progress", "yes",
         "--repository-root", root,
       ], { encoding: "utf8" });
       assert.equal(advance.status, 0, `${advance.stdout}\n${advance.stderr}`);
@@ -53,13 +54,45 @@ test("phase advance does not consume repair-cycle limit", () => {
     const state = JSON.parse(fs.readFileSync(path.join(root, ORIS_FLOW_RUNTIME, "chat-active.json"), "utf8"));
     assert.equal(state.active, true);
     assert.equal(state.state, "advance");
-    assert.equal(state.repairCycles, 0);
+    assert.equal(state.noProgressStreak, 0);
+    assert.deepEqual(state.roles, ["executor", "verifier"]);
     assert.equal(state.phaseName, "clean");
   } finally {
     fs.rmSync(root, { recursive: true, force: true });
   }
 });
 
+test("no-progress passes force the loop to blocked", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-loop-noprog-"));
+  try {
+    const task = initSmokeRepository(root, {
+      taskSlug: "noprog-smoke",
+      program: "noprog-smoke",
+    });
+    const chat = path.join(scriptsRoot, "oris-loop-chat.mjs");
+    const start = spawnSync(process.execPath, [
+      chat, "--action", "start", "--repository-root", root, "--task", task.taskPath,
+    ], { encoding: "utf8" });
+    assert.equal(start.status, 0, `${start.stdout}\n${start.stderr}`);
+
+    // maxNoProgress is 2 in the smoke loop document.
+    for (let index = 0; index < 2; index += 1) {
+      const step = spawnSync(process.execPath, [
+        chat, "--action", "set-state", "--state", "continue", "--progress", "no", "--repository-root", root,
+      ], { encoding: "utf8" });
+      assert.equal(step.status, 0, `${step.stdout}\n${step.stderr}`);
+    }
+
+    const state = JSON.parse(fs.readFileSync(path.join(root, ORIS_FLOW_RUNTIME, "chat-active.json"), "utf8"));
+    assert.equal(state.state, "blocked");
+    assert.equal(state.active, false);
+    assert.equal(state.stopReason, "no-progress limit exhausted");
+    assert.equal(state.noProgressStreak, 2);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test("same-chat start accepts an existing loop slug", () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-loop-slug-"));
   try {

package/scripts/tests/test-oris-loop-stop.mjs

@@ -52,11 +52,12 @@ function activeState(overrides = {}) {
       doctor: "model-d",
       debriefer: "inherit",
     },
+    roles: ["executor", "verifier", "doctor"],
     conversationId: null,
     iteration: 0,
     maxIterations: 5,
-    repairCycles: 0,
-    maxRepairCycles: 2,
+    noProgressStreak: 0,
+    maxNoProgress: 2,
     maxMinutes: 30,
     startedAt: new Date().toISOString(),
     ...overrides,
@@ -91,13 +92,15 @@ test("cursor: claims the conversation and injects the orchestrator prompt", () =
     assert.match(message, /Definition: \.oris-flow\/loops\/sample\/loop\.md/);
     assert.match(message, /Prompts: \.oris-flow\/loops\/sample\/prompts/);
     assert.match(message, /executor=model-e verifier=model-v doctor=model-d debriefer=inherit/);
+    assert.match(message, /Active roles: executor, verifier, doctor/);
     assert.match(message, /Improve mode: auto/);
     assert.match(message, /ROLE: you are the orchestrator only/);
     assert.match(message, /SPAWN executor subagent/);
     assert.match(message, /SPAWN verifier subagent/);
     assert.match(message, /SPAWN doctor subagent/);
-    assert.match(message, /oris-skills loop chat --action set-state --state/);
-    assert.match(message, /ORIS_LOOP_STATE: continue \| advance \| complete \| blocked \| ask_user/);
+    assert.match(message, /npx oris-skills loop chat --action set-state --state/);
+    assert.match(message, /--progress <yes\|no>/);
+    assert.match(message, /ORIS_LOOP_STATE: <continue\|advance\|complete\|blocked\|ask-user>/);
     assert.doesNotMatch(message, /\{\{iteration\}\}/, "runtime placeholders must be substituted");
     assert.equal(result.state.conversationId, "c1");
     assert.equal(result.state.iteration, 1);
@@ -141,6 +144,23 @@ test("claude: platform is auto-detected from Stop payload", () => {
   }
 });
 
+test("cursor: auto-detected even when the payload also carries session_id", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-hook-"));
+  try {
+    // Real Cursor payloads include BOTH conversation_id and session_id.
+    const result = runHook(
+      root,
+      { conversation_id: "c9", session_id: "s9", status: "completed", loop_count: 0 },
+      activeState(),
+    );
+    assert.ok(result.output.followup_message, "must answer in Cursor format");
+    assert.equal(result.output.decision, undefined);
+    assert.equal(result.state.conversationId, "c9");
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test("per-loop prompts/orchestrator.md overrides the default template", () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-hook-"));
   try {
@@ -214,6 +234,47 @@ test("stops on terminal state and exhausted limits", () => {
     );
     assert.deepEqual(expired.output, {});
     assert.equal(expired.state.state, "blocked");
+
+    const stalled = runHook(
+      root,
+      { conversation_id: "c1", status: "completed", loop_count: 0 },
+      activeState({ conversationId: "c1", noProgressStreak: 2, maxNoProgress: 2 }),
+    );
+    assert.deepEqual(stalled.output, {});
+    assert.equal(stalled.state.state, "blocked");
+    assert.equal(stalled.state.stopReason, "no-progress limit exhausted");
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("claude: stopping on an exhausted limit tells the user via systemMessage", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-hook-"));
+  try {
+    const result = runHook(
+      root,
+      { session_id: "s1", hook_event_name: "Stop", stop_hook_active: false, cwd: root },
+      activeState({ conversationId: "s1", iteration: 5, maxIterations: 5 }),
+      ["--platform", "claude"],
+    );
+    assert.match(result.output.systemMessage, /iteration limit exhausted/);
+    assert.equal(result.output.decision, undefined, "must not block the chat");
+    assert.equal(result.state.state, "blocked");
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("ask-user pauses the loop: the hook does not resume it", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-hook-"));
+  try {
+    const result = runHook(
+      root,
+      { conversation_id: "c1", status: "completed", loop_count: 0 },
+      activeState({ state: "ask-user", conversationId: "c1" }),
+    );
+    assert.deepEqual(result.output, {});
+    assert.equal(result.state.state, "ask-user", "pause must not be rewritten");
   } finally {
     fs.rmSync(root, { recursive: true, force: true });
   }

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

@@ -28,7 +28,7 @@ function runCli(args, homeDir) {
 
 test("plugin manifest skills all exist and match front-matter names", () => {
   const manifest = JSON.parse(read(".cursor-plugin/plugin.json"));
-  assert.ok(manifest.skills.length >= 10);
+  assert.equal(manifest.skills.length, 1, "one user-facing skill");
   for (const entry of manifest.skills) {
     const relative = entry.replace(/^[.\\/]+/, "");
     const skillFile = path.join(relative, "SKILL.md");
@@ -40,8 +40,8 @@ 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\/[a-z-]+\/SKILL\.md)`/g)].map((match) => match[1]);
-  assert.ok(destinations.length >= 9, "route table must list at least 9 destinations");
+  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");
   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);
@@ -54,14 +54,13 @@ test("shared conventions centralize question, language, and gate rules", () => {
   assert.match(conventions, /ONE question per turn/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);
-  const questions = read("references/questions.md");
-  assert.match(questions, /`Explain the options`/);
-  assert.match(questions, /`Spiega le opzioni`/);
-  assert.match(questions, /`Basta domande — procedi`/);
-  assert.match(questions, /`Genera il documento`/);
-  assert.match(questions, /`Continua l'intervista`/);
-  assert.match(questions, /`Approva documento`/);
-  assert.match(questions, /`Annulla`/);
+  assert.match(conventions, /`Basta domande — procedi`/);
+  assert.match(conventions, /`Genera il documento`/);
+  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.equal(exists("references/questions.md"), false, "questions.md was merged into conventions.md");
 });
 
 test("every skill points at conventions instead of repeating shared rules", () => {
@@ -74,10 +73,10 @@ test("every skill points at conventions instead of repeating shared rules", () =
 });
 
 test("loop skill covers craft, demo, run, audit, improve and editable prompt files", () => {
-  const skill = read("skills/oris-loop/SKILL.md");
-  assert.match(skill, /references\/craft\.md/);
-  assert.match(skill, /references\/run\.md/);
-  assert.match(skill, /references\/improve\.md/);
+  const skill = read("skills/oris-flow/references/loop.md");
+  assert.match(skill, /references\/loop-craft\.md/);
+  assert.match(skill, /references\/loop-run\.md/);
+  assert.match(skill, /references\/loop-improve\.md/);
   assert.match(skill, /oris-skills loop demo/);
   assert.match(skill, /oris-skills loop dry-run/);
   assert.match(skill, /oris-skills loop list --json/);
@@ -85,10 +84,10 @@ test("loop skill covers craft, demo, run, audit, improve and editable prompt fil
   assert.match(skill, /improve\.mode: auto/);
   assert.match(skill, /Cursor|Claude Code|Codex/);
   for (const reference of ["craft", "run", "improve"]) {
-    assert.equal(exists(`skills/oris-loop/references/${reference}.md`), true, reference);
+    assert.equal(exists(`skills/oris-flow/references/loop-${reference}.md`), true, reference);
   }
   for (const template of ["orchestrator", "executor", "verifier", "doctor", "debriefer"]) {
-    assert.equal(exists(`skills/oris-loop/templates/${template}.md`), true, template);
+    assert.equal(exists(`skills/oris-flow/templates/${template}.md`), true, template);
   }
 });
 
@@ -100,23 +99,26 @@ test("loop contract stays subagent-first with per-role editable prompts", () =>
   assert.match(contract, /improve/);
   assert.match(contract, /inherit/);
   assert.match(contract, /NEVER success/i);
-  const run = read("skills/oris-loop/references/run.md");
+  const run = read("skills/oris-flow/references/loop-run.md");
   assert.match(run, /oris-skills loop chat --action start --loop <slug>/);
   assert.match(run, /NEVER do executor\/verifier\/doctor work in the main chat/i);
   assert.match(run, /set-state blocked/);
   assert.match(run, /oris-skills loop run --loop <slug> --agent codex\|claude/);
-  const craft = read("skills/oris-loop/references/craft.md");
-  assert.match(craft, /skills\/oris-loop\/templates\//);
+  const craft = read("skills/oris-flow/references/loop-craft.md");
+  assert.match(craft, /skills\/oris-flow\/templates\//);
   assert.match(craft, /write the loop \| edit verifier \| edit executor \| edit doctor/);
-  for (const text of [contract, run, craft, read("skills/oris-loop/SKILL.md")]) {
+  assert.match(contract, /ORIS LOOP ACTIVE/, "the contract defines the executor gate literal");
+  for (const text of [contract, run, craft, read("skills/oris-flow/references/loop.md")]) {
     assert.doesNotMatch(text, /node scripts\/(?:flow|loop)\//);
     assert.doesNotMatch(text, /composer-2\.5/);
-    assert.doesNotMatch(text, /ORIS LOOP ACTIVE/);
+  }
+  for (const text of [run, craft, read("skills/oris-flow/references/loop.md")]) {
+    assert.doesNotMatch(text, /ORIS LOOP ACTIVE/, "the gate literal lives in the contract and executor prompts only");
   }
 });
 
 test("setup and repo-map keep the installed CLI as the command surface", () => {
-  const setup = read("skills/oris-flow-setup/SKILL.md");
+  const setup = read("skills/oris-flow/references/setup.md");
   assert.match(setup, /oris-skills flow scan --repository-root <repo> --json/);
   assert.match(setup, /oris-skills loop bootstrap --repository-root <repo>/);
   assert.match(setup, /oris-skills flow clean-runtime --repository-root <repo> --dry-run/);
@@ -179,3 +181,16 @@ test("CLI exposes install, loop learnability, and flow helper commands", () => {
     fs.rmSync(homeDir, { recursive: true, force: true });
   }
 });
+
+test("copilot install is planned alongside the universal pointer", () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "oris-copilot-"));
+  try {
+    const result = runCli(["install", "--dry-run", "--agents", "copilot"], homeDir);
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stdout, /Copilot prompts/);
+    assert.match(result.stdout, /universal pointer/);
+    assert.match(result.stdout, /oris-flow\.md/);
+  } finally {
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+// The Oris skill style, enforced: front matter that routes, leading-word moves,
+// an explicit Never block, a Done when checklist, and a hard line budget.
+// One user-facing skill exists; every route is one of its references.
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+const skillsRoot = path.join(repoRoot, "skills");
+const MAX_LINES = 110;
+
+const skillDirs = fs.readdirSync(skillsRoot, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory())
+  .map((entry) => entry.name);
+
+function resolveHandles(text, label, localRoot) {
+  for (const match of text.matchAll(/`(?:~\/\.oris\/oris-skills\/)?((?:skills|references)\/[A-Za-z0-9/._-]+\.md)`/g)) {
+    const target = path.join(repoRoot, match[1]);
+    const local = path.join(localRoot, match[1]);
+    assert.ok(fs.existsSync(target) || fs.existsSync(local), `${label}: routing handle resolves: ${match[1]}`);
+  }
+}
+
+test("exactly one user-facing skill: oris-flow", () => {
+  assert.deepEqual(skillDirs, ["oris-flow"], "users see one skill; routes are its references");
+  assert.ok(fs.existsSync(path.join(skillsRoot, "oris-flow", "SKILL.md")));
+});
+
+test("skill style: oris-flow", () => {
+  const text = fs.readFileSync(path.join(skillsRoot, "oris-flow", "SKILL.md"), "utf8");
+  const front = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  assert.ok(front, "has front matter");
+  assert.match(front[1], /^name: oris-flow$/m, "front matter name matches the folder");
+  const description = front[1].match(/^description: (.+)$/m)?.[1];
+  assert.ok(description, "front matter has description");
+  assert.match(description, /Use for/, "description names its triggers");
+  assert.doesNotMatch(front[1], /disable-model-invocation/, "the single entry point must stay model-invocable");
+  assert.ok(text.includes("## Never"), "carries an explicit Never block");
+  assert.ok(text.includes("## Done when"), "ends with a Done when checklist");
+  const lines = text.split(/\r?\n/).length;
+  assert.ok(lines <= MAX_LINES, `SKILL.md is ${lines} lines (max ${MAX_LINES}) — move detail to references/`);
+  resolveHandles(text, "SKILL.md", path.join(skillsRoot, "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})`);
+  assert.deepEqual(routes, [...new Set(routes)], "route destinations are unique");
+  const referencesDir = path.join(skillsRoot, "oris-flow", "references");
+  for (const file of routes) {
+    const text = fs.readFileSync(path.join(referencesDir, file), "utf8");
+    assert.doesNotMatch(text, /^---\r?\n/, `${file}: references carry no front matter`);
+    assert.ok(text.includes("## Never"), `${file}: carries an explicit Never block`);
+    assert.ok(text.includes("## Done when"), `${file}: ends with a Done when checklist`);
+  }
+  for (const file of fs.readdirSync(referencesDir)) {
+    const text = fs.readFileSync(path.join(referencesDir, file), "utf8");
+    resolveHandles(text, file, path.join(skillsRoot, "oris-flow"));
+  }
+});

package/skills/oris-flow/SKILL.md

@@ -1,55 +1,83 @@
 ---
 name: oris-flow
-description: Oris entry point. Use when the user types /oris-flow, picks from its menu, or describes any software-flow goal (analyze, define criteria, plan, implement, fix, loop, docs). Routes to the right Oris skill in the same chat.
+description: The one Oris skill - read the intent, pick ONE route, apply it in the same chat. Use for /oris-flow and whenever the user wants to set up a repo for agents, start a project, understand or define behavior, write acceptance criteria, plan, implement, fix a bug, verify criteria, handle a spec change, run a work loop (fix until green, repeat until verified), review architecture, update task docs, or asks how Oris works.
 ---
 
-# Oris Flow — Entry Point
+# Oris Flow — the router
 
-The only command users must remember. READ the intent, ROUTE to one skill, ENTER it in the same chat.
+The only skill users see. READ the intent, PICK one route, say one line
+("Entering <route>: <why>"), then READ the route's reference file and APPLY it top to
+bottom in the same chat — its Never and Done when bind the whole route.
+NEVER tell the user to type another command; NEVER narrate the reading
+(`references/conventions.md` `## Silence`).
 
-RULES: follow `references/conventions.md`. This router NEVER writes documents, code, Git, or DevOps — the destination skill owns its own gates.
+RULES: `references/conventions.md`. This router NEVER writes documents, code, Git, or
+DevOps — the route's own reference owns its gates.
 
 ## Route
 
-Match the desired outcome to ONE route:
+Match the desired outcome to ONE route, then apply its reference:
 
-| Route | When the user wants… | Enter |
+| Route | When the user wants… | Apply |
 |-------|----------------------|-------|
-| setup | prepare / map / refresh the repo for Oris | `skills/oris-flow-setup/SKILL.md` |
-| discover | understand or define product behavior | `skills/oris-flow-discover/SKILL.md` |
-| criteria | acceptance criteria / QA checks | `skills/oris-flow-criteria/SKILL.md` |
-| plan | a technical implementation plan | `skills/oris-flow-plan/SKILL.md` |
-| implement | build from a plan or confirmed scope | `skills/oris-flow-implement/SKILL.md` |
-| fix | fix a bug or regression | `skills/oris-flow-fix/SKILL.md` |
-| loop | repeat work until verified (design, demo, run, tune) | `skills/oris-loop/SKILL.md` |
-| docs | update task docs after a change | `skills/oris-flow-docs/SKILL.md` |
-| help | how Oris works, install, troubleshooting | `skills/oris-help/SKILL.md` |
-
-ROUTING:
-1. IF intent is clear → say one line ("Entering <route>: <why>"), then READ and APPLY the destination skill immediately. NEVER tell the user to type another command.
-2. IF intent is unclear → ask ONE menu question (below).
-3. IF the user wants to analyze, rethink, or change an existing plan → route to the interview owner (discover / plan / loop), NEVER straight to implement.
-4. IF `.oris-flow/manifest.json` is missing → recommend setup first; respect the user's choice.
-5. Destination skills marked `disable-model-invocation` may still be entered from here — that flag only blocks unsolicited invocation from generic chat.
+| 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` |
+| 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` |
+| implement | build from a plan or confirmed scope | `skills/oris-flow/references/implement.md` |
+| fix | broken behavior, a regression, a failed QA check | `skills/oris-flow/references/fix.md` |
+| verify | check acceptance criteria against the real product, once | `skills/oris-flow/references/verify.md` |
+| change | the spec changed — update analysis, criteria, plan, and history together | `skills/oris-flow/references/change.md` |
+| loop | repeat work until verified — fix until green, step through a plan | `skills/oris-flow/references/loop.md` |
+| architecture | review architecture, find deepening/refactor opportunities | `skills/oris-flow/references/architecture.md` |
+| docs | update task docs after a change | `skills/oris-flow/references/docs.md` |
+| help | how Oris works, install, update, troubleshooting | `skills/oris-flow/references/help.md` |
+
+## Precedence (the calls that look ambiguous)
+
+1. INTENT clear → enter the route NOW. Unclear → ONE menu question (below); NEVER guess
+   between two routes and never ask twice.
+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.
+5. CHECK once → verify. Repeat-until-verified → loop.
+6. EMPTY directory or from-scratch intent → new. Existing repo without
+   `.oris-flow/manifest.json` → recommend setup first; respect the user's choice.
 
 ## Menu (low confidence)
 
 ASK "What do you want to do?" localized to `uiLanguage`, 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
 - Loop: repeat until verified
+- Architecture review
 - Update docs
 - Help
 - Explain the options / Spiega le opzioni
 
-IF "Implement or fix" → one follow-up: new planned work (implement) or broken behavior (fix)?
 IF "Explain the options" → explain briefly, re-ask the same question.
+Every other label maps 1:1 to its route in the table above.
+
+## Never
+
+- Force a route onto a plain question — no flow intent means no menu: just answer.
+- 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.
 
 ## Done when
 
-- [ ] One route entered in the same chat, or the menu was asked.
-- [ ] No writes happened before the destination skill's own gate.
+- [ ] One route entered and applied in the same chat, or the menu was asked exactly once.
+- [ ] No writes happened before the route's own gate.

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

@@ -0,0 +1,77 @@
+# Architecture Review
+
+Surface architectural friction and propose deepening opportunities — refactors that turn
+shallow modules into deep ones. The aim is testability and AI-navigability.
+
+RULES: `references/conventions.md`. Output is a report + an interview; implementation
+routes to plan/implement.
+
+## Vocabulary (use these words exactly)
+
+- **module** — a unit with an interface and an implementation. Never "component",
+  "service", "layer".
+- **interface** — what callers must know. Never "API", "signature".
+- **deep / shallow** — deep: small interface, big implementation. Shallow: interface
+  nearly as complex as the implementation.
+- **seam** — where two modules meet. Never "boundary". One adapter = hypothetical seam;
+  two = real.
+- **locality** — bugs concentrate where the behavior lives; **leverage** — one interface
+  serves N call sites.
+- **deletion test** — would deleting the module concentrate complexity (good signal) or
+  just move it?
+
+## 1. Explore
+
+1. READ first: setup map, `CONTEXT.md` (domain names for good seams), `docs/adr/`
+   (decisions NOT to re-litigate).
+2. WALK the codebase with parallel subagents. No rigid heuristics — note real friction:
+   - understanding one concept requires bouncing between many small modules;
+   - shallow modules (deletion test says "concentrates");
+   - pure functions extracted for testability while the bugs hide in how they're called;
+   - tight coupling leaking across seams;
+   - untested code, or code untestable through its current interface.
+
+## 2. Report (HTML, outside the repo)
+
+WRITE a self-contained HTML file to the OS temp dir (`architecture-review-<timestamp>.html`),
+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`;
+- 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;
+- wins as bullets ≤6 words, glossary terms only — never "cleaner code";
+- ADR conflict → amber callout ("contradicts ADR-0007 — worth reopening because…").
+
+END with Top recommendation: one candidate, one sentence why.
+ASK: "Which of these would you like to explore?" — DO NOT propose interfaces yet.
+
+## 3. Walk the picked candidate
+
+INTERVIEW per conventions (one question per turn, recommended answer first):
+constraints, dependencies, the shape of the deepened module, what sits behind the seam,
+which tests survive.
+
+SIDE EFFECTS as decisions crystallize:
+- new concept named → add the term to `CONTEXT.md` (create lazily);
+- fuzzy term sharpened → update `CONTEXT.md` in place;
+- candidate rejected for a load-bearing reason → offer an ADR so future reviews don't
+  re-suggest it (skip ephemeral reasons).
+
+AFTER: offer technical plan for the deepening (`skills/oris-flow/references/plan.md`) |
+explore another candidate | stop.
+
+## Never
+
+- Edit product code — the deepening routes to plan, then implement.
+- Use non-glossary words: component, service, layer, boundary, "cleaner code".
+- Re-litigate an ADR silently — surface the conflict, let the user reopen it.
+- Write the report inside the repo.
+
+## Done when
+
+- [ ] CONTEXT.md and ADRs read before exploring; no ADR re-litigated silently.
+- [ ] Report written to temp (repo untouched), opened, path shown.
+- [ ] Glossary terms used exactly; wins named in locality/leverage terms.
+- [ ] Implementation routed to plan, not started here.