Advanced Workflows

This guide explains how tk’s graph analytics, stacks, parallel tracks, and worktrees work together to enable sophisticated development workflows. Understanding these concepts helps you structure work for maximum parallelization and efficient merge queues.

The Dependency Graph

At its core, tk maintains a directed acyclic graph (DAG) of your issues. Each issue can depend on zero or more other issues, and these relationships form the graph structure. This graph enables:

Topological sorting — Determine execution order
Cycle detection — Prevent impossible dependencies
Impact analysis — Know what work unblocks what
Parallelization — Find independent work streams

Two Types of Structure: Stacks vs Tracks

tk recognizes two fundamental patterns in your dependency graph:

Stacks (Linear Chains)

A stack is a linear sequence where each issue depends on exactly one predecessor: Characteristics:

Sequential execution — Must be worked in order
Coordinated review — Can be reviewed as a unit
Merge optimization — Validate tip, fast-forward merge all
Graphite-style — Mirrors stacked PR workflows

Use stacks for:

Incremental feature development
Layered refactoring (foundation → API → UI)
Changes that must be merged in order

Parallel Tracks

A track is a group of issues that share a common root but can be worked independently: Characteristics:

Parallel execution — Can be worked simultaneously
Independent review — Each track reviewed separately
Merge flexibility — Merge in any order after root completes

Use tracks for:

Feature branches that share infrastructure
Platform-specific implementations
Independent components of a larger system

Graph Analytics Deep Dive

tk uses several graph algorithms to help prioritize work:

PageRank Priority

PageRank scores issues by their position in the dependency graph. Issues that block more downstream work get higher scores.

tk priority

How it works:

Each issue starts with equal “importance”
Importance flows through dependency edges
Issues that block many others accumulate importance
Scores normalize to 0-100 range

Interpretation:

Score	Meaning
80+	Critical blocker, blocks significant work
50-79	Important, blocks multiple issues
20-49	Moderate impact
< 20	Leaf node or low-dependency issue

Betweenness Centrality

Measures how often an issue appears on the shortest path between other issues. High betweenness indicates a bottleneck.

tk insights

Why it matters: An issue with high betweenness:

Sits at a critical junction in your workflow
Delays here cascade to multiple work streams
May need to be split or prioritized

Critical Path

The longest chain of dependencies determines your minimum timeline. No amount of parallelization can shorten the critical path.

tk insights --critical-path

Using critical path:

Identify issues on the critical path
These are your highest-leverage optimization targets
Breaking dependencies on critical path shortens timeline
Monitor critical path length as a project health metric

Execution Planning

The tk plan command generates an execution plan using topological sort:

tk plan

Sample output:

Execution Plan:

Batch 1 (start immediately):
  • tk-auth     - Authentication setup
  • tk-config   - Configuration system

Batch 2 (after Batch 1):
  • tk-api      - API endpoints (waits: tk-auth)
  • tk-ui       - UI components (waits: tk-config)

Batch 3 (after Batch 2):
  • tk-deploy   - Deployment (waits: tk-api, tk-ui)

Batches represent:

Maximum parallelism — All issues in a batch can be worked simultaneously
Dependency ordering — Each batch depends only on previous batches
Resource allocation — Match batch sizes to team capacity

Stacks + Worktrees: Graphite-Style Workflows

tk’s worktree support enables Graphite-style stacked development:

The Pattern

Detect stacks in your issue graph
Create worktrees for each issue in the stack
Work bottom-up from stack root to tip
Validate at tip — run tests on the final state
Merge all — fast-forward the entire stack

Setup

# Configure worktree location (sibling directory)
tk config set workflow.worktree_base "../wt"

# View detected stacks
tk stacks

Working a Stack

# See your stacks
tk stacks

# Output:
# ○ stack-1 [3 issues] tk-base → tk-api → tk-ui
#   Chain: tk-base → tk-api → tk-ui

# Start from root
tk claim tk-base
tk worktree create tk-base

# Work in the worktree
cd ../wt/tk-base
# ... make changes, commit ...

# Move up the stack
tk resolve tk-base
tk claim tk-api
# The worktree inherits from tk-base's branch

Stack-Aware Hooks

tk’s hook system supports stack workflows with special variables:

# .tickets/hooks/on-claim.sh
#!/bin/bash

# Stack-aware worktree creation
if [ -n "{{ stack_id }}" ]; then
    echo "Working on {{ id }} ({{ stack_position }}/{{ stack_depth }} in {{ stack_id }})"

    # Create worktree based on previous stack issue if not root
    if [ "{{ stack_position }}" -gt 1 ]; then
        git worktree add ../wt/{{ id | short }} {{ previous_in_stack }}
    else
        git worktree add ../wt/{{ id | short }} main
    fi
fi

Combining Concepts: A Real Workflow

Here’s how all these concepts work together in a real project:

1. Structure Your Work

# Create foundation (no deps - track root)
tk create "Auth system" -t feature -p 1
# Created: tk-auth

# Create parallel tracks (independent work)
tk create "REST API" -t feature -d tk-auth
tk create "GraphQL API" -t feature -d tk-auth
tk create "Mobile SDK" -t feature -d tk-auth

# Create a stack (sequential work)
tk create "User model" -t task -d tk-auth
tk create "User API" -t task -d tk-user-model
tk create "User UI" -t task -d tk-user-api

2. Analyze the Graph

# See the structure
tk plan

# Batch 1: tk-auth (root)
# Batch 2: tk-rest, tk-graphql, tk-mobile, tk-user-model
# Batch 3: tk-user-api
# Batch 4: tk-user-ui

# See stacks
tk stacks

# stack-1: tk-user-model → tk-user-api → tk-user-ui

# Check priorities
tk priority

# tk-auth: 85 (blocks everything)
# tk-user-model: 45 (stack root, blocks 2)
# Others: 20-30

3. Execute Strategically

# Start with highest-impact work
tk triage

# Recommendation: tk-auth (blocks 6 issues)
tk claim tk-auth

# After completing auth, multiple tracks open up
tk resolve tk-auth

# Now unblocked: tk-rest, tk-graphql, tk-mobile, tk-user-model
# Assign to team members or work in parallel

# Work the stack bottom-up
tk claim tk-user-model
# ... complete ...
tk resolve tk-user-model
tk claim tk-user-api
# ... and so on

4. Monitor Health

# Regular health checks
tk triage

# Watch for:
# - High stack count → lots of sequential work
# - Long critical path → timeline risk
# - High bottleneck count → restructure needed
# - Cycles detected → immediate fix required

Best Practices

Minimize critical path length

The critical path determines minimum timeline. To shorten it:

Break large issues into parallel sub-tasks
Remove unnecessary dependencies
Identify and optimize bottleneck issues

Use stacks for incremental features

Stacks excel when:

Changes must be reviewed/merged in order
Each layer builds on the previous
You want to validate the final state once

Avoid stacks when:

Work can genuinely be done in parallel
You have multiple reviewers
Speed is more important than ordering

Balance stack depth

Deep stacks (5+ issues) have trade-offs:

Pro: Clear progression, easy to follow
Con: Sequential bottleneck, long merge times

Consider splitting deep stacks into parallel tracks where possible.

Use triage daily

tk triage combines all analytics into actionable recommendations:

Start sessions with tk triage
Focus on blockers to clear first
Quick wins maintain momentum
Monitor health trends over time

Structure for your team size

Solo: Deeper stacks are fine, you control the sequence
Small team (2-4): Mix stacks and parallel tracks
Large team (5+): Maximize parallel tracks, minimize shared stacks

Command Reference

Command	Purpose
`tk plan`	Parallel execution batches
`tk stacks`	Detect linear chains
`tk priority`	PageRank-based priorities
`tk insights`	Betweenness, critical path
`tk triage`	Unified recommendations
`tk dep tree <id>`	Visualize dependencies
`tk worktree create <id>`	Create issue worktree

Next Steps

Stacks

Deep dive into linear dependency chains.

Dependencies

Managing issue dependencies.

Graph Analytics

PageRank, critical path, and metrics.

CLI Reference

Full command documentation.

Getting Started

Concepts

CLI Reference

Integrations

About

Blog

Advanced Workflows

The Dependency Graph

Two Types of Structure: Stacks vs Tracks

Stacks (Linear Chains)

Parallel Tracks

Graph Analytics Deep Dive

PageRank Priority

Betweenness Centrality

Critical Path

Execution Planning

Stacks + Worktrees: Graphite-Style Workflows

The Pattern

Setup

Working a Stack

Stack-Aware Hooks

Combining Concepts: A Real Workflow

1. Structure Your Work

2. Analyze the Graph

3. Execute Strategically

4. Monitor Health

Best Practices

Command Reference

Next Steps

Stacks

Dependencies

Graph Analytics

CLI Reference

​The Dependency Graph

​Two Types of Structure: Stacks vs Tracks

​Stacks (Linear Chains)

​Parallel Tracks

​Graph Analytics Deep Dive

​PageRank Priority

​Betweenness Centrality

​Critical Path

​Execution Planning

​Stacks + Worktrees: Graphite-Style Workflows

​The Pattern

​Setup

​Working a Stack

​Stack-Aware Hooks

​Combining Concepts: A Real Workflow

​1. Structure Your Work

​2. Analyze the Graph

​3. Execute Strategically

​4. Monitor Health

​Best Practices

​Command Reference

​Next Steps

Stacks

Dependencies

Graph Analytics

CLI Reference

The Dependency Graph

Two Types of Structure: Stacks vs Tracks

Stacks (Linear Chains)

Parallel Tracks

Graph Analytics Deep Dive

PageRank Priority

Betweenness Centrality

Critical Path

Execution Planning

Stacks + Worktrees: Graphite-Style Workflows

The Pattern

Setup

Working a Stack

Stack-Aware Hooks

Combining Concepts: A Real Workflow

1. Structure Your Work

2. Analyze the Graph

3. Execute Strategically

4. Monitor Health

Best Practices

Command Reference

Next Steps