oris-skills 2.0.0

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

@@ -0,0 +1,181 @@
+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 read(relativePath) {
+  return fs.readFileSync(path.join(root, relativePath), "utf8");
+}
+
+function exists(relativePath) {
+  return fs.existsSync(path.join(root, relativePath));
+}
+
+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("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);
+  for (const entry of manifest.skills) {
+    const relative = entry.replace(/^[.\\/]+/, "");
+    const skillFile = path.join(relative, "SKILL.md");
+    assert.equal(exists(skillFile), true, skillFile);
+    const name = read(skillFile).match(/^name:\s*(.+)$/m)?.[1].trim();
+    assert.equal(name, path.basename(relative), `front-matter name must match folder: ${relative}`);
+  }
+});
+
+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");
+  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);
+  assert.match(text, /route to the interview owner/i);
+  assert.match(text, /references\/conventions\.md/);
+});
+
+test("shared conventions centralize question, language, and gate rules", () => {
+  const conventions = read("references/conventions.md");
+  assert.match(conventions, /ONE question per turn/i);
+  assert.match(conventions, /Explain the options.*Spiega le opzioni/s);
+  assert.match(conventions, /NEVER write documents, code, settings, Git, or DevOps without explicit user confirmation/i);
+  const questions = read("references/questions.md");
+  assert.match(questions, /`Explain the options`/);
+  assert.match(questions, /`Spiega le opzioni`/);
+  assert.match(questions, /`Basta domande — procedi`/);
+  assert.match(questions, /`Genera il documento`/);
+  assert.match(questions, /`Continua l'intervista`/);
+  assert.match(questions, /`Approva documento`/);
+  assert.match(questions, /`Annulla`/);
+});
+
+test("every skill points at conventions instead of repeating shared rules", () => {
+  const manifest = JSON.parse(read(".cursor-plugin/plugin.json"));
+  for (const entry of manifest.skills) {
+    const relative = `${entry.replace(/^[.\\/]+/, "")}/SKILL.md`;
+    if (relative.includes("oris-help")) continue;
+    assert.match(read(relative), /conventions\.md/, relative);
+  }
+});
+
+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/);
+  assert.match(skill, /oris-skills loop demo/);
+  assert.match(skill, /oris-skills loop dry-run/);
+  assert.match(skill, /oris-skills loop list --json/);
+  assert.match(skill, /prompts\//);
+  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);
+  }
+  for (const template of ["orchestrator", "executor", "verifier", "doctor", "debriefer"]) {
+    assert.equal(exists(`skills/oris-loop/templates/${template}.md`), true, template);
+  }
+});
+
+test("loop contract stays subagent-first with per-role editable prompts", () => {
+  const contract = read("references/loop-contract.md");
+  assert.match(contract, /schemaVersion: 2/);
+  assert.match(contract, /approved: true/);
+  assert.match(contract, /prompts\/orchestrator\.md/);
+  assert.match(contract, /improve/);
+  assert.match(contract, /inherit/);
+  assert.match(contract, /NEVER success/i);
+  const run = read("skills/oris-loop/references/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\//);
+  assert.match(craft, /write the loop \| edit verifier \| edit executor \| edit doctor/);
+  for (const text of [contract, run, craft, read("skills/oris-loop/SKILL.md")]) {
+    assert.doesNotMatch(text, /node scripts\/(?:flow|loop)\//);
+    assert.doesNotMatch(text, /composer-2\.5/);
+    assert.doesNotMatch(text, /ORIS LOOP ACTIVE/);
+  }
+});
+
+test("setup and repo-map keep the installed CLI as the command surface", () => {
+  const setup = read("skills/oris-flow-setup/SKILL.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/);
+  const repoMap = read("references/repo-map.md");
+  assert.match(repoMap, /never `node scripts\/\.\.\.` paths/);
+});
+
+test("no markdown references the pre-2.0 layout", () => {
+  const offenders = [];
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if ([".git", "node_modules", ".cursor", ".claude", "dist", ".oris-flow"].includes(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.name.endsWith(".md") && entry.name !== "CHANGELOG.md") {
+        const text = fs.readFileSync(full, "utf8");
+        if (/flow\/oris\/|help\/skills\/|help\/references\//.test(text)) {
+          offenders.push(path.relative(root, full).replace(/\\/g, "/"));
+        }
+      }
+    }
+  };
+  walk(root);
+  assert.deepEqual(offenders, []);
+});
+
+test("uninstall and reinstall dry-runs show destructive plan before action", () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "oris-lifecycle-"));
+  try {
+    fs.mkdirSync(path.join(homeDir, ".cursor"), { recursive: true });
+    const uninstall = runCli(["uninstall", "--dry-run"], homeDir);
+    assert.equal(uninstall.status, 0, uninstall.stderr);
+    assert.match(uninstall.stdout, /Dry run uninstall plan/);
+    assert.match(uninstall.stdout, /Would remove/);
+    assert.match(uninstall.stdout, /oris-skills/);
+
+    const reinstall = runCli(["reinstall", "--dry-run"], homeDir);
+    assert.equal(reinstall.status, 0, reinstall.stderr);
+    assert.match(reinstall.stdout, /Dry run uninstall plan/);
+    assert.match(reinstall.stdout, /Would install/);
+    assert.ok(reinstall.stdout.indexOf("Dry run uninstall plan") < reinstall.stdout.indexOf("Would install"));
+  } finally {
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  }
+});
+
+test("CLI exposes install, loop learnability, and flow helper commands", () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "oris-cli-help-"));
+  try {
+    const help = runCli(["help"], homeDir);
+    assert.equal(help.status, 0, help.stderr);
+    assert.match(help.stdout, /--agents cursor,claude,codex/);
+    assert.match(help.stdout, /oris-skills loop demo/);
+    assert.match(help.stdout, /oris-skills loop dry-run --loop <slug>/);
+    assert.match(help.stdout, /oris-skills loop verify --temp/);
+    assert.match(help.stdout, /oris-skills loop chat --action start --loop <slug>/);
+    assert.match(help.stdout, /oris-skills loop run --loop <slug> --agent codex\|claude/);
+    assert.match(help.stdout, /oris-skills flow scan/);
+  } finally {
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  }
+});

package/scripts/tests/test-schemas.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+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";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+function read(relativePath) {
+  return JSON.parse(fs.readFileSync(path.join(root, relativePath), "utf8"));
+}
+
+test("settings schema is the generic v1 contract", () => {
+  const schema = read("references/settings.schema.json");
+  assert.equal(schema.properties.version.const, 1);
+  assert.deepEqual(schema.required, ["version", "orisFlow", "defaultProfiles", "profiles"]);
+  assert.ok(schema.$defs.profile.properties.values);
+  assert.ok(schema.$defs.profile.properties.secrets);
+  assert.ok(schema.$defs.profile.properties.flags);
+});
+
+test("adapter schema v1 declares paths, commands, model aliases, profile, preflight", () => {
+  const schema = read("references/loop-adapter.schema.json");
+  assert.equal(schema.$id, "https://oris.dev/schemas/oris-loop-adapter-v1.json");
+  assert.equal(schema.properties.schemaVersion.const, 1);
+  assert.deepEqual(
+    schema.required,
+    ["$schema", "schemaVersion", "repository", "paths", "commands", "profile", "preflight"],
+  );
+  assert.ok(schema.properties.paths.properties.loops);
+  assert.ok(schema.properties.models, "adapter schema must allow a model alias map");
+  assert.equal(schema.$defs.mapping.properties.secret.type, "boolean");
+});
+
+test("loop document schema is v2 with approved gate, per-role models, and improve mode", () => {
+  const schema = read("references/loop.schema.json");
+  assert.equal(schema.$id, "https://oris.dev/schemas/oris-loop-v2.json");
+  assert.equal(schema.properties.schemaVersion.const, 2);
+  assert.ok(schema.required.includes("approved"));
+  assert.ok(!schema.required.includes("runtime"), "runtime field was removed in v2");
+  for (const role of ["default", "executor", "verifier", "doctor", "debriefer"]) {
+    assert.ok(schema.properties.models.properties[role], `models.${role}`);
+  }
+  assert.deepEqual(schema.properties.improve.properties.mode.enum, ["propose", "auto"]);
+  assert.equal(schema.$defs.model.type, "string", "models are free strings (inherit | alias | model id), not a hardcoded enum");
+});
+
+test("repository map schema v1 allows stack-aware optional sections", () => {
+  const schema = read("references/repo-map.schema.json");
+  assert.equal(schema.properties.schemaVersion.const, 1);
+  assert.deepEqual(schema.required, ["$schema", "schemaVersion", "repository", "generatedAt", "updatedAt", "setup", "sections"]);
+  assert.ok(schema.$defs.sections.additionalProperties);
+});

package/skills/oris-flow/SKILL.md

@@ -0,0 +1,55 @@
+---
+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.
+---
+
+# Oris Flow — Entry Point
+
+The only command users must remember. READ the intent, ROUTE to one skill, ENTER it in the same chat.
+
+RULES: follow `references/conventions.md`. This router NEVER writes documents, code, Git, or DevOps — the destination skill owns its own gates.
+
+## Route
+
+Match the desired outcome to ONE route:
+
+| Route | When the user wants… | Enter |
+|-------|----------------------|-------|
+| setup | prepare / map / refresh the repo for Oris | `skills/oris-flow-setup/SKILL.md` |
+| discover | understand or define product behavior | `skills/oris-flow-discover/SKILL.md` |
+| criteria | acceptance criteria / QA checks | `skills/oris-flow-criteria/SKILL.md` |
+| plan | a technical implementation plan | `skills/oris-flow-plan/SKILL.md` |
+| implement | build from a plan or confirmed scope | `skills/oris-flow-implement/SKILL.md` |
+| fix | fix a bug or regression | `skills/oris-flow-fix/SKILL.md` |
+| loop | repeat work until verified (design, demo, run, tune) | `skills/oris-loop/SKILL.md` |
+| docs | update task docs after a change | `skills/oris-flow-docs/SKILL.md` |
+| help | how Oris works, install, troubleshooting | `skills/oris-help/SKILL.md` |
+
+ROUTING:
+1. IF intent is clear → say one line ("Entering <route>: <why>"), then READ and APPLY the destination skill immediately. NEVER tell the user to type another command.
+2. IF intent is unclear → ask ONE menu question (below).
+3. IF the user wants to analyze, rethink, or change an existing plan → route to the interview owner (discover / plan / loop), NEVER straight to implement.
+4. IF `.oris-flow/manifest.json` is missing → recommend setup first; respect the user's choice.
+5. Destination skills marked `disable-model-invocation` may still be entered from here — that flag only blocks unsolicited invocation from generic chat.
+
+## Menu (low confidence)
+
+ASK "What do you want to do?" localized to `uiLanguage`, options:
+
+- Setup repository
+- Understand / define behavior (discovery)
+- Acceptance criteria
+- Technical plan
+- Implement or fix
+- Loop: repeat until verified
+- 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.
+
+## Done when
+
+- [ ] One route entered in the same chat, or the menu was asked.
+- [ ] No writes happened before the destination skill's own gate.

package/skills/oris-flow/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Oris Flow"
+  short_description: "Start the Oris workflow menu"
+  default_prompt: "Use $oris-flow to choose the right Oris workflow command."

package/skills/oris-flow-criteria/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: oris-flow-criteria
+description: Generate or audit business-readable acceptance criteria with stable IDs, numbered steps, and observable outcomes. Use for acceptance-criteria intent or acceptance-criteria.md work. Ambiguous request - route to /oris-flow.
+---
+
+# Acceptance Criteria
+
+Generate verifiable, browser-observable criteria. These later feed loop VERIFIER prompts — precision here pays twice.
+
+RULES: follow `references/conventions.md`. Doc standards: `references/doc-policy.md`.
+NEVER write code, Git, or DevOps here.
+
+## Generate privately first
+
+1. SOURCES in order of trust: confirmed chat > task docs (`functional-analysis.md` preferred, never required — say once when missing) > current UI > code and tests.
+2. DEDUCE create vs update: existing `acceptance-criteria.md` → update, PRESERVE IDs; never recycle a removed ID for different behavior.
+3. IDs: `AC-001`, `AC-002`, … stable across revisions.
+4. Each scenario: role + starting state, deterministic data, numbered user steps, observable outcome placed under the step that causes it, negative coverage, regressions to keep.
+5. CLASSIFY each: `Verifiable` | `Needs setup/data` | `Blocked by Open QA`.
+6. DISCARD criteria not checkable through observable product behavior. For unbuilt features: only confirmed intended behavior — NEVER invent labels or messages.
+
+## Interview (only high-impact gaps)
+
+ASK one at a time, only what docs/UI/code cannot answer: actor boundaries, required data/state, success message + visible result, blocked/negative cases, async states visible to the user, regressions, ambiguous wording. NEVER ask "anything else?".
+
+## Write + gate
+
+WRITE `docs/tasks/{task}/acceptance-criteria.md` (language `artifactLanguage`):
+
+```markdown
+# {Feature} — Acceptance Criteria
+## AC-001 {scenario title}   [Verifiable | Needs setup/data | Blocked by Open QA]
+Role/state: … | Data: …
+Steps:
+1. …
+   → observable outcome
+Negative: … | Regressions: …
+## Open QA
+## Change history (date | source | change | reason)
+```
+
+THEN ask ONE question: Approve document | Regenerate | Edit specific criteria | Cancel.
+Document is confirmed ONLY on approval. AFTER: offer technical plan | verification loop | stop.
+
+## Done when
+
+- [ ] IDs stable; every scenario observable and classified.
+- [ ] Questions only for gaps evidence could not close.
+- [ ] Approval asked exactly once after writing.

package/skills/oris-flow-discover/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: oris-flow-discover
+description: Business-first functional discovery interview. Use to clarify what a feature should do, define product behavior, or produce functional-analysis.md. Ambiguous request - route to /oris-flow.
+---
+
+# Discovery
+
+Interview the stakeholder until the desired business behavior is clear enough to document. The cornerstone of the flow: everything downstream (criteria, plan, loops) builds on this.
+
+RULES: follow `references/conventions.md`. Doc standards: `references/doc-policy.md`.
+NEVER write code, Git, or DevOps here. WRITE `functional-analysis.md` only after the user explicitly chooses generation.
+
+## Before asking
+
+1. EXPLORE first: task folder (`docs/tasks/{task}/`), existing `functional-analysis.md` / `acceptance-criteria.md` / `implementation-plan.md`, project docs, setup map, code evidence, DevOps context when available.
+2. DEDUCE create vs update: existing `functional-analysis.md` → update; missing → create. Ask only on contradictory signals.
+3. Technical evidence = private input. TRANSLATE it to business language; never show file paths or code to the stakeholder.
+
+## Interview
+
+ASK one business decision at a time, recommended answer first, early-exit option always present.
+BUSINESS ONLY: actors, roles, permissions, goals, current vs desired behavior, visible states, labels, messages, navigation, edge cases, empty/error states, scope in/out/deferred, rollout, priority.
+NEVER ask about: files, APIs, services, tables, selectors, branches, tests, frameworks, implementation order.
+WALK every branch of the decision tree until intent, boundaries, cases, and open points are explicit or intentionally parked. Do not stop at the first plausible answer.
+ESTIMATE complexity in Fibonacci Story Points (1–21) from scope, dependencies, uncertainty, QA impact.
+
+## Generation gate
+
+SHOW compact summary: goal, confirmed behavior, scope in/out, open points, estimate.
+ASK: generate the document | keep interviewing | explain.
+ON generate → write `docs/tasks/{task}/functional-analysis.md` per the template below (language: `artifactLanguage`).
+
+## Document template
+
+```markdown
+# {Feature} — Functional Analysis
+## Goal            (business value, one paragraph)
+## Actors & permissions
+## Behavior        (current → desired, user-visible only, numbered flows)
+## States & messages (labels, empty/error/loading states)
+## Edge cases
+## Scope           (included | excluded | deferred)
+## Open points
+## Estimate        (Story Points + rationale)
+## Change history  (date | source | change | reason)
+```
+
+FACTS only from confirmed sources; open questions go to Open points — NEVER invent behavior.
+
+## After writing
+
+OFFER: acceptance criteria | technical plan | stop. Never auto-start the next phase.
+
+## Done when
+
+- [ ] Explored before asking; questions stayed business-only, one at a time.
+- [ ] Document written only after explicit generation choice.
+- [ ] No code, Git, or DevOps writes.

package/skills/oris-flow-docs/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: oris-flow-docs
+description: Update existing task documents after a later functional, QA, or implementation change. Use when documented behavior changed and docs/tasks files must record it.
+disable-model-invocation: true
+---
+
+# Update Task Docs
+
+Bring `docs/tasks/{task}/` documents in line with a later change, keeping the change traceable.
+
+RULES: follow `references/conventions.md`. Doc standards: `references/doc-policy.md`.
+
+## Workflow
+
+1. IDENTIFY the task folder. IF unclear → ask which task; recommend the obvious recent one.
+2. IF the change itself is vague → ask what changed before reading further.
+3. READ the existing docs, COMPARE with the new reality, CLASSIFY the change: functional | criteria | technical.
+4. ASK only unresolved questions, one at a time.
+5. SUMMARIZE proposed updates; CONFIRM before writing.
+6. UPDATE affected documents in place (language `artifactLanguage`):
+   - rewrite sections to the new behavior — no "changed!" notes scattered in the body;
+   - add one change-history row per document: date | source | short change | reason;
+   - keep unresolved risks in open points, never silently drop them;
+   - preserve acceptance-criteria IDs.
+7. NEVER create a replacement task folder unless the user wants a new feature.
+8. CLOSE with a concise summary. Offer next steps without auto-starting them.
+
+## Done when
+
+- [ ] Every affected document updated in place with a change-history row.
+- [ ] Confirmation before writing; nothing else touched.

package/skills/oris-flow-fix/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: oris-flow-fix
+description: Triage, diagnose, and fix a bug with the smallest safe change. Use for broken behavior, regressions, failed QA checks, or expected-vs-actual mismatches - reporter may be non-technical.
+disable-model-invocation: true
+---
+
+# Fix
+
+Smallest safe change near the failing behavior. The caller may be non-technical — reconstruct context yourself.
+
+RULES: follow `references/conventions.md`.
+NEVER edit code before root cause, proposed fix, and verification plan are summarized and explicitly confirmed.
+
+## Triage
+
+1. IF no details given → ask ONE question (localized): "Which bug? Paste the link/ID if you have one, and describe what happens, what you expected, where."
+2. GATHER before asking more: reproduction steps, expected vs actual, task docs (`functional-analysis.md`, `acceptance-criteria.md`, `implementation-plan.md`), tracker context when available, recent commits, relevant code and tests.
+3. ASSUME bug report, not redesign. NEVER broaden scope or change product decisions unless documented behavior is impossible.
+
+## Diagnose
+
+- REPRODUCE or trace the failure path in code before proposing anything.
+- FIND root cause, not symptom. Check whether the documented behavior (criteria/analysis) defines "correct".
+- SUMMARIZE: root cause → proposed minimal fix → files → verification plan. CONFIRM explicitly.
+
+## Fix
+
+- SURGICAL change near the failure. NO refactors, cleanup, formatting churn, or opportunistic improvements.
+- PRESERVE unrelated user changes.
+- ADD a regression test when the area has test conventions.
+
+## Verify + close
+
+1. RUN the reproduction + targeted tests; broaden if the surface is shared.
+2. SUMMARIZE: cause, change, verification, residual risk.
+3. RECOMMEND: `/oris-loop` verification when criteria exist; docs update when documented behavior changed.
+
+## Done when
+
+- [ ] Root cause identified and confirmed before edits.
+- [ ] Minimal change; regression verified.
+- [ ] No unrelated code touched.

package/skills/oris-flow-implement/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: oris-flow-implement
+description: Implement a confirmed feature from implementation-plan.md or an explicitly confirmed technical recap. Use for build, code, implement, apply-the-plan intents after planning.
+disable-model-invocation: true
+---
+
+# Implement
+
+Execute the confirmed plan — nothing more, nothing less.
+
+RULES: follow `references/conventions.md`.
+NEVER edit code before BOTH the source (plan or recap) and the execution mode are confirmed.
+
+## Prepare
+
+1. FIND `docs/tasks/{task}/implementation-plan.md`. IF missing → reconstruct a technical recap from chat, task docs, and code; SHOW it; CONFIRM before any edit.
+2. READ setup map, project standards, local skills/rules, tests and build conventions for the touched area.
+3. MAP the code, tests, config, and translations the plan touches (parallel subagents when available).
+
+## Execution mode (ask before first edit)
+
+- `Step by step` (recommended) — one numbered `### n.` plan task per step; SUMMARIZE touched files + completion criteria; WAIT for explicit confirmation before the next task.
+- `One shot` — all tasks in order, no stops between tasks.
+
+## While coding
+
+- FOLLOW existing project patterns; no new abstractions without need.
+- STAY inside the confirmed scope; park discoveries as notes, don't chase them.
+- ADD or update focused tests when practical.
+- CLEAN as you finish (`references/clean-code-checklist.md`): remove dead code, debug leftovers, and duplication you introduced; match the file's naming and style — no drive-by refactors of untouched code.
+- NEVER update DevOps unless explicitly asked.
+
+## Verify + close
+
+1. RUN targeted verification first; broaden when the touched surface is shared.
+2. SUMMARIZE: touched files, verification results, residual risk.
+3. RECOMMEND next: `/oris-loop` verification loop when acceptance criteria exist; otherwise update docs (`oris-flow-docs`).
+
+## Done when
+
+- [ ] Source and mode confirmed before edits.
+- [ ] Only planned scope touched; verification ran.
+- [ ] Next step recommended, not auto-started.

package/skills/oris-flow-plan/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: oris-flow-plan
+description: Technical implementation-plan interview before coding - file mapping, architecture choices, sequencing, verification strategy, implementation-plan.md. Ambiguous request - route to /oris-flow.
+---
+
+# Technical Plan
+
+Interview the technical owner until another agent or developer could execute the plan without guessing.
+
+RULES: follow `references/conventions.md`. Doc standards: `references/doc-policy.md`.
+NEVER write code, Git, or DevOps here. WRITE `implementation-plan.md` only after explicit generation choice.
+
+## Before asking
+
+1. EXPLORE: `functional-analysis.md` + `acceptance-criteria.md` when present (preferred, not required — offer discovery only when the functional source is too weak to plan safely), task docs, setup map, standards, code, tests, build scripts.
+2. NEVER re-ask functional/QA questions already answered by docs or confirmed chat.
+3. PREFER existing project patterns over new abstractions. Keep uncertainty visible — never invent architecture, field names, or commands.
+
+## Interview
+
+ASK one technical decision at a time, recommended answer first, early-exit always present:
+ownership boundaries, files/symbols to touch, APIs/contracts, data model, permissions, feature flags, frontend integration, migrations, verification strategy, rollout, risk, sequencing.
+
+## Generation gate
+
+SHOW compact recap: approach, touched areas, sequence, verification, risks, open points.
+ASK: generate the document | keep interviewing | explain.
+ON generate → write `docs/tasks/{task}/implementation-plan.md` (language `artifactLanguage`):
+
+```markdown
+# {Feature} — Implementation Plan
+## Approach        (decisions + why, existing patterns referenced)
+## Implementation plan
+### 1. {task}      (files, changes, completion criteria)
+### 2. …
+## Verification    (commands, tests, what proves each step)
+## Risks & open points
+## Change history  (date | source | change | reason)
+```
+
+Numbered `### n.` tasks are the execution steps `oris-flow-implement` will follow — keep each one bounded and independently verifiable.
+
+## After writing
+
+OFFER: implement | verification loop | stop. Never auto-start.
+
+## Done when
+
+- [ ] Explored before asking; only implementation questions asked.
+- [ ] Plan tasks bounded with completion criteria.
+- [ ] Document written only after explicit generation choice.

package/skills/oris-flow-setup/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: oris-flow-setup
+description: Prepare a repository for Oris - interview, scan, write .oris-flow/manifest.json + maps, arm loop hooks. Use for setup, map, refresh, or "prepare this repo for Oris" intents.
+disable-model-invocation: true
+---
+
+# Oris Setup
+
+GOAL: make the repo cheap for Oris to understand — manifest + maps + loop readiness. Writes ONLY after the user confirms the recap.
+
+RULES: follow `references/conventions.md`. Map format: `references/repo-map.md`.
+
+## Mode
+
+IF `.oris-flow/manifest.json` exists → ask ONE question: refresh all | update one area | review stale sections | show summary (no writes) | recreate from scratch | language & profiles | clean runtime.
+ELSE → create from scratch.
+
+- "language & profiles" → Local Preferences below; touches only `~/.oris/settings.json`.
+- "clean runtime" → preview with `oris-skills flow clean-runtime --repository-root <repo> --dry-run`, confirm, run without `--dry-run`.
+
+## Workflow
+
+1. CONFIRM the target repository root (ask only if multiple roots are plausible).
+2. INTERVIEW before scanning: project context, key standards, test depth, protected areas.
+3. SCAN: `oris-skills flow scan --repository-root <repo> --json` = deterministic baseline. Add parallel subagent scans (docs, frontend, backend/data, tests/build, local skills/rules) only when needed. Scan output = draft evidence, not truth.
+4. DRAFT manifest + map sections with confidence flags; ask focused questions ONLY for ambiguous, high-impact facts.
+5. ASK refresh policy (manual | monthly | after refactor | after test-layout change) — advisory only, never a scheduler.
+6. ASK version control for the map: commit (team default) or gitignore. Record in manifest.
+7. RECAP: repo, mode, detected stack, files to write, loop-readiness gaps, choices. CONFIRM explicitly.
+8. WRITE `.oris-flow/manifest.json` + `.oris-flow/maps/**`, then apply:
+   - `oris-skills flow version-control --repository-root <repo> --mode commit|gitignore`
+   - `oris-skills loop bootstrap --repository-root <repo>` when adapter/hooks are missing.
+9. OFFER next steps: discovery, technical plan, loop (mention `oris-skills loop demo` for first-timers), refresh one area, stop.
+
+REFRESH runs keep user-confirmed values unless the scan proves them stale; update `updatedAt`, confidence, stale flags.
+
+## Local Preferences
+
+1. READ `~/.oris/settings.json` (defaults in `references/settings.md`).
+2. ASK what to change: uiLanguage | artifactLanguage | default test profile | add/update/remove profile.
+3. SHOW masked summary (passwords `***`), CONFIRM, write ONLY the settings file.
+4. NEVER copy secrets into `.oris-flow/**`, docs, or loop state.
+
+## Done when
+
+- [ ] Mode chosen; scan before questions; questions only for real ambiguity.
+- [ ] Explicit confirmation before every write.
+- [ ] No secrets in repository files.
+- [ ] Loop readiness bootstrapped or intentionally skipped.

package/skills/oris-help/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: oris-help
+description: Explain how to install, use, and troubleshoot Oris Skills. Use when the user asks how Oris works, what to type, how to install/update/uninstall, or why a skill is missing.
+disable-model-invocation: true
+---
+
+# Oris Help
+
+Answer in the user's language. Start with the next practical action. Keep it short; details on request.
+
+## Quick answers
+
+| Need | Answer |
+|------|--------|
+| Start anything | Type `/oris-flow` — it routes or shows the menu. It's the only command to remember. |
+| Try loops safely | `oris-skills loop demo` → follow the 3 printed steps (`dry-run` previews, `chat --action start` runs). |
+| Install / update | `npx oris-skills@latest install` (detects Cursor, Claude Code, Codex; or `--agents cursor,claude,codex`). Reload the agent afterwards. |
+| Uninstall / reinstall | `npx oris-skills uninstall` / `npx oris-skills reinstall` (preview with `--dry-run`). |
+| Stop a loop | `oris-skills loop chat --action stop` |
+| Loop status | `oris-skills loop chat --action status` / `oris-skills loop list` |
+| Skill missing after install | Reload the agent; check `~/.oris/oris-skills/` exists; re-run install with `--force`. |
+| Hook not firing | `oris-skills loop verify --temp` self-checks the runtime; `oris-skills loop bootstrap` re-arms repo hooks. |
+| Change language / test profiles | `/oris-flow` → Setup → language & profiles (settings live in `~/.oris/settings.json`). |
+| Edit a loop's behavior | Edit the files in `.oris-flow/loops/{slug}/prompts/` — next pass obeys them. |
+
+## Guardrails
+
+- NEVER tell users to paste secrets anywhere.
+- Skip internals (manifest JSON, hook mechanics) unless the user asks for technical troubleshooting.
+- Deeper docs: `docs/user-guide.md`, `docs/architecture.md` in the bundle (`~/.oris/oris-skills/`).