oris-skills 2.0.0 → 2.2.0

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "oris-skills",
   "description": "Oris Skills: one entry point (/oris-flow), guided discovery-to-implementation flow, and self-tuning verified loops. Cross-model: Cursor, Claude Code, Codex.",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "author": {
     "name": "Davide Baldassarre"
   },
@@ -17,15 +17,6 @@
     "codex"
   ],
   "skills": [
-    "./skills/oris-flow",
-    "./skills/oris-flow-setup",
-    "./skills/oris-flow-discover",
-    "./skills/oris-flow-criteria",
-    "./skills/oris-flow-plan",
-    "./skills/oris-flow-implement",
-    "./skills/oris-flow-fix",
-    "./skills/oris-flow-docs",
-    "./skills/oris-loop",
-    "./skills/oris-help"
+    "./skills/oris-flow"
   ]
 }

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+## 2.2.0 - 2026-07-07
+
+- **One skill**: users see only `/oris-flow`. Every former skill (setup, new, discover, criteria, plan, implement, fix, verify, change, architecture, merge, docs, help, loop) is now a route reference inside `skills/oris-flow/references/`; the router reads the intent, picks ONE route, and applies its reference in the same chat. Loop prompt templates moved to `skills/oris-flow/templates/`.
+- **Full skill revision, one skeleton**: essence paragraph, leading-word moves (READ / ASK / WRITE / NEVER), an explicit `## Never` block, and a `## Done when` checklist in every route, plus a silence contract — machinery (map reads, freshness checks, write-back) is never narrated. The router's description carries the whole trigger vocabulary so the model auto-enters the flow from plain chat.
+- **Routing hardened**: new `Precedence` section settles the ambiguous calls explicitly (rethink beats build; change vs discover; fix vs implement; verify once vs loop; new vs setup) — one menu question maximum, then enter.
+- **Loops are four decisions**: the craft interview shrank from nine questions to four (GOAL, PROOF, SCOPE, STOP); roles, limits, models, and improve mode are stated defaults, changed only when the user objects or the work demands it.
+- **SHA-anchored maps + write-back**: the scan records `headSha`; `npx oris-skills flow scan --check` answers "is the map fresh?" in one cheap call (SHA compare + changed-file list, zero reads when fresh). Skills refresh only the touched areas in place and write proved facts back (`confirmed` commands, corrected sections) silently at natural pauses — write-back never blocks or slows the work.
+- **Caveman response style**: `orisFlow.responseStyle: "caveman"` in `~/.oris/settings.json` switches chat to maximum token density (answer first, no warm-up, fragments fine); generated documents, gate labels, receipts, and error reports are never compressed. Set via `/oris-flow` → Setup → language & profiles.
+- **Every agent, honestly**: installer now targets GitHub Copilot too (user prompt file in the VS Code profile — enable `chat.promptFiles` once, then `/oris-flow`), and writes a universal pointer at `~/.oris/oris-flow.md` so ANY file-reading agent can join with one sentence. Support matrix: in-chat loop hooks on Cursor and Claude Code; headless loops via Codex/Claude CLIs; the full flow everywhere.
+- **Leaner core**: the merge-conflict route was removed — agents handle it natively and it never belonged to the flow discipline. Loop economy tightened: default limit is now 10 passes, and the craft guidance states when a loop pays for itself (~3 expected passes; below that, implement or verify directly). Canonical subagents aligned with the hardened templates: executors stop instead of half-doing oversized actions, verifiers run checks before judging, debriefers may never weaken the verification bar.
+- **Style is enforced, not hoped for**: new `scripts/tests/test-skill-style.mjs` checks front-matter naming, trigger-bearing descriptions, Never + Done when blocks, a line budget, and that every routing handle resolves to a real bundle file.
+
+- **Harness independence**: task documents default to `.oris-flow/tasks/{task}/` (`setup.tasksRoot` in the manifest) — Oris no longer writes into the project's `docs/`; repos already using `docs/tasks` keep it via a recorded setup choice.
+- **Adaptive setup**: the scan detects `projectType` (webapp/api/library/cli/monorepo), derives build/test commands for .NET, Python, Go, and Rust (marked `inferred` until confirmed), walks breadth-first with a `truncated` flag, and honors `--area` for partial refreshes. Refresh merges instead of overwriting: `confirmed` sections, commands, and decisions survive; missing evidence marks them stale.
+- `oris-flow-setup` rewritten: explore → present findings → decisions one at a time with explainers; AI-readiness check (AGENTS.md, CONTEXT.md, ADRs, project skills, confirmed verify commands) with per-file scaffold offers.
+- New skills: `oris-flow-new` (bootstrap an AI-driven project: sparse commands-first AGENTS.md, CONTEXT.md glossary, ADR-0001, test+lint observed green, flow armed), `oris-flow-architecture` (deepening-opportunity review with visual HTML report in the OS temp dir), `oris-flow-merge` (intent-preserving merge/rebase conflict resolution).
+- **Loops default to 2 roles** (executor + verifier); doctor and debriefer are opt-in via `roles:` in loop.md. Without a doctor, the verifier verdict (`goalMet`) drives the state directly.
+- New flow skills: `oris-flow-verify` (one-shot acceptance-criteria verification with evidence report) and `oris-flow-change` (spec-change delta interview, homogeneous doc updates, `CH-xxx` change log). Implement/fix now route verification to `oris-flow-verify` instead of suggesting a loop.
+- Canonical doctor decision enum (`continue|advance|complete|ask-user|propose-patch|blocked`) unified across agent specs, templates, and the headless runner; `ask-user` now pauses the loop instead of silently killing it.
+- `limits.maxNoProgress` is enforced at runtime (stop hook + headless runner + `set-state --progress yes|no`); previously declared but never checked.
+- Read-only roles (verifier, doctor) run without write access in headless mode.
+- Stop hook: Cursor auto-detection fixed (payloads carrying both `conversation_id` and `session_id`); exhausted limits and corrupt state now surface a user-visible message on Claude Code.
+- Executor gate literal `ORIS LOOP ACTIVE` ships in the executor prompt template; role output is a ```json fenced block (robust extraction in the headless runner).
+- All CLI commands in skills, templates, and docs use `npx oris-skills …` (the CLI is not installed globally).
+- Installer now generates Cursor/Claude/Codex loop-agent adapters into the detected agent homes.
+- `{task}` slug convention defined once in `references/doc-policy.md`; `references/questions.md` merged into `references/conventions.md`; clean-code checklist trimmed to its implement/fix use.
+- Removed dead surface: `repairCycles`, `--node-only`/`test:node`/`npm run validate` duplication, empty `scripts/maintenance/`, unused `.gitattributes` rules.
+
+## 2.0.0 - 2026-07-04
+
+- Public npm package (MIT): `npx oris-skills@latest install`, multi-agent installer for Cursor, Claude Code, and Codex; bundle moved to `~/.oris/`.
+- Flattened layout: `skills/`, `references/`, `agents/`; 10 essential skills, single entry point `/oris-flow` with inline routing.
+- Loop document schemaVersion 2: `approved` gate, per-role `models` (`inherit` | adapter alias | model id), `improve.mode: auto|propose`.
+- Role prompts moved to per-loop editable files `prompts/{orchestrator,executor,verifier,doctor,debriefer}.md`; orchestrator prompt no longer hardcoded in the stop hook.
+- Self-tuning loops: in `auto` mode the debriefer rewrites prompt files between passes and archives old versions to `history/`.
+- Cross-model triggers: shared stop hook now speaks Cursor (`followup_message`) and Claude Code (`decision: block`); new headless runner `oris-skills loop run --agent codex|claude` (one CLI process per role).
+- Learnability: `oris-skills loop demo` (sandboxed tutorial loop), `oris-skills loop dry-run` (preview the injected pass message).
+- Skill texts rewritten with leading words (~60% shorter); shared rules centralized in `references/conventions.md`.
+- Removed: org-specific MCP config, DevOps story skills, scaffold/service standards, utility skills, demo showcase, legacy fallbacks.
+
+## 1.0.0 - 2026-06-29
+
+- Release Oris Skills 1.0 with Node-based install, validation, packaging, and cross-platform CI.
+- Add Oris Loop 1.0 with project-local `.oris-flow/` storage, schemaVersion 1 loop documents, compact receipts, Doctor proposals, and subagent-first orchestration.
+- Add canonical subagent contracts for executor, verifier, Doctor, and debriefer, plus generated Cursor, Claude, and Codex adapters.
+- Add clean Node CLI entrypoints through `oris-skills install`, `oris-skills validate`, `oris-skills doctor`, and `oris-skills loop`.

package/README.md

@@ -1,66 +1,114 @@
 # Oris Skills
 
-One entry point, a guided software flow, and self-tuning verified loops — for **Cursor**, **Claude Code**, and **Codex**.
+**One command. A disciplined software flow. Loops that verify themselves.**
+For Cursor, Claude Code, Codex, GitHub Copilot — and any agent that can read a file.
 
 ```bash
 npx oris-skills@latest install
 ```
 
-The installer detects your agents (`~/.cursor`, `~/.claude`, `~/.codex`) or takes `--agents cursor,claude,codex`. Reload your agent, then type **`/oris-flow`** — the only command you need to remember.
+Reload your agent, then type **`/oris-flow`**. That is the entire user manual.
 
-## What you get
+## The idea
 
-**`/oris-flow`** routes any software-flow request to the right skill in the same chat:
+AI agents are brilliant executors and terrible colleagues: they guess requirements,
+declare victory without evidence, and forget everything between sessions. Oris fixes the
+colleague part with three rules baked into every interaction:
 
-| Route | Purpose |
-|-------|---------|
-| setup | map the repository into `.oris-flow/` so agents stop re-scanning |
-| discover | business-first interview → `functional-analysis.md` |
-| criteria | verifiable acceptance criteria → `acceptance-criteria.md` |
-| plan | technical interview → `implementation-plan.md` |
-| implement / fix | execute the plan, or the smallest safe bug fix |
-| loop | repeat work until verified, with subagents and receipts |
-| docs / help | keep task docs aligned; explain Oris |
+1. **Interview before writing.** Nothing lands in your repo — no document, no code — before
+   you explicitly approve it. One question per turn, recommended answer first.
+2. **Evidence before done.** "It works" means a command ran and its output says so.
+   Verification is independent from execution: the agent that writes code never grades
+   its own homework.
+3. **Remember without slowing down.** The repo map is anchored to a commit SHA; one cheap
+   check answers "is my knowledge fresh?", and only the changed areas are re-read.
+   Bookkeeping is silent — you see questions, answers, and results, never the machinery.
+
+## One skill, every route
 
-**Oris loops** run the cycle *observe → one bounded action → independent verify → record → repeat/stop* with four roles (executor, verifier, doctor, debriefer), each driven by **an editable prompt file**:
+`/oris-flow` reads your intent and enters the right route in the same chat — no other
+command exists. Say "the login button does nothing" and you are in **fix**; say "the
+client changed their mind about invoicing" and you are in **change**.
+
+```text
+        idea ──► discover ──► criteria ──► plan ──► implement ──► verify
+                    │                                    ▲            │
+                    └── change (spec moved) ─────────────┘        fix ◄┘ (red)
+```
+
+| Route | You get |
+|-------|---------|
+| **setup** | the repo mapped into `.oris-flow/` (type, commands, structure) so agents stop re-scanning; AI-readiness check |
+| **new** | a greenfield project born agent-native: sparse `AGENTS.md`, domain glossary, first ADR, red→green test observed |
+| **discover** | business-first interview → `functional-analysis.md` |
+| **criteria** | observable, stable-ID acceptance criteria → `acceptance-criteria.md` |
+| **plan** | technical interview → `implementation-plan.md` with bounded, verifiable steps |
+| **implement / fix** | the plan executed step by step, or the smallest safe bug fix — root cause first |
+| **verify** | every criterion checked against the *real* product, with evidence → `verification-report.md` |
+| **change** | spec delta interviewed, **all** documents updated in one approved pass → `change-log.md` |
+| **loop** | repeat-until-verified work with subagents and receipts (below) |
+| **architecture / docs / help** | deepening review, doc alignment, answers |
+
+Every route follows one skeleton — what to do, what **Never** to do, and a **Done when**
+checklist — enforced by the test suite, so the discipline survives refactors.
+
+## Loops: repeat until *proven*
+
+A loop is four decisions — **GOAL** (what done looks like), **PROOF** (how a pass proves
+it), **SCOPE** (what it may touch), **STOP** (when to quit) — everything else is a sane
+default. Each pass: *observe → one bounded action → independent verify → receipt →
+repeat or stop.*
 
 ```text
 .oris-flow/loops/{slug}/
-  loop.md        contract: goal, scope, limits, per-role models, improve mode
-  prompts/       orchestrator.md executor.md verifier.md doctor.md debriefer.md  ← edit freely
-  context.md  receipts/  proposals/  history/
+  loop.md        the approved contract: goal, scope, roles, limits, models
+  prompts/       one editable file per role — the next pass obeys your edits
+  receipts/      one compact evidence record per pass
+  context.md  proposals/  history/
 ```
 
-- **Per-role models** — `models:` in `loop.md`: `inherit` (session model), an adapter alias, or a platform model id.
-- **Self-tuning** — `improve.mode: auto` lets the debriefer rewrite the prompt files between passes (old versions archived in `history/`); scope and limits always require your approval.
-- **Cross-platform triggers** — Cursor stop hook, Claude Code Stop hook (same chat continues automatically), or `oris-skills loop run --agent codex|claude` for headless/CI where each role is a separate CLI process.
+- **Two roles by default** — executor acts, verifier checks with evidence. Doctor
+  (multi-phase stop logic) and debriefer (learns across passes) are opt-in.
+- **Prompts are yours** — plain markdown files; edit them mid-run and the loop adapts.
+  With `improve.mode: auto` the debriefer tunes them itself (old versions archived);
+  scope and limits always require your approval.
+- **No false victories** — an exhausted limit, a missing tool, or an unverifiable claim
+  is never "success". Progress is counted only when the verifier confirms it.
+- **Cross-platform** — Cursor and Claude Code continue the same chat via stop hooks;
+  Codex/CI runs headless: `npx oris-skills loop run --loop <slug> --agent codex|claude`.
+  Copilot and every other agent get the full flow via prompt pointers; point any
+  file-reading agent at `~/.oris/oris-flow.md` and it is in.
 
-## Try a loop in 3 minutes
+Try it safely in three minutes — the demo touches only its own sandbox folder:
 
 ```bash
-oris-skills loop demo                    # creates a sandboxed tutorial loop
-oris-skills loop dry-run --loop oris-demo  # preview the exact pass message — runs nothing
-oris-skills loop chat --action start --loop oris-demo   # then end the chat turn; the hook does the rest
+npx oris-skills loop demo                       # 1. create the tutorial loop
+npx oris-skills loop dry-run --loop oris-demo   # 2. preview the exact pass — runs nothing
+npx oris-skills loop chat --action start --loop oris-demo   # 3. arm it, end your turn
 ```
 
-Stop anytime: `oris-skills loop chat --action stop`. Self-check the runtime: `oris-skills loop verify --temp`.
+Stop anything, anytime: `npx oris-skills loop chat --action stop`.
+
+## Tuning
+
+Settings live in `~/.oris/settings.json` (`/oris-flow` → Setup → language & profiles):
+chat and document language (`en`/`it`), test profiles, and `responseStyle: "caveman"` —
+chat shrinks to maximum token density while documents and safety gates stay complete.
 
 ## Repository layout
 
 | Path | Purpose |
 |------|---------|
-| `skills/` | the 10 Oris skills (`SKILL.md` each) |
-| `skills/oris-loop/templates/` | role prompt templates copied into new loops |
-| `references/` | shared contracts and JSON schemas |
-| `agents/` | canonical subagent definitions (Cursor/Claude/Codex adapters generated) |
+| `skills/oris-flow/` | the one skill: router (`SKILL.md`), route references, loop prompt templates |
+| `references/` | shared contracts (conventions, loop contract, doc policy) and JSON schemas |
+| `agents/` | canonical subagent definitions (platform adapters generated at install) |
 | `scripts/` | Node CLI, loop runtime, installer, tests |
 | `docs/` | architecture, user guide, maintainer guide |
 
 ## Maintainers
 
 ```bash
-npm test               # cross-platform Node test suite
-npm run validate
+npm test               # cross-platform Node test suite (includes the skill-style gate)
 npm run verify:loop    # end-to-end stop-hook simulation (cursor + claude)
 ```
 

package/agents/oris-loop-debriefer.md

@@ -13,6 +13,7 @@ Rules:
 3. improve.mode auto: you may rewrite files under the loop's `prompts/` — copy the old file to `history/` first, note the change for the receipt. One improvement per debrief.
 4. improve.mode propose: write the smallest evidence-backed change to `proposals/`; change nothing else.
 5. NEVER touch loop.md scope, limits, permissions, or verification — always a proposal.
+   NEVER weaken verification to make passes green — fix the loop, not the bar.
 6. Keep the summary compact.
 
 Output:

package/agents/oris-loop-doctor.md

@@ -22,7 +22,7 @@ Output:
 ```json
 {
   "role": "doctor",
-  "decision": "continue|complete|block|ask-user|propose-patch",
+  "decision": "continue|advance|complete|ask-user|propose-patch|blocked",
   "diagnosis": "",
   "evidence": "",
   "patchSummary": "",

package/agents/oris-loop-executor.md

@@ -10,12 +10,15 @@ Rules:
 
 1. Verify the task includes `ORIS LOOP ACTIVE`.
 2. Read only the loop definition, context, and files in declared scope.
-3. Perform exactly one bounded action.
+3. Perform exactly one bounded action. Re-read the fresh state of every file
+   you touch before editing it. The action proves bigger than bounded → stop
+   and return blocked with what you found; half-done work is worse than none.
 4. Preserve unrelated user work.
 5. Do not commit, push, deploy, write DevOps, send external messages, expose
    credentials, or edit `.oris-flow/runtime/**`.
 6. Return a compact result with changed files, claim, risk, and suggested
-   verifier check.
+   verifier check. claim = what changed + the exact command or observation
+   that proves it.
 
 Output:
 

package/agents/oris-loop-verifier.md

@@ -8,10 +8,11 @@ You are the Oris Loop verifier.
 
 Rules:
 
-1. Do not trust the executor claim without evidence.
+1. Do not trust the executor claim without evidence. Run the checks FIRST,
+   judge after — a claim you could not check is inconclusive, never pass.
 2. Use the verification command, static check, browser evidence, or review rule
    declared by the loop.
-3. Do not edit product files.
+3. Do not edit product files — you only observe, never fix.
 4. Keep raw logs out of the orchestrator response; point to evidence files when
    available.
 5. Report pass, fail, blocked, or inconclusive.
@@ -22,6 +23,7 @@ Output:
 {
   "role": "verifier",
   "state": "pass|fail|blocked|inconclusive",
+  "goalMet": false,
   "summary": "",
   "evidence": "",
   "evidencePath": "",
@@ -29,3 +31,5 @@ Output:
   "nextRecommendation": ""
 }
 ```
+
+`goalMet` is true only when the loop goal itself is satisfied, not just this pass.

package/docs/architecture.md

@@ -5,11 +5,11 @@ Read this before explaining or changing the project.
 ## Shape
 
 ```text
-skills/       10 skills; oris-flow is the router, oris-loop the loop system
-references/   shared contracts (conventions, loop-contract, settings, questions, repo-map, doc-policy) + schemas
-agents/       canonical subagent definitions; adapters generated per platform
-scripts/      Node CLI (oris-skills.mjs), loop runtime, installer, tests
-docs/         this file, user-guide, maintainer-guide, distribution
+skills/oris-flow/   the ONE user-facing skill: SKILL.md routes; references/ hold every route (setup…loop); templates/ hold the loop role prompts
+references/         shared contracts (conventions, loop-contract, settings, repo-map, doc-policy, clean-code-checklist) + JSON schemas
+agents/             canonical subagent definitions; adapters generated per platform
+scripts/            Node CLI (oris-skills.mjs), loop runtime, installer, tests
+docs/               this file, user-guide, maintainer-guide, distribution
 ```
 
 ## Principles
@@ -17,10 +17,12 @@ docs/         this file, user-guide, maintainer-guide, distribution
 - ONE source of truth per fact: contracts live in `references/`, skills point at them.
 - Skills use leading words (READ / ASK / NEVER / IF) and stay short; shared rules live in `references/conventions.md`.
 - Everything repeatable lives in the target project under `.oris-flow/`; the bundle at `~/.oris/oris-skills/` owns scripts and templates.
+- Oris never dirties the project: task documents default to `.oris-flow/tasks/` (`setup.tasksRoot` in the manifest; legacy `docs/tasks` supported).
 - Loop prompts are per-loop editable files (`prompts/*.md`), never hardcoded in scripts.
 
 ## Runtime
 
-- `/oris-flow` routes; destination skills own their gates.
+- `/oris-flow` routes; each route reference owns its gates.
+- The repo map is SHA-anchored: `flow scan --check` compares `headSha` to HEAD; only touched areas are refreshed; write-back is silent and never blocks work.
 - Loop triggers: Cursor stop hook + Claude Stop hook (shared `scripts/loop/oris-loop-stop.mjs`, `--platform` switch), headless `loop run` for Codex/CI.
-- State machine: `.oris-flow/runtime/chat-active.json`, managed only by `oris-skills loop chat`.
+- State machine: `.oris-flow/runtime/chat-active.json`, managed only by `npx oris-skills loop chat`.

package/docs/distribution.md

@@ -20,7 +20,7 @@ The installer detects Cursor / Claude Code / Codex from `~/.cursor`, `~/.claude`
 ~/.codex/prompts/<name>.md  Codex prompts pointing to the bundled SKILL.md
 ```
 
-Project assets live only in each repository's `.oris-flow/` (adapter, loops, runtime) plus thin hook wrappers in `.cursor/hooks/` and `.claude/hooks/` written by `oris-skills loop bootstrap`.
+Project assets live only in each repository's `.oris-flow/` (adapter, loops, runtime) plus thin hook wrappers in `.cursor/hooks/` and `.claude/hooks/` written by `npx oris-skills loop bootstrap`.
 
 ## Uninstall / reinstall
 

package/docs/maintainer-guide.md

@@ -6,12 +6,13 @@ Use when improving Oris Skills itself. Keep changes tiny; update the canonical f
 
 | Change | Canonical place |
 |--------|-----------------|
-| User-facing explanation | `docs/user-guide.md`, `skills/oris-help/SKILL.md` |
+| User-facing explanation | `docs/user-guide.md`, `skills/oris-flow/references/help.md` |
 | Project structure | `docs/architecture.md` |
 | Routing | `skills/oris-flow/SKILL.md` (route table) |
-| Shared interaction rules | `references/conventions.md`, `references/questions.md` |
-| Loop behavior | `references/loop-contract.md`, `skills/oris-loop/` |
-| Loop prompt templates | `skills/oris-loop/templates/` |
+| Shared interaction rules | `references/conventions.md` |
+| Task doc standards | `references/doc-policy.md` ({task} slug, per-doc ownership) |
+| Loop behavior | `references/loop-contract.md`, `skills/oris-flow/references/loop*.md` |
+| Loop prompt templates | `skills/oris-flow/templates/` |
 | Loop runtime | `scripts/loop/` |
 | Install lifecycle | `scripts/oris-skills.mjs`, `scripts/install/` |
 | Tests | `scripts/tests/` |
@@ -20,7 +21,6 @@ Use when improving Oris Skills itself. Keep changes tiny; update the canonical f
 
 ```bash
 npm test
-npm run validate
 npm run verify:loop
 ```
 

package/docs/user-guide.md

@@ -3,29 +3,32 @@
 Install once, remember one command:
 
 ```bash
-npx oris-skills@latest install     # detects Cursor / Claude Code / Codex
+npx oris-skills@latest install     # detects Cursor / Claude Code / Codex / Copilot (VS Code)
 ```
 
-Then type **`/oris-flow`** in your agent chat. It routes your request or shows a short menu (setup, discovery, criteria, plan, implement/fix, loop, docs, help). On Codex use the installed `/oris-flow` prompt.
+Then type **`/oris-flow`** in your agent chat. It routes your request or shows a short menu (setup, new project, discovery, criteria, plan, implement/fix, verify, spec change, loop, architecture review, docs, help). On Codex use the installed `/oris-flow` prompt; on Copilot Chat use `/oris-flow` too (enable the VS Code setting `chat.promptFiles` once). Any other agent: tell it to read `~/.oris/oris-flow.md`.
+
+The flow in one line: **discover → criteria → plan → implement → verify**, with `fix` for bugs, `change` when the spec changes mid-flight (it updates all task docs together and logs `CH-xxx` history), and `loop` for work that must repeat until verified. `new` bootstraps an AI-driven project from scratch; `architecture` maps deepening/refactor opportunities. Task documents live in `.oris-flow/tasks/` by default — your project's own docs stay untouched.
 
 ## Loops in short
 
 A loop repeats: one bounded action → independent verification → receipt → continue or stop.
+Building one takes four decisions — goal, proof, scope, stop — everything else defaults.
 
 Learn it safely:
 
 ```bash
-oris-skills loop demo                      # sandboxed tutorial loop
-oris-skills loop dry-run --loop oris-demo  # preview, nothing runs
-oris-skills loop chat --action start --loop oris-demo   # arm, then end the chat turn
+npx oris-skills loop demo                      # sandboxed tutorial loop
+npx oris-skills loop dry-run --loop oris-demo  # preview, nothing runs
+npx oris-skills loop chat --action start --loop oris-demo   # arm, then end the chat turn
 ```
 
 Control it:
 
 ```bash
-oris-skills loop list            # what exists
-oris-skills loop chat --action status
-oris-skills loop chat --action stop
+npx oris-skills loop list            # what exists
+npx oris-skills loop chat --action status
+npx oris-skills loop chat --action stop
 ```
 
 Tune it: edit the files in `.oris-flow/loops/{slug}/prompts/` — the next pass obeys them. With `improve.mode: auto` in `loop.md`, the loop tunes those prompts itself and archives old versions in `history/`.
@@ -39,4 +42,4 @@ npx oris-skills reinstall
 ```
 
 Uninstall removes only Oris-owned paths (including legacy locations); preview with `--dry-run`.
-Settings (language, test profiles): `~/.oris/settings.json`, edited via `/oris-flow` → Setup.
+Settings (language, test profiles, `responseStyle: caveman` for ultra-short chat): `~/.oris/settings.json`, edited via `/oris-flow` → Setup.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oris-skills",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "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",
@@ -16,6 +16,7 @@
     "docs",
     ".cursor-plugin",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "keywords": [
@@ -37,8 +38,6 @@
   },
   "scripts": {
     "test": "node scripts/tests/run-all-tests.mjs",
-    "test:node": "node scripts/tests/run-all-tests.mjs --node-only",
-    "validate": "node scripts/oris-skills.mjs validate",
     "scan": "node scripts/flow/oris-flow-scan.mjs --json",
     "install:dry-run": "node scripts/install/install-user-skills.mjs --dry-run",
     "verify:loop": "node scripts/loop/oris-loop-verify.mjs --temp"

package/references/clean-code-checklist.md

@@ -1,107 +1,20 @@
-# Clean Code Checklist
-
-Use this reference during `/oris-flow-clean-code` audits. Investigate before concluding; absence in one file is not proof of dead code.
-
-## Analysis Order
-
-1. Resolve scope from task folder, recent diff, or user-provided section.
-2. Read project conventions: README, `docs/**`, `.cursor/rules/**`, `.cursor/skills/**`, linter config, and formatting rules.
-3. List scoped files and their relationships: imports, tests, config, translations, DI registration, routing, and feature flags.
-4. Audit category by category below.
-5. Record only findings with file, line, severity, problem, and proposed fix.
-
-## In Scope
-
-### Dead and unused code
-
-- Unused imports, variables, parameters, private methods, classes, constants, and files
-- Unreachable branches left from earlier attempts
-- Commented-out code blocks that are not active documentation
-- Feature flags or toggles that no longer gate anything
-- Orphan tests for removed behavior
-
-Verify with cross-file search, DI/container registration, reflection, dynamic imports, string-based dispatch, routing tables, Razor/tag helpers, code generation, and framework conventions before marking dead.
-
-### Duplication
-
-- Copy-pasted logic with only naming changes
-- Parallel helpers that should be one function
-- Repeated validation, mapping, or query patterns in the same feature area
-
-Prefer the existing project abstraction level. Do not introduce new shared layers for one-off duplication unless the user approves.
-
-### Abandoned attempts
-
-- Half-finished branches with TODO/FIXME/HACK tied to the current feature
-- Alternate implementations left in place after a chosen approach
-- Debug logging, temporary guards, or experimental code paths no longer needed
-- Stale comments describing behavior that no longer exists
-
-### Typos and wording
-
-- Misspellings in user-visible strings when the task scope includes them
-- Wrong identifiers that reduce readability but are not public API contracts
-- Misleading names for variables or methods introduced in the current work
-
-Do not rename public API surface, routes, database fields, or serialized property names unless the user explicitly approves.
-
-### Obvious inefficiencies
-
-- Duplicate queries or remote calls inside loops
-- Repeated allocations or parsing in hot paths within the scoped change
-- Redundant null checks, casts, or conversions introduced during iteration
-
-Flag only clear wins with low regression risk. Do not micro-optimize unrelated code.
-
-### Style and format
-
-Apply only when conventions are explicit in project docs or `.cursor/rules`:
-
-- Naming patterns
-- Import/order rules
-- Formatter or analyzer expectations
-- File layout conventions
-
-Avoid formatting-only churn outside the scoped files.
-
-## Out of Scope
-
-- Bug fixes or behavior corrections - use `/oris-flow-fix`
-- Architectural deepening, module consolidation, or seam redesign
-- Large refactors, API redesign, or cross-feature rewrites
-- DevOps, commits, branches, pull requests, or documentation updates
-- Rewriting tests to change behavior instead of removing obsolete coverage
-
-## Evidence Bar
-
-Before reporting a finding:
-
-- Search references and call sites in the scoped area and direct dependents
-- Check whether tests, config, or registration files still require the symbol
-- For dead code candidates, note what search was performed
-- For duplication, cite both locations and why consolidation is safe
-- For abandoned attempts, tie the finding to the current feature or recent diff when possible
-
-## Report Shape
-
-Keep chat output compact:
-
-```text
-Blue src/Feature/Foo.cs:42 - unused import `System.Linq`
-Yellow src/Feature/Bar.cs:18-31 - duplicated validation with Baz.cs:44-57 - extract local helper
-Red src/Feature/Qux.cs:90 - private method appears unused but referenced via reflection in Registry.cs
-```
-
-## Post-Fix Recap Shape
-
-After approved fixes, show a short bulleted recap in settings `uiLanguage`:
-
-```text
-- Removed unused imports in Foo.cs and Bar.cs - no references remained after cross-file search.
-- Deleted commented fallback block in Qux.cs - superseded by current handler.
-- Aligned member order in Baz.cs to project rule X.
-```
-
-## Last updated
-
-2026-06-23
+# Clean Code Checklist
+
+Used by `oris-flow-implement` and `oris-flow-fix` while closing work: clean what YOU introduced, in the files you touched. Investigate before concluding; absence in one file is not proof of dead code.
+
+## Check, in the touched scope only
+
+- **Dead code you left behind**: unused imports, variables, parameters, helpers; unreachable branches from earlier attempts; commented-out code that is not documentation.
+- **Abandoned attempts**: half-finished alternates, debug logging, temporary guards, TODO/FIXME tied to this change, stale comments describing behavior that no longer exists.
+- **Duplication you introduced**: copy-pasted logic that should be one function — at the project's existing abstraction level, no new shared layers without approval.
+- **Naming and wording**: misleading identifiers introduced in this work; misspellings in user-visible strings when in scope. NEVER rename public API surface, routes, DB fields, or serialized names without explicit approval.
+- **Obvious inefficiencies**: duplicate queries/calls in loops, repeated parsing in hot paths — only clear wins with low regression risk.
+- **Style**: match the file's existing conventions (naming, import order, layout). No formatting-only churn outside touched files.
+
+## Evidence bar
+
+Before removing anything: search references and call sites (including DI registration, reflection, dynamic imports, routing, code generation, framework conventions). Tests, config, or registration may still require the symbol.
+
+## Never here
+
+Bug fixes (→ `skills/oris-flow/references/fix.md`), architectural redesign, cross-feature refactors, DevOps, drive-by cleanup of code you did not touch.