Slipwai

Slipwai creates a new product repository. You answer a few questions. You get a Git repository with one commit on main, ready for coding agents to work in.

Say the name as "slipway".

The canonical source is git.treyco.dev/ROBCOATVG/slipwai. GitHub is the public mirror. Report issues and propose changes there.

slipwai generate            # answer a few questions -> a fresh Git repo, one commit, on main
cd ledger && ./init         # Spec Kit + your coding agent, on demand
make verify                 # the gate, the same one CI runs

Jump to — New to this · What it is · Getting started · Cruise · What you get · The answers you give · Documentation

New to this — start here

Do not clone this repository to create a product. Install the command once. Then run slipwai generate or slipwai adopt.

Two learning paths. Each one installs the command, walks the first session with terminal screenshots, then shows how to update slipwai, how to migrate a project when the factory moves, and how to catch up. /catch-up handles the work a merge cannot finish.

What it is

A factory.

A generated project owns every one of its files. It may rename, replace or delete any of them. No file is marked as belonging to the factory. There is no list of files a project may not touch. The factory never reaches in and overwrites one. That is what makes the skeleton safe to edit on day one.

It is not a one-way door. You can run the factory again inside a project it made:

• slipwai add-service and slipwai add-frontend read project.json and regenerate only the files that list the project's applications. The factory derives that set by generating the project twice and comparing the results, so it cannot drift from a hand-kept list. slipwai describe-service records what a service already there is for — its purpose and its bounded contexts — and regenerates the same way.
• ./init answers the event store, HTTP, staff identity and customer identity questions again, by removing what the old answers brought.

Both respect what the project has become, not what it was generated from.

Later improvements arrive the same way. Run slipwai migrate inside the project. It generates what the current factory would produce for the project's recorded answers, then merges that over the project:

• A file only the factory changed is taken.
• A file only the project changed is kept.
• Where both changed, the project decides.

So an upgrade is a merge, never a replace. Bring a generated project forward is the recipe. make test-migration proves it against the last release on every change.

A merge cannot finish some work. Examples: a step in a cloud account, an answer the project has to give, a gate that now judges code written before it. migrate leaves these in the project as catch-up notes, taken from the CHANGELOG entries for the versions just crossed. /catch-up works through them against the project's own make verify.

Everything generated comes from assets/. No starter copy is committed anywhere, so a change in that tree reaches every combination the moment it is generated.

The profile is the one answer you cannot change later

The two directions are not symmetric. An event log folds back down into tables whenever you want it to. State cannot be turned into history nobody recorded. So event-modelling is the reversible choice.

What it buys is a flat cost per slice, rather than a cheap first slice. That is worth it for a product with years ahead of it, and overkill for a throwaway tool. It is worth more when agents write the slices, not less: a flat marginal cost per slice is the same property as bounded reading per slice.

Both the prompt and Which profile make this argument before you answer.

Every other question has its own answer, and a project can answer most of them again later. See The answers you give.

Getting started

Four steps. You install a slipwai command and run it. You do not clone this repository.

New here? Use the generate learning path, or adopt for an existing tree. Both cover install, first session, upgrade, migrate and /catch-up, with terminal screenshots.

Scaffold a new project is the full reference. Tools required lists what each toolchain and make target needs.

1. Get the command

Scaffolding needs Python 3.11 or later and Git.

uv is the recommended installer. It is worth having anyway: a generated project's ./init uses uv to fetch Spec Kit, so one tool covers both ends.

uv tool install slipwai
slipwai --version

pip install slipwai is the alternative. There is also a standalone executable that needs nothing but Git. All three embed the same catalog, templates, skills, commands and locks, and produce identical repositories. See Install the command.

slipwai upgrade moves an installed copy to the newest release. slipwai upgrade --pre counts the snapshot of main as well.

This repository is the factory that makes the command. Clone it only to change the factory. Work on the factory is that path.

Going to a cloud needs four more things on the machine before you generate, because ./init there pushes the repository and bootstraps the account:

1. OpenTofu.
2. That cloud's CLI, signed in with enough authority to create what the bootstrap creates.
3. A region.
4. Access to your forge.

slipwai generate checks all four as soon as you choose aws or azure, and refuses with what is missing. Tools required has the full list. Running costs are in The AWS target and The Azure target, which is also where the two are compared.

2. Generate a project

Run generate with no arguments to be asked one question at a time. Pass the answers as flags for scripts and CI:

slipwai generate ledger \
  --profile event-modelling \
  --language typescript \
  --frontend react-vite \
  --event-store postgres \
  --http fastify

That creates ./ledger in the current directory, initialised on main with one commit. The target directory must not already exist. --output names a different parent directory.

3. Bootstrap the new repository

Spec Kit is deliberately absent until you ask for it. From inside the generated project:

./init

That installs Spec Kit. It then asks which coding agent to project skills/, commands/ and agents/ into — any of 36 harnesses. It then offers optional extensions as a checkbox menu: CodeGraph, UI/UX Pro Max and the UX gates.

--integration <name> and --extension <key> skip those questions. --extension also adds one later. See Extensions.

4. Work in it, and run it

make help        # every target, with a line each
make verify      # the gate — native checks, tests, architecture, drift, constitution, event model
make dev         # the service in the foreground
make demo        # the whole thing in containers, printing the addresses once it answers

Then open an agent session and type /drive. It walks the ladder from principles to a demo the actor can see, and enters at the first stage whose artifact is missing. See The delivery loop.

/drive stops when it needs a person: for a product decision, and at every demo. /cruise answers those stops itself and keeps going until the specification is satisfied. It has a section of its own, next.

Cruise: /drive with nobody at the wheel

/cruise is the same ladder as /drive, with the two stops that wait for a person answered by the machine. It decides as the product owner. It runs each demo as the actor. It goes on, one iteration after another, until the specification is satisfied, and it stops only for you. Nothing about what a stage produces changes. What changes is who answers.

What it promises.

• It stops only for a human. A stop file, Ctrl-C, or you typing into the session ends a run. A finished slice, a demo, a product question, a stale checkout or a full context does not.
• Every answer is written down twice. Once where /drive would have written yours, and once in one decision log per feature, specs/<feature>/decisions.md: the question, the options, the decision, the reason, who decided, and what it was written into. Overturn any entry by changing its status and writing the answer you want into the artifact it names. The next iteration re-enters the ladder from there. A decision that would cost a migration to reverse — an event's schema, stream identity, tenancy, the store, personal data — is also an ADR at Proposed under docs/adr/, for you to accept or supersede.
• It never invents a fact. A credential, an external system, a person's approval: the slice is marked blocked, the run takes the next ready slice, and a strong delegate works around the block — a fake behind the port, recorded as a fake, or the narrower reading that keeps every rule — and writes down what it did.
• Every merge is dark. Under the default release setting each slice ships behind a flag seeded off. Nothing the run merged reaches a real actor until you turn a key on.
• Done means the specification is satisfied. When the split runs out, an audit reads the specification against what shipped. Each finding becomes a new slice, or a recorded decision that it is out of scope. Only an audit with nothing left ends the run.

How to run one. It ships switched off.

/cruise-settings enabled=true            # switch it on; commits .specify/cruise.json
/cruise use the PRD in docs/prd.md       # start the runner, detached, and watch it from this session
/cruise-status                           # is it running, how the last iteration ended, the feed's tail
/cruise-tell take the payments feature next   # queued for the next iteration; --now ends the one in flight
/cruise-stop                             # end the run after the iteration in flight; `now` ends it now

Or make cruise from a terminal. Either way the runner is the one thing that continues a run: one fresh headless session per iteration, through any coding-agent CLI on the PATH, until the last line says done. The session you typed in takes the watch seat. It shows the feed as the iteration works — each command, file and delegate — answers you while it watches, and changes a setting when you ask. Leaving the seat ends nothing; /cruise typed again later sits back down where the feed left off.

Steer it without stopping it. .specify/product-owner.md is the owner brief: who the actor is, what the product is for, priorities and tie-breakers, taste, what is out of scope, and what must always ask a person. The skipper reads it before every decision, so editing it steers the next one. /cruise-settings sets who decides, how it releases, what a demo is driven with, which model the iteration runs on, and the budgets — iterations, hours, and how many unchanged iterations count as stuck.

Afterwards, read specs/<feature>/cruise-report.md for what shipped and what was ruled out, then decisions.md for every decision and its reason, then each slice's demo-log.md and the evidence under demo/, then the flags: nothing is visible until you turn one on.

Run it in a sandbox. An unattended loop runs with the permissions a normal run has; bypassing them all needs the runner's --sandbox flag, and a container around the run. Cruise has the whole of it: the three roles, what it does at each of /drive's stops, every setting, and the limits.

What you get

Everything below is in a generated repository from its first commit. The full tour is here. Each row links to the page that covers it properly.

The commands a project gets

Seventeen, of which fifteen are in standard. A repository that adopted the method gets four more. None of them is copied: each is generated against this project's profile, languages, frameworks and services, so the paths and toolchains named in them are real.

The delivery loop describes each one in full, and the ladder they sit on.

The three that change settings

Run any of them with no arguments to see the current setting. Pass arguments to change it. Each refuses a value it does not know and writes nothing, and each asks you to commit the settings file on its own — the choice is versioned with the project.

/drive-settings — how much one implementation delegate is handed, and how many failing tests a cycle opens with. It writes .specify/drive.json.

/drive-settings                             # show both settings
/drive-settings delegate=task               # one delegate per task
/drive-settings cycle=example               # one failing test at a time
/drive-settings delegate=story cycle=rule   # back to the defaults

delegate takes story, rule or task. cycle takes rule or example. cycle=story is refused: that is the batch Principle V prohibits.

/model-delegation-settings — which model runs each stage of /drive. It writes .specify/models.json.

/model-delegation-settings                  # show the table
/model-delegation-settings implement=strong # move a stage to the strong role
/model-delegation-settings claude.fast=haiku  # map a role to a model on one harness

A stage=role argument moves a stage between strong and fast. A harness.role=identifier argument says what a role runs on. Changing it also rewrites the agent types, so the harnesses cannot drift apart.

The change takes effect at the next stage /drive runs. Nothing already running is interrupted.

/cruise-settings — how /cruise runs /drive with nobody at the wheel. It writes .specify/cruise.json.

/cruise-settings                            # show every setting
/cruise-settings enabled=true               # switch it on; it ships switched off
/cruise-settings release=park               # stop before every push and ask a person
/cruise-settings max_hours=8                # give a run a budget

enabled switches the command on. decide says who answers a product question. release says whether every merge stays behind a flag or waits for a person. hand says what a demo is driven with, a browser first. The rest bound the run: when it counts as stuck, how many iterations or hours it may take, how often a parked run looks for a reason to resume. Cruise explains each one.

The answers you give

Beyond the profile, each role is a separate question, answered independently:

The default is event-modelling with typescript, the react-vite frontend, a Postgres event store, and the HTTP transport that backend has.

Both identity questions default to none, and they are genuinely different questions. Keycloak answers either one with a realm of its own, in one local container: a staff realm with groups, or a customers realm with self-registration, password reset and browser login. A service's token validation is only written where a framework owns it.

--event-store memory --http none gives a project with no infrastructure at all.

An unimplementable combination is refused rather than half-ported. Project shape says which is which, what each answer brings, and how a project answers a question again later.

Documentation

Using the factory

What a generated project gets

Working on the factory

Adding a language, a framework, a backing service, a target or an extension each has a skill under .claude/skills/ that walks the whole checklist.

Licence and contributing

Slipwai is licensed under the MIT License. Some adapted skills carry their own nested licence, including cli-design under CC BY-SA 4.0. NOTICE lists them, and each complete notice remains beside its material.

Public issues and proposed changes belong on the GitHub mirror. See CONTRIBUTING.md, and report vulnerabilities through SECURITY.md.