Oris Skills

One command. A disciplined software flow. Evidence before "done". For Cursor, Claude Code, Codex, GitHub Copilot — and any agent that can read a file.

npx oris-skills@latest install

Reload your agent, then type /oris-flow. That is the entire user manual.

The idea

AI agents are brilliant executors and terrible colleagues: they guess requirements, declare victory without evidence, and hallucinate the world outside your repo. Oris fixes the colleague part with three rules baked into every interaction:

1. Interview before writing. Nothing lands in your repo — no document, no code — before you explicitly approve it. One question per turn, recommended answer first.
2. Evidence before done. "It works" means a command ran and its output says so. And when the problem crosses the repo boundary — a third-party API, a library misbehaving — the flow checks current official docs at your pinned versions instead of guessing, and records the sources.
3. Your repo stays yours. Durable facts go in AGENTS.md (the file every agent already reads), preferences in one small settings file, task documents in their own folder. No caches, no state, no churn — and the skill never triggers itself: you type /oris-flow, or nothing happens.

One skill, every route

/oris-flow reads your intent and enters the right route in the same chat — no other command exists. Say "the login button does nothing" and you are in fix; say "the client changed their mind about invoicing" and you are in change; say "a client reported this, park it" and triage captures it as a work item; say "I'm out of context" and handoff packages the session for the next one.

        idea ──► discover ──► criteria ──► plan ──► implement ──► verify
                    │                                    ▲            │
                    └── change (spec moved) ─────────────┘        fix ◄┘ (red)

| Route | You get | |-------|---------| | setup | the repo made agent-ready: detected commands and structure confirmed into AGENTS.md; AI-readiness check | | new | a greenfield project born agent-native: sparse AGENTS.md, domain glossary, first ADR, red→green test observed | | triage | raw intake — an idea, a bug report — becomes a work item with an agent-ready brief, duplicates linked, routed onward | | discover | business-first interview → functional-analysis.md | | criteria | observable, stable-ID acceptance criteria → acceptance-criteria.md | | plan | technical interview → implementation-plan.md with bounded, verifiable steps — external APIs verified against their docs, sources recorded | | implement / fix | the plan executed step by step, or the smallest safe bug fix — root cause first, researched when it crosses the repo boundary | | verify | every criterion checked against the real product, with evidence → verification-report.md | | change | spec delta interviewed, all documents updated in one approved pass → change-log.md | | architecture / docs / help | deepening review, doc alignment, answers | | commit / pr | Conventional Commits and English PRs, work item linked, always gated | | handoff | session state packaged outside the repo — decisions, evidence, next move — so a fresh session resumes exactly there |

Every route follows one skeleton — what to do, what Never to do, and a Done when checklist — enforced by the test suite, so the discipline survives refactors.

Tuning

Settings live in .oris-flow/settings.json (/oris-flow → Setup): document language (artifactLanguage, default en), responseStyle (standard/caveman, where caveman shrinks chat to maximum token density while documents and safety gates stay complete), tasksRoot, and whether .oris-flow/ is committed or gitignored. Chat language is deduced from your messages, not configured.

Repository layout

| Path | Purpose | |------|---------| | skills/oris-flow/ | the one skill: router (SKILL.md) + route references | | references/ | shared contracts (conventions, doc-policy, devops, research, settings) and JSON schemas | | scripts/ | Node CLI, repository scanner, installer, tests | | docs/ | architecture, user guide, maintainer guide |

Maintainers

npm test               # cross-platform Node test suite (includes the skill-style gate)

Node.js 20+. License: MIT.