OpenSpec

Primeros pasos ​

Esta guía explica cómo funciona OpenSpec después de haberlo instalado e inicializado. Para las instrucciones de instalación, consulta el README principal o la Guía de instalación. ¿Es tu primera vez con este conjunto de documentación? El inicio de la documentación te muestra todo lo que hay disponible.

¿Dónde escribo estos comandos? En dos lugares, y mezclarlos es el tropiezo más común al principio.

  • Los comandos openspec ... (como openspec init) se ejecutan en tu terminal.
  • Los comandos /opsx:... (como /opsx:propose) se ejecutan en el chat de tu asistente de IA, en la misma caja donde le pedirías que escriba código.

No hay un "modo interactivo" separado para iniciar. Simplemente escribe el comando con barra diagonal en el chat y tu asistente se encarga del resto. Explicación completa: Cómo funcionan los comandos.

Tus primeros cinco minutos ​

El ciclo completo, con cada paso etiquetado según dónde ocurre:

text
TERMINAL   $ npm install -g @fission-ai/openspec@latest
TERMINAL   $ cd your-project && openspec init
CHAT IA      /opsx:explore                    (opcional: piénsalo primero)
CHAT IA      /opsx:propose add-dark-mode      (la IA redacta el plan; tú lo revisas)
CHAT IA      /opsx:apply                      (la IA lo construye)
CHAT IA      /opsx:archive                    (especificaciones actualizadas, cambio archivado)

Dos pasos en terminal para configurar, y luego trabajas en el chat. El resto de esta guía desglosa qué hace cada paso y qué verás.

¿No quieres hacer la parte de terminal tú mismo? Pega la instrucción de configuración en tu asistente y él gestionará ambas líneas, informándote luego qué ha creado.

¿No estás seguro de qué construir aún? Empieza con /opsx:explore. Es un compañero de pensamiento sin riesgos que lee tu base de código, sopesa opciones y afina una idea vaga hasta convertirla en un plan concreto, todo antes de que exista cualquier artefacto o código. Cuando el panorama está claro, transfiere el trabajo a /opsx:propose. Este es el mejor hábito para trabajar con una IA que, de otro modo, construiría con confianza algo incorrecto. Consulta la guía Explorar.

Cómo funciona ​

OpenSpec ayuda a ti y a tu asistente de codificación con IA a ponerse de acuerdo sobre qué construir antes de escribir cualquier código.

Ruta rápida por defecto (perfil principal):

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (opcional)

Empieza con /opsx:explore cuando estés averiguando qué hacer, o salta directamente a /opsx:propose cuando ya lo sepas. Explore está incluido en el perfil por defecto, así que siempre está disponible cuando lo necesitas.

Ruta ampliada (selección de flujo de trabajo personalizado):

text
/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

El perfil global por defecto es core, que incluye propose, explore, apply, update, sync y archive. Puedes habilitar los comandos del flujo de trabajo ampliado con openspec config profile y luego openspec update.

Qué crea OpenSpec ​

Después de ejecutar openspec init, tu proyecto tiene esta estructura:

openspec/
├── specs/              # Fuente de verdad (el comportamiento de tu sistema)
│   └── <domain>/
│       └── spec.md
├── changes/            # Actualizaciones propuestas (una carpeta por cambio)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Especificaciones delta (lo que está cambiando)
│           └── <domain>/
│               └── spec.md
└── config.yaml         # Configuración del proyecto (opcional)

Dos directorios clave:

  • specs/ - La fuente de verdad. Estas especificaciones describen cómo se comporta tu sistema actualmente. Organizado por dominio (por ejemplo, specs/auth/, specs/payments/).

  • changes/ - Modificaciones propuestas. Cada cambio tiene su propia carpeta con todos los artefactos relacionados. Cuando un cambio está completo, sus especificaciones se fusionan en el directorio principal specs/.

Entendiendo los artefactos ​

Cada carpeta de cambio contiene artefactos que guían el trabajo:

ArtefactoPropósito
proposal.mdEl "por qué" y el "qué" - captura la intención, el alcance y el enfoque
specs/Especificaciones delta que muestran requisitos ADDED/MODIFIED/REMOVED
design.mdEl "cómo" - enfoque técnico y decisiones de arquitectura
tasks.mdLista de comprobación de implementación con casillas de verificación

Los artefactos se construyen unos sobre otros:

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            actualizar a medida que aprendes

Siempre puedes volver atrás y refinar los artefactos anteriores a medida que aprendes más durante la implementación.

Cómo funcionan las especificaciones delta ​

Las especificaciones delta son el concepto clave en OpenSpec. Muestran qué está cambiando en relación con tus especificaciones actuales.

El formato ​

Las especificaciones delta utilizan secciones para indicar el tipo de cambio:

markdown
# Delta para Auth

## Requisitos ADDED

### Requisito: Autenticación de dos factores
El sistema DEBE requerir un segundo factor durante el inicio de sesión.

#### Escenario: Se requiere OTP
- DADO un usuario con 2FA habilitado
- CUANDO el usuario envía credenciales válidas
- ENTONCES se presenta un desafío OTP

## Requisitos MODIFIED

### Requisito: Tiempo de espera de sesión
El sistema EXPIRARÁ las sesiones después de 30 minutos de inactividad.
(Previamente: 60 minutos)

#### Escenario: Tiempo de espera por inactividad
- DADA una sesión autenticada
- CUANDO pasan 30 minutos sin actividad
- ENTONCES la sesión se invalida

## Requisitos REMOVED

### Requisito: Recordarme
(En desuso en favor de 2FA)

Qué sucede al archivar ​

Cuando archivas un cambio:

  1. Los requisitos ADDED se añaden a la especificación principal
  2. Los requisitos MODIFIED reemplazan la versión existente
  3. Los requisitos REMOVED se eliminan de la especificación principal

La carpeta de cambio se mueve a openspec/changes/archive/ para el historial de auditoría.

Ejemplo: Tu primer cambio ​

Recorramos el proceso de añadir modo oscuro a una aplicación.

1. Iniciar el cambio (Por defecto) ​

text
Tú: /opsx:propose add-dark-mode

IA:  Creado openspec/changes/add-dark-mode/
     ✓ proposal.md — por qué hacemos esto, qué está cambiando
     ✓ specs/       — requisitos y escenarios
     ✓ design.md    — enfoque técnico
     ✓ tasks.md     — lista de comprobación de implementación
     ¡Listo para la implementación!

Si has habilitado el perfil de flujo de trabajo ampliado, también puedes hacerlo en dos pasos: /opsx:new seguido de /opsx:ff (o /opsx:continue incrementalmente).

2. Qué se crea ​

proposal.md - Captura la intención:

markdown
# Propuesta: Añadir Modo Oscuro

## Intención
Los usuarios han solicitado una opción de modo oscuro para reducir la fatiga visual
durante el uso nocturno.

## Alcance
- Añadir interruptor de tema en ajustes
- Soporte para detección de preferencia del sistema
- Persistir la preferencia en localStorage

## Enfoque
Usar propiedades personalizadas de CSS para el tema con un contexto de React
para la gestión del estado.

specs/ui/spec.md - Delta que muestra nuevos requisitos:

markdown
# Delta para UI

## Requisitos ADDED

### Requisito: Selección de tema
El sistema PERMITIRÁ a los usuarios elegir entre temas claros y oscuros.

#### Escenario: Interruptor manual
- DADO un usuario en cualquier página
- CUANDO el usuario hace clic en el interruptor de tema
- ENTONCES el tema cambia inmediatamente
- Y la preferencia persiste entre sesiones

#### Escenario: Preferencia del sistema
- DADO un usuario sin preferencia guardada
- CUANDO la aplicación se carga
- ENTONCES se utiliza el esquema de color preferido del sistema

tasks.md - Lista de comprobación de implementación:

markdown
# Tareas

## 1. Infraestructura de Temas
- [ ] 1.1 Crear ThemeContext con estado claro/oscuro
- [ ] 1.2 Añadir propiedades personalizadas de CSS para colores
- [ ] 1.3 Implementar persistencia en localStorage

## 2. Componentes UI
- [ ] 2.1 Crear componente ThemeToggle
- [ ] 2.2 Añadir interruptor a la página de ajustes
- [ ] 2.3 Actualizar Header para incluir interruptor rápido

## 3. Estilos
- [ ] 3.1 Definir paleta de colores del tema oscuro
- [ ] 3.2 Actualizar componentes para usar variables CSS

3. Implementar ​

Tú: /opsx:apply

IA:  Trabajando en las tareas...
     ✓ 1.1 Creado ThemeContext con estado claro/oscuro
     ✓ 1.2 Añadidas propiedades personalizadas de CSS a globals.css
     ✓ 1.3 Implementada persistencia en localStorage
     ✓ 2.1 Creado componente ThemeToggle
     ...
     ¡Todas las tareas completadas!

Durante la implementación, si descubres que el diseño necesita ajustes, simplemente actualiza el artefacto y continúa.

4. Archivar ​

Tú: /opsx:archive

IA:  Archivando add-dark-mode...
     ✓ Especificaciones fusionadas en openspec/specs/ui/spec.md
     ✓ Movido a openspec/changes/archive/2025-01-24-add-dark-mode/
     ¡Hecho! Listo para la siguiente función.

Tus especificaciones delta ahora forman parte de las especificaciones principales, documentando cómo funciona tu sistema.

Verificación y revisión ​

Utiliza la CLI para consultar el estado de tus cambios:

bash
# Listar cambios activos
openspec list

# Ver detalles del cambio
openspec show add-dark-mode

# Validar el formato de las especificaciones
openspec validate add-dark-mode

# Panel de control interactivo
openspec view

Próximos pasos ​