CODITECT Task Orchestrator

Atomic task management and agentic orchestration for AI-assisted development.

---

Overview

The CODITECT Task Orchestrator decomposes large project plans into atomic, database-stored tasks with intelligent agent assignment, dependency resolution, and execution tracking.

Metric	Value
Architecture	Hierarchical Task Network (HTN)
Storage	PostgreSQL + pgvector + Neo4j
Assignment	Semantic matching + affinity scoring
Execution	Circuit breaker + retry patterns

---

Problem Statement

Large project planning documents (e.g., PILOT plan at 380KB) create:

1. Token inefficiency - 47% context window consumed by plan alone
2. No execution tracking - Status scattered across markdown checkboxes
3. Manual assignment - No automated agent-task matching
4. No dependency graph - Blocking relationships not enforced
5. No learning loop - Agent performance not tracked

---

Solution

┌─────────────────────────────────────────────────────────────────┐
│                    TASK ORCHESTRATOR                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Markdown Plan    ──▶   Atomic Tasks DB   ──▶   Agent Dispatch  │
│  (PILOT.md)            (PostgreSQL)             (MoE Routing)   │
│                                                                  │
│  Features:                                                       │
│  • Hierarchical decomposition (Track.Section.Task.Subtask)      │
│  • Dependency graph (Neo4j)                                     │
│  • Semantic search (pgvector embeddings)                        │
│  • Agent affinity scoring                                       │
│  • Circuit breaker patterns                                     │
│  • Execution metrics & learning                                 │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

---

Directory Structure

coditect-task-orchestrator/
├── README.md                    # This file
├── CLAUDE.md                    # AI agent context
│
├── docs/
│   ├── architecture/
│   │   └── adrs/
│   │       ├── adr-069-atomic-task-management.md
│   │       ├── adr-070-task-dependency-graph.md
│   │       ├── adr-071-agent-task-matching.md
│   │       ├── adr-072-execution-tracking.md
│   │       └── adr-073-learning-feedback-loop.md
│   │
│   └── design/
│       ├── tdd-task-orchestrator.md
│       └── sdd-task-orchestrator.md
│
├── src/
│   ├── core/
│   │   ├── __init__.py
│   │   ├── models.py            # SQLAlchemy models
│   │   ├── decomposer.py        # Plan → atomic tasks
│   │   ├── dependency_resolver.py
│   │   └── task_queue.py
│   │
│   ├── api/
│   │   ├── __init__.py
│   │   ├── routes.py            # REST API
│   │   └── schemas.py           # Pydantic models
│   │
│   └── workers/
│       ├── __init__.py
│       ├── dispatcher.py        # Agent assignment
│       ├── executor.py          # Task execution
│       └── metrics_collector.py
│
├── tests/
│   ├── test_decomposer.py
│   ├── test_dependency_resolver.py
│   └── test_dispatcher.py
│
├── scripts/
│   ├── decompose_pilot_plan.py
│   ├── import_tasks.py
│   └── generate_embeddings.py
│
├── config/
│   ├── task_types.json
│   ├── agent_capabilities.json
│   └── priority_rules.json
│
└── migrations/
    ├── 001_create_atomic_tasks.sql
    ├── 002_create_dependencies.sql
    └── 003_create_agent_affinity.sql

---

Quick Start

1. Decompose PILOT Plan

python scripts/decompose_pilot_plan.py \
  --input ~/.coditect/internal/project/plans/PILOT-PARALLEL-EXECUTION-PLAN.md \
  --output tasks.json

2. Import to Database

python scripts/import_tasks.py \
  --input tasks.json \
  --db postgresql://localhost/coditect_tasks

3. Generate Embeddings

python scripts/generate_embeddings.py \
  --model text-embedding-3-small \
  --batch-size 100

4. Query Ready Tasks

# Via API
curl http://localhost:8080/api/v1/tasks/ready

# Via CLI
python -m src.core.task_queue --list-ready

---

Core Concepts

Atomic Task

The smallest unit of work that can be:

• Assigned to a single agent
• Completed in a single session
• Verified independently
• Rolled back atomically

Task Hierarchy

Track (A-G)
└── Section (A.1, A.2, ...)
    └── Task (A.1.1, A.1.2, ...)
        └── Subtask (A.1.1.1, A.1.1.2, ...)  ← Atomic level

Dependency Types

Type	Description	Enforcement
blocks	Must complete before downstream	Hard
informs	Provides context for downstream	Soft
relates	Related but independent	None

Agent Matching

affinity_score = (
    semantic_similarity * 0.4 +
    historical_success_rate * 0.3 +
    domain_expertise * 0.2 +
    availability * 0.1
)

---

Integration Points

System	Integration
CODITECT Core	/orient loads ready tasks
Cloud Backend	Task sync via API
Session Logs	Execution tracking
MoE System	Agent dispatch

---

Related Documentation

Local ADRs

Document	Purpose
ADR-069	Atomic task management design
ADR-070	Dependency graph storage
ADR-071	Agent matching algorithm
ADR-072	Execution tracking
ADR-073	Learning feedback loop

Related ADRs (coditect-core)

Located in coditect-core/internal/architecture/adrs/

ADR	Purpose
ADR-068	Large Project Plan Token Economics (motivation)
ADR-052	Intent-Aware Context Management
ADR-053	Cloud Context Sync Architecture
ADR-054	Track Nomenclature Extensibility

---

License

Copyright 2026 AZ1.AI INC. All rights reserved.

Part of the CODITECT platform.

---

Repository: coditect-task-orchestrator Owner: AZ1.AI INC Lead: Hal Casteel Version: 0.1.0 Created: January 13, 2026