Dependencies

Dependencies define the relationships between issues in your project. When issue B depends on issue A, B is blocked until A is completed. tk uses these relationships to power graph analytics, prioritization, and execution planning.

Defining Dependencies

Using the CLI

# Create an issue with dependencies
tk create "Build API endpoints" -d tk-abc123 -d tk-def456

# Add dependency to existing issue
tk dep add tk-ghi789 --depends-on tk-abc123

# Remove a dependency
tk dep remove tk-ghi789 --depends-on tk-abc123

In Issue Files

Dependencies are listed in the YAML frontmatter:

---
status: open
deps: [tk-abc123, tk-def456]
type: feature
priority: 1
---
# Build API endpoints

This issue depends on the database schema (tk-abc123)
and authentication setup (tk-def456).

Dependencies reference issue IDs. The ID is the filename without the .md extension.

Dependency Types

Direct vs Transitive

Direct dependencies: Issues explicitly listed in deps
Transitive dependencies: Issues blocked through a chain

Blockers vs Blocked

Blockers: Issues that must complete first (deps)
Blocked by this: Issues waiting for this to complete

# See what blocks an issue
tk show tk-api

# See full dependency tree
tk dep tree tk-api

Visualizing Dependencies

Dependency Tree

tk dep tree tk-api

Sample output:

tk-api: Build API endpoints [P1] (open)
    ├── tk-auth: Authentication setup [P1] (open)
    │   └── tk-db: Database schema [P0] (in_progress)
    └── tk-config: Config system [P2] (closed) ✓

Closed dependencies show a checkmark. Only open dependencies block progress.

Graph Analytics

# See how dependencies affect priority
tk priority

# Find bottlenecks in dependency graph
tk insights

Dependency Best Practices

Keep dependencies minimal

Only add dependencies that are truly blocking. Over-specifying dependencies reduces parallelization opportunities.

Avoid circular dependencies

tk detects cycles but can’t resolve them. If A depends on B and B depends on A, neither can be completed.

# Check for cycles
tk dep cycles

Use epics for grouping, not blocking

Don’t make subtasks depend on the epic. Use parent field instead:

# Good: parent relationship
parent: tk-epic123

# Avoid: dependency on parent
deps: [tk-epic123]

Break large dependencies

If issue A depends on 10 things from issue B, B might be too large. Consider splitting B into smaller pieces.

Working with Blocked Issues

Finding Ready Work

Issues with no open blockers are “ready”:

# List all ready issues
tk ready

# Filter by priority
tk ready --priority 0

Unblocking Work

When you complete an issue, dependents become unblocked:

# Complete and see what's unblocked
tk resolve tk-db
# Output: tk-auth is now ready!

Handling Blocked Issues

# See blocked issues
tk list --status blocked

# See what's blocking a specific issue
tk show tk-api

Linear Chains (Stacks)

When issues form a linear chain of dependencies, tk recognizes them as stacks: Stacks are useful for:

Incremental feature development
Coordinated code reviews
Merge queue ordering

Learn about Stacks

See how tk detects and works with linear dependency chains.

Graph Analytics on Dependencies

tk analyzes your dependency graph to provide intelligent recommendations:

Analysis	What it shows
PageRank	Issues blocking the most downstream work
Critical Path	Longest chain determining minimum timeline
Betweenness	Bottleneck issues appearing in many paths

# Get all analytics
tk insights

# AI-powered recommendations
tk triage

Graph Analytics

Deep dive into how tk uses graph algorithms for prioritization.

Common Patterns

Feature Development

# Create dependent feature issues
tk create "Database schema for users" -t feature -p 1
# Created: tk-user-db

tk create "User API endpoints" -t feature -p 1 -d tk-user-db
# Created: tk-user-api

tk create "User profile UI" -t feature -p 1 -d tk-user-api
# Created: tk-user-ui

Bug Fix with Test

# Bug depends on having a test first
tk create "Add test for edge case" -t task -p 1
# Created: tk-test

tk create "Fix edge case bug" -t bug -p 0 -d tk-test
# Created: tk-bug

Epic Breakdown

# Create epic
tk create "Authentication system" -t epic -p 1
# Created: tk-auth-epic

# Create subtasks with parent (not deps)
tk create "OAuth provider setup" -t task --parent tk-auth-epic
tk create "Session management" -t task --parent tk-auth-epic
tk create "Login UI" -t task --parent tk-auth-epic

Troubleshooting

Circular dependency detected

Use tk dep cycles to find the cycle, then remove one dependency to break it.

Too many blocked issues

Run tk triage to find high-impact blockers. Clear these first to unblock the most work.

Dependency not recognized

Ensure the dependency ID matches exactly. IDs are case-sensitive and include the tk- prefix.

Next Steps

Stacks

Learn about linear dependency chains.

Graph Analytics

Understand priority scoring and bottleneck detection.

CLI Reference

Full command reference for dependency management.

Quickstart

Get started with tk in 60 seconds.

Getting Started

Concepts

CLI Reference

Integrations

About

Blog

Defining Dependencies

Using the CLI

In Issue Files

Dependency Types

Direct vs Transitive

Blockers vs Blocked

Visualizing Dependencies

Dependency Tree

Graph Analytics

Dependency Best Practices

Working with Blocked Issues

Finding Ready Work

Unblocking Work

Handling Blocked Issues

Linear Chains (Stacks)

Learn about Stacks

Graph Analytics on Dependencies

Graph Analytics

Common Patterns

Feature Development

Bug Fix with Test

Epic Breakdown

Troubleshooting

Next Steps

Stacks

Graph Analytics

CLI Reference

Quickstart

​Defining Dependencies

​Using the CLI

​In Issue Files

​Dependency Types

​Direct vs Transitive

​Blockers vs Blocked

​Visualizing Dependencies

​Dependency Tree

​Graph Analytics

​Dependency Best Practices

​Working with Blocked Issues

​Finding Ready Work

​Unblocking Work

​Handling Blocked Issues

​Linear Chains (Stacks)

Learn about Stacks

​Graph Analytics on Dependencies

Graph Analytics

​Common Patterns

​Feature Development

​Bug Fix with Test

​Epic Breakdown

​Troubleshooting

​Next Steps

Stacks

Graph Analytics

CLI Reference

Quickstart

Defining Dependencies

Using the CLI

In Issue Files

Dependency Types

Direct vs Transitive

Blockers vs Blocked

Visualizing Dependencies

Dependency Tree

Graph Analytics

Dependency Best Practices

Working with Blocked Issues

Finding Ready Work

Unblocking Work

Handling Blocked Issues

Linear Chains (Stacks)

Graph Analytics on Dependencies

Common Patterns

Feature Development

Bug Fix with Test

Epic Breakdown

Troubleshooting

Next Steps