oris-skills 2.1.0 → 2.2.1

package/skills/oris-flow/SKILL.md

@@ -1,43 +1,52 @@
 ---
 name: oris-flow
-description: Oris entry point. Use when the user types /oris-flow, picks from its menu, or describes any software-flow goal (analyze, define criteria, plan, implement, fix, loop, docs). Routes to the right Oris skill in the same chat.
+description: The one Oris skill - read the intent, pick ONE route, apply it in the same chat. Use for /oris-flow and whenever the user wants to set up a repo for agents, start a project, understand or define behavior, write acceptance criteria, plan, implement, fix a bug, verify criteria, handle a spec change, run a work loop (fix until green, repeat until verified), review architecture, update task docs, or asks how Oris works.
 ---
 
-# Oris Flow — Entry Point
+# Oris Flow — the router
 
-The only command users must remember. READ the intent, ROUTE to one skill, ENTER it in the same chat.
+The only skill users see. READ the intent, PICK one route, say one line
+("Entering <route>: <why>"), then READ the route's reference file and APPLY it top to
+bottom in the same chat — its Never and Done when bind the whole route.
+NEVER tell the user to type another command; NEVER narrate the reading
+(`references/conventions.md` `## Silence`).
 
-RULES: follow `references/conventions.md`. This router NEVER writes documents, code, Git, or DevOps — the destination skill owns its own gates.
+RULES: `references/conventions.md`. This router NEVER writes documents, code, Git, or
+DevOps — the route's own reference owns its gates.
 
 ## Route
 
-Match the desired outcome to ONE route:
+Match the desired outcome to ONE route, then apply its reference:
 
-| Route | When the user wants… | Enter |
+| Route | When the user wants… | Apply |
 |-------|----------------------|-------|
-| setup | prepare / map / refresh the repo for Oris | `skills/oris-flow-setup/SKILL.md` |
-| new | bootstrap a new AI-driven project from scratch | `skills/oris-flow-new/SKILL.md` |
-| discover | understand or define product behavior | `skills/oris-flow-discover/SKILL.md` |
-| criteria | acceptance criteria / QA checks | `skills/oris-flow-criteria/SKILL.md` |
-| plan | a technical implementation plan | `skills/oris-flow-plan/SKILL.md` |
-| implement | build from a plan or confirmed scope | `skills/oris-flow-implement/SKILL.md` |
-| fix | fix a bug or regression | `skills/oris-flow-fix/SKILL.md` |
-| verify | check acceptance criteria against the real product, once | `skills/oris-flow-verify/SKILL.md` |
-| change | the spec changed — update analysis, criteria, plan, and history together | `skills/oris-flow-change/SKILL.md` |
-| loop | repeat work until verified (design, demo, run, tune) | `skills/oris-loop/SKILL.md` |
-| architecture | review architecture, find deepening/refactor opportunities | `skills/oris-flow-architecture/SKILL.md` |
-| merge | resolve an in-progress merge/rebase conflict | `skills/oris-flow-merge/SKILL.md` |
-| docs | update task docs after a change | `skills/oris-flow-docs/SKILL.md` |
-| help | how Oris works, install, troubleshooting | `skills/oris-help/SKILL.md` |
-
-ROUTING:
-1. IF intent is clear → say one line ("Entering <route>: <why>"), then READ and APPLY the destination skill immediately. NEVER tell the user to type another command.
-2. IF intent is unclear → ask ONE menu question (below).
-3. IF the user wants to analyze, rethink, or change an existing plan → route to the interview owner (discover / plan / change), NEVER straight to implement.
-4. IF requirements changed on a feature that already has task docs or code → change, not discover (change owns the delta + history).
-5. IF `.oris-flow/manifest.json` is missing → recommend setup first; respect the user's choice.
-   IF the target directory is empty or the user starts a project from scratch → new, not setup.
-6. Destination skills marked `disable-model-invocation` may still be entered from here — that flag only blocks unsolicited invocation from generic chat.
+| setup | prepare / map / refresh an existing repo for Oris and agents | `skills/oris-flow/references/setup.md` |
+| new | bootstrap a project from scratch, greenfield, empty directory | `skills/oris-flow/references/new.md` |
+| discover | understand or define product behavior, functional analysis | `skills/oris-flow/references/discover.md` |
+| criteria | acceptance criteria, QA checks, testable scenarios | `skills/oris-flow/references/criteria.md` |
+| plan | a technical implementation plan before coding | `skills/oris-flow/references/plan.md` |
+| implement | build from a plan or confirmed scope | `skills/oris-flow/references/implement.md` |
+| fix | broken behavior, a regression, a failed QA check | `skills/oris-flow/references/fix.md` |
+| verify | check acceptance criteria against the real product, once | `skills/oris-flow/references/verify.md` |
+| change | the spec changed — update analysis, criteria, plan, and history together | `skills/oris-flow/references/change.md` |
+| loop | repeat work until verified — fix until green, step through a plan | `skills/oris-flow/references/loop.md` |
+| architecture | review architecture, find deepening/refactor opportunities | `skills/oris-flow/references/architecture.md` |
+| docs | update task docs after a change | `skills/oris-flow/references/docs.md` |
+| help | how Oris works, install, update, troubleshooting | `skills/oris-flow/references/help.md` |
+
+## Precedence (the calls that look ambiguous)
+
+1. INTENT clear → enter the route NOW. Unclear → ONE menu question (below); NEVER guess
+   between two routes and never ask twice.
+2. RETHINK beats build: analyze, question, or reshape existing work →
+   route to the interview owner (discover / plan / change), NEVER straight to implement.
+3. CHANGED spec on a feature that already has task docs or code → change, not discover —
+   change owns the delta and the history.
+4. BROKEN behavior → fix. NEW planned work → implement. The menu answer "Implement or
+   fix" gets exactly one follow-up question to split them.
+5. CHECK once → verify. Repeat-until-verified → loop.
+6. EMPTY directory or from-scratch intent → new. Existing repo without
+   `.oris-flow/manifest.json` → recommend setup first; respect the user's choice.
 
 ## Menu (low confidence)
 
@@ -53,16 +62,22 @@ ASK "What do you want to do?" localized to `uiLanguage`, options:
 - Spec changed: update feature docs
 - Loop: repeat until verified
 - Architecture review
-- Resolve merge conflicts
 - Update docs
 - Help
 - Explain the options / Spiega le opzioni
 
-IF "Implement or fix" → one follow-up: new planned work (implement) or broken behavior (fix)?
 IF "Explain the options" → explain briefly, re-ask the same question.
 Every other label maps 1:1 to its route in the table above.
 
+## Never
+
+- Force a route onto a plain question — no flow intent means no menu: just answer.
+- Write anything — the route's reference owns every gate.
+- Hand the user a command or skill name to type — enter the route yourself.
+- Route to implement while the plan itself is in question.
+- Keep interviewing here: one menu question maximum, then enter.
+
 ## Done when
 
-- [ ] One route entered in the same chat, or the menu was asked.
-- [ ] No writes happened before the destination skill's own gate.
+- [ ] One route entered and applied in the same chat, or the menu was asked exactly once.
+- [ ] No writes happened before the route's own gate.

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.