Documentation | Installation | Release Notes

Slipway

Slipway is a governance CLI for AI-assisted software delivery inside a local Git repository.

It turns agent work into a durable, inspectable change record: intent, research, requirements, decisions, tasks, implementation evidence, review evidence, and final closeout all live next to the code. AI tools can help execute the work, but Slipway keeps the lifecycle authority in the repository.

Why Slipway

AI coding tools are fast at changing files and weak at preserving accountable process. Slipway exists to make that process explicit.

Design Philosophy

• Local-first governance: the repository is the system of record. Slipway does not require a hosted service to explain what happened.
• One current authority: artifacts/changes/<slug>/change.yaml owns lifecycle state; logs and Markdown files support it but do not replace it.
• Evidence before confidence: tests, builds, review records, and assurance artifacts are proof surfaces, not after-the-fact notes.
• AI tools are adapters: host-specific skills, commands, hooks, and prompts route back into the same CLI instead of creating parallel workflows.
• Human-readable, machine-checkable artifacts: Markdown remains readable to people, while stable sections and YAML records give the runtime something deterministic to inspect.
• Smallest useful control plane: Slipway stays narrower than adjacent spec, workflow, and agent frameworks by keeping governance authority in the CLI and repository artifacts.

See Design Philosophy for the longer architecture explanation.

Core Capabilities

Lifecycle

%%{init: {"theme": "base", "themeVariables": {"fontFamily": "Inter, ui-sans-serif, system-ui, sans-serif", "primaryColor": "#f8fafc", "primaryTextColor": "#0f172a", "primaryBorderColor": "#115e59", "lineColor": "#64748b", "tertiaryColor": "#ecfeff"}}}%%
flowchart LR
  classDef entry fill:#ecfeff,stroke:#115e59,stroke-width:2px,color:#0f172a
  classDef plan fill:#eef2ff,stroke:#2563eb,stroke-width:2px,color:#0f172a
  classDef execute fill:#f8fafc,stroke:#475569,stroke-width:2px,color:#0f172a
  classDef review fill:#fff7ed,stroke:#c2410c,stroke-width:2px,color:#0f172a
  classDef verify fill:#f0fdf4,stroke:#15803d,stroke-width:2px,color:#0f172a
  classDef complete fill:#111827,stroke:#111827,stroke-width:2px,color:#ffffff
  classDef loop fill:#f8fafc,stroke:#94a3b8,stroke-dasharray: 5 5,color:#334155

  start((new)):::entry --> intake["Intake<br/>intent + guardrail classification"]:::entry
  intake --> planNode["Plan<br/>research + requirements + tasks"]:::plan
  planNode --> executeNode["Execute<br/>wave work + evidence"]:::execute
  executeNode --> reviewNode["Review<br/>domain + independent checks"]:::review
  reviewNode --> verifyNode["Verify<br/>assurance + goal proof"]:::verify
  verifyNode --> closeout["Closeout<br/>fresh proof + archive ready"]:::verify
  closeout --> doneNode((done)):::complete

  intake -. clarify / research .-> intake
  planNode -. audit blockers .-> planNode
  executeNode -. wave blockers .-> executeNode
  reviewNode -. changes requested .-> executeNode

  commandLoop["Primary command loop<br/>next inspects<br/>run advances<br/>status reports"]:::loop
  commandLoop -.-> intake
  commandLoop -.-> executeNode
  commandLoop -.-> verifyNode

The primary lifecycle commands are slipway new, slipway next, slipway run, slipway status, and slipway done.

Install

Slipway can be installed or built several ways. The full platform matrix is in Installation.

Prefer published release artifacts or release-backed package-manager channels for normal installation. Treat GitHub Releases under signalridge/slipway, ghcr.io/signalridge/slipway, signalridge/tap, signalridge/scoop-bucket, and slipway-bin as the documented release sources; stop and verify before using same-name packages from unrelated registries. Use go install, Nix, or a local source build when you need a developer fallback, a not-yet-packaged platform path, or unreleased code.

Quick Install

With Go:

go install github.com/signalridge/slipway@latest
slipway --help

From a local checkout for development:

go build -o ./bin/slipway .
./bin/slipway --help

Initialize Slipway in a repository:

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

Omitting --tools creates only .slipway.yaml. Use --refresh to regenerate already managed adapters deterministically.

AI-Agent Install

Paste the prompt below into an AI coding tool to have it install and initialize Slipway for the current repository. Read it before pasting and supervise the agent while it runs. The prompt is short on purpose — it points the agent at the canonical AI Tool Installation Prompt section, which carries the full Discovery / Install / Initialize / Verify / Report guidance.

Install Slipway for this repository.

Read https://signalridge.github.io/slipway/installation/ — specifically the
"AI Tool Installation Prompt" section — and follow it.

Before installing, detect the operating system and CPU architecture, and run
`slipway --version` to see if Slipway is already on PATH. Prefer documented
release sources owned by the Slipway project (the `signalridge` org). Do NOT
install same-name packages from unrelated registries. If no documented path
applies, stop and report.

After installing, run `slipway --version`, `slipway status --json`, and
`git status --short --branch`. Report which install path succeeded and what
files were generated (especially `.slipway.yaml` and adapter directories).

Quick Workflow

slipway new "refresh governance docs" --preset standard
slipway next --json
# execute the surfaced skill or resolve blockers
slipway run --json --diagnostics
slipway status --json
slipway done --json

next, status, and validate are read-only inspection surfaces. run, new, preset, checkpoint, repair, cancel, abort, and done can mutate local governed state.

AI Tool Adapters

Generate host-tool surfaces with slipway init --tools.

The AI-tool installation prompt in Installation is written for copy-paste use in tools such as OpenCode, Codex, and Claude Code.

Runtime Files

• artifacts/changes/: governed change bundles. artifacts/changes/<slug>/change.yaml and top-level Markdown artifacts are project records. Active records are runtime authority; archived records stay in the owning workspace in a Git-safe form with archive-local artifact paths.
• artifacts/changes/**/evidence/, artifacts/changes/**/events/, and artifacts/changes/**/verification/ are raw local proof directories by default. Keep them for local audit and validation; they are ignored by Slipway-managed .gitignore rules.
• artifacts/codebase/ contains advisory repo-scoped codebase maps generated by slipway codebase-map; it is local-only by default.
• .worktrees/ contains dedicated governed worktrees and is local-only by default.

Documentation

• Installation: platform packages, source builds, repository initialization, and AI-tool install prompt.
• Design Philosophy: governing principles, authority boundaries, and adjacent-system tradeoffs.
• Governed Workflow: lifecycle states, read-only surfaces, mutating commands, and Open Questions semantics.
• Command Reference: core, situational, and diagnostics commands.
• AI Tool Adapters: generated paths and host invocation styles.
• Operator Guide: worktrees, state authority, health, repair, verification, and closeout.
• Contributing: repo layout, docs build, adapter contracts, and governance tests.

Verification

Use focused package tests while developing, then run the full local proof before closeout:

go test -timeout=20m ./... -count=1
go build ./...
go vet ./...
mkdocs build --strict

CI also runs Markdown/YAML/action linting, Go tests across platforms, race tests, build checks, security scans, release checks, Nix checks, and the docs workflow in .github/workflows/docs.yml.

Repository Status