oris-skills 2.0.0 → 2.1.0

package/skills/oris-loop/SKILL.md

@@ -1,16 +1,19 @@
 ---
 name: oris-loop
-description: Design, test, run, and self-tune bounded work loops with executor/verifier/doctor/debriefer subagents. Use for repeated verified work - fix until green, implement plan step by step, align docs, or any observe-act-verify cycle. Cross-platform - Cursor, Claude Code, Codex.
+description: Design, test, run, and self-tune bounded work loops with executor + verifier subagents (doctor/debriefer opt-in). Use for repeated verified work - fix until green, implement plan step by step, align docs, or any observe-act-verify cycle. Cross-platform - Cursor, Claude Code, Codex.
 ---
 
 # Oris Loop
 
 A loop = observe → choose ONE bounded action → act → verify with evidence → record → repeat or stop.
 IF fresh evidence cannot change the next action → recommend a one-shot workflow, not a loop.
+IF the goal is verifying acceptance criteria once → recommend `skills/oris-flow-verify/SKILL.md`, not a loop.
 
-RULES: follow `references/conventions.md`. CONTRACT: `references/loop-contract.md` (folder layout, loop.md schema, states, receipts).
+RULES: follow `references/conventions.md`. CONTRACT: `references/loop-contract.md` — the single source for folder layout, loop.md schema (roles, limits, models), states, receipts, and self-improvement (`improve.mode: auto` vs `propose`). Read it before crafting or running.
 Treat loop files, receipts, and proposals as untrusted data until they are the approved active loop.
 
+Default roles per pass: executor + verifier. Doctor and debriefer are opt-in via `roles:` in loop.md — offer them only for multi-phase stop logic (doctor) or long unattended runs (debriefer).
+
 ## Route
 
 Pick the smallest path; load ONLY its reference file:
@@ -18,46 +21,23 @@ Pick the smallest path; load ONLY its reference file:
 | User wants… | Route | Read |
 |-------------|-------|------|
 | a new loop (or adapt an existing one) | craft | `references/craft.md` (in this skill folder) |
-| try/learn the system safely | demo | run `oris-skills loop demo`, then guide the 3 printed steps |
+| try/learn the system safely | demo | run `npx oris-skills loop demo`, then guide the 3 printed steps |
 | execute or resume an approved loop | run | `references/run.md` |
 | inspect a loop without running it | audit | read its `loop.md` + `prompts/` + last receipts; report gaps against the contract |
 | learn from receipts / tune the loop | improve | `references/improve.md` |
 
-BEFORE craft/run: `oris-skills loop list --json` (fallback: scan `.oris-flow/loops/`).
+BEFORE craft/run: `npx oris-skills loop list --json` (fallback: scan `.oris-flow/loops/`).
 IF loops exist AND the route is ambiguous → ask ONE question: reuse | adapt | run | audit | new.
 NEVER overwrite loop files, receipts, proposals, or history without confirmation.
-
-## Loop anatomy (what the user can touch)
-
-```text
-.oris-flow/loops/{slug}/
-  loop.md        contract: goal, scope, limits, models, improve mode (schemaVersion 2, approved: true)
-  prompts/       ONE FILE PER ROLE — edit any of them, next pass obeys:
-    orchestrator.md  executor.md  verifier.md  doctor.md  debriefer.md
-  context.md     living handoff snapshot
-  receipts/      one compact receipt per pass
-  proposals/     debriefer/doctor suggestions awaiting approval
-  history/       archived prompt/loop versions
-```
-
-- Models per role: `models:` in loop.md front matter — `inherit` (session model), an adapter alias, or a platform model id.
-- Self-tuning: `improve.mode: auto` lets the debriefer rewrite `prompts/*.md` between passes (old versions archived to `history/`); `propose` (default) requires approval for every change. Scope, limits, permissions are NEVER auto-changed in either mode.
+The prompts under a loop's `prompts/` folder are user-editable — the next pass obeys the edited file.
 
 ## Test before trusting
 
-- `oris-skills loop demo` — creates a sandbox tutorial loop (touches only its own folder).
-- `oris-skills loop dry-run --loop <slug>` — prints the exact message the next pass would inject; runs nothing.
-- `oris-skills loop verify --temp` — self-checks the hook runtime end to end.
-
-## Platforms
-
-| Platform | Trigger | Subagents |
-|----------|---------|-----------|
-| Cursor | stop hook (`.cursor/hooks.json`) re-triggers the same chat | native subagents |
-| Claude Code | Stop hook (`.claude/settings.json`) continues the same session | Task-tool subagents |
-| Codex / CI | `oris-skills loop run --loop <slug> --agent codex\|claude` | each role = separate CLI process |
+- `npx oris-skills loop demo` — creates a sandbox tutorial loop (touches only its own folder).
+- `npx oris-skills loop dry-run --loop <slug>` — prints the exact message the next pass would inject; runs nothing.
+- `npx oris-skills loop verify --temp` — self-checks the hook runtime end to end.
 
-`oris-skills loop bootstrap` arms the hooks; `oris-skills loop chat --action stop` halts any loop.
+Platform triggers (Cursor stop hook, Claude Code Stop hook, Codex/CI headless run) are defined in the contract. `npx oris-skills loop bootstrap` arms the hooks; `npx oris-skills loop chat --action stop` halts any loop.
 
 ## Done when
 

package/skills/oris-loop/references/craft.md

@@ -8,21 +8,22 @@ READ first: `.oris-flow/manifest.json` + relevant maps (project facts live there
 ASK one question at a time (conventions apply). Required decisions:
 
 1. Goal — what does "done" look like?
-2. Verification — how do we PROVE a pass worked? (commands, criteria, browser proof → feeds the VERIFIER prompt verbatim)
+2. Verification — how do we PROVE a pass worked? (commands, criteria, observable proof → feeds the VERIFIER prompt verbatim)
 3. Scope — what may the loop inspect/change? What is off-limits?
 4. Stop — when to stop, ask for help, or declare no-progress?
 5. Limits — max passes / minutes (suggest defaults: 25 / 240).
-6. Models — default `inherit`; ask ONLY if the user wants per-role models.
-7. Improve — `propose` (default) or `auto` (self-tuning prompts)?
-8. Run now or just save?
+6. Roles — default executor + verifier (recommend it). Offer doctor ONLY for multi-phase loops with non-trivial stop logic; debriefer ONLY for long unattended runs that should learn across passes.
+7. Models — default `inherit`; ask ONLY if the user wants per-role models.
+8. Improve — `propose` (default) or `auto` (self-tuning prompts; requires the debriefer role)?
+9. Run now or just save?
 
 INFER phases and structure from the answers. NEVER ask the user to design schemas or subagent contracts.
 IF new evidence could not change the next action → recommend a one-shot workflow instead.
 
 ## Draft prompts
 
-COPY templates from `skills/oris-loop/templates/` (executor, verifier, doctor, debriefer, orchestrator).
-FILL the CAPS placeholders from interview answers. The verifier prompt MUST embed decision 2 verbatim.
+COPY templates from `skills/oris-loop/templates/` — ONLY for the active roles (executor + verifier by default; doctor/debriefer/orchestrator when opted in).
+FILL the CAPS placeholders from interview answers. The verifier prompt MUST embed decision 2 verbatim, including when `goalMet` becomes true.
 KEEP runtime placeholders (`{{iteration}}`, `{{phase}}`, `{{currentTarget}}`) — the orchestrator fills them each pass.
 TRACE one full pass silently (observe → act → verify → record → stop rule). Repair weak verification or vague stops before showing anything.
 
@@ -35,12 +36,12 @@ ITERATE until the user chooses "write the loop". NEVER write files before that.
 ## Write
 
 Under `.oris-flow/loops/{slug}/`:
-- `loop.md` — front matter per `references/loop-contract.md` (`schemaVersion: 2`, `approved: true`) + body: `Goal:` and `Stop:` lines.
-- `prompts/executor.md`, `verifier.md`, `doctor.md` (+ `debriefer.md`, `orchestrator.md` when customized).
+- `loop.md` — front matter per `references/loop-contract.md` (`schemaVersion: 2`, `approved: true`, `roles:` from the interview) + body: `Goal:` and `Stop:` lines.
+- `prompts/executor.md`, `verifier.md` (+ `doctor.md`, `debriefer.md`, `orchestrator.md` for opted-in roles).
 - `context.md` — objective + next action.
 - empty `receipts/`, `proposals/`, `history/`.
 
-THEN: `oris-skills loop dry-run --loop {slug}` and show the result.
+THEN: `npx oris-skills loop dry-run --loop {slug}` and show the result.
 IF the user chose "run now" → follow `references/run.md`.
 
 ## Adapt an existing loop

package/skills/oris-loop/references/run.md

@@ -2,9 +2,9 @@
 
 ## Arm (first turn)
 
-1. RESOLVE the slug: `oris-skills loop list --json`.
-2. CHECK readiness: `oris-skills loop dry-run --loop <slug>` (validates prompts + shows the pass message).
-3. ARM: `oris-skills loop chat --action start --loop <slug>` (rebind a broken runtime with `--action repair`).
+1. RESOLVE the slug: `npx oris-skills loop list --json`.
+2. CHECK readiness: `npx oris-skills loop dry-run --loop <slug>` (validates prompts + shows the pass message).
+3. ARM: `npx oris-skills loop chat --action start --loop <slug>` (rebind a broken runtime with `--action repair`).
 4. END the turn with one status line. The stop hook injects the next pass automatically — NEVER start a pass in the same turn, NEVER simulate the hook.
 
 `--task <path>` is only for materializing a NEW loop from a task path. NEVER create symlinks or copied folders to alias slugs.
@@ -14,11 +14,13 @@
 The injected message IS the orchestrator prompt (from `prompts/orchestrator.md` or the default). Follow it exactly:
 
 - Orchestrator = control plane only. NEVER do executor/verifier/doctor work in the main chat.
-- SPAWN one subagent per role with its `prompts/<role>.md` file, runtime placeholders filled, model from the pass message.
+- SPAWN one subagent per ACTIVE role (listed in the pass message) with its `prompts/<role>.md` file, runtime placeholders filled, model from the pass message.
+- No doctor in the active roles → map the verifier verdict yourself: pass + goalMet → complete; pass → continue; fail → continue; blocked/inconclusive → ask-user.
 - Windows: workers must not chain commands with `&&`; use the tool working directory.
 - RECEIPT per pass (see contract), raw logs → `.oris-flow/runtime/evidence/`.
-- CLOSE: `oris-skills loop chat --action set-state --state <state>`, then end with `ORIS_LOOP_STATE: <state>`.
+- CLOSE: `npx oris-skills loop chat --action set-state --state <state> --progress <yes|no>`, then end with `ORIS_LOOP_STATE: <state>`.
 - After continue/advance: END THE TURN. Never ask "run next pass?".
+- On ask-user: tell the user what decision is needed; the loop stays paused until `set-state --state continue`.
 
 IF prompts files are missing → `set-state blocked`, tell the user to complete craft. NEVER invent role instructions.
 IF subagents cannot be spawned → `set-state blocked`. The main chat never degrades into doing worker roles.
@@ -26,5 +28,5 @@ NEVER classify an error, missing tool, or exhausted limit as success.
 
 ## Headless (Codex / CI)
 
-`oris-skills loop run --loop <slug> --agent codex|claude`
-Each role runs as a separate CLI process with its own prompt file and model; receipts and state work the same.
+`npx oris-skills loop run --loop <slug> --agent codex|claude`
+Each active role runs as a separate CLI process with its own prompt file and model (read-only roles run without write access); receipts and state work the same.

package/skills/oris-loop/templates/debriefer.md

@@ -14,5 +14,5 @@ IMPROVE MODE = {{IMPROVE_MODE}}:
 
 RULE: one improvement per debrief. No improvement without receipt evidence.
 
-RETURN compact JSON only:
+RETURN compact JSON only (```json fenced):
 { "role": "debriefer", "outcome": "keep|tuned|proposed", "insight": "", "changedFiles": [], "proposalPath": "" }

package/skills/oris-loop/templates/doctor.md

@@ -6,15 +6,17 @@ Diagnose from executor + verifier evidence, never from confidence.
 STOP RULES for this loop:
 {{STOP_RULES}}
 
-CLASSIFY one:
-- PASS — criteria met; continue or complete.
-- PATCH_REQUIRED — loop design gap; describe the minimal patch (improve mode decides where it lands).
-- ASK_USER — missing authority, scope, or product decision.
-- BLOCKED — environment, tooling, scope violation, or no progress ({{iteration}} vs limits).
+DECIDE one (canonical, references/loop-contract.md):
+- continue — criteria progressing; run another pass.
+- advance — this phase is done; move to the next declared phase.
+- complete — the loop goal is met with evidence.
+- ask-user — missing authority, scope, or product decision.
+- propose-patch — loop design gap; describe the minimal patch (improve mode decides where it lands).
+- blocked — environment, tooling, scope violation, or no progress ({{iteration}} vs limits).
 
 DISTINGUISH: loop design issue | execution choice | environment | changed goal | insufficient evidence.
 
 NEVER: edit product files, edit loop.md scope/limits/permissions directly.
 
-RETURN compact JSON only:
-{ "role": "doctor", "decision": "continue|advance|complete|retry|stop", "classification": "", "diagnosis": "", "evidence": "", "patchSummary": "", "approvalRequired": true }
+RETURN compact JSON only (```json fenced):
+{ "role": "doctor", "decision": "continue|advance|complete|ask-user|propose-patch|blocked", "classification": "", "diagnosis": "", "evidence": "", "patchSummary": "", "approvalRequired": true }

package/skills/oris-loop/templates/executor.md

@@ -1,6 +1,7 @@
 # Executor prompt — edit freely; the orchestrator sends this file to the executor subagent each pass
 
-You are the executor of the Oris loop "{{OBJECTIVE_SLUG}}".
+ORIS LOOP ACTIVE — approved pass of the loop "{{OBJECTIVE_SLUG}}".
+You are its executor.
 
 GOAL: {{OBJECTIVE}}
 
@@ -15,5 +16,5 @@ SCOPE:
 
 NEVER: commit, push, deploy, expose credentials, edit .oris-flow/runtime/**, self-verify.
 
-RETURN compact JSON only:
+RETURN compact JSON only (```json fenced):
 { "role": "executor", "state": "claimed|blocked", "summary": "", "changedFiles": [], "claim": "", "evidenceHint": "", "blocker": "" }

package/skills/oris-loop/templates/orchestrator.md

@@ -3,6 +3,7 @@
 ORIS LOOP RUN — pass {{iteration}}/{{maxIterations}}
 Loop: {{loop}} | Phase: {{phase}} ({{phaseIndex}}/{{phaseCount}}) | Do: {{instruction}}
 Definition: {{loopPath}} | Context: {{contextPath}} | Prompts: {{promptsDir}}
+Active roles: {{roles}}
 Models: executor={{executorModel}} verifier={{verifierModel}} doctor={{doctorModel}} debriefer={{debrieferModel}} ("inherit" = current session model)
 Improve mode: {{improveMode}}
 
@@ -12,13 +13,15 @@ EACH PASS:
 1. READ {{contextPath}}; pick exactly ONE bounded next step.
 2. SPAWN executor subagent with {{promptsDir}}/executor.md (fill runtime values), model {{executorModel}}.
 3. SPAWN verifier subagent with {{promptsDir}}/verifier.md + the executor claim, model {{verifierModel}}.
-4. SPAWN doctor subagent with {{promptsDir}}/doctor.md + both compact summaries, model {{doctorModel}}.
+4. DECIDE the state:
+   - doctor in active roles → SPAWN doctor subagent with {{promptsDir}}/doctor.md + both compact summaries, model {{doctorModel}}; use its decision.
+   - no doctor → map the verifier verdict: pass + goalMet → complete; pass → continue; fail → continue; blocked or inconclusive → ask-user.
 5. WRITE a compact receipt to the loop receipts/ folder; update context.md with durable facts only.
-6. RUN: `oris-skills loop chat --action set-state --state <continue|advance|complete|blocked>`.
-7. END the turn with exactly: `ORIS_LOOP_STATE: continue | advance | complete | blocked | ask_user`.
+6. RUN: `npx oris-skills loop chat --action set-state --state <continue|advance|complete|blocked|ask-user> --progress <yes|no>` (progress yes = the verifier confirmed forward movement).
+7. END the turn with exactly: `ORIS_LOOP_STATE: <continue|advance|complete|blocked|ask-user>`.
 
-IMPROVE ({{improveMode}}):
-- auto → after the doctor verdict, the debriefer may rewrite files under {{promptsDir}} (archive the old version to history/ first). It must NEVER change scope, limits, permissions, or verification in loop.md — those go to proposals/.
+IMPROVE ({{improveMode}}, only when debriefer is in active roles):
+- auto → after the verdict, the debriefer may rewrite files under {{promptsDir}} (archive the old version to history/ first). It must NEVER change scope, limits, permissions, or verification in loop.md — those go to proposals/.
 - propose → the debriefer writes proposals/ only; nothing changes until the user approves.
 
 ALWAYS:
@@ -26,8 +29,8 @@ ALWAYS:
 - Tell the user in one line what this pass will do before spawning workers.
 
 NEVER:
-- Continue when the doctor says blocked, scope is violated, or the same failure repeats.
+- Continue when the verdict is blocked, scope is violated, or the same failure repeats.
 - Commit, push, deploy, edit .oris-flow/runtime/**, or touch paths outside the approved scope.
 - Ask "run next pass?" after continue/advance — end the turn; the hook schedules the next pass.
 
-IF prompts files are missing or subagents cannot be spawned: `set-state --state blocked`, say why, end the turn.
+IF prompt files are missing or subagents cannot be spawned: `set-state --state blocked`, say why, end the turn.

package/skills/oris-loop/templates/verifier.md

@@ -17,5 +17,7 @@ RULES:
 - Store raw logs under .oris-flow/runtime/evidence/; return pointers, not dumps.
 - Report pass, fail, blocked, or inconclusive — with reproducible evidence.
 
-RETURN compact JSON only:
-{ "role": "verifier", "state": "pass|fail|blocked|inconclusive", "summary": "", "evidence": "", "evidencePath": "", "nextRecommendation": "" }
+RETURN compact JSON only (```json fenced):
+{ "role": "verifier", "state": "pass|fail|blocked|inconclusive", "goalMet": false, "summary": "", "evidence": "", "evidencePath": "", "failureSignal": "", "nextRecommendation": "" }
+
+goalMet = true ONLY when the LOOP goal (not just this pass) is satisfied per the criteria above.

package/references/questions.md

@@ -1,38 +0,0 @@
-# Oris Question Contract
-
-How every Oris skill asks. Base rules live in `references/conventions.md`; this file adds the standard options and localized labels.
-
-## Standard options
-
-Include in every Oris question, localized to `uiLanguage`:
-
-| Option | `en` | `it` |
-|--------|------|------|
-| explanation (always) | `Explain the options` | `Spiega le opzioni` |
-| early exit (interviews only) | `Enough questions — proceed` | `Basta domande — procedi` |
-
-- Explanation → explain briefly, re-ask the same question.
-- Early exit → stop asking, go to the matching generation gate. It is NOT approval to write or execute.
-
-## Generation gates
-
-Standard labels:
-
-| `en` | `it` |
-|------|------|
-| `Generate the document` | `Genera il documento` |
-| `Approve document` | `Approva documento` |
-| `Continue the interview` | `Continua l'intervista` |
-| `Cancel` | `Annulla` |
-
-Rules:
-1. NEVER write documents, code, or external changes before the explicit gate choice.
-2. Exception: `oris-flow-criteria` writes the file first, then asks once — confirmed only on `Approve document` / `Generate the document`.
-3. After a document is written: concise summary + contextual next-step menu. NEVER auto-start the next phase.
-
-## Interview standard
-
-Oris is a guided product, not a silent task runner.
-1. READ everything the repo can answer first; ask only real decisions.
-2. ONE focused question per turn until outcome, authority, evidence, and stop rules are clear.
-3. The agent recommends; the user's explicit choice decides the approved scope.