Agentic Control Framework (ACF)

Author: Abhilash Chadhar (FutureAtoms)

Repository: agentic-control-framework

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 ` 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 ` (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

mindmap
  root((ACF Tools79 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

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** - 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** - GCP deployment
• **Docker** - Container deployment
• **Remote Setup** - Remote client configuration

🧪 Testing & Quality

• **Cloud MCP Testing** - Latest comprehensive testing
• **Tool Verification** - All 79 tools verified
• **Security Testing** - Security validation
• **Test Framework** - Testing infrastructure

🏗️ Technical Reference

• **System Architecture** - Complete architecture with diagrams
• **Tool Reference** - Complete tool documentation
• **Priority System** - Advanced task prioritization
• **MCP Integration** - Protocol implementation details
• **Project Structure** - Repository organization
• **Quick Reference** - Essential commands

📋 Complete Documentation Index

• **Master Documentation Index** - Complete catalog of all documentation
• **Documentation Index** - Quick reference index

📊 Current Status

*All tests passing! See 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**

🚀 Quick Start

> 📋 Need detailed setup instructions? See our comprehensive Platform Setup Guide for Windows, macOS, and Ubuntu with step-by-step instructions.

Prerequisites

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

# 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 for detailed setup instructions.

🚀 Start ACF Server

Choose your preferred mode:

Option 1: CLI Mode (Direct Commands)

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

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

Option 3: Cloud MCP Mode (Remote Access)

# 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

# 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

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

# 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

# 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

graph TD
    subgraph "Priority Ranges"
        CRIT[🚨 Critical900-1000Security, Blockers]
        HIGH[🔴 High700-899Important Features]
        MED[🟡 Medium400-699Standard Work]
        LOW[🟢 Low1-399Documentation]
    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

# 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

# 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

# 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** - Comprehensive documentation
• **Migration Guide** - Upgrading from string priorities

Automation Examples

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

{
       "WORKSPACE_ROOT": "/path/to/your/project",
       "ALLOWED_DIRS": "/path/to/your/project:/tmp",
       "READONLY_MODE": "false"
     }

Option 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"
      }
    }
  }
}

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

{
  "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:

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

{
  "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:

# 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

3. ☁️ Cloud MCP Mode (100% Working)

Perfect for: Remote access, web clients, multi-client support

Setup Cloud Deployment

Local Development with 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"

Test HTTP/SSE Endpoints

# 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

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

Deploy to 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

📚 Example Use Cases

1. Automated Project Setup

# 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

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

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

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

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

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

Development Setup

# 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

# 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

# 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

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

For detailed test results and improvement roadmap, see ACF-TESTING-SUMMARY.md.