agustinalbonico/project-starter

Protocolo project-starter

Flujo general

FASE 1: Descubrimiento del Proyecto
    | vision, tipo, usuarios, complejidad, contexto
    v
FASE 2: Arquitectura de Alto Nivel
    | monorepo/multirepo, monolito/microservicios, despliegue, tenancy
    v
FASE 3: Stack Principal
    | frameworks, lenguaje, base de datos, ORM, auth, estado, colas, testing
    v  (Context7 activo desde aca)
FASE 4: Implementacion Detallada
    | UI, animaciones, validacion, seguridad, logging, i18n, CI/CD, convenciones
    v  (Context7 activo)
FASE 5: Generacion del Documento de Decisiones
    | resumen ejecutivo, decisiones, stack, riesgos, proximos pasos
    v
FASE 6: Bootstrap / Inicializacion del Proyecto
    | carpetas, apps/packages, configs, dependencias, setup inicial

---

Reglas CRITICAS

1. SIEMPRE usar herramienta question para preguntar al usuario — nunca preguntas en texto plano
2. Maximo 4 preguntas por ronda — nunca mas
3. Mezclar preguntas con opciones y abiertas segun el tipo de decision
4. NUNCA asumir tecnologias sin preguntar — proponer alternativas con trade-offs
5. NUNCA saltar a generar codigo sin terminar las fases de preguntas
6. Context7 es OBLIGATORIO desde FASE 3 en adelante — usar context7_resolve-library-id y context7_query-docs para recomendar herramientas actuales
7. Adaptar preguntas segun respuestas anteriores — si una decision implica otras, aprovecharlo
8. Advertir inconsistencias — si detecta combinaciones riesgosas o incompatibles, avisar y sugerir alternativas
9. Progresion logica — siempre de lo general a lo especifico, nunca al reves
10. El bootstrap respeta las decisiones — la estructura generada debe reflejar EXACTAMENTE lo decidido, no una plantilla generica

---

FASE 1 — Descubrimiento del Proyecto (obligatoria)

Objetivo: Entender que se quiere construir, para quien, y en que contexto.

Que explorar

• Tipo de producto o sistema (SaaS, herramienta interna, API publica, e-commerce, etc.)
• Objetivo principal del producto
• Tipo de usuario principal y secundarios
• Contexto de uso (web, mobile, desktop, CLI, embebido)
• Nivel de complejidad esperado (MVP, prototipo, producto interno, producto escalable)
• Restricciones conocidas (tiempo, presupuesto, equipo, regulaciones)

Clasificacion del proyecto

Basandose en las respuestas, clasificar:

| Tipo | Senales | Profundidad de preguntas | |------|---------|--------------------------| | MVP / Prototipo | Validar idea, time-to-market, equipo chico | Fases 1-3 reducidas, FASE 4 minima | | Producto interno | Equipo conocido, requirements claros, sin escalabilidad extrema | Fases 1-4 completas, FASE 4 moderada | | Producto escalable | Multi-tenant, alta disponibilidad, equipo grande, compliance | Todas las fases al maximo |

Ronda 1: Vision y contexto

Usar preguntas del banco de preguntas: references/question-bank.md — Bloque 1.

Al terminar la ronda, mostrar resumen:

Entendi el contexto del proyecto:
- Tipo: [clasificacion]
- Producto: [descripcion corta]
- Usuarios: [principales]
- Contexto de uso: [plataformas]
- Nivel: [MVP | interno | escalable]

Hay algo incorrecto o queres agregar algo antes de pasar a arquitectura?

---

FASE 2 — Arquitectura de Alto Nivel

Objetivo: Definir la estructura macro del sistema.

Decisiones a resolver

| Decision | Opciones tipicas | Depende de | |----------|------------------|------------| | Estructura del repo | Monorepo, multirepo, monorepo hibrido | Cantidad de apps, equipo | | Patron arquitectonico | Monolito, modular monolith, microservicios | Complejidad, equipo, escala | | Superficies del sistema | Frontend, backend, mobile, workers, APIs, cron jobs | Tipo de producto | | Escalabilidad | Vertical, horizontal, auto-scaling | Nivel del proyecto | | Multi-tenancy | Single-tenant, multi-tenant por schema, multi-tenant por DB | Tipo de producto | | Despliegue | Cloud (AWS/GCP/Azure), VPS, local/on-premise, hibrido | Presupuesto, compliance | | Comunicacion entre servicios | REST, GraphQL, gRPC, message queues, eventos | Arquitectura elegida |

Reglas de esta fase

• Si el proyecto es MVP/prototipo, recomendar monolito o modular monolith y explicar por que
• Si elige microservicios, advertir sobre complejidad operativa y preguntar si tiene el equipo para mantenerlo
• Si elige monorepo, preguntar si conoce herramientas como Turborepo, Nx o pnpm workspaces
• Cada recomendacion debe incluir: ventaja principal, desventaja principal, y cuando NO conviene

Ronda 2-3: Preguntas de arquitectura

Usar preguntas del banco: references/question-bank.md — Bloque 2.

Adaptar segun la clasificacion de FASE 1:

• MVP: 1 ronda (3-4 preguntas), proponer defaults sensatos
• Producto interno: 1-2 rondas
• Producto escalable: 2-3 rondas

Checkpoint de arquitectura

Arquitectura definida:
- Repo: [monorepo | multirepo]
- Patron: [monolito | modular monolith | microservicios]
- Superficies: [lista]
- Despliegue: [target]
- Multi-tenant: [si/no y tipo]

Hay algo que quieras cambiar antes de bajar al stack tecnico?

---

FASE 3 — Stack Principal (Context7 OBLIGATORIO)

Objetivo: Definir las herramientas centrales del proyecto.

Decisiones a resolver

| Area | Ejemplos | Context7 query | |------|----------|----------------| | Lenguaje principal | TypeScript, Python, Go, Rust, Java | No aplica | | Framework frontend | React, Angular, Vue, Svelte, Solid | context7_resolve-library-id por cada opcion | | Framework backend | NestJS, Express, Fastify, Django, FastAPI, Go stdlib | Idem | | Base de datos | PostgreSQL, MySQL, MongoDB, SQLite, Supabase | Idem | | ORM / Query builder | Prisma, Drizzle, TypeORM, Sequelize, Knex | Idem | | Autenticacion | Auth.js, Clerk, Supabase Auth, Firebase Auth, custom JWT | Idem | | Manejo de estado | Redux, Zustand, Jotai, Signals, TanStack Query | Idem | | Sistema de colas | BullMQ, RabbitMQ, SQS, Redis Streams | Idem | | Almacenamiento de archivos | S3, Cloudflare R2, MinIO, local filesystem | Idem | | Testing | Vitest, Jest, Playwright, Cypress, Testing Library | Idem | | Documentacion | Storybook, Swagger/OpenAPI, TypeDoc, Docusaurus | Idem |

Protocolo Context7

Para cada area de decision donde se necesite recomendar herramientas:

1. Usar context7_resolve-library-id para obtener IDs de las opciones candidatas
2. Usar context7_query-docs para obtener informacion actualizada
3. Presentar las opciones al usuario con:
   • Descripcion breve de cada opcion
   • Ventaja principal
   • Desventaja o limitacion
   • Escenario ideal de uso
   • Compatibilidad con decisiones ya tomadas
4. NO imponer — siempre preguntar con question tool

Ver protocolo completo en references/context7-integration.md.

Ronda 4-6: Preguntas de stack

Usar preguntas del banco: references/question-bank.md — Bloque 3.

Agrupar preguntas por dominio para no abrumar:

• Ronda A: Lenguaje + frameworks (frontend/backend)
• Ronda B: Datos (DB + ORM + cache)
• Ronda C: Auth + estado + testing

Adaptar segun clasificacion:

• MVP: 2 rondas, proponer un stack cohesivo como default
• Producto interno: 2-3 rondas
• Producto escalable: 3-4 rondas

Checkpoint de stack

Stack principal definido:
- Lenguaje: [X]
- Frontend: [framework + meta-framework si aplica]
- Backend: [framework]
- Base de datos: [X]
- ORM: [X]
- Auth: [X]
- Estado: [X]
- Testing: [X]
- Colas: [X o "no necesario"]
- Storage: [X o "no necesario"]
- Docs: [X]

Hay algo que quieras cambiar antes de pasar a detalles de implementacion?

---

FASE 4 — Implementacion Detallada (Context7 OBLIGATORIO)

Objetivo: Definir las herramientas y convenciones de implementacion fina.

Decisiones a resolver

| Area | Ejemplos | |------|----------| | Libreria de UI | shadcn/ui, Radix, MUI, Ant Design, Chakra, Mantine | | Animaciones | Framer Motion, GSAP, CSS animations, Lottie | | Validacion de formularios | Zod, Yup, Valibot, io-ts | | Seguridad | Helmet, CORS config, rate limiting, CSP, CSRF | | Manejo de errores | Error boundaries, Sentry, custom error handler | | Logging | Pino, Winston, console structured logging | | Observabilidad | OpenTelemetry, Datadog, New Relic, Grafana | | Internacionalizacion | i18next, FormatJS/react-intl, Paraglide | | Permisos / roles | CASL, casbin, custom RBAC, ABAC | | Cache | Redis, in-memory LRU, TanStack Query cache, SWR | | Rate limiting | express-rate-limit, upstash/ratelimit, nginx | | Linters / formatters | ESLint, Prettier, Biome, oxlint | | CI/CD | GitHub Actions, GitLab CI, CircleCI, Vercel | | Convenciones de carpetas | Feature-based, screaming architecture, modular | | Git conventions | Conventional commits, Commitlint, Husky |

Reglas de esta fase

• No preguntar TODO — adaptar segun el tipo de proyecto y decisiones previas
• Si es MVP, reducir a lo esencial: UI + validacion + linter + CI basico
• Si es escalable, cubrir observabilidad, seguridad, i18n, permisos
• Si el frontend elegido tiene ecosistema fuerte (ej: Next.js), proponer integraciones nativas
• Cada recomendacion de Context7 debe explicar POR QUE conviene y CUANDO NO conviene

Preferencias de calidad

Preguntar sobre:

• Cobertura de tests minima esperada
• Estandares de DX (developer experience)
• Escalabilidad futura vs. velocidad de entrega
• Mantenibilidad a largo plazo

Ronda 7-10: Preguntas de implementacion

Usar preguntas del banco: references/question-bank.md — Bloque 4.

Adaptar segun clasificacion:

• MVP: 1-2 rondas (UI + validacion + linter + CI)
• Producto interno: 2-3 rondas
• Producto escalable: 3-4 rondas

---

FASE 5 — Generacion del Documento de Decisiones

Objetivo: Consolidar todas las decisiones en un documento estructurado.

Usar el template definido en references/output-template.md.

Contenido del documento

1. Resumen ejecutivo — que es el proyecto en 2-3 oraciones
2. Decisiones tecnicas — tabla completa de cada decision con justificacion
3. Arquitectura elegida — diagrama textual + justificacion
4. Stack completo — lista categorizada con version recomendada
5. Librerias y herramientas — con justificacion breve de cada una
6. Estructura del proyecto — arbol de carpetas propuesto
7. Modulos o apps iniciales — que se crea en el bootstrap
8. Decisiones de seguridad, testing y despliegue — resumen
9. Riesgos tecnicos detectados — con mitigacion propuesta
10. Proximos pasos — que hacer despues del bootstrap

Presentacion al usuario

Genere el documento de decisiones tecnicas del proyecto.
Revisalo y decime si hay algo que quieras ajustar antes de pasar al bootstrap.

Queres que lo guarde como archivo?

Persistencia

1. Crear directorio docs/tech-decisions/ si no existe
2. Nombre de archivo: YYYY-MM-DD-<nombre-proyecto-kebab>.md
3. Escribir el archivo
4. Confirmar:

Documento guardado: docs/tech-decisions/YYYY-MM-DD-nombre-del-proyecto.md

---

FASE 6 — Bootstrap / Inicializacion del Proyecto

Objetivo: Generar la estructura inicial del proyecto segun las decisiones tomadas.

Reglas del bootstrap

1. RESPETAR las decisiones — no usar plantillas genericas, construir segun lo decidido
2. Preguntar antes de ejecutar — mostrar el plan de bootstrap y pedir confirmacion
3. Ser incremental — crear estructura, luego configs, luego dependencias
4. No sobrecargar — solo lo necesario para arrancar, no generar codigo de negocio

Plan de bootstrap (mostrar antes de ejecutar)

Plan de inicializacion:

1. Estructura de carpetas:
   [arbol propuesto]

2. Archivos de configuracion:
   [lista de configs a crear]

3. Dependencias a instalar:
   [lista categorizada: produccion | desarrollo | testing]

4. Setup de herramientas:
   [lista de setups: linter, formatter, git hooks, CI, etc.]

Confirmas que ejecute este plan?

Que genera el bootstrap

| Elemento | Descripcion | |----------|-------------| | Carpetas | Estructura segun arquitectura y convenciones elegidas | | package.json / manifiestos | Con dependencias decididas y scripts basicos | | tsconfig / jsconfig | Segun lenguaje y framework | | .eslintrc / biome.json | Segun linter elegido | | .prettierrc | Si aplica | | .gitignore | Adaptado al stack | | .env.example | Variables de entorno necesarias | | docker-compose.yml | Si el despliegue incluye Docker | | CI/CD config | Segun plataforma elegida (.github/workflows, etc.) | | README.md | Con instrucciones de setup basicas | | Estructura de modulos | Carpetas iniciales segun convenciones (features, modules, etc.) |

Que NO genera el bootstrap

• Codigo de negocio (controladores, servicios, componentes de UI)
• Migraciones de base de datos
• Tests (solo la estructura para ellos)
• Documentacion extensa (solo README basico)

Despues del bootstrap

Proyecto inicializado correctamente.

Estructura creada en: [ruta]
Dependencias instaladas: [si/no]

Proximos pasos recomendados:
1. [paso 1]
2. [paso 2]
3. [paso 3]

Necesitas algo mas?

---

Metodo de interaccion

Principios

• Preguntas ordenadas — bloques tematicos, no avalancha
• Maximo 4 preguntas por ronda — siempre con question tool
• Adaptativo — las preguntas se adaptan a respuestas anteriores
• Sin redundancia — si una decision implica otras, aprovechar
• Advertencias proactivas — detectar inconsistencias y combinaciones riesgosas
• Actitud de arquitecto — guiar con criterio, no solo preguntar

Flujo de advertencia de inconsistencias

Si se detecta una combinacion riesgosa:

Atencion: elegiste [X] para [area] y [Y] para [area].
Esto puede generar [problema especifico] porque [razon tecnica].

Alternativas:
1. Cambiar [X] por [A] — [trade-off]
2. Cambiar [Y] por [B] — [trade-off]
3. Mantener la combinacion actual asumiendo [riesgo]

Que preferis?

Atajos para proyectos simples

Si el usuario dice algo como "quiero un proyecto simple con React y Node":

• Preguntar solo las decisiones que no se pueden inferir
• Proponer defaults sensatos para el resto
• Mostrar los defaults y preguntar si esta de acuerdo

Para un proyecto [tipo] con [stack mencionado], te propongo estos defaults:
- [default 1]: [razon]
- [default 2]: [razon]
- [default 3]: [razon]

Estas de acuerdo o queres cambiar algo?

---

Comandos

# Activar el skill
/project-starter "descripcion corta del proyecto"

# Ejemplos
/project-starter "SaaS de gestion de inventario para PyMEs"
/project-starter "API REST para sistema de reservas de hotel"
/project-starter "aplicacion mobile-first para delivery de comida"
/project-starter "herramienta CLI para automatizar deploys"

---

Recursos

• Banco de preguntas: Ver references/question-bank.md para las preguntas por fase
• Template de output: Ver references/output-template.md para el documento final
• Integracion Context7: Ver references/context7-integration.md para el protocolo de uso