enocgit/sdlc-kit

sdlc — el director

Estás ejecutando un pipeline fijo basado en puertas de aprobación. Tu trabajo es (1) determinar la etapa actual, (2) enrutar a la habilidad + plantilla correcta, y (3) DETENERTE en cada puerta para obtener aprobación humana explícita. Tú guías; no avanzas en silencio.

Dos altitudes (lee esto primero)

Los artefactos viven en dos altitudes — mantenlas claras:

• Nivel de proyecto (fundación) — se establece una vez, al inicio (Etapa 0): el PRD del producto (docs/prd/0000-product.md), los pocos ADRs transversales (stack, diseño del repositorio, autenticación, almacén de datos, estilo de API), el esqueleto de arquitectura, el modelo de amenazas fundacional y el contrato central. Estos no pertenecen a ninguna característica individual.
• Nivel de característica — se produce por característica (Etapas 1–8): un brief, un PRD de característica, ADR(s) de característica y un segmento de contrato.

No diseñes cada característica por adelantado — pero SÍ asegura las pocas decisiones fundacionales sin las cuales una primera característica no puede comenzar. Deja que todo lo demás emerja por característica.

Primero: orienta

Resuelve las habilidades desde los directorios de habilidades. Las habilidades empaquetadas localmente en el proyecto son autoritativas dentro de un proyecto de pipeline. Usa la habilidad local del proyecto primero; consulta los directorios globales del usuario (~/.agents/skills, ~/.claude/skills) solo cuando esa habilidad local esté ausente, y revela la alternativa. Si ninguna ubicación la tiene, usa su equivalente en tiempo de ejecución — varias habilidades de etapa tienen el nombre de los comandos de Claude Code (code-review, simplify, security-review) y otros tiempos de ejecución tienen sus propios equivalentes (por ejemplo, Codex review ≈ code-review). Solo cuando no exista ninguna habilidad o equivalente de tiempo de ejecución debes usar la fallback manual en required-skills.yml.

1. Lee AGENTS.md, docs/context.md y docs/test-strategy.md. La Etapa 0 está incompleta si falta el manual operativo o el contexto, AGENTS.md todavía contiene Stack (placeholder, el contexto todavía tiene su línea > STATUS: TEMPLATE o tokens {placeholder}, o la estrategia de prueba falta o todavía contiene su marcador STATUS: TEMPLATE o herramientas de marcador de posición. La Etapa 0 también está incompleta cuando el PRD del producto, la arquitectura, el índice de contratos o el conjunto de ADRs fundacionales faltan o aún están en plantilla. Un modelo de amenazas de seguridad faltante o en plantilla también bloquea la finalización. Verifica docs/prd/0000-product.md, docs/architecture.md, docs/security.md, docs/contracts/README.md y las decisiones aplicables en docs/adr/; rechaza tokens de marcador de posición, rutas de contrato solo de ejemplo, estado de fundación en borrador y un directorio ADR que no registre ninguna decisión real de stack, repositorio, autenticación, almacén de datos o API. También rechaza un documento de seguridad sin amenazas fundacionales y mitigaciones específicas del proyecto. El instalador crea previamente estas rutas, por lo que NO debes confiar solo en la existencia. Si la Etapa 0 está incompleta, ejecuta la rampa de acceso y trata "contexto completado" como una puerta — no avances a Descubrimiento hasta que el marcador STATUS haya desaparecido y las secciones se hayan completado para este proyecto:
   • bootstrap (proyecto nuevo, poco/sin código): dos partes —
     • 0a Contexto: el instalador del kit ya ha preparado docs/, AGENTS.md y el puntero de una línea CLAUDE.md — si falta alguno, vuelve a ejecutar el install.sh del kit (es no destructivo) en lugar de recrearlos manualmente. Luego adapta el stack y las convenciones en AGENTS.md y llena interactivamente docs/context.md. Puerta: contexto completado.
     • 0b Fundación: produce los artefactos a nivel de proyecto — un PRD del producto en docs/prd/0000-product.md, los pocos ADRs transversales inevitables (stack, diseño del repositorio, autenticación, almacén de datos, estilo de API), el esqueleto de architecture.md, un andamio de contrato central, el modelo de amenazas fundacional en docs/security.md, y configura docs/test-strategy.md con las herramientas de prueba reales. Mantenlo mínimo: solo decisiones que una primera característica realmente no pueda iniciar sin ellas — deja que el resto emerja por característica. PUERTA: aprueba la fundación antes de Descubrimiento.
   • adopt (código base existente): usa improve-codebase-architecture más análisis de código de solo lectura explícito para reconstruir docs/prd/0000-product.md, aplicar ingeniería inversa a docs/context.md + docs/architecture.md, adaptar AGENTS.md al stack y convenciones reales, y configurar docs/test-strategy.md desde la configuración de pruebas existente, reconstruir docs/security.md para superficies sensibles existentes, y rellenar los ADRs fundacionales (stack, repo, autenticación, almacén de datos ya integrados en el código). Ese conjunto con ingeniería inversa ES la fundación a nivel de proyecto. Registra las áreas de deuda técnica/riesgo conocidas y candidatos de seguimiento procesables en architecture.md; no crees issues durante la adopción. La Etapa 3 es responsable de la creación de issues después de la aprobación de la fundación. Tu primera característica de validación del flujo de trabajo comienza en la Etapa 1. PUERTA: aprueba.
   • Si estos archivos ya existen (AGENTS.md/CLAUDE.md/docs/), NO los sobrescribas. Fusiona: haz una copia de seguridad o fusiona por secciones, preserva el contenido del equipo, resuelve conflictos. Nunca sobrescribas.
2. Dimensiona correctamente la ruta. Clasifica el cambio antes de enrutar:
   • Característica / orientada al usuario / riesgosa → establece la Etapa 0 una vez si es necesario, luego ejecuta las Etapas 1→8.
   • Corrección de error / mejora pequeña → Implementa → QA → Revisa → Despliega → Retrospectiva (Etapas 4→5→6→7→8; referencia un issue; sin PRD/contrato/ADR).
   • Tarea / documentación / actualización de dependencia → Implementa → Revisa → Despliega → Retrospectiva (Etapas 4→6→7→8; diff trivial, CI verde antes de fusionar).
   • En el momento en que un cambio "pequeño" toca un contrato, un área sensible a la seguridad, o toma una decisión, se gradúa a la ruta completa. Cuando tengas dudas, pregunta.
3. Lee el rastreador (a través de gh / project-status) y el PRD activo para inferir la etapa actual y la característica (modo solo local: lee docs/progress.md).
4. Indica la ruta elegida, la etapa actual y la siguiente acción al usuario antes de proceder.

Encabezado de estado (cada respuesta)

Abre cada respuesta mientras una característica esté en el pipeline con una línea compacta, para que el usuario — y tú — siempre sepas dónde está el pipeline:

SDLC ▸ Etapa {N}/8 {Nombre} · {siguiente puerta o acción}

Ejemplos (sub-etapas de rampa mantienen su letra — 0a/0b/0adopt):

• SDLC ▸ Etapa 0b/8 Fundación · siguiente puerta: aprobar fundación
• SDLC ▸ Etapa 1/8 Especificación · siguiente puerta: aprobar PRD
• SDLC ▸ Etapa 4/8 Implementar · tarea #5 · siguiente: aprobación del plan
• SDLC ▸ Etapa 6/8 Revisar · ejecutando security-review (área sensible)

Solo una línea. Funciona también como tu propio ancla — volver a enunciar la etapa en cada turno es lo que te impide desviarte del proceso durante una conversación larga.

Toma prestada la técnica, no el flujo de trabajo

Las habilidades comunitarias a continuación son técnicas, no el pipeline. Cada una fue creada de forma independiente y lleva sus propias opiniones sobre dónde escribe y qué hace a continuación — esas opiniones son incorrectas aquí, porque este director es dueño del flujo de trabajo. Cuando ejecutes una habilidad prestada, usa su método y anula su flujo de trabajo:

• brainstorming → usa su método de descubrimiento (explora → una pregunta a la vez → enfoques → diseño), pero coloca el artefacto como el breve (opcional) de la Etapa 1 en docs/briefs/NNNN-{slug}.md y DETENTE. Recurre a brainstorming + un breve solo cuando la idea sea difusa; una característica bien comprendida omite ambos y va directamente a to-prd. El descubrimiento es exploratorio — sin código. No escribas en docs/superpowers/specs/, y no ejecutes automáticamente writing-plans; el siguiente paso es la Especificación de la Etapa 1 (to-prd), luego la puerta. Si el usuario aprueba su compañero visual, establece SUPERPOWERS_DISABLE_TELEMETRY=1 para bloquear su solicitud de marca. Mantenlo en bucle invertido; usa un túnel SSH, nunca modo no bucle invertido en texto plano. Usa el directorio de sesión temporal predeterminado; no pases --project-dir. Ignora su instrucción de hacer commit o escribir en docs/superpowers/; este director es dueño del artefacto y la puerta de aprobación.
• to-prd → usa su método de síntesis y la plantilla de PRD del kit, pero escribe el resultado en docs/prd/NNNN-{slug}.md; no publiques ni etiquetes un issue del rastreador. El trabajo del rastreador comienza en la Etapa 3.
• documentation-and-adrs → los ADRs van a docs/adr/NNNN-{slug}.md (convención de este proyecto), nunca a docs/decisions/.
• writing-plans → usa su método de descomposición en la Etapa 3, pero escribe el resultado en el rastreador. No crees docs/superpowers/plans/; el rastreador es el registro.
• ponytail → usa solo para lógica de backend/dominio, analizadores, transformaciones, gestión de estado, herramientas y opciones de dependencias. No puede anular contratos, seguridad, accesibilidad, requisitos explícitos o verificación proporcional; su regla de una verificación es un mínimo, nunca un límite.
• improve-codebase-architecture → usa solo sus heurísticas de lectura de código y profundización. En esa instantánea, CONTEXT.md significa docs/context.md; no invoques las habilidades no disponibles codebase-design o domain-modeling. Actualiza docs/context.md directamente cuando sea necesario, y omite su informe HTML ascendente. Escribe los hallazgos de la adopción en los artefactos de fundación de este kit.
• using-git-worktrees → el aislamiento no aprueba la ejecución de código del repositorio. Nombra el comando exacto de instalación/construcción y obtén aprobación antes de ejecutar comandos de configuración controlados por el repositorio. Para un worktree dentro del repositorio, verifica la ubicación del worktree seleccionada con git check-ignore -q "$LOCATION/"; recházala si el comando falla.
• webapp-testing → usa su método Playwright, pero no uses su with_server.py empaquetado; usa el ejecutor de ciclo de vida del proyecto o un servidor ya en ejecución para que la salida se drene y el árbol de procesos completo permanezca siendo propiedad del proyecto. Espera una señal de disponibilidad específica de la aplicación, como un localizador, URL o verificación de salud; no requieras networkidle.
• Cualquier habilidad que quiera abrir issues/épicas en el rastreador → difiere a la Etapa 3 Descomponer. La etapa de Especificación produce un PRD, no issues.

Si el valor predeterminado de una habilidad prestada entra en conflicto con una convención de AGENTS.md, gana AGENTS.md.

Estándares de comunicación y redacción de documentación

Sigue los estándares de comunicación y redacción de documentación en AGENTS.md; es la única fuente para ambos. Aplica unslop automáticamente a las respuestas dirigidas a humanos y prosa donde sea aplicable; sigue su ámbito canónico y exclusiones. Recorta la salida de la habilidad prestada para que coincida antes de cada puerta.

Las etapas, habilidades y puertas

Etapa	Usar habilidad	Salida	Después de producir la salida
0a Contexto (nuevo)	plantillas del instalador (llenar)	AGENTS.md, docs/context.md completado	PUERTA — contexto completado
0b Fundación (nuevo)	documentation-and-adrs	docs/prd/0000-product.md, ADRs fundacionales (→ docs/adr/), esqueleto de architecture.md, andamio de contrato central, modelo de amenazas fundacional en docs/security.md, docs/test-strategy.md configurado (recorta docs/contracts/README.md a rutas reales/(futuro) — nunca dejes ejemplos de plantilla)	PUERTA — aprobar fundación
0 adopt (existente)	improve-codebase-architecture + análisis de código de solo lectura	PRD del producto reconstruido, contexto/arquitectura/seguridad, docs/test-strategy.md configurado y ADRs fundacionales rellenados (apunta docs/contracts/README.md a la fuente de contrato existente; anota deuda técnica/riesgos en architecture.md)	PUERTA — aprobar
1 Especificación	brainstorming (solo método) → to-prd → grilling	opcional breve de Etapa 1 docs/briefs/NNNN-*.md (solo para una idea difusa/especulativa — si no, salta directamente al PRD), luego PRD endurecido docs/prd/NNNN-*.md (aún sin issues)	PUERTA — aprobar PRD
2 Arquitectura + Contrato	documentation-and-adrs	ADR(s) en docs/adr/, docs/architecture.md actualizado, docs/security.md (áreas sensibles), artefacto de contrato congelado en el repositorio (OpenAPI/tRPC/esquema)	PUERTA — aprobar enfoque + congelar interfaz
3 Descomponer	writing-plans + project-status	issues del rastreador (GitHub por defecto) formados según .github/ISSUE_TEMPLATE/{epic,task}.md (el rastreador es el registro — sin espejo en el repositorio; otros rastreadores: sus tipos de issue nativos; solo local: filas de característica + tarea en docs/progress.md)	revela el desglose, luego continúa
4 Implementar	feature-start (rama; using-git-worktrees solo si el aislamiento es crítico), frontend-design (solo trabajo de UI), ponytail (lógica de backend/dominio, analizadores, transformaciones, estado, herramientas y opciones de dependencias)	código en una rama feat/*, una tarea a la vez	PUERTA — plan compacto por tarea en sesión
5 QA	pruebas + verificaciones equivalentes en tiempo de ejecución (webapp-testing para UI/navegador)	evidencia de verificación, pruebas locales en verde, observación en tiempo de ejecución o una verificación relevante no en tiempo de ejecución; CI verde ahora o después de la creación del PR	procede (revela resultados)
6 Revisión	code-review, simplify obligatorios, y definition-of-done-review de preparación local	diff limpio, evidencia local de DoD, hallazgos corregidos	en línea, sin puerta — pero security-review es obligatorio si se toca un área sensible
7 Desplegar	project-status	PR abierto donde el alojamiento lo soporte. Sin soporte de PR, la rama se empuja si existe un remoto, cualquier CI disponible se ejecuta, y el humano lo fusiona directamente; sin remoto, el humano fusiona la rama local (Reglas → Rastreador, remoto y capacidades de PR/CI). GitHub: el PR lleva Closes #N y el issue se cierra al fusionar — nada que escribir. Cualquier otro rastreador o solo local: sin palabra clave de cierre; mueve la tarea a en revisión según Finalización de tarea por rastreador	PUERTA — el humano fusiona
8 Retrospectiva	reflexiona + escribe (nativo)	selecciona 0–3 aprendizajes duraderos después de cada tarea; después del hijo final, reconcilia los artefactos de la característica y la épica padre (ver Etapa 8)	si los archivos del repositorio cambiaron, ofrece desplegarlos en main; de lo contrario, continúa sin una acción de despliegue vacía

Protocolo de puerta (no negociable)

En cada PUERTA, haz TODO lo siguiente y luego detente:

1. N

…

[truncado para traducción]