> ## Documentation Index
> Fetch the complete documentation index at: https://taskgraph-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cross-Tag Task Movement

> Move tasks between tag contexts

TaskGraph 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:

```bash theme={null}
# Move a single task
taskgraph move --from=5 --to=7

# Move a subtask
taskgraph move --from=5.2 --to=7.3

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

### Cross-Tag Moves

Move tasks between different tag contexts:

```bash theme={null}
# Basic cross-tag move
taskgraph move --from=5 --from-tag=backlog --to-tag=in-progress

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

## Dependency Resolution

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

### Move with Dependencies

Move the main task along with all its dependent tasks:

```bash theme={null}
taskgraph 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:

```bash theme={null}
taskgraph 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

TaskGraph provides enhanced error messages with specific resolution suggestions:

### Cross-Tag Dependency Conflicts

When you encounter dependency conflicts, you'll see:

```text theme={null}
❌ 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: taskgraph move --from=5,6 --from-tag=backlog --to-tag=in-progress --with-dependencies
  2. Break dependencies: taskgraph move --from=5,6 --from-tag=backlog --to-tag=in-progress --ignore-dependencies
  3. Validate and fix dependencies: taskgraph validate-dependencies && taskgraph fix-dependencies
  4. Move dependencies first: taskgraph 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:

```text theme={null}
❌ 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: taskgraph remove-subtask --id=5.2 --convert
  2. Then move the promoted task: taskgraph move --from=5 --from-tag=backlog --to-tag=in-progress
  3. Or move the parent task with all subtasks: taskgraph move --from=5 --from-tag=backlog --to-tag=in-progress --with-dependencies
```

### Invalid Tag Combinations

When source and target tags are the same:

```text theme={null}
❌ 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: taskgraph move --from=<id> --to=<id> --tag=backlog
  3. Check available tags: taskgraph tags
```

## Best Practices

### 1. Check Dependencies First

Before moving tasks, validate your dependencies:

```bash theme={null}
# Check for dependency issues
taskgraph validate-dependencies

# Fix common dependency problems
taskgraph 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:

```bash theme={null}
# Move multiple tasks with dependencies
taskgraph move --from=5,6,7 --from-tag=backlog --to-tag=in-progress --with-dependencies

# Move multiple tasks, breaking dependencies
taskgraph 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:

```bash theme={null}
# This will create the "new-feature" tag if it doesn't exist
taskgraph move --from=5 --from-tag=backlog --to-tag=new-feature
```

### Current Tag Fallback

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

```bash theme={null}
# Uses current tag as source
taskgraph move --from=5 --to-tag=in-progress
```

## MCP Integration

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

```javascript theme={null}
// 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 `taskgraph tags`
2. **"Task not found"**: Verify task IDs with `taskgraph list`
3. **"Cross-tag dependency conflicts"**: Use dependency resolution flags
4. **"Cannot move subtask"**: Promote subtask first or move parent task

### Getting Help

```bash theme={null}
# Show move command help
taskgraph move --help

# Check available tags
taskgraph tags

# Validate dependencies
taskgraph validate-dependencies

# Fix dependency issues
taskgraph fix-dependencies
```

## Examples

### Scenario 1: Moving from Backlog to In-Progress

```bash theme={null}
# Check for dependencies first
taskgraph validate-dependencies

# Move with dependencies
taskgraph move --from=5 --from-tag=backlog --to-tag=in-progress --with-dependencies
```

### Scenario 2: Breaking Dependencies

```bash theme={null}
# Move task, breaking cross-tag dependencies
taskgraph move --from=5 --from-tag=backlog --to-tag=done --ignore-dependencies
```

### Scenario 3: Force Move

Choose one of these options explicitly:

```bash theme={null}
# Move together with dependencies
taskgraph move --from=5 --from-tag=backlog --to-tag=in-progress --with-dependencies

# Or break dependencies
taskgraph move --from=5 --from-tag=backlog --to-tag=in-progress --ignore-dependencies
```

### Scenario 4: Moving Subtasks

```bash theme={null}
# Option 1: Promote subtask first
taskgraph remove-subtask --id=5.2 --convert
taskgraph move --from=5 --from-tag=backlog --to-tag=in-progress

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.