wshobson/superself

Que fait superself ?

Superself est un CLI Apache-2.0 (npm install -g [email protected], Node 22.12+) qui contrôle en version l'état d'un projet — objectifs, décisions, unités de travail, rapports — sous forme de journal d'événements en annexe seulement dans un dépôt Git séparé du code. L'état est dérivé à la demande, donc rien n'y est maintenu à la main. Cette compétence dit à un agent comment lire et écrire cet état via le CLI self. Elle est maintenue par les auteurs de Superself : https://github.com/fxylabs/superself

Quand cette compétence s'applique

• Le fichier AGENTS.md ou CLAUDE.md du projet contient un bloc entre <!-- superself:begin et <!-- superself:end -->, ou self setup affiche l'espace de travail, le projet et le store auxquels ce répertoire se résout.
• Ignorer la compétence quand self --version échoue : le projet n'utilise pas Superself, et rien ci-dessous ne doit être inventé manuellement. Cette compétence est écrite pour [email protected] ; une version majeure ou mineure différente peut avoir déplacé un verbe ou un indicateur, alors vérifiez self <commande> --help avant de vous appuyer sur l'un d'eux.

Démarrage de session

1. Exécutez self context et traitez sa sortie comme la vérité courante : l'objectif, les décisions et conventions actives, le travail ouvert, les rapports récents. Elle est pliée à partir du journal, jamais écrite à la main.
2. Quelque chose manquant dans le contexte a été intentionnellement placé hors de l'ensemble rendu ; self search <requête> trouve les enregistrements vivants que le contexte a laissés de côté, et self work show <id> imprime le briefing complet et l'historique des rapports d'une unité.

Pendant le travail

• Un 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 briefing et enregistre que cette session a pris l'unité en charge ; si une autre session la détient, le CLI dit qui et depuis quand et ne refuse pas. Jugez et poursuivez.
• Après avoir commité, signalez la progression : self report <id> "<ce qui s'est passé>". Le commit HEAD courant est attaché comme preuve automatiquement ; --evidence <commit|note> attache autre chose, --file <chemin> attache un briefing plus long.
• Enregistrez une décision confirmée par l'utilisateur : self decide "<texte>" --why "<raison>". Utilisez --proposed lorsque l'utilisateur ne l'a pas confirmée. Une décision par événement.
• Bloqué ? self work block <id> --on décision|dépendance|externe --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.
• Vous avez trouvé un écart entre un objectif et l'état actuel ? Proposez le travail avec self work propose et son briefing ; l'utilisateur l'accepte ou le refuse.
• 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 vit uniquement dans la conversation est perdu quand la conversation se termine.

Fermeture

• self work done <id> ferme une unité uniquement lorsqu'un rapport porte un commit ou un artefact, ou que le done lui-même indique ce qui s'est vérifiablement passé : self work done <id> --report "<ce qui s'est vérifiablement passé>". Une simple affirmation est refusée, et les critères déclarés la bloquent jusqu'à ce que chacun soit couvert.
• Le texte d'un enregistrement est immuable une fois confirmé. Corrigez-le en reformulant : --supersedes <id> sur tout verbe d'ajout 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 : la revue de PR et l'IC contrôlent la fusion. Superself possède le contexte et le graphe de travail, pas la porte de fusion.
• Ne modifiez jamais à la main 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 en un projet enregistré, demandez une fois à l'utilisateur s'il faut 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 s'il faut l'enregistrer avec self project init. N'enregistrez ni ne connectez jamais un projet par vous-même.

Pour aller plus loin

self --help liste chaque verbe ; self <commande> --help affiche les indicateurs d'une commande sans toucher à l'état. Des guides thématiques sont fournis avec le CLI :

• self help agents — comment une session pilote ce CLI, du début à la fin
• self help context — ce que self context rend, et pourquoi quelque chose en est absent
• self help records — une entité derrière chaque type d'enregistrement, et comment un enregistrement est corrigé
• 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, buts, jalons, et ce qu'il faut pour en atteindre un
• self help workspace — le store, les projets qu'il contient, et le déplacer entre machines