@sylad/cadence 1.15.0 → 1.15.1

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "cadence",
       "description": "Session start and close rituals driven by a versioned plan (raf), and deliveries proven by their effect. Needs the cadence CLI (npm i -g @sylad/cadence).",
-      "version": "1.15.0",
+      "version": "1.15.1",
       "source": "./",
       "author": {
         "name": "Sylvain Ladoire"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cadence",
   "description": "A repo-native working method: session start and close rituals driven by a versioned plan (raf), deliveries proven by their effect, and three reviewer agents (UX, code, QA).",
-  "version": "1.15.0",
+  "version": "1.15.1",
   "author": { "name": "Sylvain Ladoire" },
   "homepage": "https://github.com/Sylad/cadence",
   "repository": "https://github.com/Sylad/cadence",

package/README.md

@@ -17,6 +17,12 @@ raf add "My first lot" --estimate 1
 
 Then `raf start L1`, commit with `feat(L1): …`, `raf now` to see where you are, `raf done L1` when it is finished.
 
+## Lead several projects in 10 minutes
+
+A parent folder, a plan in each project, a `/cadence:lead` session that picks the lots, a wave that does the work.
+[docs/quickstart.md](docs/quickstart.md) goes from install to the first wave, and lists the usual stops.
+Something broken or missing? [Open an issue](https://github.com/Sylad/cadence/issues/new/choose).
+
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/cycle-vague-dark.svg">
   <img alt="A lot goes through spec, mockup, accept, implement, review, ux and deliver; the lead picks the lots, answers the questions, re-verifies and delivers" src="docs/cycle-vague-light.svg">

package/docs/overview.md

@@ -61,6 +61,7 @@ The two plugins are independent. `cadence@cadence` carries the rituals, which ca
 
 | Page | What it covers |
 |---|---|
+| [docs/quickstart.md](quickstart.md) | getting started as a lead of several projects, in 10 minutes: install, the parent folder, `raf init`, the tour, the first wave |
 | [docs/raf.md](raf.md) | the plan: commands, plan file, foreign plan formats, Gantt |
 | [docs/orchestrate.md](orchestrate.md) | waves of sessions: budgets, spec, accept and review steps, neighbouring repositories, one worktree per lot (`orchestrate.worktrees: true`, on in cadence's own `cadence.yaml`, off by default elsewhere; `--integrate`, `--replay`, `--remove-worktree`; recovery of a handed-back lot's branch and the `CHANGELOG.md` union at the integration are described there) |
 | [docs/deliver.md](deliver.md) | delivery: wait for CI, deploy, verify the effect |

package/docs/quickstart-dark.svg

@@ -0,0 +1,33 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1010 190" width="1010" height="190" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#e6edf3">
+<title>One lead, several projects, one wave</title>
+<desc>A parent folder holds the projects alpha and beta, each with its own plan. The lead session reads their tour and you choose the lots. A wave of fresh sessions does the work, then you review and deliver.</desc>
+<defs><marker id="arq" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#8b949e"/></marker></defs>
+<rect width="1010" height="190" fill="#0d1117"/>
+<text x="20" y="22" font-weight="600" font-size="13.5" fill="#e6edf3">1. Parent folder</text>
+<rect x="20" y="32" width="220" height="140" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5" stroke-dasharray="5 4"/>
+<text x="130" y="52" text-anchor="middle" font-size="11.5" fill="#8b949e">atelier/ (not a repository)</text>
+<rect x="40" y="64" width="180" height="42" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="130" y="83" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">alpha</text>
+<text x="130" y="98" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">raf init · plan</text>
+<rect x="40" y="116" width="180" height="42" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="130" y="135" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">beta</text>
+<text x="130" y="150" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">raf init · plan</text>
+<text x="300" y="22" font-weight="600" font-size="13.5" fill="#e6edf3">2. The lead</text>
+<rect x="300" y="64" width="210" height="94" rx="6" fill="#0c2d6b" stroke="#58a6ff" stroke-width="2"/>
+<text x="405.0" y="96" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Lead session</text>
+<text x="405.0" y="114" text-anchor="middle" font-size="11.5" fill="#c9d1d9">reads the tour, asks you</text>
+<text x="405.0" y="132" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#c9d1d9">/cadence:lead</text>
+<text x="570" y="22" font-weight="600" font-size="13.5" fill="#e6edf3">3. The wave</text>
+<rect x="570" y="64" width="200" height="94" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="670.0" y="96" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Fresh sessions</text>
+<text x="670.0" y="114" text-anchor="middle" font-size="11.5" fill="#8b949e">implement, then review</text>
+<text x="670.0" y="132" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">cadence orchestrate</text>
+<text x="830" y="22" font-weight="600" font-size="13.5" fill="#e6edf3">4. You</text>
+<rect x="830" y="64" width="160" height="94" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="910.0" y="96" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Review, deliver</text>
+<text x="910.0" y="114" text-anchor="middle" font-size="11.5" fill="#8b949e">one project at a time</text>
+<text x="910.0" y="132" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">/cadence:deliver</text>
+<polyline points="240,111 298,111" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arq)"/>
+<polyline points="510,111 568,111" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arq)"/>
+<polyline points="770,111 828,111" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arq)"/>
+</svg>

package/docs/quickstart-light.svg

@@ -0,0 +1,33 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1010 190" width="1010" height="190" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#1f2328">
+<title>One lead, several projects, one wave</title>
+<desc>A parent folder holds the projects alpha and beta, each with its own plan. The lead session reads their tour and you choose the lots. A wave of fresh sessions does the work, then you review and deliver.</desc>
+<defs><marker id="arq" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#57606a"/></marker></defs>
+<rect width="1010" height="190" fill="#ffffff"/>
+<text x="20" y="22" font-weight="600" font-size="13.5" fill="#1f2328">1. Parent folder</text>
+<rect x="20" y="32" width="220" height="140" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5" stroke-dasharray="5 4"/>
+<text x="130" y="52" text-anchor="middle" font-size="11.5" fill="#57606a">atelier/ (not a repository)</text>
+<rect x="40" y="64" width="180" height="42" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="130" y="83" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">alpha</text>
+<text x="130" y="98" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">raf init · plan</text>
+<rect x="40" y="116" width="180" height="42" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="130" y="135" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">beta</text>
+<text x="130" y="150" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">raf init · plan</text>
+<text x="300" y="22" font-weight="600" font-size="13.5" fill="#1f2328">2. The lead</text>
+<rect x="300" y="64" width="210" height="94" rx="6" fill="#ddf4ff" stroke="#0969da" stroke-width="2"/>
+<text x="405.0" y="96" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Lead session</text>
+<text x="405.0" y="114" text-anchor="middle" font-size="11.5" fill="#57606a">reads the tour, asks you</text>
+<text x="405.0" y="132" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">/cadence:lead</text>
+<text x="570" y="22" font-weight="600" font-size="13.5" fill="#1f2328">3. The wave</text>
+<rect x="570" y="64" width="200" height="94" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="670.0" y="96" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Fresh sessions</text>
+<text x="670.0" y="114" text-anchor="middle" font-size="11.5" fill="#57606a">implement, then review</text>
+<text x="670.0" y="132" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">cadence orchestrate</text>
+<text x="830" y="22" font-weight="600" font-size="13.5" fill="#1f2328">4. You</text>
+<rect x="830" y="64" width="160" height="94" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="910.0" y="96" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Review, deliver</text>
+<text x="910.0" y="114" text-anchor="middle" font-size="11.5" fill="#57606a">one project at a time</text>
+<text x="910.0" y="132" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">/cadence:deliver</text>
+<polyline points="240,111 298,111" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arq)"/>
+<polyline points="510,111 568,111" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arq)"/>
+<polyline points="770,111 828,111" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arq)"/>
+</svg>

package/docs/quickstart.md

@@ -0,0 +1,138 @@
+[← cadence](../README.md)
+
+# Start in 10 minutes: one lead, several projects
+
+You keep a folder with a few small projects. A **lead** session looks at all of them, you choose what to
+do, and a program runs each lot in fresh sessions. This page takes you from nothing to the first wave.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="quickstart-dark.svg">
+  <img alt="A parent folder holds the projects alpha and beta; the lead session reads their tour and you choose; a wave of fresh sessions works; you review and deliver" src="quickstart-light.svg">
+</picture>
+
+The commands below were played on a clean Windows 11 machine with WSL (Ubuntu 24.04, L357): about 40 seconds of commands,
+29 of them for Node and Claude Code. The rest of the ten minutes is reading and typing.
+
+## Before you start
+
+You need four things; the page says how to check each.
+
+- **Node 22.18 or later** (`node --version`). If you have none: [nvm](https://github.com/nvm-sh/nvm), or the NodeSource
+  package of your distribution (`setup_22.x`). Node 20 is not enough.
+- **git, with an identity.** Without one, the first `git commit` stops with `empty ident name`:
+
+  ```sh
+  git config --global user.name "Your Name"
+  git config --global user.email "you@example.com"
+  ```
+
+- **Claude Code, installed and logged in.** `claude auth status` must print `"loggedIn": true`. A wave opens
+  `claude -p` sessions and stops at the first one with `Not logged in · Please run /login` otherwise.
+  Install it from [claude.com/claude-code](https://claude.com/claude-code), then run `claude` once and log in.
+- **A test command** for each project (`npm test`, `pytest`, `go test ./...`). The wave runs it after every change.
+
+## Install
+
+```sh
+npm install -g @sylad/cadence
+cadence --version
+```
+
+If npm answers `EACCES: permission denied, mkdir '/usr/lib/node_modules/@sylad'`, your Node belongs to the system.
+Give npm a folder of your own, then install again:
+
+```sh
+npm config set prefix ~/.npm-global
+export PATH="$HOME/.npm-global/bin:$PATH"     # add this line to ~/.bashrc or ~/.zshrc too
+npm install -g @sylad/cadence
+```
+
+The skills and agents come as a Claude Code plugin:
+
+```sh
+claude plugin marketplace add Sylad/cadence
+claude plugin install cadence@cadence
+```
+
+## The parent folder
+
+The lead works from a folder that holds the projects as sub-folders. The folder itself is not a repository.
+Each project is one: give it a plan with `raf init`, a first lot, and the test command, in one commit.
+Run the block once per project (here `alpha`, then `beta`):
+
+```sh
+mkdir alpha && cd alpha
+git init -b main
+raf init
+raf add "Create hello.txt containing hello" --estimate 0.25
+cat > cadence.yaml <<'EOF'
+orchestrate:
+  test: test -f hello.txt        # passes once the first lot has created hello.txt
+EOF
+git add -A && git commit -m "chore: init raf"
+raf ignore $(git rev-parse --short HEAD)
+git add .cadence/raf.yaml && git commit -m "plan: acknowledge init"
+cd ..
+```
+
+What it does: `raf init` writes the plan (`.cadence/raf.yaml`), a commit hook and a `.gitignore` line. The commit
+that adds the plan cites no lot, so `raf` warns `commit sans lot` and `raf check` would list it as a gap: `raf ignore`
+acknowledges it once, and the plan records that. `cadence.yaml` is the project's settings file; its single
+`orchestrate.test` line is the minimum the wave needs, and without it the tour warns `porte de tests absente`.
+The folder is empty, so the gate here is `test -f hello.txt`, which the toy lot satisfies. On a project that already exists,
+put its own test command there (`npm test`, `pytest`, `go test ./...`): `npm test` in a folder without `package.json` fails.
+The reference for every other key is [orchestrate](orchestrate.md) and [deliver](deliver.md).
+
+Then, from the parent folder:
+
+```sh
+cadence lead tour
+```
+
+It prints one line per project: lots in progress, drift, next lot, repository state. Expect `alpha · en cours rien ·
+dérive aucune · … · prochain L1 Create hello.txt containing hello · dépôt propre`, and the same for `beta`. This is the table the lead reads.
+
+## Start the lead
+
+Open Claude Code in the parent folder and call the skill:
+
+```sh
+claude
+```
+
+then type `/cadence:lead` (or say « pilot all projects »). The lead runs the tour, reports in a table, proposes three
+lots and **waits for your priority**: nothing starts before you answer. [The lead workflow](lead.md) draws every step.
+
+## The first wave
+
+When you pick `alpha:L1`, the lead launches a wave. You can do it yourself, from the parent folder:
+
+```sh
+cadence orchestrate alpha:L1 --dry-run
+cadence orchestrate alpha:L1 --wave first
+```
+
+The first line only prints what would run: each step, its model and its budget. The second runs the lot in fresh
+sessions: implement, then review, and hands the lot back to you. From inside a project, write `.:L1` instead of
+`alpha:L1` (the project is a sub-folder of the current folder, so `alpha:L1` from inside `alpha` finds nothing).
+
+The sessions of a wave never push and never deliver. You read the table, answer the questions it brings back, then
+`/cadence:deliver` ships one project at a time ([deliver](deliver.md)). How waves, budgets and reviews work: [orchestrate](orchestrate.md).
+
+## If it stops
+
+| You see | Cause | Do |
+|---|---|---|
+| `npm: command not found` | no Node | install Node 22.18+ (above) |
+| `EACCES: permission denied, mkdir '/usr/lib/node_modules/@sylad'` | system-owned Node | `npm config set prefix ~/.npm-global` (above) |
+| `fatal: empty ident name … not allowed` | no git identity | the two `git config --global` lines (above) |
+| `Not logged in · Please run /login` | Claude Code not logged in | `claude`, log in, then `claude auth status` |
+| `porte de tests absente` | no `orchestrate.test` | the `cadence.yaml` line of the project block |
+| `alpha:L1 … introuvable` | launched from inside `alpha` | use `.:L1` |
+
+A problem that is not here: [open an issue](https://github.com/Sylad/cadence/issues/new/choose) with `cadence --version` and the command you ran.
+
+## Not played
+
+The lead skill and a wave played to the end (review, `raf done`, delivery) were not played on that machine, which was not logged
+in to Claude Code; the tour, the dry run and the dry delivery were. Other systems (macOS, native Linux, PowerShell without WSL) were not played either.

package/docs/whats-new.md

@@ -4,6 +4,7 @@
 
 ## In two lines
 
+- **1.15.1**: a getting-started page (`docs/quickstart.md`) takes a lead of several projects from install to the first wave and lists the usual stops; GitHub issue templates for bugs and requests; a contrast fix in the dark figure.
 - **1.15.0**: worktree integration settles the `CHANGELOG.md` conflict by itself; `--integrate` accepts a lot corrected and reviewed outside the wave; `raf ignore` clears a plan commit citing lots; `raf done` gives the plan commit.
 - **1.14.1**: publishes 1.14.0 (tagged, never published): Node 22.18 or later is required; `plan.commit`, `plan.onWrite`, `orchestrate.testReplay`, `spec green`, `ref coverage` and `verify --gate --sha`.
 - **1.14.0**: Node 22.18 or later is now required (Node 20 dropped). `plan.commit`, `plan.onWrite` and `orchestrate.testReplay` fit a wave to your hooks, files and load; `spec green`, `ref coverage` and `verify --gate --sha` are new.
@@ -36,6 +37,8 @@ Each is a paragraph in [docs/whats-new.md](whats-new.md) and a full section in [
 
 The long form of « In two lines » above (the README no longer carries a « What's new » section since L326: it links here). The full history, with the date of each version, is in [CHANGELOG.md](../CHANGELOG.md).
 
+**1.15.1**: a way in for a lead who has never used cadence. A new getting-started page, `docs/quickstart.md` (L358, a section of the README), goes from install to the first wave: the parent folder, `raf init` in each project with the minimal `cadence.yaml`, the tour, `/cadence:lead`, the first wave, and a table of the usual stops (no Node, `EACCES`, no git identity, Claude Code not logged in). It comes from a walkthrough measured on a clean machine. Two GitHub issue templates, bug and request, are forms (L358, `.github/ISSUE_TEMPLATE/`); a `config.yml` turns off blank issues and points to the getting-started page, and the bug form asks for `cadence --version`, the steps and what was printed. The dark getting-started figure (`docs/quickstart-dark.svg`) draws the grey texts of « Lead session » in a lighter grey, 4.26:1 on the blue before and now above the 4.5:1 of WCAG 2.2 AA, and `docs/overview.md` lists `docs/quickstart.md` in its map of the pages (L374).
+
 **1.15.0**: fewer lots handed back, and fewer manual detours, on the lead's side. The integration of `cadence orchestrate` in worktree mode no longer hands a lot back for a `CHANGELOG.md` conflict when the branch was released while the lot lived (L369, `docs/orchestrate.md`): an entry that the release moved under the published version is no longer read as a removal, and the entries a lot's commits wrote then reworded are dropped in favour of the version at the tip of the lot's branch, so one final entry per lot is left. `cadence orchestrate --resume --integrate <project:lot>` now accepts a lot handed back for its budget or a non-compliant review that the lead corrected and reviewed outside the wave (L370, `docs/orchestrate.md`, `docs/lead.md`): fix in the worktree, `raf review` there with the plan committed there, then `--integrate`; the lot restarts at the integration step with that verdict instead of the refusal « le lot n'est pas rendu à l'étape d'intégration ». A review older than a commit of the lot, or none, keeps the refusal. If the lead also wrote on that lot in the repository's plan meanwhile, the plan conflict of the rebase is settled by the program, provided that plan commit adds nothing but lot reviews. `raf ignore` also acknowledges a commit that cites known lots (L372): a plan commit that creates lots or cites a setting in parentheses was counted as work on those lots and could not be cleared; an acknowledged commit now counts for no lot, `raf commits` no longer lists it, and `raf check --ignored` does. `raf done <lot>` says that it did not commit the plan (L371): it never has, `raf` only writes the plan file, so when the plan or a file `plan.onWrite` produces has changes, the message prints the `git add` and `git commit` that take them, the subject following the project's `plan.commit` template.
 
 **1.14.1**: 1.14.0 was tagged but never published (a test of the Node minimum read only `[Unreleased]`, which the version commit empties, a fault of the test and not of the tool, L368); 1.14.1 publishes it as it stands, so everything listed under 1.14.0 below arrives with it, Node 22.18 or later first.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sylad/cadence",
-  "version": "1.15.0",
+  "version": "1.15.1",
   "description": "A small, repo-native working method: a versioned plan linked to your commits, a changelog with screenshots, session rituals and deliveries proven by their effect.",
   "license": "MIT",
   "author": "Sylvain Ladoire",
@@ -44,6 +44,9 @@
     "docs/fonctionnement-lead-dark.svg",
     "docs/lead-workflow-light.svg",
     "docs/lead-workflow-dark.svg",
+    "docs/quickstart.md",
+    "docs/quickstart-light.svg",
+    "docs/quickstart-dark.svg",
     "docs/cycle-vague-light.svg",
     "docs/cycle-vague-dark.svg",
     "LICENSE"