acs-framework-cli/README.md

🚀 CLI inteligente para configurar automáticamente el Augmented Context Standard (ACS) Framework. Context-as-Code que convierte tu conocimiento en un activo versionado.

# ACS Framework CLI v2.0.5 🚀

**CLI inteligente para configurar automáticamente el Augmented Context Standard (ACS) Framework**

## 🎯 Context-as-Code: Tu conocimiento, versionado

Convierte tu proyecto en un activo inteligente que elimina el bus factor y acelera el onboarding. 

### 💎 ¿Por qué ACS Framework?

- **🧠 IA que entiende tu arquitectura** - Adiós alucinaciones, hola respuestas precisas
- **⚡ Onboarding instantáneo** - Nuevos devs hacen commits productivos desde el día 2  
- **🔒 Elimina "cajas negras"** - Documenta automáticamente las partes que nadie toca
- **📈 Escala contigo** - Desde MVP hasta enterprise, el contexto evoluciona

## ⚡ Instalación (30 segundos)

```bash
# Instalar globalmente
npm install -g acs-framework-cli

# Ir a tu proyecto y ejecutar EL COMANDO PRINCIPAL
cd mi-proyecto
acs-hub

# ¡Ya está! Tu IA ahora entiende tu proyecto
```

## 🧠 Análisis Inteligente V2

### Detección Automática de Complejidad
- **📊 Análisis estructural** - Profundidad, organización, patrones
- **⚙️ Análisis tecnológico** - Stack, frameworks, configuraciones
- **🏗️ Análisis arquitectónico** - Microservicios, monorepos, DDD
- **🔗 Análisis de dependencias** - Acoplamiento, integración

### Estimaciones Precisas
- **🟢 Proyecto simple**: 2-5 min setup
- **🟡 Proyecto moderado**: 5-10 min setup
- **🔴 Proyecto complejo**: 10-20 min setup

## 🎪 Comandos Disponibles

```bash
acs-hub               # COMANDO PRINCIPAL - Todo en uno 🌟
acs-master            # Redirige a acs-hub (legacy)
acs-init              # Redirige a acs-hub (legacy)
acs-validate          # Redirige a acs-hub (legacy)
acs-agent             # Redirige a acs-hub (legacy)
acs-facts             # Redirige a acs-hub (legacy)
acs-upgrade           # Migración directa (también en acs-hub)
```
```

**⚡ Comando principal:** `acs-hub` es el ÚNICO comando que necesitas conocer.

**🧠 Filosofía de UX perfecta:**
- Un solo comando, todas las funciones
- Menús contextuales inteligentes
- No más comandos que recordar
- Experiencia fluida y guiada

**📱 Otros comandos** muestran mensaje educativo y te dirigen a `acs-hub`.

## ✨ Lo que genera automáticamente

### 📁 Estructura `.context/` inteligente
- **`README.md`** - Info básica y setup personalizado
- **`ARCHITECTURE.md`** - Mapa del sistema adaptado a tu stack
- **`RULES.md`** - Convenciones específicas de tu equipo  
- **`SYSTEM_PROMPT.md`** - Contexto optimizado para IA
- **`FEATURES.md`** - Historias de usuario y flujos críticos
- **`AGENT_PROMPT.md`** - Instrucciones para IA autónoma
- **`CHANGELOG.md`** - Registro de cambios estructurado

### 🔧 Templates personalizados
- **`.github/pull_request_template.md`** - PR checklist con ACS
- **Configuraciones** adaptadas a tu tecnología específica
```bash
npm install -g acs-framework-cli
```

### Opción 2: Uso directo con npx (sin instalación)
```bash
npx acs-framework-cli
```

### Opción 3: Instalación local para desarrollo
```bash
git clone [este-repo]
cd acs-framework/cli
npm install
npm link  # Para usar globalmente
```

## 🚀 Comandos Disponibles

### `acs-init`
Inicializa la estructura ACS Framework en tu proyecto.

```bash
npx acs-framework-cli
# o si está instalado globalmente:
acs-init
```

### `acs-validate`
Valida la completitud y precisión de tu documentación ACS.

```bash
acs-validate
```

**Nuevo en v2.0+**: Incluye validaciones anti-delirio:
- ✅ Detecta placeholders prohibidos 
- ✅ Verifica tecnologías vs dependencies reales
- ✅ Valida comandos vs scripts de package.json
- ✅ Comprueba consistencia entre archivos

### `acs-facts` 
Extrae hechos verificables del proyecto para alimentar el agente IA.

```bash
acs-facts > facts.json
```

### `acs-upgrade` ⭐ NUEVO en v2.0.5
Migración segura para usuarios existentes con preservación de customizaciones.

```bash
acs-upgrade
```

**Características de migración segura:**
- 🛡️ **Backup automático** de toda la configuración existente
- 🔍 **Análisis inteligente** de customizaciones del usuario  
- 🎯 **Opciones selectivas**: actualizar solo templates o migración completa
- 👀 **Vista previa** de cambios antes de aplicar
- 📁 **Preservación** de archivos personalizados en .context/

### `acs-agent` (MEJORADO en v2.0)
Ejecutor seguro del agente de documentación con validaciones anti-delirio.

```bash
acs-agent
```

**Características anti-delirio:**
- 🛡️ **Backup automático** de documentación antes de cambios
- 🔍 **Extracción de facts** reales del proyecto (dependencies, scripts, estructura)
- 🤖 **Prompt con evidencias** verificables para IA
- ✅ **Validación automática** de cambios del agente
- 🚫 **Bloqueo de inventos** (tecnologías/comandos no presentes en proyecto)
- 📊 **Detección de placeholders** prohibidos
- 🔄 **Restore automático** si hay problemas críticos
- 🎯 **Validación de consistencia** entre archivos

**Flujo seguro completo:**
1. `acs-validate` - verificar estado actual
2. `acs-agent` - ejecutar agente con validaciones
3. Aplicar cambios sugeridos por la IA (basados en facts reales)
4. El sistema valida automáticamente y acepta/rechaza cambios
5. Solo se aplican cambios con evidencia verificable

## Uso

### Configurar un proyecto nuevo
```bash
# Navega al directorio de tu proyecto
cd /path/to/tu/proyecto

# Ejecuta la CLI
acs-init
```

### Configurar un proyecto existente
```bash
# En el directorio raíz del proyecto (donde está el package.json, composer.json, etc.)
acs-init
```

## ¿Qué preguntas hace la CLI?

La CLI te hará preguntas organizadas en secciones:

### 📋 Información básica
- Nombre del proyecto
- Descripción breve
- Responsable (nombre + email)
- Estado actual (desarrollo, producción, etc.)
- Tecnologías principales

### 🏗️ Arquitectura
- Tipo de proyecto (API, web app, móvil, etc.)
- Componentes principales
- Flujo crítico principal

### 👥 Convenciones del equipo
- Estilo de commits (Conventional, descriptivo, etc.)
- Estrategia de branches
- Política de Pull Requests
- Uso de tests

### 📖 Historia de usuario inicial (opcional)
- Funcionalidad principal
- Rol del usuario
- Beneficio esperado

## ¿Qué archivos genera?

```
.context/
├── README.md           # Info básica para arrancar
├── ARCHITECTURE.md     # Mapa del sistema
├── RULES.md           # Convenciones del equipo
├── SYSTEM_PROMPT.md   # Instrucciones para IA
├── FEATURES.md        # Historias de usuario (opcional)
└── CHANGELOG.md       # Registro de cambios

.github/
└── pull_request_template.md  # Template con checklist ACS
```

## Ejemplos de uso

### Para un proyecto Laravel
```bash
cd mi-proyecto-laravel
acs-init

# La CLI detectará/preguntará:
# - Tecnologías: Laravel, PHP, MySQL
# - Comandos típicos: composer install, php artisan migrate
# - Convenciones de Laravel
```

### Para un proyecto React
```bash
cd mi-app-react
acs-init

# La CLI generará contexto para:
# - Tecnologías: React, Node.js, etc.
# - Comandos típicos: npm install, npm start
# - Estructura de componentes
```

### Para un proyecto Python/Django
```bash
cd mi-proyecto-django
acs-init

# Configurará contexto para:
# - Tecnologías: Python, Django
# - Comandos: pip install, python manage.py migrate
# - Convenciones de Django
```

## Después de usar la CLI

### 1. Revisa los archivos generados
Los archivos están pre-poblados con la información que proporcionaste, pero tendrás secciones marcadas como `[Pendiente definir]` que puedes completar gradualmente.

### 2. Personaliza según tu proyecto
- Completa comandos específicos en `.context/README.md`
- Agrega diagramas a `.context/ARCHITECTURE.md`
- Define reglas específicas en `.context/RULES.md`

### 3. Comparte con tu IA
Copia el contenido de `.context/SYSTEM_PROMPT.md` cuando uses GitHub Copilot, ChatGPT, Claude, etc.

### 4. Úsalo en el flujo de desarrollo
- El template de PR incluye checklist ACS automáticamente
- Actualiza la documentación como parte del desarrollo normal

## Ventajas

✅ **Setup en 5 minutos** - No más horas configurando documentación  
✅ **Personalizado para tu stack** - Se adapta a Laravel, React, Python, etc.  
✅ **Listo para IA** - GitHub Copilot tendrá contexto desde día 1  
✅ **Mantenimiento automático** - Checklist en PRs asegura que se mantenga actualizado  
✅ **Nuevos desarrolladores felices** - Contexto claro desde el primer día  

## Tecnologías

- **Node.js 16+** (para ejecutar la CLI)
- **Inquirer.js** (preguntas interactivas)
- **Chalk** (output colorido)
- **fs-extra** (manipulación de archivos)

## Contribuir

¿Encontraste un bug o tienes una mejora?

1. Fork el repo
2. Crea una branch: `git checkout -b feature/mi-mejora`
3. Haz tus cambios
4. Commit: `git commit -m "feat: agregar soporte para Vue.js"`
5. Push: `git push origin feature/mi-mejora`
6. Abre una Pull Request

## FAQ

### ¿Puedo usar esto en proyectos existentes?
Sí, la CLI detecta si ya existe una carpeta `.context/` y pregunta si quieres sobrescribirla.

### ¿Funciona con cualquier lenguaje/framework?
Sí, la CLI es agnóstica del tecnología. Incluye opciones para los stacks más comunes y permite agregar tecnologías personalizadas.

### ¿Qué pasa si mi proyecto usa tecnologías no listadas?
Puedes agregar tecnologías personalizadas durante la configuración. La CLI las incluirá en la documentación generada.

### ¿Puedo modificar los templates?
Sí, una vez generados los archivos son tuyos. Modifícalos según las necesidades específicas de tu proyecto.

### ¿Funciona en Windows/Mac/Linux?
Sí, es multiplataforma. Solo necesitas Node.js 16+.

## Licencia

MIT - Úsalo libremente en proyectos personales y comerciales.

---

**¿Preguntas?** Abre un issue en el repositorio.  
**¿Te gusta?** ⭐ Dale una estrella al repo.