oris-skills 2.2.3 → 3.0.2

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

@@ -3,6 +3,9 @@
 Bring `{tasksRoot}/{task}/` documents in line with a later change, keeping the change
 traceable ({tasksRoot} per doc-policy).
 
+BOUNDARY: the spec is unchanged but code/reality moved on → this route. The business spec
+itself changed → `skills/oris-flow/references/change.md` (it owns the delta and the history).
+
 RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
 
 ## Workflow
@@ -18,7 +21,8 @@ RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
    - add one change-history row per document: date | source | short change | reason;
    - keep unresolved risks in open points;
    - preserve acceptance-criteria IDs.
-7. CLOSE with a concise summary. Offer next steps without auto-starting them.
+7. CLOSE with a concise summary. OFFER next: commit the doc updates
+   (`skills/oris-flow/references/commit.md`) | stop — never auto-started.
 
 ## Never
 

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

@@ -3,9 +3,9 @@
 The smallest safe change near the failing behavior. Reproduce first, root cause before
 any edit, evidence before done.
 
-RULES: `references/conventions.md`.
+RULES: `references/conventions.md`. Research: `references/research.md`.
 
-## Triage
+## Intake
 
 1. IF no details given → ask ONE question: what happens, what was expected, where
    (link/ID when one exists).
@@ -19,8 +19,12 @@ RULES: `references/conventions.md`.
 - 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.
+- RESEARCH when the cause crosses the repo boundary (`references/research.md`): a
+  third-party error, a library behaving unlike its docs, a known-issue smell → search
+  for the documented behavior and standard workarounds at the repo's pinned versions,
+  instead of guessing.
+- SUMMARIZE: root cause → proposed minimal fix → files → verification plan (+ sources
+  when research ran). CONFIRM explicitly.
 
 ## Fix
 
@@ -33,7 +37,8 @@ RULES: `references/conventions.md`.
 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.
+   (`skills/oris-flow/references/docs.md`) when documented behavior changed; commit
+   (`skills/oris-flow/references/commit.md`) when the fix is verified and ready to package.
 
 ## Never
 

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

@@ -0,0 +1,67 @@
+# Handoff
+
+Package this session's state so the next session — or another agent — resumes from the
+exact point: decisions, evidence, next move. The handoff is a bridge, not a store: task
+docs and `AGENTS.md` stay the truth, the handoff points at them and carries ONLY what
+lives nowhere else yet.
+
+RULES: `references/conventions.md`. Entering handoff IS the request to write it — no
+generation gate; the document lands outside the repo.
+
+## 1. Collect (silent)
+
+1. GATHER from this conversation: the active task and route, decisions the user
+   confirmed, evidence observed (commands seen green, verifications, reproductions),
+   open questions with their current best answer, and the next move.
+2. SPLIT what you gathered:
+   - already recorded in task docs or `AGENTS.md` → the handoff POINTS at the file;
+   - confirmed in chat but written nowhere → the handoff CARRIES it, marked with who
+     confirmed it;
+   - speculation → out, or listed as an open question.
+3. Durable project facts proved this session and missing from `AGENTS.md` → write them
+   back NOW (`references/conventions.md` `## Project facts`), so the handoff can point
+   instead of carry.
+
+## 2. Write (outside the repo)
+
+WRITE `handoff-{task-or-topic}-{timestamp}.md` to the OS temp directory — never inside
+the repo or `{tasksRoot}`. Language: `artifactLanguage` (another session reads this cold —
+never caveman-compressed). Structure:
+
+```markdown
+# Handoff — {task or topic}
+Date: … | Repo: {absolute path} | Route in progress: {route or none}
+## Where we are
+What was asked, what is done, what is verified — evidence, not claims.
+## Decisions confirmed in chat, not yet in docs
+- {decision} — confirmed by {user}, because {reason}
+## Read before acting
+- {file} — {why it matters first}
+## Open questions
+- {question} — current best answer: {answer or none}
+## Next move
+One imperative sentence: the first action the next session takes.
+## Resume with
+{the route reference to re-enter} — {one-line why}
+```
+
+TELL the absolute path + a one-line summary of the next move. OFFER: keep working here |
+stop.
+
+## Never
+
+- Write the handoff inside the repo or under `{tasksRoot}` — it is session luggage, not
+  a project document.
+- Duplicate task-doc or `AGENTS.md` content — point at the file.
+- Carry anything not observed in this session or confirmed by the user — a handoff that
+  guesses poisons the next session.
+- Include secrets or tokens — mask as `***`.
+- Auto-start the next route after writing.
+
+## Done when
+
+- [ ] Facts proved this session written back to `AGENTS.md` before the handoff.
+- [ ] Every item in the handoff is a pointer, an observed fact, or a user-confirmed
+      decision — nothing guessed.
+- [ ] Document written to the OS temp dir; absolute path and next move shown.
+- [ ] Resume route named; nothing auto-started.

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

@@ -8,24 +8,21 @@ details on request.
 | Need | Answer |
 |------|--------|
 | 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, 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. |
+| Capture an idea or bug without doing it now | `/oris-flow` → Triage — it becomes a work item with a brief, routed to its route. |
+| Context window full / continue in a new session | `/oris-flow` → Hand off — writes a resume doc and names the route to re-enter. |
 | Change document language / chat verbosity | `/oris-flow` → Setup (settings live in `.oris-flow/settings.json`). |
 | 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
+- Dump internals (settings JSON, install layout) unless the user asks for technical
   troubleshooting.
 
 ## Done when

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

@@ -2,14 +2,14 @@
 
 Execute the confirmed plan — nothing more, nothing less.
 
-RULES: `references/conventions.md`.
+RULES: `references/conventions.md`. Research: `references/research.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.
+2. READ `AGENTS.md`, 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).
 
@@ -22,6 +22,8 @@ RULES: `references/conventions.md`.
 ## While coding
 
 - FOLLOW existing project patterns; no new abstractions without need.
+- RESEARCH mid-build only when an external API resists (`references/research.md`) —
+  verify its current docs at the repo's pinned version; never guess signatures.
 - 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
@@ -32,7 +34,8 @@ RULES: `references/conventions.md`.
 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`).
+   otherwise update docs (`skills/oris-flow/references/docs.md`) or commit
+   (`skills/oris-flow/references/commit.md`) when the change is verified and ready to package.
 
 ## Never
 

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

@@ -10,7 +10,7 @@ RULES: `references/conventions.md`. Writes ONLY after the recap is confirmed.
 
 1. PURPOSE — the product in one sentence; it anchors every agent decision and opens AGENTS.md.
 2. TYPE — webapp | api | library | cli | monorepo. Drives layout and verify strategy.
-3. STACK — recommend from purpose + the user's existing repos (setup maps of sibling
+3. STACK — recommend from purpose + the user's existing repos (`AGENTS.md` of sibling
    projects when visible). Never impose.
 4. TEST RUNNER + LINT — the stack's default unless the user objects. Non-negotiable that
    one exists: agents need a red/green signal, not opinions.
@@ -42,10 +42,10 @@ RUN the test command and the lint command; SHOW real output — fail first, then
 
 ## Arm the flow
 
-1. RUN `npx oris-skills flow scan --repository-root <repo> --write` — manifest + maps;
-   the commands just verified → mark `confirmed`.
-2. RUN `npx oris-skills loop bootstrap --repository-root <repo>`.
-3. tasksRoot: `.oris-flow/tasks` (default — the project stays clean).
+1. The commands just verified are ALREADY in `AGENTS.md` (scaffold table) — that is the
+   whole record; nothing else to generate.
+2. WRITE `.oris-flow/settings.json` with the defaults (`references/settings.md`);
+   tasksRoot `.oris-flow/tasks` — the project stays clean.
 
 AFTER: offer discover the first feature (`skills/oris-flow/references/discover.md`) | stop.
 
@@ -61,4 +61,4 @@ AFTER: offer discover the first feature (`skills/oris-flow/references/discover.m
 - [ ] Purpose, type, stack, test runner confirmed before any write.
 - [ ] AGENTS.md sparse and commands-first; CONTEXT.md + ADR-0001 written.
 - [ ] Test + lint observed running (fail → pass shown).
-- [ ] Manifest written with confirmed commands; loop bootstrapped.
+- [ ] Verified commands recorded in `AGENTS.md`; settings written with defaults.

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

@@ -4,13 +4,17 @@ Interview the technical owner until another agent or developer could execute the
 without guessing.
 
 RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
+Research: `references/research.md`.
 
 ## Before asking
 
 1. EXPLORE: `functional-analysis.md` + `acceptance-criteria.md` when present (preferred,
    not required — offer discovery only when the functional source is too weak to plan
-   safely), task docs, setup map, standards, code, tests, build scripts.
-2. PREFER existing project patterns over new abstractions. Keep uncertainty visible.
+   safely), task docs, `AGENTS.md`, standards, code, tests, build scripts.
+2. RESEARCH external surfaces (`references/research.md`): the plan leans on a
+   third-party API, library, or service → verify against its current official docs at
+   the repo's pinned versions; sources go into the plan.
+3. PREFER existing project patterns over new abstractions. Keep uncertainty visible.
 
 ## Interview
 
@@ -36,6 +40,7 @@ ON generate → write `{tasksRoot}/{task}/implementation-plan.md` (language `art
 ### 2. …
 ## Verification    (commands, tests, what proves each step)
 ## Risks & open points
+## Sources         (only when research ran: link + what it settled)
 ## Change history  (date | source | change | reason)
 ```
 

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

@@ -22,8 +22,8 @@ RULES: `references/conventions.md`. DevOps config: `references/devops.md`.
 ## Gate (never skipped)
 
 SHOW the title + description + target branch. ASK: open PR | edit | cancel.
-ON open → create via the provider (Azure DevOps MCP `oris-devops`, or `gh` for GitHub)
-read from `references/devops.md`. Missing provider auth → say so; never guess credentials.
+ON open → create via the configured provider (`references/devops.md` — read `provider`,
+act generically). Missing provider auth → say so; never guess credentials.
 
 ## After
 

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

@@ -1,25 +1,21 @@
 # Oris Setup
 
-Make the repo cheap for agents to understand — manifest + maps + AI-readiness + loop
-readiness. ADAPT to what the repo IS; never force one structure. Writes ONLY after the
-user confirms the recap.
+Make the repo cheap for agents to understand — `AGENTS.md` as the one durable store,
+preferences in `.oris-flow/settings.json`, AI-readiness checked. ADAPT to what the repo
+IS; never force one structure. Writes ONLY after the user confirms the recap.
 
-RULES: `references/conventions.md`. Map format: `references/repo-map.md`.
-IF the repo is empty or brand-new → route to `skills/oris-flow/references/new.md` instead.
+RULES: `references/conventions.md`. Settings: `references/settings.md`.
+IF the repo has no source files, or no commit beyond a scaffold-only init → route to
+`skills/oris-flow/references/new.md` instead.
 
 ## Mode
 
-IF `.oris-flow/manifest.json` exists → CHECK freshness first:
-`npx oris-skills flow scan --repository-root <repo> --check` — `fresh: true` → say so
-(a rescan would be a no-op); stale → the `changedFiles` list names the areas worth
-refreshing. THEN ask ONE question with these options:
-- refresh all (keeps `confirmed` values — scan merges, never overwrites them)
-- update one area (`--area <section>`)
-- review stale sections
+IF `AGENTS.md` (or `CLAUDE.md`) exists → this is a refresh: READ it first, then ask ONE
+question with these options:
+- update it from a fresh scan (scan below; edits merge in, confirmed facts stay)
+- review one section
 - show summary (no writes)
-- recreate from scratch
 - preferences → Local Preferences below; touches only `.oris-flow/settings.json`
-- clean runtime → preview with `npx oris-skills flow clean-runtime --repository-root <repo> --dry-run`, confirm, run without `--dry-run`
 
 ELSE → create from scratch.
 
@@ -27,15 +23,15 @@ ELSE → create from scratch.
 
 1. CONFIRM the target repository root (ask only if multiple roots are plausible).
 2. SCAN: `npx oris-skills flow scan --repository-root <repo> --json` — deterministic
-   baseline: `projectType`, stacks, commands (with confidence), sections, `truncated`
-   flag. Scan output = draft evidence, not truth.
+   baseline: `projectType`, stacks, commands (with confidence), areas, `truncated` flag.
+   Scan output = draft evidence, not truth; it writes nothing.
 3. IF `truncated: true` → say so, then per-area subagent scans are REQUIRED, not optional.
 4. FAN OUT parallel subagent scans (docs, frontend, backend/data, tests/build, local
    skills/rules) by DEFAULT whenever the repo has more than one of those areas —
    entering setup is the user's request to spawn (`references/conventions.md`
-   `## Subagents`). SKIP only when the repo is small enough that the baseline already
-   answers every §2 decision — say you skipped and why. No agent tool on the platform →
-   same scans inline, sequentially.
+   `## Subagents`). SKIP only when the baseline scan already answers EVERY §2 decision
+   (project type, tasks root, verify commands, version control) — say you skipped and
+   name the evidence. No agent tool on the platform → same scans inline, sequentially.
 
 ## 2. Present findings, decide one at a time
 
@@ -43,14 +39,15 @@ SHOW compactly: detected project type + evidence, stacks, commands, AI-readiness
 Then WALK decisions ONE per turn — short explainer first, recommended answer first:
 
 - **Project type** — confirm `projectType` (webapp | api | library | cli | monorepo); it
-  drives which map sections matter and how criteria/verify observe behavior.
+  drives how criteria/verify observe behavior.
 - **Tasks root** — where Oris writes task documents. Default `.oris-flow/tasks` (keeps
   the project clean); keep `docs/tasks` only when the team already treats task docs as
-  project docs. Record in `setup.tasksRoot`.
-- **Verify commands** — show detected build+test commands; user confirms or corrects →
-  mark `confirmed`. They feed implement, verify, and loop VERIFIER; unconfirmed = a guess.
-- **Version control for `.oris-flow/`** — commit (team default) or gitignore. Task docs
-  follow the same choice.
+  project docs. Record in settings `tasksRoot`.
+- **Verify commands** — show detected build+test commands; user confirms or corrects.
+  Confirmed commands go into `AGENTS.md` — they feed implement, verify, and fix;
+  unconfirmed = a guess.
+- **Version control for `.oris-flow/`** — commit (team default) or gitignore. Record in
+  settings `versionControl`.
 
 ## 3. AI-readiness check
 
@@ -63,7 +60,7 @@ fix offer:
 | `CONTEXT.md` | domain glossary — the names agents must use for the product's concepts |
 | `docs/adr/` | decisions agents must not re-litigate |
 | project skills/rules (`.claude/skills`, `.cursor/rules`) | repeatable workflows as source of truth |
-| confirmed test/build commands | deterministic feedback loop — agents verify instead of guessing |
+| confirmed test/build commands in `AGENTS.md` | deterministic feedback — agents verify instead of guessing |
 
 ON explicit confirmation per file → scaffold the missing ones minimal.
 
@@ -71,32 +68,29 @@ ON explicit confirmation per file → scaffold the missing ones minimal.
 
 1. RECAP: repo, mode, project type, tasksRoot, files to write, AI-readiness gaps,
    choices. CONFIRM explicitly.
-2. WRITE `.oris-flow/manifest.json` + `.oris-flow/maps/**` (confirmed facts get
-   confidence `confirmed` so refresh preserves them), then apply:
-   - `npx oris-skills flow version-control --repository-root <repo> --mode commit|gitignore`
-   - `npx oris-skills loop bootstrap --repository-root <repo>` when adapter/hooks are missing.
-3. OFFER next: discovery | technical plan | loop (`npx oris-skills loop demo` for
-   first-timers) | refresh one area | stop.
+2. WRITE `AGENTS.md` (edit the file that exists — never create `AGENTS.md` beside
+   `CLAUDE.md`) + `.oris-flow/settings.json`, then apply:
+   `npx oris-skills flow version-control --repository-root <repo> --mode commit|gitignore`.
+3. OFFER next: discovery | technical plan | review one area | stop.
 
 ## Local Preferences
 
 1. READ `.oris-flow/settings.json` (defaults in `references/settings.md`).
 2. ASK what to change: artifactLanguage (document language, default `en`) | responseStyle
-   (standard | caveman — maximum token density in chat).
+   (standard | caveman — maximum token density in chat) | tasksRoot | versionControl.
 3. SHOW summary, CONFIRM, write ONLY the settings file.
 
 ## Never
 
 - Write before the recap is explicitly confirmed.
-- Overwrite `confirmed` values on refresh — the scan merges; missing evidence marks
-  stale, never deletes.
-- Overwrite existing agent files: edit the file that exists, never create `AGENTS.md`
-  beside `CLAUDE.md`.
-- Copy secrets into `.oris-flow/**`, docs, or loop state.
+- Overwrite existing agent files: edit the file that exists, never create a rival.
+- Bloat `AGENTS.md`: facts agents need on every request only — commands, structure
+  pointers, decisions; long reference material belongs in `docs/` or skills.
+- Copy secrets into `AGENTS.md`, `.oris-flow/**`, or docs.
 
 ## Done when
 
 - [ ] Mode chosen; scan ran before questions; decisions asked one at a time with explainers.
-- [ ] Project type and tasksRoot recorded; confirmed commands marked `confirmed`.
+- [ ] Confirmed commands and decisions recorded in `AGENTS.md`; preferences in settings.
 - [ ] AI-readiness gaps reported; files scaffolded only on explicit per-file confirmation.
 - [ ] Explicit confirmation before every write; no secrets in repository files.

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

@@ -0,0 +1,69 @@
+# Triage
+
+Turn raw intake — an idea, a bug report, a request — into a work item on the DevOps
+provider with a brief the next route can act on. Capture, classify, route: the work
+itself stays with discover / fix / implement.
+
+RULES: `references/conventions.md`. Provider: `references/devops.md`.
+
+## 1. Understand the intake
+
+1. READ the resolved DevOps config (`references/devops.md`). Provider tools missing or
+   unauthenticated → degrade: compose everything below, show it, tell the user where to
+   paste it — never block on tooling.
+2. SEARCH the provider for existing work items matching the intake (title, keywords,
+   area) BEFORE composing anything. A match → propose linking/updating it, never a
+   duplicate.
+3. CLASSIFY on evidence: bug (behavior observed broken) | feature (new behavior) |
+   spec change on an existing feature | chore. Cheap checks against the repo or product
+   come before questions; a claim you could verify and didn't stays a claim.
+4. ASK one question at a time, only for gaps evidence cannot close: expected vs actual,
+   reproduction conditions, desired outcome, urgency. Early exit always available.
+
+## 2. Compose the work item
+
+BUILD title + description (language `artifactLanguage`; title says the behavior, not the
+solution). Description carries the brief:
+
+```markdown
+## Intake
+{verbatim request} — source: {who/where}, date: {date}
+## Type & evidence
+{bug|feature|spec change|chore} — {what was checked, what was observed}
+## Expected vs actual        ← bugs; features: ## Desired outcome
+…
+## Reproduction              ← bugs only
+1. …
+## Links
+{duplicates found, related items, task docs if any}
+## Next step
+{the Oris route that should pick this up}
+```
+
+Spec change on a feature that already has task docs → say so: the delta belongs to
+`skills/oris-flow/references/change.md`; the work item only tracks it.
+
+## 3. Gate, write, route
+
+1. SHOW the composed work item compactly (or the update to the existing one).
+2. ASK ONE question: Create the work item | Adjust | Stop. Update case: Update the
+   existing item | Adjust | Stop.
+3. ON approval → write via the provider; SHOW the id in the provider's `workItemSyntax`.
+   Degraded mode → deliver the composed item as text instead.
+4. OFFER next: enter the route named in the brief now | triage another intake | stop.
+
+## Never
+
+- Do the work here — no code, no task docs; triage captures and routes.
+- Write to the provider before the composed item is explicitly approved.
+- Recreate what exists — search first; duplicates get linked or updated.
+- Invent reporter, urgency, or behavior not present in the intake or observed.
+- Put secrets, tokens, or personal data beyond the reporter's name in a work item.
+
+## Done when
+
+- [ ] Intake classified with named evidence; duplicate search ran before composing.
+- [ ] Work item shown and explicitly approved before any provider write.
+- [ ] Work item created/updated with id shown in `workItemSyntax` — or degraded output
+      delivered and said so.
+- [ ] Next route offered, not auto-started.

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

@@ -1,7 +1,7 @@
 # Verify
 
 Check every acceptance criterion against the REAL product once, with evidence. One pass,
-no loop ceremony.
+no ceremony.
 
 RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
 
@@ -10,7 +10,7 @@ RULES: `references/conventions.md`. Doc standards: `references/doc-policy.md`.
 1. FIND `{tasksRoot}/{task}/acceptance-criteria.md` ({task} per doc-policy). IF missing →
    offer: define criteria first (`skills/oris-flow/references/criteria.md`) | verify against a
    confirmed chat recap | stop.
-2. READ setup map + verification conventions (test commands, run scripts, environments)
+2. READ `AGENTS.md` + verification conventions (test commands, run scripts, environments)
    before improvising.
 3. PLAN one check per AC: command, test, API call, or observed behavior.
 
@@ -39,9 +39,9 @@ Date: … | Source: acceptance-criteria.md | Verified by: oris-flow verify route
 ## Change history  (date | source | change | reason)
 ```
 
-ON fix → enter `skills/oris-flow/references/fix.md` with the failing AC as the bug report.
-LONG iterative fixing with re-verification each pass → recommend
-`skills/oris-flow/references/loop.md` only when one fix-verify pass is clearly not enough.
+ON fix → enter `skills/oris-flow/references/fix.md` with the failing AC as the bug report;
+re-verify the fixed criteria afterwards, as many fix-verify passes as the user approves.
+ON save with every AC Pass → also offer commit (`skills/oris-flow/references/commit.md`).
 
 ## Never
 

package/agents/oris-loop-debriefer.md

@@ -1,30 +0,0 @@
----
-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.
-   NEVER weaken verification to make passes green — fix the loop, not the bar.
-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

@@ -1,32 +0,0 @@
----
-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|advance|complete|ask-user|propose-patch|blocked",
-  "diagnosis": "",
-  "evidence": "",
-  "patchSummary": "",
-  "approvalRequired": true,
-  "nextAction": ""
-}
-```

package/agents/oris-loop-executor.md

@@ -1,35 +0,0 @@
----
-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. Re-read the fresh state of every file
-   you touch before editing it. The action proves bigger than bounded → stop
-   and return blocked with what you found; half-done work is worse than none.
-4. Preserve unrelated user work.
-5. Do not commit, push, deploy, write DevOps, send external messages, expose
-   credentials, or edit `.oris-flow/runtime/**`.
-6. Return a compact result with changed files, claim, risk, and suggested
-   verifier check. claim = what changed + the exact command or observation
-   that proves it.
-
-Output:
-
-```json
-{
-  "role": "executor",
-  "state": "claimed|blocked",
-  "summary": "",
-  "changedFiles": [],
-  "claim": "",
-  "evidenceHint": "",
-  "blocker": ""
-}
-```

package/agents/oris-loop-verifier.md

@@ -1,35 +0,0 @@
----
-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. Run the checks FIRST,
-   judge after — a claim you could not check is inconclusive, never pass.
-2. Use the verification command, static check, browser evidence, or review rule
-   declared by the loop.
-3. Do not edit product files — you only observe, never fix.
-4. Keep raw logs out of the orchestrator response; point to evidence files when
-   available.
-5. Report pass, fail, blocked, or inconclusive.
-
-Output:
-
-```json
-{
-  "role": "verifier",
-  "state": "pass|fail|blocked|inconclusive",
-  "goalMet": false,
-  "summary": "",
-  "evidence": "",
-  "evidencePath": "",
-  "failureSignal": "",
-  "nextRecommendation": ""
-}
-```
-
-`goalMet` is true only when the loop goal itself is satisfied, not just this pass.