Project Begin

Skill: /project-begin

Cuándo usar este skill: Usar como primer paso del pipeline de ProjectSpecFactory, cuando el usuario quiera iniciar un nuevo proyecto, capturar la intención inicial o generar el artefacto project-intent.md. Invocar también cuando el usuario mencione "comenzar proyecto", "iniciar proyecto", "capturar intención", "project-begin" o equivalentes.

Objetivo

Orquesta el estado Begin Intention del pipeline de ProjectSpecFactory: conduce una entrevista estructurada con el usuario a través del agente project-pm para capturar y refinar la intención del proyecto, produciendo $SPECS_BASE/specs/01-projects/<PROJ-ID>-<nombre>/project-intent.md en una sola sesión.

Qué hace este skill:

• Verifica el entorno y la regla WIP=1 antes de iniciar
• Resuelve o crea el directorio del proyecto activo
• Delega la entrevista de dos fases (captura + refinamiento) al agente project-pm
• Confirma la existencia del documento generado al finalizar

Qué NO hace este skill:

• No genera el documento directamente — esa responsabilidad es del agente project-pm
• No avanza al siguiente estado del pipeline (project-discovery)

Entrada

• No se requiere input explícito — el skill inicia una entrevista interactiva
• $SPECS_BASE/specs/templates/project-intent-template.md — fuente de verdad estructural del documento de salida (solo lectura); si no existe, el seed assets/project-intent-template.md del skill
• $SPECS_BASE/specs/01-projects/ — directorio donde se detectan proyectos activos (WIP=1)

Parámetros

• Ninguno — el skill opera de forma completamente interactiva mediante el agente project-pm

Precondiciones

• El entorno debe superar el preflight (skill-preflight) sin errores
• project-intent-template.md debe existir, sea el central en $SPECS_BASE/specs/templates/ o el seed assets/project-intent-template.md
• No debe existir ningún proyecto con substatus: IN-PROGRESS en $SPECS_BASE/specs/01-projects/ (regla WIP=1), salvo que el usuario elija retomar o sobrescribir el activo

Dependencias

• Skills: [skill-preflight]
• Agentes: [project-pm]
• Archivos: [$SPECS_BASE/specs/templates/project-intent-template.md, assets/project-intent-template.md (seed)]

Modos de ejecución

• Manual (/project-begin): siempre interactivo — conduce la entrevista con el usuario.
• Retoma: si existe un project-intent.md con substatus: IN-PROGRESS, el agente project-pm continúa solo las secciones incompletas sin reiniciar desde cero.

Restricciones / Reglas

• WIP=1: solo puede haber un proyecto activo (substatus: IN-PROGRESS) a la vez; si ya existe uno, el skill ofrece Retomar o Sobrescribir antes de continuar.
• Template de solo lectura: assets/project-intent-template.md nunca se modifica ni se usa como ruta de salida.
• Extracción dinámica: las secciones del documento se derivan en runtime del template; si el template cambia, el output se actualiza automáticamente.
• Sin avance automático: el skill no invoca project-discovery — el usuario decide cuándo continuar.
• NO modifique ningún archivo existente en el código fuente (estamos en etapa de inicial, no de implementación)
• NO genere código; estas iniciando la especificación, no implementando los artefactos técnicos
• Encoding: All generated .md files MUST be saved as UTF-8 without BOM. Do not use Latin-1, CP-1252, or any other encoding. If you see characters like ó or 📖, that indicates an encoding error — fix it.

Flujo de ejecución

Paso 0 — Verificar entorno (skill-preflight)

Invocar skill-preflight. Si retorna ✗ Entorno inválido, detener la ejecución. Usar $SPECS_BASE en todas las rutas siguientes.

Paso 0b — Resolver o crear directorio del proyecto (PROJ_DIR)

Antes de iniciar la entrevista, determinar el directorio del proyecto activo:

1. Listar todos los subdirectorios de $SPECS_BASE/specs/01-projects/.
2. Para cada subdirectorio encontrado, leer project-intent.md y verificar si substatus es IN-PROGRESS.
3. Si se encuentra exactamente uno con substatus: IN-PROGRESS → usar ese directorio como $PROJ_DIR. Ejemplo: PROJ-01-mi-proyecto.
4. Si no se encuentra ninguno → $PROJ_DIR se determinará durante la entrevista (ver Paso 4): el project-pm derivará el ID desde el título del proyecto (formato PROJ-NN-nombre-kebab) y lo confirmará con el usuario antes de crear el directorio.
5. Si se encuentran varios con substatus: IN-PROGRESS → mostrar la lista y pedir al usuario que elija uno antes de continuar.

La ruta completa del proyecto será: $SPECS_BASE/specs/01-projects/$PROJ_DIR/

Paso 1 — Verificar WIP=1

Antes de iniciar, escanea $SPECS_BASE/specs/01-projects/ y detecta si existe algún subdirectorio con project-intent.md que tenga substatus: IN-PROGRESS.

• Si no existe ningun documento en substatus IN-PROGRESS: continua al Paso 2.
• Si existe al menos uno en substatus IN-PROGRESS: notifica el conflicto WIP=1 e indica que ya hay un proyecto activo. Muestra cual documento esta en substatus IN-PROGRESS y ofrece solo estas opciones:
  • Sobrescribir: iniciar de cero y continuar con el flujo normal.
  • Retomar: continuar el proyecto activo aplicando flujo de retoma sobre el documento en substatus IN-PROGRESS.

Si el usuario elige retomar, activa el flujo de retoma del Paso 4 sin reiniciar desde cero.

Paso 2 — Verificar estado del documento de output

Lee $SPECS_BASE/specs/01-projects/$PROJ_DIR/project-intent.md (si existe) y detecta el valor de **Estado**:.

• Si el archivo no existe: continua al Paso 3 (primera ejecucion).
• Si existe con substatus: IN-PROGRESS: activa flujo de retoma y continua al Paso 3.
• Si existe con substatus: DONE: informa que el documento ya esta completo y pide confirmacion antes de sobrescribir.
  • Si el usuario confirma sobrescribir: continua al Paso 3.
  • Si el usuario cancela: deten la ejecucion sin modificar el archivo.

Paso 3 — Verificar que el template existe

El archivo de plantilla es la única fuente de información estructural para generar el output. Define qué secciones existen, en qué orden y con qué propósito. Nunca codifique directamente los nombres o la estructura de las secciones en esta habilidad; siempre derívelos de la plantilla en tiempo de ejecución. Si la plantilla cambia, el output generado se actualizará automáticamente.

El archivo de plantilla es de solo lectura. Nunca escriba en él, lo modifique ni lo use como ruta de salida.

Lee el archivo de plantilla $SPECS_BASE/specs/templates/project-intent-template.md (fuente de verdad del proyecto, puede contener personalizaciones).

• Si el archivo central no existe: usar el seed assets/project-intent-template.md y emitir:

  ⚠️ Usando template seed del skill. Ejecuta sddf-init para centralizarlo en $SPECS_BASE/specs/templates/.

• Si tampoco existe el seed: informar al usuario y detener la ejecución:

  ❌ Template project-intent-template.md no encontrado. Ejecuta sddf-init.

• Si alguno de los dos existe: continua.

Guardar la ruta del template efectivamente resuelto (central o seed) como $TEMPLATE_PATH: es la que se le pasa al project-pm en el Paso 4. El agente no debe reconstruir la ruta por su cuenta — hacerlo lo acoplaría a una plataforma de instalación concreta (.claude/, .agents/ o .github/).

Paso 4 — Delegar al project-pm

Invoca al agente project-pm con la siguiente instrucción, sustituyendo $SPECS_BASE, $PROJ_DIR y $TEMPLATE_PATH por los valores ya resueltos (el agente no los resuelve por su cuenta):

Lee el template en $TEMPLATE_PATH. Extrae las secciones del template en runtime.

Si estas en flujo de retoma (documento existente en Estado: IN-PROGRESS), primero lee $SPECS_BASE/specs/01-projects/$PROJ_DIR/project-intent.md, identifica secciones incompletas con placeholders como [...] o valores sin reemplazar, y continua solo con esas secciones. No vuelvas a preguntar ni sobrescribas secciones ya completas.

Conduce la entrevista de intencion de proyecto con el usuario en dos fases dentro de la misma sesion:

Fase 1 — Captura de intención: Pregunta al usuario por la idea general del proyecto (qué quiere construir, para quién, qué problema resuelve). Usa máx 3-4 preguntas abiertas para entender el contexto.

Fase 2 — Refinamiento: A partir de las respuestas de la Fase 1, profundiza sección por sección del template (máx 3-4 preguntas por ronda). Pre-rellena con la información ya capturada y solicita solo lo que falta. Infiere el contenido faltante marcándolo con [inferido].

Escribe el resultado completo en $SPECS_BASE/specs/01-projects/$PROJ_DIR/project-intent.md. Si no puedes obtener respuesta del usuario, aplica tu Protocolo de Resiliencia: degrada a inferencia, marca con [inferido: sin respuesta del usuario] y lista las inferencias al final.

El project-pm se encargará de:

• Capturar la intención inicial del proyecto en la Fase 1
• Refinar y completar todas las secciones del template en la Fase 2
• Inferir contenido faltante marcándolo con [inferido]
• Escribir el documento final con metadatos de generación

Paso 5 — Confirmar output

Cuando el project-pm termine:

1. Verifica que $SPECS_BASE/specs/01-projects/$PROJ_DIR/project-intent.md existe leyendo el archivo
2. Si existe, confirma al usuario:

   ✅ Documento generado correctamente. Path: $SPECS_BASE/specs/01-projects/$PROJ_DIR/project-intent.md Siguiente comando: /project-discovery.

3. Si no existe, informa al usuario que algo salió mal y sugiere ejecutar /project-begin nuevamente.

Salida

• $SPECS_BASE/specs/01-projects/<PROJ-ID>-<nombre>/project-intent.md — documento de intención del proyecto generado por project-pm, con substatus: DONE al completarse.