Specs y planes
El trabajo de features se documenta primero. Toda feature no trivial arranca como spec endocs/superpowers/specs/ y se implementa a partir de
un plan derivado en docs/superpowers/plans/. Ambos usan el mismo formato
de nombre: YYYY-MM-DD-nombre.md.
Roadmap
roadmap.md, en la raíz del repo, mantiene el estado de cada requerimiento
funcional — RF-01 a RF-20 — como una lista de tareas: qué está hecho,
qué sigue pendiente y en qué fase entra.
Lint y formato
npm run lint corre Biome en modo check --write: lint, formato y
organización de imports en una sola pasada. No hay un comando de formato
separado — Biome hace las tres cosas a la vez.
La regla de docs
Toda spec nueva endocs/superpowers/specs/ incluye una sección
## Impacto en docs con una tabla de dos columnas, Página del handbook | Cambio. Declarar ninguna es una respuesta válida, pero exige justificar
por qué esa feature no toca ningún acuerdo documentado aquí. El plan de
implementación que se deriva de la spec hereda esa obligación: la
actualización del handbook aparece ahí como una tarea del plan, con su
propio checkbox — no como una nota al margen que alguien puede saltarse.
El handbook vive en
docs/handbook/ y se publica en el sitio Mintlify
público. La regla existe para que ese sitio no se quede desactualizado
respecto al código.Por qué existe esta regla
Al escribir este handbook nos topamos con una prueba directa de por qué hace falta. La sección Route handlers deCLAUDE.md describía el cursor
de paginación de usuarios como “compuesto y codificado en base64url”,
implementado en src/lib/admin-users-cursor.ts. Ese archivo no existe: se
eliminó en un refactor que simplificó el cursor a un id plano, igual que
en el resto de listados — pero la documentación nunca se actualizó para
reflejarlo.
Nadie mintió a propósito. El refactor simplemente no incluyó el paso de
“actualizar la doc que describe esto”, porque no había ningún paso formal
que lo exigiera. Es la misma deriva la que aparece si una spec cambia un
permiso, agrega un endpoint o mueve un umbral de cobertura y nadie se
acuerda de tocar el handbook.