oris-skills 2.0.0 → 2.2.0

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

@@ -1,5 +1,6 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
+import childProcess from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
@@ -9,12 +10,14 @@ import {
   ORIS_FLOW_MAP_SCHEMA,
   ORIS_FLOW_MAP_SCHEMA_VERSION,
   ORIS_FLOW_MAPS_ROOT,
+  ORIS_FLOW_TASKS_ROOT,
   relativeToRepository,
   resolveInsideRepository,
   toPosixPath,
 } from "./oris-flow-layout.mjs";
 
 const ignoredDirectories = new Set([
+  ".oris-flow",
   ".git",
   ".hg",
   ".svn",
@@ -40,9 +43,17 @@ const stackDetectors = [
   { id: "java", label: "Java", match: (file) => ["pom.xml", "build.gradle", "build.gradle.kts"].includes(file.name) },
   { id: "go", label: "Go", match: (file) => file.name === "go.mod" },
   { id: "rust", label: "Rust", match: (file) => file.name === "Cargo.toml" },
+  { id: "php", label: "PHP", match: (file) => file.name === "composer.json" },
+  { id: "ruby", label: "Ruby", match: (file) => file.name === "Gemfile" },
+  { id: "make", label: "Make", match: (file) => file.name === "Makefile" },
   { id: "playwright", label: "Playwright", match: (file) => /^playwright\.config\.(ts|js|mjs|cjs)$/i.test(file.name) },
   { id: "vitest", label: "Vitest", match: (file) => /^vitest\.config\.(ts|js|mjs|cjs)$/i.test(file.name) },
   { id: "jest", label: "Jest", match: (file) => /^jest\.config\.(ts|js|mjs|cjs)$/i.test(file.name) || file.name === "jest.config.json" },
+  { id: "vite", label: "Vite", match: (file) => /^vite\.config\.(ts|js|mjs|cjs)$/i.test(file.name) },
+  { id: "next", label: "Next.js", match: (file) => /^next\.config\.(ts|js|mjs|cjs)$/i.test(file.name) },
+  { id: "angular", label: "Angular", match: (file) => file.name === "angular.json" },
+  { id: "nx", label: "Nx", match: (file) => file.name === "nx.json" },
+  { id: "turborepo", label: "Turborepo", match: (file) => file.name === "turbo.json" },
   { id: "docker", label: "Docker", match: (file) => file.name === "Dockerfile" || file.name === "docker-compose.yml" || file.name === "compose.yaml" },
   { id: "azure-pipelines", label: "Azure Pipelines", match: (file) => /^azure-pipelines.*\.ya?ml$/i.test(file.name) },
   { id: "github-actions", label: "GitHub Actions", match: (file) => file.relative.startsWith(".github/workflows/") && /\.ya?ml$/i.test(file.name) },
@@ -53,6 +64,68 @@ function fail(message) {
   process.exit(1);
 }
 
+function git(root, args) {
+  try {
+    const output = childProcess.execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return output.trim();
+  } catch {
+    return null;
+  }
+}
+
+/** Commit SHA the scan anchors to; null outside git (the anchor is then unavailable, never an error). */
+export function gitHeadSha(root) {
+  return git(root, ["rev-parse", "HEAD"]);
+}
+
+/**
+ * Files changed since the anchored SHA: committed delta + working-tree changes,
+ * deduped. The map's own files (.oris-flow/**) never count — they describe the
+ * code, they are not the code.
+ */
+export function gitChangedFiles(root, sinceSha) {
+  const diff = git(root, ["diff", "--name-only", `${sinceSha}..HEAD`]);
+  const status = git(root, ["status", "--porcelain", "-uall"]);
+  if (diff === null && status === null) return null;
+  const changed = new Set();
+  const add = (file) => {
+    const clean = file.replace(/^"|"$/g, "");
+    if (clean && !clean.startsWith(".oris-flow/")) changed.add(clean);
+  };
+  for (const line of (diff ?? "").split(/\r?\n/)) if (line.trim()) add(line.trim());
+  for (const line of (status ?? "").split(/\r?\n/)) {
+    const file = line.slice(3).trim();
+    if (file) add(file.includes(" -> ") ? file.split(" -> ")[1] : file);
+  }
+  return [...changed].sort();
+}
+
+/**
+ * Freshness in one cheap call (the delta-scan anchor): compare the manifest's
+ * headSha with the current HEAD. Equal and clean → fresh, zero reads. Moved →
+ * the changed file list tells the caller which map areas to refresh in place.
+ */
+export function checkFreshness(repositoryRoot) {
+  const root = path.resolve(repositoryRoot);
+  const manifest = readJson(path.join(root, ...ORIS_FLOW_MANIFEST.split("/")));
+  if (!manifest) return { manifest: false, fresh: false, reason: "no manifest — run a full scan" };
+  const headSha = gitHeadSha(root);
+  const scannedSha = manifest.headSha ?? null;
+  if (!headSha || !scannedSha) {
+    return { manifest: true, fresh: false, reason: "no SHA anchor — refresh writes one", headSha, scannedSha, changedFiles: null };
+  }
+  const changedFiles = gitChangedFiles(root, scannedSha) ?? [];
+  const fresh = headSha === scannedSha && changedFiles.length === 0;
+  return {
+    manifest: true,
+    fresh,
+    headSha,
+    scannedSha,
+    changedFiles: fresh ? [] : changedFiles.slice(0, 200),
+    sections: Object.keys(manifest.sections ?? {}),
+  };
+}
+
 function parseArgs(argv) {
   const options = {
     repositoryRoot: process.cwd(),
@@ -72,6 +145,7 @@ function parseArgs(argv) {
     else if (key === "--write") options.write = true;
     else if (key === "--json") options.json = true;
     else if (key === "--area" || key.startsWith("--area=")) [i, options.area] = readValue(i, raw);
+    else if (key === "--check") options.check = true;
     else fail(`Unknown argument: ${raw}`);
   }
   return options;
@@ -80,9 +154,16 @@ function parseArgs(argv) {
 function walk(root, options = {}) {
   const maxFiles = Number(options.maxFiles ?? 6000);
   const files = [];
-  const stack = [root];
-  while (stack.length > 0 && files.length < maxFiles) {
-    const current = stack.pop();
+  const queue = [root];
+  let truncated = false;
+  let index = 0;
+  while (index < queue.length) {
+    if (files.length >= maxFiles) {
+      truncated = true;
+      break;
+    }
+    const current = queue[index];
+    index += 1;
     let entries = [];
     try {
       entries = fs.readdirSync(current, { withFileTypes: true });
@@ -95,14 +176,17 @@ function walk(root, options = {}) {
       const full = path.join(current, entry.name);
       const relative = relativeToRepository(root, full);
       if (entry.isDirectory()) {
-        stack.push(full);
+        queue.push(full);
       } else if (entry.isFile()) {
         files.push({ full, relative, name: entry.name });
+        if (files.length >= maxFiles) {
+          truncated = true;
+          break;
+        }
       }
-      if (files.length >= maxFiles) break;
     }
   }
-  return files;
+  return { files, truncated };
 }
 
 function readJson(filePath) {
@@ -130,6 +214,49 @@ function detectStacks(files) {
   }));
 }
 
+function detectProjectType(files, stacks) {
+  const stackIds = new Set(stacks.map((stack) => stack.id));
+  const has = (predicate) => files.some(predicate);
+  const packageJsonCount = files.filter((file) => file.name === "package.json").length;
+  const projectFileCount = files.filter((file) => /\.(csproj|fsproj|vbproj)$/i.test(file.name)).length;
+
+  if (files.length === 0) {
+    return { id: "empty", label: "Empty repository", confidence: "detected", evidence: [] };
+  }
+  if (stackIds.has("nx") || stackIds.has("turborepo") || packageJsonCount > 2 || projectFileCount > 3
+    || has((file) => /^packages\/[^/]+\/package\.json$/.test(file.relative))) {
+    return {
+      id: "monorepo",
+      label: "Monorepo / multi-project",
+      confidence: "detected",
+      evidence: files.filter((file) => file.name === "package.json" || /\.(sln|csproj)$/i.test(file.name)).map((file) => file.relative).slice(0, 8),
+    };
+  }
+  const webSignals = files.filter((file) =>
+    stackIds.has("next") && /^next\.config\./.test(file.name)
+    || stackIds.has("angular") && file.name === "angular.json"
+    || stackIds.has("vite") && /^vite\.config\./.test(file.name)
+    || /(^|\/)(wwwroot|public)\//.test(file.relative)
+    || /(^|\/)(Views|Pages|pages|app)\/.+\.(cshtml|razor|tsx|jsx|vue|svelte)$/i.test(file.relative));
+  if (webSignals.length > 0) {
+    return { id: "webapp", label: "Web application", confidence: "detected", evidence: webSignals.map((file) => file.relative).slice(0, 8) };
+  }
+  const apiSignals = files.filter((file) => /(^|\/)(Controllers|controllers|routes|api)\//.test(file.relative) || /openapi\.(ya?ml|json)$/i.test(file.name));
+  if (apiSignals.length > 0) {
+    return { id: "api", label: "API / backend service", confidence: "detected", evidence: apiSignals.map((file) => file.relative).slice(0, 8) };
+  }
+  const rootPackage = files.find((file) => file.relative === "package.json");
+  if (rootPackage) {
+    const pkg = readJson(rootPackage.full);
+    if (pkg?.bin) return { id: "cli", label: "Command-line tool", confidence: "detected", evidence: ["package.json (bin)"] };
+    if (pkg?.exports || pkg?.main) return { id: "library", label: "Library / package", confidence: "detected", evidence: ["package.json (main/exports)"] };
+  }
+  if (has((file) => /(^|\/)(src|lib)\//.test(file.relative))) {
+    return { id: "library", label: "Library / package", confidence: "inferred", evidence: [] };
+  }
+  return { id: "unknown", label: "Unclassified", confidence: "inferred", evidence: [] };
+}
+
 function findPackageCommands(files) {
   const commands = [];
   for (const file of files.filter((item) => item.name === "package.json")) {
@@ -143,6 +270,7 @@ function findPackageCommands(files) {
           cwd,
           command: cwd === "." ? `npm run ${name}` : `npm run ${name} --prefix ${cwd}`,
           evidence: file.relative,
+          confidence: "detected",
         });
       }
     }
@@ -150,6 +278,37 @@ function findPackageCommands(files) {
   return commands;
 }
 
+/** Default commands for stacks whose runners are conventional; marked inferred until the user confirms them. */
+function deriveStackCommands(stacks, files) {
+  const commands = [];
+  const stackIds = new Set(stacks.map((stack) => stack.id));
+  const firstEvidence = (id) => stacks.find((stack) => stack.id === id)?.evidence[0] ?? "";
+  if (stackIds.has("dotnet")) {
+    const solution = files.find((file) => /\.sln$/i.test(file.name));
+    const target = solution ? solution.relative : firstEvidence("dotnet");
+    commands.push(
+      { name: "build", cwd: ".", command: `dotnet build ${target}`.trim(), evidence: target, confidence: "inferred" },
+      { name: "test", cwd: ".", command: `dotnet test ${target}`.trim(), evidence: target, confidence: "inferred" },
+    );
+  }
+  if (stackIds.has("python")) {
+    commands.push({ name: "test", cwd: ".", command: "python -m pytest", evidence: firstEvidence("python"), confidence: "inferred" });
+  }
+  if (stackIds.has("go")) {
+    commands.push(
+      { name: "build", cwd: ".", command: "go build ./...", evidence: firstEvidence("go"), confidence: "inferred" },
+      { name: "test", cwd: ".", command: "go test ./...", evidence: firstEvidence("go"), confidence: "inferred" },
+    );
+  }
+  if (stackIds.has("rust")) {
+    commands.push(
+      { name: "build", cwd: ".", command: "cargo build", evidence: firstEvidence("rust"), confidence: "inferred" },
+      { name: "test", cwd: ".", command: "cargo test", evidence: firstEvidence("rust"), confidence: "inferred" },
+    );
+  }
+  return commands;
+}
+
 function hasAny(files, predicate) {
   return files.some(predicate);
 }
@@ -171,8 +330,8 @@ function buildSections(root, files, stacks, commands, scannedAt) {
   const sections = {};
   const topFiles = files.map((file) => file.relative);
 
-  if (hasAny(files, (file) => /(^|\/)(README|CONTEXT|CHANGELOG|CONTRIBUTING)\.md$/i.test(file.relative) || file.relative.startsWith("docs/"))) {
-    const docs = topFiles.filter((file) => /(^|\/)(README|CONTEXT|CHANGELOG|CONTRIBUTING)\.md$/i.test(file) || file.startsWith("docs/")).slice(0, 20);
+  if (hasAny(files, (file) => /(^|\/)(README|CONTEXT|CHANGELOG|CONTRIBUTING|AGENTS|CLAUDE)\.md$/i.test(file.relative) || file.relative.startsWith("docs/"))) {
+    const docs = topFiles.filter((file) => /(^|\/)(README|CONTEXT|CHANGELOG|CONTRIBUTING|AGENTS|CLAUDE)\.md$/i.test(file) || file.startsWith("docs/")).slice(0, 20);
     sections.docs = makeSection(".oris-flow/maps/docs.md", "Documentation and task context detected.", {
       scannedAt,
       markdown: [
@@ -185,15 +344,18 @@ function buildSections(root, files, stacks, commands, scannedAt) {
     });
   }
 
-  if (hasAny(files, (file) => file.relative.startsWith(".cursor/skills/") || file.relative.startsWith(".cursor/rules/"))) {
-    const cursorFiles = topFiles.filter((file) => file.startsWith(".cursor/skills/") || file.startsWith(".cursor/rules/")).slice(0, 20);
-    sections.cursorGuidance = makeSection(".oris-flow/maps/cursor-guidance.md", "Project-local Cursor skills or rules detected.", {
+  const guidancePaths = topFiles.filter((file) =>
+    file.startsWith(".cursor/skills/") || file.startsWith(".cursor/rules/")
+    || file.startsWith(".claude/skills/") || /^AGENTS\.md$/i.test(file) || /^CLAUDE\.md$/i.test(file)
+    || /^CONTEXT\.md$/i.test(file) || file.startsWith("docs/adr/")).slice(0, 20);
+  if (guidancePaths.length > 0) {
+    sections.agentGuidance = makeSection(".oris-flow/maps/agent-guidance.md", "Agent guidance detected (AGENTS/CLAUDE/CONTEXT, skills, rules, ADRs).", {
       scannedAt,
       markdown: [
-        "# Cursor Guidance",
+        "# Agent Guidance",
         "",
-        "Detected local Cursor guidance:",
-        ...cursorFiles.map((file) => `- ${file}`),
+        "Detected agent-facing guidance:",
+        ...guidancePaths.map((file) => `- ${file}`),
         "",
       ].join("\n"),
     });
@@ -216,12 +378,12 @@ function buildSections(root, files, stacks, commands, scannedAt) {
   }
 
   if (commands.length > 0) {
-    sections.commands = makeSection(".oris-flow/maps/commands.md", `Detected ${commands.length} package command(s).`, {
+    sections.commands = makeSection(".oris-flow/maps/commands.md", `Detected ${commands.length} command(s).`, {
       scannedAt,
       markdown: [
         "# Commands",
         "",
-        ...commands.map((command) => `- \`${command.command}\` (${command.evidence})`),
+        ...commands.map((command) => `- \`${command.command}\` (${command.evidence || command.confidence}${command.confidence === "inferred" ? ", inferred — confirm before relying on it" : ""})`),
         "",
       ].join("\n"),
     });
@@ -261,12 +423,68 @@ function buildSections(root, files, stacks, commands, scannedAt) {
   return sections;
 }
 
+function resolveTasksRoot(root, existingManifest) {
+  const configured = existingManifest?.setup?.tasksRoot;
+  if (typeof configured === "string" && configured.length > 0) return configured;
+  const legacy = path.join(root, "docs", "tasks");
+  if (fs.existsSync(legacy) && fs.readdirSync(legacy).length > 0) return "docs/tasks";
+  return ORIS_FLOW_TASKS_ROOT;
+}
+
+/**
+ * Refresh keeps user truth: confirmed decisions, tasksRoot, version control,
+ * refresh policy, confirmed commands, and confirmed sections (whose map files
+ * are also left untouched). A confirmed section the scan no longer sees is
+ * marked stale, never deleted.
+ */
+function mergeWithExisting(scan, existingManifest) {
+  if (!existingManifest || typeof existingManifest !== "object") return scan;
+  const merged = scan;
+  merged.manifest.generatedAt = existingManifest.generatedAt ?? merged.manifest.generatedAt;
+  if (Array.isArray(existingManifest.setup?.confirmedDecisions)) {
+    merged.manifest.setup.confirmedDecisions = existingManifest.setup.confirmedDecisions;
+  }
+  if (existingManifest.setup?.versionControl?.orisFlowMap) {
+    merged.manifest.setup.versionControl.orisFlowMap = existingManifest.setup.versionControl.orisFlowMap;
+  }
+  if (existingManifest.refreshPolicy && typeof existingManifest.refreshPolicy === "object") {
+    merged.manifest.refreshPolicy = existingManifest.refreshPolicy;
+  }
+  if (existingManifest.projectType?.confidence === "confirmed") {
+    merged.manifest.projectType = existingManifest.projectType;
+  }
+
+  const confirmedCommands = (existingManifest.commands ?? []).filter((command) => command?.confidence === "confirmed");
+  if (confirmedCommands.length > 0) {
+    const scanned = merged.manifest.commands.filter((command) =>
+      !confirmedCommands.some((confirmed) => confirmed.name === command.name && confirmed.cwd === command.cwd));
+    merged.manifest.commands = [...confirmedCommands, ...scanned];
+    merged.commands = merged.manifest.commands;
+  }
+
+  merged.preservedSections = new Set();
+  for (const [key, pointer] of Object.entries(existingManifest.sections ?? {})) {
+    if (pointer?.confidence !== "confirmed") continue;
+    const rescanned = merged.manifest.sections[key];
+    merged.manifest.sections[key] = {
+      ...pointer,
+      stale: rescanned ? pointer.stale === true : true,
+    };
+    merged.preservedSections.add(key);
+    if (merged.sections[key]) delete merged.sections[key];
+  }
+  return merged;
+}
+
 export function scanRepository(repositoryRoot, options = {}) {
   const root = path.resolve(repositoryRoot);
   const scannedAt = new Date().toISOString();
-  const files = walk(root, options);
+  const headSha = gitHeadSha(root);
+  const existingManifest = readJson(path.join(root, ...ORIS_FLOW_MANIFEST.split("/")));
+  const { files, truncated } = walk(root, options);
   const stacks = detectStacks(files);
-  const commands = findPackageCommands(files);
+  const projectType = detectProjectType(files, stacks);
+  const commands = [...findPackageCommands(files), ...deriveStackCommands(stacks, files)];
   const sections = buildSections(root, files, stacks, commands, scannedAt);
   const sectionPointers = Object.fromEntries(
     Object.entries(sections).map(([key, value]) => [key, value.pointer]),
@@ -277,9 +495,13 @@ export function scanRepository(repositoryRoot, options = {}) {
     repository: path.basename(root),
     generatedAt: scannedAt,
     updatedAt: scannedAt,
+    headSha,
+    projectType,
+    truncated,
     setup: {
-      mode: options.mode ?? "create",
+      mode: options.mode ?? (existingManifest ? "refresh" : "create"),
       scanDepth: options.scanDepth ?? "balanced",
+      tasksRoot: options.tasksRoot ?? resolveTasksRoot(root, existingManifest),
       confirmedDecisions: [],
       versionControl: {
         orisFlowMap: options.versionControl ?? "commit",
@@ -292,27 +514,35 @@ export function scanRepository(repositoryRoot, options = {}) {
     commands,
     sections: sectionPointers,
   };
-  return {
+  const scan = {
     repositoryRoot: root,
     scannedAt,
     fileCount: files.length,
+    truncated,
+    projectType,
     stacks,
     commands,
     sections,
     manifest,
+    preservedSections: new Set(),
   };
+  return mergeWithExisting(scan, existingManifest);
 }
 
-export function writeScanResult(scan) {
+export function writeScanResult(scan, options = {}) {
   const root = scan.repositoryRoot;
+  const area = options.area ?? "";
   const manifestPath = resolveInsideRepository(root, ORIS_FLOW_MANIFEST, "Oris Flow manifest");
   fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
   fs.writeFileSync(manifestPath, `${JSON.stringify(scan.manifest, null, 2)}\n`, "utf8");
 
-  for (const section of Object.values(scan.sections)) {
+  const written = [];
+  for (const [key, section] of Object.entries(scan.sections)) {
+    if (area && key !== area) continue;
     const sectionPath = resolveInsideRepository(root, section.pointer.path, "Oris Flow section");
     fs.mkdirSync(path.dirname(sectionPath), { recursive: true });
     fs.writeFileSync(sectionPath, section.markdown, "utf8");
+    written.push(section.pointer.path);
   }
 
   const readmePath = resolveInsideRepository(root, `${ORIS_FLOW_MAPS_ROOT}/README.md`, "Oris Flow map README");
@@ -322,17 +552,25 @@ export function writeScanResult(scan) {
   }
   return {
     manifestPath: relativeToRepository(root, manifestPath),
-    sectionPaths: Object.values(scan.sections).map((section) => section.pointer.path),
+    sectionPaths: written,
+    preservedSections: [...(scan.preservedSections ?? [])],
   };
 }
 
 if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
   const options = parseArgs(process.argv.slice(2));
+  if (options.check) {
+    console.log(JSON.stringify(checkFreshness(options.repositoryRoot), null, 2));
+    process.exit(0);
+  }
   const scan = scanRepository(options.repositoryRoot, options);
-  const written = options.write ? writeScanResult(scan) : null;
+  const written = options.write ? writeScanResult(scan, { area: options.area }) : null;
   const payload = {
     repositoryRoot: toPosixPath(scan.repositoryRoot),
     fileCount: scan.fileCount,
+    truncated: scan.truncated,
+    projectType: scan.projectType,
+    tasksRoot: scan.manifest.setup.tasksRoot,
     stacks: scan.stacks,
     commands: scan.commands,
     sections: scan.manifest.sections,
@@ -342,9 +580,9 @@ if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToP
     console.log(JSON.stringify(payload, null, 2));
   } else {
     console.log(`Oris Flow scan: ${payload.repositoryRoot}`);
-    console.log(`Files scanned: ${payload.fileCount}`);
+    console.log(`Files scanned: ${payload.fileCount}${payload.truncated ? " (truncated)" : ""}`);
+    console.log(`Project type: ${payload.projectType.label}`);
     console.log(`Stacks: ${payload.stacks.map((stack) => stack.label).join(", ") || "none"}`);
     console.log(`Sections: ${Object.keys(payload.sections).join(", ") || "none"}`);
   }
 }
-

package/scripts/install/generate-agent-adapters.mjs

@@ -52,17 +52,34 @@ developer_instructions = ${instructions}
 `;
 }
 
-export function generateAgentAdapters(root = repoRoot) {
-  const agents = fs.readdirSync(sourceRoot)
+function readAgents() {
+  return fs.readdirSync(sourceRoot)
     .filter((name) => name.endsWith(".md"))
     .map((name) => ({ name, ...readAgent(path.join(sourceRoot, name)) }));
+}
 
+/** Write adapters into repo-local .cursor/.claude/.codex dirs under root. */
+export function generateAgentAdapters(root = repoRoot) {
+  const agents = readAgents();
   for (const agent of agents) {
     writeFile(path.join(root, ".cursor", "agents", agent.name), renderMarkdownAgent(agent));
     writeFile(path.join(root, ".claude", "agents", agent.name), renderMarkdownAgent(agent));
     writeFile(path.join(root, ".codex", "agents", agent.name.replace(/\.md$/, ".toml")), renderCodexAgent(agent));
   }
+  return agents.map((agent) => agent.frontMatter.name);
+}
 
+/**
+ * Write adapters into explicit agent homes, e.g. { cursor: "~/.cursor", codex: "~/.codex" }.
+ * Used by the installer so the generated adapters actually reach the user's agents.
+ */
+export function writeAgentAdapters(targets) {
+  const agents = readAgents();
+  for (const agent of agents) {
+    if (targets.cursor) writeFile(path.join(targets.cursor, "agents", agent.name), renderMarkdownAgent(agent));
+    if (targets.claude) writeFile(path.join(targets.claude, "agents", agent.name), renderMarkdownAgent(agent));
+    if (targets.codex) writeFile(path.join(targets.codex, "agents", agent.name.replace(/\.md$/, ".toml")), renderCodexAgent(agent));
+  }
   return agents.map((agent) => agent.frontMatter.name);
 }
 

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";
@@ -19,11 +22,19 @@ import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
+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);
@@ -42,6 +53,7 @@ function defaultPaths() {
       cursor: path.join(home, ".cursor"),
       claude: path.join(home, ".claude"),
       codex: path.join(home, ".codex"),
+      copilot: vscodeUserDir(home),
     },
   };
 }
@@ -74,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) {
@@ -154,6 +167,7 @@ function defaultSettings() {
     orisFlow: {
       uiLanguage: "en",
       artifactLanguage: "en",
+      responseStyle: "standard",
     },
     defaultProfiles: {
       testing: "default",
@@ -204,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));
@@ -224,8 +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")}`);
+      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;
   }
@@ -245,11 +295,19 @@ 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.filter((agent) => agent !== "copilot").map((agent) => [agent, options.agentRoots[agent]]));
+  const loopAgents = writeAgentAdapters(adapterTargets);
+  log(`Installed ${loopAgents.length} loop agent adapters (${agents.join(", ")})`);
 
   if (!fs.existsSync(options.settingsPath)) writeJson(options.settingsPath, defaultSettings());
   writeJson(path.join(options.bundleRoot, installManifestName), {
@@ -260,7 +318,7 @@ function main() {
     installedAt: new Date().toISOString(),
   });
   log(`Done for agents: ${agents.join(", ")}. Reload your agent environment.`);
-  log("Next: type /oris-flow in your agent chat, or try the loop demo: oris-skills loop demo");
+  log("Next: type /oris-flow in your agent chat, or try the loop demo: npx oris-skills loop demo");
 }
 
 try {