Start Here

This page is the shortest path from “I have a repo” to “Slipway is governing one real change.”

Slipway is built around a few durable project records:

Slipway surface	What it does
Governed change	One bounded unit of work under `artifacts/changes/<slug>/`.
Codebase map	Shared repo context under `artifacts/codebase/` for brownfield work.
Task evidence	Runtime proof under `.git/slipway/runtime/changes/<slug>/evidence/`.
Review evidence	Fresh verification records that must match the current worktree.
AI adapters	Generated host files that route agents back to the Slipway CLI.

The CLI is the authority. AI tools can help author artifacts and run stages, but they should not invent lifecycle state or edit evidence by hand.

Choose Your Path

Situation	Start with
You are new to Slipway and want a small end-to-end run.	First governed change
You are adding Slipway to a repo that already has behavior.	Onboarding an existing codebase
You need the install and adapter commands only.	Install and refresh adapters
A change is stuck, stale, or confusing.	Recover and troubleshoot
You are evaluating the design.	Design and Workflow

For concrete adoption patterns, use Real-World Scenarios.

First Install

Pick an official release-backed path for your platform:

Platform	Recommended path
macOS	`brew install --cask signalridge/tap/slipway`
Windows	`scoop bucket add signalridge https://github.com/signalridge/scoop-bucket` `scoop install slipway`
Linux	Use the `.deb`, `.rpm`, `.apk`, `tar.gz`, AUR, or container image paths in Installation.
Go fallback	`go install github.com/signalridge/slipway@latest`

Then confirm the binary is visible:

slipway --help

The full platform matrix, release archive paths, checksum verification, and source-build instructions remain in Installation.

Initialize A Repo

Run this from the repository root:

slipway init --tools codex

Use the tool IDs you actually use:

slipway init --tools claude,codex,opencode
slipway init --tools all
slipway init --tools none

slipway init writes .slipway.yaml and optional generated AI-tool adapters. The adapters are convenience surfaces; the CLI remains authoritative.

Start One Governed Change

You do not drive Slipway by hand. In your AI-tool session, describe the change in plain language:

Add a short usage note to the README.

The adapter generated by slipway init routes that request into the governed lifecycle. The entry skill picks up the change, and the agent runs the slipway stages — intake, planning, implementation, review, and the done gate — on your behalf, pausing only when Slipway surfaces a skill handoff, checkpoint, blocker, or done-ready state for you to act on.

Slipway, not the agent, decides whether the change is actually done. When you want to see the same state the agent is reading, use the read-only surfaces:

slipway status --json
slipway next --json --diagnostics

Drive It Yourself (Optional)

If you would rather run the lifecycle by hand, the same change is created and advanced through plain commands:

slipway new "add a short usage note to README" --profile docs --preset standard
slipway run --json --diagnostics

slipway run advances only through Slipway-owned stages and stops at each operator-facing boundary. If it returns a skill handoff, complete that handoff in your AI tool and rerun the read-only command before continuing.

If It Fails Closed

Fail-closed output is a feature. It means Slipway saw missing or stale proof and named the next safe action.

Use this order:

slipway status --json
slipway validate
slipway next --json --diagnostics
slipway health --doctor --json

Then follow the named recovery command. Do not hand-edit change.yaml, verification YAML, task evidence, or lifecycle timestamps. If evidence is stale, rerun the owning stage, reviewer, or task evidence path so Slipway can re-derive freshness from the current worktree.

Keep Going

Follow First governed change for a copy-pasteable first run.
Follow Onboarding an existing codebase when the repo already has conventions the agent must learn.
Use Commands when you need exact command and JSON surface details.