oris-skills 2.1.0 → 2.2.0

package/scripts/install/install-user-skills.mjs

@@ -8,9 +8,12 @@
  * - Cursor skills:      ~/.cursor/skills/<name>/
  * - Claude Code skills: ~/.claude/skills/<name>/
  * - Codex prompts:      ~/.codex/prompts/<name>.md (pointer to the bundled SKILL.md)
+ * - Copilot prompts:    VS Code user prompts dir /<name>.prompt.md (same pointer)
+ * - Any other agent:    ~/.oris/oris-flow.md — a universal pointer any file-reading
+ *   agent can be told to follow.
  *
  * Agents are auto-detected from existing home directories; override with
- * --agents cursor,claude,codex.
+ * --agents cursor,claude,codex,copilot.
  */
 
 import childProcess from "node:child_process";
@@ -24,7 +27,14 @@ import { writeAgentAdapters } from "./generate-agent-adapters.mjs";
 const markerName = ".oris-skills-managed.json";
 const installManifestName = ".oris-skills-install.json";
 const nodeDownloadUrl = "https://nodejs.org/en/download";
-const KNOWN_AGENTS = ["cursor", "claude", "codex"];
+const KNOWN_AGENTS = ["cursor", "claude", "codex", "copilot"];
+
+/** VS Code user dir — where Copilot Chat reads user prompt files (chat.promptFiles). */
+function vscodeUserDir(home) {
+  if (process.platform === "win32") return path.join(home, "AppData", "Roaming", "Code", "User");
+  if (process.platform === "darwin") return path.join(home, "Library", "Application Support", "Code", "User");
+  return path.join(home, ".config", "Code", "User");
+}
 
 function fail(message) {
   throw new Error(message);
@@ -43,6 +53,7 @@ function defaultPaths() {
       cursor: path.join(home, ".cursor"),
       claude: path.join(home, ".claude"),
       codex: path.join(home, ".codex"),
+      copilot: vscodeUserDir(home),
     },
   };
 }
@@ -75,6 +86,7 @@ function parseArgs(argv) {
     else if (key === "--cursor-root" || key.startsWith("--cursor-root=")) options.agentRoots.cursor = value();
     else if (key === "--claude-root" || key.startsWith("--claude-root=")) options.agentRoots.claude = value();
     else if (key === "--codex-root" || key.startsWith("--codex-root=")) options.agentRoots.codex = value();
+    else if (key === "--copilot-root" || key.startsWith("--copilot-root=")) options.agentRoots.copilot = value();
     else fail(`Unknown argument: ${raw}`);
   }
   for (const agent of options.agents) {
@@ -155,6 +167,7 @@ function defaultSettings() {
     orisFlow: {
       uiLanguage: "en",
       artifactLanguage: "en",
+      responseStyle: "standard",
     },
     defaultProfiles: {
       testing: "default",
@@ -205,6 +218,39 @@ User request: $ARGUMENTS
   }
 }
 
+/** Copilot Chat user prompt files: /<name> in chat once chat.promptFiles is enabled. */
+function installCopilotPrompts(skills, vscodeUserRoot, bundleRoot) {
+  const promptsRoot = path.join(vscodeUserRoot, "prompts");
+  fs.mkdirSync(promptsRoot, { recursive: true });
+  for (const skill of skills) {
+    const bundledSkill = path.join(bundleRoot, skill.relativePath, "SKILL.md").replace(/\\/g, "/");
+    const description = skillDescription(skill.sourceDir);
+    fs.writeFileSync(path.join(promptsRoot, `${skill.name}.prompt.md`), `---
+description: ${description || "Oris entry point"}
+---
+<!-- ${markerName} -->
+Read the Oris skill file at \`${bundledSkill}\` and follow it exactly.
+Then handle the user's request in this conversation.
+`, "utf8");
+  }
+}
+
+/** Universal pointer for any file-reading agent that has no install target of its own. */
+function installUniversalPointer(skills, bundleRoot) {
+  const primary = skills[0];
+  const bundledSkill = path.join(bundleRoot, primary.relativePath, "SKILL.md").replace(/\\/g, "/");
+  fs.writeFileSync(path.join(path.dirname(bundleRoot), "oris-flow.md"), `<!-- ${markerName} -->
+# Oris — universal entry point
+
+Tell any agent that can read files:
+
+> Read \`${bundledSkill}\` and follow it exactly.
+
+That file routes every Oris flow (setup, discover, criteria, plan, implement, fix,
+verify, change, loop, architecture, docs, help) in the same chat.
+`, "utf8");
+}
+
 function main() {
   requireNode();
   const options = parseArgs(process.argv.slice(2));
@@ -225,9 +271,11 @@ function main() {
     log(`Would write bundle: ${options.bundleRoot}`);
     for (const agent of agents) {
       if (agent === "codex") log(`Would write Codex prompts: ${path.join(options.agentRoots.codex, "prompts")}`);
+      else if (agent === "copilot") log(`Would write Copilot prompts: ${path.join(options.agentRoots.copilot, "prompts")}`);
       else log(`Would write ${agent} skills: ${path.join(options.agentRoots[agent], "skills")}`);
-      log(`Would write ${agent} loop agents: ${path.join(options.agentRoots[agent], "agents")}`);
+      if (agent !== "copilot") log(`Would write ${agent} loop agents: ${path.join(options.agentRoots[agent], "agents")}`);
     }
+    log(`Would write universal pointer: ${path.join(path.dirname(options.bundleRoot), "oris-flow.md")}`);
     log(`Would create settings if missing: ${options.settingsPath}`);
     return;
   }
@@ -247,13 +295,17 @@ function main() {
     if (agent === "codex") {
       installCodexPrompts(skills, options.agentRoots.codex, options.bundleRoot);
       log(`Installed ${skills.length} Codex prompts`);
+    } else if (agent === "copilot") {
+      installCopilotPrompts(skills, options.agentRoots.copilot, options.bundleRoot);
+      log(`Installed ${skills.length} Copilot prompts (enable VS Code setting chat.promptFiles)`);
     } else {
       installSkillDirs(skills, path.join(options.agentRoots[agent], "skills"), manifest, options.bundleRoot, options);
       log(`Installed ${skills.length} ${agent} skills`);
     }
   }
+  installUniversalPointer(skills, options.bundleRoot);
 
-  const adapterTargets = Object.fromEntries(agents.map((agent) => [agent, options.agentRoots[agent]]));
+  const adapterTargets = Object.fromEntries(agents.filter((agent) => agent !== "copilot").map((agent) => [agent, options.agentRoots[agent]]));
   const loopAgents = writeAgentAdapters(adapterTargets);
   log(`Installed ${loopAgents.length} loop agent adapters (${agents.join(", ")})`);
 

package/scripts/install/uninstall-user-skills.mjs

@@ -28,6 +28,11 @@ function parseArgs(argv) {
     cursorRoot: path.join(home, ".cursor"),
     claudeRoot: path.join(home, ".claude"),
     codexRoot: path.join(home, ".codex"),
+    copilotRoot: process.platform === "win32"
+      ? path.join(home, "AppData", "Roaming", "Code", "User")
+      : process.platform === "darwin"
+        ? path.join(home, "Library", "Application Support", "Code", "User")
+        : path.join(home, ".config", "Code", "User"),
   };
   for (let i = 0; i < argv.length; i += 1) {
     const raw = argv[i];
@@ -44,6 +49,7 @@ function parseArgs(argv) {
     else if (key === "--cursor-root" || key.startsWith("--cursor-root=")) options.cursorRoot = value();
     else if (key === "--claude-root" || key.startsWith("--claude-root=")) options.claudeRoot = value();
     else if (key === "--codex-root" || key.startsWith("--codex-root=")) options.codexRoot = value();
+    else if (key === "--copilot-root" || key.startsWith("--copilot-root=")) options.copilotRoot = value();
     else fail(`Unknown argument: ${raw}`);
   }
   return options;
@@ -86,6 +92,14 @@ function managedCodexPrompts(codexRoot) {
     .map((entry) => path.join(promptsRoot, entry.name));
 }
 
+function managedCopilotPrompts(copilotRoot) {
+  const promptsRoot = path.join(copilotRoot, "prompts");
+  if (!fs.existsSync(promptsRoot)) return [];
+  return fs.readdirSync(promptsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.toLowerCase().startsWith("oris-") && entry.name.endsWith(".prompt.md"))
+    .map((entry) => path.join(promptsRoot, entry.name));
+}
+
 function legacyOrisPaths(options) {
   return [
     path.join(options.cursorRoot, "oris-skills"),
@@ -104,6 +118,8 @@ function plannedRemovals(options) {
     ...managedSkillDirs(path.join(options.cursorRoot, "skills")),
     ...managedSkillDirs(path.join(options.claudeRoot, "skills")),
     ...managedCodexPrompts(options.codexRoot),
+    ...managedCopilotPrompts(options.copilotRoot),
+    path.join(path.dirname(options.bundleRoot), "oris-flow.md"),
     ...legacyOrisPaths(options),
   ]);
   return [...paths].map((target) => path.resolve(target)).filter(safeOrisPath).sort();
@@ -125,7 +141,7 @@ function removeOrisMcpServers(userMcpPath, dryRun) {
 
 export function uninstallUserSkills(rawArgs = []) {
   const options = parseArgs(rawArgs);
-  for (const target of [options.bundleRoot, options.settingsPath, options.cursorRoot, options.claudeRoot, options.codexRoot]) {
+  for (const target of [options.bundleRoot, options.settingsPath, options.cursorRoot, options.claudeRoot, options.codexRoot, options.copilotRoot]) {
     assertInsideHome(target);
   }
 

package/scripts/loop/oris-loop-chat.mjs

@@ -40,7 +40,7 @@ function parseArgs(argv) {
     progress: "",
     repositoryRoot: "",
     runner: "chat",
-    maxIterations: 25,
+    maxIterations: 10,
     maxMinutes: 240,
     profile: "",
     settingsPath: ORIS_SKILLS_SETTINGS,
@@ -285,7 +285,7 @@ if (options.action === "start") {
   }
   const prompts = assessPromptFiles(path.dirname(loopPath), activeRoles(loopDocument.data));
   if (prompts.missing.length > 0) {
-    fail(`Loop prompt files are missing or empty: ${prompts.missing.join(", ")}. Craft or copy them from skills/oris-loop/templates/.`);
+    fail(`Loop prompt files are missing or empty: ${prompts.missing.join(", ")}. Craft or copy them from skills/oris-flow/templates/.`);
   }
   if (fs.existsSync(statePath)) {
     const existing = normalizeChatState(JSON.parse(fs.readFileSync(statePath, "utf8")));

package/scripts/loop/oris-loop-dry-run.mjs

@@ -108,7 +108,7 @@ console.log(followup);
 console.log("=== End of injected message ===");
 console.log("");
 if (prompts.missing.length > 0) {
-  console.log("NOT runnable yet — create the missing prompt files first (templates: skills/oris-loop/templates/).");
+  console.log("NOT runnable yet — create the missing prompt files first (templates: skills/oris-flow/templates/).");
   process.exit(1);
 }
 console.log(`Runnable. Start it with: npx oris-skills loop chat --action start --loop ${metadata.name}`);

package/scripts/loop/oris-loop-fixtures.mjs

@@ -40,7 +40,7 @@ approved: true
 phases: [${phases.join(", ")}]
 roles: [${roles.join(", ")}]
 limits:
-  maxIterations: 25
+  maxIterations: 10
   maxNoProgress: 2
   maxMinutes: 240
 ${modelLines.join("\n")}

package/scripts/loop/oris-loop-templates.mjs

@@ -3,7 +3,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 /**
- * Prompt templates live in skills/oris-loop/templates/*.md so users and
+ * Prompt templates live in skills/oris-flow/templates/*.md so users and
  * agents can read and copy them. Scripts fall back to an embedded
  * orchestrator prompt so the stop hook can never fail on a missing file.
  */
@@ -47,8 +47,8 @@ IF prompt files are missing or subagents cannot be spawned: \`set-state --state
 export function resolveTemplatesDir(fromImportMetaUrl) {
   const scriptsLoop = path.dirname(fileURLToPath(fromImportMetaUrl));
   const candidates = [
-    path.resolve(scriptsLoop, "..", "..", "skills", "oris-loop", "templates"),
-    path.resolve(scriptsLoop, "..", "skills", "oris-loop", "templates"),
+    path.resolve(scriptsLoop, "..", "..", "skills", "oris-flow", "templates"),
+    path.resolve(scriptsLoop, "..", "skills", "oris-flow", "templates"),
   ];
   for (const candidate of candidates) {
     if (fs.existsSync(path.join(candidate, "orchestrator.md"))) return candidate;

package/scripts/oris-skills.mjs

@@ -32,7 +32,7 @@ function printHelp() {
   console.log(`Oris Skills
 
 Install for your agents (Cursor, Claude Code, Codex):
-  oris-skills install [--agents cursor,claude,codex] [--dry-run]
+  oris-skills install [--agents cursor,claude,codex,copilot] [--dry-run]
   oris-skills uninstall [--dry-run]
   oris-skills reinstall [--dry-run]
 

package/scripts/tests/run-all-tests.mjs

@@ -14,6 +14,7 @@ const nodeTestFiles = [
   "scripts/tests/test-oris-1-0-cleanliness.mjs",
   "scripts/tests/test-oris-flow-scan.mjs",
   "scripts/tests/test-routing-lifecycle.mjs",
+  "scripts/tests/test-skill-style.mjs",
   "scripts/tests/test-oris-loop-stop.mjs",
   "scripts/tests/test-oris-loop-smoke.mjs",
   "scripts/tests/test-oris-loop-bootstrap.mjs",

package/scripts/tests/test-oris-flow-scan.mjs

@@ -3,7 +3,8 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
-import { scanRepository, writeScanResult } from "../flow/oris-flow-scan.mjs";
+import childProcess from "node:child_process";
+import { checkFreshness, scanRepository, writeScanResult } from "../flow/oris-flow-scan.mjs";
 import { ORIS_FLOW_MANIFEST } from "../flow/oris-flow-layout.mjs";
 
 function write(filePath, content) {
@@ -113,3 +114,44 @@ test("confirmed section without fresh evidence is marked stale, not deleted", ()
   }
 });
 
+
+test("scan anchors the map to HEAD; --check answers freshness from the SHA + changed files", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-flow-scan-"));
+  const git = (...args) => childProcess.execFileSync("git", args, { cwd: root, encoding: "utf8" });
+  try {
+    write(path.join(root, "README.md"), "# Demo\n");
+    write(path.join(root, "package.json"), `${JSON.stringify({ scripts: { test: "node --test" } })}\n`);
+    git("init", "-q");
+    git("-c", "user.email=t@t", "-c", "user.name=t", "add", ".");
+    git("-c", "user.email=t@t", "-c", "user.name=t", "commit", "-q", "-m", "init");
+
+    const scan = scanRepository(root);
+    assert.equal(typeof scan.manifest.headSha, "string", "scan records the HEAD anchor");
+    writeScanResult(scan);
+
+    const fresh = checkFreshness(root);
+    assert.equal(fresh.fresh, true, "same SHA + clean tree → fresh, zero reads");
+    assert.deepEqual(fresh.changedFiles, []);
+
+    write(path.join(root, "src", "new.js"), "export const later = 1;\n");
+    const stale = checkFreshness(root);
+    assert.equal(stale.fresh, false, "working-tree change → stale");
+    assert.ok(stale.changedFiles.some((file) => file.includes("new.js")), "changed files name the delta");
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("outside git the map still works — no anchor, never an error", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-flow-scan-"));
+  try {
+    write(path.join(root, "README.md"), "# Demo\n");
+    const scan = scanRepository(root);
+    assert.equal(scan.manifest.headSha, null);
+    writeScanResult(scan);
+    const check = checkFreshness(root);
+    assert.equal(check.fresh, false, "no anchor → refresh advised, not an error");
+  } 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);
@@ -73,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/);
@@ -84,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);
   }
 });
 
@@ -99,26 +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/);
   assert.match(contract, /ORIS LOOP ACTIVE/, "the contract defines the executor gate literal");
-  for (const text of [contract, run, craft, read("skills/oris-loop/SKILL.md")]) {
+  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/);
   }
-  for (const text of [run, craft, read("skills/oris-loop/SKILL.md")]) {
+  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/);
@@ -181,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,43 +1,52 @@
 ---
 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` |
-| new | bootstrap a new AI-driven project from scratch | `skills/oris-flow-new/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` |
-| verify | check acceptance criteria against the real product, once | `skills/oris-flow-verify/SKILL.md` |
-| change | the spec changed — update analysis, criteria, plan, and history together | `skills/oris-flow-change/SKILL.md` |
-| loop | repeat work until verified (design, demo, run, tune) | `skills/oris-loop/SKILL.md` |
-| architecture | review architecture, find deepening/refactor opportunities | `skills/oris-flow-architecture/SKILL.md` |
-| merge | resolve an in-progress merge/rebase conflict | `skills/oris-flow-merge/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 / change), NEVER straight to implement.
-4. IF requirements changed on a feature that already has task docs or code → change, not discover (change owns the delta + history).
-5. IF `.oris-flow/manifest.json` is missing → recommend setup first; respect the user's choice.
-   IF the target directory is empty or the user starts a project from scratch → new, not setup.
-6. 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)
 
@@ -53,16 +62,22 @@ ASK "What do you want to do?" localized to `uiLanguage`, options:
 - Spec changed: update feature docs
 - Loop: repeat until verified
 - Architecture review
-- Resolve merge conflicts
 - 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.