Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "agent-cost-kit",
"version": "0.21.1",
"version": "0.22.0",
"description": "Setup de développement par agents économe en tokens pour Claude Code : quatre sous-agents routés par rôle (dev-story Sonnet, second-avis Haiku, reviewer Opus, lookup Haiku), un contrôle rapide de fin de story, un script de mesure du coût réel des agents depuis les transcriptions, un skill d'installation, et des bancs pour re-tester le kit quand de nouveaux modèles sortent.",
"author": {
"name": "Anaël Yahi"
Expand Down
1 change: 1 addition & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
*.sh text eol=lf
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
# Historique

- **0.22.0** (2026-11-11) : sortie de Fable 5.2 (`claude-fable-5-2`, 8 $ / 40 $ par Mtok, lecture du cache à 0,20 $). **Correctif de prix** : sans entrée dédiée, `tarifs.json` lui donnait le tarif du préfixe `claude-fable-5`, avec une lecture du cache à 1 $ (5 fois trop) ; entrées `claude-fable-5-2` et `claude-mythos-5-2` ajoutées, familles `fable` et `mythos` alignées, `tarifs.ts` régénéré, test ajouté au mod `couts-session`. **Aucun agent ne change**, d'après quatre bancs du 2026-11-10 (112 $, références dans `bancs/README.md`) : en contre-revue isolée, Fable 5.2 `medium` signale 20 défauts connus sur 24 contre 13 pour Opus 5.5, mais comme `reviewer` dans la chaîne le code sort avec les mêmes fiches (9 sur 15 cas) pour 1,97 $ contre 0,99 $ ; en développement, même qualité que Sonnet pour 4 fois le coût ; en orchestration, +49 % sans gain. La description de `reviewer` le dit. `installer_global.py` ne pose plus `modelSettings.claude-fable-5-1` (effort `high`) et signale cette règle si elle reste. **Bancs rejouables** : `bancs/corpus.json` (6 stories, 2 dépôts), `bancs/verite-terrain.json` (13 fiches de défauts, à valider), `bancs/banc_relecteur.sh` (même développement, un clone par relecteur candidat, vérificateur en lecture seule), `bancs/noter.py`, `bancs/reglages-banc.json` (`acceptEdits` et liste d'outils, sans `bypassPermissions`, que le mode auto refuse). **Nouveau skill `new-model`**, à invocation manuelle : sans argument, il compare les modèles publiés à `tarifs.json` et s'arrête là ; avec un identifiant, il relève prix et recommandations, liste les écarts avec le kit et les réglages, chiffre les bancs, les lance après accord, puis propose les réglages sans rien appliquer seul ;
- **0.21.1** (2026-11-06) : `avancement-run` suit les runs hors epics (PR #17) et compte les stories terminées sans fusion. Identifiants alphanumériques de story (`C1`, `O4a`, `E1b`, `S3`, motif `[A-Z]{1,3}\d+[a-z]?`) en plus de `N.M` et `N.Mb`, lus dans les cellules des vagues, les dépendances (seulement si ce sont des stories du run) et la colonne story du journal, jamais ailleurs (« v14 », « M1 » dans un résultat, heures et SHA ne comptent pas). Périmètre `| Dans le run | Stories C1 à C9, O1, O4a | … |` (plages développées, notes entre parenthèses ignorées) ; une story du périmètre absente des vagues va dans une vague « — ». Une story absente de `sprint-status.yaml` est suivie par le journal seul ; avec seulement `blocked` ou `attente humaine`, elle reste « à faire », drapeau bloquée. Son titre vient de la liste `- C1 : titre` sous la table des vagues. Ces stories forment la ligne « — · Hors epic » du tableau par epic. `décision` et `report` ne marquent plus une story « reprise ». Nouvelle étape de journal `clôture` (`- 2026-11-06 18:00 · 3.6 · clôture · terminée sans PR (raison) · abc1234`) : elle termine la story comme une `fusion`. Repli : une story `done` dans sprint-status sans `fusion` ni `clôture` compte terminée (compte, taux, estimation, météo), avec la puce « terminée sans fusion journalisée » et la piste « ajouter au journal une ligne `fusion` ou `clôture` ». Elle reste en cours si sa dernière ligne la montre en vol (`blocked`, PR ouverte, CI rouge, étape lancée). Avant, une story poussée sur main sans PR (0.0) ou close sans fusion (3.6) laissait son epic non terminée. La dernière étape fait foi : une `fusion` suivie d'un `dev · lancé` est une reprise. Spec : `docs/spec-0.21.1.md`.
- **0.21.0** (2026-11-06) : deux règles du modèle de run (`modeles/run-autonome.md`) issues de la rétrospective de l'Epic 2 de slm-weight-editing (actions A-7 et A-10). **A-10** : la levée d'un point d'arrêt (« retire mes points d'arrêt et continue ») avait été lue comme une délégation ; vingt questions de protocole tranchées en deux minutes, fusionnées sans relecture. Désormais l'orchestrateur ne tranche que les questions techniques ; les questions de protocole, de méthode ou de publication vont dans `decisions-a-confirmer.md`, validé par l'utilisateur avant la fusion de la story concernée, qui reste en `attente humaine` pendant que le run avance sur le reste. **A-7** : une release y avait été publiée sur une branche principale rouge, avant la fin de la CI du commit tagué ; pas de tag ni de release sans CI verte de la branche principale sur ce commit, vérifiée par `gh run watch --interval 60`. Aucun changement de code ni d'agent ;
- **0.20.1** (2026-11-06) : le gabarit du bilan des tokens passe à la charte générique v2.1 : jetons v2.1 par usage (variables `--surface`, `--texte`, `--primaire`… à la place de `--c-*`), thème sombre d'abord et clair selon le système (`prefers-color-scheme`) ou `[data-theme]`, bouton principal neutre et boutons secondaires en contour (l'état enfoncé prend le fond doux de la sélection, jamais un aplat bleu), focus de la charte, liens soulignés, filet or sous le titre, pictogramme de la charte, piles de polices Sora, Atkinson Hyperlegible et JetBrains Mono avec repli système (aucun CDN). Le fond à points disparaît ; les familles de modèles prennent les couleurs de série `--cat-*`, et les étapes sont regroupées en trois groupes (cadrage, développement, le reste) en `cat-1` à `cat-3` avec un motif chacun et les parts écrites sous la pile de chaque projet. À l'impression, la page prend les jetons clairs, sans barre de navigation, avec les marques des graphiques gardées. Les catalogues `en.json` et `de.json` suivent. Nouveau `tests/test_bilan_charte.py` (contrastes 4,5:1 et 3:1 dans les deux thèmes, aucun hex hors des jetons, pas d'aplat bleu de bouton). Limites : pas de favicon (une image ne lit pas les variables CSS) ; polices non embarquées (repli système si elles ne sont pas installées) ; les drapeaux du sélecteur de langue gardent leurs couleurs nationales ; les pages déjà publiées ne changent pas, un `--c-*` dans un gabarit personnalisé (`AGENT_COST_KIT_GABARIT_BILAN`) reste valable pour ce gabarit.
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ Mesurez votre point de départ avant de changer de méthode : `/agent-cost-kit:m
- [Mutation guidée](docs/mutation-guidee.md) (expérimental) : étape optionnelle après dev-story, script `scripts/mutation_story.py`, chiffres de la veille (T4, T10, T10b).
- [Vérification front](docs/verif-front.md) (expérimental) : sous-agent `verif-front` (Playwright MCP) copié par l'installation, chiffres de la veille (T12).
- [Aiguillage sans cadrage](docs/aiguillage-stories.md) (expérimental) : règle de l'orchestrateur pour les petites stories, chiffres de la veille (T13, T13 bis).
- [Re-tester le kit à la sortie d'un modèle](bancs/README.md) : corpus, bancs et références datées ; le skill `/agent-cost-kit:new-model` vérifie s'il existe un modèle à évaluer, ou déroule l'évaluation pour un identifiant donné.
- [Historique des versions](CHANGELOG.md).

**Contribuer** : la CI lance les tests sur Linux et Windows et valide le plugin (`claude plugin validate . --strict`) à chaque PR ; `master` est protégé, une PR ne fusionne que si la CI est verte.
Expand Down
2 changes: 1 addition & 1 deletion agents/reviewer.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: reviewer
description: Relit un commit ou un diff de story, corrige les constats Important (medium ou high) réels et consigne la revue. À utiliser par l'orchestrateur après dev-story et second-avis, une passe par story par défaut, relancée seulement après correction d'un constat Important, 3 passes au plus au total, en lui transmettant la liste du second avis. Sur Opus par défaut. Une revue Sonnet est possible (paramètre `model`) pour une story mécanique, mais sur 10 stories elle a manqué la plupart des défauts.
description: Relit un commit ou un diff de story, corrige les constats Important (medium ou high) réels et consigne la revue. À utiliser par l'orchestrateur après dev-story et second-avis, une passe par story par défaut, relancée seulement après correction d'un constat Important, 3 passes au plus au total, en lui transmettant la liste du second avis. Sur Opus par défaut. Une revue Sonnet est possible (paramètre `model`) pour une story mécanique, mais sur 10 stories elle a manqué la plupart des défauts. Une revue Fable 5.2 (paramètre `model` à `claude-fable-5-2`) coûte le double et, sur 6 revues appariées, laisse les mêmes défauts dans le code, donc à réserver à une story à risque.
model: opus
effort: medium
tools: Read, Edit, Write, Grep, Glob, Bash, PowerShell, LSP
Expand Down
22 changes: 21 additions & 1 deletion bancs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@ Les réglages du kit (Sonnet pour coder, Opus pour relire, Haiku pour le second
1. **Prix.** Relevez la page officielle (`platform.claude.com/docs/en/about-claude/pricing`) : entrée, écriture du cache à 5 min et à 1 h, lecture du cache, sortie, et seuils de contexte long. Mettez à jour `prix` dans `plugins/couts-session/donnees/tarifs.json` (une entrée par identifiant de modèle, avec repli par famille), puis `py plugins/couts-session/donnees/generer_tarifs.py` pour le mod. Un écart sur la lecture du cache fausse tout : c'est 40 % du coût, et Sonnet a déjà été compté au double par erreur.
2. **Noms des modèles.** `famille()` reconnaît les modèles par le nom de leur famille (`opus`, `sonnet`, `haiku`, `fable`). Ajoutez toute nouvelle famille dans `prix.familles` de `tarifs.json`, et chaque nouvelle génération dans `prix.modeles` (une génération n'a pas le tarif de la précédente).
3. **Réglages de Claude Code.** Vérifiez dans la doc que `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`, `subagentPromptCacheTtl`, `syncClaudeAiSkills` et les champs `model`, `effort`, `tools` et `disallowedTools` du frontmatter existent toujours, avec le même sens.
4. **Corpus.** Gardez 5 à 10 stories déjà livrées, sur au moins deux dépôts, avec leur base Git. On rejoue les bancs dessus, chaque story dans son propre worktree.
4. **Corpus.** `corpus.json` consigne les stories rejouables (dépôt, base, tête, spec, lignes de spec à garder) et `verite-terrain.json` les défauts connus de chacune, une fiche par défaut. Le corpus d'octobre 2026 n'avait pas été consigné : celui-ci date du 2026-11-10 (6 stories, 2 dépôts, 13 fiches). Ajoutez-y vos stories plutôt que d'en reconstituer un. Une fiche dont `validation` est `null` n'a pas été tranchée par un humain et ne compte pas dans un taux publié.
5. **Permissions.** Le classifieur du mode auto refuse de lancer des sessions en `bypassPermissions`. Les bancs tournent donc avec `reglages-banc.json` (`--settings`) : `acceptEdits`, liste d'outils explicite (édition, `git` local, `uv run`, lecture en shell), ni réseau ni push. Rejouez le développement dans un clone jetable sans remote, pas dans un worktree du dépôt réel : avec une liste trop courte, les agents se voient refuser `git add` et `git commit` (8 à 15 refus par chaîne le 2026-11-10).

## Les bancs, par ordre d'utilité

Expand Down Expand Up @@ -40,6 +41,25 @@ Worktree : <chemin>. Diff à relire : git diff <base>..HEAD." \
- Lancez aussi une fusion de toutes les branches dans un worktree jetable, puis la suite complète, **avec la même installation que la CI**. Un `uv sync` différent de la CI a déjà masqué un vrai défaut.
- Référence d'octobre 2026, sur 10 stories : Opus 11 défauts certains (0,63 $ par story), Sonnet 1 (0,27 $), Haiku 2 plus des constats propres (0,03 $). Aucun relecteur n'a tout trouvé.

- Référence du 2026-11-10 (Claude Code 2.1.322, 5 stories du corpus, 3 essais par cellule, 8 défauts medium ou plus signalés au moins deux fois) : Opus 5.5 `medium` 13 détections sur 24 (0,65 $ par revue), Fable 5.2 `low` 18 sur 24 (1,17 $), Fable 5.2 `medium` 20 sur 24 (1,36 $). Regroupement des signalements fait à la main, fiches non encore validées.

### 1 bis. Le relecteur dans la chaîne

Une contre-revue isolée ne prédit pas le relecteur du kit : le 2026-11-10, Opus signalait un défaut 3 fois sur 3 en contre-revue et ne le corrigeait que 2 fois sur 6 dans la chaîne. `banc_relecteur.sh` rejoue donc le développement (Sonnet) et le second avis (Haiku) une fois par essai, copie le clone pour chaque relecteur candidat, puis fait dire à un vérificateur quelles fiches restent présentes :

```bash
bash bancs/banc_relecteur.sh <dossier hors dépôt> "usine-6-11 frugal-9-3" "opus:medium claude-fable-5-2:medium" 3
uv run --no-project python bancs/noter.py <dossier hors dépôt>/resultats
```

Le script tient lieu d'orchestrateur : son coût sort de la comparaison. Écart avec un run réel : ni rebase, ni push, ni CI de branche.

- Le vérificateur (Sonnet) ne juge que les fiches connues. Lisez aussi les sections `## Revue` : deux relecteurs peuvent laisser les mêmes fiches et corriger des défauts différents.
- Une fiche déjà absente du développement relu ne mesure rien : comptez les cas applicables, pas les fiches.
- Référence du 2026-11-10 (Claude Code 2.1.322, 2 stories, 3 essais, 12 revues, 26,11 $) : `reviewer` Opus 5.5 `medium` 0,99 $ par revue, Fable 5.2 `medium` 1,97 $ ; 9 fiches présentes sur 15 cas après revue pour chacun, mêmes verdicts fiche par fiche. Fable mentionne F01 à 3 essais sur 3 (Opus 0) mais la classe low et la reporte. Développement 1,01 $, second avis 0,03 $, vérification 0,17 $. Fiches non validées. Le `reviewer` reste sur Opus.
- Autres mesures du même jour, hors de ce script : développement d'une story par Fable 5.2 `low` de 1,72 à 2,07 $ contre 0,33 à 0,60 $ pour Sonnet `medium`, même nombre de défauts en contre-revue ; orchestration de la chaîne par Fable 5.2 `medium` à 2,63 $ en moyenne contre 1,76 $ pour Opus, sans écart de qualité.
- Le skill `/agent-cost-kit:new-model` rejoue cette démarche pour un nouveau modèle.

### 2. A contre kit : le setup complet

Une même story, 3 essais par setup, chacun dans un worktree partant de la même base :
Expand Down
78 changes: 78 additions & 0 deletions bancs/banc_relecteur.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
#!/usr/bin/env bash
# Banc du relecteur dans la chaîne : même développement, deux relecteurs.
# Par essai : un clone jetable sans remote reçoit dev-story (Sonnet) puis second-avis (Haiku) ; ce clone est
# ensuite copié une fois par relecteur candidat, qui reçoit le même diff et la même liste du second avis.
# Un vérificateur en lecture seule dit enfin, par clone, quelles fiches de la vérité terrain restent présentes.
# L'orchestrateur est ce script : son coût et son aléa sortent de la comparaison.
#
# Usage : banc_relecteur.sh <dossier de sortie> "<story> <story>..." "<modèle:effort> <modèle:effort>..." [essais]
# Exemple : banc_relecteur.sh ../_bancs/2026-11-10 "usine-6-11 frugal-9-3" "opus:medium claude-fable-5-2:medium" 3
# Permissions : bancs/reglages-banc.json (acceptEdits, liste d'outils, ni réseau ni push). Relançable : un
# résultat déjà écrit n'est pas refait.
set -u
KIT=$(cd "$(dirname "$0")/.." && pwd)
RACINE=$(dirname "$KIT")
SORTIE=$(mkdir -p "$1" && cd "$1" && pwd)
STORIES=$2 RELECTEURS=$3 ESSAIS=${4:-3}
REGLAGES=$KIT/bancs/reglages-banc.json
OUT=$SORTIE/resultats
mkdir -p "$OUT"
corps() { awk 'f>=2{print} /^---$/{f++}' "$KIT/agents/$1.md" > "$OUT/consigne-$1.md"; }
corps dev-story; corps second-avis; corps reviewer
champ() { uv run --no-project python -c "import json,sys; s=[x for x in json.load(open(sys.argv[1],encoding='utf-8'))['stories'] if x['id']==sys.argv[2]][0]; print(s[sys.argv[3]] if sys.argv[3]!='fiches' else ' '.join(s['fiches']))" "$KIT/bancs/corpus.json" "$1" "$2"; }
journal() { echo "$(date '+%F %T') $*" >> "$OUT/journal.txt"; }
session() { # session <fichier json> <modèle> <effort> <consigne ou -> <budget> <prompt>
local f=$1 modele=$2 effort=$3 consigne=$4 budget=$5 prompt=$6
[ -s "$f" ] && return 0
local opt=(); [ "$consigne" != "-" ] && opt=(--append-system-prompt-file "$OUT/consigne-$consigne.md")
# Lecture seule réelle pour le second avis et le vérificateur.
case "$consigne" in -|second-avis) opt+=(--disallowedTools "Edit" "Write" "NotebookEdit" "Bash(git add:*)" "Bash(git commit:*)");; esac
claude -p "$prompt" --model "$modele" --effort "$effort" --settings "$REGLAGES" "${opt[@]}" \
--add-dir "$KIT/bancs" --max-budget-usd "$budget" --output-format json > "$f" 2> "$f.err"
}
texte() { uv run --no-project python -c "import json,sys; print(json.load(open(sys.argv[1],encoding='utf-8')).get('result') or '')" "$1"; }

une_story() {
local story=$1
local depot base tete spec lignes fiches
depot=$(champ "$story" depot); base=$(champ "$story" base); tete=$(champ "$story" tete)
spec=$(champ "$story" spec); lignes=$(champ "$story" spec_lignes); fiches=$(champ "$story" fiches)
for essai in $(seq 1 "$ESSAIS"); do
local id="$story-e$essai" dev="$SORTIE/clones/$story-e$essai-dev"
if [ ! -d "$dev" ]; then
git clone -q --no-hardlinks "$RACINE/$depot" "$dev" && cd "$dev" || continue
git remote remove origin; git checkout -q -b "banc/$id" "$base"
mkdir -p "$(dirname "$spec")"
git -C "$RACINE/$depot" show "$tete:$spec" | head -n "$lignes" | sed "s/^status: .*/status: 'ready-for-dev'/" > "$spec"
git add "$spec" && git commit -q -m "Banc : spec de la story (sans rapport ni revue)"
uv sync -q > "$OUT/$id-uvsync.log" 2>&1
fi
cd "$dev" || continue
session "$OUT/dev-$id.json" sonnet medium dev-story 8 "Implémente la story décrite dans $spec. Dépôt de travail : $dev (branche banc/$id, déjà créée ; il tient lieu de worktree). Lance les tests ciblés, puis commite sur cette branche. Ce dépôt n'a pas de remote : rien à pousser, rien à fusionner."
journal "dev $id propre=$(git status --porcelain | wc -l) diff=[$(git diff --shortstat "$base" HEAD)]"
session "$OUT/avis-$id.json" haiku medium second-avis 2 "Relis en lecture seule le diff de la story $spec dans $dev : git diff $base..HEAD. Rends ta liste de constats."
journal "second-avis $id"
local avis; avis=$(texte "$OUT/avis-$id.json")
local sha_dev; sha_dev=$(git rev-parse HEAD)
for cfg in $RELECTEURS; do
local modele=${cfg%%:*} effort=${cfg##*:}
local rid="$id-$modele-$effort" rev="$SORTIE/clones/$story-e$essai-$modele-$effort"
if [ ! -d "$rev" ]; then
git clone -q --no-hardlinks "$dev" "$rev" && cd "$rev" || continue
git remote remove origin; git checkout -q -B "banc/$id" "$sha_dev"
uv sync -q > "$OUT/$rid-uvsync.log" 2>&1
fi
cd "$rev" || continue
session "$OUT/revue-$rid.json" "$modele" "$effort" reviewer 8 "Relis la story $spec dans $rev : git diff $base..HEAD. Corrige les constats Important réels, commite sur la branche banc/$id et consigne la revue dans la spec. Cadre du banc : ce dépôt n'a pas de remote, donc ni rebase, ni push, ni fusion ; CI de branche : absente. Une seule passe.
Liste du second avis (à vérifier, pas à croire) :
$avis"
journal "revue $rid propre=$(git status --porcelain | wc -l) commits=$(git rev-list --count "$sha_dev"..HEAD) diff=[$(git diff --shortstat "$sha_dev" HEAD)]"
session "$OUT/verif-$rid.json" sonnet medium - 2 "Vérification en lecture seule : ne modifie aucun fichier, ne commite rien. Lis $KIT/bancs/verite-terrain.json et ne garde que les fiches : $fiches. Pour chacune, dis si le défaut décrit est PRESENT, ABSENT ou SANS_OBJET dans l'état actuel de ce dépôt ($rev, diff git diff $base..HEAD), en lisant le code et, si utile, par un test ciblé (uv run pytest ou uv run python -c). Réponds par une ligne par fiche, sans rien d'autre : <id> | PRESENT ou ABSENT ou SANS_OBJET | fichier:ligne | preuve en une phrase."
journal "verif $rid"
done
done
}
export -f une_story champ journal session texte
export KIT RACINE SORTIE RELECTEURS ESSAIS REGLAGES OUT
printf '%s\n' $STORIES | xargs -P 2 -I{} bash -c 'une_story {}'
journal FIN
Loading
Loading