williamsnieves/landing-factory

Implementar tareas de un cambio de OpenSpec.

Selección de almacén: Si el usuario nombra un almacén (un almacén es un repositorio OpenSpec independiente registrado en esta máquina) o el trabajo reside en uno, ejecuta openspec store list --json para descubrir los ids de almacenes registrados, luego pasa --store <id> en los comandos que leen o escriben especificaciones y cambios (new change, status, instructions, list, show, validate, archive, doctor, context, schemas, view). Una vez seleccionado, trata --store <id> como persistente para el resto del flujo de trabajo. Cada ejemplo sin ámbito de esos comandos a continuación es una abreviatura: antes de ejecutarlo, añade la bandera. Por ejemplo, ejecuta openspec status --change "<name>" --json --store "<id>", no la forma sin ámbito mostrada a continuación. Otros comandos no toman la bandera. Las pistas impresas por los comandos ya llevan la bandera; mantenla en los seguimientos. Sin un almacén, los comandos actúan sobre la raíz local openspec/ más cercana.

Verificación del proyecto: Estos pasos esperan un proyecto que ya usa OpenSpec. Antes del primer paso que escriba algo (new change, archive, sync specs o la creación de un archivo de artefacto), confirma que el proyecto tenga una raíz: ejecuta openspec list --json (con --store <id> cuando se haya seleccionado un almacén, ya que el almacén es entonces la raíz) y lee root. Un objeto root significa que el proyecto está configurado. "root": null significa que no lo está; no hay un directorio openspec/ aquí, y una escritura como openspec new change lo crearía como efecto secundario. El comando también sale con código distinto de cero, lo cual es esa respuesta en lugar de un CLI roto, así que lee el JSON en lugar de reintentar o sortearlo.

Un "root": null no se trata de configuración: cuando un mensaje de error de status comienza con Declared in o Invalid store declaration in y nombra el openspec/config.yaml (o config.yml) de este proyecto, el proyecto sí usa OpenSpec a través de un almacén que declara, pero esta máquina no puede resolverlo (el almacén no está registrado, o la línea store: está mal formada). No lo trates como no inicializado y no te saltes las ramas siguientes: detente antes de escribir y muéstrale al usuario el message y el fix de ese error.

De lo contrario, sin raíz, lo que sucede a continuación depende de cómo se llegó a este flujo de trabajo:

• Seleccionado automáticamente: elegiste este flujo de trabajo por ti mismo, sin que el usuario nombre OpenSpec, nombre este skill, o ejecute su comando de barra. Deja de usar OpenSpec y responde la solicitud normalmente, como lo harías sin OpenSpec instalado. No le pidas que configure nada y no menciones la configuración de OpenSpec.
• Solicitud explícita de OpenSpec: el usuario nombró OpenSpec, nombró este skill, o ejecutó su comando de barra. Detente antes de escribir y pregunta cómo proceder: configurar este proyecto (openspec init), apuntar a un almacén que ya tenga (--store <id>), o continuar sin OpenSpec para esta solicitud. Espera su respuesta.

En ambas ramas, nunca crees la raíz como efecto secundario: no ejecutes openspec init hasta que el usuario lo pida, no crees archivos openspec/ manualmente, y no dejes que un comando la cree.

Entrada: Opcionalmente especifica un nombre de cambio (ej., /opsx:apply add-auth). Si se omite, verifica si se puede inferir del contexto de la conversación. Si es vago o ambiguo, DEBES solicitar los cambios disponibles.

Pasos

1. Seleccionar el cambio

   Si se proporciona un nombre, úsalo. De lo contrario:

   • Inferir del contexto de la conversación si el usuario mencionó un cambio
   • Auto-seleccionar si solo existe un cambio activo
   • Si es ambiguo, ejecuta openspec list --json para obtener los cambios disponibles y pide al usuario que seleccione uno

   Siempre anuncia: "Usando cambio: " y cómo sobrescribir (ej., /opsx:apply <other>).

2. Verificar el estado para entender el esquema

   openspec status --change "<name>" --json
   

   Analiza el JSON para entender:

   • schemaName: El flujo de trabajo que se está usando (ej., "spec-driven")
   • planningHome, changeRoot, y actionContext: alcance de planificación y restricciones de edición
   • Qué artefacto contiene las tareas (típicamente "tasks" para spec-driven, verifica el estado para otros)

3. Obtener instrucciones de aplicar

   openspec instructions apply --change "<name>" --json
   

   Esto devuelve:

   • contextFiles: ID del artefacto -> array de rutas de archivo concretas (varía según el esquema: puede ser propuesta/especificaciones/diseño/tareas o especificación/pruebas/implementación/documentos)
   • Progreso (total, completado, restante)
   • Lista de tareas con estado, ruta de origen y línea de origen
   • Instrucción dinámica basada en el estado actual
   • Opcional context: entrada de instrucción actual requerida del proyecto desde la raíz seleccionada
   • Opcional operationGuidance: guía de asesoramiento actual para aplicar
   • missingArtifacts (cuando está presente): ids de artefactos requeridos sin salida

   Manejar estados:

   • Si state: "blocked": muestra el mensaje y pausa la implementación.
     • Si missingArtifacts no está vacío: sugiere completar los artefactos faltantes. Ejecuta openspec status --change "<name>" --json, selecciona el siguiente artefacto ready (no skipped o blocked), y usa openspec instructions "<artifact-id>" --change "<name>" --json para sus reglas y plantilla. Mantén el --store <id> seleccionado en ambos comandos.
     • De lo contrario, sigue la instrucción del CLI para crear o reparar el archivo de seguimiento configurado en el esquema a partir de los artefactos de planificación existentes. No asumas que otro artefacto está listo ni inicies la implementación mientras esté bloqueado.
   • Si state: "all_done": informa que todas las tareas rastreadas están completas y sugiere revisión o verificación según corresponda antes de archivar
   • De lo contrario: procede a la implementación

   Trata context como una entrada requerida a nivel de prompt. Léelo y considéralo, y aplica hechos, convenciones y restricciones relevantes del proyecto mientras implementas. Trata operationGuidance como consejo adicional opcional. Lee y considera cada entrada, y sigue las entradas que sean aplicables y compatibles con el flujo de trabajo incorporado.

   Mantén ambos campos separados del estado devuelto por el CLI, artefactos faltantes, tareas, progreso, contextFiles y la instruction incorporada. No son evidencia de finalización de tareas, no reemplazan la instrucción incorporada y no permiten omitir un estado bloqueado. Si el contexto entra en conflicto con la instrucción incorporada, una elección explícita del usuario o un valor controlado por el CLI, informa el conflicto y preserva el valor controlador. Si la guía no es aplicable o entra en conflicto con esas entradas controladoras, no la sigas y explica por qué. Estos son contratos de comportamiento a nivel de prompt, no verificaciones exigibles.

4. Leer archivos de contexto

   Lee cada ruta de archivo listada bajo contextFiles de la salida de instrucciones de aplicar. Los archivos dependen del esquema que se esté usando:

   • spec-driven: propuesta, especificaciones, diseño, tareas
   • Otros esquemas: sigue el contextFiles de la salida del CLI

   No copies context o operationGuidation textualmente en archivos de implementación o artefactos de planificación a menos que el usuario lo solicite por separado.

5. Mostrar el progreso actual

   Muestra:

   • Esquema que se está usando
   • Progreso: "N/M tareas completadas"
   • Resumen de tareas restantes
   • Instrucción dinámica del CLI

6. Implementar tareas (bucle hasta terminar o estar bloqueado)

   Para cada tarea pendiente:

   • Muestra en qué tarea se está trabajando
   • Realiza los cambios de código requeridos
   • Mantén los cambios mínimos y enfocados
   • Antes de editar, confirma que la casilla de verificación en la sourcePath y line devueltas aún coincida con la descripción de la tarea; si no es así, vuelve a ejecutar las instrucciones de aplicar y usa la ubicación actualizada
   • Marca la tarea como completada en su sourcePath y line devueltas: - [ ] → - [x]
   • Vuelve a ejecutar las instrucciones de aplicar y confirma que esa tarea ahora está realizada y el progreso cambió
   • Continúa con la siguiente tarea

   Pausa si:

   • La tarea no está clara → pide aclaración
   • La implementación revela un problema de diseño → sugiere actualizar artefactos
   • Una tarea necesita trabajo más allá de lo que describen la especificación y las tareas, o te ves tentado a eliminar, reducir, aplazar o aceptar excepciones al comportamiento especificado para que encaje → saca a relucir el alcance adicional y pregunta; no lo absorbas en silencio
   • Error o bloqueador encontrado → informa y espera orientación
   • El usuario interrumpe

7. Al completar o pausar, mostrar estado

   Muestra:

   • Tareas completadas en esta sesión
   • Progreso general: "N/M tareas completadas"
   • Si todo está hecho: informa que las tareas rastreadas están completas y sugiere revisión o verificación según corresponda antes de archivar
   • Si está en pausa: explica por qué y espera orientación

Salida Durante la Implementación

## Implementando: <change-name> (esquema: <schema-name>)

Trabajando en tarea 3/7: <task description>
[...implementación en curso...]
✓ Tarea completada

Trabajando en tarea 4/7: <task description>
[...implementación en curso...]
✓ Tarea completada

Salida al Completar

## Implementación Completa

**Cambio:** <change-name>
**Esquema:** <schema-name>
**Progreso:** 7/7 tareas completadas ✓

### Completado en Esta Sesión
- [x] Tarea 1
- [x] Tarea 2
...

Todas las tareas rastreadas están completas. Revisa o verifica el cambio según
corresponda antes de archivar. Puedes archivar este cambio con `/opsx:archive`.

Salida en Pausa (Problema Encontrado)

## Implementación en Pausa

**Cambio:** <change-name>
**Esquema:** <schema-name>
**Progreso:** 4/7 tareas completadas

### Problema Encontrado
<description del problema>

**Opciones:**
1. <opción 1>
2. <opción 2>
3. Otro enfoque

¿Qué te gustaría hacer?

Barreras de Seguridad

• Continúa con las tareas hasta terminar o estar bloqueado
• Siempre lee los archivos de contexto antes de comenzar (de la salida de instrucciones de aplicar)
• Si la tarea es ambigua, pausa y pregunta antes de implementar
• Si la implementación revela problemas, pausa y sugiere actualizaciones de artefactos
• Mantén los cambios de código mínimos y centrados en cada tarea
• Actualiza la casilla de verificación de la tarea inmediatamente después de completar cada tarea
• Pausa en errores, bloqueadores o requisitos poco claros; no adivines
• Cuando una tarea necesita trabajo más allá de lo que describe la especificación, saca a relucir el alcance adicional y pausa; nunca reduzcas, aplaces ni simplifiques en silencio el comportamiento especificado
• Solo marca una tarea - [x] cuando su comportamiento especificado esté completamente implementado, no cuando esté parcialmente hecho o aplazado
• Usa contextFiles de la salida del CLI, no asumas nombres de archivo específicos
• Usa sourcePath y line de cada tarea para actualizar su casilla de verificación exacta
• No uses el contexto ni la guía de operación como prueba de que una tarea está completa
• Aplica el contexto del proyecto relevante; informa conflictos con las entradas controladoras del flujo de trabajo
• Considera cada entrada de guía; explica cualquier consejo inaplicable o conflictivo
• No copies el contexto de ejecución ni la guía de operación en archivos de implementación o artefactos de planificación
• Preserva el comportamiento controlado por el CLI de bloqueado/listo/completado y los criterios de finalización

Integración de Flujo de Trabajo Fluido

Este skill admite el modelo de "acciones sobre un cambio":

• Se puede invocar en cualquier momento: Antes de que todos los artefactos estén hechos (si existen tareas), después de implementación parcial, intercalado con otras acciones
• Permite actualizaciones de artefactos: Si la implementación revela problemas de diseño, sugiere actualizar artefactos; no está bloqueado por fases, trabaja de forma fluida