taskwarrior

Taskwarrior Skill

Purpose: Task management using taskwarrior with smart notifications and markdown context integration.

Philosophy: Minimal wrapper around taskwarrior CLI. Let taskwarrior do what it does best, add Python helpers only for custom workflows.

Quick Start

Creating Tasks

# Simple task
task add "Fix bug in worker status" project:clawd +bugfix priority:H due:tomorrow

# Task with inline notes
task add "Research taskwarrior hooks" project:clawd +research priority:M
task 1 annotate "Check: on-modify, on-exit hooks
Look at examples in taskwarrior docs
Test with simple echo script first"

# Task with external documentation
task add "Design OAuth refresh flow" project:clawd +design priority:H due:3days
task 1 annotate "Design: ~/clawd/docs/plans/2026-01-31-oauth-refresh-design.md"

Managing Tasks

# Mark as active
task 1 start

# Add notes
task 1 annotate "Additional context here"

# Complete task
task 1 done

# Delete task (no longer relevant)
task 1 delete

# Defer task for a week
task 1 modify wait:1week

Viewing Tasks

# List all pending tasks
task

# List by project
task project:clawd list

# List by tag
task +bugfix list

# View specific task
task 1

# View task with markdown context
~/clawd/skills/taskwarrior/scripts/task-open.py 1

Task Structure

Core Attributes

• Description (required): Short, clear task title
• Project: Hierarchical grouping (e.g., clawd, clawd.skills, guion.flicknote)
• Tags: Multiple single-word tags (e.g., +bugfix, +research, +implementation)
• Priority: H/M/L for importance
• Due date: When task should be completed
• Annotations: Multi-line notes or file references

Three Task Patterns

Pattern 1: Simple tasks - No extra context needed

task add "Update README" project:clawd priority:L

Pattern 2: Tasks with inline notes - Context fits in annotations

task add "Investigate performance issue" project:clawd +bugfix priority:H
task 1 annotate "User reports slow response on large datasets
Check database query optimization
Profile API endpoint response times"

Pattern 3: Tasks with external docs - Complex planning needs separate file

task add "Design new feature architecture" project:clawd +design priority:H
task 1 annotate "Design: ~/clawd/docs/plans/2026-01-31-feature-design.md"
# View with: ~/clawd/skills/taskwarrior/scripts/task-open.py 1

File Reference Formats

The task-open.py script recognizes these annotation patterns:

Design: ~/clawd/docs/plans/2026-01-31-design.md
Doc: ~/clawd/docs/architecture.md
Reference: ~/clawd/docs/api-spec.md
File: ~/path/to/any-doc.md

All paths are expanded automatically (~ → home directory).

Status Management

• Pending → Default state for new tasks
• Active → task N start when currently working on it
• Completed → task N done when finished
• Deleted → task N delete if no longer relevant
• Waiting → task N modify wait:1week to defer

Task Dependencies

Taskwarrior has built-in dependency tracking. Never duplicate dependency information in descriptions or annotations.

✅ Correct Way

# Create tasks
task add "Fix authentication bug" project:clawd +bugfix priority:H
task add "Deploy authentication fix" project:clawd +deployment priority:H

# Set dependency (task 2 depends on task 1)
task 2 modify depends:1

# Annotations should have context, not dependency info
task 2 annotate "Need staging environment approval before production deploy"

Result:

task list
# Shows:
# 1 [H] Fix authentication bug
# 2 [H] Deploy authentication fix (BLOCKED)

Task 2 automatically shows as BLOCKED until task 1 is completed.

❌ Wrong Way - Don't Do This!

# BAD: Putting dependency info in annotations
task 2 annotate "Blocked by: Task #1 (authentication bug fix)"
task 2 modify depends:1  # Already tracked by taskwarrior!

Why this is bad:

• Duplicates information taskwarrior already tracks
• Annotations become stale when dependencies change
• Harder to query/filter by actual dependency status
• Violates DRY (Don't Repeat Yourself)

Managing Dependencies

# View dependencies
task 2 info  # Shows "Depends on: 1"

# Remove dependency
task 2 modify depends:

# Multiple dependencies
task 3 modify depends:1,2  # Task 3 depends on both 1 and 2

# View all blocked tasks
task +BLOCKED list

Helper Script for Workers

When working on a task, you can easily create a follow-up task that depends on the current one:

# From within a worker session:
create_dependent_task.py "Add timeouts to subprocess calls" --priority H

What it does:

• Automatically finds current task from $ZELLIJ_SESSION_NAME
• Creates new task with dependency on current task
• Inherits project from current task
• New task is BLOCKED until current task completes

Example workflow:

# Current task: "Migrate to taskwarrior UDAs"
create_dependent_task.py "Add error handling improvements" --priority M

# Output:
# ✓ Created dependent task: 040796ee...
#   Description: Add error handling improvements
#   Priority: M
#   Depends on: e65b0ee5...
#
# The new task will be blocked until the current task completes.

This is much easier than manually querying the current task UUID and setting dependencies!

When Task Completes

task 1 done
# Task 2 automatically becomes unblocked!

Rule: Use depends: for dependencies, use annotations for context that taskwarrior doesn't track.

⚠️ Important: Task IDs vs UUIDs

Task IDs change, UUIDs are permanent.

• Task IDs (1, 2, 3...) are NOT stable - they change when tasks complete
• UUIDs are permanent identifiers that never change
• Never reference task IDs in annotations - they become invalid when IDs shift
• Dependencies use UUIDs internally (safe to use depends:1)

❌ Bad - Don't do this:

task add "Implement feature" project:clawd
task 5 annotate "Depends on task #3 to be completed first"
# ↑ If task 3 completes, it might become task 2, reference breaks!

✅ Good - Use depends: field:

task add "Implement feature" project:clawd
task 5 modify depends:3  # Uses UUID internally, safe!
task 5 annotate "Requires authentication system to be in place"
# ↑ Describes WHY, not WHAT task number

When referencing other tasks:

• In depends: field → Use task ID (converts to UUID)
• In annotations → Describe the dependency, don't use task numbers
• For permanent references → Use UUID directly if needed

Smart Notifications

Two daily checks (8AM/2PM Asia/Taipei) via check-urgent-tasks.py:

Tier 1: Urgent Tasks

Always shown if they exist:

• Overdue: Past their due date
• Due soon: Due in next 3 days
• High-priority stale: High priority, created 3+ days ago
• Blocked ready: Dependencies resolved (future)

Tier 2: Suggestions

Shown if nothing urgent:

• High-value: High priority, recently created
• Quick wins: Unblocked, ready to start
• Fresh ideas: Added in last 48 hours
• Random element: Occasionally surface forgotten tasks

Example Output

Nothing urgent:

✅ No urgent tasks!

💡 Suggested tasks to consider:

HIGH VALUE:
  #12 [H] Design caching layer (added yesterday)

QUICK WINS:
  #23 [L] Update README with new examples (no dependencies)

FRESH IDEAS:
  #25 [M] Explore Effect.ts error handling (added 1 day ago)

Has urgent:

🔴 Urgent Tasks Need Attention:

OVERDUE (1):
  #5 [H] Fix authentication bug (due 2 days ago)

DUE TODAY:
  #8 [M] Review PR #234

💡 Also consider:
  #12 [H] Design caching layer (when you have time)

Built-in Reports

Taskwarrior has excellent built-in reporting:

# Task status breakdown by project
task summary

# Database statistics
task stats

# Visual burndown charts
task burndown.weekly
task burndown.monthly

# Task history over time
task history

Common Workflows

Daily Workflow

1. Check notifications (automatic at 8AM/2PM)
2. Review pending tasks: task
3. Start working on task: task N start
4. Complete task: task N done

Planning Workflow

1. Create task with external doc reference:

   task add "Implement new feature" project:clawd +implementation priority:H
   task annotate "Design: ~/clawd/docs/plans/2026-01-31-feature-design.md"
   

2. Write detailed design in markdown file

3. View complete context:

   ~/clawd/skills/taskwarrior/scripts/task-open.py 1
   

4. Start implementation:

   task 1 start
   

Weekly Review

# See what was completed this week
task end.after:today-7days completed

# Check summary by project
task summary

# Review burndown
task burndown.weekly

Helper Scripts

check-urgent-tasks.py

Purpose: Smart notification checker for cron

Usage:

~/clawd/skills/taskwarrior/scripts/check-urgent-tasks.py

Exit codes:

• 0: Clean or suggestions only
• 1: Urgent tasks exist

Run manually:

# Test notifications
~/clawd/skills/taskwarrior/scripts/check-urgent-tasks.py
echo $?  # Check exit code

task-open.py

Purpose: Display task with inline markdown documentation

Usage:

~/clawd/skills/taskwarrior/scripts/task-open.py <task_id>

Example:

# View task #5 with all referenced documentation
~/clawd/skills/taskwarrior/scripts/task-open.py 5

Cron Integration

Notifications run automatically twice daily:

• Morning check: 8:00 AM Asia/Taipei
• Afternoon check: 2:00 PM Asia/Taipei

Setup commands (already configured):

openclaw cron add "Morning task check" \
  --cron "0 8 * * *" \
  --session main \
  --system-event "Run ~/clawd/skills/taskwarrior/scripts/check-urgent-tasks.py" \
  --tz "Asia/Taipei"

openclaw cron add "Afternoon task check" \
  --cron "0 14 * * *" \
  --session main \
  --system-event "Run ~/clawd/skills/taskwarrior/scripts/check-urgent-tasks.py" \
  --tz "Asia/Taipei"

Data Location

• Data directory: ~/.task/
• Database: ~/.task/taskchampion.sqlite3
• Config: ~/.taskrc (uses defaults)

Taskwarrior works out of the box, no custom configuration needed.

Tips and Best Practices

Task Descriptions

• Keep descriptions short and action-oriented
• Start with verb: "Fix", "Implement", "Research", "Design"
• Be specific but concise

Good:

• "Fix authentication timeout bug"
• "Implement user profile caching"
• "Research OAuth 2.1 refresh flow"

Bad:

• "Bug" (too vague)
• "Need to look into the authentication system because users are reporting timeouts" (too long, use annotations)

Projects and Tags

Projects are hierarchical:

task add "..." project:clawd
task add "..." project:clawd.skills
task add "..." project:guion.flicknote

Tags are flat and combinable:

task add "..." +bugfix +urgent
task add "..." +research +documentation

Priorities

• H (High): Must be done soon, important
• M (Medium): Should be done, normal priority
• L (Low): Nice to have, can wait
• None: No priority set

Due Dates

Be realistic with due dates:

due:today
due:tomorrow
due:3days
due:1week
due:2026-02-15

Overuse of due dates leads to "due date fatigue". Only set when genuinely time-sensitive.

Annotations

Multiline annotations work:

task 1 annotate "First line
Second line
Third line"

Link to files for complex context:

task 1 annotate "Design: ~/clawd/docs/plans/2026-01-31-design.md"

Worker Lifecycle Hooks

Automated worker management using taskwarrior hooks that integrate with OpenClaw agents.

Overview

When you start a task (task N start), a worker is automatically spawned. When you complete a task (task N done), the worker is automatically cleaned up based on PR status.

How It Works

Task Start → Worker Spawn:

1. Hook detects task start
2. Sends task context to worker-lifecycle agent
3. Agent analyzes task and derives worker name/project
4. Agent calls ttal worker spawn
5. Task gets annotated with Worker: <session-name>
6. Telegram notification sent

Task Complete → Auto Cleanup:

1. Hook detects task completion
2. Checks for Worker: annotation
3. If PR merged: auto-cleanup (session + worktree + branch deleted)
4. If PR not merged: agent decides (keep or force cleanup)
5. If no worker: silent log
6. Telegram notification sent

Installation

The hooks are managed by chezmoi in ~/clawd/dotfiles/dot_task/hooks/:

# Hooks are automatically applied by chezmoi
chezmoi apply ~/.task/hooks

# Verify hooks are installed
task diagnostics | grep hooks
# Should show: on-modify-worker-lifecycle

# To edit hooks:
# 1. Edit in dotfiles: ~/clawd/dotfiles/dot_task/hooks/
# 2. Apply changes: chezmoi apply ~/.task/hooks
# 3. Commit to dotfiles repo

Note: Hooks are no longer symlinked. They are real files managed by chezmoi, which allows for better version control and multi-machine sync.

Configuration

The worker-lifecycle OpenClaw agent handles spawn decisions and cleanup.

# Check agent exists
openclaw agents list
# Should show: worker-lifecycle

# View agent workspace
ls ~/.openclaw/agents/worker-lifecycle/

Agent configuration in ~/.openclaw/agents/worker-lifecycle/SOUL.md defines:

• Worker naming conventions (kebab-case, max 30 chars)
• Project selection logic
• Cleanup decision criteria

Monitoring

# View hook logs
tail -f ~/.task/hooks.log

# Check worker tracking
cat ~/.clawd-zellij/worker-tracking.json

Example Workflow

# Start a task
task add "Implement user profile" project:clawd +feature priority:H
task 1 start

# Hook automatically:
# - Calls worker-lifecycle agent
# - Agent spawns worker
# - Annotates task: "Worker: impl-user-profile-clawd"
# - Sends Telegram notification

# Work in spawned worker session...
# Create PR, get it merged...

# Complete the task
task 1 done

# Hook automatically:
# - Checks Worker annotation
# - Checks PR status → merged
# - Calls ttal worker close --cleanup
# - Removes session, worktree, branch
# - Sends Telegram notification

Troubleshooting

Hook not triggering:

# Check hook is executable
ls -l ~/.task/hooks/on-modify-worker-lifecycle
# Should show: -rwxr-xr-x

# Check hook detected
task diagnostics | grep hooks

# Check logs
tail ~/.task/hooks.log

Worker not spawning:

# Check agent exists
openclaw agents list

# Check Telegram chat ID in config
cat ~/.task/hooks/config.json

# Test agent manually
openclaw agent --message "Test" --agent worker-lifecycle --deliver

Cleanup not working:

# Check ttal is installed
which ttal

# List active workers
ttal worker list

# Manual cleanup
ttal worker close <session> --force

For detailed design and implementation: ~/clawd/docs/plans/2026-02-01-taskwarrior-hooks-design.md

Advanced Features (Future)

Additional taskwarrior features available:

• Recurrence: task add "..." recur:weekly due:monday
• Contexts: task context define work project:work
• Custom reports: Define in ~/.taskrc
• Sync: Sync across devices with taskd server
• UDA: User Defined Attributes for custom metadata

See Taskwarrior documentation for details.

Troubleshooting

Task command not found

# Check if taskwarrior is installed
which task

# Install if needed (macOS)
brew install task

Python scripts not executable

chmod +x ~/clawd/skills/taskwarrior/scripts/*.py

Cron jobs not triggering

# List configured cron jobs
openclaw cron list

# Check cron logs
openclaw gateway logs

References

• Taskwarrior Official Docs
• Taskwarrior Best Practices
• Design Document
• OpenClaw Cron Documentation