AI-SDLC CLI prerequisites

Install openspec and specify before any Spec Kit or OpenSpec work.

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: asegúrate 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.

Referencias

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