Solucionar una instalación

Recorre primero esta tabla — la mayoría de los reportes encajan en una de estas seis filas.

Síntoma	Solución
No hay `/flow` después de `npm i`	Ejecuta `npx @manhquy/flow-skill@latest`. Debes ejecutar el CLI; instalar el paquete solo no copia nada a un skill home.
Skill viejo después de una «reinstalación»	Usa siempre `@latest` para el skill v0.34.4 (instalador 0.7.11). Un nombre de paquete sin tag puede servirse desde la caché de npx.
Claude o Codex no lista el skill	Reinicia por completo el agente una vez después de la primera instalación.
`flow.sh: No such file` en PowerShell	Llama a `…/runner/flow.cmd`, no a `bash`.
`durable layer DISABLED`	Instala `python3`, o ignóralo — los gates mecánicos siguen funcionando.
CRLF o «bad interpreter»	El repo impone LF vía `.gitattributes`; re-clona si los finales de línea se dañaron.

Empieza con doctor

bash ~/.claude/skills/flow/runner/flow.sh doctor

doctor comprueba bash, python, grep y git e informa las rutas de instalación que ve. Un resultado READY significa que el entorno está bien y el problema está en otro lado — normalmente el agente no se reinició.

«Lo instalé pero no hay /flow»

Dos causas distintas, en orden de probabilidad.

Instalaste el paquete en lugar de ejecutarlo. npm i @manhquy/flow-skill añade un paquete a una carpeta node_modules. No copia el árbol del skill a ningún lugar donde mire un agente. El instalador es un CLI que ejecutas:

npx @manhquy/flow-skill@latest

No reiniciaste el agente. Los agentes enumeran su directorio de skills al arrancar. Claude Code necesita un reinicio; Codex necesita un reinicio y luego $flow en lugar de /flow; Cursor y Antigravity necesitan recargar la herramienta o el IDE.

Confirma que los archivos realmente aterrizaron:

ls ~/.claude/skills/flow/SKILL.md

«Instaló una versión vieja»

Comprueba lo que realmente tienes, desde la máquina en lugar de desde cualquier documento:

npx @manhquy/flow-skill@latest --help
# --help imprime ambos números: instalador CLI, luego el producto skill que trae

grep -E '^\s*version:' ~/.claude/skills/flow/SKILL.md | head -1

Si la versión del skill instalado está por detrás de la que reporta --help, el paso de copia no llegó a ese home — re-ejecuta el instalador y selecciona el agente explícitamente.

Dos errores de pinning causan la mayoría de las instalaciones obsoletas:

Fijar la versión del producto skill en npm. Ese número no es una versión de paquete publicada. Fija la versión del instalador CLI, o usa @latest para el skill actual.
Usar el tag @rc. Está retirado y obsoleto.

Si npm dice No matching version found, fijaste el número del producto skill. Usa @latest o fija el instalador. Los dos números y por qué difieren están en Dos números de versión.

Windows: PowerShell resuelve el bash equivocado

En PowerShell o cmd — incluyendo dentro de Codex — un bash solo suele resolver a WSL en C:\WINDOWS\system32\bash.exe. WSL no puede leer rutas C:/... ni /c/..., así que falla con No such file or directory y el harness parece roto cuando no lo está.

Usa el lanzador, que encuentra Git Bash y le pasa una ruta que acepta:

& "$env:USERPROFILE\.codex\skills\flow\runner\flow.cmd" status

Solo llama a bash flow.sh directamente una vez que hayas confirmado que bash es Git Bash.

«durable layer DISABLED»

Esto es un modo degradado, no un fallo. La capa durable es un almacén Python más SQLite para registros de intake, story, trace, decision y backlog. Sin python3 los gates mecánicos y cada comprobación de stage y card siguen funcionando — pierdes la memoria entre sesiones, así que /flow recall tiene menos que leer de vuelta. Instala python3 para reactivarla.

Aún atascado

Reúne tres cosas antes de pedir ayuda: la salida completa de doctor, los dos números de versión que imprime --help, y el comando exacto con su texto de error. Abre un issue en github.com/manhquydev/flow-skill.

Rutas alternativas de instalación

El instalador npm, npx @manhquy/flow-skill@latest, es el camino recomendado para el skill v0.34.4. Las alternativas existen para contribuidores y máquinas air-gapped.

Desde un checkout de git:

bash install.sh global          # o: pwsh install.ps1 global  en Windows
bash install.sh project [dir]   # skill Claude local al proyecto

bash install.sh global sincroniza cada home de agente detectado y ejecuta el paso de doctor. bash install.sh project [dir] instala un skill Claude local al proyecto. En Windows usa pwsh install.ps1 global, ya que un bash solo en PowerShell suele ser WSL y no puede leer rutas de Windows.

Claude Code también puede añadir el repositorio como plugin marketplace e instalar flow@flow-marketplace.

El camino totalmente manual es copiar skills/flow/ a ~/.claude/skills/flow/ y hacer runner/flow.sh ejecutable. Cada canal escribe el mismo árbol, así que un proyecto puede cambiar entre ellos sin reemitir ningún gate ni card.

Comandos y notas de plataforma: README.md

Flags del instalador CLI

npx @manhquy/flow-skill@latest

Requiere Node.js 22.14 o superior. Incluye siempre @latest (trae el skill v0.34.4) — un npx @manhquy/flow-skill solo puede servirse desde la caché de npx y re-ejecutar una copia vieja.

Copia estos; no parafrasees el significado de los flags. --project aplica solo a claude.

npx @manhquy/flow-skill@latest --yes
npx @manhquy/flow-skill@latest --yes --target claude
npx @manhquy/flow-skill@latest --yes -t claude -t codex
npx @manhquy/flow-skill@latest --yes --all
npx @manhquy/flow-skill@latest --yes --project --dir .
npx @manhquy/flow-skill@latest --yes --all --dry-run --json

Flag	Significado
`-y`, `--yes`	Saltar prompts; instalar selección por defecto (detectados + Claude)
`-t`, `--target <name>`	Objetivo (repetible o separado por comas)
`--all`	Todos los objetivos, aunque no se detecten
`--project`	Alcance de proyecto — solo Claude → `<dir>/.claude/skills/flow`
`--dir <path>`	Directorio del proyecto (implica `--project`; por defecto: cwd)
`--json`	Eventos JSONL (`plan`, `install:*`, `summary`)
`--dry-run`	Imprimir plan; no escribir
`-h`, `--help`	Ayuda. `--help` imprime ambos números de versión.

--project soporta solo claude. Otros objetivos con --project salen con 2.

Haz	No hagas
`npx @manhquy/flow-skill@latest`	`npx @manhquy/flow-skill` solo (caché de npx obsoleta)
Ejecuta el CLI para copiar el skill	Solo `npm i` (paquete; sin archivos del skill en los homes del agente)
Fija el instalador `@0.7.11` si lo necesitas	Fija npm `@0.34.4` (versión del skill ≠ versión del paquete)
Prefiere `@latest`	`@rc` (retirado / atrasado)

Paquete: @manhquy/flow-skill en npm. Los significados de los flags se mantienen con el instalador: npm-wrapper/README.md.

Rutas de instalación

El instalador copia el mismo árbol del skill a cada home de agente que selecciones. Nada se comparte entre homes — cada uno es una copia completa.

Por agente

Agente	Ruta	Invocación
Claude Code	`~/.claude/skills/flow` (o `.claude/skills/flow` local al proyecto)	`/flow`
Codex CLI	`~/.codex/skills/flow`	`$flow` — reinicia Codex después de instalar
Agents home	`~/.agents/skills/flow`	específico del host
Antigravity	`~/.gemini/antigravity-cli/skills/flow` (CLI) y `~/.gemini/config/skills/flow` (IDE)	`/flow` después de recargar
Cursor	`~/.cursor/skills/flow`	panel de agent skills después de recargar

Antigravity tiene dos homes porque el CLI y el IDE leen directorios distintos. Es el mismo bundle SKILL.md en ambos; ejecuta agy inspect para confirmar que se descubrió.

Qué hay dentro de un skill home

Ruta	Contenido
`SKILL.md`	Entrada de la capa semántica: dispatch, gatekeeping, orquestación. Lleva `metadata.version`.
`runner/flow.sh`	El motor mecánico. `runner/flow.cmd` es el lanzador de Windows.
`harness/`	La capa durable (Python más SQLite).
`law/`	Ley de sesión de construcción `CLAUDE.md`, ley de UI `DESIGN.md`, `RETRO.md`.
`references/`	Los playbooks semánticos: reglas de gate, concierge, tipos de proyecto, mapeo de agentes y más.
`_templates/`	Los artefactos con gates que el runner copia a un proyecto. Nunca editar durante una ejecución.
`playbooks/`	Conocimiento de stack — leer antes de construir sobre ese stack, cosechar después.

A dónde van los archivos del proyecto

El skill home guarda el harness. Tu proyecto guarda el trabajo, bajo el directorio desde el que ejecutas:

flow/00-idea.md .. 05-contract.md   artefactos de planificación, con gates
cards/C-NNN.md                      unidades de envío
MODE, PROJECT_TYPE                  modo de autoría y tipo de proyecto
RETRO.md, DEBT.md, AUTO-LOG.md      libros
DESIGN.md                           ley de UI del proyecto
.flow/harness.db                    registros durables

Sobrescribe la raíz del proyecto con FLOW_PROJECT_ROOT. Ejecutar desde un subdirectorio que no tiene su propio flow/ adopta el proyecto flow ancestro más cercano e imprime una nota a stderr, en lugar de crear una segunda raíz fragmentada.

Base de conocimiento entre proyectos

/flow promote <playbook.md> copia un playbook a ~/.claude/flow/playbooks, donde /flow recall lo muestra en cada proyecto en lugar de solo en el que vino.

Dependencias de runtime

Dependencia	Necesaria para
`bash`	El motor mecánico. En Windows esto significa Git Bash — usa `runner/flow.cmd`.
`python3`	Recomendado. Alimenta el harness durable. Sin él, los gates siguen funcionando y la capa SQLite se desactiva.
`git`	Opcional. Necesario para worktrees y `/flow auto`.
Node.js ≥ 22.14	Solo el instalador npm, no el skill en runtime.

Verificar un home

grep -E '^\s*version:' ~/.claude/skills/flow/SKILL.md | head -1
bash ~/.claude/skills/flow/runner/flow.sh doctor

Variables de entorno

El runner lee varias variables FLOW_*. Estas son las documentadas para uso diario; el conjunto completo está definido en el código del runner.

Variable	Efecto
`FLOW_PROJECT_ROOT`	Sobrescribe la raíz del proyecto en lugar de confiar en el recorrido de directorios.
`FLOW_SESSION_ID`	Un identificador de sesión estable. Expórtalo una vez por sesión y pásalo en cada llamada para obtener protección dura de concurrencia en lugar de una advertencia.
`FLOW_LOCK_TTL`	Segundos antes de que un `flow/.lock` se auto-reclame. Por defecto 900.
`FLOW_FORCE`	Ponlo a `1` para tomar un candado que estás seguro de que está muerto.
`FLOW_LOG_DISABLE` / `DO_NOT_TRACK`	Desactiva el log JSONL local de uso que `/flow usage` acumula. El log es local de todos modos.
`FLOW_EVAL_RETRY_BACKOFF`	Backoff de reintento en segundos para el batch facturable de eval. Por defecto 5; pon 0 en tests.

Sin FLOW_SESSION_ID el runner no puede probar que una sesión competidora es distinta, así que advierte en lugar de bloquear — por eso exportarlo importa en una máquina compartida.

Definiciones autoritativas: skills/flow/runner/flow.sh

Dos números de versión

flow publica dos números de versión, y no coinciden. Es intencional, no deriva. --help imprime ambos números. Compruébalos en tu propia máquina en lugar de en cualquier documento.

Qué	Qué versiona
Producto skill	Los gates, `SKILL.md`, el runner, las referencias y las plantillas — lo que juzga tu construcción. Vive en los metadatos de `SKILL.md`.
Instalador npm	El CLI `@manhquy/flow-skill` que copia el skill a tus homes de agente. Vive en el paquete npm.

npx @manhquy/flow-skill@latest --help
# flow-skill v0.7.11 (ships skill v0.34.4)

grep -E '^\s*version:' ~/.claude/skills/flow/SKILL.md | head -1

Por qué dos números

Versionan artefactos distintos con ritmos de cambio distintos.

  monorepo skills/flow/  --npm run sync-->  npm-wrapper/skills/flow  --npm pack-->  registry
         |                                         |
         | install.sh / agent skill homes          | npx @manhquy/flow-skill@latest
         v                                         v
  ~/.claude/skills/flow                     mismo árbol vía instalador CLI

El producto skill es el harness mismo. Su versión impulsa la comprobación de coherencia y el campo de telemetría registrado en la capa durable, para que un proyecto siempre pueda decir bajo qué semántica de gates se construyó. Cambia cada vez que cambia un gate, un stage o un playbook de referencia — que es a menudo.

El paquete npm versiona solo el instalador CLI: detección de agentes, el multi-select interactivo, dónde se copian los archivos, los flags. Esa superficie es pequeña y estable. Publicar una nueva versión del instalador porque cambió una regla de gate sería mentir sobre qué cambió, y obligaría a los usuarios a razonar sobre un número que no les dice nada.

Colapsar los dos significaría o bien subir el instalador por cada cambio de gate o bien congelar las versiones de gates al ritmo de release del instalador. Ambas son peores que explicar una tabla.

El error que esto causa, y cómo evitarlo

El modo de fallo es fijar el número equivocado. La versión del producto skill no es una versión de paquete npm publicada. Fija el instalador CLI si necesitas un release fijo. Mejor para casi todos: @latest.

# Mal — fijar la versión del producto skill (no es una versión de paquete npm)
# Bien — fijar la versión del instalador CLI, o usar @latest para el skill actual
npx @manhquy/flow-skill@latest

Ahora mismo el skill más nuevo está en @latest (0.7.11 trae el skill 0.34.4). Un npx @manhquy/flow-skill solo puede servirse desde la caché de npx y re-ejecutar en silencio una copia vieja. El tag @rc está retirado; no lo uses.

Si npm reporta No matching version found, casi seguro fijaste el número del producto skill. --help imprime ambos números; fija el del instalador.

Qué número te importa

Si usas flow, la versión del producto skill es la que describe tu experiencia — te dice qué gates y qué comandos tienes. La versión del instalador solo importa cuando depuras una instalación o fijas una build.

Si reportas un problema, da ambos. --help los imprime juntos en una línea, que es para lo que existe esa línea.

Comprobar deriva dentro de un proyecto

/flow coherence

Esto marca deriva de versiones entre campos de versión declarados — el trozo barato documento-versus-código de la retícula de deriva. Es asesor: marca, nunca auto-arregla.

Instalar y primera ejecución · Registro de cambios