claude-task-master/docs/cross-tag-task-movement.md

Cross-Tag Task Movement

Task Master now supports moving tasks between different tag contexts, allowing you to organize your work across multiple project contexts, feature branches, or development phases.

Overview

Cross-tag task movement enables you to:

• Move tasks between different tag contexts (e.g., from "backlog" to "in-progress")
• Handle cross-tag dependencies intelligently
• Maintain task relationships across different contexts
• Organize work across multiple project phases

Basic Usage

Within-Tag Moves

Move tasks within the same tag context:

# Move a single task
task-master move --from=5 --to=7

# Move a subtask
task-master move --from=5.2 --to=7.3

# Move multiple tasks
task-master move --from=5,6,7 --to=10,11,12

Cross-Tag Moves

Move tasks between different tag contexts:

# Basic cross-tag move
task-master move --from=5 --from-tag=backlog --to-tag=in-progress

# Move multiple tasks
task-master move --from=5,6,7 --from-tag=backlog --to-tag=done

Dependency Resolution

When moving tasks between tags, you may encounter cross-tag dependencies. Task Master provides several options to handle these:

Move with Dependencies

Move the main task along with all its dependent tasks:

task-master move --from=5 --from-tag=backlog --to-tag=in-progress --with-dependencies

This ensures that all dependent tasks are moved together, maintaining the task relationships.

Break Dependencies

Break cross-tag dependencies and move only the specified task:

task-master move --from=5 --from-tag=backlog --to-tag=in-progress --ignore-dependencies

This removes the dependency relationships and moves only the specified task.

Force Move

Note: Force moves are no longer supported. Instead, use one of these options:

• --with-dependencies — move dependents together
• --ignore-dependencies — break cross-tag dependencies

⚠️ Warning: This may break dependency relationships and should be used with caution.

Error Handling

Task Master provides enhanced error messages with specific resolution suggestions:

Cross-Tag Dependency Conflicts

When you encounter dependency conflicts, you'll see:

❌ Cannot move tasks from "backlog" to "in-progress"

Cross-tag dependency conflicts detected:
  • Task 5 depends on 2 (in backlog)
  • Task 6 depends on 3 (in done)

Resolution options:
  1. Move with dependencies: task-master move --from=5,6 --from-tag=backlog --to-tag=in-progress --with-dependencies
  2. Break dependencies: task-master move --from=5,6 --from-tag=backlog --to-tag=in-progress --ignore-dependencies
  3. Validate and fix dependencies: task-master validate-dependencies && task-master fix-dependencies
  4. Move dependencies first: task-master move --from=2,3 --from-tag=backlog --to-tag=in-progress
  5. After deciding, re-run the move with either --with-dependencies or --ignore-dependencies

Subtask Movement Restrictions

Subtasks cannot be moved directly between tags:

❌ Cannot move subtask 5.2 directly between tags

Subtask movement restriction:
  • Subtasks cannot be moved directly between tags
  • They must be promoted to full tasks first

Resolution options:
  1. Promote subtask to full task: task-master remove-subtask --id=5.2 --convert
  2. Then move the promoted task: task-master move --from=5 --from-tag=backlog --to-tag=in-progress
  3. Or move the parent task with all subtasks: task-master move --from=5 --from-tag=backlog --to-tag=in-progress --with-dependencies

Invalid Tag Combinations

When source and target tags are the same:

❌ Invalid tag combination

Error details:
  • Source tag: "backlog"
  • Target tag: "backlog"
  • Reason: Source and target tags are identical

Resolution options:
  1. Use different tags for cross-tag moves
  2. Use within-tag move: task-master move --from=<id> --to=<id> --tag=backlog
  3. Check available tags: task-master tags

Best Practices

1. Check Dependencies First

Before moving tasks, validate your dependencies:

# Check for dependency issues
task-master validate-dependencies

# Fix common dependency problems
task-master fix-dependencies

2. Use Appropriate Flags

• --with-dependencies: When you want to maintain task relationships
• --ignore-dependencies: When you want to break cross-tag dependencies

3. Organize by Context

Use tags to organize work by:

• Development phases: backlog, in-progress, review, done
• Feature branches: feature-auth, feature-dashboard
• Team members: alice-tasks, bob-tasks
• Project versions: v1.0, v2.0

4. Handle Subtasks Properly

For subtasks, either:

1. Promote the subtask to a full task first
2. Move the parent task with all subtasks using --with-dependencies

Advanced Usage

Multiple Task Movement

Move multiple tasks at once:

# Move multiple tasks with dependencies
task-master move --from=5,6,7 --from-tag=backlog --to-tag=in-progress --with-dependencies

# Move multiple tasks, breaking dependencies
task-master move --from=5,6,7 --from-tag=backlog --to-tag=in-progress --ignore-dependencies

Tag Creation

Target tags are created automatically if they don't exist:

# This will create the "new-feature" tag if it doesn't exist
task-master move --from=5 --from-tag=backlog --to-tag=new-feature

Current Tag Fallback

If --from-tag is not provided, the current tag is used:

# Uses current tag as source
task-master move --from=5 --to-tag=in-progress

MCP Integration

The cross-tag move functionality is also available through MCP tools:

// Move task with dependencies
await moveTask({
  from: "5",
  fromTag: "backlog", 
  toTag: "in-progress",
  withDependencies: true
});

// Break dependencies
await moveTask({
  from: "5",
  fromTag: "backlog",
  toTag: "in-progress", 
  ignoreDependencies: true
});

Troubleshooting

Common Issues

1. "Source tag not found": Check available tags with task-master tags
2. "Task not found": Verify task IDs with task-master list
3. "Cross-tag dependency conflicts": Use dependency resolution flags
4. "Cannot move subtask": Promote subtask first or move parent task

Getting Help

# Show move command help
task-master move --help

# Check available tags
task-master tags

# Validate dependencies
task-master validate-dependencies

# Fix dependency issues
task-master fix-dependencies

Examples

Scenario 1: Moving from Backlog to In-Progress

# Check for dependencies first
task-master validate-dependencies

# Move with dependencies
task-master move --from=5 --from-tag=backlog --to-tag=in-progress --with-dependencies

Scenario 2: Breaking Dependencies

# Move task, breaking cross-tag dependencies
task-master move --from=5 --from-tag=backlog --to-tag=done --ignore-dependencies

Scenario 3: Force Move

Choose one of these options explicitly:

# Move together with dependencies
task-master move --from=5 --from-tag=backlog --to-tag=in-progress --with-dependencies

# Or break dependencies
task-master move --from=5 --from-tag=backlog --to-tag=in-progress --ignore-dependencies

Scenario 4: Moving Subtasks

# Option 1: Promote subtask first
task-master remove-subtask --id=5.2 --convert
task-master move --from=5 --from-tag=backlog --to-tag=in-progress

# Option 2: Move parent with all subtasks
task-master move --from=5 --from-tag=backlog --to-tag=in-progress --with-dependencies