Task Dependencies¶

TaskRepo supports task dependencies, allowing you to define relationships between tasks where one task must be completed before another can start.

Overview¶

Dependencies help model workflows where: - Task B can't start until Task A is complete - Multiple tasks must finish before a final task begins - Project phases must proceed sequentially

Defining Dependencies¶

Dependencies are specified in the task's YAML frontmatter using the depends field.

Syntax¶

---
uuid: 'c5f9e4b2-6d7e-4f3a-9b1c-2d3e4f5a6b7c'
title: Deploy to production
depends:
  - 'a3f2e1d9-4b7c-4e3f-9a1b-2c3d4e5f6a7b'  # Code review task
  - 'b4e8f3a1-5c6d-4e2f-8a9b-1c2d3e4f5a6b'  # Testing task
---

Field: depends Type: List of UUIDs (strings) Format: Each dependency is a task UUID

Creating Dependencies¶

Via CLI (Manual Edit)¶

1. Find the UUID of the dependency task:

   tsk info 1
   # Output shows: uuid: 'a3f2e1d9-4b7c-4e3f-9a1b-2c3d4e5f6a7b'
   

2. Edit the dependent task:

   tsk edit 2
   

3. Add depends field in YAML frontmatter:

   depends:
     - 'a3f2e1d9-4b7c-4e3f-9a1b-2c3d4e5f6a7b'
   

Direct File Edit¶

Edit the task file directly:

vim ~/tasks/tasks-work/tasks/task-{uuid}.md

Add or modify the depends field in YAML frontmatter.

Dependency Types¶

Single Dependency¶

Task depends on one other task:

depends:
  - 'a3f2e1d9-4b7c-4e3f-9a1b-2c3d4e5f6a7b'

Multiple Dependencies¶

Task depends on several tasks (all must complete):

depends:
  - 'a3f2e1d9-4b7c-4e3f-9a1b-2c3d4e5f6a7b'
  - 'b4e8f3a1-5c6d-4e2f-8a9b-1c2d3e4f5a6b'
  - 'c5f9e4b2-6d7e-4f3a-9b1c-2d3e4f5a6b7c'

Dependency Chains¶

Tasks can form chains:

Task A (no dependencies)
  ↓
Task B (depends on A)
  ↓
Task C (depends on B)
  ↓
Task D (depends on C)

# Task B
depends:
  - '{uuid-of-task-a}'

# Task C
depends:
  - '{uuid-of-task-b}'

# Task D
depends:
  - '{uuid-of-task-c}'

Parallel Dependencies¶

Multiple tasks depend on the same prerequisite:

Task A (no dependencies)
  ├→ Task B (depends on A)
  ├→ Task C (depends on A)
  └→ Task D (depends on A)

Complex DAG (Directed Acyclic Graph)¶

Tasks form a dependency graph:

Task A ────┐
           ├→ Task D
Task B ────┤
           └→ Task E ──→ Task F
Task C ────────────────┘

Viewing Dependencies¶

Task Info¶

View dependencies for a specific task:

tsk info 4

Output:

Task: Deploy to production
UUID: c5f9e4b2-6d7e-4f3a-9b1c-2d3e4f5a6b7c
Status: pending
Priority: H

Dependencies:
  • [a3f2e1d9] Fix authentication bug (completed)
  • [b4e8f3a1] Write integration tests (in-progress)

Blocked: Yes (1 dependency not complete)

TUI Tree View (Planned)¶

Future versions will include tree view in TUI:

tsk tui
# Press 't' to toggle tree view

Planned display:

┌─ Tasks (Tree View) ─────────────────────────────────────────┐
│                                                              │
│ ▼ 1. Fix authentication bug [completed]                     │
│     └─ 3. Write integration tests [in-progress]             │
│         └─ 4. Deploy to production [pending]                │
│                                                              │
│ ▼ 2. Update documentation [pending]                         │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Dependency Validation¶

Current Implementation¶

TaskRepo stores dependencies but doesn't enforce them (planned for future).

What's supported now: - ✅ Store dependencies in YAML - ✅ View dependencies via tsk info - ✅ Manual dependency management

What's planned: - ⏳ Automatic dependency validation - ⏳ Block starting tasks with incomplete dependencies - ⏳ Dependency graph visualization - ⏳ Smart task ordering in lists

Manual Validation¶

Until automatic validation is implemented, manually check:

# View dependency status
tsk info 4

# Check dependency task
tsk info {dependency-display-id}

Workflow Examples¶

Example 1: Feature Development¶

# Task 1: Design API endpoint
uuid: 'a3f2e1d9-4b7c-4e3f-9a1b-2c3d4e5f6a7b'
title: Design API endpoint
status: completed

# Task 2: Implement API endpoint (depends on Task 1)
uuid: 'b4e8f3a1-5c6d-4e2f-8a9b-1c2d3e4f5a6b'
title: Implement API endpoint
status: completed
depends:
  - 'a3f2e1d9-4b7c-4e3f-9a1b-2c3d4e5f6a7b'

# Task 3: Write tests (depends on Task 2)
uuid: 'c5f9e4b2-6d7e-4f3a-9b1c-2d3e4f5a6b7c'
title: Write integration tests
status: in-progress
depends:
  - 'b4e8f3a1-5c6d-4e2f-8a9b-1c2d3e4f5a6b'

# Task 4: Deploy (depends on Task 3)
uuid: 'd6a1f5c3-7e8f-4a4b-1c2d-3e4f5a6b7c8d'
title: Deploy to production
status: pending
depends:
  - 'c5f9e4b2-6d7e-4f3a-9b1c-2d3e4f5a6b7c'

Workflow: 1. Complete design → Mark Task 1 as completed 2. Start implementation → Mark Task 2 as in-progress 3. Complete implementation → Mark Task 2 as completed 4. Start testing → Mark Task 3 as in-progress 5. Complete testing → Mark Task 3 as completed 6. Deploy → Mark Task 4 as in-progress

Example 2: Parallel Tasks with Shared Dependency¶

# Task A: Setup development environment
uuid: '{uuid-a}'
title: Setup development environment
status: completed

# Task B: Implement feature X (depends on A)
uuid: '{uuid-b}'
title: Implement feature X
status: in-progress
depends:
  - '{uuid-a}'

# Task C: Implement feature Y (depends on A)
uuid: '{uuid-c}'
title: Implement feature Y
status: pending
depends:
  - '{uuid-a}'

# Task D: Integration testing (depends on B and C)
uuid: '{uuid-d}'
title: Integration testing
status: pending
depends:
  - '{uuid-b}'
  - '{uuid-c}'

Workflow: 1. Complete environment setup (Task A) 2. Start both features in parallel (Tasks B and C) 3. Complete both features 4. Start integration testing (Task D)

Example 3: Project Phases¶

# Phase 1: Requirements
uuid: '{uuid-1}'
title: Gather requirements
status: completed

# Phase 2: Design (depends on Phase 1)
uuid: '{uuid-2}'
title: Create system design
status: completed
depends:
  - '{uuid-1}'

# Phase 3: Implementation (depends on Phase 2)
uuid: '{uuid-3}'
title: Implement system
status: in-progress
depends:
  - '{uuid-2}'

# Phase 4: Testing (depends on Phase 3)
uuid: '{uuid-4}'
title: Test system
status: pending
depends:
  - '{uuid-3}'

# Phase 5: Deployment (depends on Phase 4)
uuid: '{uuid-5}'
title: Deploy to production
status: pending
depends:
  - '{uuid-4}'

Best Practices¶

Use UUIDs, Not Display IDs¶

Correct:

depends:
  - 'a3f2e1d9-4b7c-4e3f-9a1b-2c3d4e5f6a7b'

Incorrect:

depends:
  - '1'  # Display IDs change!

Reason: Display IDs can change as tasks are added/removed. UUIDs are permanent.

Document Dependency Rationale¶

Explain why dependencies exist:

depends:
  - 'a3f2e1d9-4b7c-4e3f-9a1b-2c3d4e5f6a7b'  # Need API endpoint before integration

Or in task description:

## Dependencies

This task depends on "Design API endpoint" because we need the API specification
before implementing the integration tests.

Avoid Circular Dependencies¶

Don't do this:

# Task A depends on Task B
depends:
  - '{uuid-of-task-b}'

# Task B depends on Task A
depends:
  - '{uuid-of-task-a}'

Result: Circular dependency - neither task can start!

Keep Dependency Chains Reasonable¶

Good: 3-5 tasks in a chain Acceptable: 5-10 tasks Avoid: 10+ tasks in a linear chain

Reason: Long chains are fragile and hard to manage.

Group Related Dependencies¶

For tasks with many dependencies, group by category in description:

## Dependencies

### Code Complete
- Task A: Implement authentication
- Task B: Implement authorization
- Task C: Write API documentation

### Testing Complete
- Task D: Unit tests
- Task E: Integration tests

All the above must be completed before deployment.

Update Dependencies as Needed¶

If task relationships change:

tsk edit 4  # Edit dependent task
# Modify depends list in YAML

Future Features¶

TaskRepo's dependency system will expand with:

Dependency Validation (Planned)¶

Automatic checking when marking tasks as in-progress:

tsk in-progress 4
# Output: ⚠️  Warning: Task has 2 incomplete dependencies:
#         • Task 1: Fix authentication bug [in-progress]
#         • Task 2: Write tests [pending]
#         Start anyway? [y/N]

Dependency Graph Visualization (Planned)¶

tsk graph --repo work

Output: ASCII or graphical dependency graph

Smart Task Ordering (Planned)¶

Automatically sort tasks by dependencies:

tsk list --sort dependencies

Output: Tasks ordered so dependencies appear first

Blocked Task Filtering (Planned)¶

tsk list --blocked     # Show tasks with incomplete dependencies
tsk list --unblocked   # Show tasks ready to start

Dependency Templates (Planned)¶

tsk template feature-development
# Creates linked task set:
# - Design (no dependencies)
# - Implement (depends on Design)
# - Test (depends on Implement)
# - Deploy (depends on Test)

Troubleshooting¶

Dependency Not Showing¶

Problem: Added dependency but tsk info doesn't show it

Solutions: - Check YAML syntax (valid list format) - Verify UUID is correct (not display ID) - Ensure file was saved

Circular Dependency¶

Problem: Tasks depend on each other

Solution: Break the cycle by removing one dependency and restructuring tasks

Lost Dependency on Move¶

Problem: Moved task to different repository, dependency link broken

Solution: Dependencies are repository-scoped. To maintain cross-repo dependencies, document them in task description instead.

Can't Find UUID¶

Problem: Need UUID for dependency but don't know it

Solution:

tsk list              # See display IDs
tsk info {id}         # Get UUID from display ID

Next Steps¶

• Git Sync - Sync tasks with dependencies
• Conflict Resolution - Handle dependency conflicts
• Task Management - Managing task workflows