oris-skills 2.0.0

package/.cursor-plugin/plugin.json

@@ -0,0 +1,31 @@
+{
+  "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",
+  "author": {
+    "name": "Davide Baldassarre"
+  },
+  "license": "MIT",
+  "keywords": [
+    "oris",
+    "skills",
+    "workflow",
+    "flow",
+    "loop",
+    "cursor",
+    "claude",
+    "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"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davide Baldassarre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# Oris Skills
+
+One entry point, a guided software flow, and self-tuning verified loops — for **Cursor**, **Claude Code**, and **Codex**.
+
+```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.
+
+## What you get
+
+**`/oris-flow`** routes any software-flow request to the right skill in the same chat:
+
+| 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 |
+
+**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**:
+
+```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/
+```
+
+- **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.
+
+## Try a loop in 3 minutes
+
+```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
+```
+
+Stop anytime: `oris-skills loop chat --action stop`. Self-check the runtime: `oris-skills loop verify --temp`.
+
+## 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) |
+| `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 run verify:loop    # end-to-end stop-hook simulation (cursor + claude)
+```
+
+Node.js 20+. License: MIT.

package/agents/oris-loop-debriefer.md

@@ -0,0 +1,29 @@
+---
+name: oris-loop-debriefer
+description: Learns across Oris Loop receipts and tunes the loop prompts (improve.mode auto) or proposes changes (propose). Use after passes complete.
+readonly: false
+---
+
+You are the Oris Loop debriefer.
+
+Rules:
+
+1. Use receipts and referenced evidence only; no durable pattern from a single weak signal.
+2. Separate design problems from execution, environment, verifier, and changed-goal problems.
+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.
+6. Keep the summary compact.
+
+Output:
+
+```json
+{
+  "role": "debriefer",
+  "outcome": "keep|tuned|proposed|execution-issue|environment-blocked|inconclusive",
+  "insight": "",
+  "changedFiles": [],
+  "proposalPath": "",
+  "nextAction": ""
+}
+```

package/agents/oris-loop-doctor.md

@@ -0,0 +1,32 @@
+---
+name: oris-loop-doctor
+description: Diagnoses Oris Loop run evidence and decides whether to continue, block, ask the user, or propose a minimal loop patch.
+readonly: true
+---
+
+You are the Oris Loop Doctor.
+
+Rules:
+
+1. Diagnose from receipts and verifier evidence, not confidence.
+2. Distinguish loop design issues from execution mistakes, verifier issues,
+   environment failures, changed goals, and insufficient evidence.
+3. Do not patch the loop directly.
+4. Propose the smallest loop change only when evidence shows the loop design is
+   the problem.
+5. Require approval for changes to scope, authority, commands, paths, stop
+   rules, risk, credentials, or external systems.
+
+Output:
+
+```json
+{
+  "role": "doctor",
+  "decision": "continue|complete|block|ask-user|propose-patch",
+  "diagnosis": "",
+  "evidence": "",
+  "patchSummary": "",
+  "approvalRequired": true,
+  "nextAction": ""
+}
+```

package/agents/oris-loop-executor.md

@@ -0,0 +1,32 @@
+---
+name: oris-loop-executor
+description: Performs one bounded action for an approved Oris Loop pass. Use only when the orchestrator provides loop scope, current phase, allowed paths, and verification intent.
+readonly: false
+---
+
+You are the Oris Loop executor.
+
+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.
+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.
+
+Output:
+
+```json
+{
+  "role": "executor",
+  "state": "claimed|blocked",
+  "summary": "",
+  "changedFiles": [],
+  "claim": "",
+  "evidenceHint": "",
+  "blocker": ""
+}
+```

package/agents/oris-loop-verifier.md

@@ -0,0 +1,31 @@
+---
+name: oris-loop-verifier
+description: Independently verifies an Oris Loop executor claim using declared project evidence. Use after an executor reports a bounded action.
+readonly: true
+---
+
+You are the Oris Loop verifier.
+
+Rules:
+
+1. Do not trust the executor claim without evidence.
+2. Use the verification command, static check, browser evidence, or review rule
+   declared by the loop.
+3. Do not edit product files.
+4. Keep raw logs out of the orchestrator response; point to evidence files when
+   available.
+5. Report pass, fail, blocked, or inconclusive.
+
+Output:
+
+```json
+{
+  "role": "verifier",
+  "state": "pass|fail|blocked|inconclusive",
+  "summary": "",
+  "evidence": "",
+  "evidencePath": "",
+  "failureSignal": "",
+  "nextRecommendation": ""
+}
+```

package/docs/architecture.md

@@ -0,0 +1,26 @@
+# Oris Skills Architecture
+
+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
+```
+
+## Principles
+
+- 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.
+- Loop prompts are per-loop editable files (`prompts/*.md`), never hardcoded in scripts.
+
+## Runtime
+
+- `/oris-flow` routes; destination skills own their gates.
+- 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`.

package/docs/distribution.md

@@ -0,0 +1,38 @@
+# Oris Skills Distribution
+
+## Channel
+
+Public npm package `oris-skills` (MIT). Users install with:
+
+```bash
+npx oris-skills@latest install
+```
+
+The installer detects Cursor / Claude Code / Codex from `~/.cursor`, `~/.claude`, `~/.codex`, or takes `--agents`. Node.js 20+.
+
+## Installed assets
+
+```text
+~/.oris/oris-skills/        bundle: scripts, skills, references, agents, docs
+~/.oris/settings.json       user settings (created only if missing)
+~/.cursor/skills/<name>/    Cursor skills (marker-managed)
+~/.claude/skills/<name>/    Claude Code skills (marker-managed)
+~/.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`.
+
+## Uninstall / reinstall
+
+```bash
+npx oris-skills uninstall --dry-run   # preview
+npx oris-skills uninstall             # removes Oris-owned paths incl. legacy ~/.cursor locations
+npx oris-skills reinstall
+```
+
+## Publish
+
+1. Versions aligned in `package.json` + `.cursor-plugin/plugin.json`; CHANGELOG updated.
+2. `npm test` green on CI (Windows/Linux/macOS).
+3. `npm publish` (publishConfig.access = public).
+4. Tag the release.

package/docs/maintainer-guide.md

@@ -0,0 +1,32 @@
+# Oris Skills Maintainer Guide
+
+Use when improving Oris Skills itself. Keep changes tiny; update the canonical file instead of duplicating an explanation.
+
+## Ownership
+
+| Change | Canonical place |
+|--------|-----------------|
+| User-facing explanation | `docs/user-guide.md`, `skills/oris-help/SKILL.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/` |
+| Loop runtime | `scripts/loop/` |
+| Install lifecycle | `scripts/oris-skills.mjs`, `scripts/install/` |
+| Tests | `scripts/tests/` |
+
+## Validate
+
+```bash
+npm test
+npm run validate
+npm run verify:loop
+```
+
+## Release
+
+1. Bump `package.json` + `.cursor-plugin/plugin.json` versions together.
+2. Update `CHANGELOG.md`.
+3. `npm test` green on CI (Windows/Linux/macOS).
+4. `npm publish` (public, MIT).

package/docs/user-guide.md

@@ -0,0 +1,42 @@
+# Oris Skills User Guide
+
+Install once, remember one command:
+
+```bash
+npx oris-skills@latest install     # detects Cursor / Claude Code / Codex
+```
+
+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.
+
+## Loops in short
+
+A loop repeats: one bounded action → independent verification → receipt → continue or stop.
+
+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
+```
+
+Control it:
+
+```bash
+oris-skills loop list            # what exists
+oris-skills loop chat --action status
+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/`.
+
+## Install lifecycle
+
+```bash
+npx oris-skills install [--agents cursor,claude,codex] [--force]
+npx oris-skills uninstall [--dry-run]
+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.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "oris-skills",
+  "version": "2.0.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",
+  "type": "module",
+  "bin": {
+    "oris-skills": "scripts/oris-skills.mjs"
+  },
+  "files": [
+    "scripts",
+    "skills",
+    "references",
+    "agents",
+    "docs",
+    ".cursor-plugin",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "oris",
+    "skills",
+    "agent",
+    "workflow",
+    "loop",
+    "cursor",
+    "claude",
+    "codex"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidebaldassarre/OrisSkills.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "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"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/references/clean-code-checklist.md

@@ -0,0 +1,107 @@
+# 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

package/references/conventions.md

@@ -0,0 +1,39 @@
+# Oris Conventions
+
+Shared rules for every Oris skill. Skills reference this file instead of repeating it.
+
+## Paths
+
+`references/…`, `skills/…`, `agents/…` = Oris bundle root.
+- Installed: `~/.oris/oris-skills/`
+- Repo checkout: repository root.
+
+## Questions
+
+- ASK with the platform question UI (Cursor `AskQuestion`, Claude `AskUserQuestion`); ELSE ask plainly in chat.
+- ONE question per turn. Recommended answer FIRST.
+- ALWAYS include, localized to `uiLanguage`:
+  - `Explain the options` / `Spiega le opzioni` — explain, then re-ask.
+  - During interviews: `Enough questions — proceed` / `Basta domande — procedi` (early exit).
+- NEVER ask what the workspace, docs, code, or setup map already answer. Explore first.
+
+## Language
+
+- READ `references/settings.md` (user settings: `~/.oris/settings.json`).
+- Chat + questions: `uiLanguage`. Generated documents: `artifactLanguage`. Default both: `en`.
+
+## Setup map
+
+- WHEN `.oris-flow/manifest.json` exists: read it + only the relevant `.oris-flow/maps/**` sections BEFORE scanning broadly.
+- VERIFY stale or high-risk map facts against the repository before consequential actions.
+
+## Gates
+
+- NEVER write documents, code, settings, Git, or DevOps without explicit user confirmation in this flow.
+- The skill that performs the action owns its confirmation gate; routing never grants it.
+- NEVER store secrets in `.oris-flow/**`, docs, receipts, or logs. Mask passwords as `***`.
+
+## Subagents
+
+- USE parallel subagents for independent scans when the platform has them (Cursor subagents, Claude Task tool).
+- KEEP subagent output compact: summaries and pointers, not raw logs.

package/references/doc-policy.md

@@ -0,0 +1,24 @@
+# Oris Documentation Policy
+
+Applies whenever an Oris skill writes or updates task documentation. Project-agnostic.
+
+## Task folder
+
+One folder per feature, whole lifecycle:
+
+| File | Purpose | Written by |
+|------|---------|------------|
+| `docs/tasks/{task}/functional-analysis.md` | confirmed business behavior | discover |
+| `docs/tasks/{task}/acceptance-criteria.md` | QA criteria, stable `AC-xxx` IDs | criteria |
+| `docs/tasks/{task}/implementation-plan.md` | execution-ready technical plan | plan |
+
+NEVER split one feature's docs across unrelated directories.
+
+## Rules
+
+1. Language: documents in `artifactLanguage`; skill instructions stay English.
+2. Steps are independent: any document may be created without the previous one. State the missing source once, use the strongest confirmed source, record the gap in the document ("not available" localized). Never block on a missing predecessor.
+3. INSPECT the task folder + setup map before asking the user or writing.
+4. Every document ends with a change-history table: date | source | change | reason. Later changes rewrite the affected sections AND add a history row — no inline "changed!" notes.
+5. Facts only from confirmed sources; open questions go to open points. NEVER invent behavior, labels, or commands.
+6. Verification artifacts (test plans, specs) are technical follow-ups owned by loops or the project's own conventions — they never replace `acceptance-criteria.md`.