convez.ai
AgenteDevOps & InfraestruturaAvançado
signalridge

Slipway

signalridge/slipway

Governança local que força agentes IA a cumprir promessas, não só fazê-las

Ver no GitHub
BomPluginScore · de 0 a 100

Agent de governança Git-nativa que valida e controla o ciclo de vida completo de trabalho entregue por agentes de IA (Claude, Cursor, Gemini). Transforma promessas de conclusão em evidência verificável: testes, compilação e conformidade com o plano original antes de marcar como pronto.

Instalação

$npx convez-ai signalridge/slipway

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
24
Forks
1
Acompanhando
1
Saúde
42%
Último commit
há 3 dias
Versão
v1.0.0
Issues abertas
7
Contribuidores
3

Casos de uso

  • Validar completude de tarefas de código gerado por agentes IA
  • Manter accountability entre plano, implementação e testes em fluxos Git
  • Prevenir que agentes IA marquem trabalho como concluído sem evidência de qualidade

Veredito

Ferramenta sólida para quem usa agentes de código em produção e precisa garantir qualidade sem confiar apenas em prompts. Endereça um problema real: agentes IA tendem a cortar etapas críticas. Implementação em Go, distribuição multiplataforma, integração Git nativa e sem lock-in de serviço hosted são pontos fortes genuínos.

README

A tradução para o português deste README ainda está na fila.

Documentation | Installation | Release Notes

Slipway

Governance that keeps your AI coding agent honest: "done" means proven, not promised. You drive it in plain language and never memorize a slash command.

AI coding agents are fast, but they cut corners. They skip the tests, drift from the plan, and call work "done" that was never verified. Slipway is a local, Git-native governance layer that makes that hard to fake: it turns the agent's work into a durable, inspectable change record and keeps the lifecycle authority in the repository itself, not in a hosted service. Your AI tool does the work; Slipway decides when it is actually done. It works with Claude Code, Codex, Cursor, Gemini, and OpenCode.

  • The model can't fake "done." Completion is gated on fresh review and verification evidence: checks compiled into the CLI, not advisory prompts the agent can rationalize past. If the evidence goes stale or the work drifts from the plan, Slipway reopens the change instead of waving it through.
  • No commands to learn. After a one-time slipway init, a generated entry skill routes your ordinary plain-language requests through the governed lifecycle; on tools that support session hooks, live governed state is also surfaced every session, unprompted. You describe the change, and the agent drives the process.
  • Lighter on tokens. The governance logic runs as compiled Go in the CLI, not as phase prompts your model re-reads and re-reasons every turn. One thin entry skill stays resident; stage skills load only when the CLI asks for them.

See it in action

You talk to your AI tool the way you already do. The agent handles the governance, and you never type a Slipway command:

You:  Add a --dry-run flag to the export command.

(The agent already knows this repo is governed and that no change is active:
 the entry skill routes it there, and on tools with session hooks that state
 is pushed in automatically, so no action is needed from you.)

Agent (routing on its own):
  → slipway new      captures intent, scope, and guardrail class
  → slipway next     intake → planning; writes requirements / decision / tasks
  → implements the flag, runs your test + build commands
  → slipway run      spec review, quality review, goal verification
  → done-ready ✓     every step backed by evidence committed beside the code

You:  Looks good, finalize it.

Agent:
  → slipway done     archives the terminal state

You never typed a slash command. Slipway handed the agent the lifecycle;
the agent drove it.

And if the agent had tried to call it done before the tests ran and the review evidence existed? slipway done refuses: the gate lives in the CLI, not in a prompt the agent can decide to skip.

How Slipway compares

Spec, workflow, and skill toolkits for AI coding are all good at structuring work. The axis that sets Slipway apart is where the rules live and whether the model can ignore them: almost all of them encode the process as prompts or Markdown the agent is asked to follow, so the gates stay advisory. Slipway compiles the process into a deterministic CLI backed by repo evidence, so the gates fail closed.

ToolHow you drive itEnforcement of "done"
Spec Kit (GitHub)/speckit.* slash command per phaseAdvisory: an incomplete checklist passes on a "yes"
OpenSpec/opsx:* slash commandsAdvisory by design: "fluid, not rigid," and verify is optional
spec-kitty/spec-kitty.* plus a spec-kitty next autopilot loopPartial: merge gates on status, but review is an advisory "nudge"
gsd80+ /gsd-* slash commandsAdvisory: hooks must not block, and --skip-* / --auto bypass
superpowersSkills auto-fire from a session bootstrap (no commands)Self-discipline: an "Iron Law" the model is asked to obey
SlipwayPlain language; an entry skill auto-fires (no commands)Compiled, fail-closed: gates live in the CLI and repo evidence

The pattern is consistent: those tools enforce process by asking the model to comply, while Slipway enforces it in code the model runs but can't rewrite. (superpowers is the closest on experience, since its skills also auto-trigger without slash commands, but its rules live in the model's context, not in a binary.) On capability the lines blur, because Slipway also runs dependency-ordered waves, dedicated worktrees, and TDD governance, so the real divide is enforcement, not feature count. Where the peers genuinely lead is reach and ecosystem: far more supported agents, more mileage, and models Slipway lacks, like OpenSpec's delta-specs or Spec Kit's large integration catalog.

What Slipway deliberately trades off

Several of the differences above are intentional, not gaps. Slipway optimizes for provable outcomes on changes that matter, and accepts the costs that come with that:

DimensionMost spec / skill toolkitsSlipway's deliberate choiceWhat the trade-off buys
Agent reach15 to 30+ agents via generated prompt files5 first-class adapters (growing)A tested contract per tool, not a lowest-common-denominator prompt
Install & runtimenpx / uvx, no binaryA single versioned Go binaryOne deterministic engine; no per-session prompt or version drift
State integrityRepo or spec files the model maintainsEngine-owned state with freshness digestsStale or hand-edited evidence is detected, not trusted
FlexibilityEdit any artifact anytime ("fluid")A staged lifecycle that reopens on driftPlan and code can't silently diverge, at the cost of less freeform editing
Speed vs. assuranceFast by default; gates optionalGates are mandatory and freshness-checkedSlower on throwaway edits; safe on the changes that matter
Failure modeSkipping a step degrades silentlyMissing or stale evidence fails closedYou learn the work isn't done before you ship, not after

One thing is not a deliberate trade-off, just where Slipway is today: mileage. It is younger and less battle-tested than Spec Kit or superpowers, and the five-tool list is still growing. The bet is that fail-closed depth is the harder thing to retrofit later, and breadth and mileage come with time.

Depth, not just a gate

A single "did you run the tests?" check is easy to fake. The point of Slipway is the depth behind the gate: a chain of stage-owned checkpoints that each demand their own evidence, so quality is enforced all the way through instead of rubber-stamped at the end.

  • Intake fixes intent, scope, open questions, and a guardrail class. Sensitive domains (auth, credentials/PII, financial, schema migration, irreversible ops, external-API contracts) fail closed harder and get no bypass, force-close, or private attestation path.
  • Planning binds a requirements.md / decision.md / tasks.md bundle that execution is held to, so the agent can't quietly re-scope mid-flight.
  • Review is two independent passes (spec-compliance, then code-quality) read with fresh context, not by the agent that wrote the code.
  • Goal verification re-checks the acceptance criteria against fresh evidence before anything may claim done.
  • Drift and freshness are enforced, not trusted: edit the plan or let evidence go stale, and Slipway reopens the earliest affected stage and re-walks it. A change can't limp to done on half-stale proof.

That chain is what command-driven spec toolkits and in-context skill packs don't carry. Instead of a single end-of-run checkbox, you get an auditable trail of stage-owned evidence that the next session, human or AI, can re-inspect and trust.

Quick start

1. Install (pick one; full matrix in Installation):

brew install --cask signalridge/tap/slipway   # macOS
scoop install slipway                          # Windows (after adding the bucket)
go install github.com/signalridge/slipway@latest   # any platform with Go

Linux users also have .deb / .rpm / .apk, the ghcr.io/signalridge/slipway container image, AUR slipway-bin, and Nix. See Installation for every path and checksum verification.

2. Initialize your repo and generate the adapter for your AI tool:

slipway init --tools claude        # or: codex, cursor, gemini, opencode
slipway init --tools all           # generate every adapter

For each --tools target, this writes .slipway.yaml, a managed .gitignore block, and the governed skills that teach the AI tool how to enter the lifecycle. Tools that support session hooks also get one. (Omit --tools to set up runtime only.)

3. Just talk to your AI tool. Start a new session and describe what you want: "add a retry to the upload client," "fix the off-by-one in pagination," "refactor the auth middleware." The entry skill routes the request, and on tools with session hooks governed state is surfaced automatically, so Slipway walks it from intake to done-ready. No command to remember.

slipway new "refresh governance docs" --preset standard
slipway next --json        # read-only handoff: what's next, what's blocking
slipway run --json         # advance until a skill, blocker, or done-ready stop
slipway status --json
slipway done --json

How it works

A governed change moves through intake → planning → execution → review → verification → closeout. change.yaml holds the current authority; mutating lifecycle events append to events/lifecycle.jsonl; evidence accumulates beside the code. slipway next, slipway status, and slipway validate are read-only inspection surfaces; slipway new, slipway run, slipway done, and a few others are the explicit mutation surfaces.

The plain-language experience rests on generated surfaces per AI tool:

  • A thin entry skill (every supported tool) whose description triggers on natural-language change requests and routes into the right CLI command. It never re-implements governance; it hands off to the CLI, and the CLI decides state, readiness, recovery, and the next governed step.
  • A session-start hook (on tools that support session hooks: Claude, Cursor, Gemini, OpenCode, but not Codex) that asks the CLI for current governed state every session and injects a compact handoff, so the agent knows whether a change is active before you prompt it. Where a tool has no hook, the entry skill has the agent pull the same state with slipway status --json on first contact, so enforcement is identical and the state is just pulled instead of pushed.

All these surfaces emit --json, so agents and scripts get structured handoffs, and slipway health, repair, stats, and codebase-map inspect or recover local state. When evidence drifts, slipway next shows the recovery path and slipway run re-walks it. The deeper JSON contracts live in the Operator Guide and Command Reference.

Design philosophy

  • One current authority. A single change.yaml owns lifecycle state; logs and Markdown support it but never replace it.
  • Human-readable, machine-checkable. Markdown stays readable to people, while stable sections and YAML give the runtime something deterministic to inspect.
  • Smallest useful control plane. Slipway stays narrower than adjacent spec, workflow, and agent frameworks by keeping authority in the CLI and repository artifacts.

See Design Philosophy for the longer architecture explanation.

AI tool adapters

Generate host-tool surfaces with slipway init --tools <id> (claude, codex, cursor, gemini, opencode, all, or none). Use --refresh to regenerate managed files deterministically.

ToolGenerated surfaces
Claude.claude/skills/slipway-*/SKILL.md, .claude/commands/slipway/*.md, .claude/hooks/slipway-session-start.sh, .claude/settings.json
Codex.codex/skills/slipway-*/SKILL.md (entry, per-command, and governance skills)
Cursor.cursor/skills/slipway-*/SKILL.md, .cursor/commands/*.md, .cursor/hooks/slipway-session-start.sh
Gemini.gemini/skills/slipway-*/SKILL.md, .gemini/commands/slipway/*.toml, .gemini/hooks/slipway-session-start.sh, .gemini/settings.json
OpenCode.opencode/skills/slipway-*/SKILL.md, .opencode/commands/slipway-*.md, .opencode/hooks/slipway-session-start.sh

Exported generated skill rows are pinned by public skill directory: slipway/SKILL.md, slipway-ci-triage/SKILL.md, slipway-code-quality-review/SKILL.md, slipway-codebase-mapping/SKILL.md, slipway-coding-discipline/SKILL.md, slipway-context-assembly/SKILL.md, slipway-coverage-analysis/SKILL.md, slipway-final-closeout/SKILL.md, slipway-git-recovery/SKILL.md, slipway-goal-verification/SKILL.md, slipway-incident-response/SKILL.md, slipway-independent-review/SKILL.md, slipway-intake-clarification/SKILL.md, slipway-plan-audit/SKILL.md, slipway-research-orchestration/SKILL.md, slipway-root-cause-tracing/SKILL.md, slipway-security-review/SKILL.md, slipway-spec-compliance-review/SKILL.md, slipway-spec-trace/SKILL.md, slipway-tdd-governance/SKILL.md, slipway-test-design/SKILL.md, slipway-wave-orchestration/SKILL.md, and slipway-worktree-preflight/SKILL.md.

Every tool gets the entry skill. Codex enters the lifecycle through its skills (the entry skill, one skill per command, and governance host skills); the other four also get an auto-injecting session-start hook (Codex has no session-hook surface to attach to, so its agent pulls governed state via slipway status --json instead).

Want an agent to install and initialize Slipway for you? Paste the AI Tool Installation Prompt into Claude Code, Codex, OpenCode, or another tool, but read it first and supervise the run. See AI Tool Adapters for invocation spellings and safety rules.

Runtime files

  • artifacts/changes/: governed change bundles. Each holds change.yaml plus the Markdown artifacts (intent, research, requirements, decision, tasks, assurance) and verification records for the change. Active records are runtime authority; archived records stay Git-safe in the owning workspace.
  • artifacts/changes/**/evidence/, events/, verification/: raw local proof directories, ignored by Slipway-managed .gitignore rules. Keep them for local audit and validation.
  • artifacts/codebase/: advisory repo-scoped codebase maps from slipway codebase-map, git-tracked by default so brownfield context is shared rather than hidden.
  • .worktrees/: dedicated governed worktrees, local-only by default.

See the Operator Guide for state authority, freshness state, and recovery details.

Documentation

  • Installation: platform packages, source builds, repo initialization, and the 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.
  • Surface Manifest: generated inventory of adapter, command, skill, JSON, and documentation surfaces.
  • 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 run ./internal/toolgen/cmd/gen-surface-manifest --check
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

Repobeats analytics image

Ver o original no GitHub

Bom para

Relacionados