Agentic Control Framework (ACF)

# Agentic Control Framework (ACF) **Author:** Abhilash Chadhar (FutureAtoms) **Repository:** [agentic-control-framework](https://github.com/FutureAtoms/agentic-control-framework)          [](https://smithery.ai/server/@FutureAtoms/agentic-control-framework) [](https://github.com/FutureAtoms/agentic-control-framework/actions/workflows/ci.yml) AI‑native orchestration layer (CLI + MCP) with 80+ tools for context engineering—retrieval, code editing, browser automation, terminal orchestration, and persistent memory—designed for Claude Code, Cursor, Codex, and VS Code. This README reflects the current code and tested integrations. - CLI entry: `bin/acf` - MCP server: `bin/agentic-control-framework-mcp` → `src/mcp/server.js` - Example client configs: `config/examples/` - Tests: `npm run test:cli`, `npm test` ## What’s included What’s in the box - Task manager with priorities, dependencies, subtasks, templates - CLI with rich commands - MCP server (JSON‑RPC over stdio) tested with Claude Desktop/Code, Cursor, Codex **Key Features:** - 🔧 **80+ Specialized Tools**: Task management, filesystem, terminal, browser automation, AppleScript integration - 🎯 **3 Usage Modes**: CLI, Local MCP, Cloud MCP for maximum flexibility - 🔗 **Universal Compatibility**: Works with Claude Code, Cursor, Claude Desktop, VS Code, and any MCP-compatible client - ☁️ **Cloud-Ready**: Deploy to GCP, Railway, Fly.io with auto-scaling - 🚀 **Production-Ready**: Comprehensive test suite coverage across core tools - ⚡ **High Performance**: Average response time 200-1000ms, excellent reliability - 🛡️ **Security-First**: Filesystem guardrails, permission systems, and secure defaults - 📋 **MCP 2025-03-26 Compliant**: Default protocol with tool titles, annotations, and proper capabilities ## How ACF Solves Context Engineering ACF turns the messy, multi-file, multi-step reality of software work into precise, addressable “context units” that LLMs can request, refine, and act on. It does this by combining a task graph, rich context surfaces, retrieval/edit tools, and guardrails — all accessible via CLI and MCP. - Task Graph as Source of Truth - Each task/subtask has an ID, status, numeric priority (1–1000), dependencies, related files, activity log, timestamps. - Priority engine supports time decay and effort weighting to keep “what’s next” dynamically correct. - Rich, On‑Demand Context Surfaces - `getContext` returns the exact task/subtask context block (including related files metadata and activity log). - `generateTaskFiles` materializes one Markdown file per task (tasks/), and `tasks-table.md` gives a project overview. - CLI `context <id>` prints a human summary for humans and LLMs. - Retrieval and Editing Tools (for context building and application) - Retrieval: `search_code`, `tree`, `list_directory`, `get_file_info`, `read_file`/`read_multiple_files`, `read_url`. - Editing: `edit_block` applies surgical replacements using explicit old/new blocks (minimizes accidental drift). - Execution: terminal tools (`execute_command`, `list_processes`, sessions) to verify context assumptions (tests, builds). - Synchronization & Freshness - File watcher syncs `tasks.json` and per‑task files; debounced change detection; `tasks-table.md` kept fresh. - Guards: `allowedDirectories` and `readonlyMode` restrict the accessible filesystem scope. - Planning from Product Docs (optional) - `parsePrd`, `expandTask`, `reviseTasks` convert PRDs or change requests into structured tasks via Gemini, then fold back into the task graph for traceable execution. Together, this provides a repeatable “context loop”: plan → retrieve → edit/verify → update state, with every step addressable by tools so MCP clients (Claude Code, Cursor, Codex, VS Code) can drive it reliably. ### End‑to‑End Context Recipes - Bootstrap from PRD - `tools/call: parsePrd { filePath }` → tasks created with priorities and dependencies → `generateTaskFiles` for review. - Focus a Model on the Next Action - `tools/call: getNextTask` → get the next actionable task considering dependencies/priority. - `tools/call: getContext { id }` → fetch the task block; then `read_file`/`search_code` for surrounding code. - Safe, Surgical Code Change - Retrieve: `search_code` to identify exact block; verify with `read_file`. - Apply: `edit_block { file_path, old_string, new_string, normalize_whitespace }`. - Verify: `execute_command { command: "npm test" }` or suite‑specific commands. - Keep Context Fresh - `start_file_watcher` → modify files or tasks → `file_watcher_status` for stats → `stop_file_watcher` when done. ### Persistent Memory (Activity Logs in tasks.json) ACF keeps a durable, queryable memory of what the agent (or human) did, when, and why. This persistent memory lives in `.acf/tasks.json` and per‑task files: - What is stored - For every task and subtask: `createdAt`, `updatedAt`, and `activityLog[]` entries with timestamped messages. - Each change to a task (status, title, description, priority, dependencies, related files) appends a log entry and bumps `updatedAt`. - AI flows (`parsePrd`, `expandTask`, `reviseTasks`) also write clear activity messages. - How LLMs write memory - CLI: include `--message "..."` when changing state to append a human/LLM note to the activity log. - Examples: - `acf status 12 inprogress --message "Started implementing parser"` - `acf update 12 --priority 750 --message "Raised priority due to deadline"` - MCP: pass `message` in tools/call arguments for `updateStatus` or `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" } }` - How to consume memory - `acf context <id>` (CLI) prints a rich, human‑readable context including the recent `activityLog`. - `tools/call: getContext { id }` (MCP) returns the same structured block, ideal for LLM prompts. - `generateTaskFiles` produces markdown snapshots; `tasks-table.md` shows a live overview synced from `.acf/tasks.json` via the file watcher. ## Quick Start - Requirements - Node.js 18+ - macOS for AppleScript tools (optional). Playwright browsers if using browser tools: `npx playwright install`. - Install - `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` - MCP Server (stdio) - `node ./bin/agentic-control-framework-mcp --workspaceRoot $(pwd)` - Use example client configs in `config/examples/` for Claude Code, Cursor, and Codex. ## Documentation - Overview - Primary docs index: `docs/README.md` - Project structure: `docs/PROJECT-STRUCTURE.md` - Architecture overview: `docs/architecture/overview.md` - MCP integration details: `docs/architecture/mcp-integration.md` - Integrations (MCP Clients) - Connection guides: `docs/INTEGRATIONS.md` - Example configs: - Claude Code (VS Code): `config/examples/claude_code.json` - Cursor (project/global): `config/examples/cursor.mcp.json` - Codex CLI (TOML): `config/examples/codex.config.toml` - Claude helper (dev notes): `CLAUDE.md` - Reference - CLI complete examples: `docs/reference/cli_examples.md` - MCP request/response examples (auto‑generated): `docs/reference/mcp_examples.md` - Testing & Validation - Test summary and notes: `docs/TESTING_SUMMARY.md` - Doc command validator: `scripts/testing/validate-doc-commands.sh` - Proposals & Ideas - Workspace indexing proposal: `docs/workspace-indexing-proposal.md` ## MCP tools (implemented) ### Tool Categories Overview ```mermaid 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 ``` Core task tools - initProject, addTask, addSubtask, listTasks, updateTask, updateStatus, removeTask, getNextTask - generateTaskFiles, recalculatePriorities, getPriorityStatistics, getDependencyAnalysis - getPriorityTemplates, calculatePriorityFromTemplate, suggestPriorityTemplate, addTaskWithTemplate Utilities - read_file, write_file - execute_command (stub for tests) Note: Tools are advertised via `tools/list` from `src/mcp/server.js`, and each listed tool has a handler in the server. ## Configuration - Core environment variables - `WORKSPACE_ROOT`: default workspace path used by CLI/MCP - `ALLOWED_DIRS`: additional allowed directories (path-delimited) - `READONLY_MODE`: set to `true` to disable write operations - `ACF_PATH`: project root override for bins - Optional/feature flags - `GEMINI_API_KEY`: enable AI-backed tools (`parsePrd`, `expandTask`, `reviseTasks`) - `ACF_SKIP_POSTINSTALL=1`: skip all postinstall steps - `ACF_SKIP_PLAYWRIGHT=1`: skip heavy Playwright browser downloads - `ACF_INSTALL_SHARP=1` or `ACF_INSTALL_ALL=1`: install optional `sharp` - `ACF_ENABLE_BROWSER_TOOLS=1`: enable Playwright browser tests (macOS default) - `ACF_ENABLE_APPLESCRIPT=1`: enable AppleScript tests (macOS only) ## Security & Guardrails - Filesystem access is constrained by `allowedDirectories` and `readonlyMode`. - URL reads (`read_url`) are explicit; edits use `edit_block` with old/new content to minimize unintended changes. - Terminal execution supports blocked commands and timeouts; sessions can be listed/terminated. ## CLI commands (high level) - 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 ### Terminal Tools (6 tools) ✅ ``` 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 ``` ### Browser Automation Tools (25 tools) ✅ ``` 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 ``` ### Search & Edit Tools (2 tools) ✅ ``` Code Operations: - search_code: Advanced text/code search with ripgrep - edit_block: Surgical text replacements ``` ### AppleScript Tools (1 tool) ✅ ``` macOS Automation: - applescript_execute: Run AppleScript for system integration ``` ### Configuration Tools (2 tools) ✅ ``` Server Management: - get_config: Get server configuration - set_config_value: Update configuration values ``` [](https://mseep.ai/app/futureatoms-agentic-control-framework) ## Project structure The repository is organized following standard practices with clean separation of concerns: ``` 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 ``` See also: docs/PROJECT-STRUCTURE.md ## Integrations Use the ready-to-copy templates in `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` More details: docs/INTEGRATIONS.md ### ☁️ Cloud Deployment - **[Deployment Guide](docs/deployment/deployment-guide.md)** - Complete deployment overview ## Testing - MCP tests: `npm test` - CLI tests: `npm run test:cli` - Coverage: `npm run coverage:all` Environment flags - `ACF_SKIP_POSTINSTALL=1` to skip all postinstall steps - `ACF_SKIP_PLAYWRIGHT=1` to skip Playwright browser downloads on install - `ACF_INSTALL_SHARP=1` (or `ACF_INSTALL_ALL=1`) to install optional `sharp` - `ACF_ENABLE_BROWSER_TOOLS=1` to enable Playwright browser tests (macOS only by default) - `ACF_ENABLE_APPLESCRIPT=1` to enable AppleScript tests (macOS only) Platform gating (CI-safe by default) - Browser and AppleScript MCP tests are skipped by default and on Windows/Linux. - To run them locally on macOS, set the corresponding `ACF_ENABLE_*` env vars. - **[Google Cloud Run](docs/deployment/gcp-deployment-guide.md)** - GCP deployment - **[Docker](docs/deployment/docker.md)** - Container deployment - **[Remote Setup](docs/deployment/remote-client-setup.md)** - Remote client configuration ### 🧪 Testing & Quality - **[Cloud MCP Testing](docs/testing/cloud-mcp-comprehensive-test-report.md)** - Latest comprehensive testing - **[Tool Verification](docs/testing/tool-category-verification-report.md)** - All 79 tools verified - **[Security Testing](docs/testing/authentication-security-test-results.md)** - Security validation - **[Test Framework](test/README.md)** - Testing infrastructure ### 🏗️ Technical Reference - **[System Architecture](docs/architecture/overview.md)** - Complete architecture with diagrams - **[Tool Reference](docs/architecture/tool-reference.md)** - Complete tool documentation - **[Priority System](docs/architecture/priority-system.md)** - Advanced task prioritization - **[MCP Integration](docs/architecture/mcp-integration.md)** - Protocol implementation details - **[Project Structure](docs/PROJECT-STRUCTURE.md)** - Repository organization - **[Quick Reference](docs/reference/QUICK-REFERENCE.md)** - Essential commands ### 📋 Complete Documentation Index - **[Master Documentation Index](docs/MASTER-DOCUMENTATION-INDEX.md)** - Complete catalog of all documentation - **[Documentation Index](DOCUMENTATION-INDEX.md)** - Quick reference index ## 📊 Current Status | Component | Status | Details | |-----------|--------|---------| | **CLI Mode** | ✅ 100% Working | All task management and core tools functional | | **Local MCP** | ✅ 100% Working | All core tools verified via MCP protocol | | **Cloud MCP** | ✅ 100% Working | mcp-proxy integration, HTTP/SSE transport verified | | **IDE Integrations** | ✅ 100% Working | Cursor, Claude Desktop, Claude Code, VS Code tested | | **Core ACF Tools** | ✅ 25/25 Working | Task management, priority system, file generation | | **Filesystem Tools** | ✅ 14/14 Working | File operations, directory management, search | | **Browser Tools** | ✅ 25/25 Working | Playwright automation, screenshots, PDF generation | | **Terminal Tools** | ✅ 6/6 Working | Command execution, process management | | **Search/Edit Tools** | ✅ 3/3 Working | Code search with ripgrep, surgical editing | | **System Tools** | ✅ 7/7 Working | AppleScript, configuration management | | **MCP Protocol** | ✅ Supported | JSON-RPC 2.0; MCP 2025-03-26 (default) and 2024-11-05 | *All tests passing! See [ACF-TESTING-SUMMARY.md](./ACF-TESTING-SUMMARY.md) for detailed test results* ## 🧪 Test Results & Quality Assurance **Latest Test Run: 100% Pass Rate (All Tests Passing)** ### ✅ Comprehensive Test Coverage - **CLI Tool Tests**: ✅ PASSED - All task management operations working - **Local MCP Tool Tests**: ✅ PASSED - 3/3 core tests, 100% success rate - **stdio MCP Tool Tests**: ✅ PASSED - 25/25 comprehensive tests, 100% success rate - **Specialized Tool Tests**: ✅ PASSED - Filesystem, Browser, AppleScript, Search, Edit tools - **Integration Tests**: ✅ PASSED - MCP proxy, client configurations, SSE endpoints - **End-to-End Tests**: ✅ PASSED - System health check, all modules loading ### 📊 Performance Metrics - **Average Response Time**: 24ms - **Maximum Response Time**: 439ms - **No Slow Responses**: 0 responses >1s - **No Large Responses**: 0 responses >10KB - **Quality Assessment**: EXCELLENT (100% pass rate) ### 🔧 Validated Features - Task management workflow with dependencies - Priority system and recalculation - MCP protocol compliance and communication - Browser automation with Playwright - AppleScript integration (macOS) - Filesystem operations with security guardrails - Search and edit tool functionality - Client configuration generation (Cursor, Claude Desktop, VS Code) ## 🧪 Testing & Verification **Comprehensive Testing Completed (January 2025)** ACF has undergone extensive testing to ensure production readiness: ### Tool Verification ✅ - Extensive tool testing: Core tools verified via MCP protocol - **100% Success Rate**: All tools working correctly across all categories - **Performance Validated**: Average 4ms response time, no slow responses ### IDE Integration Testing ✅ - **Claude Code**: 15/15 compatibility tests passed - **Cursor IDE**: Configuration and tool discovery verified - **Claude Desktop**: SSE transport and mcp-proxy integration tested - **VS Code**: Cline and Continue extension configurations verified ### Protocol Compliance ✅ - **MCP 2025-03-26**: Default protocol version; backward compatible with 2024-11-05 - **JSON-RPC 2.0**: Full protocol implementation - **Error Handling**: Standard error codes and graceful degradation **📊 [View Complete Testing Report](COMPREHENSIVE-TESTING-REPORT.md)** ## 🚀 Quick Start > **📋 Need detailed setup instructions?** See our comprehensive [Platform Setup Guide](PLATFORM-SETUP-GUIDE.md) for Windows, macOS, and Ubuntu with step-by-step instructions. ### Prerequisites ```bash # 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/* ``` ### ⚙️ Configuration Setup Copy and customize configuration templates: ```bash # 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 ``` > **📋 Need help with configuration?** See [config/README.md](config/README.md) for detailed setup instructions. ### 🚀 Start ACF Server Choose your preferred mode: #### Option 1: CLI Mode (Direct Commands) ```bash # 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 ``` #### MCP server (for IDEs) ```bash node ./bin/agentic-control-framework-mcp --workspaceRoot $(pwd) ``` #### Option 3: Cloud MCP Mode (Remote Access) ```bash # 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 ``` ### ✅ Verify Installation ```bash # 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 ``` ## 📋 Usage Modes ### Usage Mode Comparison ```mermaid 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. 🖥️ CLI Mode (100% Working) **Perfect for**: Automated scripts, local development, CI/CD integration ### Basic Task Management ```bash # 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 ``` ### Advanced CLI Usage ```bash # 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 ``` ## 🎯 Numerical Priority System (1-1000) ACF features a sophisticated numerical priority system that replaces traditional 4-level priorities with a flexible 1-1000 scale, providing fine-grained control and intelligent dependency management. ### Priority System Architecture ```mermaid 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 ``` ### Priority Ranges - **🟢 Low (1-399)**: Documentation, cleanup, nice-to-have features - **🟡 Medium (400-699)**: Standard development work, regular features - **🔴 High (700-899)**: Important features, significant bugs, urgent tasks - **🚨 Critical (900-1000)**: Security fixes, blocking issues, production emergencies ### Basic Priority Usage ```bash # 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 ``` ### Priority Manipulation Commands ```bash # 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 ``` ### Advanced Priority Features - **🔄 Automatic Uniqueness**: Every task gets a unique priority value - **📈 Dependency Boosts**: Tasks with dependents automatically get priority increases - **🔗 Critical Path Analysis**: Identifies and prioritizes bottleneck tasks - **⚡ Intelligent Recalculation**: Optimizes priorities based on dependencies and time - **📊 Distribution Optimization**: Prevents priority clustering and maintains meaningful differences ### Priority Display Formats ```bash # 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 ``` For complete documentation, see: - **[Priority System Guide](docs/priority-system.md)** - Comprehensive documentation - **[Migration Guide](docs/migration-guide.md)** - Upgrading from string priorities ### Automation Examples ```bash # 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. 🔗 Local MCP Mode (100% Working) **Perfect for**: IDE integration (Cursor, Claude Desktop, Claude Code), local development ### Cursor Configuration #### Option 1: Via Cursor Settings UI (Recommended) 1. Open Cursor → Settings → MCP 2. Add new server: - **Name**: `acf-local` - **Command**: `node` - **Args**: `["/path/to/agentic-control-framework/bin/agentic-control-framework-mcp", "--workspaceRoot", "/path/to/your/project"]` - **Environment**: ```json { "WORKSPACE_ROOT": "/path/to/your/project", "ALLOWED_DIRS": "/path/to/your/project:/tmp", "READONLY_MODE": "false" } ``` #### Option 2: Via settings.json ```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" } } } } ``` ### Claude Desktop Configuration **⚠️ IMPORTANT: Use ONLY the Direct Executable Method - This is the ONLY method confirmed to work reliably** **Configuration File Location:** - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - **Linux**: `~/.config/Claude/claude_desktop_config.json` **Configuration (replace with your actual paths):** ```json { "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" } } } } ``` **⚠️ CRITICAL REQUIREMENTS:** - Use **FULL ABSOLUTE PATHS** - no relative paths or `~` - Set `ACF_PATH` to your ACF installation directory - Set `WORKSPACE_ROOT` to your project workspace - Ensure `bin/agentic-control-framework-mcp` is executable: `chmod +x bin/agentic-control-framework-mcp` - **❌ DO NOT USE** the `node` + `args` pattern - it fails in Claude Desktop ### Claude Code Configuration #### Option 1: Using Claude MCP commands (Recommended) Configure ACF as an MCP server using Claude's built-in commands: ```bash # 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 ``` #### Option 2: Manual configuration Add to your Claude Code MCP settings: ```json { "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" } } } } ``` #### Option 3: Project-scoped setup For team collaboration with shared MCP configuration: ```bash # 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 ``` ### Usage Examples in IDE Once configured, you can use natural language with your AI assistant: ``` "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" ``` ### Available Tools in MCP Mode | Category | Tools | Status | |----------|-------|--------| | **Task Management** | listTasks, addTask, updateStatus, getNextTask, priority tools | ✅ Working | | **Filesystem** | read_file, write_file, list_directory, search_files | ✅ Working | | **Terminal** | execute_command, list_processes, kill_process | ✅ Working | | **Browser** | navigate, click, type, screenshot, pdf_save | ✅ Working | | **Search/Edit** | search_code, edit_block | ✅ Working | | **AppleScript** | applescript_execute (macOS only) | ✅ Working | ## 3. ☁️ Cloud MCP Mode (100% Working) **Perfect for**: Remote access, web clients, multi-client support ### Setup Cloud Deployment #### Local Development with mcp-proxy ```bash # 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" ``` #### Test HTTP/SSE Endpoints ```bash # 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":{}}}' ``` ### Cursor Configuration for Cloud Mode ```json { "mcp.servers": { "acf-cloud": { "transport": "sse", "endpoint": "http://localhost:8080/sse" } } } ``` ### Deploy to Google Cloud Platform ```bash # 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 ``` ## 📚 Example Use Cases ### 1. Automated Project Setup ```bash # 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. Code Review Automation ```javascript // 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. CI/CD Integration ```bash #!/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. Browser Testing Automation ```javascript // 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" ``` ## 🔧 Development & Testing ### Run Tests ```bash # Comprehensive test suite node test-simple-tools.js # Individual component tests ./test-all-tools-comprehensive.sh ``` ### Development Setup ```bash # 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 ``` ## 🐛 Troubleshooting ### CLI Mode Issues ```bash # Check if tasks.json exists ls -la tasks.json # Verify permissions chmod +x bin/acf # Check Node.js version node --version # Should be 22+ ``` ### MCP Mode Issues ```bash # 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 ``` ### Cloud Mode Issues ```bash # 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) ``` ## 🤝 Contributing 1. **Fork** the repository 2. **Create** a feature branch: `git checkout -b feature/amazing-feature` 3. **Test** your changes: `node test-simple-tools.js` 4. **Commit** your changes: `git commit -m 'Add amazing feature'` 5. **Push** to the branch: `git push origin feature/amazing-feature` 6. **Open** a Pull Request ### Testing Guidelines - All new tools must have CLI, MCP, and Cloud tests - Maintain or improve the current test coverage (68%+) - Add examples to this README for new functionality ## 📄 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## 🙏 Acknowledgments - **MCP Protocol**: For standardized AI-tool communication - **Playwright**: For browser automation capabilities - **Commander.js**: For excellent CLI interface - **mcp-proxy**: For HTTP/SSE bridge functionality --- **🚀 Ready to build your autonomous agent? Choose your mode and get started!** | Mode | Use Case | Setup Time | Status | Test Results | |------|----------|------------|--------|--------------| | **CLI** | Scripts, automation | 2 minutes | ✅ Production Ready | 100% Pass Rate | | **Local MCP** | IDE integration | 5 minutes | ✅ Production Ready | 25/25 Tests Passing | | **Cloud MCP** | Remote access | 15 minutes | ✅ Production Ready | Full Integration Verified | For detailed test results and improvement roadmap, see [ACF-TESTING-SUMMARY.md](./ACF-TESTING-SUMMARY.md).