Agentic Control Framework (ACF)

Um kit de ferramentas para desenvolvimento de agentes autônomos com ferramentas para gerenciamento de tarefas, operações de sistema de arquivos, automação de navegador e controle de terminal.

GitHub

Experimente este MCPPatrocinado

Documentação

Agentic Control Framework (ACF)

Autor: Abhilash Chadhar (FutureAtoms) Repositório: agentic-control-framework

Camada de orquestração nativa para IA (CLI + MCP) com mais de 80 ferramentas para engenharia de contexto—recuperação, edição de código, automação de navegador, orquestração de terminal e memória persistente—projetada para Claude Code, Cursor, Codex e VS Code. Este README reflete o código atual e as integrações testadas.

Entrada CLI: bin/acf
Servidor MCP: bin/agentic-control-framework-mcp → src/mcp/server.js
Exemplos de configuração de cliente: config/examples/
Testes: npm run test:cli, npm test

O que está incluído

O que vem na caixa

Gerenciador de tarefas com prioridades, dependências, subtarefas, modelos
CLI com comandos ricos
Servidor MCP (JSON‑RPC sobre stdio) testado com Claude Desktop/Code, Cursor, Codex

Principais recursos:

🔧 Mais de 80 ferramentas especializadas: Gerenciamento de tarefas, sistema de arquivos, terminal, automação de navegador, integração AppleScript
🎯 3 modos de uso: CLI, MCP local, MCP na nuvem para máxima flexibilidade
🔗 Compatibilidade universal: Funciona com Claude Code, Cursor, Claude Desktop, VS Code e qualquer cliente compatível com MCP
☁️ Pronto para nuvem: Implante em GCP, Railway, Fly.io com autoescalonamento
🚀 Pronto para produção: Cobertura abrangente de suíte de testes nas ferramentas principais
⚡ Alto desempenho: Tempo médio de resposta de 200-1000ms, excelente confiabilidade
🛡️ Segurança em primeiro lugar: Proteções do sistema de arquivos, sistemas de permissão e padrões seguros
📋 Compatível com MCP 2025-03-26: Protocolo padrão com títulos de ferramentas, anotações e capacidades adequadas

Como o ACF resolve a engenharia de contexto

O ACF transforma a realidade confusa, multi-arquivo e multi-etapa do trabalho de software em "unidades de contexto" precisas e endereçáveis que os LLMs podem solicitar, refinar e sobre as quais podem agir. Ele faz isso combinando um grafo de tarefas, superfícies de contexto ricas, ferramentas de recuperação/edição e proteções — tudo acessível via CLI e MCP.

Grafo de tarefas como fonte da verdade
- Cada tarefa/subtarefa tem um ID, status, prioridade numérica (1–1000), dependências, arquivos relacionados, registro de atividades e carimbos de data/hora.
- O mecanismo de prioridade suporta decaimento temporal e ponderação de esforço para manter "o que vem a seguir" dinamicamente correto.
Superfícies de contexto ricas e sob demanda
- getContext retorna o bloco de contexto exato da tarefa/subtarefa (incluindo metadados de arquivos relacionados e registro de atividades).
- generateTaskFiles materializa um arquivo Markdown por tarefa (tasks/), e tasks-table.md fornece uma visão geral do projeto.
- CLI context <id> imprime um resumo legível para humanos e LLMs.
Ferramentas de recuperação e edição (para construção e aplicação de contexto)
- Recuperação: search_code, tree, list_directory, get_file_info, read_file/read_multiple_files, read_url.
- Edição: edit_block aplica substituições cirúrgicas usando blocos explícitos de antigo/novo (minimiza desvios acidentais).
- Execução: ferramentas de terminal (execute_command, list_processes, sessões) para verificar suposições de contexto (testes, builds).
Sincronização e atualização
- O observador de arquivos sincroniza tasks.json e arquivos por tarefa; detecção de alterações com debounce; tasks-table.md mantido atualizado.
- Proteções: allowedDirectories e readonlyMode restringem o escopo do sistema de arquivos acessível.
Planejamento a partir de documentos de produto (opcional)
- parsePrd, expandTask, reviseTasks convertem PRDs ou solicitações de mudança em tarefas estruturadas via Gemini e depois as incorporam de volta ao grafo de tarefas para execução rastreável.

Juntos, isso fornece um "loop de contexto" repetível: planejar → recuperar → editar/verificar → atualizar estado, com cada etapa acessível por ferramentas para que clientes MCP (Claude Code, Cursor, Codex, VS Code) possam conduzi-lo de forma confiável.

Receitas de contexto de ponta a ponta

Inicialização a partir de PRD
- tools/call: parsePrd { filePath } → tarefas criadas com prioridades e dependências → generateTaskFiles para revisão.
Focar um modelo na próxima ação
- tools/call: getNextTask → obtenha a próxima tarefa acionável considerando dependências/prioridade.
- tools/call: getContext { id } → busque o bloco da tarefa; depois read_file/search_code para o código ao redor.
Mudança de código segura e cirúrgica
- Recuperar: search_code para identificar o bloco exato; verifique com read_file.
- Aplicar: edit_block { file_path, old_string, new_string, normalize_whitespace }.
- Verificar: execute_command { command: "npm test" } ou comandos específicos da suíte.
Manter o contexto atualizado
- start_file_watcher → modifique arquivos ou tarefas → file_watcher_status para estatísticas → stop_file_watcher quando terminar.

Memória persistente (registros de atividades em tasks.json)

O ACF mantém uma memória durável e consultável do que o agente (ou humano) fez, quando e por quê. Essa memória persistente vive em .acf/tasks.json e em arquivos por tarefa:

O que é armazenado
- Para cada tarefa e subtarefa: entradas createdAt, updatedAt e activityLog[] com mensagens com carimbo de data/hora.
- Cada alteração em uma tarefa (status, título, descrição, prioridade, dependências, arquivos relacionados) acrescenta uma entrada de log e incrementa updatedAt.
- Fluxos de IA (parsePrd, expandTask, reviseTasks) também escrevem mensagens claras de atividade.
Como os LLMs escrevem memória
- CLI: inclua --message "..." ao alterar o estado para acrescentar uma nota humana/LLM ao registro de atividades.
  - Exemplos:
    - acf status 12 inprogress --message "Started implementing parser"
    - acf update 12 --priority 750 --message "Raised priority due to deadline"
- MCP: passe message nos argumentos de tools/call para updateStatus ou 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" } }
Como consumir memória
- acf context <id> (CLI) imprime um contexto rico e legível por humanos, incluindo os activityLog recentes.
- tools/call: getContext { id } (MCP) retorna o mesmo bloco estruturado, ideal para prompts de LLM.
- generateTaskFiles produz instantâneos em markdown; tasks-table.md mostra uma visão geral ao vivo sincronizada de .acf/tasks.json por meio do observador de arquivos.

Início rápido

Requisitos
- Node.js 18+
- macOS para ferramentas AppleScript (opcional). Navegadores Playwright se usar ferramentas de navegador: npx playwright install.
Instalação
- 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)
- Use exemplos de configuração de cliente em config/examples/ para Claude Code, Cursor e Codex.

Documentação

Visão geral
- Índice principal de documentação: docs/README.md
- Estrutura do projeto: docs/PROJECT-STRUCTURE.md
- Visão geral da arquitetura: docs/architecture/overview.md
- Detalhes de integração MCP: docs/architecture/mcp-integration.md
Integrações (clientes MCP)
- Guias de conexão: docs/INTEGRATIONS.md
- Exemplos de configuração:
  - Claude Code (VS Code): config/examples/claude_code.json
  - Cursor (projeto/global): config/examples/cursor.mcp.json
  - Codex CLI (TOML): config/examples/codex.config.toml
- Auxiliar do Claude (notas de desenvolvimento): CLAUDE.md
Referência
- Exemplos completos de CLI: docs/reference/cli_examples.md
- Exemplos de solicitação/resposta MCP (gerados automaticamente): docs/reference/mcp_examples.md
Testes e validação
- Resumo e notas de teste: docs/TESTING_SUMMARY.md
- Validador de comandos de documentação: scripts/testing/validate-doc-commands.sh
Propostas e ideias
- Proposta de indexação de workspace: docs/workspace-indexing-proposal.md

Ferramentas MCP (implementadas)

Visão geral das categorias de ferramentas

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

Ferramentas principais de tarefas

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

Utilitários

read_file, write_file
execute_command (stub para testes)

Nota: As ferramentas são anunciadas via tools/list de src/mcp/server.js, e cada ferramenta listada tem um manipulador no servidor.

Configuração

Variáveis de ambiente principais
- WORKSPACE_ROOT: caminho padrão do workspace usado por CLI/MCP
- ALLOWED_DIRS: diretórios adicionais permitidos (delimitados por caminho)
- READONLY_MODE: defina como true para desabilitar operações de escrita
- ACF_PATH: substituição da raiz do projeto para bins
Sinalizadores opcionais/de recursos
- GEMINI_API_KEY: habilita ferramentas com suporte de IA (parsePrd, expandTask, reviseTasks)
- ACF_SKIP_POSTINSTALL=1: pular todas as etapas de pós-instalação
- ACF_SKIP_PLAYWRIGHT=1: pular downloads pesados de navegadores Playwright
- ACF_INSTALL_SHARP=1 ou ACF_INSTALL_ALL=1: instalar sharp opcional
- ACF_ENABLE_BROWSER_TOOLS=1: habilitar testes de navegador Playwright (padrão macOS)
- ACF_ENABLE_APPLESCRIPT=1: habilitar testes AppleScript (somente macOS)

Segurança e proteções

O acesso ao sistema de arquivos é restringido por allowedDirectories e readonlyMode.
Leituras de URL (read_url) são explícitas; edições usam edit_block com conteúdo antigo/novo para minimizar alterações não intencionais.
A execução de terminal suporta comandos bloqueados e tempos limite; sessões podem ser listadas/encerradas.

Comandos CLI (nível 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

Ferramentas de terminal (6 ferramentas) ✅

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

Ferramentas de automação de navegador (25 ferramentas) ✅

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

Ferramentas de busca e edição (2 ferramentas) ✅

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

Ferramentas AppleScript (1 ferramenta) ✅

macOS Automation:
- applescript_execute: Run AppleScript for system integration

Ferramentas de configuração (2 ferramentas) ✅

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

Estrutura do projeto

O repositório é organizado seguindo práticas padrão com separação clara 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

Veja também: docs/PROJECT-STRUCTURE.md

Integrações

Use os modelos prontos para copiar em 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

Mais detalhes: docs/INTEGRATIONS.md

☁️ Implantação na nuvem

Guia de implantação - Visão geral completa da implantação

Testes

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

Sinalizadores de ambiente

ACF_SKIP_POSTINSTALL=1 para pular todas as etapas de pós-instalação
ACF_SKIP_PLAYWRIGHT=1 para pular downloads de navegadores Playwright na instalação
ACF_INSTALL_SHARP=1 (ou ACF_INSTALL_ALL=1) para instalar sharp opcional
ACF_ENABLE_BROWSER_TOOLS=1 para habilitar testes de navegador Playwright (somente macOS por padrão)
ACF_ENABLE_APPLESCRIPT=1 para habilitar testes AppleScript (somente macOS)

Controle de plataforma (seguro para CI por padrão)

Os testes MCP de navegador e AppleScript são ignorados por padrão e no Windows/Linux.
Para executá-los localmente no macOS, defina as variáveis de ambiente ACF_ENABLE_* correspondentes.
Google Cloud Run - Implantação no GCP
Docker - Implantação em contêiner
Configuração remota - Configuração de cliente remoto

🧪 Testes e qualidade

Testes MCP na nuvem - Testes abrangentes mais recentes
Verificação de ferramentas - Todas as 79 ferramentas verificadas
Testes de segurança - Validação de segurança
Estrutura de testes - Infraestrutura de testes

🏗️ Referência técnica

Arquitetura do sistema - Arquitetura completa com diagramas
Referência de ferramentas - Documentação completa das ferramentas
Sistema de prioridades - Priorização avançada de tarefas
Integração MCP - Detalhes da implementação do protocolo
Estrutura do projeto - Organização do repositório
Referência rápida - Comandos essenciais

📋 Índice completo de documentação

Índice mestre de documentação - Catálogo completo de toda a documentação
Índice de documentação - Índice de referência rápida

📊 Status atual

Componente	Status	Detalhes
Modo CLI	✅ 100% Funcional	Todas as ferramentas de gerenciamento de tarefas e ferramentas principais funcionais
MCP Local	✅ 100% Funcional	Todas as ferramentas principais verificadas via protocolo MCP
MCP na Nuvem	✅ 100% Funcional	Integração mcp-proxy, transporte HTTP/SSE verificado
Integrações IDE	✅ 100% Funcional	Cursor, Claude Desktop, Claude Code, VS Code testados
Ferramentas Principais ACF	✅ 25/25 Funcionais	Gerenciamento de tarefas, sistema de prioridade, geração de arquivos
Ferramentas de Sistema de Arquivos	✅ 14/14 Funcionais	Operações de arquivo, gerenciamento de diretórios, busca
Ferramentas de Navegador	✅ 25/25 Funcionais	Automação Playwright, capturas de tela, geração de PDF
Ferramentas de Terminal	✅ 6/6 Funcionais	Execução de comandos, gerenciamento de processos
Ferramentas de Busca/Edição	✅ 3/3 Funcionais	Busca de código com ripgrep, edição cirúrgica
Ferramentas de Sistema	✅ 7/7 Funcionais	AppleScript, gerenciamento de configuração
Protocolo MCP	✅ Suportado	JSON-RPC 2.0; MCP 2025-03-26 (padrão) e 2024-11-05

Todos os testes passando! Consulte ACF-TESTING-SUMMARY.md para resultados detalhados dos testes

🧪 Resultados de Testes e Garantia de Qualidade

Última Execução de Testes: 100% de Taxa de Aprovação (Todos os Testes Passando)

✅ Cobertura Abrangente de Testes

Testes de Ferramentas CLI: ✅ APROVADO - Todas as operações de gerenciamento de tarefas funcionando
Testes de Ferramentas MCP Local: ✅ APROVADO - 3/3 testes principais, 100% de taxa de sucesso
Testes de Ferramentas MCP stdio: ✅ APROVADO - 25/25 testes abrangentes, 100% de taxa de sucesso
Testes de Ferramentas Especializadas: ✅ APROVADO - Ferramentas Filesystem, Browser, AppleScript, Search, Edit
Testes de Integração: ✅ APROVADO - proxy MCP, configurações de cliente, endpoints SSE
Testes de Ponta a Ponta: ✅ APROVADO - Verificação de saúde do sistema, todos os módulos carregando

📊 Métricas de Desempenho

Tempo Médio de Resposta: 24ms
Tempo Máximo de Resposta: 439ms
Sem Respostas Lentas: 0 respostas >1s
Sem Respostas Grandes: 0 respostas >10KB
Avaliação de Qualidade: EXCELENTE (100% de taxa de aprovação)

🔧 Recursos Validados

Fluxo de trabalho de gerenciamento de tarefas com dependências
Sistema de prioridade e recálculo
Conformidade e comunicação com o protocolo MCP
Automação de navegador com Playwright
Integração AppleScript (macOS)
Operações de filesystem com proteções de segurança
Funcionalidade das ferramentas de busca e edição
Geração de configuração de cliente (Cursor, Claude Desktop, VS Code)

🧪 Testes e Verificação

Testes Abrangentes Concluídos (Janeiro de 2025)

O ACF passou por testes extensivos para garantir prontidão para produção:

Verificação de Ferramentas ✅

Testes extensivos de ferramentas: Ferramentas principais verificadas via protocolo MCP
100% de Taxa de Sucesso: Todas as ferramentas funcionando corretamente em todas as categorias
Desempenho Validado: Tempo médio de resposta de 4ms, sem respostas lentas

Testes de Integração IDE ✅

Claude Code: 15/15 testes de compatibilidade aprovados
Cursor IDE: Configuração e descoberta de ferramentas verificadas
Claude Desktop: Transporte SSE e integração mcp-proxy testados
VS Code: Configurações das extensões Cline e Continue verificadas

Conformidade com o Protocolo ✅

MCP 2025-03-26: Versão padrão do protocolo; compatível com versões anteriores da 2024-11-05
JSON-RPC 2.0: Implementação completa do protocolo
Tratamento de Erros: Códigos de erro padrão e degradação graciosa

📊 Ver Relatório Completo de Testes

🚀 Início Rápido

📋 Precisa de instruções detalhadas de configuração? Consulte nosso abrangente Guia de Configuração de Plataforma para Windows, macOS e Ubuntu com instruções passo a passo.

Pré-requisitos

# 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/*

⚙️ Configuração

Copie e personalize os modelos de configuração:

# 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

📋 Precisa de ajuda com a configuração? Consulte config/README.md para instruções detalhadas de configuração.

🚀 Iniciar o Servidor ACF

Escolha seu modo preferido:

Opção 1: Modo CLI (Comandos Diretos)

# 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)

Opção 3: Modo MCP na Nuvem (Acesso 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 Instalação

# 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

Comparação 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% Funcional)

Perfeito para: Scripts automatizados, desenvolvimento local, integração CI/CD

Gerenciamento Básico de Tarefas

# 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 Avançado da 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 Prioridade Numérica (1-1000)

O ACF possui um sistema sofisticado de prioridade numérica que substitui as prioridades tradicionais de 4 níveis por uma escala flexível de 1-1000, proporcionando controle granular e gerenciamento inteligente de dependências.

Arquitetura do Sistema de Prioridade

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

Faixas de Prioridade

🟢 Baixa (1-399): Documentação, limpeza, recursos opcionais
🟡 Média (400-699): Trabalho padrão de desenvolvimento, recursos regulares
🔴 Alta (700-899): Recursos importantes, bugs significativos, tarefas urgentes
🚨 Crítica (900-1000): Correções de segurança, problemas bloqueantes, emergências de produção

Uso Básico de Prioridade

# 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 Manipulação de Prioridade

# 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

Recursos Avançados de Prioridade

🔄 Unicidade Automática: Cada tarefa recebe um valor de prioridade único
📈 Aumentos por Dependência: Tarefas com dependentes recebem automaticamente aumentos de prioridade
🔗 Análise de Caminho Crítico: Identifica e prioriza tarefas gargalo
⚡ Recálculo Inteligente: Otimiza prioridades com base em dependências e tempo
📊 Otimização de Distribuição: Evita agrupamento de prioridades e mantém diferenças significativas

Formatos de Exibição de Prioridade

# 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 documentação completa, consulte:

Guia do Sistema de Prioridade - Documentação abrangente
Guia de Migração - Atualização de prioridades de string

Exemplos de Automação

# 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% Funcional)

Perfeito para: Integração com IDE (Cursor, Claude Desktop, Claude Code), desenvolvimento local

Configuração do Cursor

Opção 1: Via Interface de Configurações do Cursor (Recomendado)

Abra Cursor → Configurações → MCP
Adicione um novo servidor:
- Nome: acf-local
- Comando: node
- Argumentos: ["/path/to/agentic-control-framework/bin/agentic-control-framework-mcp", "--workspaceRoot", "/path/to/your/project"]
- Ambiente:
```
{
  "WORKSPACE_ROOT": "/path/to/your/project",
  "ALLOWED_DIRS": "/path/to/your/project:/tmp",
  "READONLY_MODE": "false"
}
```

Opção 2: Via 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"
      }
    }
  }
}

Configuração do Claude Desktop

⚠️ IMPORTANTE: Use SOMENTE o Método de Executável Direto - Este é o ÚNICO método confirmado para funcionar de forma confiável

Localização do Arquivo de Configuração:

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

Configuração (substitua pelos seus caminhos reais):

{
  "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 CAMINHOS ABSOLUTOS COMPLETOS - sem caminhos relativos ou ~
Defina ACF_PATH para o diretório de instalação do seu ACF
Defina WORKSPACE_ROOT para o espaço de trabalho do seu projeto
Garanta que bin/agentic-control-framework-mcp seja executável: chmod +x bin/agentic-control-framework-mcp
❌ NÃO USE o padrão node + args - ele falha no Claude Desktop

Configuração do Claude Code

Opção 1: Usando comandos MCP do Claude (Recomendado)

Configure o ACF como um servidor MCP usando os comandos integrados do 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

Opção 2: Configuração manual

Adicione às configurações MCP do seu 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"
      }
    }
  }
}

Opção 3: Configuração no escopo do projeto

Para colaboração em equipe com configuração MCP compartilhada:

# 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

Exemplos de Uso na IDE

Após a configuração, você pode usar linguagem natural com seu assistente 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"

Ferramentas Disponíveis no Modo MCP

Categoria	Ferramentas	Status
Gerenciamento de Tarefas	listTasks, addTask, updateStatus, getNextTask, ferramentas de prioridade	✅ Funcional
Filesystem	read_file, write_file, list_directory, search_files	✅ Funcional
Terminal	execute_command, list_processes, kill_process	✅ Funcional
Navegador	navigate, click, type, screenshot, pdf_save	✅ Funcional
Busca/Edição	search_code, edit_block	✅ Funcional
AppleScript	applescript_execute (somente macOS)	✅ Funcional

3. ☁️ Modo MCP na Nuvem (100% Funcional)

Perfeito para: Acesso remoto, clientes web, suporte a múltiplos clientes

Configurar Implantação na Nuvem

Desenvolvimento Local com 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"

Testar 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":{}}}'

Configuração do Cursor para Modo Nuvem

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

Implantar no 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

📚 Exemplos de Casos de Uso

1. Configuração Automatizada de Projeto

# 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. Automação de Revisão 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. Integração 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. Automação de Testes 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"

🔧 Desenvolvimento e Testes

Executar Testes

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

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

Configuração de Desenvolvimento

# 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

🐛 Solução de Problemas

Problemas no 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 no 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 no Modo Nuvem

# 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)

🤝 Contribuindo

Faça um fork do repositório
Crie um branch de recurso: git checkout -b feature/amazing-feature
Teste suas alterações: node test-simple-tools.js
Faça commit das suas alterações: git commit -m 'Add amazing feature'
Envie para o branch: git push origin feature/amazing-feature
Abra um Pull Request

Diretrizes de Testes

Todas as novas ferramentas devem ter testes CLI, MCP e Cloud
Mantenha ou melhore a cobertura de testes atual (68%+)
Adicione exemplos a este README para novas funcionalidades

📄 Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

🙏 Agradecimentos

Protocolo MCP: Pela comunicação padronizada entre ferramentas de IA
Playwright: Pelas capacidades de automação de navegador
Commander.js: Pela excelente interface CLI
mcp-proxy: Pela funcionalidade de ponte HTTP/SSE

🚀 Pronto para construir seu agente autônomo? Escolha seu modo e comece!

Modo	Caso de Uso	Tempo de Configuração	Status	Resultados de Testes
CLI	Scripts, automação	2 minutos	✅ Pronto para Produção	100% de Taxa de Aprovação
MCP Local	Integração IDE	5 minutos	✅ Pronto para Produção	25/25 Testes Aprovados
MCP na Nuvem	Acesso remoto	15 minutos	✅ Pronto para Produção	Integração Completa Verificada

Para resultados detalhados de testes e roteiro de melhorias, consulte ACF-TESTING-SUMMARY.md.