The package manager for your team's way of working
Today that way of working spreads by hand: zipped skills, copy-pasted rules, every repo drifting, nobody sure which version anyone runs.
ways packages it — skills, rules, hooks, gated flows, tool requirements — as one versioned, agent-neutral artifact. Add it pinned, bind it to your tools, and validate the whole environment before anyone runs it.
- skillswhat the agent can doskills.sh
- rulesknowledge:conventions, agent-nativesteering
- hooksguards that run on their ownhooks.sh
- gated flowflow:phases · approvals · docsways
- requirementsrequires:CLIs · env · MCP serversdoctor
- slotsneeds:vcs-host, never "GitHub"bind
placed by open installers ways enforces doctor validates
What's in a way
Everything a team passes around by hand today, declared in one way.yaml — versioned together, installed together. The open installers ways rides on (skills.sh, steering, hooks.sh) place the content; ways adds the contract, the gates, and the validation above them.
Open the interactive anatomy — hover each section of a real manifest →
metadata: # ns/name, version, publisherspec:skills: # what the agent can do · skills.shknowledge: # rules & context, agent-native · steeringhooks: # guards that run on their own · hooks.shrequires: # CLIs, env vars, MCP servers · ways doctorneeds: # capability slots — vcs-host, never GitHub · ways bindflow: # phases, human gates, documents · ways
How it fits
Packaging rides the formats teams already use — skills as SKILL.md, rules via steering, MCP servers described in a standard server.json — and the content lands native in Cursor, Kiro, Claude Code, and every agent those installers support.
Add it. Bind it. Check 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…
One way, or a whole family
A way is one gated flow. A family bundles several under one identity and installs them as one — each member keeps its own flow; 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.
Read the whole plan. Then say yes.
Nothing runs until you approve it
The full plan is shown before anything is enabled.
Every skill, rule, and command that will run, under an executable surface you read before saying yes. Changed content always asks again — trust binds to the digest, not the name.
executable surface (will be enabled): ! hook PreToolUse[Bash(git commit*)] → $PACK/scripts/gate-guard.sh (gate-guard) shield: no findingsenable this way? (↑/↓ · enter)› Enable
An installer, not a runtime
ways runs, places content, and exits.
No daemon, no background service — nothing resident in your repo but files you can read, and ways.lock lists every one.
Shield scans what pinning can't prove
Leaked credentials refuse the install.
A pinned commit says where content came from, not that it's safe. Shield scans before the approval gate — unpinned MCP servers and chained hook commands are disclosed — on add and on install.
Pinned and reproducible
Every install is pinned in ways.lock with a content digest.
Like npm ci for the process: a fresh clone or CI reproduces the exact approved set, byte-for-byte.
doctor finds what's missing
Every check answers pass, fail, skipped, unknown, or not-inspectable.
CLIs, env vars, MCP servers, slot bindings, pins — each with a copy-pasteable fix. It never turns ignorance into a pass.
Phases and gates that hold
A way can't advertise gates it doesn't enforce.
It declares its phases, the human approval points, and the documents each phase produces — and conformance checks the claim.
No infrastructure to stand up
A way is a git repo with a way.yaml.
Skills and rules can stay where they already live — other repos, other teams, public or private. Read access is the only requirement.
Always know where the flow stands
Every run writes its state to .ways/state.json — the current phase, the gates, the documents. Lens renders it beside your code: come back after a meeting and you know exactly where the agent left off, without re-reading a transcript.
Contact export
feat/003-contact-export
Phase: Implementation
Flow
- ✓Discovery
- ✓PRD
- ✓Plan
- Implementation
- Validation
- Review
- PR → develop
- PR → main
- Done
Progress
- Schema + migration
- Export service
- CSV writer
- REST endpoint
- Tests
- Docs
Gates
- PRD review
- Plan review
- PR → developPR ↗
Documents
A mock, drawn from the real renderer. In your editor the panel inherits your theme's colors, the PR and ticket links are live, and it re-renders on every .ways/ or branch change.
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 · way.yaml
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
way.yaml is what the way declares · ways.yaml is how each repo answers it
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-way skill: 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 → — let an agent draft it, and the rules that bite. The manifest itself: The way.yaml →
No more zipping skills and copy-pasting rules
One way.yaml replaces the drift: every repo that adds it gets the same gates, the same knowledge, and a doctor that says whether the environment is ready. Start where the page started —