Superself

Superself est un CLI Apache-2.0 (npm install -g superself@0.6.1, Node 22.12+) qui contrôle les versions de l'état d'un projet — objectifs, décisions, unités de travail, rapports — comme un journal d'événements en append-only dans un dépôt git séparé du code. L'état est dérivé à la demande, donc rien n'y est maintenu manuellement. Cette skill indique à un agent comment lire et écrire cet état via la CLI self. Elle est maintenue par les auteurs de Superself : https://github.com/fxylabs/superself

Quand cette skill s'applique

Le fichier AGENTS.md ou CLAUDE.md du projet contient un bloc entre , ou self setup affiche l'espace de travail, le projet et le store auquel ce répertoire se résout.
Ignorer la skill quand self --version échoue : le projet n'utilise pas Superself, et rien ci-dessous ne doit être inventé manuellement. Cette skill est écrite pour superself@0.6.1 ; une version majeure ou mineure différente peut avoir déplacé un verbe ou un flag, donc vérifiez self <command> --help avant de vous fier à l'un d'eux.

Démarrage de session

Exécutez self context et traitez sa sortie comme la vérité actuelle : l'objectif, les décisions actives et conventions, le travail ouvert, les rapports récents. Elle est repliée depuis le journal, jamais écrite manuellement.
Quelque chose manquant du contexte a été placé en dehors de l'ensemble rendu intentionnellement ; self search <query> trouve les enregistrements vivants que le contexte a omis, et self work show <id> affiche le bref complet d'une unité et l'historique des rapports.

Pendant le travail

Le travail substantiel s'attache à une unité de travail. Créez-en une avec self work add "<résultat requis>" — le résultat est ce qui doit devenir vrai, pas la tâche — puis self work start <id>. start lit le bref et enregistre que cette session a repris l'unité ; si une autre session la tient, la CLI indique qui et depuis quand et ne refuse pas. Jugez et procédez.
Après un commit, signalez la progression : self report <id> "<ce qui s'est passé>". Le commit HEAD courant est joint automatiquement comme preuve ; --evidence <commit|note> joint quelque chose d'autre, --file <path> joint un bref plus long.
Enregistrez une décision confirmée par l'utilisateur : self decide "<texte>" --why "<raison>". Utilisez --proposed quand l'utilisateur ne l'a pas confirmée. Une décision par événement.
Bloqué ? self work block <id> --on decision|dependency|external --why "...". Remplacé ou déplacé ? self work retire <id> --why "..." [--successor <id>]. Ne marquez jamais une telle unité comme terminée, et ne la laissez jamais faussement bloquée.
Trouvé un écart entre un objectif et l'état courant ? Proposez le travail avec self work propose et son bref ; l'utilisateur l'accepte ou le décline.
L'utilisateur a approuvé une prochaine étape ou une continuation ? Enregistrez-la immédiatement avec self work add et le contexte derrière elle. Un plan qui n'existe que dans la conversation est perdu quand la conversation se termine.

Clôture

self work done <id> ferme une unité seulement quand un rapport comporte un commit ou un artefact, ou quand le done lui-même énonce ce qui s'est verifiablement produit : self work done <id> --report "<ce qui s'est verifiablement produit>". Une affirmation nue est refusée, et les critères déclarés la barrent jusqu'à ce que chacun soit couvert.
Le texte d'un enregistrement est immuable une fois confirmé. Corrigez-le en le réaffirmant : --supersedes <id> sur n'importe quel verbe add enregistre la nouvelle formulation et conserve la lignée. retract retire un enregistrement sans rien le remplacer.

Règles qui maintiennent l'état fiable

Les enregistrements — événements, décisions, rapports, conventions — sont écrits en anglais pour que quiconque les ouvre ensuite puisse les lire ; répondez à la personne dans sa propre langue.
Une branche atteint main via une pull request : l'examen et le CI contrôlent la fusion. Superself contrôle le contexte et le graphe de travail, pas la porte de fusion.
Ne modifiez jamais manuellement les fichiers d'état générés ou quoi que ce soit sous .superself/.
Dans un projet sans bloc superself, exécutez d'abord self setup. S'il résout le répertoire à un projet enregistré, demandez une fois à l'utilisateur si exécuter self connect, qui écrit le bloc géré dans AGENTS.md ou CLAUDE.md. S'il ne résout aucun projet, demandez une fois si le registrer avec self project init. N'enregistrez ni ne connectez jamais un projet de vous-même.

Approfondir

self --help liste chaque verbe ; self <command> --help affiche les flags d'une commande sans toucher l'état. Les guides thématiques sont fournis avec la CLI :

self help agents — comment une session pilote cette CLI, du début à la fin
self help context — ce que self context affiche, et pourquoi quelque chose en est absent
self help records — une entité derrière chaque type d'enregistrement, et comment corriger un enregistrement
self help placement — portée, priorité et exposition — comment un enregistrement gagne sa place dans le contexte
self help work — le graphe de travail : résultats, preuves, critères, et propositions
self help goals — objectifs à long terme, objectifs, jalons, et ce que leur atteinte exige
self help workspace — le store, les projets qu'il contient, et le déplacer entre machines