← Volver al listado de tecnologías ← Índice de Organic Driven Development (ODD)

Instalar y operar

5 de noviembre de 2026 Por: Artiko

oddgentle-aiinstalacionclioperacion

Instalar y operar

Objetivos

Instalar Gentle AI y confirmar que ODD llegó a tu agente.
Usar sync después de actualizar el binario.
Conocer los comandos de operación relacionados con ODD.

ODD no se instala por separado: forma parte de la guía de enrutamiento que Gentle AI proyecta en cada agente. Los comandos de este capítulo provienen de la documentación del proyecto y se contrastaron con el enrutador de comandos del código. Los flags evolucionan, de modo que ante cualquier diferencia manda gentle-ai --help en tu versión.

Requisitos

Requisito	Detalle
Git	En todas las plataformas
Node.js 18+ y npm	`gentle-ai install` los comprueba y muestra una indicación si faltan
Go 1.25.10+	Para compilar desde el código, y obligatorio en Windows
Un agente instalado	Gentle AI no instala tu agente. Hermes, por ejemplo, solo se detecta
Pi en `PATH`	Solo si seleccionas ese agente

Instalar el binario

# macOS (Homebrew)
brew install gentleman-programming/tap/gentle-ai

# macOS y Linux (curl)
curl -fsSL https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.sh | bash

En Windows se instala desde el código, porque los binarios oficiales están temporalmente no disponibles mientras se provisiona la firma Authenticode:

go install github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-[email protected]

Nota sobre la documentación. El README usa v4.1.1 en este comando y la guía de inicio menciona v4.0.0, mientras que la última versión publicada en la fecha del curso es v4.3.1. Consulta la página de versiones. Además, las notas de v4.1.0 advierten que esa versión falla la comprobación de checksum con go install, y remiten a v4.1.1.

go install no cambia tu PATH: el binario queda en $(go env GOBIN) o en $(go env GOPATH)/bin, normalmente ~/go/bin. La ruta del módulo incluye /v4, y la antigua /v3 nunca llega a la versión 4.

Como con cualquier script de instalación que se ejecuta desde internet, conviene leerlo antes.

Configurar tus agentes

# Ecosistema completo para varios agentes
gentle-ai install --agent claude-code,opencode,gemini-cli --preset full-gentleman

# Configuración mínima para Cursor
gentle-ai install --agent cursor --preset minimal

# Selección manual de componentes y skills
gentle-ai install --agent claude-code \
  --component engram,skills,context7,persona,permissions \
  --skill go-testing,skill-creator,branch-pr,issue-creation \
  --persona gentleman

# Vista previa sin aplicar cambios
gentle-ai install --dry-run --agent claude-code,opencode --preset full-gentleman

Preset	ID	Incluye
Dev Stack + Polish	`full-gentleman`	Todos los componentes y skills
Dev Stack	`ecosystem-only`	Engram, Skills, Context7, GGA y todos los skills
Memory Only	`minimal`	Solo Engram
Custom	`custom`	Eliges componentes y skills de forma manual

La persona se selecciona aparte y se aplica de forma independiente del preset.

El instalador también ofrece una interfaz interactiva. Antes de la confirmación final, el instalador personalizable explica RDD y te pide elegir RDD ON o RDD OFF. Si no hay preferencia global se sugiere ON, y un OFF global explícito se mantiene.

Para Pi el comando es gentle-ai install --agent pi. Su plan muestra la pila de paquetes de Pi:

pi install npm:gentle-pi
pi install npm:gentle-engram
pi install npm:pi-web-access
pi install npm:pi-btw

El componente permissions agrega una lista de rutas sensibles denegadas en Claude Code y OpenCode, por ejemplo ~/.ssh/* y **/.env*.

Comprobar que ODD llegó

flowchart LR
    A["gentle-ai doctor<br/>diagnóstico de solo lectura"] --> B["Abrir el archivo gestionado<br/>de tu agente"]
    B --> C["Buscar ## Implementation Routing"]
    C --> D["Probar un pedido pequeño"]

gentle-ai doctor no cambia nada, incluidos los permisos de los archivos. Para comprobar que el modo de revisión es el que esperas:

gentle-ai review mode status --cwd .

Después, prueba de comportamiento: pide algo pequeño y comprueba que el agente no crea ningún documento. Pide algo que claramente no se pueda retomar desde el diff y comprueba que crea odd/tasks/<feature-name>.md antes de escribir código, avisándote en una línea. Si el modelo no cumple, recuerda lo que advierte la documentación: las pruebas establecen la entrega de las instrucciones, no el cumplimiento.

Mantener la guía actualizada

Hay dos cosas distintas que actualizar:

Qué	Comando	Efecto
El binario	`gentle-ai update`	Comprueba si hay una versión nueva
El binario	`gentle-ai upgrade`	Descarga y reemplaza el binario
La guía instalada	`gentle-ai sync --dry-run`	Vista previa del alcance
La guía instalada	`gentle-ai sync`	Refresca los recursos gestionados
La guía de ciertos agentes	`gentle-ai sync --agent claude-code --agent opencode`	Selecciona agentes específicos

flowchart TD
    A["gentle-ai update"] --> B{"¿Hay versión nueva?"}
    B -->|"Sí"| C["gentle-ai upgrade"]
    C --> D["gentle-ai sync --dry-run"]
    D --> E["gentle-ai sync"]
    E --> F["gentle-ai doctor"]
    B -->|"No"| F

El paso más fácil de olvidar es sync: actualizar el binario no cambia lo que ya está instalado en tus agentes. sync actúa sobre los agentes registrados como instalados, salvo que selecciones otros, y su refresco es idempotente.

Comandos de operación

Comando	Uso
`gentle-ai doctor`	Diagnóstico de solo lectura
`gentle-ai skill-registry refresh`	Refresca el catálogo de skills. `--force` ignora la caché, `--cwd` y `--quiet` están disponibles
`gentle-ai codegraph init --cwd <repo>`	Crea el índice de CodeGraph. Es una acción del parent
`gentle-ai review mode status --cwd <repo>`	Estado del interruptor de RDD
`gentle-ai review assess --cwd <repo> --json`	Evaluación de riesgo de solo lectura
`gentle-ai uninstall --agent cursor --component skills --yes`	Desinstalación selectiva
`gentle-ai uninstall --all`	Desinstalación completa

La desinstalación elimina la configuración gestionada, no los datos del usuario sin relación ni paquetes externos. Conviene revisar su alcance antes de confirmar. Un --strict-tdd en sync se rechaza, porque esa opción se retiró.

Archivos que el agente crea en tu repositorio

Ruta	Contenido
`odd/tasks/<feature-name>.md`	Documentos de feature de tareas grandes
`.atl/skill-registry.md`	Catálogo de skills del proyecto, cuando existe

Conviene decidir con tu equipo si odd/tasks/ se versiona. El repositorio de Gentle AI sí lo hace, y por eso este curso puede citar documentos reales.

Recomendaciones de endurecimiento

La guía de inicio recomienda estos ajustes para los paquetes npm que instalas por tu cuenta:

npm config set ignore-scripts true
npm config set min-release-age 3
npm config set allow-git none

Gentle AI ya fija versiones y desactiva los scripts de postinstalación en cada instalación npm que genera.

Actividad

Si decides instalarlo en un proyecto de prueba, sigue esta secuencia y anota el resultado de cada paso:

Ejecuta el instalador con --dry-run y revisa el plan.
Instala para un solo agente.
Ejecuta gentle-ai doctor.
Busca el bloque de enrutamiento en la configuración de tu agente.
Haz un pedido de solo lectura, uno pequeño y uno grande, y compara con el caso guiado.

Autoevaluación

¿Cómo se instala ODD?
- A. Con gentle-ai install --component odd
- B. Como parte de la guía de enrutamiento que proyecta Gentle AI
- C. Con un paquete npm separado
- D. Solo mediante la interfaz gráfica
Actualizaste el binario. ¿Qué falta para refrescar la guía de tus agentes?
- A. Reinstalar el agente
- B. Nada, se actualiza sola
- C. Borrar odd/tasks/
- D. Ejecutar gentle-ai sync
¿Qué hace gentle-ai doctor?
- A. Un diagnóstico de solo lectura
- B. Repara la configuración
- C. Reinstala los skills
- D. Activa RDD
¿Qué elimina la desinstalación?
- A. Todos los datos del usuario
- B. Los agentes instalados
- C. La configuración gestionada, no datos no relacionados ni paquetes externos
- D. El historial de Git

Respuestas

B. docs/components.md dice que no es un componente aparte.
D. sync refresca los recursos gestionados.
A. “Read-only, changes nothing.”
C. Según docs/intended-usage.md.

Lista de control

Instalé el binario por una vía documentada.
Sé diferenciar actualizar el binario de refrescar la guía.
Comprobé el bloque de enrutamiento en mi agente.
Decidí si versiono odd/tasks/.

Fuentes

README.md, docs/quickstart.md, docs/usage.md, docs/intended-usage.md, docs/pi.md, docs/components.md, internal/app/app.go, internal/cli/codegraph.go, notas de v4.1.0.