speckit-worktree-list

name	speckit-worktree-list
description	Show all active worktrees with feature status and spec artifact summary
compatibility	Requires spec-kit project structure with .specify/ directory
metadata	{"author":"github-spec-kit","source":"worktree:commands/speckit.worktree.list.md"}

List Worktrees

Show all active git worktrees with their feature branch status, spec artifact availability, and task completion progress — a dashboard for parallel feature development.

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty). The user may request a specific format (e.g., "compact") or filter (e.g., "stale only").

Prerequisites

1. Verify a spec-kit project exists by checking for .specify/ directory
2. Verify git is available and the project is a git repository

Outline

1. List all worktrees: Run git worktree list to get all active worktrees:

   • Parse the output to extract path, branch, and HEAD commit for each worktree
   • Identify the main working directory vs. feature worktrees
   • Check which worktrees are in .worktrees/ directory

2. Gather feature status: For each worktree, check its spec-kit state:

   • Branch name: The feature branch checked out in this worktree
   • Spec artifacts: Which files exist (spec.md, plan.md, tasks.md, research.md)
   • Task progress: If tasks.md exists, count [x] vs [ ] items
   • Last activity: Most recent commit date on the branch
   • Merge status: Whether the branch has been merged into main/master
   • Staleness: Whether any artifacts have ⚠️ **STALE** markers

3. Classify worktree status:

   Status	Condition
   ✅ Active	Recent commits (within 7 days), unmerged
   🟡 Idle	No recent commits (7-30 days), unmerged
   ⚠️ Stale	No commits for 30+ days, unmerged
   ✅ Merged	Branch merged into main/master
   ❌ Orphaned	Branch deleted but worktree still exists

4. Output dashboard:

   # Active Worktrees
   
   | # | Branch | Path | Status | Artifacts | Tasks | Last Activity |
   |---|--------|------|--------|-----------|-------|---------------|
   | 1 | 003-user-auth | .worktrees/003-user-auth/ | ✅ Active | spec ✅ plan ✅ tasks ✅ | 12/18 (67%) | 2 hours ago |
   | 2 | 004-chat-system | .worktrees/004-chat-system/ | 🟡 Idle | spec ✅ plan ✅ tasks ❌ | — | 12 days ago |
   | 3 | 005-api-gateway | .worktrees/005-api-gateway/ | ✅ Merged | spec ✅ plan ✅ tasks ✅ | 8/8 (100%) | 3 days ago |
   
   ## Summary
   - **Total worktrees**: 3 (+ main working directory)
   - **Active**: 1
   - **Idle**: 1
   - **Ready to clean**: 1 (merged)
   
   ## Recommended Actions
   - Run `/speckit.worktree.clean` to remove the merged worktree (005-api-gateway)
   - Resume work on 004-chat-system or run `/speckit.tasks` to generate tasks
   

5. Report: Output the dashboard. Do not modify any files — this command is read-only.

Rules

• Read-only — this command never modifies any files or worktrees
• Always include main — show the main working directory as the first entry for context
• Show all worktrees — include active, idle, stale, merged, and orphaned
• Accurate progress — task counts must reflect actual [x] and [ ] in tasks.md
• Recommend cleanup — always suggest cleaning merged or orphaned worktrees