What is a way

A way is a team's way of working, packaged: its gated phases, the documents each phase must produce, the knowledge and rules it carries, and the tools, environment variables, and MCP servers it requires — declared in one portable, versioned, agent-neutral manifest (way.yaml).

ways is the CLI that makes that manifest real:

npx ways.sh add <source>    # acquire pinned → see the full plan → approve → install
npx ways.sh bind            # bind the way's capability slots to YOUR tools
npx ways.sh doctor          # validate the whole environment, honestly
npx ways.sh install         # reproduce the whole ways.lock on a fresh clone / in CI

Install / invocation

The CLI is published under three names — same tool, pick whichever you prefer:

npx ways (no suffix) does not work — that unscoped name belongs to an unrelated npm package. All three expose the ways bin:

npm i -g ways.sh    # then: ways add <source>

Not another installer

Packaging and placement ride the substrates that already work: skills land via skills.sh, rules land via steering (converted to each agent's native format), MCP dependencies are described with the standard server.json vocabulary. ways never copies skill files itself and never targets a single agent.

What none of those substrates have — and what ways adds on top — is the contract:

The 30-second mental model

1. A way author writes way.yaml: skills, knowledge, requirements, capability slots, and the flow (phases → gates → generated documents).
2. A consumer runs ways add: the way is fetched pinned, validated against the schema and the conformance rules, and nothing executable is enabled until the full plan is approved.
3. The consumer runs ways bind to fill the way's slots with their tools (GitHub or GitLab, Jira or Linear — the way doesn't care, the contract does).
4. ways doctor proves the environment is ready — or tells you exactly what to fix.
5. Every teammate (and CI) runs ways install to reproduce that exact set from ways.lock — byte-for-byte, with the approval carried in the lock so trusted content isn't re-prompted.

One way, or a whole family

A way.yaml describes one gated flow. To ship several related flows under one identity — a feature flow and a bug flow, say, each with its own gates — package them as a WayFamily: it references member ways and carries the payload they share, so ways add installs the whole set in one command while each member stays installable on its own.

Continue with Getting started, or go straight to ways & families.

Normative source of truth: the ways repo — schemas in schemas/ways/v1alpha1/, program docs in docs/program/.