itinerary 0.1.0

# Itinerary

A command-line interface for managing Claude Code tasks.

Itinerary provides task discovery, querying, modification, and workflow
operations optimized for AI agent coordination. Tasks use Claude Code's
stnadard JSON file format in `~/.claude/tasks/<task_list_id>/`.

## Installation

```bash
cargo install itinerary
```

## Quick Start

By default, Itinerary uses the `CLAUDE_CODE_TASK_LIST_ID` environment variable
or the current directory name as the task list ID. From any project directory,
you can immediately start managing tasks:

Create a task:

```bash
it create "Fix login bug" --body "The login form rejects valid passwords"
```

Show tasks ready to work on:

```bash
it ready
```

View task details:

```bash
it show 1
```

Add a dependency (task 5 depends on task 3):

```bash
it dep add 5 3
```

Mark a task complete:

```bash
it close 1
```

## Command Reference

### Task Operations

| Command | Description |
|---------|-------------|
| `show <id>` | Display detailed task information |
| `create <subject>` | Create a new task |
| `update <id>` | Modify an existing task |
| `close <id>` | Mark tasks as completed |
| `reopen <id>` | Revert completed tasks to pending |
| `edit <id>` | Open task in $EDITOR |

### Querying

| Command | Description |
|---------|-------------|
| `list` | Query and display tasks with filtering |
| `ready` | Show tasks ready to work on |
| `blocked` | Show tasks blocked by dependencies |
| `search <query>` | Search tasks by subject and description |
| `tree` | Display tasks in dependency hierarchy |
| `graph <id>` | Display ASCII dependency graph |
| `count` | Count tasks matching filters |
| `status` | Show summary statistics |

### Workflow

| Command | Description |
|---------|-------------|
| `pop` | Atomic ready + claim + show for task acquisition |
| `claim <id>` | Mark task as in-progress |
| `q <subject>` | Quick capture: create task and output ID |
| `duplicate <id> <canonical>` | Mark task as duplicate of another |

### Organization

| Command | Description |
|---------|-------------|
| `dep` | Manage task dependencies |
| `label` | Manage task labels |
| `category` | Manage task categories |

### Data Management

| Command | Description |
|---------|-------------|
| `export` | Export tasks to JSON Lines format |
| `import` | Import tasks from JSON Lines format |
| `doctor` | Health checks and repairs |
| `completion` | Generate shell completions |

## Global Options

```
--json                Output structured JSON
-v, --verbose         Enable detailed logging
-q, --quiet           Suppress non-essential output
--task-list <id>      Specify task list ID
--tasks-root <path>   Override tasks root directory
--readonly            Block write operations
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `CLAUDE_CODE_TASK_LIST_ID` | Override task list ID (takes precedence over current directory) |
| `ITINERARY_TASK_LIST` | Alternative task list ID |
| `ITINERARY_TASKS_ROOT` | Override tasks root directory (default: `~/.claude/tasks`) |

**Task List Resolution Order:**
1. `--task-list` CLI flag
2. `CLAUDE_CODE_TASK_LIST_ID` environment variable
3. `ITINERARY_TASK_LIST` environment variable
4. Current directory name (default)

## Task Status

Tasks have a `status` field with one of three values:

| Status | Description |
|--------|-------------|
| `pending` | Ready to work on |
| `in_progress` | Currently being worked on |
| `completed` | Finished |

## Examples

### Filter tasks by status and priority

```bash
it list --status pending --priority-max 1
```

### Find tasks with a label

```bash
it list --label urgent
```

### Search task descriptions

```bash
it search "authentication"
```

### Export and import

```bash
it export -o backup.jsonl
it import backup.jsonl
```

### Generate shell completions

```bash
it completion bash > ~/.bash_completion.d/itinerary
it completion zsh > ~/.zfunc/_itinerary
```

## Task Metadata

Itinerary extends Claude Code tasks with custom metadata fields stored in the
task's `metadata` object:

| Field | Type | Description |
|-------|------|-------------|
| `priority` | Integer 0-4 | Task priority where 0 is highest. Priority 4 is treated as backlog and excluded from `ready` by default. |
| `labels` | Array of strings | Arbitrary tags for categorizing tasks (e.g., `["urgent", "frontend"]`) |
| `category` | String | Single category for grouping related tasks (e.g., `"api"`, `"ui"`) |

These fields can be set when creating tasks:

```bash
it create "Fix bug" --priority 1 --label urgent --category api
```

And used for filtering:

```bash
it list --priority 0 --label urgent --category api
```

## Documentation

For detailed design documentation, see [docs/itinerary_design.md](docs/itinerary_design.md).

## License

Apache-2.0