Inicio rápido

Esta guía te lleva de cero a usar AI Framework en tu proyecto: instalar el plugin, configurar tu entorno y ejecutar tu primer comando.

Antes de empezar: lee Por qué AI Framework para entender qué hace el framework.

---

Requisitos

• Claude Code CLI
• Git
• Python 3.8+ — requerido por los hooks del plugin
• Node.js 18+ — requerido por agent-browser (auto-instalación vía npm/brew)
• GitHub CLI (opcional, para /pull-request y comandos git)

---

Instalación

Primera vez

# Agregar marketplace
/plugin marketplace add Dario-Arcos/ai-framework-marketplace

# Instalar plugin
/plugin install ai-framework@ai-framework-marketplace

Actualizar (manual)

# Solo necesario si NO habilitaste auto-update
/plugin marketplace update ai-framework-marketplace
/plugin update ai-framework@ai-framework-marketplace

Reinstalar limpio

/plugin marketplace remove ai-framework-marketplace
/plugin marketplace add Dario-Arcos/ai-framework-marketplace
/plugin install ai-framework@ai-framework-marketplace

---

Habilitar actualización automática

Altamente recomendado

Los plugins de terceros no se actualizan automáticamente por defecto. Sin este paso, tendrás que ejecutar /plugin marketplace update + /plugin update manualmente cada vez que haya una nueva versión. Habilitar auto-update te asegura tener siempre la última versión sin intervención.

Paso a paso:

1. Ejecuta /plugin en Claude Code
2. Selecciona la pestaña Marketplaces
3. Selecciona ai-framework-marketplace
4. Selecciona Enable auto-update

Una vez habilitado, Claude Code sincroniza el marketplace y actualiza el plugin automáticamente al inicio de cada sesión. Si hay una actualización, verás una notificación sugiriendo reiniciar.

¿Cómo funciona internamente?

Al iniciar sesión, Claude Code verifica si hay nuevas versiones en el marketplace. Si la versión publicada es mayor a la instalada, descarga e instala la nueva versión automáticamente. El plugin no se actualiza mid-session — solo al inicio de la siguiente.

¿Puedo desactivarlo después?

Sí. Repite el mismo proceso (/plugin → Marketplaces → ai-framework-marketplace) y selecciona Disable auto-update. Volverás al modo manual.

---

Después de instalar

Reinicio obligatorio

Después de instalar o actualizar, cierra Claude Code, espera ~10 segundos y abre una nueva sesión. Los hooks necesitan registrarse y ejecutarse al menos una vez.

Qué pasa en la primera sesión

Al iniciar Claude Code después de instalar el plugin, los hooks ejecutan automáticamente:

1. session-start.py — Sincroniza templates del framework al proyecto (instantáneo)
2. agent-browser-check.py — Instala agent-browser CLI + navegador Chromium en background (~30-60s)

Los hooks son silenciosos cuando todo funciona — solo inyectan mensajes cuando requieren tu atención.

Además, el framework inyecta spinner tips personalizados via spinnerTipsOverride en settings.json — durante la ejecución verás recordatorios sobre /project-init, /commit, /scenario-driven-development y /verification-before-completion mezclados con los tips default de Claude Code.

Flujo recomendado de primera instalación

1. Instala el plugin
2. Cierra Claude Code
3. Espera ~10 segundos (permite que el proceso termine de registrarse)
4. Abre nueva sesión — la instalación de agent-browser ocurre en background
5. Trabaja normalmente. En la siguiente sesión, la skill se activa automáticamente

¿Por qué esperar antes de reiniciar?

Claude Code necesita unos segundos para registrar los hooks del plugin en su configuración interna. Si abres una nueva sesión inmediatamente, los hooks pueden no haberse registrado aún y no ejecutarán.

---

Compatibilidad de plataformas

La plataforma principal es macOS. Linux funciona completamente. Windows es compatible con Git for Windows.

Hooks por plataforma

Hook	Evento	macOS	Linux	Windows
session-start.py	SessionStart	✅	✅	✅
agent-browser-check.py	SessionStart	✅	✅	✅
constraint-reinforcement.py	UserPromptSubmit	✅	✅	✅
subagent-start.py	SubagentStart	✅	✅	✅
notify.sh	Stop, Notification	✅	➖	➖
sdd-test-guard.py	PreToolUse	✅	✅	✅
sdd-auto-test.py	PostToolUse	✅	✅	✅
teammate-idle.py	TeammateIdle	✅	✅	✅
task-completed.py	TaskCompleted	✅	✅	✅

Detalles por hook

session-start.py — Python puro (stdlib), 100% cross-platform. Sincroniza templates y .gitignore.

constraint-reinforcement.py — Refuerzo constitucional en recency zone. Inyecta ~55 tokens de constraints del framework en cada prompt del usuario para contrarrestar dilución de atención en conversaciones largas. Cross-platform: Python puro.

subagent-start.py — Inyecta registro de skills en sub-agentes (general-purpose) para que puedan invocar skills sin que el padre pase la lista manualmente. Cross-platform: Python puro.

agent-browser-check.py — Usa bash -c para lanzar procesos en background. Cross-platform: Git for Windows provee bash en Windows.

notify.sh — Notificaciones nativas macOS (afplay para sonido, osascript para visual). En Linux y Windows se salta silenciosamente (exit 0). No afecta la funcionalidad del framework.

sdd-test-guard.py — Valida que ediciones a archivos de test no reduzcan assertions cuando los tests están fallando (protección contra reward hacking). Cross-platform: file locking gracefully degradado en Windows, paths temporales portables.

sdd-auto-test.py — Ejecuta tests en background después de cada edición a archivos fuente. Cross-platform: file locking gracefully degradado en Windows, paths temporales portables.

teammate-idle.py — Safety net para ralph-orchestrator. Cross-platform: file locking gracefully degradado en Windows.

task-completed.py — Quality gates para validar tareas completadas. Cross-platform: file locking gracefully degradado en Windows.

Windows

Notas para Windows

• Requisito: Git for Windows (Git Bash ejecuta los hooks)
• File locking: Degradado gracefully — fcntl se omite en Windows sin afectar funcionalidad en uso single-user
• Statusline: Usa Python embebido en el script (no requiere jq)
• Notificaciones: No disponibles (requieren macOS)

Para desactivar la auto-instalación de agent-browser en entornos donde falla:

export AI_FRAMEWORK_SKIP_BROWSER_INSTALL=1

Después puedes instalar agent-browser manualmente:

macOS (Homebrew)

brew install agent-browser

Linux / Windows (npm)

npm install -g agent-browser
agent-browser install

---

Inicializar proyecto

cd /tu/proyecto
claude

En la primera sesión, ejecuta:

/project-init

Genera reglas de contexto en .claude/rules/ — Claude las carga automáticamente en cada sesión.

Gestión de plugins

# Deshabilitar temporalmente
/plugin disable ai-framework@ai-framework-marketplace

# Re-habilitar
/plugin enable ai-framework@ai-framework-marketplace

# Desinstalar
/plugin uninstall ai-framework@ai-framework-marketplace

# Explorar plugins disponibles
/plugin

Reinicia Claude Code después de cualquier cambio.

---

Usar el framework

Describe lo que quieres en lenguaje natural:

"Implementa validación de email en el formulario de registro"

Claude activa automáticamente los skills relevantes (SDD, code review, etc).

Para commits y PRs:

/commit "feat: add email validation"
/pull-request develop

---

Troubleshooting

Problema	Solución
Comandos/skills no visibles	Cierra Claude Code, espera ~10s, abre nueva sesión
Hooks no ejecutan	Verifica Python 3.8+: python3 --version
Plugin no aparece	/plugin → selecciona "Discover"
Update no funciona	Ejecuta primero /plugin marketplace update
agent-browser no funciona	Revisa log en /tmp/agent-browser-install.log. Si falló: npm install -g agent-browser
agent-browser install failed en sesión	Verifica Node.js 18+: node --version. Instala manualmente con npm install -g agent-browser
Notificaciones no suenan	Solo disponibles en macOS. Verifica permisos de Script Editor en System Settings → Privacy
Hook falla en Windows	Verifica Git for Windows instalado. Los hooks SDD funcionan nativamente. Para agent-browser: npm install -g agent-browser

Ver logs de instalación de agent-browser

# Log de instalación (primera vez)
cat /tmp/agent-browser-install.log

# Log de sincronización de skill
cat /tmp/agent-browser-skill-sync.log

# Log de auto-update (cada 24h)
cat /tmp/agent-browser-update.log

---

Siguientes pasos

• Skills Guide — Los 23 skills del framework
• Agents Guide — 6 agentes especializados
• Integrations — Plugins, MCPs y herramientas externas

Siguiente paso: Workflow AI-first

---

Última actualización

Fecha: 2026-03-11