wshobson/superself

¿Qué hace superself?

Superself es una CLI Apache-2.0 (npm install -g [email protected], Node 22.12+) que versiona el estado de un proyecto (objetivos, decisiones, unidades de trabajo, informes) como un registro de eventos de solo añadidura en un repositorio git separado del código. El estado se deriva bajo demanda, por lo que nada en él se mantiene manualmente. Esta habilidad le indica a un agente cómo leer y escribir ese estado a través del CLI self. Es mantenido por los autores de Superself: https://github.com/fxylabs/superself

Cuándo aplica esta habilidad

• El archivo AGENTS.md o CLAUDE.md del proyecto contiene un bloque entre <!-- superself:begin y <!-- superself:end -->, o self setup imprime el espacio de trabajo, el proyecto y el almacén al que este directorio resuelve.
• Omite la habilidad cuando self --version falla: el proyecto no usa Superself, y nada de lo siguiente debe ser inventado manualmente. Esta habilidad está escrita para [email protected]; una versión mayor o menor diferente puede haber movido un verbo o una bandera, así que verifica self <comando> --help antes de confiar en uno.

Inicio de sesión

1. Ejecuta self context y trata su salida como la verdad actual: el objetivo, las decisiones y convenciones activas, el trabajo abierto, los informes recientes. Se pliega a partir del registro, nunca se escribe a mano.
2. Algo que falta en el contexto fue colocado fuera del conjunto renderizado a propósito; self search <consulta> encuentra registros vivos que el contexto omitió, y self work show <id> imprime la historia completa de una unidad y sus informes.

Mientras se trabaja

• El trabajo sustancial se adjunta a una unidad de trabajo. Crea una con self work add "<resultado requerido>" — el resultado es lo que debe hacerse realidad, no la tarea — luego self work start <id>. start lee la descripción y registra que esta sesión tomó la unidad; si otra sesión la tiene, el CLI dice quién y desde cuándo y no la rechaza. Juzga y procede.
• Después de hacer commit, reporta el progreso: self report <id> "<lo que sucedió>". El commit HEAD actual se adjunta como evidencia automáticamente; --evidence <commit|nota> adjunta otra cosa, --file <ruta> adjunta una descripción más larga.
• Registra una decisión que el usuario confirmó: self decide "<texto>" --why "<razón>". Usa --proposed cuando el usuario no la haya confirmado. Una decisión por evento.
• ¿Bloqueado? self work block <id> --on decision|dependency|external --why "...". ¿Superado o movido? self work retire <id> --why "..." [--successor <id>]. Nunca marques dicha unidad como hecha, y nunca la dejes falsamente bloqueada.
• ¿Encontraste una brecha entre un objetivo y el estado actual? Propón el trabajo con self work propose y su descripción; el usuario lo acepta o rechaza.
• ¿El usuario aprobó un siguiente paso o una continuación? Regístralo de inmediato con self work add y el contexto detrás de él. Un plan que vive solo en la conversación se pierde cuando la conversación termina.

Cierre

• self work done <id> cierra una unidad solo cuando un informe lleva un commit o un artefacto, o el propio done declara lo que sucedió verificablemente: self work done <id> --report "<lo que sucedió verificablemente>". Una afirmación simple es rechazada, y los criterios declarados la bloquean hasta que cada uno esté cubierto.
• El texto de un registro es inmutable una vez confirmado. Corrígelo reformulando: --supersedes <id> en cualquier verbo de añadidura registra la nueva redacción y mantiene el linaje. retract retira un registro sin reemplazarlo.

Reglas que mantienen el estado confiable

• Los registros (eventos, decisiones, informes, convenciones) se escriben en inglés para que quien los abra después pueda leerlos; responde a la persona en su propio idioma.
• Una rama llega a main a través de un pull request: la revisión de PR y CI controlan la fusión. Superself posee el contexto y el grafo de trabajo, no la puerta de fusión.
• Nunca edites manualmente archivos de estado generados ni nada bajo .superself/.
• En un proyecto sin un bloque superself, ejecuta self setup primero. Si resuelve el directorio a un proyecto registrado, pregunta al usuario una vez si debe ejecutar self connect, que escribe el bloque gestionado en AGENTS.md o CLAUDE.md. Si no resuelve ningún proyecto, pregunta una vez si registrarlo con self project init. Nunca registres ni conectes un proyecto por tu cuenta.

Profundizando

self --help lista cada verbo; self <comando> --help imprime las banderas de un comando sin tocar el estado. Las guías de temas vienen con el CLI:

• self help agents — cómo una sesión maneja este CLI, de principio a fin
• self help context — qué renderiza self context, y por qué algo falta en él
• self help records — una entidad detrás de cada tipo de registro, y cómo se corrige un registro
• self help placement — alcance, prioridad y exposición — cómo un registro gana su lugar en el contexto
• self help work — el grafo de trabajo: resultados, evidencia, criterios y propuestas
• self help goals — objetivos a largo plazo, metas, hitos y lo que se necesita para alcanzar uno
• self help workspace — el almacén, los proyectos en él y cómo moverlo entre máquinas