oris-skills 2.0.0 → 2.1.0

package/skills/oris-flow/SKILL.md

@@ -16,38 +16,51 @@ Match the desired outcome to ONE route:
 | Route | When the user wants… | Enter |
 |-------|----------------------|-------|
 | 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 / loop), NEVER straight to implement.
-4. IF `.oris-flow/manifest.json` is missing → recommend setup first; respect the user's choice.
-5. Destination skills marked `disable-model-invocation` may still be entered from here — that flag only blocks unsolicited invocation from generic chat.
+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.
 
 ## Menu (low confidence)
 
 ASK "What do you want to do?" localized to `uiLanguage`, options:
 
 - Setup repository
+- New project from scratch
 - Understand / define behavior (discovery)
 - Acceptance criteria
 - Technical plan
 - Implement or fix
+- Verify acceptance criteria
+- 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.
 
 ## Done when
 

package/skills/oris-flow-architecture/SKILL.md

@@ -0,0 +1,64 @@
+---
+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.
+
+RULES: follow `references/conventions.md`. NEVER edit product code here — 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".
+- **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?
+
+## 1. Explore
+
+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);
+   - 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.
+
+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.
+
+END with Top recommendation: one candidate, one sentence why.
+DO NOT propose interfaces yet. ASK: "Which of these would you like to explore?"
+
+## 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.
+
+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).
+
+## After
+
+OFFER: technical plan for the deepening (`skills/oris-flow-plan/SKILL.md`) | explore another candidate | stop. Never auto-start.
+
+## Done when
+
+- [ ] CONTEXT.md and ADRs read before exploring; no ADR re-litigated silently.
+- [ ] Report written to temp (repo untouched), opened, path shown.
+- [ ] Glossary terms used exactly; wins named in locality/leverage terms.
+- [ ] Implementation routed to plan, not started here.

package/skills/oris-flow-change/SKILL.md

@@ -0,0 +1,55 @@
+---
+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.
+
+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.
+
+## 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.
+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);
+- plan tasks `### n.`: changed | obsolete | new;
+- 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.
+
+## 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).
+2. APPEND one entry to `{tasksRoot}/{task}/change-log.md` (create on first change):
+
+```markdown
+# {Feature} — Change Log
+## CH-001 {short title}
+Date: … | Requested by: … | Reason: …
+Delta: {before → after, business language}
+Impacted: functional-analysis §…, AC-004 (changed), AC-007 (removed), plan tasks 3-4, code: {area}
+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-implement/SKILL.md`) | re-verify criteria (`skills/oris-flow-verify/SKILL.md`) | stop. Never auto-start.
+
+## Done when
+
+- [ ] Delta confirmed in business terms before any edit.
+- [ ] Impact map approved; all affected documents updated in ONE pass.
+- [ ] CH-xxx entry written; AC IDs preserved, removed IDs never recycled.

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

@@ -5,7 +5,7 @@ description: Generate or audit business-readable acceptance criteria with stable
 
 # Acceptance Criteria
 
-Generate verifiable, browser-observable criteria. These later feed loop VERIFIER prompts — precision here pays twice.
+Generate verifiable criteria grounded in observable product behavior — UI, API response, CLI output, or a visible system effect, whatever the product exposes. These later feed `oris-flow-verify` checks and loop VERIFIER prompts — precision here pays twice.
 
 RULES: follow `references/conventions.md`. Doc standards: `references/doc-policy.md`.
 NEVER write code, Git, or DevOps here.
@@ -15,7 +15,13 @@ NEVER write code, Git, or DevOps here.
 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; never recycle a removed ID for different behavior.
 3. IDs: `AC-001`, `AC-002`, … stable across revisions.
-4. Each scenario: role + starting state, deterministic data, numbered user steps, observable outcome placed under the step that causes it, negative coverage, regressions to keep.
+4. Each scenario declares ALL of:
+   - role + starting state;
+   - deterministic data;
+   - numbered user steps;
+   - observable outcome, placed 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. For unbuilt features: only confirmed intended behavior — NEVER invent labels or messages.
 
@@ -25,7 +31,7 @@ ASK one at a time, only what docs/UI/code cannot answer: actor boundaries, requi
 
 ## Write + gate
 
-WRITE `docs/tasks/{task}/acceptance-criteria.md` (language `artifactLanguage`):
+WRITE `{tasksRoot}/{task}/acceptance-criteria.md` (language `artifactLanguage`):
 
 ```markdown
 # {Feature} — Acceptance Criteria
@@ -40,7 +46,7 @@ Negative: … | Regressions: …
 ```
 
 THEN ask ONE question: Approve document | Regenerate | Edit specific criteria | Cancel.
-Document is confirmed ONLY on approval. AFTER: offer technical plan | verification loop | stop.
+Document is confirmed ONLY on approval. AFTER: offer technical plan (`skills/oris-flow-plan/SKILL.md`) | verify now (`skills/oris-flow-verify/SKILL.md`, when the feature is already built) | stop.
 
 ## Done when
 

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

@@ -12,15 +12,20 @@ NEVER write code, Git, or DevOps here. WRITE `functional-analysis.md` only after
 
 ## Before asking
 
-1. EXPLORE first: task folder (`docs/tasks/{task}/`), existing `functional-analysis.md` / `acceptance-criteria.md` / `implementation-plan.md`, project docs, setup map, code evidence, DevOps context when available.
+1. EXPLORE first: task folder (`{tasksRoot}/{task}/`), existing `functional-analysis.md` / `acceptance-criteria.md` / `implementation-plan.md`, 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 option always present.
-BUSINESS ONLY: actors, roles, permissions, goals, current vs desired behavior, visible states, labels, messages, navigation, edge cases, empty/error states, scope in/out/deferred, rollout, priority.
-NEVER ask about: files, APIs, services, tables, selectors, branches, tests, frameworks, implementation order.
+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.
+NEVER ask about implementation: files, APIs, services, tables, selectors, branches, tests, frameworks, sequencing.
 WALK every branch of the decision tree 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.
 
@@ -28,7 +33,7 @@ ESTIMATE complexity in Fibonacci Story Points (1–21) from scope, dependencies,
 
 SHOW compact summary: goal, confirmed behavior, scope in/out, open points, estimate.
 ASK: generate the document | keep interviewing | explain.
-ON generate → write `docs/tasks/{task}/functional-analysis.md` per the template below (language: `artifactLanguage`).
+ON generate → write `{tasksRoot}/{task}/functional-analysis.md` per the template below (language: `artifactLanguage`).
 
 ## Document template
 
@@ -49,7 +54,7 @@ FACTS only from confirmed sources; open questions go to Open points — NEVER in
 
 ## After writing
 
-OFFER: acceptance criteria | technical plan | stop. Never auto-start the next phase.
+OFFER: acceptance criteria (`skills/oris-flow-criteria/SKILL.md`) | technical plan (`skills/oris-flow-plan/SKILL.md`) | stop. Never auto-start the next phase.
 
 ## Done when
 

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

@@ -1,12 +1,12 @@
 ---
 name: oris-flow-docs
-description: Update existing task documents after a later functional, QA, or implementation change. Use when documented behavior changed and docs/tasks files must record it.
+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 `docs/tasks/{task}/` documents in line with a later change, keeping the change traceable.
+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`.
 

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

@@ -33,7 +33,7 @@ NEVER edit code before root cause, proposed fix, and verification plan are summa
 
 1. RUN the reproduction + targeted tests; broaden if the surface is shared.
 2. SUMMARIZE: cause, change, verification, residual risk.
-3. RECOMMEND: `/oris-loop` verification when criteria exist; docs update when documented behavior changed.
+3. RECOMMEND: `skills/oris-flow-verify/SKILL.md` when criteria exist; docs update when documented behavior changed.
 
 ## Done when
 

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

@@ -13,7 +13,7 @@ NEVER edit code before BOTH the source (plan or recap) and the execution mode ar
 
 ## Prepare
 
-1. FIND `docs/tasks/{task}/implementation-plan.md`. IF missing → reconstruct a technical recap from chat, task docs, and code; SHOW it; CONFIRM before any edit.
+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).
 
@@ -34,7 +34,7 @@ NEVER edit code before BOTH the source (plan or recap) and the execution mode ar
 
 1. RUN targeted verification first; broaden when the touched surface is shared.
 2. SUMMARIZE: touched files, verification results, residual risk.
-3. RECOMMEND next: `/oris-loop` verification loop when acceptance criteria exist; otherwise update docs (`oris-flow-docs`).
+3. RECOMMEND next: `skills/oris-flow-verify/SKILL.md` when acceptance criteria exist; otherwise update docs (`skills/oris-flow-docs/SKILL.md`).
 
 ## Done when
 

package/skills/oris-flow-merge/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: oris-flow-merge
+description: Resolve an in-progress git merge or rebase conflict - understand both intents from primary sources, preserve them, verify with project checks, finish. Use for merge conflict, rebase conflict, "conflitti" intents.
+disable-model-invocation: true
+---
+
+# Resolve Merge Conflicts
+
+Resolve the in-progress merge/rebase by understanding WHY each side changed, not by picking lines that compile.
+
+RULES: follow `references/conventions.md`. ALWAYS resolve; never `--abort`. NEVER invent new behavior a conflict hunk doesn't contain.
+
+## 1. See the state
+
+1. READ: `git status`, which operation (merge | rebase | cherry-pick), conflicting files, the merge's stated goal (branch names, merge commit message).
+2. LIST every conflict hunk before touching any.
+
+## 2. Find the primary sources
+
+For EACH conflicting area:
+- `git log` both sides of the hunk (`git log --merge`, `git blame`), read the commit messages;
+- CHECK the PRs / tickets / task docs (`{tasksRoot}/…`, tracker IDs in messages) behind each change;
+- STATE both intents in one line each BEFORE resolving. Unknown intent = investigate more, not guess.
+
+## 3. Resolve
+
+- PRESERVE both intents where possible.
+- INCOMPATIBLE → pick the side matching the merge's stated goal; NOTE the trade-off in the resolution summary.
+- NEVER invent behavior that exists on neither side.
+
+## 4. Verify
+
+1. READ verify commands from the setup map (`confirmed` first); ELSE discover: typecheck → tests → lint/format.
+2. RUN them; FIX what the merge broke — the conflict isn't resolved until checks pass.
+
+## 5. Finish
+
+- STAGE everything, COMMIT (merge) or `git rebase --continue` until all commits are replayed.
+- SUMMARIZE: hunks resolved, intents preserved, trade-offs taken, checks output.
+
+## Done when
+
+- [ ] Both intents stated per hunk before resolving; no invented behavior.
+- [ ] Project checks ran green after resolution.
+- [ ] Merge/rebase completed — never aborted, never left half-done.

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

@@ -0,0 +1,58 @@
+---
+name: oris-flow-new
+description: Bootstrap a new project optimized for AI-driven development - interview, scaffold agent-native standards (AGENTS.md, CONTEXT.md, ADRs, skills, deterministic verify), arm the Oris flow. Use for new project, greenfield, start-from-scratch intents.
+disable-model-invocation: true
+---
+
+# New Project
+
+Bootstrap a repo where agents work at their best from day zero: minimal agent guidance, a domain glossary, recorded decisions, repeatable skills, and a deterministic feedback loop. Then hand it to the flow.
+
+RULES: follow `references/conventions.md`. Writes ONLY after the recap is confirmed.
+
+## Interview (one decision per turn, recommended answer first)
+
+1. PURPOSE — the product in one sentence (it anchors every agent decision; it 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 projects when visible). Never impose.
+4. TEST RUNNER + LINT — pick the stack's default unless the user objects. Non-negotiable that one exists: agents need a red/green signal, not opinions.
+5. NAME + LOCATION — kebab-case; confirm the target directory is empty or new.
+
+## Scaffold (one confirmed pass)
+
+WRITE the agent-native baseline — sparse beats complete, every file must earn its tokens:
+
+| File | Content |
+|------|---------|
+| `AGENTS.md` | one-line purpose, package manager, then COMMANDS first: setup, test, lint, build. Nothing agents can discover alone. ~20 lines max |
+| `CONTEXT.md` | domain glossary seeded from the interview: each core concept, one line, the exact name agents must use |
+| `docs/adr/0001-stack.md` | the stack choice + why — the first decision agents must not re-litigate |
+| `README.md` | humans: purpose, quickstart pointer |
+| stack init | package manifest, `src/`, test runner + lint configured |
+| one sample test | proves the loop: make it fail, make it pass, show both outputs |
+| `.gitignore` + `git init` | first commit only on explicit confirmation |
+
+MONOREPO → root `AGENTS.md` = purpose + navigation; each package gets its own minimal `AGENTS.md`. Nearest file wins.
+
+PROJECT SKILLS — offer to seed `.claude/skills/` (or `.cursor/rules/`) with the first repeatable workflow (e.g. "add a module", "add an endpoint") once one exists; skills are the project's how-to source of truth, growing with the code.
+
+## Verify the feedback loop
+
+RUN the test command and the lint command; SHOW real output. A bootstrap whose verify commands were never observed green is not done.
+
+## Arm the flow
+
+1. RUN `npx oris-skills flow scan --repository-root <repo> --write` — manifest + maps; 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).
+
+## After
+
+OFFER: discover the first feature (`skills/oris-flow-discover/SKILL.md`) | stop. Never auto-start.
+
+## Done when
+
+- [ ] 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.

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

@@ -18,14 +18,18 @@ NEVER write code, Git, or DevOps here. WRITE `implementation-plan.md` only after
 
 ## Interview
 
-ASK one technical decision at a time, recommended answer first, early-exit always present:
-ownership boundaries, files/symbols to touch, APIs/contracts, data model, permissions, feature flags, frontend integration, migrations, verification strategy, rollout, risk, sequencing.
+ASK one technical decision at a time, recommended answer first, early-exit always present. Cover:
+- ownership boundaries, files/symbols to touch;
+- APIs/contracts, data model, migrations;
+- permissions, feature flags, frontend integration;
+- verification strategy;
+- rollout, risk, sequencing.
 
 ## Generation gate
 
 SHOW compact recap: approach, touched areas, sequence, verification, risks, open points.
 ASK: generate the document | keep interviewing | explain.
-ON generate → write `docs/tasks/{task}/implementation-plan.md` (language `artifactLanguage`):
+ON generate → write `{tasksRoot}/{task}/implementation-plan.md` (language `artifactLanguage`):
 
 ```markdown
 # {Feature} — Implementation Plan
@@ -42,7 +46,7 @@ Numbered `### n.` tasks are the execution steps `oris-flow-implement` will follo
 
 ## After writing
 
-OFFER: implement | verification loop | stop. Never auto-start.
+OFFER: implement (`skills/oris-flow-implement/SKILL.md`) | stop. Never auto-start.
 
 ## Done when
 

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

@@ -1,38 +1,69 @@
 ---
 name: oris-flow-setup
-description: Prepare a repository for Oris - interview, scan, write .oris-flow/manifest.json + maps, arm loop hooks. Use for setup, map, refresh, or "prepare this repo for Oris" intents.
+description: Prepare a repository for Oris - explore, detect project type, write .oris-flow/manifest.json + maps, check AI-readiness, arm loop hooks. Use for setup, map, refresh, or "prepare this repo for Oris" intents.
 disable-model-invocation: true
 ---
 
 # Oris Setup
 
-GOAL: make the repo cheap for Oris to understand — manifest + maps + loop readiness. Writes ONLY after the user confirms the recap.
+GOAL: 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.
 
 RULES: follow `references/conventions.md`. Map format: `references/repo-map.md`.
+IF the repo is empty or brand-new → route to `skills/oris-flow-new/SKILL.md` instead.
 
 ## Mode
 
-IF `.oris-flow/manifest.json` exists → ask ONE question: refresh all | update one area | review stale sections | show summary (no writes) | recreate from scratch | language & profiles | clean runtime.
-ELSE → create from scratch.
+IF `.oris-flow/manifest.json` exists → ask ONE question with these options:
+- refresh all (keeps `confirmed` values — scan merges, never overwrites them)
+- update one area (`--area <section>`)
+- review stale sections
+- show summary (no writes)
+- recreate from scratch
+- language & profiles → Local Preferences below; touches only `~/.oris/settings.json`
+- clean runtime → preview with `npx oris-skills flow clean-runtime --repository-root <repo> --dry-run`, confirm, run without `--dry-run`
 
-- "language & profiles" → Local Preferences below; touches only `~/.oris/settings.json`.
-- "clean runtime" → preview with `oris-skills flow clean-runtime --repository-root <repo> --dry-run`, confirm, run without `--dry-run`.
+ELSE → create from scratch.
 
-## Workflow
+## 1. Explore first
 
 1. CONFIRM the target repository root (ask only if multiple roots are plausible).
-2. INTERVIEW before scanning: project context, key standards, test depth, protected areas.
-3. SCAN: `oris-skills flow scan --repository-root <repo> --json` = deterministic baseline. Add parallel subagent scans (docs, frontend, backend/data, tests/build, local skills/rules) only when needed. Scan output = draft evidence, not truth.
-4. DRAFT manifest + map sections with confidence flags; ask focused questions ONLY for ambiguous, high-impact facts.
-5. ASK refresh policy (manual | monthly | after refactor | after test-layout change) — advisory only, never a scheduler.
-6. ASK version control for the map: commit (team default) or gitignore. Record in manifest.
-7. RECAP: repo, mode, detected stack, files to write, loop-readiness gaps, choices. CONFIRM explicitly.
-8. WRITE `.oris-flow/manifest.json` + `.oris-flow/maps/**`, then apply:
-   - `oris-skills flow version-control --repository-root <repo> --mode commit|gitignore`
-   - `oris-skills loop bootstrap --repository-root <repo>` when adapter/hooks are missing.
-9. OFFER next steps: discovery, technical plan, loop (mention `oris-skills loop demo` for first-timers), refresh one area, stop.
-
-REFRESH runs keep user-confirmed values unless the scan proves them stale; update `updatedAt`, confidence, stale flags.
+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.
+3. IF `truncated: true` → say so; large monorepos may need per-area subagent scans.
+4. ADD parallel subagent scans (docs, frontend, backend/data, tests/build, local skills/rules) only when the baseline leaves real gaps.
+
+## 2. Present findings, decide one at a time
+
+SHOW compactly: detected project type + evidence, stacks, commands, AI-readiness (below). Then walk decisions ONE per turn — short explainer first, recommended answer first, assume the user may not know the term:
+
+- **Project type** — confirm or correct `projectType` (webapp | api | library | cli | monorepo). It drives which map sections matter and how criteria/verify will observe behavior.
+- **Tasks root** — where Oris writes task documents. Default `.oris-flow/tasks` (Oris's own folder, 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/inferred build+test commands; user confirms or corrects → mark `confirmed`. These feed implement, verify, and loop VERIFIER; an unconfirmed command is a guess.
+- **Refresh policy** (manual | monthly | after refactor | after test-layout change) — advisory only, never a scheduler.
+- **Version control for `.oris-flow/`** — commit (team default) or gitignore. Task docs follow the same choice.
+
+## 3. AI-readiness check
+
+COMPARE the repo against the agent-native standards; report gaps, one line each, with a fix offer:
+
+| Check | Why it matters |
+|-------|----------------|
+| `AGENTS.md` (or `CLAUDE.md`) at root | the cross-tool agent entry point — minimal: one-line purpose + commands. Keep it sparse; every token loads on every request |
+| `CONTEXT.md` | domain glossary — 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 |
+
+ON explicit confirmation per file → scaffold the missing ones minimal (never overwrite existing content; edit the file that exists, never create AGENTS.md beside CLAUDE.md).
+
+## 4. Recap + write
+
+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/**` (enrich generated sections with confirmed facts; set their confidence to `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 steps: discovery, technical plan, loop (mention `npx oris-skills loop demo` for first-timers), refresh one area, stop.
+
+REFRESH runs keep user-confirmed values — the scan merges (`confirmed` sections/commands/decisions survive; missing evidence marks them stale, never deletes).
 
 ## Local Preferences
 
@@ -43,7 +74,7 @@ REFRESH runs keep user-confirmed values unless the scan proves them stale; updat
 
 ## Done when
 
-- [ ] Mode chosen; scan before questions; questions only for real ambiguity.
-- [ ] Explicit confirmation before every write.
-- [ ] No secrets in repository files.
-- [ ] Loop readiness bootstrapped or intentionally skipped.
+- [ ] Mode chosen; scan before questions; decisions asked one at a time with explainers.
+- [ ] Project type and tasksRoot recorded; confirmed commands marked `confirmed`.
+- [ ] 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-verify/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: oris-flow-verify
+description: One-shot verification of acceptance criteria against real product behavior with a Pass/Fail evidence report. Use after implement/fix, or for verify, check, QA-run intents. Ambiguous request - route to /oris-flow.
+---
+
+# Verify
+
+Check every acceptance criterion against the REAL product once, with evidence. One pass, no loop ceremony.
+
+RULES: follow `references/conventions.md`. Doc standards: `references/doc-policy.md`.
+NEVER edit product code here. IF a check fails, verification records it — fixing belongs to `skills/oris-flow-fix/SKILL.md`.
+
+## Prepare
+
+1. FIND `{tasksRoot}/{task}/acceptance-criteria.md` ({task} per doc-policy). IF missing → offer: define criteria first (`skills/oris-flow-criteria/SKILL.md`) | verify against a confirmed chat recap | stop.
+2. READ setup map + verification conventions (test commands, run scripts, environments) before improvising.
+3. PLAN one check per AC: command, test, API call, or observed behavior. Skip nothing silently.
+
+## Verify (read-only on product code)
+
+For EACH `AC-xxx`, in order:
+- EXECUTE the numbered steps against the real product (tests, running app, API, CLI — whatever the criterion observes).
+- MARK: `Pass` | `Fail` | `Not verifiable` (say why: missing data, blocked env, needs setup).
+- CAPTURE evidence: command + output excerpt, observed behavior, or pointer to logs. Facts, not impressions.
+- NEVER mark Pass from code reading alone when the criterion describes observable behavior.
+
+## Report gate
+
+SHOW compact results: `AC-xxx → Pass/Fail/Not verifiable — one-line evidence` + totals.
+ASK ONE question: Save report | Fix failures now | Stop.
+ON save → write `{tasksRoot}/{task}/verification-report.md` (language `artifactLanguage`):
+
+```markdown
+# {Feature} — Verification Report
+Date: … | Source: acceptance-criteria.md | Verified by: oris-flow-verify
+## Results
+| AC | Result | Evidence |
+## Failures        (reproduction + observed vs expected)
+## Not verifiable  (reason + what would unblock)
+## Change history  (date | source | change | reason)
+```
+
+ON fix → enter `skills/oris-flow-fix/SKILL.md` with the failing AC as the bug report.
+FOR long iterative fixing with re-verification each pass → `skills/oris-loop/SKILL.md` remains available; recommend it only when one fix-verify pass is clearly not enough.
+
+## Done when
+
+- [ ] Every AC checked against real behavior or explicitly marked Not verifiable.
+- [ ] Evidence captured per criterion; no Pass without observation.
+- [ ] Report written only after the gate; failures routed, not fixed here.

package/skills/oris-help/SKILL.md

@@ -13,13 +13,13 @@ Answer in the user's language. Start with the next practical action. Keep it sho
 | Need | Answer |
 |------|--------|
 | Start anything | Type `/oris-flow` — it routes or shows the menu. It's the only command to remember. |
-| Try loops safely | `oris-skills loop demo` → follow the 3 printed steps (`dry-run` previews, `chat --action start` runs). |
+| 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. |
 | Uninstall / reinstall | `npx oris-skills uninstall` / `npx oris-skills reinstall` (preview with `--dry-run`). |
-| Stop a loop | `oris-skills loop chat --action stop` |
-| Loop status | `oris-skills loop chat --action status` / `oris-skills loop list` |
+| 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 | `oris-skills loop verify --temp` self-checks the runtime; `oris-skills loop bootstrap` re-arms repo hooks. |
+| 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. |