Agentic Workflow Orchestrator (AWO)

Creator: Abhilash Chadhar (FutureAtoms) Source Code: agentic-control-framework

An AI-centric coordination substrate (CLI + MCP endpoint) providing over eighty utilities for sophisticated context manipulation—covering retrieval, code modification, runtime execution, persistent state maintenance, and browser interaction. Optimized for consumption by Claude Code, Cursor, Codex, and VS Code extensions operating under the MCP framework. This documentation reflects the current, validated state of the codebase.

CLI Entry Point: bin/acf
MCP Communication Server: bin/agentic-control-framework-mcp → dispatched from src/mcp/server.js
Client Configuration Templates: config/examples/
Testing Suites: npm run test:cli, npm test

Core Capabilities

What the package provides:

Comprehensive work item supervisor supporting granular control over priorities, dependencies, sub-components, and standardized templates.
A robust command-line interface (bin/acf).
A resilient MCP service layer (implementing JSON-RPC over stdio) validated against Claude Desktop/Code, Cursor, and Codex clients.

Key Operational Strengths: - 🔧 Extensive Toolset: Access to 80+ discrete utilities spanning task logistics, filesystem access, terminal control, web interface automation, and native system interaction (AppleScript). - 🎯 Versatile Deployment: Supports CLI, Local MCP, and Cloud MCP modes for maximum operational adaptability. - 🔗 Broad Interoperability: Seamless functionality with Claude Code, Cursor, Claude Desktop, VS Code, and any client adhering to the MCP specification. - ☁️ Cloud Native Support: Configuration streamlined for deployment on GCP, Railway, and Fly.io, including auto-scaling preparation. - 🚀 Quality Assurance: Backed by an exhaustive automated test matrix confirming core functionality. - ⚡ Latency Profile: Achieves fast interaction times, typically between 200 and 1000 milliseconds, with high stability. - 🛡️ Security Enforced: Incorporates mandatory filesystem sandboxing, strict permission modeling, and secure default settings. - 📋 Protocol Adherence: Fully compliant with MCP specification dated 2025-03-26, featuring proper tool annotations, descriptive titles, and capability declaration.

Resolving Context Engineering Challenges

AWO transforms the inherently complex, multi-artifact, iterative nature of software development into discrete, addressable 'contextual units.' These units are readily requested, refined, and acted upon by Large Language Models. This is achieved by synthesizing a task dependency graph, exposing rich context APIs, providing granular retrieval/editing instruments, and enforcing operational guardrails, all accessible via CLI or MCP.

Task Graph as Definitive Record
Every atomic work unit (task/subtask) maintains an identifier, execution status, a quantifiable priority score (1–1000), antecedent dependencies, associated file metadata, chronological activity records, and precise timestamps.
The built-in priority mechanism incorporates temporal decay factors and effort estimation to ensure the 'next action' is always dynamically relevant.
Dynamic, On-Demand Context Surfaces
getContext utility returns the precise context block for a task, including file metadata and the complete history log.
generateTaskFiles procedure materializes individual Markdown files per task (located in tasks/), complemented by tasks-table.md for a holistic project overview.
The CLI's context <id> command renders a human-readable summary suitable for both human review and LLM consumption.
Retrieval and Editing Utilities (for Context Materialization and Application)
Retrieval: Tools like search_code, tree, list_directory, get_file_info, read_file/read_multiple_files, and read_url.
Modification: edit_block ensures surgical replacements by demanding explicit old/new blocks, drastically reducing unintended state corruption.
Validation: Terminal interfaces (execute_command, list_processes, session management) allow verification of context assumptions (e.g., running tests or builds).
Synchronization and Temporal Freshness
A file watcher maintains consistency between tasks.json and per-task artifacts; change detection is debounced; tasks-table.md is kept current.
Guardrails: Filesystem scope is strictly limited via allowedDirectories and readonlyMode.
Planning from Specification Documents (Optional)
Utilities such as parsePrd, expandTask, and reviseTasks utilize generative models (e.g., Gemini) to translate Product Requirement Documents or change requests into structured work items, which are then integrated into the traceable task graph.

Collectively, this architecture establishes a predictable 'context feedback loop': strategize → fetch context → modify/validate → persist state. Every step is tool-addressable, enabling reliable control by MCP clients (Claude Code, Cursor, Codex, VS Code).

End-to-End Context Operation Recipes

Initiating from a PRD
tools/call: parsePrd { filePath } initiates task creation with calculated priorities/dependencies → subsequently running generateTaskFiles for stakeholder sign-off.
Focusing the Agent on the Immediate Next Step
tools/call: getNextTask retrieves the highest-ranking actionable item considering constraints.
tools/call: getContext { id } fetches the task metadata; followed by necessary artifact retrieval like read_file/search_code.
Executing Safe, Atomic Code Edits
Retrieval: Employ search_code to pinpoint the exact code section; confirm content via read_file.
Application: Use edit_block { file_path, old_string, new_string, normalize_whitespace }.
Verification: Confirm stability with execute_command { command: "npm test" } or relevant test suites.
Maintaining Current Context State
Activate monitoring with start_file_watcher → apply modifications to files or task definitions → check status with file_watcher_status → deactivate monitoring via stop_file_watcher.

Durable State Management (Activity Logs in tasks.json)

AWO preserves a durable, searchable history of agentic (and human) actions, including rationale. This persistent memory resides in .acf/tasks.json and associated per-task files:

Data Persistence Details
For every unit of work: createdAt, updatedAt, and an activityLog[] array containing timestamped annotations.
Any modification to a task's attributes (status, title, priority, dependencies, associated files) results in a new log entry and updates the updatedAt timestamp.
AI-driven workflows (parsePrd, etc.) explicitly record their execution narrative.
LLM-Driven Memory Logging
CLI: State changes include an optional --message "..." flag to append a note to the activity log.
- Example: acf status 12 inprogress --message "Initiated implementation phase"
- Example: acf update 12 --priority 750 --message "Escalated priority based on review feedback"
MCP: The message field is included in tool invocations targeting state modification.
- tools/call { name: "updateStatus", arguments: { id: "12", newStatus: "done", message: "Verification tests passed; ready for commit" } }
- tools/call { name: "updateTask", arguments: { id: "12", priority: 820, message: "Priority raised following stakeholder consensus" } }
Memory Consumption Methods
acf context <id> (CLI) outputs a rich, narrative summary including recent activityLog segments.
tools/call: getContext { id } (MCP) returns the raw structured data, perfect for prompt inclusion.
generateTaskFiles generates Markdown snapshots; tasks-table.md offers a live, synchronized overview of .acf/tasks.json state.

Quick Initiation Guide

Prerequisites
Runtime Environment: Node.js (version 18 or newer)
macOS Dependency (Optional): Required for AppleScript utilities. Playwright browser runtimes must be installed: npx playwright install.
Installation Steps
Navigate to the project root: cd agentic-control-framework
Install dependencies: npm ci
CLI Operation (Local)
Initialize new context: ./bin/acf init --project-name "PilotRun" --project-description "Initial setup test"
Add first unit of work: ./bin/acf add -t "Define core services" -p high
Review state: ./bin/acf list --format human
MCP Server Execution (For IDEs)
Start the stdio server: node ./bin/agentic-control-framework-mcp --workspaceRoot $(pwd)
Client configuration: Utilize the provided samples within config/examples/ for connecting Claude Code, Cursor, and Codex clients.

Documentation Index

Main Overview: docs/README.md
Repository Layout: docs/PROJECT-STRUCTURE.md
System Blueprint: docs/architecture/overview.md
MCP Communication Protocol: docs/architecture/mcp-integration.md

Implemented MCP Utilities (Tool Registry)

Tool Groupings Summary

mindmap
  root((AWO Tools Set<br/>80+ Total)) 
    Core Orchestration
      Task Logic
        listTasks
        addTask
        updateStatus
        getNextTask
      Priority Mechanics
        recalculatePriorities
        getPriorityStatistics
        bumpTaskPriority
        prioritizeTask
      State Sync
        initializeFileWatcher
        stopFileWatcher
        forceSyncTaskFiles
      Templates
        getPriorityTemplates
        addTaskWithTemplate
    File System Interop
      CRUD
        read_file
        write_file
        copy_file
        delete_file
      Navigation
        list_directory
        create_directory
        tree
        search_files
    Runtime Execution
      Command Invocation
        execute_command
        read_output
        force_terminate
      Process Supervision
        list_processes
        kill_process
    Web Interface Control (Playwright)
      Traversal
        browser_navigate
        browser_navigate_back
        browser_close
      Interaction Layer
        browser_click
        browser_type
        browser_hover
        browser_drag
      Data Capture
        browser_take_screenshot
        browser_pdf_save
        browser_snapshot
      Session Management
        browser_tab_list
        browser_tab_new
        browser_tab_close
    Code Manipulation & Discovery
      search_code
      edit_block
    System Utilities
      System Calls
        applescript_execute
      Settings
        get_config
        set_config_value

Core administrative utilities include: initProject, addTask, addSubtask, listTasks, updateTask, updateStatus, removeTask, getNextTask, generateTaskFiles, recalculatePriorities, and various priority analysis functions.

Auxiliary functions include standard file I/O (read_file, write_file) and command execution stubs.

Operational Configuration Parameters

Essential Environment Variables
WORKSPACE_ROOT: Default directory context for CLI/MCP operations.
ALLOWED_DIRS: Supplementary directories permitted for filesystem interaction (colon-separated).
READONLY_MODE: Setting to true strictly prohibits all write operations.
ACF_PATH: Override location for the AWO installation root.
Feature Toggles (Optional)
GEMINI_API_KEY: Activates generative planning tools (parsePrd, expandTask, reviseTasks).
ACF_SKIP_POSTINSTALL=1: Bypasses post-installation setup routines.
ACF_SKIP_PLAYWRIGHT=1: Prevents downloading large browser binaries during setup.
ACF_INSTALL_SHARP=1 or ACF_INSTALL_ALL=1: Enables optional sharp library dependency.
ACF_ENABLE_BROWSER_TOOLS=1: Permits execution of Playwright automation routines (macOS default).
ACF_ENABLE_APPLESCRIPT=1: Permits execution of native AppleScript operations (macOS only).

Security Posture and Safeguards

Filesystem operations are strictly bounded by the allowedDirectories list and the readonlyMode flag.
External resource fetching (read_url) requires explicit invocation; modification tools like edit_block mandate providing both the original and target content to prevent accidental corruption.
Terminal invocation incorporates blacklists for dangerous commands, enforced timeouts, and session visibility/termination controls.

High-Level CLI Command Set

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

Tool Categories (Detailed Counts)

Terminal Interfaces (6) ✅
Web Automation (25) ✅
Discovery & Editing (2) ✅
macOS Scripting (1) ✅
Configuration Management (2) ✅

Repository Layout

The structure emphasizes modularity and separation of concerns:

agentic-control-framework/
├── 📁 bin/           # Executable scripts (CLI, MCP Server entry)
├── 📁 src/           # Primary implementation logic and tool handlers
├── 📁 docs/          # Exhaustive documentation resources
├── 📁 test/          # Testing frameworks and execution suites
├── 📁 config/        # Configuration blueprints and client examples
├── 📁 scripts/       # Maintenance, deployment, and utility scripts
├── 📁 deployment/    # Infrastructure-as-Code definitions (Cloud)
├── 📁 tasks/         # Runtime storage for project work items (.acf/tasks.json)
├── 📁 templates/     # Blueprints for standardized task creation
├── 📁 public/        # Static client assets
└── 📁 data/          # Persistent data storage

Operational Status Dashboard

Metric	State	Commentary
CLI Interface	✅ Fully Functional	All core task logistics and utility calls confirmed operational.
Local MCP Endpoint	✅ Fully Functional	All core utilities successfully invoked via stdio protocol.
Cloud MCP Endpoint	✅ Fully Functional	HTTP/SSE proxy integration and remote execution validated.
IDE Bindings	✅ Confirmed Compatible	Tested with Cursor, Claude Desktop, Claude Code, and standard VS Code extensions.
Core Task Tools	✅ 25/25 Active	Task structure, priority engine, and context generation components verified.
Filesystem Utilities	✅ 14/14 Active	File manipulation, directory browsing, and content search functional.
Browser Automation	✅ 25/25 Active	Full Playwright suite coverage, including capture mechanisms.
Terminal Executors	✅ 6/6 Active	Command execution and process supervision confirmed.
Code Search/Edit	✅ 3/3 Active	Code discovery (ripgrep) and surgical text replacement validated.
System Adapters	✅ 7/7 Active	AppleScript bridge and configuration setters verified.
MCP Protocol	✅ Fully Supported	Implements JSON-RPC 2.0; defaults to 2025-03-26 standard; supports 2024-11-05 fallback.