@sylad/cadence 0.8.0 → 0.10.0

package/skills/lead/SKILL.md

@@ -34,26 +34,46 @@ progress, then drift that blocks a delivery, then ready quick wins. **Stop and w
 
 ## 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.
+The default way to delegate is **`cadence orchestrate`** (section 2b): a program, not a conversation, that runs
+one fresh short session per step. When the lead delegates by hand, the brief is the template
+`templates/orchestrate/implement.md` of the cadence package — the single source, tested; `cadence
+orchestrate --dry-run <project>:<lot>` writes it rendered for the lot. The lead runs
+`cd <project> && raf start <lot>`, fills `{{chemin}}`, `{{lot}}`, `{{titre}}` and `{{objectif}}` (what done
+looks like, from the human's words), and keeps the rest verbatim.
 
 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.
 
+### 2b. A wave through `cadence orchestrate`
+
+Once the human has chosen the lots, the lead runs, **in the background** (it is notified at the end; no
+silent wait, no polling loop — `cadence orchestrate --status` shows where the wave is):
+
+```sh
+cadence orchestrate <project>:<lot> <project>:<lot>@haiku … [--budget 2M]
+```
+
+`cadence orchestrate --dry-run …` first when a precondition is in doubt. The program, not the lead, runs
+for each lot a fresh short session per step — implementation (Sonnet), UX review if the lot is `visible`
+and the project declares how to see its app (`orchestrate.ux` in `cadence.yaml`), code review last
+(Opus, the `code-reviewer` agent), a correction in a new session if the review is not compliant (two
+passes at most) — and records `raf review` itself when the code review is compliant. The state is in
+`.cadence/runs/<wave>/`, not in this conversation. `@haiku` only when the human writes it, for a
+mechanical lot. Exit code: 0 all ready · 1 some lots handed back · 2 refused before acting · 3 wave
+suspended (budget or usage limit; `--resume --budget …` continues).
+
+What the orchestrator does **not** do, and stays with the lead: choose the lots (with the human), bring the
+questions back (`--resume --answer <project>:<lot> "…"`), look at the UX reviewer's captures and record
+`raf ux` (the orchestrator reports its verdict, it never records it), re-verify (section 3, point 2),
+`raf done`, push and deliver. Minor findings and proposed sub-tasks come back in the table: adding them to
+the plan is the lead's decision. If an orchestrated wave is running in a repository, do not commit there
+and do not deliver it (`cadence deliver` refuses).
+
 ## 3. Check
 
+0. After an orchestrated wave the review is already done, by a fresh session: read the table, then go to
+   point 2. For a lot delegated by hand:
 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,

package/skills/session-close/SKILL.md

@@ -34,18 +34,39 @@ With no project named, run `cadence session close` in each project touched durin
      (`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
+3. **Stale working files** (report section "Nettoyage proposé", from `session.clean` in `cadence.yaml`):
+   list them to the human — shared tmp folder, screenshots no one refers to, throwaway scripts,
+   folders left by tests — and delete them only after the human agrees, with explicit paths (never a
+   wildcard `rm`, never a file `git` tracks). The agreement can be old by then: right before
+   deleting, re-run `cadence session close` (or the scan) and delete only the entries that are
+   still proposed, never one the human named from memory. Delete a proposed symbolic link as a
+   link (`rm path`, no trailing `/`, never `rm -r` through it). Before proposing a screenshot, check nothing still
+   refers to it (plan, news, docs). Anything kept: leave it, it will be listed again next close. No
+   section: nothing to do; a project with no `session.clean` can propose adding it.
+   An entry is proposed only if it could be measured entirely. Age: a folder's age is that of the
+   most recent entry it contains, an entry's age counting from the later of its modification and status-change times. The report never proposes: a git repository, a folder that
+   contains one at any depth, and anything under a `.git` folder; a git directory without a `.git`
+   entry (bare repository, mirror, `--separate-git-dir`, worktree admin folder — recognised by
+   `HEAD` with `objects` and `refs`, or with `commondir`), anything inside it or a folder that
+   contains one; anything `git` tracks, in any repository that has a `.git` entry above it (one limit: a bare repository driven with an external work tree, `git --git-dir=~/.dotfiles --work-tree=~`, leaves no `.git` beside its files — their tracked files can be proposed, so check a proposed entry is not one); a name starting with `.`
+   unless the pattern itself starts that name with `.`; anything behind a symbolic link a `*`
+   matched (the link itself may be proposed: remove the link, never `rm -r` through it — a segment
+   written in full before the first `*` does follow its link); the repository itself or a folder that contains it;
+   anything that could not be read entirely — those are listed apart as "illisible(s)": tell the
+   human, never delete those, and never widen the list by hand to entries the report did not
+   propose.
+4. **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
    rule. Test: "do `git log` or the docs already say it?" → then no memory.
-4. **Skills and agents, on threshold, PROPOSED**: a skill when the same chain of commands was done by
+5. **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,
+6. **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.
+7. **Three lines for next time**: `cadence session next "…" "…" "…"` — the next `session-start` shows them.
    The lines replace the previous notes. Without a line the command refuses and keeps them; erase
    them on purpose with `cadence session next --clear`, only when nothing is left to say.
 

package/templates/orchestrate/fix-minors.md

@@ -0,0 +1,22 @@
+Work in `{{chemin}}` on lot `{{lot}}` — "{{titre}}" — of its plan.
+A fresh review found only minor findings: the lot is compliant, and this is the one pass that treats them.
+Commits of the lot so far:
+{{commits}}
+
+Minor findings:
+{{constats}}
+
+Fix each minor finding that is right, and nothing else. Rules: test first; commit each fix as soon as
+its tests pass, with explicit paths (never `git add -A` or `commit -a`), and a message that cites the
+lot (`fix({{lot}}): …`); run the project's full test suite and build before reporting; do not push,
+deliver, run `raf done`, `raf ux` or `raf review`. Read the project's CLAUDE.md first.
+Do not stop to ask. A finding that is wrong, or not worth its change, is not fixed: list it under
+"choix" in your report with the reason — the reviewer re-reads it and the lead sees it. Leave
+"questions" empty. Making no commit at all is a valid outcome when every finding is rejected.
+Minor choices to settle yourself, writing the alternative you did not take:
+a spacing, colour or label value when a measurement or a rule justifies it; the URL of a link (the most general official page if a precise one is not certain);
+a News entry: only if a finding asks for it; a written rule of the project's CLAUDE.md (apply it); who launches the review or UX pass (never the session: the program and the lead do).
+"not my job to touch the plan" is not a question: say it in the report.
+You are one short session of an orchestrated wave: do not launch subagents (the Agent tool is disabled).
+Give your final report as the structured output (commits, tests, build, what you could not verify, choices).
+{{reponse}}

package/templates/orchestrate/fix.md

@@ -0,0 +1,21 @@
+Work in `{{chemin}}` on lot `{{lot}}` — "{{titre}}" — of its plan. A fresh review of the commits
+of this lot found the defects below; fix them, and nothing else.
+Commits of the lot so far:
+{{commits}}
+
+Findings to fix:
+{{constats}}
+
+Rules: test first; commit each fix as soon as its tests pass, with explicit paths (never
+`git add -A` or `commit -a`), and a message that cites the lot (`fix({{lot}}): …`); run the project's
+full test suite and build before reporting; do not push, deliver, run `raf done`, `raf ux` or
+`raf review`. Read the project's CLAUDE.md first.
+If a finding is wrong, say so under "choix" with the reason. Ask (under "questions") only when a fix needs a decision that passes the rule below.
+A question is legitimate only if it names what it would change: the scope of the lot, the architecture, or a costly rollback (data, production, public API);
+otherwise it is a choice: decide, write the alternative you did not take, go on. Minor choices to settle yourself:
+a spacing, colour or label value when a measurement or a rule justifies it; the URL of a link (the most general official page if a precise one is not certain);
+a News entry: only if a finding asks for it; a written rule of the project's CLAUDE.md (apply it); who launches the review or UX pass (never the session: the program and the lead do).
+"not my job to touch the plan" is not a question: say it in the report.
+You are one short session of an orchestrated wave: do not launch subagents (the Agent tool is disabled).
+Give your final report as the structured output (commits, tests, build, what you could not verify, choices, questions).
+{{reponse}}

package/templates/orchestrate/implement.md

@@ -0,0 +1,25 @@
+Work in `{{chemin}}` on lot `{{lot}}` — "{{titre}}" — 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: {{objectif}}
+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({{lot}}): …`); run the project's
+full test suite and build before reporting; do not push, deliver, run `raf done`, `raf ux` or
+`raf review`.
+Decide minor interpretation questions yourself (the wording of a message, a name, a default, the
+reading of an ambiguous line of the lot) and list each one under "choix" in your report, with the
+alternative you did not take — the reviewer re-reads them. Stop and ask (under "questions") only on a real blocker.
+A question is legitimate only if it names what it would change: the scope of the lot, the architecture, or a costly rollback (data, production, public API), AND the plan, its notes and the project's CLAUDE.md do not settle it;
+otherwise it is a choice: decide, write the alternative you did not take, go on. Minor choices to settle yourself:
+a spacing, colour or label value when a measurement or a rule justifies it; the URL of a link (the most general official page if a precise one is not certain);
+a News entry for a visible lot (yes, always); a written rule of the project's CLAUDE.md (apply it); who launches the review or UX pass (never the session: the program and the lead do).
+"not my job to touch the plan" is not a question: say it in the report.
+If the lot's commits already cover its open sub-tasks, do not ask whether to continue: make no commit and say so
+in your report (the review that follows re-reads those commits). If they do not cover them all, implement the rest.
+Report: commits (sha + subject), tests and build results with their numbers, what you could not
+verify, choices made, open questions.
+
+You are one short session of an orchestrated wave: do not launch subagents (the Agent tool is disabled).
+Give your final report as the structured output, not as free text. If the plan is kept by the project's own tool
+(read-only for `raf`), use that tool's commands named in the project's CLAUDE.md, never `raf start|done|note`.
+{{commits}}
+{{reponse}}

package/templates/orchestrate/review-recheck.md

@@ -0,0 +1,11 @@
+Do a short re-review of lot `{{lot}}` — "{{titre}}" — of the repository `{{chemin}}`, following your
+agent instructions. A full review found the lot compliant with minor findings, and one pass has since
+treated them. Check that the minor findings fixed are fixed, that the fixes broke nothing, and that the
+rest of the lot is still sound: read the diff yourself from the commits that cite the lot
+(`raf commits {{lot}}`, or `git log`), run the checks, report real defects only. A new minor finding
+is reported, not a reason to ask for another pass. This is a code review only.
+{{choix}}
+You are read-only: do not modify, commit, push or run `raf review|ux|done`. Do not launch subagents.
+Give your report as the structured output: counts of blocking / major / minor findings, each finding
+(severity, file, line, text), proposed sub-tasks, what you could not verify, and the one-line verdict
+for `raf review {{lot}}`.

package/templates/orchestrate/review-small.md

@@ -0,0 +1,11 @@
+Review lot `{{lot}}` — "{{titre}}" — of the repository `{{chemin}}`, following your agent instructions.
+This lot is small: one single pass covers the code review AND the usability review.
+You are given the repository path and the lot id only: read the diff yourself from the commits that
+cite the lot (`raf commits {{lot}}`, or `git log`), run the checks, report real defects only.
+{{ux}}
+{{choix}}
+You are read-only: do not modify, commit, push or run `raf review|ux|done`. Do not launch subagents.
+Give your report as the structured output: counts of blocking / major / minor findings (usability
+findings included, each tied to a named rule — Nielsen heuristic or WCAG 2.2 AA criterion — or a
+measurement), each finding (severity, file, line, text), proposed sub-tasks, what you could not
+verify, and the one-line verdict for `raf review {{lot}}`.

package/templates/orchestrate/review.md

@@ -0,0 +1,8 @@
+Review lot `{{lot}}` — "{{titre}}" — of the repository `{{chemin}}`, following your agent instructions.
+You are given the repository path and the lot id only: read the diff yourself from the commits that
+cite the lot (`raf commits {{lot}}`, or `git log`), run the checks, report real defects only.
+{{choix}}
+You are read-only: do not modify, commit, push or run `raf review|ux|done`. Do not launch subagents.
+Give your report as the structured output: counts of blocking / major / minor findings, each finding
+(severity, file, line, text), proposed sub-tasks, what you could not verify, and the one-line verdict
+for `raf review {{lot}}`.

package/templates/orchestrate/ux.md

@@ -0,0 +1,10 @@
+Review the usability and accessibility of lot `{{lot}}` — "{{titre}}" — of the repository `{{chemin}}`,
+following your agent instructions. Read the diff yourself from the commits that cite the lot
+(`raf commits {{lot}}`, or `git log`).
+{{ux}}
+You are read-only: do not modify, commit, push or run `raf review|ux|done`. Do not launch subagents.
+Ground every finding in a named rule (Nielsen heuristic, WCAG 2.2 AA criterion) or a measurement;
+describe a mockup before proposing any redesign, never code it.
+Give your report as the structured output: counts of blocking / major / minor findings, each finding
+(severity, file, line, text), proposed sub-tasks, what you could not verify, and the one-line verdict
+for `raf ux {{lot}}`.