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.9 🚀

**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
625
### Estimaciones Precisas
- **🟢 Proyecto simple**: 2-5 min setup
- **🟡 Proyecto moderado**: 5-10 min setup
- **🔴 Proyecto complejo**: 10-20 min setup

## 🎯 Tipos de Setup V2.0.9 (Mejorados)

### ⚡ Setup Instantáneo
- **Tiempo**: 2 minutos
- **Preguntas**: 0 (completamente automático)
- **Proceso**: Detección automática + generación silenciosa
- **Ideal para**: Proyectos simples, prototipado rápido

### 🎯 Setup Inteligente  
- **Tiempo**: 5 minutos
- **Preguntas**: 3 esenciales únicamente
- **Proceso**: Detección automática + personalización mínima
- **Ideal para**: La mayoría de proyectos - balance perfecto

### 🏢 Setup Completo
- **Tiempo**: 10-20 minutos  
- **Preguntas**: Configuración detallada paso a paso
- **Proceso**: Control total sobre cada aspecto
- **Ideal para**: Proyectos complejos, equipos grandes

## 🎪 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 V2.0.9:**
- Un solo comando, todas las funciones
- Menús contextuales inteligentes adaptativos  
- 3 tipos de setup claros: instantáneo/inteligente/completo
- Detección automática de complejidad
- Sin contradicciones ni flujos rotos
- Redirección automática sin preguntas innecesarias

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

## 🆕 Novedades v2.0.9

### 📚 Mejoras en Documentación de Prompts
- **USER_MANUAL_AND_TECHNICAL_DOCUMENTATION_PROMPT.md mejorado**:
  - ✅ Eliminadas redundancias: secciones duplicadas removidas
  - ✅ Estructura numerada jerárquica completa (13 secciones principales, 40+ subsecciones)
  - ✅ Índice mejorado con navegación clara
  - ✅ Mejor organización con numeración multinivel (ej: 3.2.1, 6.3.4, 13.2.6)
  - ✅ Referencias cruzadas precisas
- **Documento listo para producción**: Sin duplicaciones, profesionalmente estructurado
- **Manual optimizado**: Para generar documentación técnica y manuales de usuario de alta calidad

### 🔧 Mejoras de Calidad
- ✅ **Consolidación de contenido**: Secciones redundantes fusionadas inteligentemente
- ✅ **Navegación mejorada**: Estructura jerárquica clara facilita localización de contenido
- ✅ **Profesionalismo**: Documento con estándares de producción

## 🆕 Novedades v2.0.8

### 📋 Mejoras en Generación de Documentación
- **DOCUMENTATION_PROMPT.md**: Renombrado desde AGENT_PROMPT.md para mayor claridad
- **Nueva opción CLI**: "Generar prompt documentación técnica y manual de usuario"
- **USER_MANUAL_AND_TECHNICAL_DOCUMENTATION_PROMPT.md**: Nuevo prompt especializado para generar manuales técnicos completos
- **Referencias actualizadas**: Todas las referencias AGENT_PROMPT → DOCUMENTATION_PROMPT actualizadas sistemáticamente

### 🔧 Mejoras Técnicas v2.0.8
- ✅ **Naming consistency**: Mejor nomenclatura para archivos de prompts
- ✅ **CLI menu enhancement**: Nueva funcionalidad integrada en menú contextual
- ✅ **Complete reference update**: Actualización sistemática en todos los archivos
- ✅ **showManualPrompt()**: Nuevo método para mostrar prompt de documentación técnica

### 🎯 Mejoras UX v2.0.8
- ✅ **Mejor naming para "Optimizar configuración"**: Ahora "Validar y corregir documentación con IA"
- ✅ **Descripción más clara**: "Checkup completo automático" explica mejor la funcionalidad
- ✅ **Fix doble prompt**: Eliminado prompt duplicado en generación de documentación técnica
- ✅ **Mensajes consistentes**: Terminología alineada en toda la interfaz

## 🆕 Novedades v2.0.6

### 🎯 UX Completamente Rediseñada
- **Setup Instantáneo**: Verdaderamente sin preguntas, redirección automática
- **Setup Inteligente**: Solo 3 preguntas esenciales, detección automática primero
- **Setup Completo**: Configuración detallada sin cambios
- **Sin contradicciones**: Eliminada inconsistencia entre análisis de complejidad
- **Flujos mejorados**: Sin prompts inesperados, redirección inteligente

### 🔧 Correcciones Técnicas Críticas
- ✅ **Componentes handling**: Fix error `map is not a function`
- ✅ **Silent generation**: Métodos silenciosos para setup instantáneo
- ✅ **Auto-redirection**: Sin preguntas innecesarias post-setup
- ✅ **Complexity consistency**: Sin contradicciones SIMPLE vs MODERATE

## ✨ 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
- **`DOCUMENTATION_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
# Actualizar a la última versión (recomendado)
npm install -g acs-framework-cli@latest

# O instalación inicial
npm install -g acs-framework-cli
```

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

### Opción 3: Para desarrolladores
```bash
git clone https://github.com/jiaas/acs-framework.git
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` ⭐ MEJORADO en v2.0.9
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.