Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

acs-framework-cli

jiaas720MIT2.0.9

🚀 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, context, documentation, ai, cli, context-as-code, onboarding, automation, architecture, intelligent

readme

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)

# 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

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)

npx acs-framework-cli@latest

Opción 3: Para desarrolladores

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.

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

acs-validate

Valida la completitud y precisión de tu documentación ACS.

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.

acs-facts > facts.json

acs-upgrade ⭐ MEJORADO en v2.0.9

Migración segura para usuarios existentes con preservación de customizaciones.

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.

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

# Navega al directorio de tu proyecto
cd /path/to/tu/proyecto

# Ejecuta la CLI
acs-init

Configurar un proyecto existente

# 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

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

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

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.