Project Management

Organize work with epic/task/subtask hierarchy, phases, and dependencies

Project Management with CLEO

CLEO provides a structured approach to organizing work using hierarchies, phases, and dependencies. This guide covers the patterns and practices for effective project management.

Task Hierarchy

CLEO uses a three-level hierarchy to organize work:

Epic (large scope) → Task (unit of work) → Subtask (atomic piece)

Epic

Large feature or initiative with multiple tasks. Size: large

Task

Unit of work that can be completed in a session. Size: medium

Subtask

Atomic piece of work within a task. Size: small

Creating Hierarchical Tasks

Create Epic

cleo add "User Authentication System" \
  --type epic \
  --size large \
  --description "Complete auth implementation with JWT"

Viewing Hierarchy

# Tree view
cleo list --tree

# Filter by type
cleo list --type epic
cleo list --type task
cleo list --type subtask

# Children of specific parent
cleo list --parent T001

Maximum depth is 3 levels (epic → task → subtask). Siblings are unlimited by default (configurable via hierarchy.maxSiblings).

Phases

Phases represent project stages and provide workflow organization:

Phase	Purpose
setup	Project initialization and planning
core	Main development and implementation
testing	Validation and quality assurance
polish	Refinement and documentation
maintenance	Bug fixes and ongoing support

Working with Phases

Phase Commands

# View all phases
cleo phases

# Set current project phase
cleo phase set core

# View current phase
cleo phase show

# Assign task to phase
cleo add "Write tests" --phase testing

Filtering by Phase

# Tasks in current phase
cleo list --phase $(cleo phase show -q)

# Tasks in specific phase
cleo list --phase testing

# Phase statistics
cleo phases stats

Check phase context before work with cleo phase show. When working across phases, document the rationale with task notes.

Dependencies

Dependencies define task ordering and block execution until prerequisites complete:

# Create task with dependency
cleo add "Write integration tests" --depends T001,T002

# View dependencies
cleo deps T001

# Analyze blockers
cleo blockers
cleo blockers analyze  # Critical path analysis

Dependency Patterns

Sequential Work

cleo add "Design API" --phase setup
cleo add "Implement API" --depends T001 --phase core
cleo add "Test API" --depends T002 --phase testing

Parallel Branches

cleo add "Frontend Auth" --depends T001
cleo add "Backend Auth" --depends T001
cleo add "Integration" --depends T002,T003

Epic Dependencies

cleo add "Payment Epic" --type epic
cleo add "User Epic" --type epic
cleo add "Checkout Epic" --type epic --depends T001,T002

Labels

Labels provide flexible categorization for filtering and organization:

# Add task with labels
cleo add "Fix XSS vulnerability" --labels security,bug,urgent

# List by label
cleo list --label security

# View all labels
cleo labels

# Label statistics
cleo labels show security

Suggested Label Categories

Category	Examples
Type	bug, feature, refactor, docs
Priority	urgent, blocking, nice-to-have
Area	frontend, backend, api, infra
Sprint	sprint-12, q1-2025

Size-Based Planning

CLEO uses size (not time estimates) for scope-based planning:

CLEO explicitly prohibits time estimates. Use scope-based sizing instead.

Size	Scope	Example
small	Single function or minor change	”Fix typo in error message”
medium	Feature component or module	”Add password reset endpoint”
large	Full feature or subsystem	”Implement user authentication”

cleo add "Refactor database layer" --size large
cleo add "Add validation" --size medium
cleo add "Update error text" --size small

Analyze and Prioritize

CLEO provides intelligent task analysis:

# Task triage with leverage scoring
cleo analyze

# Auto-set focus to top task
cleo analyze --auto-focus

# Analyze specific epic
cleo analyze --parent T001

# Configure analysis strategy
cleo config set analyze.sizeStrategy quick-wins   # Favor small tasks
cleo config set analyze.sizeStrategy big-impact   # Favor large tasks
cleo config set analyze.sizeStrategy balanced     # Neutral (default)

Best Practices

Epic Scoping

Keep epics to 3-7 tasks. Split larger initiatives into multiple epics.

Phase Discipline

Work within current phase when possible. Document cross-phase rationale.

Dependency Hygiene

Review dependencies weekly. Remove stale dependencies from completed work.

Label Consistency

Define label taxonomy upfront. Review and consolidate periodically.

Next Steps

Session Management

Learn focus and session protocols

Context Monitoring

Track context window usage