AI-SDLC CLI prerequisites

Install OpenSpec and Spec Kit for agent workflows (DOC-014).

Source: docs/development/DOC-014-ai-sdlc-cli-prerequisites.md

DOC-014: AI-SDLC CLI prerequisites (OpenSpec + Spec Kit)

Estado

Approved (seed)

Por qué

Esta semilla requiere las CLIs de OpenSpec y GitHub Spec Kit (specify). Sin ellas no se puede operar el flujo híbrido (DOC-013).

Los agentes MUST validar con make doctor al iniciar sesión. Si falta alguna CLI, MUST detenerse y mostrar estas instrucciones.

Verificación rápida

make doctor
command -v openspec && openspec --version
command -v specify && specify --version

Ambos comandos deben resolver en el PATH.

1. OpenSpec CLI

Requisito: Node.js ≥ 20.19.

node --version   # v20.19+
npm install -g @fission-ai/openspec@latest
openspec --version

Alternativas: pnpm add -g @fission-ai/openspec@latest · yarn global add @fission-ai/openspec@latest · bun add -g @fission-ai/openspec@latest.

Si openspec no se encuentra tras instalar: añadí el bin global de npm al PATH (npm bin -g).

Docs: https://github.com/Fission-AI/OpenSpec/blob/main/docs/installation.md

2. Spec Kit (specify)

Requisito: uv en el PATH.

# Instalar uv (macOS/Linux) si aún no está:
curl -LsSf https://astral.sh/uv/install.sh | sh

uv tool install specify-cli
specify --version

Pin a un release (opcional):

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.11.6

Si specify no se encuentra: asegurate de que ~/.local/bin (o el path de uv tool) esté en el PATH.

Docs: https://github.com/github/spec-kit · https://github.github.io/spec-kit/

3. Tras instalar

make doctor          # debe salir 0
# En el agente:
/init-session

No hace falta re-inicializar Spec Kit/OpenSpec en un clone de esta semilla: .specify/ y openspec/ ya vienen en el repo.

4. Spec Kit agent-context y PyYAML

Tras /speckit.plan (o /speckit.agent-context.update), el script .specify/extensions/agent-context/scripts/bash/update-agent-context.sh actualiza los bloques <!-- SPECKIT START/END --> en las anclas de contexto.

Ese script necesita Python 3 + PyYAML. PyYAML viene con el venv de specify-cli (uv tool), no con el python3 del sistema.

La semilla resuelve el intérprete en este orden:

  1. SPECKIT_PYTHON (si está definida)
  2. python3 / python en el PATH (si import yaml funciona)
  3. python / python3 en el mismo directorio que el binario real de specify

make doctor reporta agent-context Python (PyYAML) cuando la resolución funciona.

Si el script salta el update

Síntoma típico:

agent-context: Python 3 with PyYAML not found; skipping update.

Opciones:

# A) Asegurar specify en PATH (recomendado; discovery automático)
command -v specify && make doctor

# B) Apuntar al python del venv de specify-cli
export SPECKIT_PYTHON="$(dirname "$(readlink "$(command -v specify)" || command -v specify)")/python"
# (ajustar si `specify` no es symlink; en macOS puede hacer falta seguir el link a mano)

# C) Instalar PyYAML en el python3 del sistema (fallback)
python3 -m pip install pyyaml

No editar a mano los bloques SPECKIT: volver a correr el script o el comando speckit.agent-context.update.

Codex desktop y PATH

Una app abierta desde macOS puede tener un PATH distinto al terminal donde usás Cursor. Si doctor no encuentra Node, uv, openspec o specify, comprobar primero las instalaciones existentes (~/.local/bin, nvm o Homebrew). No reinstalar ni re-inicializar el repo por un PATH incompleto.

Ejemplo para una instalación existente con nvm + uv (solo modifica el entorno de ese shell):

export PATH="$HOME/.local/bin:$PATH"
export NVM_DIR="$HOME/.nvm"
if [ -s "$NVM_DIR/nvm.sh" ]; then
  . "$NVM_DIR/nvm.sh" --no-use
  nvm use default
fi
make doctor

Si OpenSpec está instalado en otra versión de Node, usar esa versión existente compatible (Node ≥ 20.19). Para Homebrew, añadir su bin real al PATH. No fijar rutas de otro usuario o versiones de este Mac en archivos compartidos.

Los comandos del agente pueden correr en shells distintos: conservar los directorios resueltos en cada ejecución posterior. Repetir make doctor dentro del entorno efectivo de Codex; un resultado exitoso en otra terminal no verifica esta sesión. Para persistencia personal, configurar la inicialización del shell que usa el cliente y reiniciarlo; este repo no modifica dotfiles globales.

Guía de flujo: agents/codex.md. Solo si las CLIs realmente faltan, instalar con los pasos anteriores.

Referencias

  • DOC-011 — guía local
  • DOC-013 — Spec Kit vs OpenSpec
  • ADR-016 — make doctor
  • Extensión: .specify/extensions/agent-context/README.md