README.md

Task Orchestrator

🎯 Transform Your Meta-Agent Into An Orchestration Engine

Task Orchestrator transforms meta-agents from traffic controllers into symphony conductors - enabling outstanding task execution results every time.

Our Sacred Mission: Provide the reliable, safe, efficient, and robust orchestration layer that guarantees excellence through perfect coordination.

The Problem We Solve

When meta-agents delegate to specialized sub-agents, they lose 30% productivity to coordination overhead. Context gets lost. Agents wait unnecessarily. Work gets redone.

The Solution: Three Unique Capabilities

1. Shared Context - Requirements travel WITH tasks automatically
2. Private Reasoning - Sub-agents think deeply without noise
3. Automatic Unblocking - Dependencies resolve instantly

Your Results With Task Orchestrator

• 95%+ Task Completion (vs 60-70% baseline)
• 4-5x Faster Delivery (parallel vs sequential)
• <5% Rework Rate (vs 25% baseline)
• 90%+ Agent Utilization (no idle waiting)

🚀 Commander's Intent: The Secret to 95% Completion

Every task delegation includes THREE elements:

./tm add "Build authentication" --assignee backend_agent \
  --context "WHY: Secure user data access
             WHAT: Login, 2FA, password reset, sessions
             DONE: Users can securely access accounts"

WHY → Agents understand importance → Better decisions WHAT → Clear deliverables → No guessing
DONE → Success criteria → Right the first time

⚡ Quick Start (60 Seconds)

# 1. In YOUR project root
cd /path/to/your-project

# 2. Add tm from a release artifact or local install
cp /path/to/task-orchestrator/tm ./tm
chmod +x ./tm

# 3. Initialize Task Orchestrator in this project
./tm init

# 4. Set agent identity (required for coordination)
export TM_AGENT_ID="orchestrator_agent"

# 5. Create AI Agent Workflow with Commander's Intent
BACKEND=$(./tm add "Build auth API" --assignee backend_agent \
  -d "WHY: Secure foundation, WHAT: OAuth2/JWT/sessions, DONE: Users can login safely" | grep -o '[a-f0-9]\{8\}')

FRONTEND=$(./tm add "Create login UI" --assignee frontend_agent --depends-on $BACKEND | grep -o '[a-f0-9]\{8\}')

# 6. Watch Real-Time Orchestration
./tm watch  # See instant updates as agents work

# When backend completes, frontend auto-unblocks!
./tm complete $BACKEND  # Frontend starts immediately

🎯 Core Commands

# Set agent identity first (always required)
export TM_AGENT_ID="your_agent_name"

# Create task with Commander's Intent (use -d for description)
./tm add "Your task" -d "WHY: reason, WHAT: deliverables, DONE: success" --assignee agent_name

# Manage dependencies
./tm add "Frontend" --depends-on $BACKEND_ID

# Share context between agents
./tm share $TASK_ID "API endpoints: /users, /products"

# Private reasoning
./tm note $TASK_ID "Using Redis for caching"

# Real-time monitoring
./tm watch  # Instant notifications

# Complete and auto-unblock
./tm complete $TASK_ID

📊 Why It Works

• Zero Dependencies: Python stdlib only - installs anywhere
• Instant Setup: One command (./tm init) and you're running
• Scales Infinitely: Our LEAN architecture handles 100+ agents
• Works Today: No waiting for features - everything works now

📚 Documentation & Resources

Essential Guides

• User Guide - Complete manual with best practices
• Developer Guide - Architecture and contribution guide
• API Reference - Complete technical documentation
• AI Agent Discovery - How agents automatically find and use Task Orchestrator
• Agent Instruction Snippets - Copy/paste blocks for AGENTS.md and CLAUDE.md
• Official Agent Skill - Installable Agent Skills package for Codex/Claude Code style tools
• Agent Skill Install Guide - How to install/use the packaged skill from repo or release artifacts
• Troubleshooting - Solutions to common issues
• Claude Code Integration - REQUIRED for Claude Code users

Working Examples

Run these directly to learn by doing:

python3 docs/examples/basic_usage.py          # Core concepts
python3 docs/examples/dependency_management.py # Complex workflows
python3 docs/examples/multi_agent_workflow.py  # Team coordination

🚀 Installation

# Use in your own project
cd /path/to/your-project
cp /path/to/task-orchestrator/tm ./tm
chmod +x ./tm
./tm init

# Contributor path (develop task-orchestrator itself)
git clone https://github.com/T72/task-orchestrator.git
cd task-orchestrator
./tm init

🎯 Transform Your Meta-Agent Today

Stop losing 30% productivity to coordination overhead.

Task Orchestrator turns your meta-agent into an orchestration engine that delivers:

• 95%+ task completion (vs 60-70% baseline)
• 4-5x faster delivery through true parallelism
• <5% rework with Commander's Intent

The secret? Three simple words: WHY, WHAT, DONE.

# Set your agent identity first
export TM_AGENT_ID="orchestrator_agent"

# Your next task with Commander's Intent
./tm add "Build authentication" --assignee backend_agent \
  -d "WHY: Secure user data, WHAT: Login/2FA/sessions, DONE: Users can login safely"

Ready to orchestrate? Star us on GitHub.

---

Task Orchestrator v2.9.2 - Transform your meta-agent into an orchestration engine.