@angelardanaz/ai

Framework de IA para Claude Code que instala slash commands estructurados en tu proyecto, dándole continuidad y orden al desarrollo asistido por IA a lo largo de múltiples sesiones.

Instalación

npx @angelardanaz/ai@latest install

Uso

Tras instalar, tendrás cinco slash commands disponibles en tu herramienta de IA:

| Comando | Descripción | |---------|-------------| | /framework:init | Inicializa .framework/ con el contenido real del proyecto (ejecutar una vez tras instalar) | | /framework:research | Explora y descubre antes de planear — úsalo cuando hay incógnitas que resolver primero | | /framework:plan | Explora el código, identifica riesgos y produce un plan antes de escribir nada | | /framework:apply | Ejecuta el plan aprobado paso a paso | | /framework:unify | Revisa los cambios, actualiza la documentación y propone el commit |

Flujo de trabajo

/framework:init (una vez)

        ┌─────────────────────────────────────────────────┐
        │                                                 │
  /framework:research  →  /framework:plan  →  apruebas  →  /framework:apply  →  /framework:unify
  (si hay incógnitas)                                                               │
        └─────────────────────────────────────────────────────────────────────────┘

/framework:unify es obligatorio al final de cada ciclo. Es el paso que sincroniza .framework/ con los cambios reales del código, archiva el contexto de fase cuando termina, y propone el commit. Sin él, el estado del proyecto se desincroniza y la siguiente sesión pierde continuidad.

Herramientas soportadas

| Herramienta | Slash commands | Contexto | |-------------|---------------|----------| | Claude Code | ✅ | CLAUDE.md | | Cursor | ✅ | .cursorrules | | GitHub Copilot | — | .github/copilot-instructions.md | | Codex | — | AGENTS.md | | Windsurf | — | .windsurfules |

Comandos CLI

npx @angelardanaz/ai@latest install      # Instala slash commands en el proyecto
npx @angelardanaz/ai@latest update       # Actualiza los slash commands a la versión más reciente
npx @angelardanaz/ai@latest status       # Muestra qué está instalado en el proyecto actual
npx @angelardanaz/ai@latest uninstall    # Elimina los slash commands instalados

Qué hace install

1. Detecta tu herramienta de IA y framework frontend automáticamente
2. Copia los slash commands al directorio correspondiente (ej. .claude/commands/framework/)
3. Descarga la documentación oficial del framework con el nombre del framework (ej. astro.txt, next-js.txt)
4. Genera el archivo de contexto del proyecto (CLAUDE.md, .cursorrules, etc.)
5. Inicializa .framework/ con plantillas de documentación estructurada
6. Registra el MCP server angelardanaz-ai en .claude/settings.json
7. Registra un Stop hook que ejecuta npx @angelardanaz/ai sync al finalizar cada sesión

Auto-detección

Durante la instalación se detectan automáticamente:

• Gestor de paquetes — bun, pnpm, yarn, npm
• Runtime — versión de Bun desde packageManager, o Node.js desde .nvmrc / engines
• Lockfile — bun.lock, pnpm-lock.yaml, yarn.lock, package-lock.json
• Lenguaje — TypeScript o JavaScript
• Framework CLI — commander, yargs, oclif, ink, meow…
• Testing — vitest, jest, playwright, cypress…
• Linter — eslint, biome, oxlint

.framework/

El directorio .framework/ contiene la documentación estructurada del proyecto:

.framework/
├── PROJECT.md          # Requisitos y contexto de negocio
├── MILESTONES.md       # Historial de versiones entregadas
├── framework.json      # Configuración base del proyecto (AI tool, versión)
├── phases/
│   └── phase-XX-<nombre>.md   # Contexto archivado de cada fase al completarse
└── codebase/
    ├── STACK.md        # Stack tecnológico auto-rellenado
    ├── ARCHITECTURE.md # Decisiones arquitectónicas
    ├── CONVENTIONS.md  # Convenciones de código
    └── …

El estado del workflow (posición en el loop, fase activa, issues) lo gestiona el MCP server y se persiste en ~/.config/angelardanaz-ai/<hash>/ — fuera del repositorio.

MCP Server

Al instalar, se registra automáticamente el MCP server angelardanaz-ai en .claude/settings.json. Este servidor expone las siguientes tools para que los slash commands mantengan el estado del workflow entre sesiones:

| Tool | Descripción | |------|-------------| | get_state | Lee la posición actual del loop (IDLE / PLAN / APPLY / UNIFY) | | update_state | Actualiza la posición y anota actividad reciente | | get_roadmap | Consulta fases y planes del proyecto | | create_issue | Registra una mejora diferida descubierta durante la ejecución |

El estado se guarda en ~/.config/angelardanaz-ai/<hash>/ (fuera del repo), identificado por un hash del path del proyecto.

Stop hook

Se registra un hook en .claude/settings.json que ejecuta npx @angelardanaz/ai sync cada vez que Claude Code termina una sesión. Esto actualiza el campo last_activity en el estado persistido, permitiendo saber cuándo fue la última vez que se trabajó en el proyecto.

Requisitos

• Node.js 18+ o Bun