FAQ

ways vs skills vs steering?

They're layers, not competitors — ways delegates to the other two:

If you need one prompt-capability: skills. If you need shared conventions in every agent: steering. If you need "this is how our team ships — gates, docs, tools — and I want the environment proven before anyone runs it": ways.

Way vs WayFamily?

A Way is one gated flow — one phase model, its gates, the documents it generates, the skills that drive it, and the slots it needs. A WayFamily is a set of related ways installed together, plus the payload they share (skills, rules, slots, requires) — and it has no flow of its own. Ship a feature flow and a bug flow (different gates) under one identity as a family; ways add <family> installs all members (or a --members subset) in one approval, and each member stays a valid Way you can install on its own. Full detail in Ways & families.

What are hooks?

spec.hooks[] lets a way declare hook packs — auto-executing event handlers (e.g. a PreToolUse guard that blocks git commit while a gate is unapproved). They're placed by hooks.sh, approved with full clarity (each pack expands to its event → command lines before you say yes), pinned in the lock, and shown by ways list --components. See Authoring.

Why did ways add refuse my way?

The usual suspects, in order: not schema-valid (ways validate shows the errors), not conformant (missing hard user gate, non-namespaced name — see Gates & conformance), a declared file missing from the bundle, or a coexistence conflict with an already-installed way (the error names both ways and the resolution; --force overrides knowingly).

How do my teammates (and CI) get the exact same ways?

They run ways install. add is for acquiring a new way (resolve a ref, approve it, write it into ways.lock); install reproduces the ways already declared in the committed ways.yaml + ways.lock — every way at its locked sha, digests verified, external skills at their pins. It's the npm ci of ways. The approval travels in the lock (approvedDigest), so byte-identical content is never re-prompted, and content that doesn't match the lock is refused rather than silently installed. In CI, use ways install --frozen: anything not locked (or drifted) becomes a hard failure, so the pipeline only installs what a human already approved.

Can I override a required slot?

You can bind it to any impl, and the wizard even lets you skip it (with an explicit confirmation) — but you can't demote its requiredness: doctor fails an unbound required slot, with no consumer-side flag to silence it. That guarantee is the product. Author-side, mark slots required: false when they're genuinely optional.

What's the difference between unknown and fail in doctor?

fail = required and verified missing/broken. unknown = present but unverifiable — a bound slot with no Binding profile, a check command that didn't run because the way isn't trusted yet. doctor never converts ignorance into a pass or a fail; use --strict in CI to treat unknown as failure.

Why does doctor say "run with --run-checks on a trusted way"?

The way's declared check commands are executable content, so they only auto-run when the way is trusted: approved at its current content digest in ways.lock. If you edited the installed content (or never approved), re-run ways add to re-approve — or force one run with --run-checks.

Where do Binding profiles come from now?

Three places, in precedence order: the project's catalog (ways.yaml → contracts:) > the way's own bundle (bindings/) > the shared catalog a namespace points at (spec.contracts). First match wins, so anything a way bundles today keeps working, and your repo can register an in-house impl without forking the way. Catalogs are acquired and pinned like a way (in ways.lock under contracts), and — because a Binding contributes check commands doctor runs — they're disclosed in the ways add approval plan. Inspect what resolved with ways contracts. Full detail in Resolving contracts.

My binding shows "no Binding profile found"

No kind: Binding artifact for that {contract, impl} pair resolved from any tier — not the project catalog, the way's bundle, or the shared catalog. The binding still works (it's recorded, doctor reports the slot unknown); to get pass, ship the profile in the way bundle or register a catalog that provides it — see Resolving contracts.

What happened to capabilitySlots?

It was renamed to spec.needs. The alias still works for the lifetime of ways/v1alpha1 — legacy manifests resolve identically — but ways conformance emits a rename warning, and declaring both needs and capabilitySlots is a schema error. The bigger change is that slots now derive from what each skill declares it uses (skills[].uses: [vcs-host, sast]): the way's slot set is the union of those ids plus any needs[] entries, which enrich them with a human displayName, description, suggested options, and so on. See Slots & bindings.

Where does a way store its progress?

In a single .ways/state.json per worktree/branch — phase, gate status, and the documents each phase produced. It's what lets a flow resume and lets tooling see what's going on. This replaces the older per-item .incu-way/items/{slug}.json model (schemaVersion 2); legacy files stay readable via a fallback, and writers migrate a worktree lazily on the next write. Analytical runs (assessment, threat model, docs) use the same file with a namespaced flow. Full shape in State files.

Is there a registry?

Not yet — v1 installs from local paths and git refs, pinned, and reproduces them with ways install. The registry (shortname installs, curated slot vocabulary, trust tiers) is a later program slice — manifest-declared hooks land first — and this site will host its index.