path: root/Omni/Task/README.md

# Task Manager for AI Agents

The task manager is a dependency-aware issue tracker inspired by beads. It uses:
- **Storage**: SQLite database (`~/.cache/omni/tasks/tasks.db`)
- **Dependencies**: Tasks can block other tasks
- **Ready work detection**: Automatically finds unblocked tasks

**IMPORTANT**: You MUST use `task` for ALL issue tracking. NEVER use markdown TODOs, todo_write, task lists, or any other tracking methods.

## Human Setup vs Agent Usage

**If you see "database not found" or similar errors:**
```bash
task init --quiet  # Non-interactive, auto-setup, no prompts
```

**Why `--quiet`?** The regular `task init` may have interactive prompts. The `--quiet` flag makes it fully non-interactive and safe for agent-driven setup.

**If `task init --quiet` fails:** Ask the human to run `task init` manually, then continue.

## Create a Task
```bash
task create "<title>" [--type=<type>] [--parent=<id>] [--deps=<ids>] [--dep-type=<type>] [--discovered-from=<id>] [--namespace=<ns>]
```

Examples:
```bash
# Create an epic (container for tasks)
task create "User Authentication System" --type=epic

# Create a task within an epic
task create "Design auth API" --parent=t-abc123

# Create a task with blocking dependency
task create "Write tests" --deps=t-a1b2c3 --dep-type=blocks

# Create work discovered during implementation (shortcut)
task create "Fix memory leak" --discovered-from=t-abc123

# Create related work (doesn't block)
task create "Update documentation" --deps=t-abc123 --dep-type=related

# Associate with a namespace
task create "Fix type errors" --namespace="Omni/Task"
```

**Task Types:**
- `epic` - Container for related tasks
- `task` - Individual work item (default)
- `human` - Task specifically for human operators (excluded from agent work queues)

**Dependency Types:**
- `blocks` - Hard dependency, blocks ready work queue (default)
- `discovered-from` - Work discovered during other work, doesn't block
- `parent-child` - Epic/subtask relationship, blocks ready work
- `related` - Soft relationship, doesn't block

The `--namespace` option associates the task with a specific namespace in the monorepo (e.g., `Omni/Task`, `Biz/Cloud`). This helps organize tasks by the code they relate to.

## List Tasks
```bash
task list [options]  # Flags can be in any order
```

Examples:
```bash
task list                              # All tasks
task list --type=epic                  # All epics
task list --parent=t-abc123            # All tasks in an epic
task list --status=open                # All open tasks
task list --status=done                # All completed tasks
task list --namespace="Omni/Task"      # All tasks for a namespace
task list --parent=t-abc123 --status=open  # Combine filters: open tasks in epic
```

## Get Ready Work
```bash
task ready
```

Shows all tasks that are:
- Not closed
- Not blocked by incomplete dependencies

## Update Task Status
```bash
task update <id> <status>
```

Status values: `open`, `in-progress`, `done`

Examples:
```bash
task update t-20241108120000 in-progress
task update t-20241108120000 done
```

**Note**: Task updates are immediately saved to the SQLite database.

## View Dependencies
```bash
task deps <id>
```

Shows the dependency tree for a task.

## View Task Tree
```bash
task tree [<id>]
```

Shows task hierarchy with visual status indicators:
- `[ ]` - Open
- `[~]` - In Progress
- `[✓]` - Done

Examples:
```bash
task tree                 # Show all epics with their children
task tree t-abc123        # Show specific epic/task with its children
```

## Export Tasks
```bash
task export [-o <file>]
```

Exports tasks to JSONL format (stdout by default, or to a file with `-o`).

## Import Tasks
```bash
task import -i <file>
```

Imports tasks from a JSONL file, merging with existing tasks. Newer tasks (based on `updatedAt` timestamp) take precedence.

Examples:
```bash
task import -i /path/to/backup.jsonl
```

## Initialize (First Time)
```bash
task init
```

Creates the SQLite database at `~/.cache/omni/tasks/tasks.db`.

## Common Workflows

### Starting New Work

1. **Find what's ready to work on:**
   ```bash
   task ready
   ```

2. **Pick a task and mark it in progress:**
   ```bash
   task update t-20241108120000 in-progress
   ```

3. **When done, mark it complete:**
   ```bash
   task update t-20241108120000 done
   ```

### Creating Dependent Tasks

When you discover work that depends on other work:

```bash
# Create the blocking task first
task create "Design API" --type=task

# Note the ID (e.g., t-20241108120000)

# Create dependent task with blocking dependency
task create "Implement API client" --deps=t-20241108120000 --dep-type=blocks
```

The dependent task won't show up in `task ready` until the blocker is marked `done`.

### Discovered Work Pattern

When you find work during implementation, use the `--discovered-from` flag:

```bash
# While working on t-abc123, you discover a bug
task create "Fix memory leak in parser" --discovered-from=t-abc123

# This is equivalent to:
task create "Fix memory leak in parser" --deps=t-abc123 --dep-type=discovered-from
```

The `discovered-from` dependency type maintains context but **doesn't block** the ready work queue. This allows AI agents to track what work was found during other work while still being able to work on it immediately.

### Working with Epics

```bash
# Create an epic for a larger feature
task create "User Authentication System" --type=epic
# Note ID: t-abc123

# Create child tasks within the epic
task create "Design login flow" --parent=t-abc123
task create "Implement OAuth" --parent=t-abc123
task create "Add password reset" --parent=t-abc123

# List all tasks in an epic
task list --parent=t-abc123

# List all epics
task list --type=epic
```

## Agent Best Practices

### 1. ALWAYS Check Ready Work First
Before asking what to do, you MUST check `task ready --json` to see unblocked tasks.

### 2. ALWAYS Create Tasks for Discovered Work
When you encounter work during implementation, you MUST create linked tasks:
```bash
task create "Fix type error in auth module" --discovered-from=t-abc123 --json
task create "Add missing test coverage" --discovered-from=t-abc123 --json
```

**Bug Discovery Pattern**

When you discover a bug or unexpected behavior:
```bash
# CORRECT: Immediately file a task
task create "Command X fails when Y" --discovered-from=<current-task-id> --json

# WRONG: Ignoring it and moving on
# WRONG: Leaving a TODO comment
# WRONG: Mentioning it but not filing a task
```

**Examples of bugs you MUST file:**
- "Expected `--flag value` to work but only `--flag=value` works"
- "Documentation says X but actual behavior is Y"
- "Combining two flags causes parsing error"
- "Feature is missing that would be useful"

**CRITICAL: File bugs immediately when you discover them:**
- If a command doesn't work as documented → create a task
- If a command doesn't work as you expected → create a task
- If behavior is inconsistent or confusing → create a task
- If documentation is wrong or misleading → create a task
- If you find yourself working around a limitation → create a task

**NEVER leave TODO comments in code.** Create a task instead.

**NEVER ignore bugs or unexpected behavior.** File a task for it immediately.

### 3. Forbidden Patterns

**Markdown checklist (NEVER do this):**
```markdown
❌ Wrong:
- [ ] Refactor auth module
- [ ] Add tests
- [ ] Update docs

✅ Correct:
task create "Refactor auth module" -p 2 --json
task create "Add tests for auth" -p 2 --json
task create "Update auth docs" -p 3 --json
```

**todo_write tool (NEVER do this):**
```
❌ Wrong: todo_write({todos: [{content: "Fix bug", ...}]})
✅ Correct: task create "Fix bug in parser" -p 1 --json
```

**Inline code comments (NEVER do this):**
```python
❌ Wrong:
# TODO: write tests for this function
# FIXME: handle edge case

✅ Correct:
# Create task instead:
task create "Write tests for parse_config" -p 2 --namespace="Omni/Config" --json
task create "Handle edge case in parser" -p 1 --discovered-from=<current-id> --json
```

### 4. Track Dependencies
If work depends on other work, use `--deps`:
```bash
# Can't write tests until implementation is done
task create "Test auth flow" --deps=t-20241108120000 --dep-type=blocks --json
```

### 5. Use Descriptive Titles
Good: `"Add JWT token validation to auth middleware"`
Bad: `"Fix auth"`

### 6. Use Epics for Organization
Organize related work using epics:
- Create an epic for larger features: `task create "Feature Name" --type=epic --json`
- Add tasks to the epic using `--parent=<epic-id>`
- Use `--discovered-from` to track work found during implementation

### 7. ALWAYS Store AI Planning Docs in `_/llm` Directory
AI assistants often create planning and design documents during development:
- PLAN.md, DESIGN.md, TESTING_GUIDE.md, tmp, and similar files
- **You MUST use a dedicated directory for these ephemeral files**
- Store ALL AI-generated planning/design docs in `_/llm`
- The `_` directory is ignored by git and all of our temporary files related to the omnirepo go there
- NEVER commit planning docs to the repo root

## Dependency Rules

- A task is **blocked** if any of its dependencies are not `done`
- A task is **ready** if all its dependencies are `done` (or it has no dependencies)
- `task ready` only shows tasks with status `open` or `in-progress` that are not blocked

## Storage

Tasks are stored in a SQLite database at `~/.cache/omni/tasks/tasks.db`. This is a local database, not git-tracked.

To back up or transfer tasks, use `task export` and `task import`.

## Testing and Development

**CRITICAL**: When manually testing task functionality, use the test database:

```bash
# Set test mode to protect production database
export TASK_TEST_MODE=1

# Now all task operations use _/tmp/tasks-test.db
task create "Test task" --type=task
task list
task tree

# Unset when done
unset TASK_TEST_MODE
```

**The test suite automatically uses test mode** - you don't need to set it manually when running `task test` or `bild --test Omni/Task.hs`.

## Troubleshooting

### "Task not found"
- Check the task ID is correct with `task list`
- Ensure you've run `task init`

### "Database not initialized"
Run: `task init`

### Dependencies not working
- Verify dependency IDs exist: `task list`
- Check dependency tree: `task deps <id>`

## Reinforcement: Critical Rules

Remember these non-negotiable rules:

- ✅ Use `task` for ALL task tracking (with `--json` flag)
- ✅ Link discovered work with `--discovered-from` dependencies
- ✅ File bugs IMMEDIATELY when you discover unexpected behavior
- ✅ Check `task ready --json` before asking "what should I work on?"
- ✅ Store AI planning docs in `_/llm` directory
- ❌ NEVER use `todo_write` tool
- ❌ NEVER create markdown TODO lists or task checklists
- ❌ NEVER put TODOs or FIXMEs in code comments
- ❌ NEVER use external issue trackers
- ❌ NEVER duplicate tracking systems
- ❌ NEVER clutter repo root with planning documents

**If you find yourself about to use todo_write or create a markdown checklist, STOP and use `task create` instead.**