Agentic Control Framework (ACF)

Un conjunto de herramientas para

Documentación

Agentic Control Framework (ACF)

Autor: Abhilash Chadhar (FutureAtoms) Repositorio: agentic-control-framework

Capa de orquestación nativa para IA (CLI + MCP) con más de 80 herramientas para ingeniería de contexto: recuperación, edición de código, automatización de navegador, orquestación de terminal y memoria persistente, diseñada para Claude Code, Cursor, Codex y VS Code. Este README refleja el código actual y las integraciones probadas.

Entrada CLI: bin/acf
Servidor MCP: bin/agentic-control-framework-mcp → src/mcp/server.js
Configuraciones de cliente de ejemplo: config/examples/
Pruebas: npm run test:cli, npm test

Qué incluye

Qué hay en la caja

Gestor de tareas con prioridades, dependencias, subtareas y plantillas
CLI con comandos enriquecidos
Servidor MCP (JSON‑RPC sobre stdio) probado con Claude Desktop/Code, Cursor y Codex

Características clave:

🔧 Más de 80 herramientas especializadas: gestión de tareas, sistema de archivos, terminal, automatización de navegador, integración con AppleScript
🎯 3 modos de uso: CLI, MCP local y MCP en la nube para máxima flexibilidad
🔗 Compatibilidad universal: funciona con Claude Code, Cursor, Claude Desktop, VS Code y cualquier cliente compatible con MCP
☁️ Listo para la nube: despliegue en GCP, Railway y Fly.io con autoescalado
🚀 Listo para producción: cobertura integral de la suite de pruebas en las herramientas principales
⚡ Alto rendimiento: tiempo de respuesta promedio de 200-1000 ms, excelente fiabilidad
🛡️ Seguridad ante todo: protecciones del sistema de archivos, sistemas de permisos y valores predeterminados seguros
📋 Compatible con MCP 2025-03-26: protocolo predeterminado con títulos de herramientas, anotaciones y capacidades adecuadas

Cómo ACF resuelve la ingeniería de contexto

ACF convierte la realidad desordenada y de múltiples archivos y pasos del trabajo de software en «unidades de contexto» precisas y direccionables que los LLM pueden solicitar, refinar y sobre las que pueden actuar. Lo logra combinando un grafo de tareas, superficies de contexto enriquecidas, herramientas de recuperación/edición y protecciones, todo accesible mediante CLI y MCP.

Grafo de tareas como fuente de verdad
- Cada tarea/subtarea tiene un ID, estado, prioridad numérica (1–1000), dependencias, archivos relacionados, registro de actividad y marcas de tiempo.
- El motor de prioridades admite decaimiento temporal y ponderación por esfuerzo para mantener «qué sigue» dinámicamente correcto.
Superficies de contexto enriquecidas y bajo demanda
- getContext devuelve el bloque de contexto exacto de la tarea/subtarea (incluidos los metadatos de archivos relacionados y el registro de actividad).
- generateTaskFiles materializa un archivo Markdown por tarea (tasks/), y tasks-table.md ofrece una visión general del proyecto.
- El CLI context <id> imprime un resumen legible para humanos y LLM.
Herramientas de recuperación y edición (para construir y aplicar contexto)
- Recuperación: search_code, tree, list_directory, get_file_info, read_file/read_multiple_files, read_url.
- Edición: edit_block aplica reemplazos quirúrgicos usando bloques explícitos de antes/después (minimiza la deriva accidental).
- Ejecución: herramientas de terminal (execute_command, list_processes, sesiones) para verificar las suposiciones de contexto (pruebas, compilaciones).
Sincronización y actualización
- El observador de archivos sincroniza tasks.json y los archivos por tarea; detección de cambios con debounce; tasks-table.md se mantiene actualizado.
- Protecciones: allowedDirectories y readonlyMode restringen el alcance del sistema de archivos accesible.
Planificación a partir de documentos de producto (opcional)
- parsePrd, expandTask, reviseTasks convierten PRD o solicitudes de cambio en tareas estructuradas mediante Gemini, y luego las integran de nuevo en el grafo de tareas para una ejecución trazable.

En conjunto, esto proporciona un «bucle de contexto» repetible: planificar → recuperar → editar/verificar → actualizar el estado, con cada paso direccionable mediante herramientas para que los clientes MCP (Claude Code, Cursor, Codex, VS Code) puedan manejarlo de forma fiable.

Recetas de contexto de extremo a extremo

Arranque desde PRD
- tools/call: parsePrd { filePath } → tareas creadas con prioridades y dependencias → generateTaskFiles para revisión.
Enfocar un modelo en la siguiente acción
- tools/call: getNextTask → obtén la siguiente tarea accionable considerando dependencias/prioridad.
- tools/call: getContext { id } → recupera el bloque de la tarea; luego read_file/search_code para el código circundante.
Cambio de código seguro y quirúrgico
- Recuperar: search_code para identificar el bloque exacto; verificar con read_file.
- Aplicar: edit_block { file_path, old_string, new_string, normalize_whitespace }.
- Verificar: execute_command { command: "npm test" } o comandos específicos de la suite.
Mantener el contexto actualizado
- start_file_watcher → modifica archivos o tareas → file_watcher_status para estadísticas → stop_file_watcher al terminar.

Memoria persistente (registros de actividad en tasks.json)

ACF mantiene una memoria duradera y consultable de qué hizo el agente (o humano), cuándo y por qué. Esta memoria persistente reside en .acf/tasks.json y en los archivos por tarea:

Qué se almacena
- Para cada tarea y subtarea: entradas createdAt, updatedAt y activityLog[] con mensajes con marca de tiempo.
- Cada cambio en una tarea (estado, título, descripción, prioridad, dependencias, archivos relacionados) agrega una entrada de registro e incrementa updatedAt.
- Los flujos de IA (parsePrd, expandTask, reviseTasks) también escriben mensajes de actividad claros.
Cómo escriben memoria los LLM
- CLI: incluye --message "..." al cambiar el estado para agregar una nota humana/LLM al registro de actividad.
  - Ejemplos:
    - acf status 12 inprogress --message "Started implementing parser"
    - acf update 12 --priority 750 --message "Raised priority due to deadline"
- MCP: pasa message en los argumentos de tools/call para updateStatus o updateTask.
  - tools/call { name: "updateStatus", arguments: { id: "12", newStatus: "done", message: "Tests green; merging" } }
  - tools/call { name: "updateTask", arguments: { id: "12", priority: 820, message: "Escalated after stakeholder review" } }
Cómo consumir memoria
- acf context <id> (CLI) imprime un contexto enriquecido y legible que incluye los activityLog recientes.
- tools/call: getContext { id } (MCP) devuelve el mismo bloque estructurado, ideal para prompts de LLM.
- generateTaskFiles produce instantáneas Markdown; tasks-table.md muestra una visión general en vivo sincronizada desde .acf/tasks.json mediante el observador de archivos.

Inicio rápido

Requisitos
- Node.js 18+
- macOS para herramientas AppleScript (opcional). Navegadores Playwright si se usan herramientas de navegador: npx playwright install.
Instalación
- cd agentic-control-framework && npm ci
CLI (local)
- ./bin/acf init --project-name "Demo" --project-description "Getting started"
- ./bin/acf add -t "First task" -p high
- ./bin/acf list --format human
Servidor MCP (stdio)
- node ./bin/agentic-control-framework-mcp --workspaceRoot $(pwd)
- Usa las configuraciones de cliente de ejemplo en config/examples/ para Claude Code, Cursor y Codex.

Documentación

Descripción general
- Índice principal de documentación: docs/README.md
- Estructura del proyecto: docs/PROJECT-STRUCTURE.md
- Descripción general de la arquitectura: docs/architecture/overview.md
- Detalles de integración MCP: docs/architecture/mcp-integration.md
Integraciones (clientes MCP)
- Guías de conexión: docs/INTEGRATIONS.md
- Configuraciones de ejemplo:
  - Claude Code (VS Code): config/examples/claude_code.json
  - Cursor (proyecto/global): config/examples/cursor.mcp.json
  - Codex CLI (TOML): config/examples/codex.config.toml
- Asistente de Claude (notas de desarrollo): CLAUDE.md
Referencia
- Ejemplos completos de CLI: docs/reference/cli_examples.md
- Ejemplos de solicitud/respuesta MCP (generados automáticamente): docs/reference/mcp_examples.md
Pruebas y validación
- Resumen y notas de pruebas: docs/TESTING_SUMMARY.md
- Validador de comandos de documentación: scripts/testing/validate-doc-commands.sh
Propuestas e ideas
- Propuesta de indexación del espacio de trabajo: docs/workspace-indexing-proposal.md

Herramientas MCP (implementadas)

Descripción general de categorías de herramientas

mindmap
  root((ACF Tools<br/>79 Total))
    Core ACF
      Task Management
        listTasks
        addTask
        updateStatus
        getNextTask
      Priority System
        recalculatePriorities
        getPriorityStatistics
        bumpTaskPriority
        prioritizeTask
      File Watching
        initializeFileWatcher
        stopFileWatcher
        forceSyncTaskFiles
      Templates
        getPriorityTemplates
        addTaskWithTemplate
    File Operations
      Basic Operations
        read_file
        write_file
        copy_file
        delete_file
      Directory Ops
        list_directory
        create_directory
        tree
        search_files
    Terminal
      Command Execution
        execute_command
        read_output
        force_terminate
      Process Management
        list_processes
        kill_process
    Browser Automation
      Navigation
        browser_navigate
        browser_navigate_back
        browser_close
      Interaction
        browser_click
        browser_type
        browser_hover
        browser_drag
      Capture
        browser_take_screenshot
        browser_pdf_save
        browser_snapshot
      Tab Management
        browser_tab_list
        browser_tab_new
        browser_tab_close
    Search & Edit
      search_code
      edit_block
    System Integration
      AppleScript
        applescript_execute
      Configuration
        get_config
        set_config_value

Herramientas principales de tareas

initProject, addTask, addSubtask, listTasks, updateTask, updateStatus, removeTask, getNextTask
generateTaskFiles, recalculatePriorities, getPriorityStatistics, getDependencyAnalysis
getPriorityTemplates, calculatePriorityFromTemplate, suggestPriorityTemplate, addTaskWithTemplate

Utilidades

read_file, write_file
execute_command (stub para pruebas)

Nota: las herramientas se anuncian mediante tools/list desde src/mcp/server.js, y cada herramienta listada tiene un manejador en el servidor.

Configuración

Variables de entorno principales
- WORKSPACE_ROOT: ruta del espacio de trabajo predeterminada usada por CLI/MCP
- ALLOWED_DIRS: directorios adicionales permitidos (delimitados por ruta)
- READONLY_MODE: establece en true para deshabilitar operaciones de escritura
- ACF_PATH: anulación de la raíz del proyecto para bins
Banderas opcionales/de características
- GEMINI_API_KEY: habilita herramientas respaldadas por IA (parsePrd, expandTask, reviseTasks)
- ACF_SKIP_POSTINSTALL=1: omite todos los pasos posteriores a la instalación
- ACF_SKIP_PLAYWRIGHT=1: omite las descargas pesadas de navegadores Playwright
- ACF_INSTALL_SHARP=1 o ACF_INSTALL_ALL=1: instala sharp opcional
- ACF_ENABLE_BROWSER_TOOLS=1: habilita pruebas de navegador Playwright (macOS predeterminado)
- ACF_ENABLE_APPLESCRIPT=1: habilita pruebas de AppleScript (solo macOS)

Seguridad y protecciones

El acceso al sistema de archivos está restringido por allowedDirectories y readonlyMode.
Las lecturas de URL (read_url) son explícitas; las ediciones usan edit_block con contenido anterior/nuevo para minimizar cambios no deseados.
La ejecución en terminal admite comandos bloqueados y tiempos de espera; las sesiones se pueden listar/terminar.

Comandos CLI (nivel alto)

init, add, list, add-subtask, status, next, update, remove, context
update-subtask, bump, defer, prioritize, deprioritize
recalculate-priorities, priority-stats, dependency-analysis
start-file-watcher, stop-file-watcher, file-watcher-status, force-sync
list-templates, suggest-template, calculate-priority, add-with-template

Herramientas de terminal (6 herramientas) ✅

Command Execution:
- execute_command: Run shell commands with timeout
- read_output: Read from running processes
- force_terminate: Kill processes
- list_sessions: Show active terminal sessions
- list_processes: Show running processes
- kill_process: Terminate processes

Herramientas de automatización de navegador (25 herramientas) ✅

Navigation:
- browser_navigate: Navigate to URLs
- browser_navigate_back: Go back
- browser_navigate_forward: Go forward
- browser_close: Close browser

Interaction:
- browser_click: Click elements
- browser_type: Type text
- browser_hover: Hover over elements
- browser_drag: Drag and drop
- browser_select_option: Select dropdown options
- browser_press_key: Keyboard input

Capture:
- browser_take_screenshot: Screenshots
- browser_snapshot: Accessibility snapshots
- browser_pdf_save: Save as PDF

Management:
- browser_tab_list: List browser tabs
- browser_tab_new: Open new tabs
- browser_tab_select: Switch tabs
- browser_tab_close: Close tabs
- browser_file_upload: Upload files
- browser_wait: Wait for time/conditions
- browser_resize: Resize window
- browser_handle_dialog: Handle alerts/dialogs
- browser_console_messages: Get console logs
- browser_network_requests: Monitor network

Herramientas de búsqueda y edición (2 herramientas) ✅

Code Operations:
- search_code: Advanced text/code search with ripgrep
- edit_block: Surgical text replacements

Herramientas AppleScript (1 herramienta) ✅

macOS Automation:
- applescript_execute: Run AppleScript for system integration

Herramientas de configuración (2 herramientas) ✅

Server Management:
- get_config: Get server configuration
- set_config_value: Update configuration values

Estructura del proyecto

El repositorio está organizado siguiendo prácticas estándar con una separación limpia de responsabilidades:

agentic-control-framework/
├── 📁 bin/           # CLI executables and entry points
├── 📁 src/           # Core source code and tool implementations
├── 📁 docs/          # Comprehensive documentation (organized by category)
├── 📁 test/          # Testing infrastructure and test suites
├── 📁 config/        # Configuration files and examples
├── 📁 scripts/       # Setup, deployment, and maintenance scripts
├── 📁 deployment/    # Cloud deployment configurations
├── 📁 tasks/         # Task management files
├── 📁 templates/     # Project templates
├── 📁 public/        # Static assets
└── 📁 data/          # Data directory

Ver también: docs/PROJECT-STRUCTURE.md

Integraciones

Usa las plantillas listas para copiar en config/examples/.

Claude Desktop: claude.json
Claude Code (VS Code): config/examples/claude_code.json
Cursor: config/examples/cursor.mcp.json
Codex: config/examples/codex.config.toml

Más detalles: docs/INTEGRATIONS.md

☁️ Despliegue en la nube

Guía de despliegue - Descripción general completa del despliegue

Pruebas

Pruebas MCP: npm test
Pruebas CLI: npm run test:cli
Cobertura: npm run coverage:all

Banderas de entorno

ACF_SKIP_POSTINSTALL=1 para omitir todos los pasos posteriores a la instalación
ACF_SKIP_PLAYWRIGHT=1 para omitir las descargas de navegadores Playwright en la instalación
ACF_INSTALL_SHARP=1 (o ACF_INSTALL_ALL=1) para instalar sharp opcional
ACF_ENABLE_BROWSER_TOOLS=1 para habilitar pruebas de navegador Playwright (solo macOS de forma predeterminada)
ACF_ENABLE_APPLESCRIPT=1 para habilitar pruebas de AppleScript (solo macOS)

Restricción por plataforma (seguro para CI de forma predeterminada)

Las pruebas MCP de navegador y AppleScript se omiten de forma predeterminada y en Windows/Linux.
Para ejecutarlas localmente en macOS, establece las variables de entorno ACF_ENABLE_* correspondientes.
Google Cloud Run - Despliegue en GCP
Docker - Despliegue en contenedores
Configuración remota - Configuración de cliente remoto

🧪 Pruebas y calidad

Pruebas MCP en la nube - Pruebas integrales más recientes
Verificación de herramientas - Las 79 herramientas verificadas
Pruebas de seguridad - Validación de seguridad
Marco de pruebas - Infraestructura de pruebas

🏗️ Referencia técnica

Arquitectura del sistema - Arquitectura completa con diagramas
Referencia de herramientas - Documentación completa de herramientas
Sistema de prioridades - Priorización avanzada de tareas
Integración MCP - Detalles de implementación del protocolo
Estructura del proyecto - Organización del repositorio
Referencia rápida - Comandos esenciales

📋 Índice completo de documentación

Índice maestro de documentación - Catálogo completo de toda la documentación
Índice de documentación - Índice de referencia rápida

📊 Estado actual

Componente	Estado	Detalles
Modo CLI	✅ 100% Funcionando	Toda la gestión de tareas y herramientas principales funcionales
MCP Local	✅ 100% Funcionando	Todas las herramientas principales verificadas vía protocolo MCP
MCP Cloud	✅ 100% Funcionando	Integración mcp-proxy, transporte HTTP/SSE verificado
Integraciones IDE	✅ 100% Funcionando	Cursor, Claude Desktop, Claude Code, VS Code probados
Herramientas ACF Principales	✅ 25/25 Funcionando	Gestión de tareas, sistema de prioridades, generación de archivos
Herramientas de Sistema de Archivos	✅ 14/14 Funcionando	Operaciones de archivos, gestión de directorios, búsqueda
Herramientas de Navegador	✅ 25/25 Funcionando	Automatización Playwright, capturas de pantalla, generación de PDF
Herramientas de Terminal	✅ 6/6 Funcionando	Ejecución de comandos, gestión de procesos
Herramientas de Búsqueda/Edición	✅ 3/3 Funcionando	Búsqueda de código con ripgrep, edición quirúrgica
Herramientas de Sistema	✅ 7/7 Funcionando	AppleScript, gestión de configuración
Protocolo MCP	✅ Soportado	JSON-RPC 2.0; MCP 2025-03-26 (predeterminado) y 2024-11-05

¡Todas las pruebas pasan! Consulte ACF-TESTING-SUMMARY.md para ver los resultados detallados de las pruebas

🧪 Resultados de Pruebas y Aseguramiento de Calidad

Última Ejecución de Pruebas: 100% de Tasa de Éxito (Todas las Pruebas Pasan)

✅ Cobertura Integral de Pruebas

Pruebas de Herramientas CLI: ✅ APROBADAS - Todas las operaciones de gestión de tareas funcionando
Pruebas de Herramientas MCP Local: ✅ APROBADAS - 3/3 pruebas principales, 100% de tasa de éxito
Pruebas de Herramientas MCP stdio: ✅ APROBADAS - 25/25 pruebas integrales, 100% de tasa de éxito
Pruebas de Herramientas Especializadas: ✅ APROBADAS - Herramientas de Filesystem, Browser, AppleScript, Search, Edit
Pruebas de Integración: ✅ APROBADAS - Proxy MCP, configuraciones de cliente, endpoints SSE
Pruebas de Extremo a Extremo: ✅ APROBADAS - Verificación de salud del sistema, todos los módulos cargando

📊 Métricas de Rendimiento

Tiempo de Respuesta Promedio: 24ms
Tiempo de Respuesta Máximo: 439ms
Sin Respuestas Lentas: 0 respuestas >1s
Sin Respuestas Grandes: 0 respuestas >10KB
Evaluación de Calidad: EXCELENTE (100% de tasa de éxito)

🔧 Funcionalidades Validadas

Flujo de trabajo de gestión de tareas con dependencias
Sistema de prioridades y recálculo
Cumplimiento y comunicación del protocolo MCP
Automatización de navegador con Playwright
Integración AppleScript (macOS)
Operaciones de sistema de archivos con salvaguardas de seguridad
Funcionalidad de herramientas de búsqueda y edición
Generación de configuración de cliente (Cursor, Claude Desktop, VS Code)

🧪 Pruebas y Verificación

Pruebas Integrales Completadas (Enero 2025)

ACF ha sido sometido a pruebas exhaustivas para garantizar su preparación para producción:

Verificación de Herramientas ✅

Pruebas extensivas de herramientas: Herramientas principales verificadas vía protocolo MCP
100% de Tasa de Éxito: Todas las herramientas funcionando correctamente en todas las categorías
Rendimiento Validado: Tiempo de respuesta promedio de 4ms, sin respuestas lentas

Pruebas de Integración IDE ✅

Claude Code: 15/15 pruebas de compatibilidad aprobadas
Cursor IDE: Configuración y descubrimiento de herramientas verificado
Claude Desktop: Transporte SSE e integración mcp-proxy probados
VS Code: Configuraciones de extensiones Cline y Continue verificadas

Cumplimiento del Protocolo ✅

MCP 2025-03-26: Versión de protocolo predeterminada; compatible con versiones anteriores de 2024-11-05
JSON-RPC 2.0: Implementación completa del protocolo
Manejo de Errores: Códigos de error estándar y degradación gradual

📊 Ver Informe Completo de Pruebas

🚀 Inicio Rápido

📋 ¿Necesita instrucciones detalladas de configuración? Consulte nuestra Guía de Configuración de Plataformas para Windows, macOS y Ubuntu con instrucciones paso a paso.

Requisitos Previos

# Install Node.js 22+ (LTS)
node --version

# Install dependencies
npm install

# Install global MCP dependencies (for IDE integration)
npm install -g mcp-proxy @modelcontextprotocol/inspector

# Install browser dependencies (for automation tools)
npx playwright install

# Make CLI tools executable (macOS/Linux)
chmod +x bin/*

⚙️ Configuración

Copie y personalice las plantillas de configuración:

# Copy configuration templates
cp config/examples/config.json ./config.json
cp config/examples/claude-mcp-config.json ./claude-mcp-config.json

# Update paths in configuration files
export ACF_PATH="$(pwd)"
export WORKSPACE_ROOT="$(pwd)"

# Replace placeholders (Linux/macOS)
sed -i 's|${ACF_PATH}|'$ACF_PATH'|g' *.json
sed -i 's|${WORKSPACE_ROOT}|'$WORKSPACE_ROOT'|g' *.json

# Or set environment variables instead
echo 'export ACF_PATH="'$(pwd)'"' >> ~/.bashrc
echo 'export WORKSPACE_ROOT="'$(pwd)'"' >> ~/.bashrc

📋 ¿Necesita ayuda con la configuración? Consulte config/README.md para obtener instrucciones detalladas de configuración.

🚀 Iniciar el Servidor ACF

Elija su modo preferido:

Opción 1: Modo CLI (Comandos Directos)

# Initialize project
./bin/acf init --project-name "My Project" --project-description "Getting started with ACF"

# Start using CLI commands
./bin/acf add --title "First Task" --description "Test ACF functionality" --priority high
./bin/acf list

Servidor MCP (para IDEs)

node ./bin/agentic-control-framework-mcp --workspaceRoot $(pwd)

Opción 3: Modo MCP Cloud (Acceso Remoto)

# Terminal 1: Start ACF MCP Server
node ./bin/agentic-control-framework-mcp --workspaceRoot $(pwd)

# Terminal 2: Start mcp-proxy for HTTP/SSE access
mcp-proxy --port 8080 node ./bin/agentic-control-framework-mcp --workspaceRoot $(pwd)

# Server available at http://localhost:8080

✅ Verificar la Instalación

# Test CLI functionality
./bin/acf --help

# Test MCP server (in separate terminal)
curl -X POST http://localhost:8080/stream -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'  # If using mcp-proxy

# Run test suite
npm test

📋 Modos de Uso

Comparación de Modos de Uso

graph LR
    subgraph "CLI Mode"
        CLI1[Direct Commands]
        CLI2[Automation Scripts]
        CLI3[CI/CD Integration]
    end

    subgraph "Local MCP Mode"
        MCP1[Claude Code]
        MCP2[Cursor IDE]
        MCP3[Claude Desktop]
        MCP4[VS Code]
    end

    subgraph "Remote MCP Mode"
        REM1[Web Clients]
        REM2[Distributed Teams]
        REM3[Cloud Deployment]
        REM4[Multi-Client Access]
    end

    CLI1 --> |Fast & Direct| ACF[ACF Core]
    CLI2 --> |Scriptable| ACF
    CLI3 --> |Automated| ACF

    MCP1 --> |Natural Language| ACF
    MCP2 --> |IDE Integration| ACF
    MCP3 --> |AI Assistant| ACF
    MCP4 --> |Extension| ACF

    REM1 --> |HTTP/SSE| PROXY[mcp-proxy]
    REM2 --> |Remote Access| PROXY
    REM3 --> |Scalable| PROXY
    REM4 --> |Concurrent| PROXY

    PROXY --> ACF

    ACF --> TOOLS[80+ Tools]

    style CLI1 fill:#e1f5fe
    style MCP1 fill:#f3e5f5
    style REM1 fill:#e8f5e8
    style ACF fill:#fff3e0
    style TOOLS fill:#fce4ec

1. 🖥️ Modo CLI (100% Funcionando)

Ideal para: Scripts automatizados, desarrollo local, integración CI/CD

Gestión Básica de Tareas

# Initialize project
cd your-project
./path/to/acf/bin/acf init -n "My Project" -d "Project description"

# Add tasks
./path/to/acf/bin/acf add -t "Implement feature" -d "Add new functionality" -p high

# List tasks
./path/to/acf/bin/acf list

# Update task status
./path/to/acf/bin/acf status 1 inprogress -m "Started working"

# Add subtasks
./path/to/acf/bin/acf add-subtask 1 -t "Write tests"

# Get next actionable task
./path/to/acf/bin/acf next

# Generate task files
./path/to/acf/bin/acf generate

Uso Avanzado de CLI

# Update task details
./path/to/acf/bin/acf update 1 -p medium --related-files "src/main.js,test/main.test.js"

# Get task context
./path/to/acf/bin/acf get-context 1

# Remove completed tasks
./path/to/acf/bin/acf remove 1

# Generate markdown table
./path/to/acf/bin/acf list --table

🎯 Sistema de Prioridades Numéricas (1-1000)

ACF cuenta con un sofisticado sistema de prioridades numéricas que reemplaza las prioridades tradicionales de 4 niveles con una escala flexible de 1-1000, proporcionando control fino e inteligente gestión de dependencias.

Arquitectura del Sistema de Prioridades

graph TD
    subgraph "Priority Ranges"
        CRIT[🚨 Critical<br/>900-1000<br/>Security, Blockers]
        HIGH[🔴 High<br/>700-899<br/>Important Features]
        MED[🟡 Medium<br/>400-699<br/>Standard Work]
        LOW[🟢 Low<br/>1-399<br/>Documentation]
    end

    subgraph "Priority Engine"
        PE[Priority Engine]
        DA[Dependency Analysis]
        TA[Time Decay]
        EW[Effort Weighting]
        UT[Uniqueness Tracker]
    end

    subgraph "Algorithms"
        DB[Dependency Boosts]
        CP[Critical Path]
        DO[Distribution Optimization]
        AR[Auto Recalculation]
    end

    subgraph "Operations"
        BUMP[Bump Priority]
        DEFER[Defer Priority]
        PRIO[Prioritize]
        DEPRIO[Deprioritize]
        RECALC[Recalculate All]
    end

    PE --> DA
    PE --> TA
    PE --> EW
    PE --> UT

    DA --> DB
    DA --> CP
    PE --> DO
    PE --> AR

    BUMP --> PE
    DEFER --> PE
    PRIO --> PE
    DEPRIO --> PE
    RECALC --> PE

    PE --> CRIT
    PE --> HIGH
    PE --> MED
    PE --> LOW

    style CRIT fill:#ffebee
    style HIGH fill:#fff3e0
    style MED fill:#f9fbe7
    style LOW fill:#e8f5e8
    style PE fill:#e3f2fd

Rangos de Prioridad

🟢 Baja (1-399): Documentación, limpieza, funcionalidades deseables
🟡 Media (400-699): Trabajo de desarrollo estándar, funcionalidades regulares
🔴 Alta (700-899): Funcionalidades importantes, errores significativos, tareas urgentes
🚨 Crítica (900-1000): Correcciones de seguridad, problemas bloqueantes, emergencias de producción

Uso Básico de Prioridades

# Using numerical priorities (1-1000)
./bin/acf add "Critical security fix" --priority 950
./bin/acf add "Feature implementation" --priority 650
./bin/acf add "Documentation update" --priority 200

# Using string priorities (backward compatible)
./bin/acf add "Bug fix" --priority high
./bin/acf add "Cleanup task" --priority low

Comandos de Manipulación de Prioridades

# Increase priority by amount
./bin/acf bump 123 --amount 100

# Decrease priority by amount
./bin/acf defer 123 --amount 50

# Set to high priority range (700-899)
./bin/acf prioritize 123

# Set to low priority range (1-399)
./bin/acf deprioritize 123

# View priority statistics and distribution
./bin/acf priority-stats

# Analyze dependencies and critical paths
./bin/acf dependency-analysis

# Trigger intelligent priority recalculation
./bin/acf recalculate-priorities

Funcionalidades Avanzadas de Prioridades

🔄 Unicidad Automática: Cada tarea obtiene un valor de prioridad único
📈 Aumentos por Dependencias: Las tareas con dependientes obtienen automáticamente aumentos de prioridad
🔗 Análisis de Ruta Crítica: Identifica y prioriza tareas de cuello de botella
⚡ Recálculo Inteligente: Optimiza prioridades basándose en dependencias y tiempo
📊 Optimización de Distribución: Previene la agrupación de prioridades y mantiene diferencias significativas

Formatos de Visualización de Prioridades

# Clean table format (default)
./bin/acf list --table
┌─────┬────────────────────┬──────────┐
│ ID  │ Title              │ Priority │
├─────┼────────────────────┼──────────┤
│ 24  │ Critical Bug Fix   │ 950      │
│ 25  │ Feature Request    │ 650      │
└─────┴────────────────────┴──────────┘

# Human-readable with distribution stats
./bin/acf list --human
📊 Priority Distribution:
🚨 Critical (900+): 2 | 🔴 High (700-899): 5 | 🟡 Medium (500-699): 8 | 🟢 Low (<500): 3

Para documentación completa, consulte:

Guía del Sistema de Prioridades - Documentación integral
Guía de Migración - Actualización desde prioridades de cadena

Ejemplos de Automatización

# Daily standup automation
#!/bin/bash
echo "📊 Daily Standup Report"
echo "======================="
./bin/acf list --status inprogress
echo ""
echo "Next Priority Tasks:"
./bin/acf next

# CI/CD Integration
#!/bin/bash
# In your CI pipeline
./bin/acf add -t "Deploy v$VERSION" -d "Deploy to production" -p high
./bin/acf status $TASK_ID done -m "Deployed successfully"

2. 🔗 Modo MCP Local (100% Funcionando)

Ideal para: Integración con IDE (Cursor, Claude Desktop, Claude Code), desarrollo local

Configuración de Cursor

Opción 1: Mediante la Interfaz de Configuración de Cursor (Recomendado)

Abra Cursor → Configuración → MCP
Agregue un nuevo servidor:
- Nombre: acf-local
- Comando: node
- Argumentos: ["/path/to/agentic-control-framework/bin/agentic-control-framework-mcp", "--workspaceRoot", "/path/to/your/project"]
- Entorno:
```
{
  "WORKSPACE_ROOT": "/path/to/your/project",
  "ALLOWED_DIRS": "/path/to/your/project:/tmp",
  "READONLY_MODE": "false"
}
```

Opción 2: Mediante settings.json

{
  "mcp.servers": {
    "acf-local": {
      "command": "node",
      "args": [
        "/path/to/agentic-control-framework/bin/agentic-control-framework-mcp",
        "--workspaceRoot",
        "/path/to/your/project"
      ],
      "env": {
        "WORKSPACE_ROOT": "/path/to/your/project",
        "ALLOWED_DIRS": "/path/to/your/project:/tmp",
        "READONLY_MODE": "false"
      }
    }
  }
}

Configuración de Claude Desktop

⚠️ IMPORTANTE: Use SOLO el Método de Ejecutable Directo - Este es el ÚNICO método confirmado para funcionar de manera confiable

Ubicación del Archivo de Configuración:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Configuración (reemplace con sus rutas reales):

{
  "mcpServers": {
    "agentic-control-framework": {
      "command": "/FULL/PATH/TO/agentic-control-framework/bin/agentic-control-framework-mcp",
      "env": {
        "ACF_PATH": "/FULL/PATH/TO/agentic-control-framework",
        "WORKSPACE_ROOT": "/FULL/PATH/TO/YOUR/WORKSPACE",
        "ALLOWED_DIRS": "/FULL/PATH/TO/YOUR/WORKSPACE:/tmp",
        "READONLY_MODE": "false",
        "BROWSER_HEADLESS": "false",
        "DEFAULT_SHELL": "/bin/bash"
      }
    }
  }
}

⚠️ REQUISITOS CRÍTICOS:

Use RUTAS ABSOLUTAS COMPLETAS - sin rutas relativas ni ~
Establezca ACF_PATH en su directorio de instalación de ACF
Establezca WORKSPACE_ROOT en su espacio de trabajo del proyecto
Asegúrese de que bin/agentic-control-framework-mcp sea ejecutable: chmod +x bin/agentic-control-framework-mcp
❌ NO USE el patrón node + args - falla en Claude Desktop

Configuración de Claude Code

Opción 1: Usando comandos MCP de Claude (Recomendado)

Configure ACF como servidor MCP usando los comandos integrados de Claude:

# Navigate to your project directory
cd your-project-directory

# Add ACF as an MCP server
claude mcp add acf-server \
  -e ACF_PATH="/path/to/agentic-control-framework" \
  -e WORKSPACE_ROOT="$(pwd)" \
  -e READONLY_MODE="false" \
  -e BROWSER_HEADLESS="false" \
  -e DEFAULT_SHELL="/bin/bash" \
  -e NODE_ENV="production" \
  -- node /path/to/agentic-control-framework/bin/agentic-control-framework-mcp --workspaceRoot "$(pwd)"

# Start Claude with ACF tools available
claude

Opción 2: Configuración manual

Agregue a la configuración MCP de su Claude Code:

{
  "mcpServers": {
    "agentic-control-framework": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/path/to/agentic-control-framework/bin/agentic-control-framework-mcp",
        "--workspaceRoot",
        "/path/to/your/project"
      ],
      "env": {
        "ACF_PATH": "/path/to/agentic-control-framework",
        "WORKSPACE_ROOT": "/path/to/your/project",
        "READONLY_MODE": "false",
        "BROWSER_HEADLESS": "false",
        "DEFAULT_SHELL": "/bin/bash",
        "NODE_ENV": "production"
      }
    }
  }
}

Opción 3: Configuración a nivel de proyecto

Para colaboración en equipo con configuración MCP compartida:

# Navigate to your project directory
cd /path/to/your/project

# Add ACF as project-scoped MCP server (shared with team)
claude mcp add acf-project -s project \
  -e ACF_PATH="/path/to/agentic-control-framework" \
  -e WORKSPACE_ROOT="$(pwd)" \
  -e READONLY_MODE="false" \
  -- node /path/to/agentic-control-framework/bin/agentic-control-framework-mcp --workspaceRoot "$(pwd)"

# This creates a .mcp.json file that can be committed to version control
# Team members can then use: claude

# Start Claude with shared ACF tools
claude

Ejemplos de Uso en IDE

Una vez configurado, puede usar lenguaje natural con su asistente de IA:

"Add a new high-priority task for implementing user authentication"

"Create a critical priority task (950) for fixing the security vulnerability"

"List all tasks that are currently in progress"

"Show me priority statistics and distribution of all tasks"

"Bump the priority of task #123 by 100 points"

"Analyze dependencies and show me the critical path"

"Read the contents of src/main.js and create a task for adding error handling"

"Execute the test suite and create a task if there are failures"

"Search for all TODO comments in the codebase and create tasks for them"

"Take a screenshot of the application login page"

"Write a new file called docs/api.md with API documentation"

"Recalculate all task priorities with dependency boosts enabled"

Herramientas Disponibles en Modo MCP

Categoría	Herramientas	Estado
Gestión de Tareas	listTasks, addTask, updateStatus, getNextTask, herramientas de prioridad	✅ Funcionando
Sistema de Archivos	read_file, write_file, list_directory, search_files	✅ Funcionando
Terminal	execute_command, list_processes, kill_process	✅ Funcionando
Navegador	navigate, click, type, screenshot, pdf_save	✅ Funcionando
Búsqueda/Edición	search_code, edit_block	✅ Funcionando
AppleScript	applescript_execute (solo macOS)	✅ Funcionando

3. ☁️ Modo MCP Cloud (100% Funcionando)

Ideal para: Acceso remoto, clientes web, soporte multi-cliente

Configurar Despliegue en la Nube

Desarrollo Local con mcp-proxy

# Install mcp-proxy
npm install -g mcp-proxy

# Start ACF with mcp-proxy
export WORKSPACE_ROOT="/path/to/your/project"
export ALLOWED_DIRS="/path/to/your/project:/tmp"

mcp-proxy --port 8080 node bin/agentic-control-framework-mcp --workspaceRoot "$WORKSPACE_ROOT"

Probar Endpoints HTTP/SSE

# Test connectivity (should return error about session ID - this is expected)
curl -X POST http://localhost:8080/stream \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

# MCP initialization (requires proper session handling)
curl -X POST http://localhost:8080/stream \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

# List available tools
curl -X POST http://localhost:8080/stream \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# Call a tool
curl -X POST http://localhost:8080/stream \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"listTasks","arguments":{}}}'

Configuración de Cursor para Modo Cloud

{
  "mcp.servers": {
    "acf-cloud": {
      "transport": "sse",
      "endpoint": "http://localhost:8080/sse"
    }
  }
}

Desplegar en Google Cloud Platform

# Authenticate
gcloud auth login

# Create project
gcloud projects create acf-your-name-$(date +%s)
export GCP_PROJECT_ID="your-project-id"

# Deploy
./quick-deploy.sh gcp --proxy-only

📚 Casos de Uso de Ejemplo

1. Configuración Automatizada de Proyectos

# CLI approach
./bin/acf init -n "E-commerce App" -d "Build online store"
./bin/acf add -t "Setup project structure" -p high
./bin/acf add -t "Configure database" -p high
./bin/acf add -t "Implement user auth" -p medium
./bin/acf add -t "Add payment integration" -p medium
./bin/acf add -t "Deploy to production" -p low

2. Automatización de Revisión de Código

// MCP approach - ask your AI assistant:
"Search the codebase for any TODO comments and create tasks for each one"
"Read all JavaScript files in src/ and create tasks for any functions missing error handling"
"Take a screenshot of the app and create a task for any UI issues you notice"

3. Integración CI/CD

#!/bin/bash
# In your GitHub Actions workflow
- name: Update project tasks
  run: |
    ./bin/acf add -t "Test release v${{ github.event.release.tag_name }}" -p high
    ./bin/acf status $TASK_ID inprogress -m "Running tests for ${{ github.sha }}"
    
    # Run tests
    npm test
    
    if [ $? -eq 0 ]; then
      ./bin/acf status $TASK_ID done -m "Tests passed"
    else
      ./bin/acf status $TASK_ID error -m "Tests failed"
    fi

4. Automatización de Pruebas de Navegador

// Via MCP in your IDE
"Navigate to our staging site and take screenshots of the login, dashboard, and profile pages"
"Fill out the contact form with test data and take a screenshot of the success page"
"Test the mobile responsiveness by resizing to phone dimensions and taking screenshots"

🔧 Desarrollo y Pruebas

Ejecutar Pruebas

# Comprehensive test suite
node test-simple-tools.js

# Individual component tests
./test-all-tools-comprehensive.sh

Configuración de Desarrollo

# Clone repository
git clone https://github.com/your-org/agentic-control-framework.git
cd agentic-control-framework

# Install dependencies
npm install

# Setup development environment
chmod +x bin/*
export WORKSPACE_ROOT="$(pwd)"
export ALLOWED_DIRS="$(pwd):/tmp"

# Test CLI mode
./bin/acf list

# Test MCP mode
node bin/agentic-control-framework-mcp

🐛 Solución de Problemas

Problemas en Modo CLI

# Check if tasks.json exists
ls -la tasks.json

# Verify permissions
chmod +x bin/acf

# Check Node.js version
node --version  # Should be 22+

Problemas en Modo MCP

# Check environment variables
echo $WORKSPACE_ROOT
echo $ALLOWED_DIRS

# Test MCP server directly
node bin/agentic-control-framework-mcp --help

# Check file permissions
ls -la bin/agentic-control-framework-mcp

Problemas en Modo Cloud

# Check mcp-proxy installation
npm list -g mcp-proxy

# Test proxy connectivity
curl -X POST http://localhost:8080/stream -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

# Check proxy logs
mcp-proxy --port 8080 --debug node bin/agentic-control-framework-mcp --workspaceRoot $(pwd)

🤝 Contribuciones

Haga un fork del repositorio
Cree una rama de funcionalidad: git checkout -b feature/amazing-feature
Pruebe sus cambios: node test-simple-tools.js
Haga commit de sus cambios: git commit -m 'Add amazing feature'
Haga push a la rama: git push origin feature/amazing-feature
Abra una Solicitud de Extracción (Pull Request)

Pautas de Pruebas

Todas las nuevas herramientas deben tener pruebas CLI, MCP y Cloud
Mantenga o mejore la cobertura de pruebas actual (68%+)
Agregue ejemplos a este README para nuevas funcionalidades

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENSE para más detalles.

🙏 Agradecimientos

Protocolo MCP: Por la comunicación estandarizada de herramientas de IA
Playwright: Por las capacidades de automatización de navegador
Commander.js: Por la excelente interfaz CLI
mcp-proxy: Por la funcionalidad de puente HTTP/SSE

🚀 ¿Listo para construir su agente autónomo? ¡Elija su modo y comience!

Modo	Caso de Uso	Tiempo de Configuración	Estado	Resultados de Pruebas
CLI	Scripts, automatización	2 minutos	✅ Listo para Producción	100% de Tasa de Éxito
MCP Local	Integración IDE	5 minutos	✅ Listo para Producción	25/25 Pruebas Aprobadas
MCP Cloud	Acceso remoto	15 minutos	✅ Listo para Producción	Integración Completa Verificada

Para resultados detallados de pruebas y hoja de ruta de mejoras, consulte ACF-TESTING-SUMMARY.md.