oris-skills 2.1.0 → 2.2.0

package/skills/{oris-flow-architecture/SKILL.md → oris-flow/references/architecture.md}

@@ -1,60 +1,73 @@
----
-name: oris-flow-architecture
-description: Scan the codebase for architectural friction, present deepening opportunities as a visual HTML report, then interview through the picked one. Use for architecture review, refactor opportunities, tech-debt mapping intents.
-disable-model-invocation: true
----
-
 # Architecture Review
 
-Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
+Surface architectural friction and propose deepening opportunities — refactors that turn
+shallow modules into deep ones. The aim is testability and AI-navigability.
 
-RULES: follow `references/conventions.md`. NEVER edit product code here — output is a report + an interview; implementation routes to plan/implement.
+RULES: `references/conventions.md`. Output is a report + an interview; implementation
+routes to plan/implement.
 
 ## Vocabulary (use these words exactly)
 
-- **module** — a unit with an interface and an implementation. Never "component", "service", "layer".
+- **module** — a unit with an interface and an implementation. Never "component",
+  "service", "layer".
 - **interface** — what callers must know. Never "API", "signature".
-- **deep / shallow** — deep: small interface, big implementation. Shallow: interface nearly as complex as the implementation.
-- **seam** — where two modules meet. Never "boundary". One adapter = hypothetical seam; two = real.
-- **locality** — bugs concentrate where the behavior lives; **leverage** — one interface serves N call sites.
-- **deletion test** — would deleting the module concentrate complexity (good signal) or just move it?
+- **deep / shallow** — deep: small interface, big implementation. Shallow: interface
+  nearly as complex as the implementation.
+- **seam** — where two modules meet. Never "boundary". One adapter = hypothetical seam;
+  two = real.
+- **locality** — bugs concentrate where the behavior lives; **leverage** — one interface
+  serves N call sites.
+- **deletion test** — would deleting the module concentrate complexity (good signal) or
+  just move it?
 
 ## 1. Explore
 
-1. READ first: setup map, `CONTEXT.md` (domain names for good seams), `docs/adr/` (decisions NOT to re-litigate).
+1. READ first: setup map, `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;
    - shallow modules (deletion test says "concentrates");
-   - pure functions extracted for testability while the bugs hide in how they're called (no locality);
+   - pure functions extracted for testability while the bugs hide in how they're called;
    - tight coupling leaking across seams;
    - untested code, or code untestable through its current interface.
 
 ## 2. Report (HTML, outside the repo)
 
-WRITE a self-contained HTML file to the OS temp dir (`architecture-review-<timestamp>.html`), OPEN it (`start` | `open` | `xdg-open`), TELL the absolute path. Nothing lands in the repo.
+WRITE a self-contained HTML file to the OS temp dir (`architecture-review-<timestamp>.html`),
+OPEN it (`start` | `open` | `xdg-open`), TELL the absolute path.
 
 FORMAT: Tailwind CDN + Mermaid CDN. Per candidate, one card:
 - title (names the deepening) + strength badge: `Strong` | `Worth exploring` | `Speculative`;
 - files (monospaced), Problem (one sentence), Solution (one sentence);
-- Before/After diagram side by side — Mermaid for graph-shaped (dependencies, sequences), hand-built divs/SVG for mass diagrams and collapses; if the diagram needs a paragraph, redraw the diagram;
-- wins as bullets ≤6 words, glossary terms only ("locality: bugs concentrate", "interface shrinks") — never "cleaner code";
-- ADR conflict → amber callout ("contradicts ADR-0007 — worth reopening because…"); surface only when friction is real.
+- Before/After diagram side by side — Mermaid for graph-shaped, hand-built divs/SVG for
+  mass diagrams; if the diagram needs a paragraph, redraw the diagram;
+- wins as bullets ≤6 words, glossary terms only — never "cleaner code";
+- ADR conflict → amber callout ("contradicts ADR-0007 — worth reopening because…").
 
 END with Top recommendation: one candidate, one sentence why.
-DO NOT propose interfaces yet. ASK: "Which of these would you like to explore?"
+ASK: "Which of these would you like to explore?" — DO NOT propose interfaces yet.
 
 ## 3. Walk the picked candidate
 
-INTERVIEW per conventions (one question per turn, recommended answer first): constraints, dependencies, the shape of the deepened module, what sits behind the seam, which tests survive.
+INTERVIEW per conventions (one question per turn, recommended answer first):
+constraints, dependencies, the shape of the deepened module, what sits behind the seam,
+which tests survive.
 
 SIDE EFFECTS as decisions crystallize:
 - new concept named → add the term to `CONTEXT.md` (create lazily);
 - fuzzy term sharpened → update `CONTEXT.md` in place;
-- candidate rejected for a load-bearing reason → offer an ADR so future reviews don't re-suggest it (skip ephemeral reasons).
+- candidate rejected for a load-bearing reason → offer an ADR so future reviews don't
+  re-suggest it (skip ephemeral reasons).
+
+AFTER: offer technical plan for the deepening (`skills/oris-flow/references/plan.md`) |
+explore another candidate | stop.
 
-## After
+## Never
 
-OFFER: technical plan for the deepening (`skills/oris-flow-plan/SKILL.md`) | explore another candidate | stop. Never auto-start.
+- Edit product code — the deepening routes to plan, then implement.
+- Use non-glossary words: component, service, layer, boundary, "cleaner code".
+- Re-litigate an ADR silently — surface the conflict, let the user reopen it.
+- Write the report inside the repo.
 
 ## Done when
 

package/skills/{oris-flow-change/SKILL.md → oris-flow/references/change.md}

@@ -1,28 +1,27 @@
----
-name: oris-flow-change
-description: Handle a spec change on an existing feature - scoped delta interview, impact analysis, homogeneous update of all task documents, traceable CH-xxx change log. Use when requirements changed mid-implementation or the client changed their mind. Ambiguous request - route to /oris-flow.
----
-
 # Spec Change
 
-Specs changed while the feature exists (documented, planned, or half-built). Understand the delta, update EVERYTHING together, keep the history traceable.
+Specs changed while the feature exists (documented, planned, or half-built). Understand
+the delta, update EVERYTHING together, keep the history traceable.
 
-RULES: follow `references/conventions.md`. Doc standards: `references/doc-policy.md`.
-NEVER write code here. NEVER update documents one-by-one across separate requests — the whole point is one homogeneous, approved update.
+RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
 
 ## Delta interview
 
-1. EXPLORE first: task folder ({task} per doc-policy), `functional-analysis.md`, `acceptance-criteria.md`, `implementation-plan.md`, `change-log.md`, implemented code state.
-2. ASK one business question at a time (discover style, early exit always present): what changes, why, what stays valid, what is now wrong, urgency vs work already done.
+1. EXPLORE first: task folder ({task} per doc-policy), `functional-analysis.md`,
+   `acceptance-criteria.md`, `implementation-plan.md`, `change-log.md`, implemented code
+   state.
+2. ASK one business question at a time (discover style, early exit always present): what
+   changes, why, what stays valid, what is now wrong, urgency vs work already done.
 3. STOP interviewing when the delta is explicit: before-behavior → after-behavior, confirmed.
 
 ## Impact analysis
 
 MAP the delta to every artifact BEFORE proposing edits:
 - functional-analysis sections affected;
-- `AC-xxx` criteria: changed (keep ID) | removed (mark, never recycle the ID) | new (next free ID);
+- `AC-xxx` criteria: changed (keep ID) | removed (mark, never recycle) | new (next free ID);
 - plan tasks `### n.`: changed | obsolete | new;
-- implemented code and tests already touched (report only — fixing/implementing is not this skill);
+- implemented code and tests already touched (report only — fixing/implementing is not
+  this skill);
 - docs and open points now stale.
 
 SHOW the impact map compactly. ASK ONE question: Apply all updates | Adjust the delta | Stop.
@@ -30,7 +29,8 @@ SHOW the impact map compactly. ASK ONE question: Apply all updates | Adjust the
 ## Apply (one approved pass)
 
 ON approval, update ALL affected documents together (language `artifactLanguage`):
-1. REWRITE affected sections to the new behavior; add one change-history row per document (doc-policy rule 4).
+1. REWRITE affected sections to the new behavior; add one change-history row per
+   document (doc-policy rule 4).
 2. APPEND one entry to `{tasksRoot}/{task}/change-log.md` (create on first change):
 
 ```markdown
@@ -42,11 +42,16 @@ Impacted: functional-analysis §…, AC-004 (changed), AC-007 (removed), plan ta
 Follow-up: implement delta | re-verify | none
 ```
 
-3. `CH-xxx` IDs are stable and never recycled — they are the feature's change history.
+AFTER: offer implement the delta (`skills/oris-flow/references/implement.md`) | re-verify
+criteria (`skills/oris-flow/references/verify.md`) | stop.
 
-## After
+## Never
 
-OFFER: implement the delta (`skills/oris-flow-implement/SKILL.md`) | re-verify criteria (`skills/oris-flow-verify/SKILL.md`) | stop. Never auto-start.
+- Write code — this skill updates documents only.
+- Update documents one-by-one across separate requests — the whole point is one
+  homogeneous, approved update.
+- Recycle an `AC-xxx` or `CH-xxx` ID — they are the feature's history.
+- Apply anything before the impact map is approved, or auto-start the next phase.
 
 ## Done when
 

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

@@ -0,0 +1,60 @@
+# 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.
+
+RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
+
+## Generate privately first
+
+1. SOURCES in order of trust: confirmed chat > task docs (`functional-analysis.md`
+   preferred, never required — say once when missing) > current UI > code and tests.
+2. DEDUCE create vs update: existing `acceptance-criteria.md` → update, PRESERVE IDs.
+3. IDs: `AC-001`, `AC-002`, … stable across revisions.
+4. Each scenario declares ALL of: role + starting state · deterministic data · numbered
+   user steps · observable outcome under the step that causes it · negative coverage ·
+   regressions to keep.
+5. CLASSIFY each: `Verifiable` | `Needs setup/data` | `Blocked by Open QA`.
+6. DISCARD criteria not checkable through observable product behavior. Unbuilt features:
+   only confirmed intended behavior.
+
+## Interview (only high-impact gaps)
+
+ASK one at a time, only what docs/UI/code cannot answer: actor boundaries, required
+data/state, success message + visible result, blocked/negative cases, async states
+visible to the user, regressions, ambiguous wording.
+
+## Write + gate
+
+WRITE `{tasksRoot}/{task}/acceptance-criteria.md` (language `artifactLanguage`):
+
+```markdown
+# {Feature} — Acceptance Criteria
+## AC-001 {scenario title}   [Verifiable | Needs setup/data | Blocked by Open QA]
+Role/state: … | Data: …
+Steps:
+1. …
+   → observable outcome
+Negative: … | Regressions: …
+## Open QA
+## Change history (date | source | change | reason)
+```
+
+THEN ask ONE question: Approve document | Regenerate | Edit specific criteria | Cancel.
+The document is confirmed ONLY on approval. AFTER: offer technical plan
+(`skills/oris-flow/references/plan.md`) | verify now (`skills/oris-flow/references/verify.md`, when
+the feature is already built) | stop.
+
+## Never
+
+- Write code, Git, or DevOps.
+- Recycle a removed ID for different behavior.
+- Invent labels, messages, or behavior for unbuilt features.
+- Ask "anything else?" — every question targets a named gap.
+
+## Done when
+
+- [ ] IDs stable; every scenario observable and classified.
+- [ ] Questions only for gaps evidence could not close.
+- [ ] Approval asked exactly once after writing.

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

@@ -0,0 +1,66 @@
+# Discovery
+
+Interview the stakeholder until the desired business behavior is clear enough to
+document. The cornerstone of the flow: everything downstream (criteria, plan, loops)
+builds on this.
+
+RULES: `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.
+2. DEDUCE create vs update: existing `functional-analysis.md` → update; missing → create.
+   Ask only on contradictory signals.
+3. Technical evidence = private input. TRANSLATE it to business language; never show file
+   paths or code to the stakeholder.
+
+## Interview
+
+ASK one business decision at a time, recommended answer first, early exit always present.
+BUSINESS ONLY, in rough priority:
+- actors, roles, permissions, goals;
+- current vs desired behavior;
+- visible states, labels, messages, navigation;
+- edge cases, empty/error states;
+- scope in/out/deferred, rollout, priority.
+WALK every branch until intent, boundaries, cases, and open points are explicit or
+intentionally parked. Do not stop at the first plausible answer.
+ESTIMATE complexity in Fibonacci Story Points (1–21) from scope, dependencies,
+uncertainty, QA impact.
+
+## Generation gate
+
+SHOW compact summary: goal, confirmed behavior, scope in/out, open points, estimate.
+ASK: generate the document | keep interviewing | explain.
+ON generate → write `{tasksRoot}/{task}/functional-analysis.md` (language `artifactLanguage`):
+
+```markdown
+# {Feature} — Functional Analysis
+## Goal            (business value, one paragraph)
+## Actors & permissions
+## Behavior        (current → desired, user-visible only, numbered flows)
+## States & messages (labels, empty/error/loading states)
+## Edge cases
+## Scope           (included | excluded | deferred)
+## Open points
+## Estimate        (Story Points + rationale)
+## Change history  (date | source | change | reason)
+```
+
+AFTER: offer acceptance criteria (`skills/oris-flow/references/criteria.md`) | technical plan
+(`skills/oris-flow/references/plan.md`) | stop.
+
+## Never
+
+- Write code, Git, or DevOps — this skill only interviews and documents.
+- Ask about implementation: files, APIs, services, tables, selectors, branches, tests,
+  frameworks, sequencing.
+- Invent behavior — facts only from confirmed sources; open questions go to Open points.
+- Write the document before the explicit generation choice, or auto-start the next phase.
+
+## Done when
+
+- [ ] Explored before asking; questions stayed business-only, one at a time.
+- [ ] Every branch walked or intentionally parked; estimate given.
+- [ ] Document written only after the explicit generation choice.

package/skills/{oris-flow-docs/SKILL.md → oris-flow/references/docs.md}

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

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

@@ -0,0 +1,49 @@
+# Fix
+
+The smallest safe change near the failing behavior. Reproduce first, root cause before
+any edit, evidence before done.
+
+RULES: `references/conventions.md`.
+
+## Triage
+
+1. IF no details given → ask ONE question: what happens, what was expected, where
+   (link/ID when one exists).
+2. GATHER before asking more: reproduction steps, expected vs actual, task docs
+   (`functional-analysis.md`, `acceptance-criteria.md`, `implementation-plan.md`),
+   tracker context, recent commits, relevant code and tests.
+3. ASSUME bug report, not redesign.
+
+## Diagnose
+
+- REPRODUCE or trace the failure path in code before proposing anything.
+- FIND root cause, not symptom. Check whether the documented behavior
+  (criteria/analysis) defines "correct".
+- SUMMARIZE: root cause → proposed minimal fix → files → verification plan.
+  CONFIRM explicitly.
+
+## Fix
+
+- SURGICAL change near the failure.
+- PRESERVE unrelated user changes.
+- ADD a regression test when the area has test conventions.
+
+## Verify + close
+
+1. RUN the reproduction + targeted tests; broaden if the surface is shared.
+2. SUMMARIZE: cause, change, verification, residual risk.
+3. RECOMMEND: `skills/oris-flow/references/verify.md` when criteria exist; docs update
+   (`skills/oris-flow/references/docs.md`) when documented behavior changed.
+
+## Never
+
+- Edit code before root cause, proposed fix, and verification plan are confirmed.
+- Broaden scope or change product decisions — unless documented behavior is impossible.
+- Refactor, clean up, or reformat around the fix — surgical only.
+- Patch the symptom when the cause is elsewhere.
+
+## Done when
+
+- [ ] Root cause identified and confirmed before edits.
+- [ ] Minimal change; regression verified.
+- [ ] No unrelated code touched.

package/skills/{oris-help/SKILL.md → oris-flow/references/help.md}

@@ -1,30 +1,34 @@
----
-name: oris-help
-description: Explain how to install, use, and troubleshoot Oris Skills. Use when the user asks how Oris works, what to type, how to install/update/uninstall, or why a skill is missing.
-disable-model-invocation: true
----
-
 # Oris Help
 
-Answer in the user's language. Start with the next practical action. Keep it short; details on request.
+Answer in the user's language. Start with the next practical action. Keep it short;
+details on request.
 
 ## Quick answers
 
 | Need | Answer |
 |------|--------|
-| Start anything | Type `/oris-flow` — it routes or shows the menu. It's the only command to remember. |
+| 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; or `--agents cursor,claude,codex`). Reload the agent afterwards. |
+| 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 language / test profiles | `/oris-flow` → Setup → language & profiles (settings live in `~/.oris/settings.json`). |
-| Edit a loop's behavior | Edit the files in `.oris-flow/loops/{slug}/prompts/` — next pass obeys them. |
+| 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
+  troubleshooting.
 
-## Guardrails
+## Done when
 
-- NEVER tell users to paste secrets anywhere.
-- Skip internals (manifest JSON, hook mechanics) unless the user asks for technical troubleshooting.
-- Deeper docs: `docs/user-guide.md`, `docs/architecture.md` in the bundle (`~/.oris/oris-skills/`).
+- [ ] The user knows the next practical action, in their language.
+- [ ] No secrets requested; internals only on request.

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

@@ -0,0 +1,48 @@
+# Implement
+
+Execute the confirmed plan — nothing more, nothing less.
+
+RULES: `references/conventions.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.
+3. MAP the code, tests, config, and translations the plan touches (parallel subagents
+   when available).
+
+## Execution mode (ask before the first edit)
+
+- `Step by step` (recommended) — one numbered `### n.` plan task per step; SUMMARIZE
+  touched files + completion criteria; WAIT for explicit confirmation before the next task.
+- `One shot` — all tasks in order, no stops between tasks.
+
+## While coding
+
+- FOLLOW existing project patterns; no new abstractions without need.
+- STAY inside the confirmed scope; park discoveries as notes, don't chase them.
+- ADD or update focused tests for the changed behavior.
+- CLEAN as you finish (`references/clean-code-checklist.md`): remove dead code, debug
+  leftovers, and duplication you introduced; match the file's naming and style.
+
+## Verify + close
+
+1. RUN targeted verification first; broaden when the touched surface is shared.
+2. SUMMARIZE: touched files, verification results, residual risk.
+3. RECOMMEND next: `skills/oris-flow/references/verify.md` when acceptance criteria exist;
+   otherwise update docs (`skills/oris-flow/references/docs.md`).
+
+## Never
+
+- Edit code before BOTH the source (plan or recap) and the execution mode are confirmed.
+- Leave the confirmed scope, or drive-by refactor untouched code.
+- Update DevOps unless explicitly asked.
+- Auto-start the next phase.
+
+## Done when
+
+- [ ] Source and mode confirmed before edits.
+- [ ] Only planned scope touched; verification ran.
+- [ ] Next step recommended, not auto-started.

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

@@ -0,0 +1,59 @@
+# Craft a loop — four decisions, everything else defaults
+
+Interview → draft prompts → user approves → write. The user owns the final wording of
+every prompt. A good loop needs exactly FOUR decisions; the rest has a stated default.
+
+## Interview (four decisions, one per turn)
+
+READ first: `.oris-flow/manifest.json` + relevant maps — project facts live there; NEVER
+re-ask them. Question kernel: `references/conventions.md`.
+
+1. GOAL — what does "done" look like? One sentence; it becomes the loop's `Goal:`.
+2. PROOF — how does a pass PROVE it worked? Commands, criteria, observable behavior —
+   this feeds the VERIFIER prompt verbatim, including when `goalMet` becomes true.
+   Weak proof = weak loop; push hardest here.
+3. SCOPE — what may the loop inspect and change; what is off-limits.
+4. STOP — when to stop, ask for help, or declare no-progress. One sentence; becomes `Stop:`.
+
+DEFAULTS — state them once in the recap, change only if the user objects or the work
+demands it: roles executor + verifier · limits 10 passes / 240 minutes · models `inherit`
+· `improve.mode: propose`. OFFER doctor ONLY for multi-phase stop logic; debriefer ONLY
+for long unattended runs (and required for `improve.mode: auto`).
+
+INFER phases and structure from the answers — NEVER ask the user to design schemas or
+subagent contracts. Fresh evidence could not change the next action → recommend a
+one-shot workflow instead of a loop.
+
+## Draft prompts
+
+- COPY templates from `skills/oris-flow/templates/` — ONLY the active roles.
+- FILL the CAPS placeholders from the four decisions; the verifier prompt embeds
+  decision 2 (PROOF) verbatim.
+- 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.
+
+## Approval gate
+
+SHOW: goal + stop (2 lines) + the defaults line, then each draft prompt.
+ASK one question: write the loop | edit verifier | edit executor | edit doctor | edit debriefer | keep interviewing.
+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`, `roles:` from the interview) + body: `Goal:` and `Stop:` lines.
+- `prompts/<role>.md` — one file per active role.
+- `context.md` — objective + next action.
+- empty `receipts/`, `proposals/`, `history/`.
+
+THEN `npx oris-skills loop dry-run --loop {slug}` and show the result.
+IF the user chose "run now" → follow `skills/oris-flow/references/loop-run.md`.
+
+## Adapt an existing loop
+
+COPY the source loop's prompts, EDIT only what the interview changed, run the same
+approval gate. NEVER overwrite the source loop.

package/skills/oris-flow/references/loop-improve.md

@@ -0,0 +1,32 @@
+# Improve a loop — evidence first, smallest change
+
+READ receipts + the evidence they reference BEFORE touching anything. No pattern from a
+single run unless the defect is obvious.
+
+CLASSIFY the cause first:
+loop design | execution choice | verifier gap | environment/tooling | changed goal | insufficient evidence.
+ONLY loop-design and verifier-gap causes justify changing the loop.
+
+## Where changes land
+
+| Change | improve.mode: propose | improve.mode: auto |
+|--------|----------------------|--------------------|
+| prompts/*.md wording | proposal in `proposals/` | debriefer edits directly; old file → `history/`; noted in receipt |
+| context.md facts | allowed | allowed |
+| scope, limits, permissions, verification commands (loop.md) | proposal + explicit user approval | SAME — never automatic |
+
+RULE: one improvement per debrief, the smallest change the evidence justifies.
+APPLYING an approved loop.md change → archive the previous `loop.md` to
+`history/loop.vN.md`, record the decision in the next receipt.
+
+## Never
+
+- Let an unapproved proposal affect execution.
+- Change scope, limits, permissions, or verification commands without explicit approval —
+  in ANY improve mode.
+- Tune prompts to make the verifier easier to satisfy — fix the loop, not the bar.
+
+## Outcome
+
+Report exactly one:
+`Keep loop` | `Tuned prompts` | `Patch proposed` | `Execution issue` | `Environment blocked` | `Inconclusive`.

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

@@ -0,0 +1,47 @@
+# Run a loop — arm once, then obey the hook
+
+The chat is the control plane, never the worker. Arm the loop, end the turn; every pass
+after that is injected by the platform hook and followed exactly.
+
+## Arm (first turn)
+
+1. RESOLVE the slug: `npx oris-skills loop list --json`.
+2. CHECK readiness: `npx oris-skills loop dry-run --loop <slug>` — validates prompts and
+   shows the exact 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.
+
+`--task <path>` only materializes a NEW loop from a task path — never an alias for a slug.
+
+## Each pass (triggered by the hook message)
+
+The injected message IS the orchestrator prompt (from `prompts/orchestrator.md` or the
+shipped default). FOLLOW it exactly:
+
+- Orchestrator = control plane only. NEVER do executor/verifier/doctor work in the main chat.
+- 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 among the active roles → map the verifier verdict yourself:
+  pass + goalMet → complete · pass / 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: `npx oris-skills loop chat --action set-state --state <state> --progress <yes|no>`,
+  then end the turn with `ORIS_LOOP_STATE: <state>`.
+- On ask-user: say what decision is needed; the loop stays paused until
+  `set-state --state continue`.
+
+## Never
+
+- Start or simulate a pass in the same turn you armed the loop — the hook drives.
+- Ask "run next pass?" after continue/advance — END THE TURN instead.
+- Invent role instructions: prompt files missing → `set-state blocked`, tell the user to
+  complete craft.
+- Degrade into worker roles when subagents cannot be spawned → `set-state blocked`.
+- Classify an error, a missing tool, or an exhausted limit as success.
+
+## Headless (Codex / CI)
+
+`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.