Workflow: De Idea a Produccion
El ciclo de desarrollo completo para www.mavelpoint.com — desde la exploracion de la idea inicial hasta la especificacion, implementacion, testing y despliegue en produccion. Impulsado por el sistema de artefactos OpenSpec y las skills especificas de MavelPoint.
Vision General del Workflow
Seis fases impulsan cada cambio desde la idea hasta produccion. El workflow es fluido — los artefactos pueden actualizarse en cualquier fase si surge nueva informacion.
El Ciclo Completo
Cada feature, fix o refactor sigue el mismo ciclo estructurado.
Descubrir
Explorar el espacio del problema. Investigar el codebase. Comparar enfoques.
Planificar
Iniciar un cambio. Crear la estructura de artefactos. Definir el alcance.
Especificar
Crear artefactos de propuesta, diseno, specs y tareas.
Implementar
Construir la feature. Aplicar design tokens. Seguir patrones de componentes.
Verificar
Testear, revisar completitud, correccion y coherencia.
Desplegar
Sincronizar specs, archivar el cambio, desplegar a produccion.
Principios Clave
Reglas que gobiernan todo el workflow.
Fluido, No Bloqueado por Fases
Si la implementacion revela un problema de diseno, actualiza el artefacto de diseno inmediatamente. No esperes a un ciclo formal de revision.
Dirigido por el Agente
Claude Code puede explorar, planificar, implementar, testear y verificar cambios de forma autonoma usando el sistema de skills OpenSpec.
Preservacion de Decisiones
Cada cambio se archiva con sus artefactos completos. Siempre puedes rastrear por que algo se construyo de cierta manera.
Testing como Especificacion
Los tests son artefactos de primera clase creados a traves del mismo workflow que las features, con specs completas y verificacion.
Fase 1: Descubrir
Explorar el espacio del problema antes de comprometerse con una solucion. Investigar, comparar enfoques y detectar riesgos.
openspec-explore
Companero de pensamiento para investigar problemas.
• Hacer preguntas clarificadoras sobre el problema
• Investigar el codebase para mapear la arquitectura existente
• Comparar multiples enfoques con analisis de tradeoffs
• Visualizar conceptos con diagramas ASCII
• Detectar riesgos, incognitas y suposiciones
• Leer propuestas, disenos y specs existentes de OpenSpec
openspec-onboard
Introduccion guiada al ciclo completo del workflow.
• Escanea el codebase buscando oportunidades de mejora (TODOs, tests faltantes, problemas de tipos)
• Recorre todas las fases con trabajo real del codebase
• Seleccion de tareas y gestion del alcance
• Narracion del ciclo completo desde exploracion hasta archivo
Skills de Contexto
Conocimiento del dominio que informa las decisiones de descubrimiento.
mavelpoint-strategy
Objetivos, prioridades y hoja de ruta
mavelpoint-audiences
Segmentos de usuarios y perfiles de persona
mavelpoint-domain
Vocabulario de la industria de musica electronica
mavelpoint-web-product
Arquitectura del sitio, sitemap, tech stack
Fase 2: Planificar
Iniciar un cambio formal. Crear la estructura del directorio de artefactos y definir que se va a construir.
openspec-new-change
Iniciar un nuevo cambio desde cero.
• Derivar nombre kebab-case del cambio
• Seleccionar esquema de workflow
• Crear openspec/changes/<nombre>/
• Mostrar estado de artefactos y dependencias
openspec-ff-change
Fast-forward: crear todos los artefactos de una vez.
• Para features bien comprendidas
• Bootstrap de propuesta + diseno + specs + tareas en un paso
• Omite la creacion iterativa de artefactos
openspec-continue-change
Retomar un cambio existente en cualquier fase.
• Continuar donde lo dejaste
• Verificar estado de completitud de artefactos
• Funciona en cualquier punto del ciclo
Fase 3: Especificar
Crear los cuatro artefactos principales que definen que se va a construir y como.
Los Cuatro Artefactos
Cada artefacto captura una dimension diferente del cambio.
Por Que y Que
• Declaracion del problema u oportunidad
• Que va a cambiar
• Capacidades nuevas y modificadas
• Impacto en el codebase
Como y Decisiones
• Estado actual y contexto
• Objetivos y no-objetivos
• Decisiones tecnicas clave
• Tradeoffs y justificacion
Requisitos Detallados
• Descripciones precisas de requisitos
• Escenarios en formato WHEN / THEN / AND
• Testeables y trazables
• Delta specs para cambios incrementales
Checklist de Implementacion
• Lista de tareas en orden logico
• Formato checkbox para seguimiento de progreso
• Alcance claro y enfocado por tarea
• Se actualiza a medida que avanza el trabajo
Skills de Diseno Web
Skills consultadas durante la fase de especificacion para features web.
mavelpoint-web-design
Design tokens, tipografia (Matter), colores, espaciado, sombras, animaciones
mavelpoint-web-components
Biblioteca de componentes, patrones, arquitectura (Astro + islas React)
mavelpoint-web-ux
Flujos de usuario, navegacion, rutas de conversion, 10 journeys principales
mavelpoint-web-product
Sitemap, layouts, fuentes de datos, endpoints API, servicios
Skills de Marca y Contenido
Skills que informan el copy, la mensajeria y la identidad visual durante la especificacion.
mavelpoint-brand
Voz, tono, identidad visual, lenguaje nativo de la escena
mavelpoint-tokens
Valores de design tokens, CSS custom properties, config Tailwind
mavelpoint-copy
Framework de copywriting, formulas de titulares, patrones de CTA
mavelpoint-content
Content marketing, estrategia de blog, SEO
mavelpoint-growth
Estrategia de growth, funnels, metricas
mavelpoint-ads
Campanas publicitarias, canales de pago, segmentacion
Fase 4: Implementar
Construir la feature trabajando a traves del checklist de tareas. Los cambios de codigo siguen los artefactos de diseno y especificacion.
openspec-apply-change
La skill principal de implementacion.
• Leer contexto: propuesta, diseno, specs, tareas
• Mostrar progreso actual (N/M tareas completadas)
• Bucle por cada tarea:
→ Anunciar la tarea en progreso
→ Hacer cambios de codigo enfocados
→ Marcar tarea como completada: - [ ] → - [x]
• Gestionar bloqueos: clarificaciones, problemas de diseno, errores
• Actualizar artefactos si surgen problemas de diseno (workflow fluido)
openspec-document
Documentar codigo existente como especificaciones (ingenieria inversa).
• Leer TODOS los archivos fuente antes de escribir specs
• Extraer endpoints de controladores, DTOs, entidades, metodos de repositorio
• Capturar logica de negocio de los use cases
• Verificar precision antes de confirmar
• Solo documentar codigo que EXISTE — nunca inventar
Tech Stack Web
Tecnologias usadas durante la implementacion de features web.
Astro 5 SSR
Contenido estatico via componentes .astro. Cero JS cliente para paginas no interactivas.
React 18 Islands
Componentes interactivos con directivas client:idle, client:visible, client:load.
Tailwind CSS 3.4
Design tokens personalizados. Fuente Matter. Modo oscuro por defecto. Mobile-first.
Nanostores
Estado cross-componente. Player, tabs, navegacion, colecciones persisten entre ViewTransitions.
Headless UI
Dialog, Disclosure, Popover, Listbox. Interacciones accesibles sin estilos.
Framer Motion
Animaciones en islas React. Entrada/salida, scroll triggers, AnimatePresence.
Phosphor Icons
6 variantes de peso: thin, light, regular, bold, fill, duotone.
Keen Slider
Carruseles performantes con soporte tactil. Componente wrapper personalizado.
Fase 5: Verificar
Testear la implementacion y verificar que coincide con las especificaciones antes de desplegar.
openspec-test
Crear tests unitarios siguiendo patrones establecidos.
• Parsear ruta del modulo: contexto/modulo
• Leer unit-testing-guide.md para patrones
• Implementar tests en orden de complejidad:
1. Use cases (mas simples)
2. Repositories (mock PrismaService)
3. Controllers (mock services)
4. Services (mas complejos)
• Objetivo: >90% de cobertura
• Tests rastreados como specs formales de OpenSpec
openspec-verify-change
Verificar que la implementacion coincide con todos los artefactos.
Tres dimensiones de verificacion:
Completitud
Todas las tareas completadas. Todos los requisitos de specs implementados.
Correccion
Evidencia en el codigo mapea a requisitos. Escenarios cubiertos por tests.
Coherencia
Decisiones de diseno seguidas. Convenciones del proyecto respetadas.
Niveles de Prioridad de Incidencias
La verificacion agrupa incidencias en tres niveles de severidad.
Critico
Tareas incompletas, requisitos faltantes. Bloquea el archivo.
Advertencia
Divergencias en specs, escenarios faltantes. Deberia corregirse antes de desplegar.
Sugerencia
Inconsistencias de patrones, mejoras menores. Deseable pero no obligatorio.
Fase 6: Desplegar
Finalizar el cambio, sincronizar especificaciones, archivar el historial de decisiones y desplegar a produccion.
openspec-sync-specs
Sincronizar delta specs con los archivos de especificacion principales.
• Encontrar delta specs en openspec/changes/<nombre>/specs/
• Merge inteligente (no copia simple):
→ Requisitos AGREGADOS: anadir al spec principal
→ MODIFICADOS: aplicar actualizaciones parciales
→ ELIMINADOS: borrar del principal
→ RENOMBRADOS: renombrar en el principal
• Crear nuevos archivos de spec si la capacidad es nueva
• Preservar contenido existente no mencionado en el delta
openspec-archive-change
Archivar el cambio completado y desplegar.
• Verificar completitud de artefactos y tareas
• Opcionalmente sincronizar specs al principal (si no se hizo)
• Mover cambio a openspec/changes/archive/YYYY-MM-DD-<nombre>/
• Mostrar resumen de artefactos archivados
• Historial de decisiones preservado para referencia futura
Infraestructura de Despliegue
Como el codebase web llega a produccion.
Astro SSR en Node
Astro 5.x con adaptador @astrojs/node (modo standalone). Paginas renderizadas en servidor con rutas hibridas estaticas + dinamicas.
Despliegue en Azure
Alojado en infraestructura Azure. Variables de entorno para URLs de API, storage, claves de Gemini y feature flags.
Partytown
Scripts de analitica de terceros (GA, GTM, Meta Pixel, TikTok, Spotify) delegados a web workers.
Sentry
Seguimiento de errores y monitoreo en produccion. Captura errores del lado del cliente y del servidor.
Mapa Completo de Skills
Todas las skills referenciadas a lo largo del workflow, organizadas por categoria.
Skills del Workflow OpenSpec
El ciclo de desarrollo basado en artefactos que impulsa cada cambio.
| Skill | Fase | Proposito |
|---|---|---|
| openspec-explore | Descubrir | Investigar problemas, comparar enfoques |
| openspec-onboard | Descubrir | Aprender el workflow, recorrido guiado |
| openspec-new-change | Planificar | Iniciar nuevo cambio, crear estructura de artefactos |
| openspec-ff-change | Planificar | Fast-forward todos los artefactos de una vez |
| openspec-continue-change | Planificar | Retomar trabajo en cambio existente |
| openspec-apply-change | Implementar | Ejecutar tareas, construir la feature |
| openspec-document | Implementar | Ingenieria inversa de codigo existente a specs |
| openspec-test | Verificar | Crear tests unitarios, objetivo >90% cobertura |
| openspec-verify-change | Verificar | Verificar completitud, correccion, coherencia |
| openspec-sync-specs | Desplegar | Merge de delta specs en los specs principales |
| openspec-archive-change | Desplegar | Archivar cambio completado con historial completo |
Skills de MavelPoint Web
Conocimiento especifico de diseno, componentes y arquitectura web.
| Skill | Usado En | Proposito |
|---|---|---|
| mavelpoint-web-product | Descubrir, Especificar | Sitemap, tech stack, layouts, fuentes de datos, servicios |
| mavelpoint-web-design | Especificar, Implementar | Design tokens, fuente Matter, colores, espaciado, animaciones |
| mavelpoint-web-components | Especificar, Implementar | Biblioteca de componentes, patrones, arquitectura Astro + React |
| mavelpoint-web-ux | Especificar, Implementar | Flujos de usuario, navegacion, rutas de conversion |
Skills de Marca y Estrategia
Conocimiento transversal que informa decisiones en cada fase.
| Skill | Proposito |
|---|---|
| mavelpoint-strategy | Objetivos, prioridades y hoja de ruta 2026 |
| mavelpoint-brand | Voz, tono, identidad visual, lenguaje nativo de la escena |
| mavelpoint-tokens | Valores de design tokens, propiedades CSS, config Tailwind |
| mavelpoint-audiences | Segmentos de usuarios, perfiles de persona, niveles de audiencia |
| mavelpoint-copy | Framework de copywriting, formulas de titulares, patrones CTA |
| mavelpoint-content | Content marketing, estrategia de blog, SEO |
| mavelpoint-growth | Estrategia de growth, funnels, metricas de conversion |
| mavelpoint-ads | Campanas publicitarias, canales de pago, segmentacion |
| mavelpoint-domain | Glosario y vocabulario de la industria de musica electronica |