robsonprod/portfolio

Implementa tareas a partir de un cambio de OpenSpec.

Selección de tienda: Si el usuario nombra una tienda (una tienda es un repositorio independiente de OpenSpec registrado en esta máquina) o el trabajo reside en una, ejecuta openspec store list --json para descubrir los IDs de tiendas registradas, 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 seleccionada, trata --store <id> como persistente para el resto del flujo de trabajo. Cada ejemplo no calificado de esos comandos a continuación es una abreviatura: antes de ejecutarlo, añade la bandera. Por ejemplo, ejecuta openspec status --change "<nombre>" --json --store "<id>", no la forma no calificada que se muestra. Otros comandos no aceptan la bandera. Las pistas impresas por los comandos ya incluyen la bandera; mantenla en las acciones posteriores. Sin una tienda, los comandos actúan sobre la raíz openspec/ local más cercana.

Verificación del proyecto: Estos pasos asumen 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 una tienda, ya que la tienda 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 termina con código distinto de cero, lo cual es esa respuesta y no un CLI roto, así que lee el JSON en lugar de reintentar o evitarlo.

Un caso de "root": null no es sobre configuración: cuando un mensaje de error de status comienza con Declared in o Invalid store declaration in y nombra openspec/config.yaml (o config.yml) de este proyecto, el proyecto sí usa OpenSpec a través de una tienda que declara, pero esta máquina no puede resolverla (la tienda no está registrada o la línea store: está mal formada). No lo trates como no inicializado y no omitas las ramas a continuación: detente antes de escribir y muéstrale al usuario el message y 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:

• Selección automática: elegiste este flujo de trabajo tú mismo, sin que el usuario nombre OpenSpec, nombre este skill o ejecute su comando de barra. Deja de usar OpenSpec y responde a la solicitud normalmente, como lo harías sin OpenSpec instalado. No le pidas que configure nada ni 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 una tienda 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 los 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 pídele al usuario que seleccione uno

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

2. Verificar el estado para entender el esquema

   openspec status --change "<nombre>" --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 aplicación

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

   Esto devuelve:

   • contextFiles: ID del artefacto -> arreglo de rutas de archivo concretas (varía según el esquema: puede ser propuesta/especificaciones/diseño/tareas o espec/pruebas/implementación/documentación)
   • 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
   • context opcional: entrada de instrucción de proyecto requerida actual de la raíz seleccionada
   • operationGuidance opcional: 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 "<nombre>" --json, selecciona el siguiente artefacto ready (no skipped o blocked), y usa openspec instructions "<id-artefacto>" --change "<nombre>" --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 artefactos de planificación existentes. No asumas que otro artefacto está listo ni comiences 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: continúa con la implementación.

   Trata context como una entrada de nivel de instrucción requerida. Léela y considérala, 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 eludir un estado bloqueado. Si context entra en conflicto con la instrucción incorporada, una elección explícita del usuario o un valor controlado por el CLI, reporta el conflicto y preserva el valor controlador. Si la guía es inaplicable o entra en conflicto con esas entradas controladoras, no la sigas y explica por qué. Estos son contratos de comportamiento a nivel de instrucción, no verificaciones exigibles.

4. Leer archivos de contexto

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

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

   No copies context u operationGuidance 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 bloquearse)

   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 el sourcePath y line devueltos aún coincida con la descripción de la tarea; si no es así, vuelve a ejecutar las instrucciones de aplicación y usa la ubicación actualizada
   • Marca la tarea como completada en su sourcePath y line devueltos: - [ ] → - [x]
   • Vuelve a ejecutar las instrucciones de aplicación y confirma que esa tarea ahora está hecha y el progreso cambió
   • Continúa con la siguiente tarea

   Pausar 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 sientes tentado a omitir, reducir, aplazar o aceptar excepciones al comportamiento especificado para que encaje → saca a la superficie el alcance adicional y pregunta; no lo absorbas en silencio
   • Error o bloqueador encontrado → reporta y espera instrucciones
   • 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 instrucciones

Salida Durante la Implementación

## Implementando: <nombre-cambio> (esquema: <nombre-esquema>)

Trabajando en tarea 3/7: <descripción de la tarea>
[...implementación en curso...]
✓ Tarea completada

Trabajando en tarea 4/7: <descripción de la tarea>
[...implementación en curso...]
✓ Tarea completada

Salida al Completar

## Implementación Completa

**Cambio:** <nombre-cambio>
**Esquema:** <nombre-esquema>
**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 al Pausar (Problema Encontrado)

## Implementación en Pausa

**Cambio:** <nombre-cambio>
**Esquema:** <nombre-esquema>
**Progreso:** 4/7 tareas completadas

### Problema Encontrado
<descripción del problema>

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

¿Qué te gustaría hacer?

Guardarraíles

• Continúa con las tareas hasta terminar o bloquearse
• Siempre lee los archivos de contexto antes de comenzar (de la salida de instrucciones de aplicación)
• Si la tarea es ambigua, pausa y pregunta antes de implementar
• Si la implementación revela problemas, pausa y sugiere actualizar artefactos
• Mantén los cambios de código mínimos y enfocados 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 necesite trabajo más allá de lo que describe la especificación, saca a la superficie el alcance adicional y pausa; nunca omitas, aplazes o simplifiques en silencio el comportamiento especificado
• Solo marca una tarea como - [x] cuando su comportamiento especificado esté completamente implementado, no cuando esté parcialmente hecho o aplazado
• Usa los archivos de contexto de la salida del CLI, no asumas nombres de archivo específicos
• Usa la ruta de origen y la línea de cada tarea para actualizar su casilla de verificación exacta
• No uses el contexto o la guía de operación como prueba de que una tarea está completa
• Aplica el contexto relevante del proyecto; reporta 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 o 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/todo-hecho y los criterios de finalización

Integración de Flujo de Trabajo Fluido

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

• Se puede invocar en cualquier momento: Antes de que todos los artefactos estén listos (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 manera fluida