oris-skills 2.2.2 → 3.0.1

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

@@ -72,58 +72,27 @@ test("every skill points at conventions instead of repeating shared rules", () =
   }
 });
 
-test("loop skill covers craft, demo, run, audit, improve and editable prompt files", () => {
-  const skill = read("skills/oris-flow/references/loop.md");
-  assert.match(skill, /references\/loop-craft\.md/);
-  assert.match(skill, /references\/loop-run\.md/);
-  assert.match(skill, /references\/loop-improve\.md/);
-  assert.match(skill, /oris-skills loop demo/);
-  assert.match(skill, /oris-skills loop dry-run/);
-  assert.match(skill, /oris-skills loop list --json/);
-  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-flow/references/loop-${reference}.md`), true, reference);
-  }
-  for (const template of ["orchestrator", "executor", "verifier", "doctor", "debriefer"]) {
-    assert.equal(exists(`skills/oris-flow/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-flow/references/loop-run.md");
-  assert.match(run, /oris-skills loop chat --action start --loop <slug>/);
-  assert.match(run, /NEVER do executor\/verifier\/doctor work in the main chat/i);
-  assert.match(run, /set-state blocked/);
-  assert.match(run, /oris-skills loop run --loop <slug> --agent codex\|claude/);
-  const craft = read("skills/oris-flow/references/loop-craft.md");
-  assert.match(craft, /skills\/oris-flow\/templates\//);
-  assert.match(craft, /write the loop \| edit verifier \| edit executor \| edit doctor/);
-  assert.match(contract, /ORIS LOOP ACTIVE/, "the contract defines the executor gate literal");
-  for (const text of [contract, run, craft, read("skills/oris-flow/references/loop.md")]) {
-    assert.doesNotMatch(text, /node scripts\/(?:flow|loop)\//);
-    assert.doesNotMatch(text, /composer-2\.5/);
-  }
-  for (const text of [run, craft, read("skills/oris-flow/references/loop.md")]) {
-    assert.doesNotMatch(text, /ORIS LOOP ACTIVE/, "the gate literal lives in the contract and executor prompts only");
+test("the loop runtime is fully removed", () => {
+  for (const legacy of [
+    "scripts/loop",
+    "agents",
+    "skills/oris-flow/templates",
+    "skills/oris-flow/references/loop.md",
+    "references/loop-contract.md",
+    "references/repo-map.md",
+  ]) {
+    assert.equal(exists(legacy), false, `${legacy} must not exist`);
   }
+  const skill = read("skills/oris-flow/SKILL.md");
+  assert.doesNotMatch(skill, /\bloop\b/i, "the router must not mention loops");
 });
 
-test("setup and repo-map keep the installed CLI as the command surface", () => {
+test("setup keeps the installed CLI as the command surface and AGENTS.md as the store", () => {
   const setup = read("skills/oris-flow/references/setup.md");
   assert.match(setup, /oris-skills flow scan --repository-root <repo> --json/);
-  assert.match(setup, /oris-skills loop bootstrap --repository-root <repo>/);
-  assert.match(setup, /oris-skills flow clean-runtime --repository-root <repo> --dry-run/);
-  const repoMap = read("references/repo-map.md");
-  assert.match(repoMap, /never `node scripts\/\.\.\.` paths/);
+  assert.match(setup, /oris-skills flow version-control --repository-root <repo> --mode commit\|gitignore/);
+  assert.doesNotMatch(setup, /node scripts\//, "always the installed CLI, never source paths");
+  assert.match(setup, /AGENTS\.md/);
 });
 
 test("no markdown references the pre-2.0 layout", () => {
@@ -165,18 +134,18 @@ test("uninstall and reinstall dry-runs show destructive plan before action", ()
   }
 });
 
-test("CLI exposes install, loop learnability, and flow helper commands", () => {
+test("CLI exposes install and flow helper commands, and no loop surface", () => {
   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/);
+    assert.match(help.stdout, /oris-skills flow version-control/);
+    assert.doesNotMatch(help.stdout, /loop/i);
+
+    const loop = runCli(["loop", "list"], homeDir);
+    assert.equal(loop.status, 1, "loop is an unknown command in 3.0");
   } finally {
     fs.rmSync(homeDir, { recursive: true, force: true });
   }

package/scripts/tests/test-schemas.mjs

@@ -12,45 +12,31 @@ function read(relativePath) {
   return JSON.parse(fs.readFileSync(path.join(root, relativePath), "utf8"));
 }
 
-test("settings schema is the minimal v1 contract: only responseStyle and artifactLanguage", () => {
+test("settings schema is the v1 contract: preferences only, no secrets, no profiles", () => {
   const schema = read("references/settings.schema.json");
   assert.equal(schema.properties.version.const, 1);
   assert.deepEqual(schema.required, ["version", "orisFlow"]);
-  assert.ok(schema.properties.orisFlow.properties.responseStyle);
-  assert.ok(schema.properties.orisFlow.properties.artifactLanguage);
-  assert.ok(!schema.properties.defaultProfiles, "test profiles were removed from settings");
-  assert.ok(!schema.properties.profiles, "test profiles were removed from settings");
-});
-
-test("adapter schema v1 declares paths, commands, model aliases, preflight (no test profiles)", () => {
-  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);
+  const properties = schema.properties.orisFlow.properties;
   assert.deepEqual(
-    schema.required,
-    ["$schema", "schemaVersion", "repository", "paths", "commands", "preflight"],
+    Object.keys(properties).sort(),
+    ["artifactLanguage", "responseStyle", "tasksRoot", "versionControl"],
   );
-  assert.ok(schema.properties.paths.properties.loops);
-  assert.ok(schema.properties.models, "adapter schema must allow a model alias map");
-  assert.ok(!schema.properties.profile, "test profiles were removed from the adapter");
+  assert.deepEqual(properties.versionControl.enum, ["commit", "gitignore"]);
+  assert.ok(!schema.properties.defaultProfiles, "test profiles were removed from settings");
+  assert.ok(!schema.properties.profiles, "test profiles were removed from settings");
 });
 
-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}`);
+test("no loop or repo-map schemas survive the 3.0 cleanup", () => {
+  for (const legacy of [
+    "references/loop.schema.json",
+    "references/loop-adapter.schema.json",
+    "references/repo-map.schema.json",
+  ]) {
+    assert.equal(fs.existsSync(path.join(root, legacy)), false, `${legacy} must not exist`);
   }
-  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);
+test("devops schema stays the only other JSON contract", () => {
+  const schemas = fs.readdirSync(path.join(root, "references")).filter((name) => name.endsWith(".schema.json"));
+  assert.deepEqual(schemas.sort(), ["devops.schema.json", "settings.schema.json"]);
 });

package/scripts/tests/test-skill-style.mjs

@@ -36,8 +36,11 @@ test("skill style: oris-flow", () => {
   assert.match(front[1], /^name: oris-flow$/m, "front matter name matches the folder");
   const description = front[1].match(/^description: (.+)$/m)?.[1];
   assert.ok(description, "front matter has description");
-  assert.match(description, /Use for/, "description names its triggers");
-  assert.doesNotMatch(front[1], /disable-model-invocation/, "the single entry point must stay model-invocable");
+  assert.match(
+    front[1],
+    /^disable-model-invocation: true$/m,
+    "the entry point is user-invoked only (/oris-flow) — decision 2026-07-10, never auto-triggered",
+  );
   assert.ok(text.includes("## Never"), "carries an explicit Never block");
   assert.ok(text.includes("## Done when"), "ends with a Done when checklist");
   const lines = text.split(/\r?\n/).length;

package/skills/oris-flow/SKILL.md

@@ -1,6 +1,7 @@
 ---
 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. Routes setup, new project, discovery, acceptance criteria, technical plan, implement, fix, verify, spec change, architecture review, docs, commit, pull request, and help.
+disable-model-invocation: true
 ---
 
 # Oris Flow — the router
@@ -29,9 +30,10 @@ Match the desired outcome to ONE route, then apply its reference:
 | fix | broken behavior, a regression, a failed QA check | `skills/oris-flow/references/fix.md` |
 | verify | check acceptance criteria against the real product, once | `skills/oris-flow/references/verify.md` |
 | change | the spec changed — update analysis, criteria, plan, and history together | `skills/oris-flow/references/change.md` |
-| loop | repeat work until verified — fix until green, step through a plan | `skills/oris-flow/references/loop.md` |
 | architecture | review architecture, find deepening/refactor opportunities | `skills/oris-flow/references/architecture.md` |
 | docs | update task docs after a change | `skills/oris-flow/references/docs.md` |
+| commit | commit changes with the Oris standard — 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)
@@ -44,9 +46,10 @@ Match the desired outcome to ONE route, then apply its reference:
    change owns the delta and the history.
 4. BROKEN behavior → fix. NEW planned work → implement. The menu answer "Implement or
    fix" gets exactly one follow-up question to split them.
-5. CHECK once → verify. Repeat-until-verified → loop.
-6. EMPTY directory or from-scratch intent → new. Existing repo without
-   `.oris-flow/manifest.json` → recommend setup first; respect the user's choice.
+5. EMPTY directory or from-scratch intent → new. Existing repo never touched by Oris
+   (no `AGENTS.md`, no `.oris-flow/`) → recommend setup first; respect the user's choice.
+6. 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)
 
@@ -62,9 +65,10 @@ fallback in `references/conventions.md` `## Questions`), options:
 - Implement or fix
 - Verify acceptance criteria
 - Spec changed: update feature docs
-- 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/architecture.md

@@ -22,7 +22,7 @@ routes to plan/implement.
 
 ## 1. Explore
 
-1. READ first: setup map, `CONTEXT.md` (domain names for good seams), `docs/adr/`
+1. READ first: `AGENTS.md`, `CONTEXT.md` (domain names for good seams), `docs/adr/`
    (decisions NOT to re-litigate).
 2. WALK the codebase with parallel subagents. No rigid heuristics — note real friction:
    - understanding one concept requires bouncing between many small modules;

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

@@ -0,0 +1,46 @@
+# Commit
+
+Turn staged or working changes into one clean commit — 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. READ the diff (`git status`, `git diff --staged`) to know what actually changed.
+2. IF the diff proved a durable fact `AGENTS.md` lacks or contradicts (a new command, a
+   moved area) → correct `AGENTS.md` and stage it with the change (`references/conventions.md`
+   `## Project facts`).
+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. 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`.
+- Touch `AGENTS.md` sections the diff did not contradict.
+
+## Done when
+
+- [ ] Diff read; `AGENTS.md` corrected only where the diff proved it wrong.
+- [ ] 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/criteria.md

@@ -1,8 +1,8 @@
 # Acceptance Criteria
 
 Generate verifiable criteria grounded in observable product behavior — UI, API response,
-CLI output, or a visible system effect. They later feed verify-route checks and
-loop VERIFIER prompts — precision here pays twice.
+CLI output, or a visible system effect. They are the exact checklist the verify route
+executes — precision here pays twice.
 
 RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
 

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

@@ -1,7 +1,7 @@
 # Discovery
 
 Interview the stakeholder until the desired business behavior is clear enough to
-document. The cornerstone of the flow: everything downstream (criteria, plan, loops)
+document. The cornerstone of the flow: everything downstream (criteria, plan, implement)
 builds on this.
 
 RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
@@ -9,7 +9,7 @@ RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
 ## Before asking
 
 1. EXPLORE first: task folder (`{tasksRoot}/{task}/`), existing task docs, project docs,
-   setup map, code evidence, DevOps context when available.
+   `AGENTS.md`, 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

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

@@ -3,7 +3,7 @@
 The smallest safe change near the failing behavior. Reproduce first, root cause before
 any edit, evidence before done.
 
-RULES: `references/conventions.md`.
+RULES: `references/conventions.md`. Research: `references/research.md`.
 
 ## Triage
 
@@ -19,8 +19,12 @@ RULES: `references/conventions.md`.
 - 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.
+- RESEARCH when the cause crosses the repo boundary (`references/research.md`): a
+  third-party error, a library behaving unlike its docs, a known-issue smell → search
+  for the documented behavior and standard workarounds at the repo's pinned versions,
+  instead of guessing.
+- SUMMARIZE: root cause → proposed minimal fix → files → verification plan (+ sources
+  when research ran). CONFIRM explicitly.
 
 ## Fix
 

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

@@ -8,24 +8,19 @@ details on request.
 | Need | Answer |
 |------|--------|
 | Start anything | Type `/oris-flow` — it routes or shows the menu. The only command to remember. |
-| Try loops safely | `npx 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, Copilot; or `--agents cursor,claude,codex,copilot`). Reload the agent afterwards. |
 | Copilot / any other agent | Copilot Chat: enable `chat.promptFiles` once, then `/oris-flow`. Anything else that reads files: point it at `~/.oris/oris-flow.md`. |
 | Uninstall / reinstall | `npx oris-skills uninstall` / `npx oris-skills reinstall` (preview with `--dry-run`). |
-| Stop a loop | `npx oris-skills loop chat --action stop` |
-| Loop status | `npx oris-skills loop chat --action status` / `npx oris-skills loop list` |
 | Skill missing after install | Reload the agent; check `~/.oris/oris-skills/` exists; re-run install with `--force`. |
-| Hook not firing | `npx oris-skills loop verify --temp` self-checks the runtime; `npx oris-skills loop bootstrap` re-arms repo hooks. |
 | Change document language / chat verbosity | `/oris-flow` → Setup (settings live in `.oris-flow/settings.json`). |
 | Ultra-short answers | `/oris-flow` → Setup → set `responseStyle: caveman` — chat shrinks to maximum token density; documents stay complete. |
-| Edit a loop's behavior | Edit the files in `.oris-flow/loops/{slug}/prompts/` — the next pass obeys them. |
 
 Deeper docs: `docs/user-guide.md`, `docs/architecture.md` in the bundle (`~/.oris/oris-skills/`).
 
 ## Never
 
 - Tell users to paste secrets anywhere.
-- Dump internals (manifest JSON, hook mechanics) unless the user asks for technical
+- Dump internals (settings JSON, install layout) unless the user asks for technical
   troubleshooting.
 
 ## Done when

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

@@ -2,14 +2,14 @@
 
 Execute the confirmed plan — nothing more, nothing less.
 
-RULES: `references/conventions.md`.
+RULES: `references/conventions.md`. Research: `references/research.md`.
 
 ## Prepare
 
 1. FIND `{tasksRoot}/{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.
+2. READ `AGENTS.md`, 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).
 
@@ -22,6 +22,8 @@ RULES: `references/conventions.md`.
 ## While coding
 
 - FOLLOW existing project patterns; no new abstractions without need.
+- RESEARCH mid-build only when an external API resists (`references/research.md`) —
+  verify its current docs at the repo's pinned version; never guess signatures.
 - STAY inside the confirmed scope; park discoveries as notes, don't chase them.
 - ADD or update focused tests for the changed behavior.
 - CLEAN as you finish (`references/clean-code-checklist.md`): remove dead code, debug

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

@@ -10,7 +10,7 @@ RULES: `references/conventions.md`. Writes ONLY after the recap is confirmed.
 
 1. PURPOSE — the product in one sentence; it anchors every agent decision and opens AGENTS.md.
 2. TYPE — webapp | api | library | cli | monorepo. Drives layout and verify strategy.
-3. STACK — recommend from purpose + the user's existing repos (setup maps of sibling
+3. STACK — recommend from purpose + the user's existing repos (`AGENTS.md` of sibling
    projects when visible). Never impose.
 4. TEST RUNNER + LINT — the stack's default unless the user objects. Non-negotiable that
    one exists: agents need a red/green signal, not opinions.
@@ -42,10 +42,10 @@ RUN the test command and the lint command; SHOW real output — fail first, then
 
 ## Arm the flow
 
-1. RUN `npx oris-skills flow scan --repository-root <repo> --write` — manifest + maps;
-   the commands just verified → mark `confirmed`.
-2. RUN `npx oris-skills loop bootstrap --repository-root <repo>`.
-3. tasksRoot: `.oris-flow/tasks` (default — the project stays clean).
+1. The commands just verified are ALREADY in `AGENTS.md` (scaffold table) — that is the
+   whole record; nothing else to generate.
+2. WRITE `.oris-flow/settings.json` with the defaults (`references/settings.md`);
+   tasksRoot `.oris-flow/tasks` — the project stays clean.
 
 AFTER: offer discover the first feature (`skills/oris-flow/references/discover.md`) | stop.
 
@@ -61,4 +61,4 @@ AFTER: offer discover the first feature (`skills/oris-flow/references/discover.m
 - [ ] Purpose, type, stack, test runner confirmed before any write.
 - [ ] AGENTS.md sparse and commands-first; CONTEXT.md + ADR-0001 written.
 - [ ] Test + lint observed running (fail → pass shown).
-- [ ] Manifest written with confirmed commands; loop bootstrapped.
+- [ ] Verified commands recorded in `AGENTS.md`; settings written with defaults.

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

@@ -4,13 +4,17 @@ Interview the technical owner until another agent or developer could execute the
 without guessing.
 
 RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
+Research: `references/research.md`.
 
 ## 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. PREFER existing project patterns over new abstractions. Keep uncertainty visible.
+   safely), task docs, `AGENTS.md`, standards, code, tests, build scripts.
+2. RESEARCH external surfaces (`references/research.md`): the plan leans on a
+   third-party API, library, or service → verify against its current official docs at
+   the repo's pinned versions; sources go into the plan.
+3. PREFER existing project patterns over new abstractions. Keep uncertainty visible.
 
 ## Interview
 
@@ -36,6 +40,7 @@ ON generate → write `{tasksRoot}/{task}/implementation-plan.md` (language `art
 ### 2. …
 ## Verification    (commands, tests, what proves each step)
 ## Risks & open points
+## Sources         (only when research ran: link + what it settled)
 ## Change history  (date | source | change | reason)
 ```
 

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.

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

@@ -1,25 +1,20 @@
 # Oris Setup
 
-Make the repo cheap for agents to understand — manifest + maps + AI-readiness + loop
-readiness. ADAPT to what the repo IS; never force one structure. Writes ONLY after the
-user confirms the recap.
+Make the repo cheap for agents to understand — `AGENTS.md` as the one durable store,
+preferences in `.oris-flow/settings.json`, AI-readiness checked. ADAPT to what the repo
+IS; never force one structure. Writes ONLY after the user confirms the recap.
 
-RULES: `references/conventions.md`. Map format: `references/repo-map.md`.
+RULES: `references/conventions.md`. Settings: `references/settings.md`.
 IF the repo is empty or brand-new → route to `skills/oris-flow/references/new.md` instead.
 
 ## Mode
 
-IF `.oris-flow/manifest.json` exists → CHECK freshness first:
-`npx oris-skills flow scan --repository-root <repo> --check` — `fresh: true` → say so
-(a rescan would be a no-op); stale → the `changedFiles` list names the areas worth
-refreshing. THEN ask ONE question with these options:
-- refresh all (keeps `confirmed` values — scan merges, never overwrites them)
-- update one area (`--area <section>`)
-- review stale sections
+IF `AGENTS.md` (or `CLAUDE.md`) exists → this is a refresh: READ it first, then ask ONE
+question with these options:
+- update it from a fresh scan (scan below; edits merge in, confirmed facts stay)
+- review one section
 - show summary (no writes)
-- recreate from scratch
 - preferences → Local Preferences below; touches only `.oris-flow/settings.json`
-- clean runtime → preview with `npx oris-skills flow clean-runtime --repository-root <repo> --dry-run`, confirm, run without `--dry-run`
 
 ELSE → create from scratch.
 
@@ -27,8 +22,8 @@ ELSE → create from scratch.
 
 1. CONFIRM the target repository root (ask only if multiple roots are plausible).
 2. SCAN: `npx oris-skills flow scan --repository-root <repo> --json` — deterministic
-   baseline: `projectType`, stacks, commands (with confidence), sections, `truncated`
-   flag. Scan output = draft evidence, not truth.
+   baseline: `projectType`, stacks, commands (with confidence), areas, `truncated` flag.
+   Scan output = draft evidence, not truth; it writes nothing.
 3. IF `truncated: true` → say so, then per-area subagent scans are REQUIRED, not optional.
 4. FAN OUT parallel subagent scans (docs, frontend, backend/data, tests/build, local
    skills/rules) by DEFAULT whenever the repo has more than one of those areas —
@@ -43,14 +38,15 @@ SHOW compactly: detected project type + evidence, stacks, commands, AI-readiness
 Then WALK decisions ONE per turn — short explainer first, recommended answer first:
 
 - **Project type** — confirm `projectType` (webapp | api | library | cli | monorepo); it
-  drives which map sections matter and how criteria/verify observe behavior.
+  drives how criteria/verify observe behavior.
 - **Tasks root** — where Oris writes task documents. Default `.oris-flow/tasks` (keeps
   the project clean); keep `docs/tasks` only when the team already treats task docs as
-  project docs. Record in `setup.tasksRoot`.
-- **Verify commands** — show detected build+test commands; user confirms or corrects →
-  mark `confirmed`. They feed implement, verify, and loop VERIFIER; unconfirmed = a guess.
-- **Version control for `.oris-flow/`** — commit (team default) or gitignore. Task docs
-  follow the same choice.
+  project docs. Record in settings `tasksRoot`.
+- **Verify commands** — show detected build+test commands; user confirms or corrects.
+  Confirmed commands go into `AGENTS.md` — they feed implement, verify, and fix;
+  unconfirmed = a guess.
+- **Version control for `.oris-flow/`** — commit (team default) or gitignore. Record in
+  settings `versionControl`.
 
 ## 3. AI-readiness check
 
@@ -63,7 +59,7 @@ fix offer:
 | `CONTEXT.md` | domain glossary — the names agents must use for the product's concepts |
 | `docs/adr/` | decisions agents must not re-litigate |
 | project skills/rules (`.claude/skills`, `.cursor/rules`) | repeatable workflows as source of truth |
-| confirmed test/build commands | deterministic feedback loop — agents verify instead of guessing |
+| confirmed test/build commands in `AGENTS.md` | deterministic feedback — agents verify instead of guessing |
 
 ON explicit confirmation per file → scaffold the missing ones minimal.
 
@@ -71,32 +67,29 @@ ON explicit confirmation per file → scaffold the missing ones minimal.
 
 1. RECAP: repo, mode, project type, tasksRoot, files to write, AI-readiness gaps,
    choices. CONFIRM explicitly.
-2. WRITE `.oris-flow/manifest.json` + `.oris-flow/maps/**` (confirmed facts get
-   confidence `confirmed` so refresh preserves them), then apply:
-   - `npx oris-skills flow version-control --repository-root <repo> --mode commit|gitignore`
-   - `npx oris-skills loop bootstrap --repository-root <repo>` when adapter/hooks are missing.
-3. OFFER next: discovery | technical plan | loop (`npx oris-skills loop demo` for
-   first-timers) | refresh one area | stop.
+2. WRITE `AGENTS.md` (edit the file that exists — never create `AGENTS.md` beside
+   `CLAUDE.md`) + `.oris-flow/settings.json`, then apply:
+   `npx oris-skills flow version-control --repository-root <repo> --mode commit|gitignore`.
+3. OFFER next: discovery | technical plan | review one area | stop.
 
 ## Local Preferences
 
 1. READ `.oris-flow/settings.json` (defaults in `references/settings.md`).
 2. ASK what to change: artifactLanguage (document language, default `en`) | responseStyle
-   (standard | caveman — maximum token density in chat).
+   (standard | caveman — maximum token density in chat) | tasksRoot | versionControl.
 3. SHOW summary, CONFIRM, write ONLY the settings file.
 
 ## Never
 
 - Write before the recap is explicitly confirmed.
-- Overwrite `confirmed` values on refresh — the scan merges; missing evidence marks
-  stale, never deletes.
-- Overwrite existing agent files: edit the file that exists, never create `AGENTS.md`
-  beside `CLAUDE.md`.
-- Copy secrets into `.oris-flow/**`, docs, or loop state.
+- Overwrite existing agent files: edit the file that exists, never create a rival.
+- Bloat `AGENTS.md`: facts agents need on every request only — commands, structure
+  pointers, decisions; long reference material belongs in `docs/` or skills.
+- Copy secrets into `AGENTS.md`, `.oris-flow/**`, or docs.
 
 ## Done when
 
 - [ ] Mode chosen; scan ran before questions; decisions asked one at a time with explainers.
-- [ ] Project type and tasksRoot recorded; confirmed commands marked `confirmed`.
+- [ ] Confirmed commands and decisions recorded in `AGENTS.md`; preferences in settings.
 - [ ] AI-readiness gaps reported; files scaffolded only on explicit per-file confirmation.
 - [ ] Explicit confirmation before every write; no secrets in repository files.