felipevale23/sddkit

/sdd-stack

Entrada: $ARGUMENTS. Conduces una entrevista sobre la stack y solo escribes archivos al final, después de que el usuario confirme el resumen.

0. Antes de preguntar: descubre los hechos

Los hechos del entorno son trabajo tuyo, nunca le preguntes al usuario. Mira (o delega a un subagente):

• Manifiestos y código existentes (package.json, pyproject.toml, go.mod, Dockerfile, .github/workflows/, carpetas raíz);
• .agents/specs/stack.md y architecture.md (si ya están completos y no hay --revisar, muestra el resumen y pregunta solo lo que falta);
• .specify/memory/constitution.md (restricciones ya decididas, ej.: LGPD, base de datos única);
• sddkit suggest --json (stacks detectadas).

Lo que ya está decidido en el código entra como decisión tomada, no como pregunta.

1. Método

• Skill grilling instalada en .agents/skills/ → sigue su método (rondas por la frontera del árbol de decisiones, cada pregunta con respuesta recomendada, hasta que la frontera se vacíe).
• No instalada → mismo formato: en cada ronda, todas las preguntas cuyas precondiciones ya están respondidas, numeradas, cada una así:

❓ **Q1 — <título>**: <pregunta, con 2–4 opciones y el trade-off de cada una en 1 línea>

➡️ <tu recomendación y el porqué, en 1–2 líneas>

Escribe cada pregunta de modo que "sí" acepte la recomendación. Prefiere tecnología aburrida y madura, que el equipo ya conoce, al estado del arte; un lenguaje para todo el proyecto, salvo motivo sólido; el mínimo de piezas que cubra el alcance (cada servicio adicional es un costo de operación). Si la respuesta contradice una anterior o la constitución, señálalo y pregunta cuál prevalece.

2. Árbol de decisiones de la stack

Recorre en este orden de dependencia; salta ramas que no apliquen (ej.: sin UI → sin preguntas de frontend).

1. Producto: qué es (app web, API, app móvil, escritorio, CLI, biblioteca, worker), quién lo usa, escala esperada (usuarios, datos, picos), restricciones (LGPD, offline, costo, plazo).
2. Equipo: lenguajes que el equipo domina; quién mantendrá.
3. Forma: monolito modular, monorepo con paquetes o servicios separados; qué necesita ser asíncrono.
4. Lenguaje y runtime (versión mayor): ej.: TypeScript/Node 22, Python 3.12.
5. Frontend (si hay UI): framework (React/Next, Vue/Nuxt, Svelte, Astro…), renderizado (SPA, SSR, estático), biblioteca de componentes y estilo (MUI, shadcn+Tailwind…), estado del servidor (TanStack Query…), i18n, accesibilidad.
6. Móvil/escritorio (si hay): nativo, React Native/Expo, Flutter, Tauri, Electron.
7. Backend/API: framework (Express, Fastify, NestJS, Hono, FastAPI, Django…), estilo (REST, GraphQL, tRPC), contratos y validación (Zod, Pydantic, OpenAPI). 7b. Paradigma del backend (solo si hay backend; nunca para el frontend, que sigue el idioma del framework):
   • Estilo: OOP con SOLID (entidades con invariantes, servicios dependiendo de interfaces), funcional (funciones puras, datos inmutables, efectos en los bordes) o pragmático (módulos simples, abstracción solo con 2+ implementaciones — el estándar de ponytail).
   • Arquitectura: capas simples (controller → service → repository), clean/hexagonal (dominio sin dependencia del framework, puertos y adaptadores) o DDD (bounded contexts, agregados). Recomienda lo más simple que el dominio aguante: clean/DDD solo con regla de negocio rica.
   • Qué carpetas son backend (ej.: server/**, services/**, modules/**). Esto es lo que limita el paradigma al backend.
8. Datos: base de datos (PostgreSQL, MySQL, MongoDB, SQLite), ORM/acceso (Prisma, Drizzle, SQLAlchemy…), migraciones, caché.
9. Asíncrono: cola/jobs (BullMQ, Celery, pg-boss…), eventos, tiempo real (WebSocket/SSE).
10. Autenticación y autorización: proveedor o propio, sesiones/JWT, roles/permisos.
11. Integraciones externas: pagos (PIX…), correo, IA (SDK de Anthropic…), MCP.
12. Hospedaje y operación: dónde corre (Vercel, VPS con Docker, nube gestionada), entornos, secretos, observabilidad (logs, errores, métricas).
13. Calidad: pruebas (unidad, integración, e2e con Playwright), lint/format, typecheck, CI (GitHub Actions), commits (Conventional Commits/commitlint).

3. Confirmación

Con la frontera vacía, muestra el resumen en una tabla (capa · elección · versión · por qué · alternativa descartada) y pregunta: "¿Cerramos así?". No escribas nada antes del "sí".

4. Grabar

1. .agents/specs/stack.md: sustituye el contenido (incluyendo el marcador [PREENCHER) por:
   • ## Por componente — cada capa con tecnología, versión mayor y las bibliotecas principales por el nombre del paquete (ej.: react, @prisma/client, bullmq, fastapi): sddkit usa estos nombres para sugerir roles y skills;
   • ## Infraestructura — base de datos, cola, caché, hospedaje, CI, observabilidad;
   • ## Decisiones — cada elección relevante con el porqué y la alternativa descartada (fecha de hoy).
2. .agents/specs/architecture.md: completa la sección ## Visión general (componentes y cómo se comunican; un diagrama mermaid si hay más de 2 piezas) y quita el [PREENCHER. Si ya hay código, completa también ## Mapa del código (una línea por área: entrada, carpetas clave, pruebas). Las demás secciones quedan para cuando haya código.
3. Paradigma del backend (si se decidió en 7b y no es "pragmático"):
   • .agents/specs/coding-standards.md: sección ## Backend — paradigma con el estilo, la arquitectura, las carpetas de backend, 3–5 reglas concretas con un ejemplo corto cada una, y la herramienta que impone las reglas (abajo). Deja claro que el frontend no sigue esta sección.
   • Memoria de sddkit, para que el agente sepa el alcance en toda sesión:

     sddkit memory add "Paradigma <estilo>/<arquitectura> solo en el backend (<carpetas>); en el frontend sigue el idioma del framework" -t paradigma
     sddkit memory add "En el backend, la sección 'Backend — paradigma' de coding-standards.md prevalece sobre ponytail en interfaces y capas" -t paradigma
     sddkit memory add "<regla concreta más importante>" -t paradigma-backend --paths "<carpetas de backend>"
     

   • Skills (opcionales en el catálogo, cargadas solo por los roles de backend api, data, event-module, queue-worker): OOP/SOLID → sddkit add solid; clean/hexagonal → sddkit add clean-architecture; DDD → sddkit add domain-driven-design. Funcional: no hay una skill general buena; las reglas en coding-standards.md y el lint hacen el trabajo.
   • Imposición determinista (lint restringido a las carpetas de backend; se convierte en la primera tarea de setup de /sdd-feature si aún no hay código):
     • capas/clean/hexagonal/DDD: dependency-cruiser o eslint-plugin-boundaries (TypeScript), import-linter (Python) — el dominio no importa infraestructura ni framework;
     • funcional en TypeScript: eslint-plugin-functional en un bloque de ESLint con files: ["<carpetas de backend>"] (sin clases, sin mutación, sin let);
     • OOP: no hay linter que exija OOP; usa las reglas de capas anteriores y la revisión.
4. Constitución: si surgieron restricciones innegociables (ej.: "PostgreSQL es la única fuente de verdad"), propón el texto y sugiere /speckit-constitution — no edites la constitución directamente.
5. Dile al usuario que ejecute en el terminal:

   sddkit init        # lee la stack declarada y ofrece roles y skills de ella (nada existente se borra)
   sddkit doctor
   

Informe final (≤ 8 líneas)

Stack decidida en 1 línea por capa · paradigma del backend y cómo se impone · archivos grabados · restricciones sugeridas para la constitución · siguiente paso (sddkit init, luego /sdd-feature).