npx ways.sh
Your way of working, installable and validated
wayspackages a team's way of working — gated phases, knowledge, tool requirements — as a portable, agent-neutral artifact. Install it pinned, bind it to your tools, and validate the whole environment before anyone runs it.
$ npx ways.sh add ./ways/incu-dev --agent claude-code
add: ./ways/incu-dev
✓ acquiring local copy
✓ schema valid (Way)
✓ conformance conformant
✓ contracts 1 catalog(s), 5 binding(s)
✓ digest new — approval required
Incu Development · v1.0.0
trust ./ways/incu-dev · sha256:121be63ba9b2… (new)
brings:
skills → skills.sh:
+ skills/incu-way-development (bundled)
+ skills/incu-way-bugs (bundled)
hooks → hooks.sh:
+ hooks/gate-guard (bundled)
rules → steering:
+ rules/typescript.md (bundled)
executable surface (will be enabled):
! hook PreToolUse[Bash(git commit*)] → $PACK/scripts/gate-guard.sh (gate-guard)
! check: git --version
! check: gh auth status (ways.dev catalog, impl github)
shield: no findings
enable this way? (↑/↓ · enter)
Cancel
› Enable
✓ added incu/dev (local) — trusted@121be63ba9b2…
Acquire pinned. Shield scans the content, the plan shows exactly what will run. Approve it — or nothing happens.
How it fits
Packaging rides SKILL.md, steering and MCP server.json. ways adds the contract and the validation above them.
the unit
One way, or a whole family
A way is one gated flow. A family bundles several related ways under one identity and installs them as one — each member keeps its own flow, and they share rules, slots, and building blocks.
A team's process, packaged: phases, human gates, and the documents each phase must produce.
= a human approval gate
A set of related ways under one identity — each keeps its own flow, and they share rules, slots, and building blocks. No flow of its own.
the slot
One way, two toolchains
A way says it needs a version-control host, never that it needs GitHub. Each repo names the tool it actually has, so the same way at the same commit drives both teams — and the author never wrote a line of vendor-specific instruction.
the way · incu/dev
uses: [vcs-host, issue-tracker]your repo · ways.yaml
vcs-host: githubissue-tracker: jira
your client's repo · ways.yaml
vcs-host: gitlabissue-tracker: linear
authoring
You already have a way of working.
It just isn't installable yet.
Writing way.yaml by hand is a page of docs. Or hand it to the author-wayskill: it knows the schema and the conformance rules, and it won't hand back a way it hasn't put through the CLI itself.
Point it at what you have
A folder of SKILL.md files, Cursor rules, steering docs — or just the process described out loud. Starting from scratch is the rarer case.
It writes the way.yaml
Skills and knowledge mapped with the right applicability, requirements inferred from the tools your process actually names, and it asks about the human gate instead of inventing one.
Green on both checks
It loops on ways validate and ways conformance until both pass, so what lands is a way that installs — not a draft you still have to debug.
Authoring a way → — the full way.yaml anatomy, and the rules that bite.
Why ways
Phases and gates that hold
A way declares its phases, the points where a human has to approve, and the documents each phase must produce. Conformance checks the claim, so a way can't advertise gates it doesn't enforce.
Written once, bound per repo
A way asks for a version-control host, never for GitHub. Each repo names its own tool in ways.yaml, which is what lets one way serve your team and your client's without a fork.
doctor finds what's missing
CLIs, env vars, MCP servers, slot bindings, pins. Every check answers pass, fail, skipped, unknown, or not-inspectable, with a copy-pasteable fix. It never turns ignorance into a pass.
Nothing runs until you approve it
Installs are pinned in ways.lock with a content digest. The full plan, including every command that will run, is shown before anything is enabled, and changed content asks again.
Shield scans what pinning can't prove
A pinned commit says where content came from, not that it's safe. Ways Shield scans it before the approval gate — leaked credentials refuse the install, unpinned MCP servers and chained hook commands are disclosed — on add and on install.
Make the process installable
Author one way.yaml for your team's flow. Every repo that adds it gets the same gates, the same knowledge, and a doctor that says whether the environment is ready.
Already running a way? See its state in your editor with Lens →