oris-skills 2.2.2 → 2.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oris-skills",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "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/references/conventions.md

@@ -55,6 +55,9 @@ The `oris-skills` CLI is NOT installed globally. ALWAYS invoke it as `npx oris-s
 - GENERATED documents: `orisFlow.artifactLanguage` from `.oris-flow/settings.json`
   (default `en`).
 - Skill instructions and code stay English.
+- COMMIT messages and PULL REQUEST titles/descriptions: ALWAYS English, whatever the chat
+  language or `artifactLanguage`. Work-item references follow the DevOps provider's
+  `workItemSyntax` (`references/devops.md`).
 
 ## Response style
 

package/references/devops.md

@@ -0,0 +1,58 @@
+# Oris DevOps
+
+How Oris connects to a DevOps platform for commits, pull requests, and work items.
+Swappable by design: today Azure DevOps, tomorrow Jira or GitHub — same flows, a different
+provider block. Non-secret only; Oris stores NO credentials
+(`references/conventions.md` `## Gates`).
+
+## Config surface
+
+Resolved in order, each layer overriding the previous:
+
+1. Built-in Oris default (`azure-devops`, org `orislineweb`, MCP `oris-devops`).
+2. Organization: `~/.oris/devops.json` — shared defaults for everyone in the org.
+3. Repository: `.oris-flow/devops.json` — this repo's override.
+
+Shape (`references/devops.schema.json`):
+
+```json
+{
+  "version": 1,
+  "devops": {
+    "provider": "azure-devops",
+    "organization": "orislineweb",
+    "workItemSyntax": "#{id}",
+    "commitLanguage": "en",
+    "prLanguage": "en",
+    "mcp": {
+      "name": "oris-devops",
+      "package": "@azure-devops/mcp@2.7.0",
+      "domains": ["core", "work", "work-items", "repositories"]
+    }
+  }
+}
+```
+
+- `provider` — the DevOps platform. Swap this (and the `mcp` block) to move off Azure.
+- `organization` — org/account slug; substituted into the MCP command.
+- `workItemSyntax` — how a work item id is written in commits/PRs. `#{id}` → `#1234`.
+- `commitLanguage` / `prLanguage` — always `en`; commits and PRs are English by contract.
+- `mcp` — the MCP server Oris seeds (`oris-devops`) so agents can read work items and
+  repositories. Auth is the platform's own (PAT / sign-in), never Oris's.
+
+## Rules
+
+1. READ the resolved config before composing a commit or PR.
+2. NEVER store credentials in `.oris-flow/**`, `~/.oris/**`, or any Oris file.
+3. Missing provider auth → degrade: compose the message, tell the user, do not block.
+4. CONFIRM before writing any devops config file.
+
+## Never
+
+- Put secrets or tokens in a devops config file.
+- Hardcode a platform in the flows — read `provider` and act generically.
+
+## Done when
+
+- [ ] Effective config resolved from default → org → repo before acting.
+- [ ] No credentials written anywhere under Oris.

package/references/devops.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Oris DevOps Provider",
+  "$id": "https://oris.dev/schemas/oris-flow-devops-v1.json",
+  "type": "object",
+  "required": ["version", "devops"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1
+    },
+    "devops": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "provider": {
+          "type": "string",
+          "description": "DevOps platform id (e.g. azure-devops, github, jira). Swap this and the mcp block to change platform."
+        },
+        "organization": {
+          "type": "string",
+          "description": "Org/account slug substituted into the MCP command. Non-secret."
+        },
+        "workItemSyntax": {
+          "type": "string",
+          "description": "How a work item id is written in commits/PRs. Template with {id}, e.g. #{id} -> #1234."
+        },
+        "commitLanguage": {
+          "type": "string",
+          "minLength": 2,
+          "description": "Language for commit messages. Always en by contract."
+        },
+        "prLanguage": {
+          "type": "string",
+          "minLength": 2,
+          "description": "Language for pull request titles/descriptions. Always en by contract."
+        },
+        "mcp": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "MCP server Oris seeds so agents can read work items and repositories. No credentials.",
+          "properties": {
+            "name": { "type": "string" },
+            "package": { "type": "string" },
+            "domains": { "type": "array", "items": { "type": "string" } },
+            "command": { "type": "string" },
+            "args": { "type": "array", "items": { "type": "string" } }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * Built-in Oris default DevOps provider. Non-secret only — org and repo layers override it.
+ * The provider is swappable: move off Azure DevOps by overriding `provider` and `mcp`.
+ */
+export const DEFAULT_DEVOPS = {
+  version: 1,
+  devops: {
+    provider: "azure-devops",
+    organization: "orislineweb",
+    workItemSyntax: "#{id}",
+    commitLanguage: "en",
+    prLanguage: "en",
+    mcp: {
+      name: "oris-devops",
+      package: "@azure-devops/mcp@2.7.0",
+      domains: ["core", "work", "work-items", "repositories"],
+    },
+  },
+};
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Deep-merge source over target; arrays and scalars replace, plain objects merge. */
+function deepMerge(target, source) {
+  if (!isPlainObject(source)) return source;
+  const out = isPlainObject(target) ? { ...target } : {};
+  for (const [key, value] of Object.entries(source)) {
+    out[key] = isPlainObject(value) ? deepMerge(out[key], value) : value;
+  }
+  return out;
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the effective DevOps config: built-in default → org (`~/.oris/devops.json`) →
+ * repository (`.oris-flow/devops.json`). Missing or invalid layers are skipped, never fatal.
+ */
+export function resolveDevops(repositoryRoot, options = {}) {
+  const home = options.home ?? os.homedir();
+  const orgFile = readJson(path.join(home, ".oris", "devops.json"));
+  const repoFile = repositoryRoot ? readJson(path.join(repositoryRoot, ".oris-flow", "devops.json")) : null;
+  let resolved = DEFAULT_DEVOPS;
+  for (const layer of [orgFile, repoFile]) {
+    if (isPlainObject(layer)) resolved = deepMerge(resolved, layer);
+  }
+  return resolved;
+}
+
+/**
+ * Build the MCP server entry for an agent config from a resolved `devops` block. Azure
+ * DevOps command shape by default; any provider can supply explicit `mcp.args` instead.
+ */
+export function buildMcpServer(devops) {
+  const mcp = devops.mcp ?? {};
+  if (Array.isArray(mcp.args)) return { command: mcp.command ?? "npx", args: [...mcp.args] };
+  const domains = Array.isArray(mcp.domains) ? mcp.domains : [];
+  return { command: "npx", args: ["-y", mcp.package, devops.organization, "-d", ...domains] };
+}
+
+export function mcpServerName(devops) {
+  return devops.mcp?.name ?? "oris-devops";
+}

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

@@ -22,6 +22,8 @@ import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
+import { buildMcpServer, mcpServerName, resolveDevops } from "../flow/oris-flow-devops.mjs";
+import { MCP_AGENTS, seedMcpServer } from "./oris-mcp.mjs";
 
 const markerName = ".oris-skills-managed.json";
 const installManifestName = ".oris-skills-install.json";
@@ -61,6 +63,7 @@ function parseArgs(argv) {
   const options = {
     dryRun: false,
     force: false,
+    noMcp: false,
     agents: [],
     bundleRoot: paths.bundleRoot,
     agentRoots: paths.agentRoots,
@@ -76,6 +79,7 @@ function parseArgs(argv) {
     };
     if (key === "--dry-run") options.dryRun = true;
     else if (key === "--force") options.force = true;
+    else if (key === "--no-mcp") options.noMcp = true;
     else if (key === "--agents" || key.startsWith("--agents=")) {
       options.agents = value().split(",").map((name) => name.trim().toLowerCase()).filter(Boolean);
     } else if (key === "--bundle-root" || key.startsWith("--bundle-root=")) options.bundleRoot = value();
@@ -256,6 +260,10 @@ function main() {
   const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
   const manifest = readJson(path.join(repoRoot, ".cursor-plugin", "plugin.json"));
   const skills = manifestSkills(manifest, repoRoot);
+  const devops = resolveDevops(null).devops;
+  const mcpServer = buildMcpServer(devops);
+  const mcpName = mcpServerName(devops);
+  const mcpAgents = options.noMcp ? [] : (options.agents.length > 0 ? options.agents : detectAgents(options.agentRoots)).filter((agent) => MCP_AGENTS.includes(agent));
   const agents = options.agents.length > 0 ? options.agents : detectAgents(options.agentRoots);
   if (agents.length === 0) {
     fail("No agent detected (~/.cursor, ~/.claude, ~/.codex). Pass --agents cursor,claude,codex explicitly.");
@@ -273,6 +281,7 @@ function main() {
       else log(`Would write ${agent} skills: ${path.join(options.agentRoots[agent], "skills")}`);
     }
     log(`Would write universal pointer: ${path.join(path.dirname(options.bundleRoot), "oris-flow.md")}`);
+    if (mcpAgents.length > 0) log(`Would seed MCP server '${mcpName}' for: ${mcpAgents.join(", ")}`);
     return;
   }
 
@@ -301,6 +310,11 @@ function main() {
   }
   installUniversalPointer(skills, options.bundleRoot);
 
+  for (const agent of mcpAgents) {
+    const result = seedMcpServer(agent, options.agentRoots, mcpName, mcpServer, { force: options.force });
+    log(`MCP ${mcpName} for ${agent}: ${result.status}`);
+  }
+
   writeJson(path.join(options.bundleRoot, installManifestName), {
     package: manifest.name,
     version: manifest.version,

package/scripts/install/oris-mcp.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** Agents that receive an MCP seed. Copilot has no home-scoped MCP target here. */
+export const MCP_AGENTS = ["cursor", "claude", "codex"];
+
+/** MCP config file + format per agent, derived from the (overridable) agent roots. */
+export function mcpConfigTarget(agent, agentRoots) {
+  if (agent === "cursor") return { kind: "json", filePath: path.join(agentRoots.cursor, "mcp.json") };
+  if (agent === "claude") return { kind: "json", filePath: path.join(path.dirname(agentRoots.claude), ".claude.json") };
+  if (agent === "codex") return { kind: "toml", filePath: path.join(agentRoots.codex, "config.toml") };
+  return null;
+}
+
+function readText(filePath) {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function tomlBlock(name, server) {
+  const args = server.args.map((arg) => JSON.stringify(arg)).join(", ");
+  return `\n[mcp_servers.${name}]\ncommand = ${JSON.stringify(server.command)}\nargs = [${args}]\n`;
+}
+
+/**
+ * Seed one MCP server into an agent's config, idempotently. Already present → skip unless
+ * `force`. `dryRun` reports the plan without writing. Returns a status per agent:
+ * "seeded" | "present" | "planned" | "skipped".
+ */
+export function seedMcpServer(agent, agentRoots, name, server, options = {}) {
+  const target = mcpConfigTarget(agent, agentRoots);
+  if (!target) return { status: "skipped", agent };
+
+  if (target.kind === "json") {
+    let data = {};
+    const existing = readText(target.filePath);
+    if (existing.trim()) {
+      try {
+        data = JSON.parse(existing);
+      } catch {
+        data = {};
+      }
+    }
+    const servers = data.mcpServers && typeof data.mcpServers === "object" ? data.mcpServers : {};
+    const present = Object.prototype.hasOwnProperty.call(servers, name);
+    if (present && !options.force) return { status: "present", agent, filePath: target.filePath };
+    if (options.dryRun) return { status: "planned", agent, filePath: target.filePath };
+    servers[name] = server;
+    data.mcpServers = servers;
+    fs.mkdirSync(path.dirname(target.filePath), { recursive: true });
+    fs.writeFileSync(target.filePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+    return { status: "seeded", agent, filePath: target.filePath };
+  }
+
+  // TOML (Codex config.toml)
+  const text = readText(target.filePath);
+  const present = text.includes(`[mcp_servers.${name}]`);
+  if (present) return { status: "present", agent, filePath: target.filePath };
+  if (options.dryRun) return { status: "planned", agent, filePath: target.filePath };
+  fs.mkdirSync(path.dirname(target.filePath), { recursive: true });
+  fs.writeFileSync(target.filePath, `${text}${tomlBlock(name, server)}`, "utf8");
+  return { status: "seeded", agent, filePath: target.filePath };
+}

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

@@ -14,6 +14,8 @@ const nodeTestFiles = [
   "scripts/tests/test-skill-self-contained.mjs",
   "scripts/tests/test-oris-1-0-cleanliness.mjs",
   "scripts/tests/test-oris-flow-scan.mjs",
+  "scripts/tests/test-oris-flow-devops.mjs",
+  "scripts/tests/test-install-mcp.mjs",
   "scripts/tests/test-routing-lifecycle.mjs",
   "scripts/tests/test-skill-style.mjs",
   "scripts/tests/test-oris-loop-stop.mjs",

package/scripts/tests/test-install-mcp.mjs

@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+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("install --dry-run plans the oris-devops MCP server", () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), "oris-mcp-dry-"));
+  try {
+    const result = runCli(["install", "--dry-run", "--agents", "claude,cursor,codex"], home);
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stdout, /Would seed MCP server 'oris-devops'/);
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("--no-mcp skips seeding", () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), "oris-mcp-off-"));
+  try {
+    const result = runCli(["install", "--dry-run", "--agents", "claude", "--no-mcp"], home);
+    assert.equal(result.status, 0, result.stderr);
+    assert.doesNotMatch(result.stdout, /Would seed MCP/);
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("real install seeds oris-devops into the Claude config, idempotently", () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), "oris-mcp-real-"));
+  try {
+    fs.mkdirSync(path.join(home, ".claude"), { recursive: true });
+    const first = runCli(["install", "--force", "--agents", "claude"], home);
+    assert.equal(first.status, 0, first.stderr);
+
+    const claudeConfig = path.join(home, ".claude.json");
+    assert.ok(fs.existsSync(claudeConfig), "~/.claude.json written");
+    const data = JSON.parse(fs.readFileSync(claudeConfig, "utf8"));
+    assert.ok(data.mcpServers["oris-devops"], "oris-devops seeded");
+    assert.deepEqual(
+      data.mcpServers["oris-devops"].args.slice(0, 3),
+      ["-y", "@azure-devops/mcp@2.7.0", "orislineweb"],
+    );
+
+    const second = runCli(["install", "--force", "--agents", "claude"], home);
+    assert.equal(second.status, 0, second.stderr);
+    const after = JSON.parse(fs.readFileSync(claudeConfig, "utf8"));
+    assert.equal(Object.keys(after.mcpServers).length, 1, "no duplicate server on re-install");
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { DEFAULT_DEVOPS, resolveDevops, buildMcpServer, mcpServerName } from "../flow/oris-flow-devops.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+test("default provider is Azure DevOps with the oris-devops MCP and #{id} work items", () => {
+  const d = DEFAULT_DEVOPS.devops;
+  assert.equal(d.provider, "azure-devops");
+  assert.equal(d.organization, "orislineweb");
+  assert.equal(d.workItemSyntax, "#{id}");
+  assert.equal(d.commitLanguage, "en");
+  assert.equal(d.prLanguage, "en");
+  assert.equal(mcpServerName(d), "oris-devops");
+});
+
+test("buildMcpServer produces the exact Azure DevOps command", () => {
+  const server = buildMcpServer(DEFAULT_DEVOPS.devops);
+  assert.deepEqual(server, {
+    command: "npx",
+    args: ["-y", "@azure-devops/mcp@2.7.0", "orislineweb", "-d", "core", "work", "work-items", "repositories"],
+  });
+});
+
+test("buildMcpServer honours explicit args for a non-Azure provider", () => {
+  const server = buildMcpServer({ organization: "x", mcp: { command: "node", args: ["jira-mcp.js"] } });
+  assert.deepEqual(server, { command: "node", args: ["jira-mcp.js"] });
+});
+
+test("resolution order is default -> org -> repo, each overriding the previous", () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), "oris-devops-home-"));
+  const repo = fs.mkdtempSync(path.join(os.tmpdir(), "oris-devops-repo-"));
+  try {
+    fs.mkdirSync(path.join(home, ".oris"), { recursive: true });
+    fs.writeFileSync(
+      path.join(home, ".oris", "devops.json"),
+      JSON.stringify({ version: 1, devops: { organization: "acme", workItemSyntax: "AB#{id}" } }),
+    );
+    fs.mkdirSync(path.join(repo, ".oris-flow"), { recursive: true });
+    fs.writeFileSync(
+      path.join(repo, ".oris-flow", "devops.json"),
+      JSON.stringify({ version: 1, devops: { workItemSyntax: "JIRA-{id}" } }),
+    );
+    const resolved = resolveDevops(repo, { home }).devops;
+    assert.equal(resolved.provider, "azure-devops", "provider inherited from default");
+    assert.equal(resolved.organization, "acme", "organization from org layer");
+    assert.equal(resolved.workItemSyntax, "JIRA-{id}", "repo layer wins over org layer");
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+    fs.rmSync(repo, { recursive: true, force: true });
+  }
+});
+
+test("devops schema is a versioned v1 contract", () => {
+  const schema = JSON.parse(fs.readFileSync(path.join(root, "references", "devops.schema.json"), "utf8"));
+  assert.equal(schema.$id, "https://oris.dev/schemas/oris-flow-devops-v1.json");
+  assert.equal(schema.properties.version.const, 1);
+  assert.deepEqual(schema.required, ["version", "devops"]);
+  assert.ok(schema.properties.devops.properties.provider);
+});

package/skills/oris-flow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oris-flow
-description: The one Oris skill - read the intent, pick ONE route, apply it in the same chat. 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.
+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, commit changes, open a pull request, or asks how Oris works.
 ---
 
 # Oris Flow — the router
@@ -32,6 +32,8 @@ Match the desired outcome to ONE route, then apply its reference:
 | 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` |
+| commit | commit changes with the Oris standard — map fresh, Conventional Commits, work item linked | `skills/oris-flow/references/commit.md` |
+| pr | open or update a pull request, English title/description linked to the work item | `skills/oris-flow/references/pr.md` |
 | help | how Oris works, install, update, troubleshooting | `skills/oris-flow/references/help.md` |
 
 ## Precedence (the calls that look ambiguous)
@@ -47,6 +49,8 @@ Match the desired outcome to ONE route, then apply its reference:
 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.
+7. COMMIT staged/working changes with the standard → commit. OPEN or update a pull request
+   → pr. Neither writes product code — they package and publish what implement/fix produced.
 
 ## Menu (low confidence)
 
@@ -65,6 +69,8 @@ fallback in `references/conventions.md` `## Questions`), options:
 - Loop: repeat until verified
 - Architecture review
 - Update docs
+- Commit changes
+- Open a pull request
 - Help
 - Explain the options / Spiega le opzioni
 

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

@@ -0,0 +1,45 @@
+# Commit
+
+Turn staged or working changes into one clean commit — map fresh, message in English,
+work item linked. NEVER commit without showing the message and getting a yes.
+
+RULES: `references/conventions.md`. DevOps config: `references/devops.md`.
+
+## Before the commit
+
+1. FRESHEN the map: `npx oris-skills flow scan --repository-root <repo> --check`. Stale →
+   refresh ONLY the changed areas (`--area <section>`) and stage `.oris-flow/` with the change.
+2. READ the diff (`git status`, `git diff --staged`) to know what actually changed.
+3. RESOLVE the work item id from context — current branch, the active task doc, or the
+   DevOps provider's active items. Unsure → ASK once for the id; never invent one.
+
+## Compose (always English)
+
+- TYPE from Conventional Commits: `feat` | `fix` | `chore` | `docs` | `refactor` | `test`
+  | `perf` | `build` | `ci`. Pick from the diff, not the chat.
+- SUBJECT imperative, ≤72 chars, no trailing period. Optional `(scope)`.
+- BODY only when it adds signal: what and why, not how.
+- FOOTER: the work item via the provider `workItemSyntax` (default `#{id}`), on its own line.
+
+## Gate (never skipped)
+
+SHOW the full message + the files it will commit (code + refreshed map). ASK:
+commit | edit message | cancel. ON commit → `git commit`; NEVER `--no-verify`.
+
+## After
+
+- SUMMARIZE the commit (hash, subject, work item).
+- OFFER a pull request (`skills/oris-flow/references/pr.md`) or stop. NEVER auto-open one.
+
+## Never
+
+- Commit before the message and file list are shown and confirmed.
+- Write the message in any language but English.
+- Invent a work item id, or bypass hooks with `--no-verify`.
+- Refresh confirmed map sections, or scan-rewrite areas the diff did not touch.
+
+## Done when
+
+- [ ] Map checked, and refreshed in place only where the diff touched.
+- [ ] English Conventional message with the work item linked, confirmed at the gate.
+- [ ] Commit made without `--no-verify`; next step offered, not auto-run.

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

@@ -0,0 +1,44 @@
+# Pull Request
+
+Open or update a pull request whose title and description are English and linked to the
+work item. NEVER open or update a PR without showing it and getting a yes.
+
+RULES: `references/conventions.md`. DevOps config: `references/devops.md`.
+
+## Before
+
+1. ENSURE the branch is pushed and its commits follow the commit standard
+   (`skills/oris-flow/references/commit.md`); uncommitted work remains → route there first.
+2. READ the commit range to summarize the actual change, not the intent.
+3. RESOLVE the work item id (branch, task doc, or DevOps provider) — unsure → ASK once.
+
+## Compose (always English)
+
+- TITLE: one Conventional line, same grammar as a commit subject.
+- DESCRIPTION: a short **Summary** (what changed and why), a **Verification** line
+  (how it was proven), and the work item via the provider `workItemSyntax` (default `#{id}`).
+- KEEP secrets out — mask anything sensitive as `***` (`references/conventions.md` `## Gates`).
+
+## Gate (never skipped)
+
+SHOW the title + description + target branch. ASK: open PR | edit | cancel.
+ON open → create via the provider (Azure DevOps MCP `oris-devops`, or `gh` for GitHub)
+read from `references/devops.md`. Missing provider auth → say so; never guess credentials.
+
+## After
+
+- SUMMARIZE: PR link/number, target branch, work item.
+- RECOMMEND verify (`skills/oris-flow/references/verify.md`) when criteria exist.
+  NEVER merge automatically.
+
+## Never
+
+- Open or update a PR before the title and description are shown and confirmed.
+- Write the title or description in any language but English.
+- Invent a work item id, store credentials, or merge without being asked.
+
+## Done when
+
+- [ ] Branch pushed and commits follow the commit standard.
+- [ ] English title + description with the work item linked, confirmed at the gate.
+- [ ] PR opened/updated via the configured provider; merge never automatic.