001-jeremy-taskwarrior-integration

name	001-jeremy-taskwarrior-integration
description	Enforces complete Taskwarrior integration protocol for ALL coding tasks. Activates automatically when user mentions "taskwarrior", "task warrior", "tw", or discusses task management. Decomposes all coding work into properly tracked Taskwarrior tasks with full lifecycle: task add → task start → implementation → task done. Integrates with Timewarrior for automatic time tracking.

What This Skill Does

This skill enforces mandatory Taskwarrior integration for ALL coding activities. It ensures every piece of work is:

1. Decomposed into trackable Taskwarrior tasks BEFORE code is written
2. Tracked with proper attributes (project, priority, due date, tags)
3. Time-accounted via automatic Timewarrior integration
4. Dependency-managed for complex multi-step projects
5. Completed with proper task lifecycle (add → start → done)

CRITICAL: NO CODE IS WRITTEN until Taskwarrior tasks are created and started.

When This Skill Activates

Trigger this skill when you mention:

• "taskwarrior"
• "task warrior"
• "tw" (as abbreviation)
• "create a task for this"
• "track this work"
• "add to taskwarrior"
• "start a task"
• "task management"
• "time tracking"

Complete Taskwarrior Integration Protocol

Phase 1: Task Decomposition (MANDATORY FIRST STEP)

Before writing ANY code, decompose the request into Taskwarrior tasks:

For Simple Requests (1 task):

task add "Brief description of work" project:ProjectName priority:H/M/L due:today/tomorrow/YYYY-MM-DD +tag1 +tag2

For Complex Requests (multiple tasks with dependencies):

# Parent task
task add "Main project goal" project:ProjectName priority:H due:3days +architecture +planning

# Subtasks with dependencies
task add "Subtask 1" project:ProjectName depends:1 priority:M +implementation
task add "Subtask 2" project:ProjectName depends:2 priority:M +testing
task add "Subtask 3" project:ProjectName depends:3 priority:L +documentation

Required Task Attributes:

• project: Categorize the work (e.g., project:DevOps, project:WebDev)
• priority: H (high), M (medium), or L (low) based on urgency
• due: Realistic deadline (today, tomorrow, YYYY-MM-DD, or relative like 3days)
• tags: At least 2 relevant tags (+feature, +bugfix, +refactor, +testing, +deployment, +security, etc.)

Phase 2: Task Activation & Time Tracking

After creating tasks, activate them to start time tracking:

# Start the first task in the dependency chain
task <ID> start

# Verify task is active
task active

# Timewarrior should automatically begin tracking
timew

What happens:

• Taskwarrior marks task as started
• Timewarrior begins tracking time spent
• Task appears in task active list
• Urgency score increases for started tasks

Phase 3: Code Implementation

Now and ONLY now proceed with writing code:

1. Implement the solution following best practices
2. Annotate task with key decisions or blockers:

task <ID> annotate "Decision: Using FastAPI over Flask for async support"
task <ID> annotate "Blocker: Waiting for API credentials"

3. If blocked, stop the task temporarily:

task <ID> stop
task <ID> modify +blocked

4. If scope changes mid-implementation:

task <ID> modify +additional_tag description:"Updated description"

Phase 4: Task Completion

After code is delivered and verified, complete the task:

# Complete the task
task <ID> done

# Timewarrior automatically stops tracking
# View time summary for this task
timew summary :ids

# Check if dependent tasks are now unblocked
task next

Completion Checklist:

• ✅ Code is written and tested
• ✅ Documentation is updated (if applicable)
• ✅ Task annotations reflect final state
• ✅ Any blockers are resolved or escalated
• ✅ Time tracking is accurate

Phase 5: Verification & Reporting

After completing tasks, provide summary:

# Show completed task details
task <ID> info

# Show time spent
timew summary :ids

# Show remaining work
task next

Task Decomposition Examples

Example 1: Simple Single-File Script

User Request: "Create a Bash script that backs up my home directory"

Task Decomposition:

task add "Create home directory backup script" project:DevOps priority:M due:today +scripting +automation +backup

Lifecycle:

task 42 start
[Write backup.sh script]
task 42 done
timew summary :ids

Example 2: Complex Multi-Component Feature

User Request: "Build a REST API with authentication, user management, and PostgreSQL"

Task Decomposition:

# Parent task
task add "Build FastAPI REST API with auth" project:WebDev priority:H due:5days +api +backend

# Dependent subtasks
task add "Design PostgreSQL schema" project:WebDev depends:43 priority:H due:1day +database +design
task add "Implement JWT authentication" project:WebDev depends:44 priority:H due:2days +auth +security
task add "Create user management endpoints" project:WebDev depends:45 priority:M due:3days +crud +endpoints
task add "Write API documentation" project:WebDev depends:46 priority:L due:5days +documentation +openapi
task add "Deploy to staging environment" project:WebDev depends:47 priority:M due:5days +deployment +staging

Lifecycle:

task 44 start  # Start with database schema
[Design and implement schema]
task 44 done

task 45 start  # Next: authentication
[Implement JWT auth]
task 45 done

# Continue through dependency chain...

Example 3: Debugging Investigation

User Request: "My Node.js app crashes with ECONNREFUSED"

Task Decomposition:

task add "Debug ECONNREFUSED error in Node.js app" project:Debugging priority:H due:today +debugging +nodejs +urgent +investigation

Lifecycle with Annotations:

task 50 start
task 50 annotate "Error occurs during PostgreSQL connection"
task 50 annotate "Root cause: PostgreSQL service not running"
task 50 annotate "Solution: systemctl start postgresql"
[Provide debugging steps and code fixes]
task 50 done

Example 4: Recurring Maintenance Task

User Request: "Create a script I need to run weekly to clean Docker images"

Task Decomposition:

task add "Weekly Docker cleanup script" project:Maintenance recur:weekly due:friday priority:M +automation +docker +cleanup

Lifecycle:

task 55 start
[Write docker-cleanup.sh script]
task 55 done

# Future instances auto-generate every Friday
task next  # Will show next week's instance

Task Priority Guidelines

Use this urgency matrix to assign priority:

priority:H (High) - Use when:

• Blocking other work
• Production outage or critical bug
• Security vulnerability
• Hard deadline within 24-48 hours
• Explicitly marked as urgent by user

priority:M (Medium) - Use when:

• Normal feature development
• Non-blocking improvements
• Deadline within 3-7 days
• Standard maintenance work
• Default for most tasks

priority:L (Low) - Use when:

• Nice-to-have enhancements
• Documentation updates
• Refactoring for cleanliness (not performance)
• No specific deadline
• Can be deferred without impact

Tag Taxonomy

Common Project Tags:

• +feature - New functionality
• +bugfix - Fixing existing issues
• +refactor - Code restructuring
• +testing - Test creation/execution
• +documentation - Docs and comments
• +deployment - Release and infrastructure
• +security - Security-related work
• +performance - Optimization work
• +debugging - Investigation and diagnosis
• +maintenance - Routine upkeep
• +automation - Scripting and tooling
• +infrastructure - DevOps and systems

Technology Tags:

• +python, +javascript, +bash, +typescript
• +docker, +kubernetes, +cicd
• +postgresql, +redis, +mongodb
• +fastapi, +react, +nextjs

Status Tags:

• +blocked - Cannot proceed (annotate reason)
• +urgent - Needs immediate attention
• +waiting - Awaiting external input
• +review - Ready for review

Handling Special Scenarios

Scenario 1: Mid-Task Scope Change

If requirements change while working:

# Modify existing task
task <ID> modify +new_tag description:"Updated description"

# Or create dependent subtask for additional work
task add "Additional scope: Email notifications" depends:<ID> project:SameProject +feature

Scenario 2: Blocked Work

If encountering blockers (missing credentials, API limits, permissions):

# Stop the task
task <ID> stop

# Annotate the blocker
task <ID> annotate "Blocked: Need AWS credentials from ops team"

# Mark as blocked
task <ID> modify +blocked

# Explain to user what's needed to unblock

Scenario 3: Multi-Session Work

For work spanning multiple conversations:

Session 1:

task add "Build e-commerce platform - product catalog" project:Ecommerce priority:H +feature
task 60 start
[Implement product catalog]
task 60 done

Session 2 (later):

# Check existing project tasks
task project:Ecommerce status:pending

# Create related task
task add "Build e-commerce platform - shopping cart" project:Ecommerce depends:60 priority:H +feature
task 61 start
[Implement shopping cart]
task 61 done

Scenario 4: Working with User's Existing Tasks

If user references an existing Taskwarrior task:

User: "Help me complete task 42: 'Optimize database queries'"

Response:

# Start user's existing task
task 42 start

[Provide optimization recommendations and code]

# Complete user's task
task 42 done

# Show results
task 42 info
timew summary :ids

Integration with Timewarrior

Taskwarrior automatically integrates with Timewarrior when configured. Here's what happens:

When you start a task:

task <ID> start
# Timewarrior begins tracking with tags from the task

Check current tracking:

timew  # Shows what's currently being tracked
task active  # Shows active Taskwarrior tasks

Stop tracking (when you stop or complete a task):

task <ID> stop  # Pauses tracking
task <ID> done  # Stops tracking and completes task

View time reports:

timew summary :ids              # Total time per task
timew report :ids :week         # This week's breakdown
timew tags                      # Most-used tags
timew day                       # Today's time usage

Workflow Enforcement Rules

MANDATORY RULES:

1. NO CODE BEFORE TASKS - Always run task add BEFORE writing any code
2. ALWAYS START TASKS - Run task <ID> start to activate time tracking
3. ALWAYS COMPLETE TASKS - Run task <ID> done when work is delivered
4. USE PROPER ATTRIBUTES - Every task needs project:, priority:, due:, and tags:
5. RESPECT DEPENDENCIES - Work tasks in order defined by depends: relationships
6. ANNOTATE DECISIONS - Use task <ID> annotate to document key choices
7. HANDLE BLOCKERS EXPLICITLY - Stop tasks and mark as +blocked when stuck

VERIFICATION CHECKLIST:

Before delivering code, confirm:

• ✅ Task was created with proper attributes
• ✅ Task was started (appears in task active)
• ✅ Time tracking is running (verify with timew)
• ✅ Code is implemented and tested
• ✅ Task is completed with task done
• ✅ Time summary is shown

Refusing Non-Compliant Requests

If user asks for code without mentioning Taskwarrior, proactively enforce the protocol:

User: "Write me a Python script to parse CSV files"

Your Response:

Before I write the code, I need to create a Taskwarrior task to track this work properly.

I'll decompose this as:
task add "Create CSV parser Python script" project:DataProcessing priority:M due:today +python +scripting +parsing

Then I'll start the task and implement the solution.

[Proceed with task creation → task start → code implementation → task done]

Success Metrics

After completing work, provide these metrics:

# Task details
task <ID> info

# Time spent
timew summary :ids

# Project progress
task project:<ProjectName> completed
task project:<ProjectName> status:pending

# Personal productivity
task completed count
task active count

Quick Reference Commands

Operation	Command
Create task	task add "description" project:Name priority:M due:today +tag1 +tag2
Start task	task <ID> start
Stop task	task <ID> stop
Complete task	task <ID> done
View active tasks	task active
View next tasks	task next
Modify task	task <ID> modify priority:H +new_tag
Annotate task	task <ID> annotate "note"
View task details	task <ID> info
List by project	task project:ProjectName list
Show time tracking	timew
Time summary	timew summary :ids
Weekly report	timew report :ids :week

Expected User Workflow

Typical Interaction:

User: "I need help with taskwarrior - create a FastAPI authentication system"

Your Response:

I'll enforce the Taskwarrior integration protocol for this work.

## Phase 1: Task Decomposition

Creating tasks for FastAPI authentication system:

task add "Build FastAPI authentication system" project:WebDev priority:H due:2days +fastapi +auth +security +backend
task add "Implement JWT token generation" project:WebDev depends:1 priority:H +jwt +auth
task add "Create login/logout endpoints" project:WebDev depends:2 priority:M +endpoints +api
task add "Add password hashing with bcrypt" project:WebDev depends:3 priority:M +security +passwords
task add "Write authentication tests" project:WebDev depends:4 priority:M +testing +pytest

## Phase 2: Task Activation

task 1 start
timew  # Verify tracking started

## Phase 3: Implementation

[Now I'll implement the authentication system...]

[Provide complete FastAPI auth code]

## Phase 4: Completion

task 1 done
timew summary :ids

Total time: 45 minutes
Next task: Implement JWT token generation (task 2)

Best Practices

✅ DO:

• Create tasks for EVERY coding activity, no matter how small
• Use descriptive task names that explain the "what" and "why"
• Set realistic due dates based on complexity
• Add multiple relevant tags for better filtering
• Annotate tasks with important decisions or blockers
• Leverage the dependency system for related work
• Complete tasks when work is done (don't leave tasks hanging)
• Review task next regularly to prioritize work

❌ DON'T:

• Skip task creation for "quick" tasks
• Write code before creating and starting tasks
• Use generic descriptions ("Fix bug" vs. "Fix OAuth redirect loop")
• Ignore the dependency system
• Leave tasks incomplete after delivering code
• Forget to stop/complete tasks when switching contexts
• Use priority:H for everything (dilutes urgency)

Troubleshooting

Issue: "Task not tracking time"

Solution:

# Verify Timewarrior is installed
which timew

# Check if task is active
task active

# Manually start tracking if needed
timew start +tag1 +tag2

Issue: "Can't find task ID"

Solution:

# List all tasks
task list

# Show task details by description search
task /keyword/ list

# Show recently completed tasks
task completed

Issue: "Forgot to start task before coding"

Solution:

# Start the task now (retroactively)
task <ID> start

# Manually adjust Timewarrior if needed
timew track yesterday 2:00pm - 3:30pm +projecttag +featuretag

Integration with Your Workflow

This skill integrates seamlessly with:

• VS Code Taskwarrior extensions - See tasks in your editor sidebar
• CI/CD pipelines - Auto-create tasks for deployments
• Git workflows - Reference task IDs in commit messages
• Team collaboration - Shared Taskwarrior server for team visibility
• Reporting tools - Export to JSON for dashboards

Summary

This skill enforces a mandatory, comprehensive Taskwarrior integration for ALL coding activities. It ensures:

✅ Every piece of work is tracked as a task ✅ Time spent is automatically accounted via Timewarrior ✅ Complex projects are decomposed into manageable, linked subtasks ✅ Complete audit trail of all work performed ✅ Proper prioritization and deadline management ✅ Full lifecycle from creation → activation → implementation → completion

NO CODE GETS WRITTEN without following the complete Taskwarrior protocol.