oris-skills 2.2.0 → 2.2.1

package/.cursor-plugin/plugin.json

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

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 2.2.1 - 2026-07-07
+
+- **Loop roles are invisible to users**: the installer no longer writes `oris-loop-{executor,verifier,doctor,debriefer}` into `~/.cursor/agents/`, `~/.claude/agents/`, or `~/.codex/agents/` — they showed up as manually invocable subagents, but the loop orchestrator never spawns them by name (it passes each loop's `prompts/<role>.md` to a generic subagent). `agents/` stays in the repo as the canonical role definitions for development. Uninstall (and therefore reinstall/upgrade) now also removes adapters left behind by earlier versions.
+
 ## 2.2.0 - 2026-07-07
 
 - **One skill**: users see only `/oris-flow`. Every former skill (setup, new, discover, criteria, plan, implement, fix, verify, change, architecture, merge, docs, help, loop) is now a route reference inside `skills/oris-flow/references/`; the router reads the intent, picks ONE route, and applies its reference in the same chat. Loop prompt templates moved to `skills/oris-flow/templates/`.

package/docs/architecture.md

@@ -7,7 +7,7 @@ Read this before explaining or changing the project.
 ```text
 skills/oris-flow/   the ONE user-facing skill: SKILL.md routes; references/ hold every route (setup…loop); templates/ hold the loop role prompts
 references/         shared contracts (conventions, loop-contract, settings, repo-map, doc-policy, clean-code-checklist) + JSON schemas
-agents/             canonical subagent definitions; adapters generated per platform
+agents/             canonical loop-role definitions (internal); never installed into user agent homes — roles reach subagents via each loop's prompts/<role>.md
 scripts/            Node CLI (oris-skills.mjs), loop runtime, installer, tests
 docs/               this file, user-guide, maintainer-guide, distribution
 ```

package/docs/distribution.md

@@ -26,7 +26,7 @@ Project assets live only in each repository's `.oris-flow/` (adapter, loops, run
 
 ```bash
 npx oris-skills uninstall --dry-run   # preview
-npx oris-skills uninstall             # removes Oris-owned paths incl. legacy ~/.cursor locations
+npx oris-skills uninstall             # removes Oris-owned paths incl. legacy ~/.cursor locations and pre-2.2.1 loop agent adapters (~/.cursor|.claude|.codex/agents/oris-*)
 npx oris-skills reinstall
 ```
 

package/package.json

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

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

@@ -58,7 +58,11 @@ function readAgents() {
     .map((name) => ({ name, ...readAgent(path.join(sourceRoot, name)) }));
 }
 
-/** Write adapters into repo-local .cursor/.claude/.codex dirs under root. */
+/**
+ * Write adapters into repo-local .cursor/.claude/.codex dirs under root.
+ * Development-only: the installer never copies these into user agent homes —
+ * loop roles are internal and reach subagents via per-loop prompts/<role>.md files.
+ */
 export function generateAgentAdapters(root = repoRoot) {
   const agents = readAgents();
   for (const agent of agents) {
@@ -69,20 +73,6 @@ export function generateAgentAdapters(root = repoRoot) {
   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);
-}
-
 if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
   const rootArg = process.argv.find((arg) => arg.startsWith("--root="));
   const root = rootArg ? path.resolve(rootArg.slice("--root=".length)) : repoRoot;

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

@@ -22,7 +22,6 @@ 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";
@@ -273,7 +272,6 @@ function main() {
       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}`);
@@ -305,10 +303,6 @@ function main() {
   }
   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), {
     package: manifest.name,

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

@@ -92,6 +92,15 @@ function managedCodexPrompts(codexRoot) {
     .map((entry) => path.join(promptsRoot, entry.name));
 }
 
+/** Loop agent adapters that pre-2.2.1 installers wrote into <agent home>/agents/. */
+function managedAgentAdapters(agentRoot, extension) {
+  const agentsRoot = path.join(agentRoot, "agents");
+  if (!fs.existsSync(agentsRoot)) return [];
+  return fs.readdirSync(agentsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.toLowerCase().startsWith("oris-") && entry.name.endsWith(extension))
+    .map((entry) => path.join(agentsRoot, entry.name));
+}
+
 function managedCopilotPrompts(copilotRoot) {
   const promptsRoot = path.join(copilotRoot, "prompts");
   if (!fs.existsSync(promptsRoot)) return [];
@@ -119,6 +128,9 @@ function plannedRemovals(options) {
     ...managedSkillDirs(path.join(options.claudeRoot, "skills")),
     ...managedCodexPrompts(options.codexRoot),
     ...managedCopilotPrompts(options.copilotRoot),
+    ...managedAgentAdapters(options.cursorRoot, ".md"),
+    ...managedAgentAdapters(options.claudeRoot, ".md"),
+    ...managedAgentAdapters(options.codexRoot, ".toml"),
     path.join(path.dirname(options.bundleRoot), "oris-flow.md"),
     ...legacyOrisPaths(options),
   ]);

package/scripts/tests/test-agent-adapters.mjs

@@ -1,11 +1,25 @@
+import childProcess from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import assert from "node:assert/strict";
+import process from "node:process";
 import test from "node:test";
+import { fileURLToPath } from "node:url";
 import { generateAgentAdapters } from "../install/generate-agent-adapters.mjs";
 
-test("generates Cursor, Claude, and Codex agent adapters", () => {
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+function runCli(args, homeDir) {
+  return childProcess.spawnSync(process.execPath, ["scripts/oris-skills.mjs", ...args], {
+    cwd: root,
+    encoding: "utf8",
+    env: { ...process.env, HOME: homeDir, USERPROFILE: homeDir },
+    shell: false,
+  });
+}
+
+test("generates repo-local Cursor, Claude, and Codex agent adapters", () => {
   const temp = fs.mkdtempSync(path.join(os.tmpdir(), "oris-agent-adapters-"));
   try {
     const generated = generateAgentAdapters(temp);
@@ -17,3 +31,40 @@ test("generates Cursor, Claude, and Codex agent adapters", () => {
     fs.rmSync(temp, { recursive: true, force: true });
   }
 });
+
+test("install never plans loop agent adapters in user agent homes", () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "oris-agent-install-"));
+  try {
+    fs.mkdirSync(path.join(homeDir, ".claude"), { recursive: true });
+    fs.mkdirSync(path.join(homeDir, ".cursor"), { recursive: true });
+    const result = runCli(["install", "--dry-run"], homeDir);
+    assert.equal(result.status, 0, result.stderr);
+    assert.doesNotMatch(result.stdout, /loop agents/i);
+    assert.doesNotMatch(result.stdout, /agent adapters/i);
+  } finally {
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  }
+});
+
+test("uninstall removes legacy loop agent adapters but keeps user agents", () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "oris-agent-uninstall-"));
+  try {
+    const claudeAgents = path.join(homeDir, ".claude", "agents");
+    const cursorAgents = path.join(homeDir, ".cursor", "agents");
+    const codexAgents = path.join(homeDir, ".codex", "agents");
+    for (const dir of [claudeAgents, cursorAgents, codexAgents]) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(claudeAgents, "oris-loop-executor.md"), "legacy adapter\n", "utf8");
+    fs.writeFileSync(path.join(claudeAgents, "my-agent.md"), "user agent\n", "utf8");
+    fs.writeFileSync(path.join(cursorAgents, "oris-loop-verifier.md"), "legacy adapter\n", "utf8");
+    fs.writeFileSync(path.join(codexAgents, "oris-loop-doctor.toml"), "legacy adapter\n", "utf8");
+
+    const result = runCli(["uninstall"], homeDir);
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(fs.existsSync(path.join(claudeAgents, "oris-loop-executor.md")), false);
+    assert.equal(fs.existsSync(path.join(cursorAgents, "oris-loop-verifier.md")), false);
+    assert.equal(fs.existsSync(path.join(codexAgents, "oris-loop-doctor.toml")), false);
+    assert.equal(fs.existsSync(path.join(claudeAgents, "my-agent.md")), true, "non-Oris agents must survive");
+  } finally {
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  }
+});