Skip to main content
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

Only add dependencies that are truly blocking. Over-specifying dependencies reduces parallelization opportunities.
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
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]
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:
AnalysisWhat it shows
PageRankIssues blocking the most downstream work
Critical PathLongest chain determining minimum timeline
BetweennessBottleneck 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

Use tk dep cycles to find the cycle, then remove one dependency to break it.
Run tk triage to find high-impact blockers. Clear these first to unblock the most work.
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.