TaskFlow: Human-Agent Task Orchestration Platform

Human-Agent Task Orchestration Platform where humans and AI agents collaborate as equals.

One-liner: Your AI workforce — assign tasks to humans or agents, track everything, ship together.

This project fulfills all hackathon requirements while solving a real problem: fragmented work across projects with no unified visibility or agent collaboration.

Works directly with every web and local AI Coding Agent, SpecKitPlus, SpecKit, Google AntiGravity, and any other AI agent that implements the MCP protocol.

---

Why TaskFlow (The Real Problem)

Current State: Data Silos Everywhere

| Silo | What's Trapped | |------|----------------| | Each GitHub repo | Specs, context, implementation details | | Personal notes | Tasks that never become actionable | | Chat with Claude | Context lost after each session | | Team communication | Decisions buried in WhatsApp/Slack |

TaskFlow Solution: Unified Orchestration Layer

┌─────────────────────────────────────────────────────────────────┐
│                         TASKFLOW                                 │
│                                                                  │
│   HUMANS                              AI AGENTS                  │
│   @muhammad                           @claude-code               │
│   @hammad                             @qwen                      │
│   @wania                              @gemini                    │
│                                                                  │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │
│   │  PROJECT:   │  │  PROJECT:   │  │  PROJECT:   │            │
│   │  taskflow   │  │  personal   │  │ robolearn │            │
│   │             │  │             │  │             │            │
│   │  Tasks      │  │  Tasks      │  │  Tasks      │            │
│   │  Subtasks   │  │  Subtasks   │  │  Subtasks   │            │
│   │  Audit logs │  │  Audit logs │  │  Audit logs │            │
│   └─────────────┘  └─────────────┘  └─────────────┘            │
│                                                                  │
│   Everything tracked. Everyone accountable. Full audit trail.   │
└─────────────────────────────────────────────────────────────────┘

---

What Makes TaskFlow Different

| Traditional Task Manager | TaskFlow | |-------------------------|----------| | Humans only | Humans AND Agents as first-class workers | | Static assignment | Dynamic delegation (agent → agent) | | Manual status updates | Agents report progress via MCP | | Single project view | Cross-project visibility | | Trust the artifact | Trust the audit trail | | Personal OR work | Unified: "Message Ahmad" + "Implement MCP server" |

The Killer Feature: Agent-to-Agent Delegation

Task: "Research authentication patterns"
Assigned to: @claude-code
│
├── Subtask: "Survey existing solutions"
│   Delegated to: @gemini (by @claude-code)
│   Status: ✅ Completed
│
├── Subtask: "Analyze security tradeoffs"
│   Delegated to: @qwen (by @claude-code)
│   Status: 🔄 In Progress (60%)
│
└── Subtask: "Draft recommendation"
    Kept by: @claude-code
    Status: ⏳ Blocked (waiting on analysis)

AUDIT TRAIL shows every delegation, every decision.

---

Data Model (Core Schema)

# === CORE ENTITIES ===

class Project(SQLModel, table=True):
    """Container for related tasks"""
    id: str                          # "taskflow", "personal"
    name: str
    description: str | None
    owner_id: str
    created_at: datetime

class Worker(SQLModel, table=True):
    """Both humans and agents are workers"""
    id: str                          # "@muhammad", "@claude-code"
    type: Literal["human", "agent"]
    name: str
    agent_type: str | None           # "claude", "qwen", "gemini"
    capabilities: list[str] | None   # ["coding", "research"]
    api_key_hash: str | None         # For agent authentication
    created_at: datetime

class Task(SQLModel, table=True):
    """Unit of work — can be assigned to human or agent"""
    id: int
    title: str
    description: str | None
    project_id: str
    
    # Assignment
    assignee_id: str | None          # "@claude-code", "@muhammad"
    created_by_id: str
    
    # Hierarchy
    parent_task_id: int | None       # For subtasks
    
    # Status
    status: Literal["pending", "in_progress", "review", "completed", "blocked"]
    progress: int = 0                # 0-100
    
    # Organization (Intermediate features)
    priority: Literal["low", "medium", "high", "urgent"] | None
    tags: list[str] | None
    due_date: datetime | None
    
    # Recurrence (Advanced features)
    recurrence: str | None           # "daily", "weekly", "monthly"
    
    # Timestamps
    created_at: datetime
    updated_at: datetime
    started_at: datetime | None
    completed_at: datetime | None

class LinkedResource(SQLModel, table=True):
    """Generic linking — anything to anything"""
    id: int
    owner_type: Literal["project", "task", "blueprint"]
    owner_id: str
    resource_type: str               # "repo", "spec", "doc", "url", "task"
    resource_uri: str
    name: str
    description: str | None
    access: Literal["read", "write"] = "read"
    created_by: str
    created_at: datetime

class Blueprint(SQLModel, table=True):
    """Reusable task patterns"""
    id: str
    name: str
    description: str | None
    template_tasks: list[dict]
    created_by: str
    created_at: datetime

class AuditLog(SQLModel, table=True):
    """Every action tracked — this is the proof"""
    id: int
    entity_type: str                 # "task", "project", "worker"
    entity_id: str
    action: str                      # "created", "assigned", "delegated", "completed"
    actor_id: str
    actor_type: Literal["human", "agent"]
    details: dict | None
    created_at: datetime

class Conversation(SQLModel, table=True):
    """Chat sessions with TaskFlow AI"""
    id: int
    user_id: str
    created_at: datetime
    updated_at: datetime

class Message(SQLModel, table=True):
    """Individual messages in conversations"""
    id: int
    conversation_id: int
    role: Literal["user", "assistant", "system"]
    content: str
    tool_calls: list[dict] | None
    created_at: datetime

---

Phase Breakdown: The Evolution of TaskFlow

Each phase powers up a specific capability while meeting all hackathon requirements.

---

Phase I: Local CLI with File Storage (Dec 7)

Points: 100 | Core Proof of Concept

Objective: Build command-line TaskFlow that proves human-agent task management works.

Storage: Local files (.taskflow/config.yaml + .taskflow/data.json)

Technology Stack:

• Python 3.13+
• UV
• Typer (CLI framework)
• Pydantic (data validation)
• Claude Code + Spec-Kit Plus

Deliverables:

1. Initialization & Configuration

$ taskflow init
✓ Created .taskflow/config.yaml
✓ Created .taskflow/data.json
TaskFlow initialized!

2. Project Management

$ taskflow project add taskflow --name "TaskFlow Platform"
$ taskflow project add personal --name "Personal Tasks"
$ taskflow project list

3. Worker Management (Humans + Agents)

$ taskflow worker add @muhammad --type human --name "Muhammad"
$ taskflow agent add @claude-code --capabilities coding,architecture
$ taskflow agent add @qwen --capabilities research,analysis
$ taskflow agent add @gemini --capabilities research,summarization
$ taskflow worker list

4. Task CRUD (Basic Level Features)

# Add Task
$ taskflow add "Implement MCP server" --project taskflow --assign @claude-code
✓ Created task #1

# View Task List
$ taskflow list
$ taskflow list --project taskflow
$ taskflow list --assignee @claude-code
$ taskflow list --status pending

# Update Task
$ taskflow edit 1 --title "Implement MCP server v2" --priority high

# Delete Task
$ taskflow delete 1

# Mark Complete
$ taskflow complete 1

5. Intermediate Features

# Priorities & Tags
$ taskflow add "Fix auth bug" --priority urgent --tags bug,security

# Search & Filter
$ taskflow list --tag bug
$ taskflow list --priority urgent

# Sort
$ taskflow list --sort due_date
$ taskflow list --sort priority

6. Human-Agent Workflow

# Agent starts task and breaks down into subtasks
$ taskflow start 1
Starting task #1...
Enter subtasks (or empty to let agent decompose):
> Design protocol
> Implement handlers
> Add authentication
✓ 3 subtasks created

# Progress tracking
$ taskflow progress 1 --percent 30 --note "Protocol designed"

# Agent delegates to another agent
$ taskflow delegate 1.2 @qwen --note "Need research first"
✓ Subtask 1.2 delegated to @qwen by @claude-code

# Request review
$ taskflow review 1

# Human approves/rejects
$ taskflow approve 1
$ taskflow reject 1 --reason "Missing tests"

7. Audit Trail

$ taskflow audit 1
TASK #1: Implement MCP server
──────────────────────────────────────────────────
[2025-12-06 10:00] created by @muhammad
[2025-12-06 10:00] assigned to @claude-code
[2025-12-06 10:05] started by @claude-code
[2025-12-06 10:05] subtask added: "Design protocol"
[2025-12-06 10:05] subtask added: "Implement handlers"
[2025-12-06 10:05] subtask added: "Add authentication"
[2025-12-06 12:00] progress: 30% "Protocol designed"
[2025-12-06 13:00] subtask 1.2 delegated to @qwen
[2025-12-06 15:00] review requested

8. Linked Resources

$ taskflow link 1 --type spec --uri "./specs/mcp.md" --name "MCP Spec"
$ taskflow links 1

File Structure:

.taskflow/
├── config.yaml      # Projects, workers, settings
├── data.json        # Tasks, audit logs, links
└── .env             # API keys (gitignored)

Repository Structure:

taskflow/
├── .spec-kit/
│   └── config.yaml
├── specs/
│   ├── constitution.md
│   ├── overview.md
│   ├── phase-1/
│   │   ├── cli-interface.md
│   │   ├── data-model.md
│   │   └── storage.md
│   └── features/
│       ├── task-crud.md
│       ├── human-agent-assignment.md
│       └── audit-trail.md
├── cli/
│   ├── CLAUDE.md
│   ├── pyproject.toml
│   └── src/taskflow/
│       ├── __init__.py
│       ├── main.py
│       ├── models.py
│       ├── storage.py
│       └── commands/
├── CLAUDE.md
└── README.md

---

Phase II: Full-Stack Web Application (Dec 14)

Points: 150 | Multi-User + Persistence

Objective: Transform CLI into multi-user web app with real database.

What Changes:

• Storage moves from local files to Neon PostgreSQL
• Web UI for humans (Next.js)
• REST API (FastAPI)
• Authentication via Better Auth (reuse from Hackathon 1 SSO)

Technology Stack: | Layer | Technology | |-------|------------| | Frontend | Next.js 16+ (App Router), TypeScript, Tailwind | | Backend | Python FastAPI | | ORM | SQLModel | | Database | Neon Serverless PostgreSQL | | Auth | Better Auth with JWT/JWKS |

Architecture:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Next.js UI    │────▶│   FastAPI       │────▶│   Neon DB       │
│   (Humans)      │     │   Backend       │     │   (PostgreSQL)  │
└────────┬────────┘     └─────────────────┘     └─────────────────┘
         │                      │
         │                      ▼
         │              ┌─────────────────┐
         └─────────────▶│ Hackathon 1 SSO │
                        │ (Better Auth)   │
                        └─────────────────┘

API Endpoints:

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/projects | List user's projects | | POST | /api/projects | Create project | | GET | /api/projects/{id}/tasks | List tasks in project | | POST | /api/projects/{id}/tasks | Create task | | GET | /api/tasks/{id} | Get task with subtasks | | PUT | /api/tasks/{id} | Update task | | DELETE | /api/tasks/{id} | Delete task | | POST | /api/tasks/{id}/start | Start task | | POST | /api/tasks/{id}/subtasks | Add subtask | | PATCH | /api/tasks