slipwai 1.1.0.dev15__tar.gz → 1.2.0.dev7__tar.gz

slipwai-1.2.0.dev7/CHANGELOG.md

@@ -0,0 +1,136 @@
+# Changelog
+
+No public releases yet. Release notes are recorded here newest first.
+
+## 1.1.0 — MINOR
+
+**`/drive` bounds its convergence loop, checks the branch before it reads the artifacts, and gives a
+delegate the one legal way to watch a test fail.** Measured on a project running the generated workflow:
+convergence and the rework it ordered cost one slice 12.9 times its implementation, because the stage's exit
+condition was the judgement of the model being looped and nothing bounded it; a `/drive` on a branch
+fifty-seven commits behind trunk wrote a second example map for a slice that had shipped, because every
+artifact the ladder reads is a property of the commit it is on; and two delegates in a row reached for
+`git stash` and a copied-aside backup, both forbidden, because they needed to observe a failure without
+dirtying the tree and the safety page forbade the routes without naming one. Now the convergence rung stops
+at two passes by default and appends what is still open as Phase 4 tasks, only a `CRITICAL` or `HIGH` finding
+re-opens it and only a `CRITICAL` re-opens it past the bound, the first pass is handed every abstraction level to account for, the tree is checked clean after
+every pass including a stopped one, and a stopped pass's last line is a lead to re-run rather than a finding
+to file. The entry-stage evidence names the branch, its head and its distance from trunk, and an unreachable
+remote reads as *could not verify*, never as *current* or as every slice unclaimed. The implement brief and
+the safety page name the sanctioned move — change the production file, run the test, restore that one path —
+and ask whether each RED was observed before the implementation existed. A brief may name where a fact lives
+without asserting what it says, the host derives concurrency from disjoint manifests rather than waiting for a
+`[P]` the task list only applies to production-code contention, and `./init` says to restart the session
+before delegating, since a harness reads its agent types once.
+
+**`/drive` delegates implementation on two settings a project sets once and changes at any time — how much
+one delegate is handed, and how many RED tests one cycle opens with — with `/drive-settings` as the checked
+way to change either.** A project running the generated workflow measured most of a slice's implementation
+wall as each fresh delegate re-reading the same plan, map, precedent and test file, one task at a time, and
+ten of that slice's tasks as proofs with nothing to turn green because a rule had been cut up to fit one test
+per increment. `.specify/drive.json`, beside the models table, now carries `delegate` — `story`, every rule of
+one user story as its own cycle in one context; `rule`; or `task` — and `cycle` — `rule`, a rule's examples
+together, each failing for its own stated reason, stub-first; or `example`, one at a time. The defaults are
+`story` and `rule`. A story is never a cycle unit, since that is the batch Principle V prohibits, and
+`scripts/agents/drive.py` refuses it. Two vetoes override the defaults on a slice: no story tags falls to
+`rule`, and a map without numbered rules falls to `task` and `example`. Whatever the boundary, siblings with
+disjoint manifests run concurrently and a delegate may fan its work out inside its boundary under four
+constraints; one cycle is never parallel. `make check-agents` holds the file's shape, the stage line says both
+settings beside the model, and the implement entry records `delegate=`, `cycle=` and `split=N`, which `make
+benchmark` shows per slice.
+
+`/who-runs` is renamed `/model-delegation-settings`, so the two commands that set how `/drive` delegates read as a
+pair: which model runs each stage, and how implementation is handed out and driven. Its behaviour is unchanged.
+
+`/whats-next` joins `/where-are-we`: the board answers how far along the work is, and this answers what to do
+now — one slice, one stage, one command and the reason, in at most six lines, read off the same artifacts and
+running nothing.
+
+With it, four smaller things the same project reported. The generated Makefile names its Go modules once, in
+`GO_MODULES`, and both `lint` and `format` read it, so the two can no longer cover different paths. `./init`
+installs Spec Kit at the release `project.json` now records as `speckitSource`, so restoring the ignored
+projections is no longer a silent upgrade to upstream HEAD; `SPECIFY_SOURCE` still overrides it. The
+extension contract gains its sixth obligation: a file the user must hand-edit is a merge target, never a write
+target. And the event-model renderer says which variable to set when Chromium refuses to start as root.
+
+**Catch-up.** `commands/who-runs.md` is gone and `commands/model-delegation-settings.md` arrives in its place;
+the merge offers the deletion and `make agents` reprojects the harness copies, so a harness that still lists
+`/who-runs` has not been reprojected. `.specify/drive.json` and the `speckitSource` field of `project.json` arrive
+through the merge;
+a project that wants one delegate per task, or one test per cycle, runs `/drive-settings` once. A project that
+wants to stay on the Spec Kit it has edits `speckitSource` before its next `./init --integration`. `make
+format` and `make lint` now read `GO_MODULES`: a Go module the project added under `packages/` by hand goes on
+that line, once.
+
+**`make mutation` on a Go service keeps its report, and `make mutation SINCE=<branch-or-commit>` prices the
+stage per change rather than per repository.** The report was Gremlins' own `gremlins.json`, written inside
+the staging tree `scripts/go-mutation.py` builds and deletes, so the target left a scrollback where a slice
+record expects its evidence; it is now copied to `<service>/gremlins.json` before the cleanup, whether the
+run passed or failed, and git-ignored beside `coverage.out`. `SINCE` scopes the run to the production files
+that differ from that ref: a project measured 324 mutants in 31 minutes where seven belonged to the change
+being driven, and a stage that expensive gets routed around rather than read. The unscoped target is
+unchanged and is the full sweep.
+
+The scope is computed from git before anything is staged, not handed to Gremlins' `--diff`, which is
+unusable from a module in a subdirectory: it resolves changed paths against the repository root, matches
+them against paths within the module, and reports every mutant SKIPPED and the run successful — verified
+against 0.6.0, from the module directory and the repository root alike. Gremlins has no include list either,
+so the scope is a complement of `--exclude-files` patterns generated per run, and because that flag replaces
+the yaml's list rather than adding to it, the wrapper reads `.gremlins.yaml`'s own exclusions and passes
+them back. A change confined to files the project already excludes scopes to nothing and says so, rather
+than failing as a run that mutated nothing. An `exclude-files` written inline is a loud failure: a scope
+silently read as empty is the one outcome that would mutate what the project excluded on purpose.
+
+**Catch-up.** A Go service's mutation stage takes all of this through the merge — `scripts/go-mutation.py`,
+the `mutation:` recipe, the `.gitignore` line, the note above the target and the yaml's comments — so there
+is nothing to install and no answer to give. Two things to look at while resolving that merge. A project
+that edited `apps/<service>/.gremlins.yaml` or the `mutation:` recipe meets a conflict in the comments or on
+the recipe line: keep its own values and take the `$(if $(SINCE),...)`, which
+is what makes `SINCE` reach the script. And `gremlins.json` is now ignored at any depth, the way
+`coverage.out` already is — a mutation report a project keeps deliberately, as a slice record's evidence,
+must not be named `gremlins.json` or it stops being committed; name it for the run it belongs to, as a
+report recovered by hand before this version already had to be. Anything a project built to rescue the
+report from the staging directory can go.
+
+**The unit of a RED-GREEN-REFACTOR increment is one rule of the example map, not one test, and RED is a
+failing assertion rather than a failing build.** A project running the generated workflow found the tasks
+command routinely emitting tasks with an empty GREEN — proofs over behaviour earlier tasks had produced,
+ten of one slice's twenty-five — every one passing the moment it was written, which the constitution
+template classifies as a defect in the test. Both documents came from this factory and disagreed. The
+proof-only task is a symptom of the unit being too small: a rule had to be cut up to fit one test per
+increment, and the offcuts are the tasks that produce nothing. So Principle V in both profiles' constitution
+templates now takes one rule with its examples as the increment, written together or one at a time as the
+implementer judges, never spanning rules; and it adds the clause that makes that safe — whatever an example
+names exists far enough to compile against before the example is written, so each example fails for its own
+stated reason and a red build is never a red test. `/example-map` writes rules that own their examples
+(`R1`…`Rn`, each heading carrying its scenarios), never renumbered once cited and never retrofitted onto a
+map already implemented. The tasks brief and template cut one task per rule and fold a proof-only task into
+the increment it guards, and the implement delegate takes a task or a rule, chooses how to drive it, and may
+fan its increment out to sub-delegates over disjoint files under four constraints: a manifest that is a
+subset of its own, evidence verified against the tree rather than relayed, nothing it spawns writing
+`tasks.md`, and one report with one cycle's evidence.
+
+**Catch-up.** A ratified `.specify/memory/constitution.md` is human-owned and is not overwritten by the
+merge. Amend its Principle V by hand if this project wants the rule as its unit — the amendment is MINOR under
+the template's own versioning policy, since work built one test at a time stays compliant — and carry the
+stub-first clause even if it does not, since that clause holds whatever the unit. Maps already agreed keep
+their shape; the rule-owned format applies from the next slice mapped.
+
+## 1.0.0
+
+**A `./init` rerun that asks nothing of Spec Kit no longer reinstalls it, so adding an extension or
+re-answering an axis finishes where github.com is unreachable.** Every `./init` ran
+`specify init --here --force`, and where the `specify` CLI is not already installed that means fetching
+Spec Kit from its repository — so `./init --extension codegraph` in an offline sandbox, or
+`./init --repository <url>` once the forge tools were finally there, died on the network before doing any
+of the local work it was actually asked for. Now, when the argument scan leaves nothing to forward and
+`.specify/integration.json` records an installed integration — the file only `specify init` writes, since
+generation itself ships presets under `.specify/` — the bootstrap is skipped and the script says so.
+Anything Spec Kit-bound still delegates exactly as before: the first `./init`, and any rerun passing
+`--integration <agent>` or another forwarded flag.
+
+**Slipwai is available as an open-source project.** Version 1.0.0 is the first
+release in the public version line: a one-shot scaffolder for product
+monorepos, with generated verification, delivery workflows, migration support,
+and coding-agent guidance.
+

{slipwai-1.1.0.dev15 → slipwai-1.2.0.dev7}/NOTICE

@@ -18,9 +18,11 @@ notices:
 - event-modeling — current adaptation under the root MIT licence; its NOTICE
   records the CC0-1.0 starting point
 - find-skills — MIT; copyright Vercel, Inc.
+- frontend-design — Apache-2.0; copyright Anthropic, PBC
 - improve-codebase-architecture — MIT; copyright Matt Pocock
 - reduce-system-complexity — MIT; copyright Adam Bulmer
 - technical-writing — MIT; copyright Adam Bulmer
+- web-interface-guidelines — MIT (references/guidelines.md); copyright Vercel, Inc.
 - wtf — MIT; copyright Adam Bulmer
 
 The applicable licence notice and exact provenance for each adaptation remain

slipwai-1.2.0.dev7/PKG-INFO

@@ -0,0 +1,389 @@
+Metadata-Version: 2.5
+Name: slipwai
+Version: 1.2.0.dev7
+Summary: One-shot scaffolder for product monorepos: a walking skeleton, a verify gate, a path to production, and a repository set up for coding agents.
+Project-URL: Homepage, https://github.com/ROBCOATVG/slipwai
+Project-URL: Repository, https://git.treyco.dev/ROBCOATVG/slipwai
+Project-URL: Issues, https://github.com/ROBCOATVG/slipwai/issues
+Project-URL: Changelog, https://github.com/ROBCOATVG/slipwai/blob/main/CHANGELOG.md
+Author: Volaris Group
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+License-File: assets/toolkit/skills/LICENSE
+License-File: assets/toolkit/skills/acceptance-review/LICENSE
+License-File: assets/toolkit/skills/api-design/LICENSE
+License-File: assets/toolkit/skills/cli-design/LICENSE
+License-File: assets/toolkit/skills/codebase-design/LICENSE
+License-File: assets/toolkit/skills/diagrams/NOTICE
+License-File: assets/toolkit/skills/event-modeling/NOTICE
+License-File: assets/toolkit/skills/find-skills/LICENSE
+License-File: assets/toolkit/skills/frontend-design/LICENSE
+License-File: assets/toolkit/skills/improve-codebase-architecture/LICENSE
+License-File: assets/toolkit/skills/reduce-system-complexity/LICENSE
+License-File: assets/toolkit/skills/technical-writing/LICENSE
+License-File: assets/toolkit/skills/web-interface-guidelines/LICENSE
+License-File: assets/toolkit/skills/wtf/LICENSE
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Slipwai
+
+[![PyPI](https://img.shields.io/pypi/v/slipwai)](https://pypi.org/project/slipwai/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+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](https://git.treyco.dev/ROBCOATVG/slipwai).
+[GitHub](https://github.com/ROBCOATVG/slipwai) is the public mirror. Report issues and propose changes
+there.
+
+```sh
+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](#new-to-this--start-here) · [What it is](#what-it-is) ·
+[Getting started](#getting-started) · [What you get](#what-you-get) ·
+[The answers you give](#the-answers-you-give) · [Documentation](#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.
+
+| Path | When |
+|---|---|
+| **[Generate a new project](docs/learn-generate.md)** | You want a fresh repository. You get a walking skeleton, a gate and a delivery method from a few answers |
+| **[Adopt an existing repository](docs/learn-adopt.md)** — experimental | You already have a codebase. Install the method around it, without rewriting it first |
+
+---
+
+## 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.
+- **`./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](docs/upgrading.md) 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
+
+| Profile | Includes | When it fits |
+|---|---|---|
+| `standard` | A walking skeleton, an executable test, a local and CI `verify` gate, a minimum-CD constitution, and the delivery skills and commands | A supporting subdomain, a tool, a spike, an internal script — anything short-lived |
+| `event-modelling` | Everything above, plus **Event Modeling and event sourcing as one bundle** — the global model, example mapping, and the model-to-code gate | A product or core domain a team will grow for years |
+
+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](docs/axes.md#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](#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](docs/learn-generate.md), or
+[adopt](docs/learn-adopt.md) for an existing tree. Both cover install, first session, upgrade, migrate and
+`/catch-up`, with terminal screenshots.
+
+[Scaffold a new project](docs/generating.md) is the full reference.
+[Tools required](docs/requirements.md) 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.
+
+```sh
+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](docs/executable.md).
+
+`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](docs/maintaining.md) 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](docs/requirements.md) has the full list. Running costs are in
+[The AWS target](docs/aws-target.md) and [The Azure target](docs/azure-target.md), 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:
+
+```sh
+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:
+
+```sh
+./init
+```
+
+That installs Spec Kit. It then asks which coding agent to project `skills/`, `commands/` and `agents/`
+into — any of [36 harnesses](docs/spec-kit.md). 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](docs/extensions.md).
+
+### 4. Work in it, and run it
+
+```sh
+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](docs/delivery-loop.md).
+
+---
+
+## What you get
+
+Everything below is in a generated repository from its first commit.
+**[The full tour is here](docs/what-you-get.md)**. Each row links to the page that covers it properly.
+
+[![The delivery loop: run once — principles, specify, gaps, model the events, split into slices — then once per slice: example map, gaps, plan, tasks, implement, converge, gaps, demo, adversary, mutation, next slice](docs/images/delivery-loop.svg)](docs/delivery-loop.md)
+
+| | |
+|---|---|
+| **[The delivery loop](docs/delivery-loop.md)** | `/drive`'s ten-stage ladder on top of Spec Kit. It is resumable, because it reads artifacts rather than conversation memory. Fifteen workflow commands, thirteen of them in `standard`. Story splitting and example mapping are first-class stages with real heuristics behind them. Hooks apply the method even to a session that never typed `/drive` |
+| **[Up to 51 skills](docs/skills.md)** | The part of the delivery catalogue this project can use, owned by the project: TDD, testing, hexagonal architecture, DDD, ubiquitous language, API and BFF design, observability, secure OAuth/OIDC, refactoring, debugging and more. Code examples are rendered in the languages this project's services are actually written in |
+| **[The global event model](docs/event-model.md)** | *Event profile.* One cumulative model for the whole system, in `model.yaml`. `make model` renders the timeline, the per-segment diagrams and a self-contained browsable page. `make check-model` fails when the code and the model disagree |
+| **[The read side](docs/what-you-get.md#the-read-side)** | *Event profile.* The machinery a view is *maintained* with, finished in every backend rather than left as the greenfield half: a unit of work on the event store; a `CheckpointStore` port with memory, SQLite and Postgres adapters behind a contract suite of its own; a catch-up runner that advances the checkpoint inside the view's own transaction; a rebuild; whatever each framework already schedules a pass with; and a tag index derived from the log, so a conditional append can hold a boundary one stream cannot |
+| **[Gates](docs/verification.md)** | `make verify` runs native checks, tests, architecture direction, agent and Spec Kit drift, constitution coverage, and the event model. It is identical locally and in CI, and never needs Docker. Integration, adversarial, mutation and audit checks sit deliberately outside it |
+| **[Spec Kit, properly installed](docs/spec-kit.md)** | Obtained on demand rather than vendored. Customised through a preset layer, so it is never edited in place and `specify integration upgrade` stays automatic. The constitution is held to a floor from both directions |
+| **[36 agent harnesses](docs/what-you-get.md#one-canonical-source-36-agent-harnesses)** | One canonical `skills/`, `commands/` and `agents/`, projected into Claude Code, Cursor, Codex, Copilot, Gemini CLI, Zed and 30 more. Each delegated stage gets a named agent type, carrying its model and as much of its write scope as that harness can enforce. A gate fails when a projection drifts |
+| **[Generated documentation](docs/what-you-get.md#documentation-written-for-this-project)** | Thirteen pages written for this project's actual shape rather than copied, and an index built from the files that shipped |
+| **[Services and bounded contexts](docs/services.md)** | One list of applications, each with its own language, framework and answers. `add-service` and `add-frontend` grow it. Contexts are found rather than declared |
+| **[A path to production](docs/aws-target.md)** | `--target aws` or `--target azure` gives you `infra/` in OpenTofu, one deployable per application released blue/green, a pipeline from every push to `main` through staging to production, and a one-command rollback. The same promise on either cloud. [The Azure page](docs/azure-target.md) is where they are compared |
+| **[Extensions](docs/extensions.md)** | Optional dev tooling, adopted with `./init --extension <key>`: a code index, a design-system generator, and objective UX gates in `make verify`. None of them changes the generated skeleton's code |
+
+### The commands a project gets
+
+Fifteen, of which thirteen 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.
+
+| Command | What it does |
+|---|---|
+| `/drive` | Takes one slice from wherever it stands to a demo the actor can see |
+| `/whats-next` | Says what is next — one slice, one stage, one command. Reads the disk and changes nothing |
+| `/where-are-we` | Shows the progress board: what works, what is in progress, what is still to come |
+| `/gaps` | Reviews an artifact for holes, before they become rewritten tests |
+| `/example-map` | *Event profile.* Turns one slice of the event model into rules, examples and executable scenarios |
+| `/validate-code-against-model` | *Event profile.* Checks that the code and the event model still agree |
+| `/adversary` | Attacks a finished slice: hostile inputs, replays, interleavings, authorisation paths |
+| `/mutation` | Runs the backend's own mutation testing, to find tests that do not really test |
+| `/catch-up` | After a migration, works through what the newer factory now asks of code it did not write |
+| `/add-service` | Adds a service, with its own language, framework and answers |
+| `/add-frontend` | Adds a browser app |
+| `/benchmark` | Draws what each slice cost and how each stage did |
+| `/constitution-coverage` | Checks the constitution against the floor this project depends on, or prints the floor |
+| `/drive-settings` | Shows or changes how `/drive` hands implementation to a delegate |
+| `/model-delegation-settings` | Shows or changes which model runs each stage of `/drive` |
+
+[The delivery loop](docs/delivery-loop.md) describes each one in full, and the ladder they sit on.
+
+#### The two that change settings
+
+Run either with no arguments to see the current setting. Pass arguments to change it. Both refuse a value
+they do not know and write nothing, and both ask 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.
+
+---
+
+## The answers you give
+
+Beyond the profile, each role is a separate question, answered independently:
+
+| Question | Flag | Answers |
+|---|---|---|
+| Foundation | `--profile` | `standard`, `event-modelling` |
+| Production target | `--target` | `none`, `aws`, `azure`, `existing` (experimental) |
+| Backend language | `--language` | `typescript`, `python`, `go`, `java` |
+| Framework, where a language offers more than one | `--framework` | `quarkus`, `spring-boot` (or name the pair at once: `--backend java-spring`) |
+| Frontend | `--frontend` | `none`, `react-vite` |
+| Event store | `--event-store` | `memory`, `sqlite`, `postgres` |
+| HTTP transport | `--http` | `none`, `fastify`, `fastapi`, `net-http`, `quarkus-rest`, `spring-web` |
+| Staff authentication | `--auth` | `none`, `keycloak` (local only), `cognito` (AWS), `entra` (Azure), `auth0` (either cloud) |
+| Customer authentication | `--users` | `none`, `keycloak` (local only), `cognito` (AWS), `auth0` (either cloud) |
+| Dev tooling | `--extension` | `codegraph`, `uipro`, `ux-gates` |
+
+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](docs/axes.md) says which
+is which, what each answer brings, and how a project answers a question again later.
+
+---
+
+## Documentation
+
+### Using the factory
+
+| Document | Covers |
+|---|---|
+| [Generate a new project — learning path](docs/learn-generate.md) | Install, generate, upgrade, migrate and `/catch-up`, with terminal screenshots |
+| [Adopt an existing repository — learning path](docs/learn-adopt.md) — **experimental** | Install, adopt, upgrade, migrate and `/catch-up`, with terminal screenshots |
+| [Scaffold a new project](docs/generating.md) | The interactive and argument forms, one-shot semantics, the generated repository layout, and the event-sourcing boundary between the services and `apps/web` |
+| [Bring a generated project forward](docs/upgrading.md) | `slipwai migrate`: a newer factory's output merged over a project already generated. What comes through clean, what conflicts and should, the catch-up notes it leaves for what a merge cannot do, and the gate that proves it |
+| [Adopt an existing repository](docs/adopting.md) — **experimental** | `slipwai adopt`: the method installed around a repository the factory did not make. The survey, the questions with the findings as defaults, what is written beside the code and never over it, what `project.json` records with provenance, and what it forfeits for a language the factory cannot generate |
+| [The two workflows](docs/two-workflows.md) | Generated and adopted side by side: the same delivery loop, where each starts on its ladders, the adoption phases woven into `/drive`, the convergence map, and `slipwai converge` as the point where the distinction ends |
+| [Project shape](docs/axes.md) | Profiles, target, language, frontend and the axes. What each answer brings, why an unimplementable combination is refused, and how a project answers an axis again later |
+| [Tools required](docs/requirements.md) | What scaffolding needs, and what each generated toolchain and `make` target needs |
+| [Install the command](docs/executable.md) | `uv tool install` and `pip install` from the forge's registry, the standalone executable, `slipwai upgrade`, and building and publishing both |
+
+### What a generated project gets
+
+| Document | Covers |
+|---|---|
+| [What a generated repository gets for free](docs/what-you-get.md) | The tour: the layout, the generated documentation, the agent harnesses, and how to run it |
+| [The delivery loop](docs/delivery-loop.md) | The `/drive` ladder and the diagram behind it, the fifteen commands, story splitting and example mapping with worked examples, the Spec Kit hooks, the preset layer, and the constitution floor |
+| [The skill catalogue](docs/skills.md) | The 51 skills grouped by what they are for, why a project is given only the ones whose subject it has, how examples are rendered in your own languages, and where to edit them |
+| [The global event model](docs/event-model.md) | Why the model is global, what `make model` renders, the status ladder `make check-model` enforces, and how the browsable page is published |
+| [Gates](docs/verification.md) | What `make verify` runs, what is deliberately outside it, and why the split falls where it does |
+| [Bootstrap Spec Kit](docs/spec-kit.md) | `./init`, the 36 agent integrations, how Spec Kit is obtained, and the constitution floor gated from both sides |
+| [Services](docs/services.md) | `project.json`'s one list of applications, everything that reads it, what a second service is in each language, `add-service` and `add-frontend` and their agent commands, and what a maintainer owes a new generated file that names an application |
+| [Extensions](docs/extensions.md) | `./init --extension <key>`, the contract every extension's `init.py` owes, and what makes a second one a catalog entry plus one file |
+| [The AWS target](docs/aws-target.md) | What `--target aws` gives: the stacks, the images, the pipeline and the rollback. What it costs, what the factory proves about it and what it cannot, and how the next cloud becomes a row |
+| [The Azure target](docs/azure-target.md) | The same for `--target azure`, held against that page line for line: what it costs against AWS and why the gap widens per service, the four places the promise is not quite the same, and what a third cloud would need |
+| [Auth0 on both identity axes](docs/auth0-identity.md) | `--auth auth0` and `--users auth0` under either cloud: what the stack creates, the human step no other row has, the three places it is not like for like, and why the provider is chosen at generation time rather than pruned |
+
+### Working on the factory
+
+| Document | Covers |
+|---|---|
+| [Work on the factory](docs/maintaining.md) | `make verify` and the gates it runs, how `src/slipwai/` is laid out and the check that keeps it that way, browsing generated starters, and regenerating dependency locks |
+| [Architecture decisions](docs/adr/) | The factory's own decisions, in the shape its `architecture-decisions` skill asks of a generated project. Here that mostly means the shape of something a project persists, because a project's log is the one thing no version of this factory can migrate for it. [`0001`](docs/adr/0001-a-dcb-capable-log.md) covers the log's derived tag index and why stream-per-aggregate stays the default write path. [`0002`](docs/adr/0002-the-guard-a-slice-declares.md) covers the guard a slice declares, and identity modelled while tags are not |
+| [The canonical toolkit](assets/README.md) | The asset tree: where to edit skills, docs, gate scripts, language and frontend packs, and axis adapters |
+| [What a backend owes](docs/backend-obligations.md) | The checklist behind adding a language or a framework: every axis, every `make` target and which gate runs it, every per-backend table, the choices that belong to the ecosystem rather than to this repository, and what a framework that owns startup provides instead of a hand-written adapter |
+| [Publish the factory to Gitea](docs/publishing.md) | `scripts/publish-to-gitea.py`, cutting a release with `make release`, and the local `pages` server |
+| [Changelog](CHANGELOG.md) | Every version, its bump level, what it changed, and what a repository generated by an earlier one owes to catch up |
+
+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](LICENSE). Some adapted skills carry their own nested licence,
+including `cli-design` under CC BY-SA 4.0. [NOTICE](NOTICE) lists them, and each complete notice remains
+beside its material.
+
+Public issues and proposed changes belong on the
+[GitHub mirror](https://github.com/ROBCOATVG/slipwai). See [CONTRIBUTING.md](CONTRIBUTING.md), and report
+vulnerabilities through [SECURITY.md](SECURITY.md).