Task Hierarchy

Organize work with epics, tasks, and subtasks

Task Hierarchy

CLEO uses a simple three-level hierarchy to organize work: Epic -> Task -> Subtask.

The Three Levels

Epic

Large features or milestones containing multiple tasks

Task

Individual work items, can stand alone or be part of an epic

Subtask

Granular steps within a task

Why Three Levels?

Research shows that deeper hierarchies impair navigation and understanding. Three levels provide:

• Sufficient structure for complex projects
• Easy navigation - never more than 2 clicks to any item
• Clear responsibility - each level has distinct purpose

Attempting to create a fourth level (subtask of subtask) will return exit code 11 (depth exceeded).

Creating Hierarchies

Epic

cleo add "User Authentication System" \
  --type epic \
  --priority high \
  --phase core
# Creates T001 as epic

Task

cleo add "Implement JWT middleware" \
  --parent T001 \
  --priority medium
# Creates T002 under T001

Subtask

cleo add "Add token validation" \
  --parent T002 \
  --type subtask \
  --size small
# Creates T003 under T002

Viewing Hierarchy

# Tree view of all tasks
cleo tree

# Subtree from specific epic
cleo tree --parent T001

# List children of a task
cleo list --parent T001

Example output:

T001 [epic] User Authentication System
├── T002 [task] Implement JWT middleware
│   ├── T003 [subtask] Add token validation
│   └── T004 [subtask] Handle refresh tokens
├── T005 [task] Create login endpoint
└── T006 [task] Add password hashing

Moving Tasks

Reparent

# Move T005 under T002
cleo reparent T005 --to T002

Auto-Complete Behavior

When all children of a task are complete, the parent can auto-complete:

# Enable auto-complete
cleo config set hierarchy.autoCompleteParent true
cleo config set hierarchy.autoCompleteMode auto  # auto|suggest|off

With suggest mode, CLEO prompts before auto-completing parents.

Constraints

Constraint	Value	Configurable
Max depth	3 levels	No
Max siblings	7 (default)	Yes
Type inference	Automatic	Yes

# Adjust sibling limit
cleo config set hierarchy.maxSiblings 10

Dependency Visualization

Legend: Solid lines = parent-child, Dashed lines = dependencies

Related

Commands: reparent

Move tasks between parents

Commands: tree

View hierarchy as tree