@sylad/cadence 0.2.0 → 0.5.0

package/skills/deliver/SKILL.md

@@ -18,6 +18,28 @@ deliver:
       contains: "${SHORT}"   # the new version is the one being served
 ```
 
+A project that already has its own delivery script declares it instead — cadence then keeps the
+preconditions, the lock, the log and the delivered lots, and the script keeps the CI wait, the deploy
+and its business checks:
+
+```yaml
+deliver:
+  script: ./scripts/ship.sh "$CADENCE_SHORT"
+```
+
+Its arguments go after `--`: `cadence deliver -- api frontend` (`--sha <rev>` to deliver a pushed
+commit other than HEAD). Ask the human (or the project's own
+delivery skill) which arguments this delivery needs; never guess them.
+
+## Where to run
+
+Every `cadence` / `raf` command works on the git repository of the current directory. When the
+session runs from a parent folder that holds several projects (not itself a repository), run each
+command inside the project concerned: `cd <project> && cadence …`. The projects are the sub-folders
+that contain `docs/plan/raf.yaml`, or a `cadence.yaml` with a `plan:` key.
+
+Deliver one project at a time: the one the human names, or ask.
+
 ## Steps
 
 1. Before anything: tests and build green locally, everything committed **and pushed** — the CI can
@@ -28,7 +50,7 @@ deliver:
 3. `cadence deliver`. Exit codes: 0 delivered and verified, 1 a step failed, 2 refused before acting.
 4. On failure: read which step failed and why. Fix the cause, commit, push, deliver again. Never rerun
    blindly, never skip a check to make it pass.
-5. On success: `raf done <id>` for the lots it lists **whose effect you have seen**; if one of them is
+5. On success: `raf done <id>` (or the project's own tool when its plan is read-only) for the lots it lists **whose effect you have seen**; if one of them is
    `visible`, `cadence news build` and deliver the news too.
 
 ## Rules

package/skills/lead/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: lead
+description: Lead several cadence projects from a parent folder without loading them into the main context — fan out one subagent per project to gather the facts, agree the priorities with the human, delegate each chosen lot to a subagent with a standard brief, have the work reviewed, re-verify it yourself, then deliver one project at a time. Triggers — "/lead", "pilot all projects", "on pilote tout", "délègue aux sous-agents", start of a multi-project day.
+---
+
+# Lead — decide at the top, work in subagents
+
+The lead session stays small: it reads summaries, decides with the human, delegates, checks and
+delivers. Project files are read and changed by subagents, each with its own context. The projects
+are the sub-folders of the current directory that contain `docs/plan/raf.yaml`, or a `cadence.yaml`
+with a `plan:` key. A project whose `cadence.yaml` maps the fields of a plan kept by its own tool is
+**read-only** for `raf`: it takes part in the tour, and its plan is changed with the project's own
+commands (its CLAUDE.md names them), never with `raf start|done|note|ux|review`.
+
+## Limits that always apply
+
+- **At most two subagents running at once.** Queue the rest.
+- **Never two subagents in the same repository at the same time**, and the lead does not commit in a
+  repository where a subagent is working.
+- **Deliveries and `raf ux` / `raf review` verdicts are done by the lead, one project at a time** —
+  never by a subagent, never two deliveries in parallel.
+- A subagent cannot ask the human anything. When it hits an ambiguity it stops and reports; the lead
+  brings the question to the human.
+
+## 1. Tour of the projects
+
+For each project, a subagent (read-only) runs `cd <project> && cadence session start` and returns at
+most five lines: lots in progress (silent ones flagged), drift, notes from the last close, the next
+ready lot. Two at a time, in the background.
+
+Then report to the human in a compact table — one row per project — and propose **three** items
+across projects, each with project, lot id and one sentence of justification: finish what is in
+progress, then drift that blocks a delivery, then ready quick wins. **Stop and wait for the priority.**
+
+## 2. Delegation
+
+For each chosen lot, the lead runs `cd <project> && raf start <lot>`, then gives a subagent this brief
+(fill in the brackets, keep the rest verbatim):
+
+> Work in `<absolute path of the project>` on lot `<id>` — "<title>" — of its plan
+> (`docs/plan/raf.yaml`, or the file named by `plan:` in `cadence.yaml`; read the lot, its notes and sub-tasks, and the project's CLAUDE.md first).
+> Goal: <what done looks like, from the human's words>.
+> Rules: test first; commit each sub-part as soon as its tests pass, with explicit paths (never
+> `git add -A` or `commit -a`), and a message that cites the lot (`feat(<id>): …`); run the project's
+> full test suite and build before reporting; do not push, deliver, run `raf done`, `raf ux` or
+> `raf review`.
+> If something is ambiguous or needs a decision, stop and report the question instead of guessing.
+> Report: commits (sha + subject), tests and build results with their numbers, what you could not
+> verify, open questions.
+
+A lot that adds or changes a screen is `visible`: after the implementation, have the
+`ux-reviewer` agent review it (give it the URL or the way to run the app) and bring its verdict and
+proposed sub-tasks back to the human.
+
+## 3. Check
+
+1. The `code-reviewer` agent, as a fresh subagent (most capable model), reviews the lot. Give it
+   the absolute path of the project and the lot id, **not** the author's report: it reads the diff
+   itself from the commits that cite the lot, runs the checks, and returns real defects only,
+   ranked, with what it could not verify and a one-line verdict.
+2. **The lead re-verifies itself**: `git log` shows the commits, the test suite and build pass when
+   run by the lead, `raf check` is clean. A subagent is green on what it *could* test; say plainly
+   what nobody could verify.
+3. Fix or re-delegate what the review found; then record the verdict, `raf review <lot> "…"` with
+   the code reviewer's last line brought up to date (and `raf ux <lot> "…"` for a visible lot, with
+   the UX reviewer's), then `raf done <lot>`. Where the gate is on (`raf review enable`, the
+   human's decision for each repository), `raf done` refuses a lot that has commits and no
+   verdict, or a verdict older than its latest commit: a fix made after the review means a new
+   review of the lot, not an edited verdict. A read-only plan has no gate in `raf` (a `uxSince` or `reviewSince` written in it is
+   ignored): the verdict goes into the project's own tool.
+
+## 4. Delivery
+
+One project at a time, by the lead: push, then the `deliver` skill (`cadence deliver --dry-run`, then
+`cadence deliver`). Follow the human's standing instructions about confirmation before production.
+
+## 5. Close
+
+At the end, the `session-close` routine in each project touched, and `cadence session next` lines in
+each. Give the human one line per project: delivered, in progress, blocked (and why).

package/skills/session-close/SKILL.md

@@ -5,6 +5,16 @@ description: Close a work session on a repository that uses cadence — plan hyg
 
 # Session close — close without memorising everything
 
+## Where to run
+
+Every `cadence` / `raf` command works on the git repository of the current directory. When the
+session runs from a parent folder that holds several projects (not itself a repository), run each
+command inside the project concerned: `cd <project> && cadence …`. The projects are the sub-folders
+that contain `docs/plan/raf.yaml`, or a `cadence.yaml` with a `plan:` key.
+
+With no project named, run `cadence session close` in each project touched during the session
+(`git log --since` or `git status` tell which) and close each one.
+
 ## Steps
 
 1. Run `cadence session close` (over several days: `--since "2 days ago"`). Exit code 1 means
@@ -16,6 +26,10 @@ description: Close a work session on a repository that uses cadence — plan hyg
      is genuinely outside the plan (docs, chores);
    - a finished lot marked `visible` without a news entry → `cadence news new <id>`, written for the
      user, with a screenshot;
+   - a lot that `raf done` refuses, or that the check reports as finished, for lack of a review —
+     code review of a lot with commits, or one older than the lot's latest commit
+     (`raf review enable`), UX review of a visible lot (`raf ux enable`) → have the `code-reviewer` / `ux-reviewer` agent review it, then record its
+     verdict with `raf review <id> "…"` / `raf ux <id> "…"`; never write a verdict nobody gave;
    - rerun until the check part is clean.
 3. **Memory, filtered** (only if you keep a persistent memory): write down what the repository does
    NOT already say — a trap and its cause, a decision or correction from the human, a collaboration
@@ -23,6 +37,9 @@ description: Close a work session on a repository that uses cadence — plan hyg
 4. **Skills and agents, on threshold, PROPOSED**: a skill when the same chain of commands was done by
    hand at least twice today; an agent update when an agent got something wrong or its domain moved.
    List them with the benefit; the human decides. Never create them here.
+   When the report has a "Faits propres au projet" section (`session.close` in `cadence.yaml`), treat
+   what it flags as part of this hygiene; with a read-only plan, use the project's own tool wherever
+   these steps say `raf`.
 5. **Clean state**: everything committed and pushed, no delivery running. If the command still exits 1,
    say what remains and do NOT say the session is closed.
 6. **Three lines for next time**: `cadence session next "…" "…" "…"` — the next `session-start` shows them.

package/skills/session-start/SKILL.md

@@ -5,10 +5,21 @@ description: Start a work session on a repository that uses cadence — gather t
 
 # Session start — resume without reciting
 
-The repository already carries the state: the plan (`docs/plan/raf.yaml`), the history, the notes left at
+The repository already carries the state: the plan (`docs/plan/raf.yaml`, or the file named by `plan:` in `cadence.yaml`), the history, the notes left at
 the last close. The only thing missing is the human's priority for today. This skill gathers the facts,
 proposes, and stops.
 
+## Where to run
+
+Every `cadence` / `raf` command works on the git repository of the current directory. When the
+session runs from a parent folder that holds several projects (not itself a repository), run each
+command inside the project concerned: `cd <project> && cadence …`. The projects are the sub-folders
+that contain `docs/plan/raf.yaml`, or a `cadence.yaml` with a `plan:` key.
+
+With no project named, run `cadence session start` in **each** project that has a plan and report
+one or two lines per project (in progress, drift, notes left at the last close), then propose the
+three most useful items across projects and wait. With a project named, work in that one only.
+
 ## Steps
 
 1. Run `cadence session start` (after a weekend: `--since "3 days ago"`). If `cadence` is not on the
@@ -20,6 +31,9 @@ proposes, and stops.
    - **Drift**: each `✗` line from the check, with the one command that fixes it.
    - **Delivery in progress** or a stale lock: no new delivery until it is resolved.
    - **Notes from the last close**, if any.
+   - **Project facts** ("Faits propres au projet"), when the project plugs its own morning script in
+     (`session.start` in `cadence.yaml`): summarise what bears on today's choice — deadlines, the
+     project's own planning, documentation drift — and leave the rest.
 3. **The plan drives the work.** Propose exactly three items, each with its id and one sentence of
    justification, in the order the command gives them: finish what is in progress, then ready quick
    wins, then the next ready lots. An idea that is not in the plan is only proposed together with the
@@ -27,11 +41,21 @@ proposes, and stops.
 4. **Stop and wait** for the priority. Start nothing and commit nothing before the answer — the only
    exception is a `raf note <id> "…"` on a silent lot whose cause is already known.
 
+A plan kept by the project's own tool (`cadence.yaml` maps its fields) is **read-only** for `raf`:
+report from it as usual, but give the project's own command for every fix or start — `raf start`,
+`raf done` and `raf note` refuse.
+
 ## After the answer
 
 `raf start <id>` on the chosen lot, then the project's usual development workflow. Every commit cites
 the lot id (`feat(L3): …`) so that the history links itself to the plan.
 
+## A project with its own tooling
+
+When the plan is read-only (held by the project's own tool, `plan:` with a field mapping in
+`cadence.yaml`), every plan change — start, note, done — goes through that tool, not `raf`; the
+project's instructions say which command. Its expert agents and its own skills stay in use.
+
 ## Do not
 
 - Decide for the human: close a lot, drop one, create an agent or a skill.