path: root/Omni/Task/DESIGN.md

# Task Manager Improvement Plan

Based on beads project planning patterns, here are proposed improvements for Omni/Task.hs.

## Current State

**What we have:**
- ✅ Basic CRUD operations (create, list, update, ready)
- ✅ Dependency tracking (--deps for blocking)
- ✅ JSONL storage with git sync
- ✅ Short base62 task IDs
- ✅ Optional namespace field
- ✅ Project field for grouping
- ✅ Three status levels (open, in-progress, done)

**What we're missing:**
- ❌ Multiple dependency types (blocks, discovered-from, parent-child, related)
- ❌ Hierarchical task IDs (parent.1, parent.2)
- ❌ Task types (epic vs task) - epics will replace "project"
- ❌ Dependency tree visualization
- ❌ Work discovery tracking
- ❌ Epic/child task relationships

## Proposed Improvements (Priority Order)

### Phase 1: Core Features (High Priority)

#### 1.1 Add Task Types (Epic vs Task)
```haskell
data TaskType = Epic | Task
  deriving (Show, Eq, Generic)
```

**Benefits:**
- Epics are containers for related tasks (replace "project" concept)
- Tasks are the actual work items
- Simple two-level hierarchy
- Epic-based planning support

**Schema Changes:**
- Replace `taskProject :: Text` with `taskType :: TaskType`
- Add `taskParent :: Maybe Text` for parent epic
- Epics can contain tasks or other epics (for nested structure)

**Commands:**
```bash
# Create an epic (container)
task create "User Authentication System" --type=epic

# Create tasks within an epic
task create "Design API" --type=task --parent=t-abc123
task create "Implement JWT" --type=task --parent=t-abc123

# Create a sub-epic (optional, for complex projects)
task create "OAuth Integration" --type=epic --parent=t-abc123
```

#### 1.2 Enhanced Dependency Types
```haskell
data DependencyType = Blocks | DiscoveredFrom | ParentChild | Related
  deriving (Show, Eq, Generic)
```

**Benefits:**
- Track work discovery context
- Maintain audit trail
- Support epic hierarchies

**Commands:**
```bash
task create "Fix bug" project --discovered-from=t-abc123
task create "Subtask 1" project --parent=t-epic-id
task dep add t-123 t-124 --type=related
```

### Phase 2: Hierarchical Tasks (Medium Priority)

#### 2.1 Parent-Child Task IDs
**Pattern:** `t-abc123.1`, `t-abc123.2`, `t-abc123.3`

**Benefits:**
- Human-friendly sequential IDs under epic
- Natural work breakdown
- Up to 3 levels of nesting

**Schema Changes:**
```haskell
data Task = Task
  { ...
    taskParent :: Maybe Text  -- Parent task ID
    ...
  }

-- New table for child counters
CREATE TABLE child_counters (
    parent_id TEXT PRIMARY KEY,
    last_child INTEGER NOT NULL DEFAULT 0,
    FOREIGN KEY (parent_id) REFERENCES tasks(id) ON DELETE CASCADE
);
```

**Commands:**
```bash
task create "Design auth API" project --parent=t-abc123
# Creates: t-abc123.1

task create "Implement JWT" project --parent=t-abc123
# Creates: t-abc123.2
```

#### 2.2 Dependency Tree Visualization
```bash
task tree t-epic-id
# Shows:
# t-abc123 [Epic] User Authentication System
#   t-abc123.1 [Task] Design auth API
#   t-abc123.2 [Task] Implement JWT
#     t-abc123.2.1 [Task] Add token generation
#     t-abc123.2.2 [Task] Add token validation
#   t-abc123.3 [Task] Add password hashing
```

### Phase 3: Project Management (Lower Priority)

#### 3.1 Task Filtering and Queries
```bash
task list --type=epic
task list --status=open
task list --parent=t-epic-id  # List all children
```

#### 3.2 Epic Statistics
```bash
task stats                     # Overall stats
task stats --epic=t-abc123     # Epic-specific
task progress t-epic-id        # Epic completion %
```

#### 3.3 Discovered Work Tracking
```bash
task create "Found memory leak" project --discovered-from=t-abc123
# Automatically links context
# Shows in dependency tree as "discovered during t-abc123"
```

## Implementation Strategy

### Milestone 1: Type System Foundations
- [ ] Add TaskType enum (Epic | Task)
- [ ] Add DependencyType enum
- [ ] Update Task data structure (replace project with type and parent)
- [ ] Update CLI commands
- [ ] Update tests
- [ ] Update AGENTS.md
- [ ] Migration: existing tasks default to type=Task, project becomes epic name

### Milestone 2: Enhanced Dependencies
- [ ] Add `discovered-from` support
- [ ] Add `related` dependency type
- [ ] Track dependency metadata (who, when, why)
- [ ] Update ready work algorithm to respect dependency types

### Milestone 3: Hierarchical Structure
- [ ] Add parent field to Task
- [ ] Implement child ID generation (t-abc123.1)
- [ ] Add child_counters table/storage
- [ ] Update createTask to handle --parent flag
- [ ] Implement parent-child dependency creation

### Milestone 4: Visualization & Reporting
- [ ] Implement `task tree` command
- [ ] Implement `task stats` command
- [ ] Implement `task progress` for epics
- [ ] Add filtering by type, priority
- [ ] Improve task list display with colors/formatting

## Open Questions

1. **Storage Format**: Should we keep JSONL or move to SQLite like beads?
   - JSONL: Simple, git-friendly, human-readable
   - SQLite: Fast queries, complex relationships, beads-compatible
   - **Recommendation**: Start with JSONL, can add SQLite later for caching

2. **Child Counter Storage**: Where to store child counters?
   - Option A: Separate .tasks/counters.jsonl file
   - Option B: In-memory during session, persist to JSONL
   - Option C: Add SQLite just for this
   - **Recommendation**: Option A - separate JSONL file

3. **Dependency Storage**: How to store complex dependencies?
   - Current: List of text IDs in task
   - Beads: Separate dependencies table
   - **Recommendation**: Add dependencies field with type info:
     ```haskell
     data Dependency = Dependency
       { depId :: Text
       , depType :: DependencyType
       }
     ```

4. **Backward Compatibility**: How to handle existing tasks?
   - Add sensible defaults (type=Task, priority=Medium)
   - Migration script or auto-upgrade on load?
   - **Recommendation**: Auto-upgrade with defaults on import

## Benefits Summary

**For AI Agents:**
- Better work discovery and context tracking
- Clearer project structure
- Easier to understand what work is related
- Natural way to break down large tasks

**For Humans:**
- Epic-based planning for large features
- Priority-driven work queue
- Visual dependency trees
- Better project tracking and reporting

**For Collaboration:**
- Discovered work maintains context
- Related work is easily found
- Epic structure provides clear organization
- Dependency tracking prevents duplicate work

## Next Steps

1. Create tasks for each milestone
2. Start with Milestone 1 (Type System Foundations)
3. Get feedback on hierarchical ID format
4. Implement incrementally, test thoroughly
5. Update AGENTS.md with new patterns