OpenSpec

OpenSpec es un flujo basado en especificaciones para desarrollo asistido por IA. Motoko Base lo usa para que los agentes planifiquen antes de programar — cambios acotados en lugar de diffs aleatorios por el repositorio.

Documentación oficial: openspec.dev

¿Por qué OpenSpec?

OpenSpec separa la planificación (proposal, design, specs, tasks) de la implementación (apply). Revisas el plan antes de que cambie cualquier código de producto.

Estructura de carpetas

openspec/
├── config.yaml              # Project context + rules for AI artifacts
├── specs/                   # Durable requirements (main specs)
│   └── <capability>/
│       └── spec.md
└── changes/
    ├── <active-change>/     # Work in progress
    │   ├── .openspec.yaml
    │   ├── proposal.md
    │   ├── design.md
    │   ├── tasks.md
    │   └── specs/<capability>/spec.md   # delta spec
    └── archive/
        └── <date>-<change-name>/        # completed changes

Las main specs (openspec/specs/) son memoria de producto a largo plazo — lo que el starter debe hacer por capacidad (links, billing, storage, etc.).

Los changes (openspec/changes/) son planes de corta duración para un resultado. Tras archive, los requisitos duraderos se fusionan en las main specs.

Las reglas de IA específicas del proyecto viven en openspec/config.yaml (filosofía, stack, restricciones de arquitectura, reglas por artefacto).

Crear una proposal

Usa el slash command de Cursor o pide al agente que ejecute el skill de propose:

/opsx-propose Add a bookmarks demo with user ownership

Esto crea openspec/changes/<name>/ y genera:

Solo planificación — no hay código de producto hasta que ejecutes apply.

Para pensar sin planificar: /opsx-explore. Para revisar tras el feedback: /opsx-update.

Design

design.md registra las decisiones de arquitectura del change:

• Qué patrones existentes reutilizar (src/features/links/ como plantilla CRUD)
• Schema, rutas y puntos de contacto en archivos
• Trade-offs y non-goals a nivel de diseño

Los agentes leen proposal.md + el codebase existente antes de escribir el design. Manténlo corto — preferir reutilizar patrones del starter a inventar capas nuevas.

Tasks

tasks.md es una lista de checkboxes que el agente sigue durante apply:

- [ ] 1.1 Add schema in src/lib/db/schema/...
- [ ] 2.1 Create queries.ts with ownership filters
- [ ] 3.1 Wire dashboard route and nav item

Las tareas deben ser pequeñas, ordenadas (schema → server → UI → wiring) y nombrar rutas de archivo concretas cuando se conozcan.

Apply

Cuando el plan esté bien:

/opsx-apply

El agente:

1. Lee proposal.md, delta specs, design.md y tasks.md
2. Implementa cada tarea sin marcar
3. Marca las tareas - [x] al completarlas
4. Se detiene si el alcance no está claro o el spec necesita actualización

Puedes ejecutar apply en varias sesiones — el progreso se rastrea en tasks.md.

Archive

Cuando todas las tareas estén hechas y hayas revisado el código:

/opsx-archive

Archive:

1. Opcionalmente sincroniza las delta specs en openspec/specs/<capability>/spec.md
2. Mueve la carpeta del change a openspec/changes/archive/<date>-<name>/

Las main specs pasan a ser la fuente de verdad para futuras sesiones de IA sobre esa capacidad.

Comandos CLI útiles

openspec list                      # active changes
openspec status --change <name>    # artifact progress
openspec validate <name>           # check a change
openspec view                      # browse specs and changes

Instalación: OpenSpec installation

Comandos de Cursor

Los skills viven en .agents/skills/openspec-* y .cursor/skills/openspec-*.

Flujo de desarrollo con IA — Flujo de extremo a extremo de la idea a la revisión.

Cursor / AI Agents — AGENTS.md y consejos de prompting.