fswp-architect

FSWP Architect

No se escribe código hasta que esta etapa termine con un PRD o informe de cambio aprobado. Objetivo: cada decisión tomada en una ronda de preguntas y en un documento revisable, sin idas y vueltas posteriores.

Paso 0: Tipo de trabajo y triaje

• Confirmar el tipo de trabajo desde fswp-developer/references/work-types.md: Nuevo plugin, Nuevo tema, Actualización, Add-on, Parche del núcleo.
• Actualización, Add-on, Parche del núcleo, o cualquier base de código desconocida: ejecutar primero python3 scripts/detect_wp_project.py <ruta>. Informa el tipo de proyecto (plugin, tema, tema de bloques, checkout del núcleo, sitio, desconocido), archivo principal y campos de cabecera, versión y sugerencias de versión mínima, herramientas (Composer, npm, PHPCS, PHPStan, tests) y hooks/rutas REST/bloques encontrados. Citar los hallazgos en el plan. El script solo lee archivos.
• Las solicitudes con forma de plugin o tema cuentan aunque no tengan la palabra "plugin" o "tema" (tipos de contenido personalizados, integraciones REST, paneles de administración, plantillas personalizadas, estilos para todo el sitio, cualquier cosa que necesite activación o desactivación). Las herramientas de un solo shortcode entregadas como archivos de FluentSnippets pertenecen a wordpress-mini-app-builder, no aquí.

Paso 0a: Aún no hay PRD

Si el usuario pide empezar a construir y no existe un PRD o informe de cambio: pedirle que proporcione uno antes de empezar. No comenzar la implementación y no saltar silenciosamente al Paso 1. Si el usuario insiste explícitamente ("solo constrúyelo", "salta el PRD"), el requisito se considera renunciado: ir directamente al Paso 1 y crear el documento a partir de esa ronda de preguntas.

Paso 0b: PRD, AGENTS.md, documentos de arquitectura proporcionados por el usuario

Leerlos antes de escribir código y verificarlos contra fswp-plugin-developer/references/standards.md y las demás reglas internas.

• Sin conflicto real: proceder con la documentación proporcionada más los estándares internos; las reglas internas llenan los vacíos.
• Conflicto real (el documento pide algo que una regla interna prohíbe, como un atajo de seguridad o un esquema de nombres): mencionar ambos lados claramente y preguntar cuál prevalece. No mezclarlos silenciosamente.
• Un PRD proporcionado aún pasa por el Paso 4; no está exento.

Paso 1: Una ronda de preguntas esenciales

Usar la herramienta de preguntas estructuradas cuando esté disponible (Claude Code: AskUserQuestion; claude.ai: ask_user_input_v0); de lo contrario, una lista numerada compacta. Como máximo 3-4 preguntas, elegidas según el tipo de trabajo:

Tipo de trabajo	Preguntar sobre
Nuevo plugin	Destino de distribución (WordPress.org, zip privado, ambos); superficie de funcionalidad (tipo de contenido, tabla personalizada, REST, cron, pantalla de administración, salida frontal); sistema de diseño front-end (el del usuario, si lo hay, o uno neutro); comportamiento estático vs. dinámico; prefijo de código / acrónimo para este proyecto
Nuevo tema	Tema de bloques o clásico; distribución (directorio de temas de WordPress.org, privado, sitio del cliente); punto de partida (desde cero, hijo de un tema existente); qué tipos de contenido y diseños de página se requieren; prefijo de código / acrónimo para este proyecto
Actualización	Objetivo (error, funcionalidad, compatibilidad, refactorización); cómo se entrega (parche a un repo, zip, ediciones directas); qué no debe cambiar
Add-on	Producto anfitrión y rango de versiones soportado; qué añade el add-on; qué debe suceder si el anfitrión falta
Parche del núcleo	Número de ticket o descripción del error; componente objetivo; si ya existe un ticket en Trac

Todo lo abierto (nombres de campos, reglas de negocio, casos límite, nombre de trabajo) se infiere y se lista bajo "Suposiciones" del PRD, no se pregunta. No hay segunda ronda a menos que las respuestas de la primera creen una bifurcación realmente bloqueante.

Prefijo/acrónimo: para trabajos de nuevo plugin y nuevo tema, preguntar qué acrónimo o prefijo corto debe usar el código del proyecto; si el usuario no tiene ninguno, proponer 2-3 candidatos derivados del nombre del proyecto y dejar que elija. No hay un valor predeterminado integrado y nunca se usa el nombre o la marca de esta herramienta como sustituto. Regla completa, redacción exacta de la pregunta y excepciones (mínimo de 4 letras del tema, slug del producto vs. prefijo de código, nombres reservados): fswp-developer/references/brand-naming.md. Nunca WP o Plugin como prefijo. En trabajos de Actualización y Add-on, no preguntar; mantener el prefijo existente del proyecto. Versiones mínimas predeterminadas: WordPress 6.4, PHP 7.4; aumentar solo por una necesidad específica (por ejemplo PHP 8.1 para enums). Confirmar los requisitos actuales en la documentación oficial cuando sea relevante.

Información del proyecto (misma ronda, nunca una segunda): nombre de la empresa, nombre del producto, autor, colaboradores y enlaces (sitio web, documentación, soporte, repositorio). Preguntar solo por lo que aún no esté indicado. Nunca inventar un valor faltante: un enlace o colaborador no indicado se omite de todos los archivos generados.

Decisión de la pila tecnológica: para trabajos nuevos, decidir el nivel de UI de administración y el nivel de JS antes de redactar el PRD (fswp-plugin-developer/references/standards.md sección 2). Para trabajos existentes, la pila existente se mantiene a menos que haya una razón declarada para cambiarla.

Paso 2: Investigación competitiva

2-3 productos líderes en la categoría (directorio de WordPress.org o SaaS). Capturar las funcionalidades básicas, quejas comunes y convenciones que vale la pena igualar. Un puñado de búsquedas; 3-5 viñetas en el documento. Omitir para parches del núcleo; investigar el historial del ticket en su lugar.

Paso 3: El documento

• Nuevo plugin, nuevo tema: PRD desde references/prd-template.md (con notas de variante de tema en el interior).
• Actualización, Add-on: informe de cambio desde references/change-brief-template.md: comportamiento actual, comportamiento solicitado, lista de paridad (qué debe seguir funcionando), tabla de compatibilidad, riesgos, plan de pruebas.
• Parche del núcleo: informe breve centrado en el ticket desde references/change-brief-template.md más los pasos en fswp-core-contributor.

Ejecutar el comportamiento front-end a través de la lista de verificación de 5 puntos del nivel de JS (fswp-plugin-developer/references/frontend-output.md) y declarar el nivel. Los recuentos derivados (tokens, bloques, rutas, pantallas) provienen de los datos o el código, nunca de la memoria.

Paso 4: Puerta de aprobación (la única)

Presentar el documento. Las decisiones son visibles y ya están tomadas; el usuario aprueba o corrige una vez. Si el nivel de JS es Alpine, nombrarlo y obtener un sí explícito. Sin andamiaje ni ediciones antes de la aprobación; las correcciones aprobadas se integran primero.

Modo de migración

Para reconstruir un plugin existente sobre una nueva pila. Antes de cualquier cambio de código:

1. Línea base: capturar capturas de pantalla de cada pantalla y estado, más exportaciones de referencia (configuraciones, datos, archivos generados) de la versión antigua. Almacenar en baseline/.
2. Matriz de paridad: cada funcionalidad antigua, configuración, hook, shortcode, ruta REST y opción almacenada mapeada a: mantenido / cambiado (por qué) / eliminado (por qué). Nada no listado se envía silenciosamente.
3. Comparación de exportaciones: después de la reconstrucción, regenerar las mismas exportaciones y compararlas con la línea base. Las diferencias deben ser intencionadas y estar listadas.
4. Puerta de regresión visual: comparar las nuevas capturas de pantalla con la línea base para cada pantalla; las diferencias inexplicables bloquean la entrega (alimenta a fswp-qa-engineer).
5. Ruta de datos: una actualización desde los datos almacenados de la versión antigua debe funcionar sin reactivación (ver fswp-qa-engineer).

Paso 5: Documentos de traspaso (construcciones en múltiples sesiones)

Cuando la construcción abarque varias sesiones, escribir ambos archivos en la raíz del repositorio del plugin (no en el zip):

• AGENTS.md: qué es; comandos (build, test, puerta de QA); mapa de arquitectura; reglas internas y convenciones; decisiones y restricciones; problemas y áreas prohibidas; definición de completado.
• HANDOFF.md: estado actual; mapa de código (archivo: responsabilidad); tabla de verificado / no verificado (cada escenario del PRD con PASA / FALLA / NO EJECUTADO y evidencia); elementos abiertos; siguiente paso.

Actualizar ambos en cada parada, y antes de finalizar cualquier sesión que no haya terminado.