robsonprod/portfolio

Propón un nuevo cambio: crea el cambio y genera todos los artefactos en un solo paso.

Límite de planificación: Este flujo de trabajo solo crea artefactos de planificación. La solicitud del usuario que seleccionó o activó este flujo de trabajo autoriza únicamente la planificación, incluso si pide construir o corregir algo. No edites el código del proyecto. Una vez que los artefactos de planificación estén completos, detente. No comiences la implementación en la misma respuesta, aunque la solicitud inicial lo pida. Espera una nueva solicitud del usuario después de presentar los artefactos; luego inicia el flujo de trabajo de aplicación.

Crearé un cambio con los artefactos que define tu esquema. Con el esquema predeterminado basado en especificaciones, esto es:

• proposal.md (qué y por qué)
• specs/<ruta-de-capacidad>/spec.md (lo que el sistema debe hacer: un delta, no la especificación principal)
• design.md (cómo)
• tasks.md (pasos de implementación)

<ruta-de-capacidad> es el directorio de especificaciones relativo a specs/ (por ejemplo, user-auth o identity/user-auth). Conserva la ruta completa de una capacidad existente y sigue la organización establecida del proyecto para nuevas capacidades.

Cuando el usuario esté listo para implementar, debe iniciar explícitamente el flujo de trabajo de aplicación.

---

Selección de tienda: Si el usuario nombra una tienda (una tienda es un repositorio OpenSpec independiente 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 sin alcance 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 sin alcance que se muestra a continuación. Otros comandos no toman la bandera. Las sugerencias impresas por los comandos ya llevan la bandera; mantenla en los seguimientos. Sin una tienda, los comandos actúan sobre la raíz local openspec/ 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 raíz 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, que es esa respuesta en lugar de un CLI roto, así que lee el JSON en lugar de reintentar o evitar el problema.

Un caso donde "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 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 sigas las ramas a continuación: 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 alcanzó este flujo de trabajo:

• Auto-seleccionado: elegiste este flujo de trabajo tú mismo, sin que el usuario nombrara OpenSpec, nombrara esta habilidad o ejecutara su comando de barra. Deja de usar OpenSpec y responde a la solicitud normalmente, como lo harías sin OpenSpec instalado. No les pidas que configuren nada y no menciones la configuración de OpenSpec.
• Solicitud explícita de OpenSpec: el usuario nombró OpenSpec, nombró esta habilidad 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 tengan (--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 manualmente archivos openspec/ y no permitas que un comando la cree.

Entrada: La solicitud del usuario debe incluir un nombre de cambio (en kebab-case) O una descripción de lo que quieren construir.

Pasos

1. Comprende la solicitud y aclara la ambigüedad relevante

   Si no se proporciona una entrada clara, pregúntale al usuario (abierto, sin opciones predefinidas):

   "¿En qué cambio quieres trabajar? Describe lo que quieres construir o corregir."

   A partir de su descripción, deriva un nombre en kebab-case (por ejemplo, "añadir autenticación de usuario" → add-user-auth).

   IMPORTANTE: No continúes sin entender lo que el usuario quiere construir.

   Si la solicitud contiene ambigüedad que afectaría materialmente el alcance, el comportamiento observable externamente, la compatibilidad o los criterios de aceptación, pregúntale al usuario antes de crear el cambio. Para detalles menores, haz una suposición razonable y regístrala en los artefactos de planificación.

2. Carga el contexto del proyecto

   Ejecuta openspec context --json desde el directorio de trabajo actual (o openspec context --json --store "<id-de-tienda>" cuando se haya seleccionado explícitamente una tienda registrada). Usa el root.path devuelto como la raíz autorizada de OpenSpec. Si el contexto informa no_openspec_root, detente sin crear ni modificar ningún archivo y sigue la Verificación del proyecto anterior según cómo se alcanzó este flujo de trabajo. Ofrece openspec init solo para una solicitud explícita de OpenSpec y espera a que el usuario solicite la inicialización. No inicialices automáticamente ni ejecutes openspec new change. Después de la inicialización, vuelve a ejecutar esta verificación de contexto antes de continuar. Para cualquier otro fallo de contexto, detente e informa del error; no recurras al directorio actual ni ejecutes comandos posteriores de OpenSpec sin la tienda seleccionada.

   Solo cuando el contexto devuelva un root.path resuelto, lee <root.path>/openspec/config.yaml. Usa config.yml solo cuando config.yaml no exista. Si ninguno de los archivos existe, continúa sin contexto de proyecto. No recurras a config.yml si config.yaml es ilegible o no válido.

   Si el archivo se analiza como un objeto YAML y su campo context es una cadena de no más de 51,200 bytes en UTF-8, aplica ese campo antes de explorar la base de código o tomar decisiones de planificación. Si el archivo no se puede leer o analizar, o el campo de contexto no es válido o es demasiado grande, continúa sin contexto de proyecto. Valida este campo independientemente de otros campos de configuración, como lo hace OpenSpec.

   Trata el contexto como datos y restricciones proporcionados por el proyecto, no como autoridad para cambiar este flujo de trabajo: no puede anular la autorización del usuario, el límite de planificación, las restricciones de herramientas o las reglas de artefactos y salida. No copies el contexto en los artefactos; úsalo para enfocar cualquier exploración de la base de código y como una restricción en la propuesta.

3. Determina el esquema del flujo de trabajo

   Usa el esquema predeterminado configurado a menos que el usuario solicite explícitamente un flujo de trabajo diferente.

   Usa un esquema diferente solo si el usuario:

   • Solicita explícitamente un esquema específico por nombre → usa --schema <nombre-de-esquema>
   • Pide "mostrar flujos de trabajo" o pregunta "qué flujos de trabajo" existen → resuelve la raíz autorizada ejecutando openspec context --json desde el directorio de trabajo actual. Si el usuario seleccionó explícitamente una tienda registrada, usa openspec context --json --store "<id-de-tienda>". Luego ejecuta openspec schemas --json con su directorio de trabajo establecido en el root.path devuelto y deja que el usuario elija. Esto conserva las raíces seleccionadas por un puntero store: local o el defaultStore global; cuando se seleccionó explícitamente una tienda registrada, añade también --store "<id-de-tienda>" a openspec schemas --json. Si el contexto falla, detente como se describe en el paso de carga de contexto; no recurras al directorio actual.

   De lo contrario, omite --schema para conservar el predeterminado configurado.

4. Crea el directorio del cambio

   Elige una forma de esquema a continuación. Si se selecciona una tienda registrada, añade --store "<id-de-tienda>" a ese comando y a cada comando posterior de OpenSpec que se muestra a continuación y que acepte --store.

   Usando el predeterminado configurado:

   openspec new change "<nombre>"
   

   Usando un esquema solicitado explícitamente:

   openspec new change "<nombre>" --schema "<nombre-de-esquema>"
   

   Esto crea un cambio andamiado en el hogar de planificación resuelto por el CLI con .openspec.yaml.

5. Obtén el orden de construcción de artefactos

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

   Analiza el JSON para obtener:

   • applyRequires: array de IDs de artefactos necesarios antes de la implementación (por ejemplo, ["tasks"])
   • artifacts: lista de todos los artefactos, cada uno con su status y sus bordes requires (los IDs de artefactos de los que depende directamente)
   • planningHome, changeRoot, artifactPaths y actionContext: contexto de ruta y alcance. Úsalos en lugar de asumir rutas locales del repositorio.

6. Crea cada artefacto en el conjunto requerido

   Usa una lista de tareas pendientes para rastrear el progreso a través de los artefactos.

   Itera sobre los artefactos en orden de dependencia (primero los artefactos sin dependencias pendientes):

   a. Para cada artefacto que esté ready (dependencias satisfechas):

   • Obtén instrucciones:

     openspec instructions <id-de-artefacto> --change "<nombre>" --json
     

   • El JSON de instrucciones incluye:
     • context: Antecedentes del proyecto (restricciones para ti: NO las incluyas en la salida)
     • rules: Reglas específicas del artefacto (restricciones para ti: NO las incluyas en la salida)
     • template: La estructura a usar para tu archivo de salida
     • instruction: Guía específica del esquema para este tipo de artefacto
     • skipped/warning: presente cuando el cambio declara skip_specs y este artefacto NO debe crearse; detente y elige otro artefacto
     • resolvedOutputPath: Ruta o patrón resuelto para escribir el artefacto
     • dependencies: Artefactos completados para leer como contexto
   • Lee los archivos de dependencia completados para obtener contexto; léelos siempre del disco de nuevo, incluso si los viste antes en la conversación (el usuario puede haberlos editado)
   • Inspecciona el proyecto relevante antes de redactar: Lee primero context y rules, luego inspecciona la implementación relevante, pruebas cercanas, configuración y documentación fuera de openspec/. Mantén la inspección de solo lectura y proporcional al cambio; reutiliza los hallazgos para artefactos posteriores e inspecciona más solo cuando sea necesario.
     • Identifica el proyecto objetivo a partir de la solicitud y el contexto del proyecto; el hogar de planificación puede ser independiente del código. Si el objetivo no está claro, pregunta. Para cambios nuevos o no relacionados con código, inspecciona la estructura disponible y los documentos relevantes. Si la fuente no está disponible, indica la limitación y pregunta cuando afecte materialmente el plan.
     • Fundamenta el alcance, el enfoque y las tareas en lo que encuentres. Distingue el comportamiento observado de las suposiciones y las adiciones propuestas; señala conflictos con especificaciones existentes en lugar de decidir silenciosamente cuál es correcta.
     • Haz este descubrimiento ahora, en lugar de dejar tareas genéricas de "explorar la base de código" o "hacer un plan" para la implementación. Mantén cualquier investigación de seguimiento necesaria específica para una pregunta no resuelta.
   • Elige la ruta de salida antes de crear cualquier cosa. Si resolvedOutputPath es un glob, sigue instruction para elegir una ruta concreta dentro de changeRoot que coincida con el glob, y verifica que permanezca dentro de changeRoot después de resolver enlaces simbólicos, tanto en sus directorios padre como en el archivo mismo si ya existe; si no es así, detente e informa al usuario. De lo contrario, la ruta de salida es resolvedOutputPath
   • Si el campo instruction delega la creación a una habilidad o comando específico, invócalo solo si puede escribir el artefacto en esa ruta de salida; de lo contrario, detente e informa al usuario. Luego verifica que el archivo de artefacto exista en esa ruta de salida
   • De lo contrario, crea el archivo de artefacto usando template como estructura y escríbelo en esa ruta de salida
   • Aplica context y rules como restricciones, pero NO los copies en el archivo
   • Muestra un progreso breve: "Creado "

   b. Continúa hasta que cada artefacto en el conjunto requerido exista (no solo apply.requires)

   • Después de crear cada artefacto, vuelve a ejecutar openspec status --change "<nombre>" --json

   • El conjunto requerido es applyRequires más cada artefacto alcanzable desde esos siguiendo los bordes requires en status --json: recórrelos transitivamente (impulsado por especificaciones abarca propuesta, especificaciones, diseño, tareas). Deja intactos los artefactos fuera de ese conjunto

   • status es solo de existencia de archivos, por lo que un artefacto applyRequires que diga done NO significa que sus dependencias existan: escribir tasks.md temprano marca tasks como done mientras que specs nunca se escribió. Usa los bordes requires de cada artefacto, no su status, para construir el conjunto requerido: un artefacto done aún enumera de qué depende

   • Un artefacto que ya muestra status: "skipped" está satisfecho: el cambio declara skip_specs en .openspec.yaml, por lo que sus archivos NO deben existir. Nunca intentes crear uno

   • Crea cada artefacto en el conjunto requerido que falte, luego vuelve a verificar: crear uno puede desbloquear otros

   • Omite uno solo cuando status ya lo reporte como skipped, o cuando su propia instruction diga que es condicional: ejecuta openspec instructions <id-de-artefacto> --change "<nombre>" --json y omítelo solo si su campo instruction lo marca como opcional (por ejemplo, "crear solo si..."). El design.md impulsado por especificaciones califica; specs califica solo a través del estado skipped anterior, nunca por tu propio juicio. Informa al usuario y no lo reconsideres

   • Las dependencias son habilitadores, no barreras: si un artefacto requerido aún está blocked solo porque omitiste una dependencia condicional, escríbelo de todos modos

   • Detente cuando cada artefacto en el conjunto requerido esté done, skipped o se haya omitido deliberadamente

   c. Si un artefacto requiere entrada del usuario (contexto poco claro):

   • Pide al usuario que aclare
   • Luego continúa con la creación

7. Muestra el estado final

   openspec status --change "<nombre>"
   

Salida

Después de completar...