Stacks

Stacks are linear chains of dependent issues that form a cohesive unit of work. Inspired by Graphite’s stacked PRs, tk automatically detects stacks in your issue graph and provides tools to work with them efficiently.

What is a Stack?

A stack is a maximal linear chain where:

Each issue depends on exactly one predecessor (except the root)
Each issue has at most one dependent (except the tip)

Stacks are detected automatically from your issue dependencies. You don’t need to explicitly create them.

Why Use Stacks?

1. Structured Feature Development

Break large features into incremental, reviewable pieces:

# Create a stack of issues for authentication
tk create "Auth: Base service setup" -t feature -p 1
# Created: tk-auth1

tk create "Auth: Login endpoint" -t feature -p 1 -d tk-auth1
# Created: tk-auth2

tk create "Auth: Frontend integration" -t feature -p 1 -d tk-auth2
# Created: tk-auth3

2. Clear Work Order

The stack defines the exact order work should be completed:

tk dep tree tk-auth3

tk-auth3: Auth: Frontend integration [P1] (open)
    └── tk-auth2: Auth: Login endpoint [P1] (open)
        └── tk-auth1: Auth: Base service setup [P1] (open)

3. Coordinated Worktrees

Create worktrees for stack issues that share .tickets/:

# Create worktree for the ready root issue
tk worktree ready --issues tk-auth1

Stack Commands

tk provides a complete set of subcommands for managing stacks:

Command	Description
`tk stacks` or `tk stacks list`	List all detected stacks
`tk stacks show <id>`	Show detailed stack info
`tk stacks validate <id>`	Check if stack is ready to merge
`tk stacks merge <id>`	Fast-forward merge all branches
`tk stacks worktree <id>`	Create worktree for stack development

Detecting Stacks

View All Stacks

tk stacks
tk stacks list
tk stacks ls  # alias

Options:

--all — Include stacks with closed issues
--ready — Show only stacks where all issues are ready

Sample output:

2 stack(s) detected:

○ stack-1 [3 issues] tk-auth1 → tk-auth2 → tk-auth3
  Chain: tk-auth1 → tk-auth2 → tk-auth3
○ stack-2 [2 issues] tk-data1 → tk-data2
  Chain: tk-data1 → tk-data2

Show Stack Details

tk stacks show stack-1
tk stacks show tk-auth1  # By root issue ID

Sample output:

Stack: stack-1

  Status: ready
  Depth:  3 issues
  Root:   tk-auth1
  Tip:    tk-auth3

  Chain:
      (root) tk-auth1 - Auth: Base service setup
             tk-auth2 - Auth: Login endpoint
      (tip)  tk-auth3 - Auth: Frontend integration

JSON Output

For programmatic access:

tk stacks -f json
tk stacks show stack-1 -f json

[
  {
    "id": "stack-1",
    "issues": ["tk-auth1", "tk-auth2", "tk-auth3"],
    "root": "tk-auth1",
    "tip": "tk-auth3",
    "is_ready": true,
    "depth": 3
  }
]

Stack Properties

Property	Description
`id`	Unique identifier (e.g., “stack-1”)
`root`	First issue in chain (no blockers)
`tip`	Last issue in chain (no dependents)
`issues`	Ordered list from root to tip
`depth`	Number of issues in stack
`is_ready`	Whether the root can be started

Working with Stacks

Start at the Root

Only the root issue is “ready” since others are blocked:

# Find ready work in the stack
tk ready

# Start the root
tk claim tk-auth1

Progress Through the Stack

As you complete each issue, the next becomes unblocked:

# Complete the root
tk resolve tk-auth1
# 🎉 tk-auth2 is now ready!

# Move to the next
tk claim tk-auth2

View Stack Progress

tk stacks

After resolving tk-auth1:

📚 Detected 1 Dependency Stack(s):

  stack-1 ready (2 issues)
    Root: tk-auth2  Tip: tk-auth3
    Chain: tk-auth2 → tk-auth3

The stack shrinks as you complete issues. When only one issue remains, it’s no longer considered a stack.

Stacks vs Branches

Not all dependency chains form stacks:

Linear Chain = Stack

Each issue has one parent and one child. This is a stack.

Branching = Not a Stack

A has multiple dependents. This is not a stack.

Multiple Parents = Not a Stack

C has multiple dependencies. This is not a stack.

Validating Stacks

Before merging, validate that a stack is ready:

tk stacks validate stack-1

Validation checks:

All non-tip issues in the stack are closed
Tip issue has no external blockers (outside the stack)
All issues exist and are parseable

Sample output (valid):

✓ Stack Validation: stack-1

  PASS Stack is ready for merge!
  All 3 issues are in valid state for merging.

  Issues:
    ✓ tk-auth1 [closed] (root) - Auth: Base service setup
    ✓ tk-auth2 [closed] - Auth: Login endpoint
    ✓ tk-auth3 [open] (tip) - Auth: Frontend integration

Sample output (invalid):

✗ Stack Validation: stack-1

  FAIL Stack is NOT ready for merge.

  Issues:
    ✓ tk-auth1 [closed] (root) - Auth: Base service setup
    ✗ tk-auth2 [open] - Auth: Login endpoint
      → expected closed but is open
    ✓ tk-auth3 [open] (tip) - Auth: Frontend integration

  Fix To fix:
    - Close these issues: tk-auth2

Use tk stacks validate in CI to gate stack merges. Exit code 0 = valid, 1 = invalid.

Merging Stacks

Once validated, merge all branches in a stack with one command:

tk stacks merge stack-1

Options:

--dry-run — Preview merge without making changes
--yes — Skip confirmation prompt

Process:

Validates the stack (same as tk stacks validate)
Merges branches in dependency order (root → tip)
Closes all issues in the stack
Reports merge results

This command modifies git branches. Always use --dry-run first to preview changes.

Stack Worktrees

Create a dedicated worktree for working on a stack:

tk stacks worktree stack-1

Features:

Creates worktree with the stack’s tip branch
Symlinks .tickets/ for shared issue tracking
Places worktree in ~/.tickets/worktrees/<repo>/<stack-id>

Manage worktrees:

# List existing stack worktrees
tk stacks worktree --list

# Remove a stack worktree
tk stacks worktree --remove stack-1

Git Worktree Integration

Stacks work seamlessly with git worktrees:

1. Configure Worktree Location

tk config set workflow.worktree_base "../wt"

2. Create Worktrees for Stack Development

# Create worktree for a specific stack
tk stacks worktree stack-1

# Or create worktrees for ready issues
tk worktree ready --issues tk-auth1

3. Use Hooks for Automation

Configure hooks in .tickets/config.yaml:

hooks:
  on-claim:
    worktree: "git worktree add {{ worktree_base }}/{{ id | short }} -b {{ id }}"
    editor: "cursor {{ worktree_base }}/{{ id | short }}"

Worktree Variables

Available template variables:

{{ worktree_base }} - Base directory from config
{{ worktree_path }} - Full path to worktree
{{ id | short }} - Issue ID without prefix (e.g., “auth1”)

Best Practices

Keep stacks focused

Aim for 3-5 issues per stack. Longer stacks increase merge risk.

Work root-to-tip

Always complete the root before moving to dependent issues.

Review incrementally

Each stack issue should be independently reviewable.

Use descriptive names

Name issues to show their position: “Auth: Base”, “Auth: API”, “Auth: UI”

Future Enhancements

Planned stack features:

Stack navigation: tk stacks navigate to move between issues in a stack
Stack rebase: tk stacks rebase to rebase entire stacks onto main
Stack create: tk stacks create to easily build new dependency chains
Bisection: Isolate failures in O(log n) CI runs

Next Steps

Graph Analytics

Learn how tk analyzes your dependency graph.

Dependencies Guide

Best practices for structuring dependencies.

Worktree Commands

Full worktree command reference.

Claude Integration

Automate stack workflows with Claude Code.

Getting Started

Concepts

CLI Reference

Integrations

About

Blog

What is a Stack?

Why Use Stacks?

1. Structured Feature Development

2. Clear Work Order

3. Coordinated Worktrees

Stack Commands

Detecting Stacks

View All Stacks

Show Stack Details

JSON Output

Stack Properties

Working with Stacks

Start at the Root

Progress Through the Stack

View Stack Progress

Stacks vs Branches

Validating Stacks

Merging Stacks

Stack Worktrees

Git Worktree Integration

1. Configure Worktree Location

2. Create Worktrees for Stack Development

3. Use Hooks for Automation

Worktree Variables

Best Practices

Future Enhancements

Next Steps

Graph Analytics

Dependencies Guide

Worktree Commands

Claude Integration

​What is a Stack?

​Why Use Stacks?

​1. Structured Feature Development

​2. Clear Work Order

​3. Coordinated Worktrees

​Stack Commands

​Detecting Stacks

​View All Stacks

​Show Stack Details

​JSON Output

​Stack Properties

​Working with Stacks

​Start at the Root

​Progress Through the Stack

​View Stack Progress

​Stacks vs Branches

​Validating Stacks

​Merging Stacks

​Stack Worktrees

​Git Worktree Integration

​1. Configure Worktree Location

​2. Create Worktrees for Stack Development

​3. Use Hooks for Automation

Worktree Variables

​Best Practices

​Future Enhancements

​Next Steps

Graph Analytics

Dependencies Guide

Worktree Commands

Claude Integration

What is a Stack?

Why Use Stacks?

1. Structured Feature Development

2. Clear Work Order

3. Coordinated Worktrees

Stack Commands

Detecting Stacks

View All Stacks

Show Stack Details

JSON Output

Stack Properties

Working with Stacks

Start at the Root

Progress Through the Stack

View Stack Progress

Stacks vs Branches

Validating Stacks

Merging Stacks

Stack Worktrees

Git Worktree Integration

1. Configure Worktree Location

2. Create Worktrees for Stack Development

3. Use Hooks for Automation

Best Practices

Future Enhancements

Next Steps