Back to Documentation

Work Units

Organize tasks hierarchically and maintain context across agent sessions

What Are Work Units?

Most project management tools give you two primitives: Projects (top-level containers) and Tasks (individual work items). But there's a critical organizational layer missing: Work Units—cohesive groups of 5-8 related tasks that represent a single deliverable feature or epic.

Work Units provide the coordination layer between projects and tasks, specifically designed for AI agent workflows. The hierarchy looks like this:

Project (e.g., "E-commerce Platform")
└── Work Unit (e.g., "Shopping Cart Feature")
├── Task 1: Database schema & migrations
├── Task 2: Repository layer implementation
├── Task 3: API endpoint creation
└── Task 4: Integration tests

Work Units maintain structured metadata (status, priority, progress, execution plans) that AI agents can programmatically access via MCP, enabling session continuity and multi-task coordination without manual context re-loading.

Key Features

Three-Level Hierarchy

Work Units support a maximum of 2 levels of nesting to keep organization simple and effective.

  • •
    Epic: Large initiatives spanning multiple features (e.g., "User Authentication System"). Can contain Features but not other Epics.
  • •
    Feature: Mid-level units grouping related tasks (e.g., "OAuth Integration"). Can belong to an Epic.
  • •
    Initiative: Strategic projects (e.g., "Q1 Performance Improvements"). Same level as Epics.
Epic: User Authentication System (DXX-WU-2)
├─ Feature: OAuth Integration (DXX-WU-3)
│ ├─ Task: Implement Google OAuth (LXX-4)
│ └─ Task: Add GitHub OAuth (LXX-5)
└─ Feature: Password Recovery (DXX-WU-4)
└─ Task: Email verification flow (LXX-6)

Status & Progress Tracking

Each Work Unit tracks its own status and automatically calculates progress based on completed tasks.

Available Statuses

  • planning - Initial planning phase
  • in_progress - Active development
  • blocked - Waiting on dependencies
  • completed - All tasks done
  • cancelled - Work abandoned

Priority Levels

  • low - Nice to have
  • medium - Normal priority
  • high - Critical/urgent
Shopping Cart Feature (DXX-WU-1)
In Progress
Progress: 2 of 6 tasks completed (33%)

The Problem: AI Session State Loss

AI coding assistants are stateless. Every new session starts from scratch. For multi-task features (5-8 related tasks), this creates context overhead:

Without Work Units

Session 1: Implement database schema (45 min)
→ Agent has no memory, starts fresh
Session 2: Implement API endpoints (60 min)
→ Re-explain: "The database has a carts table with..."
→ 30 min context re-loading + 30 min implementation
Session 3: Implement frontend UI (75 min)
→ Re-explain: "There's a cart API at /api/cart..."
→ 40 min context re-loading + 35 min implementation
Total: 180 min + 70 min context overhead = 250 min

With Work Units

Session 1: Agent loads work unit "Shopping Cart" via MCP
→ Sees: 6 tasks, execution plan, 0/6 complete
→ Implements tasks 1-2, updates devInfo
Session 2: Agent loads same work unit
→ Reads devInfo: "DB schema in migrations/003_cart.sql, API at /api/cart"
→ Sees: 2/6 complete, next task is frontend
→ Implements tasks 3-4 with full context
Session 3: Agent completes work unit
→ Loads devInfo, sees files changed, commits
→ Implements remaining tasks, marks complete
Total: 180 min + 5 min context overhead = 185 min (26% faster)

How It Works: devInfo Persistence

Work Units solve context loss through structured devInfo metadata that agents programmatically access via MCP:

Execution State Tracking

// Agent reads this via get-work-unit MCP tool
{
"devInfo": {
"executionPlan": "Backend → Frontend → Tests",
"progress": { "completedTasks": 2, "totalTasks": 6 },
"filesChanged": [
"backend/migrations/003_cart.sql:1",
"backend/src/repos/CartRepo.ts:15"
],
"commits": ["a1b2c3: Add cart schema", "d4e5f6: Cart repo"],
"testResults": { "passed": 12, "coverage": "85%" }
}
}

Agent Workflow

1
Load work unit: get-work-unit({ id: "DXX-WU-1" })
Agent sees all tasks, current progress, execution plan
2
Read devInfo: Files changed, commits, test results from previous sessions
No need to re-explain architecture—it's in devInfo
3
Implement next task: Agent knows what was done, what's next
Full context without manual re-loading
4
Update devInfo: update-work-unit({ devInfo: {...} })
Agent persists context for next session

Related Documentation

Project MCP

Learn how agents access Work Unit context via MCP tools

Agent Members

Understand how to assign agents as Work Unit owners

Ready to organize your development workflow?

Start using Work Units to bring structure to your AI-powered development process.

Get StartedTry Agiflow Free