TASK-O-MATIC

TECHNICAL BULLETIN NO. 002

TASKS COMMANDS - TASK MANAGEMENT FIELD OPERATIONS

DOCUMENT ID: task-o-matic-cli-tasks-commands-v1

CLEARANCE: All Personnel

MANDATORY COMPLIANCE: Yes

⚠️ CRITICAL SURVIVAL NOTICE

Citizen, the tasks commands are your lifeblood in the post-deadline wasteland. Without proper task management, you're just wandering aimlessly through radioactive ruins. These commands provide structure, AI enhancement, and execution capabilities that separate survivors from the lost. Master them or watch your projects decay into chaos.

COMMAND ARCHITECTURE OVERVIEW

The tasks command group represents the core operational hub for task lifecycle management. Built on a hierarchical architecture, it supports parent-child relationships, AI-enhanced descriptions, implementation planning, and automated execution. Each subcommand specializes in specific aspects of task management while maintaining consistent interfaces and error handling.

Core Design Principles:

Hierarchical Structure: Tasks can have parent-child relationships forming trees
AI Integration: All task operations support AI enhancement and analysis
Execution Pipeline: Direct integration with external coding assistants
Progressive Enhancement: Tasks can be enhanced, split, and refined iteratively
Documentation Integration: Automatic fetching and analysis of relevant documentation

COMPLETE TASK COMMAND DOCUMENTATION

CREATE COMMAND

Command: task-o-matic tasks create

COMMAND SIGNATURE

task-o-matic tasks create --title <title> [options]

REQUIRED OPTIONS

--title <title>              # Task title (required)

OPTIONAL OPTIONS

--content <content>           # Task content (supports markdown)
--effort <effort>            # Estimated effort (small/medium/large)
--parent-id <id>             # Parent task ID (creates subtask)
--ai-enhance                 # Enhance task with AI using Context7 documentation
--stream                     # Show streaming AI output during enhancement
--ai-provider <provider>       # AI provider override
--ai-model <model>           # AI model override
--ai-key <key>               # AI API key override
--ai-provider-url <url>       # AI provider URL override
--reasoning <tokens>          # Enable reasoning for OpenRouter models (max reasoning tokens)

CREATE COMMAND EXAMPLES

#### Basic Task Creation

# Simple task creation
task-o-matic tasks create --title "Build radiation detector"

# Task with content and effort
task-o-matic tasks create \
  --title "Create water purification system" \
  --content "Design and implement a water purification system using reverse osmosis" \
  --effort large

# Create subtask
task-o-matic tasks create \
  --title "Research filtration methods" \
  --parent-id task-parent-123 \
  --content "Investigate various water filtration methods for radioactive contamination"

#### AI-Enhanced Task Creation

# Enhanced task with streaming
task-o-matic tasks create \
  --title "Implement emergency communication system" \
  --content "Build a resilient communication network for emergency situations" \
  --ai-enhance \
  --stream

# Enhanced task with custom AI model
task-o-matic tasks create \
  --title "Design shelter ventilation" \
  --ai-enhance \
  --ai-provider anthropic \
  --ai-model claude-3.5-sonnet \
  --reasoning 2048

# Enhanced subtask with Context7 documentation
task-o-matic tasks create \
  --title "Install air filtration units" \
  --parent-id task-ventilation-123 \
  --ai-enhance \
  --ai-provider openrouter \
  --ai-model anthropic/claude-3.5-sonnet

RETURN VALUES AND EXIT CODES

Success (0): Task created successfully, returns task object with ID
Validation Error (2): Invalid input parameters or missing required fields
AI Error (3): AI enhancement failed
Storage Error (4): Failed to save task to storage

ERROR CONDITIONS AND EXCEPTIONS

# Missing required title
Error: Missing required argument: title
Solution: Provide --title with descriptive task name

# Invalid parent ID
Error: Parent task not found: invalid-parent-id
Solution: Verify parent task exists or omit --parent-id

# AI enhancement failure
Error: Failed to enhance task with AI
Solution: Check AI provider configuration and network connectivity

# Storage permission error
Error: EACCES: permission denied, '.task-o-matic/tasks/1.json'
Solution: Check directory permissions and disk space

LIST COMMAND

Command: task-o-matic tasks list

COMMAND SIGNATURE

task-o-matic tasks list [options]

OPTIONAL OPTIONS

-s, --status <status>        # Filter by status (todo/in-progress/completed)
-t, --tag <tag>             # Filter by tag

LIST COMMAND EXAMPLES

#### Basic Listing

# List all tasks
task-o-matic tasks list

# Filter by status
task-o-matic tasks list --status todo
task-o-matic tasks list --status in-progress
task-o-matic tasks list --status completed

# Filter by tag
task-o-matic tasks list --tag urgent
task-o-matic tasks list --tag infrastructure
task-o-matic tasks list --tag security

# Combined filters
task-o-matic tasks list --status todo --tag critical

#### Advanced Filtering Examples

# List all completed infrastructure tasks
task-o-matic tasks list --status completed --tag infrastructure

# List all urgent todo items
task-o-matic tasks list --status todo --tag urgent

# List all in-progress security tasks
task-o-matic tasks list --status in-progress --tag security

OUTPUT FORMAT

The list command displays tasks in a structured format:

Task ID and title
Current status
Tags and effort estimates
Subtask count
Creation and modification dates

RETURN VALUES

Success (0): Tasks listed successfully
Filter Error (2): Invalid status or tag filter
Storage Error (4): Failed to read tasks from storage

SHOW COMMAND

Command: task-o-matic tasks show

COMMAND SIGNATURE

task-o-matic tasks show --id <id>

REQUIRED OPTIONS

--id <id>                   # Task ID to display (required)

SHOW COMMAND EXAMPLES

#### Basic Task Display

# Show task details
task-o-matic tasks show --id 1

# Show subtask details
task-o-matic tasks show --id 1-456

# Show task with full context
task-o-matic tasks show --id task-ventilation-system

DISPLAYED INFORMATION

Basic Details: Title, description, status, effort estimate
Metadata: Creation date, modification date, tags
Hierarchy: Parent task and subtasks
Planning: Implementation plan if available
Documentation: Relevant documentation if fetched
AI Metadata: Enhancement information and sources

ERROR CONDITIONS

# Task not found
Error: Task not found: invalid-task-id
Solution: Verify task ID with 'task-o-matic tasks list'

# Invalid task ID format
Error: Invalid task ID format
Solution: Use correct task ID format from list output

UPDATE COMMAND

Command: task-o-matic tasks update

COMMAND SIGNATURE

task-o-matic tasks update --id <id> [options]

REQUIRED OPTIONS

--id <id>                   # Task ID to update (required)

OPTIONAL OPTIONS

--title <title>              # New task title
--description <description>    # New task description
--status <status>            # New status (todo/in-progress/completed)
--effort <effort>           # New estimated effort (small/medium/large)
--tags <tags>                # New tags (comma-separated)

UPDATE COMMAND EXAMPLES

#### Basic Updates

# Update task title
task-o-matic tasks update --id 1 --title "Updated radiation detector design"

# Update task status
task-o-matic tasks update --id 1 --status in-progress
task-o-matic tasks update --id 1 --status completed

# Update multiple fields
task-o-matic tasks update \
  --id 1 \
  --title "Enhanced water purification system" \
  --description "Updated design with reverse osmosis and UV treatment" \
  --effort large \
  --tags "infrastructure,critical,water"

# Update tags only
task-o-matic tasks update --id 1 --tags "urgent,infrastructure,health"

#### Status Transition Examples

# Start working on task
task-o-matic tasks update --id 1 --status in-progress

# Mark task as completed
task-o-matic tasks update --id 1 --status completed

# Reopen completed task
task-o-matic tasks update --id 1 --status todo

VALIDATION RULES

At least one field must be specified for update
Status values must be one of: todo, in-progress, completed
Effort values must be one of: small, medium, large
Tags are comma-separated and will replace existing tags

ERROR CONDITIONS

# No update fields provided
Error: At least one field must be specified for update
Solution: Provide at least one of --title, --description, --status, --effort, --tags

# Invalid status
Error: Invalid status: invalid-status
Solution: Use valid status: todo, in-progress, completed

# Task not found
Error: Task not found: invalid-task-id
Solution: Verify task ID exists before updating

DELETE COMMAND

Command: task-o-matic tasks delete

COMMAND SIGNATURE

task-o-matic tasks delete --id <id> [options]

REQUIRED OPTIONS

--id <id>                   # Task ID to delete (required)

OPTIONAL OPTIONS

--force                      # Skip confirmation and delete anyway
--cascade                    # Delete all subtasks as well

DELETE COMMAND EXAMPLES

#### Safe Deletion

# Interactive deletion (shows confirmation)
task-o-matic tasks delete --id 1

# Delete with subtasks
task-o-matic tasks delete --id 1 --cascade

# Force deletion (no confirmation)
task-o-matic tasks delete --id 1 --force

# Force delete with cascade
task-o-matic tasks delete --id 1 --force --cascade

#### Deletion Scenarios

# Delete simple task (no subtasks)
task-o-matic tasks delete --id task-simple-123

# Delete parent task with subtasks
task-o-matic tasks delete --id task-parent-456 --cascade

# Batch deletion (requires confirmation for each)
task-o-matic tasks delete --id 1 --force
task-o-matic tasks delete --id task-456 --force
task-o-matic tasks delete --id task-789 --force

SAFETY MECHANISMS

Confirmation Required: Without --force, shows task details and requires confirmation
Cascade Protection: Without --cascade, refuses to delete tasks with subtasks
Irreversible Action: Deleted tasks cannot be recovered
Orphan Handling: Cascade deletion properly handles nested subtasks

ERROR CONDITIONS

# Task has subtasks without cascade
Error: Cannot delete task with subtasks without --cascade
Solution: Use --cascade to delete task and all subtasks

# Task not found
Error: Task not found: invalid-task-id
Solution: Verify task ID with 'task-o-matic tasks list'

# Confirmation required
Error: Use --force to confirm deletion
Solution: Add --force flag or run without --force for interactive confirmation

STATUS COMMAND

Command: task-o-matic tasks status

COMMAND SIGNATURE

task-o-matic tasks status --id <id> --status <status>

REQUIRED OPTIONS

-i, --id <id>               # Task ID (required)
-s, --status <status>         # New status (required)

STATUS COMMAND EXAMPLES

#### Status Changes

# Start task
task-o-matic tasks status --id 1 --status in-progress

# Complete task
task-o-matic tasks status --id 1 --status completed

# Reopen task
task-o-matic tasks status --id 1 --status todo

# Mark multiple tasks as in-progress
task-o-matic tasks status --id 1 --status in-progress
task-o-matic tasks status --id task-456 --status in-progress
task-o-matic tasks status --id task-789 --status in-progress

#### Workflow Integration

# Start work on next task
NEXT_TASK=$(task-o-matic tasks next --status todo | grep "ID:" | cut -d' ' -f2)
task-o-matic tasks status --id $NEXT_TASK --status in-progress

# Complete current task
task-o-matic tasks status --id task-current --status completed

# Move to next task
task-o-matic tasks next

STATUS VALUES AND MEANINGS

todo: Task is ready to start work
in-progress: Currently being worked on
completed: Task is finished and verified

STATUS TRANSITION RULES

Any status can transition to any other status
No restrictions on status changes
Automatic timestamp updates on status change
Subtask status independent of parent status

ERROR CONDITIONS

# Missing required options
Error: Missing required arguments: id, status
Solution: Provide both --id and --status

# Invalid status value
Error: Invalid status: invalid-status
Solution: Use valid status: todo, in-progress, completed

# Task not found
Error: Task not found: invalid-task-id
Solution: Verify task ID exists

TAGS COMMANDS

Commands: task-o-matic tasks add-tags, task-o-matic tasks remove-tags

ADD-TAGS COMMAND SIGNATURE

task-o-matic tasks add-tags --id <id> --tags <tags>

REMOVE-TAGS COMMAND SIGNATURE

task-o-matic tasks remove-tags --id <id> --tags <tags>

REQUIRED OPTIONS

--id <id>                   # Task ID (required)
--tags <tags>                # Tags to add/remove (comma-separated, required)

TAGS COMMAND EXAMPLES

#### Adding Tags

# Add single tag
task-o-matic tasks add-tags --id 1 --tags urgent

# Add multiple tags
task-o-matic tasks add-tags --id 1 --tags "infrastructure,critical,water"

# Add tags to subtask
task-o-matic tasks add-tags --id 1-456 --tags "research,filtration"

# Add priority tags
task-o-matic tasks add-tags --id 1 --tags "high-priority,security,compliance"

#### Removing Tags

# Remove single tag
task-o-matic tasks remove-tags --id 1 --tags urgent

# Remove multiple tags
task-o-matic tasks remove-tags --id 1 --tags "deprecated,old-priority"

# Remove all priority tags
task-o-matic tasks remove-tags --id 1 --tags "high-priority,low-priority,medium-priority"

# Clean up temporary tags
task-o-matic tasks remove-tags --id 1 --tags "temp,review-needed,draft"

#### Tag Management Workflows

# Initial tagging
task-o-matic tasks create --title "Build shelter" --tags "infrastructure,critical"
task-o-matic tasks add-tags --id 1 --tags "foundation,structure"

# Priority changes
task-o-matic tasks remove-tags --id 1 --tags "low-priority"
task-o-matic tasks add-tags --id 1 --tags "high-priority"

# Category organization
task-o-matic tasks add-tags --id 1 --tags "electrical,plumbing,hvac"
task-o-matic tasks add-tags --id task-456 --tags "security,monitoring,alerts"

TAG FORMATTING RULES

Case Insensitive: Tags are stored and matched case-insensitively
Trimmed: Whitespace is automatically trimmed from tags
No Duplicates: Adding existing tags has no effect
Comma Separated: Multiple tags specified with commas
Special Characters: Most characters allowed, avoid commas in tag names

ERROR CONDITIONS

# Missing required options
Error: Missing required arguments: id, tags
Solution: Provide both --id and --tags

# Task not found
Error: Task not found: invalid-task-id
Solution: Verify task ID exists

# Empty tags
Error: No tags specified
Solution: Provide at least one tag

ENHANCE COMMAND

Command: task-o-matic tasks enhance

COMMAND SIGNATURE

task-o-matic tasks enhance [options]

FILTERING OPTIONS

--task-id <id>              # Enhance specific task ID
--all                        # Enhance all existing tasks
--status <status>            # Filter tasks by status (todo/in-progress/completed)
--tag <tag>                 # Filter tasks by tag

OPERATION OPTIONS

--dry                        # Preview what would be enhanced without making changes
--force                      # Skip confirmation prompt for bulk operations
--stream                     # Show streaming AI output during enhancement

AI CONFIGURATION OPTIONS

--ai-provider <provider>       # AI provider override
--ai-model <model>           # AI model override
--ai-key <key>               # AI API key override
--ai-provider-url <url>       # AI provider URL override
--reasoning <tokens>          # Enable reasoning for OpenRouter models (max reasoning tokens)

ENHANCE COMMAND EXAMPLES

#### Single Task Enhancement

# Enhance specific task
task-o-matic tasks enhance --task-id 1

# Enhanced task with streaming
task-o-matic tasks enhance \
  --task-id 1 \
  --stream \
  --ai-provider anthropic \
  --ai-model claude-3.5-sonnet

# Enhanced task with reasoning
task-o-matic tasks enhance \
  --task-id 1 \
  --ai-provider openrouter \
  --ai-model anthropic/claude-3.5-sonnet \
  --reasoning 2048

#### Bulk Enhancement

# Enhance all todo tasks
task-o-matic tasks enhance --status todo

# Enhance all tasks with specific tag
task-o-matic tasks enhance --tag infrastructure

# Enhance all tasks (with confirmation)
task-o-matic tasks enhance --all

# Force enhance without confirmation
task-o-matic tasks enhance --all --force

#### Filtered Enhancement

# Enhance all in-progress critical tasks
task-o-matic tasks enhance --status in-progress --tag critical

# Enhance all small effort tasks
task-o-matic tasks enhance --tag small-effort

# Dry run to preview changes
task-o-matic tasks enhance --status todo --dry

# Enhance with custom AI model
task-o-matic tasks enhance \
  --status todo \
  --ai-provider openai \
  --ai-model gpt-4 \
  --force

ENHANCEMENT PROCESS

Task Selection: Filter tasks based on criteria
Context Gathering: Collect project context and existing documentation
AI Analysis: Use AI to enhance task descriptions with additional details
Documentation Integration: Fetch relevant documentation via Context7
Content Update: Update task with enhanced information
Metadata Storage: Save AI metadata and sources

ENHANCEMENT OUTPUT

Enhanced Content: Updated task description with additional details
AI Metadata: Provider, model, and confidence information
Documentation Sources: Referenced documentation and libraries
Processing Stats: Duration, tokens used, and cost estimates

ERROR CONDITIONS

# No tasks found
Error: No tasks found matching filters
Solution: Adjust filters or create tasks first

# Mutual exclusion violation
Error: Cannot specify both --task-id and --all
Solution: Use either specific task ID or bulk options

# AI enhancement failure
Error: Failed to enhance task with AI
Solution: Check AI configuration and network connectivity

# Confirmation required
Error: Operation cancelled by user
Solution: Use --force or confirm when prompted

SPLIT COMMAND

Command: task-o-matic tasks split

COMMAND SIGNATURE

task-o-matic tasks split [options]

FILTERING OPTIONS

--task-id <id>              # Split specific task ID
--all                        # Split all existing tasks that don't have subtasks
--status <status>            # Filter tasks by status (todo/in-progress/completed)
--tag <tag>                 # Filter tasks by tag

OPERATION OPTIONS

--dry                        # Preview what would be split without making changes
--force                      # Skip confirmation prompt for bulk operations
--stream                     # Show streaming AI output during breakdown
--tools                      # Enable filesystem tools for project analysis

AI CONFIGURATION OPTIONS

--ai-provider <provider>       # AI provider override
--ai-model <model>           # AI model override
--ai-key <key>               # AI API key override
--ai-provider-url <url>       # AI provider URL override
--reasoning <tokens>          # Enable reasoning for OpenRouter models (max reasoning tokens)

SPLIT COMMAND EXAMPLES

#### Single Task Splitting

# Split specific task
task-o-matic tasks split --task-id 1

# Split with streaming and tools
task-o-matic tasks split \
  --task-id 1 \
  --stream \
  --tools

# Split with custom AI model
task-o-matic tasks split \
  --task-id 1 \
  --ai-provider anthropic \
  --ai-model claude-3.5-sonnet \
  --reasoning 2048

#### Bulk Splitting

# Split all todo tasks
task-o-matic tasks split --status todo

# Split all tasks without subtasks
task-o-matic tasks split --all

# Split tasks by category
task-o-matic tasks split --tag infrastructure
task-o-matic tasks split --tag complex

# Force split without confirmation
task-o-matic tasks split --all --force

#### Advanced Splitting Scenarios

# Dry run to preview splits
task-o-matic tasks split --status todo --dry

# Split with project analysis
task-o-matic tasks split \
  --status in-progress \
  --tools \
  --stream

# Split specific complex tasks
task-o-matic tasks split \
  --tag "large-effort" \
  --ai-provider openrouter \
  --ai-model anthropic/claude-3.5-sonnet

# Split with custom reasoning
task-o-matic tasks split \
  --task-id 2 \
  --reasoning 4096 \
  --stream

SPLITTING PROCESS

Task Analysis: Analyze task complexity and scope
Context Gathering: Collect project structure and related tasks
AI Breakdown: Use AI to identify logical subtask components
Dependency Analysis: Determine subtask dependencies and order
Subtask Creation: Create subtasks with appropriate details
Hierarchy Update: Update parent-child relationships
Validation: Verify split quality and completeness

SPLITTING CRITERIA

Task Complexity: Large or complex tasks are prioritized
Effort Estimates: Tasks marked as large effort
Manual Selection: Specific task ID targeting
Tag-Based: Tasks tagged as complex or large
Status Filtering: Focus on todo or in-progress tasks

SPLITTING OUTPUT

Subtasks Created: Number and details of new subtasks
Parent Update: Original task updated with subtask references
Dependency Graph: Logical ordering and dependencies
AI Confidence: Split quality and confidence scores
Processing Metadata: AI model, tokens, and duration

ERROR CONDITIONS

# Task already has subtasks
Error: Task already has subtasks
Solution: Choose a task without existing subtasks or manage existing subtasks

# No tasks found for splitting
Error: No tasks found matching filters
Solution: Adjust filters or create tasks that need splitting

# AI splitting failure
Error: Failed to split task with AI
Solution: Check AI configuration and task complexity

# Mutual exclusion error
Error: Cannot specify both --task-id and bulk filters
Solution: Use either specific task or filtering options

EXECUTE COMMAND

Command: task-o-matic tasks execute

COMMAND SIGNATURE

task-o-matic tasks execute --id <id> [options]

REQUIRED OPTIONS

--id <id>                   # Task ID to execute (required)

EXECUTOR OPTIONS

--tool <tool>                # External tool to use (opencode/claude/gemini/codex, default: opencode)
-m, --model <model>           # Model to use with executor
--message <message>           # Custom message to send to tool (uses task plan if not provided)

EXECUTION CONTROL OPTIONS

--continue-session            # Continue last session (for error feedback, default: false)
--dry                        # Show what would be executed without running it
--auto-commit                # Automatically commit changes after execution (default: false)

PLANNING OPTIONS

--plan                       # Generate an implementation plan before execution (default: false)
--plan-model <model>         # Model/executor to use for planning (e.g., 'opencode:gpt-4o' or 'gpt-4o')
--review-plan                # Pause for human review of plan (default: false)

REVIEW OPTIONS

--review                     # Run AI review after execution (default: false)
--review-model <model>        # Model/executor to use for review (e.g., 'opencode:gpt-4o' or 'gpt-4o')

VALIDATION OPTIONS

--validate <command>          # Validation/verification command to run after execution (can be used multiple times)
--verify <command>            # Alias for --validate (verification command, can be used multiple times)

RETRY OPTIONS

--max-retries <number>       # Maximum number of retries (opt-in, enables retry logic)
--try-models <models>        # Progressive model/executor configs for retries (e.g., 'gpt-4o-mini,claude:sonnet-4')

EXECUTE COMMAND EXAMPLES

#### Basic Execution

# Execute task with default tool
task-o-matic tasks execute --id 1

# Execute with specific tool and model
task-o-matic tasks execute \
  --id 1 \
  --tool claude \
  --model claude-3.5-sonnet

# Execute with custom message
task-o-matic tasks execute \
  --id 1 \
  --message "Implement the radiation detection system using Geiger counter integration"

#### Planning and Review

# Execute with planning and review
task-o-matic tasks execute \
  --id 1 \
  --plan \
  --review-plan \
  --review

# Execute with custom planning model
task-o-matic tasks execute \
  --id 1 \
  --plan \
  --plan-model "opencode:gpt-4o" \
  --review-plan

# Execute with AI review
task-o-matic tasks execute \
  --id 1 \
  --review \
  --review-model anthropic:claude-3.5-sonnet

#### Validation and Verification

# Execute with validation commands
task-o-matic tasks execute \
  --id 1 \
  --validate "npm test" \
  --validate "npm run lint" \
  --verify "npm run build"

# Execute with comprehensive validation
task-o-matic tasks execute \
  --id 1 \
  --validate "pytest tests/" \
  --validate "black --check ." \
  --validate "mypy ."

#### Retry and Error Handling

# Execute with retry logic
task-o-matic tasks execute \
  --id 1 \
  --max-retries 3 \
  --try-models "gpt-4o-mini,gpt-4o,claude:sonnet-4"

# Execute with progressive model escalation
task-o-matic tasks execute \
  --id 1 \
  --max-retries 5 \
  --try-models "openrouter:gpt-4o-mini,openrouter:gpt-4o,openrouter:claude-3.5-sonnet"

# Continue failed session
task-o-matic tasks execute \
  --id 1 \
  --continue-session \
  --max-retries 2

#### Advanced Execution Scenarios

# Full execution pipeline
task-o-matic tasks execute \
  --id 1 \
  --plan \
  --plan-model "opencode:gpt-4o" \
  --review-plan \
  --tool claude \
  --model claude-3.5-sonnet \
  --validate "npm test" \
  --validate "npm run build" \
  --review \
  --review-model "opencode:gpt-4o" \
  --auto-commit

# Dry run execution
task-o-matic tasks execute \
  --id 1 \
  --dry \
  --plan \
  --validate "npm test"

# Execute with session continuation
task-o-matic tasks execute \
  --id 1 \
  --continue-session \
  --max-retries 3 \
  --try-models "gpt-4o-mini,claude:sonnet-4"

EXECUTION PIPELINE

Plan Generation (optional): Create implementation plan using AI
Plan Review (optional): Human review of generated plan
Task Execution: Send task and plan to external coding tool
Result Monitoring: Track execution progress and output
Validation (optional): Run verification commands
AI Review (optional): AI analysis of implementation quality
Commit (optional): Automatic git commit of changes

SUPPORTED EXECUTORS

opencode: OpenCode AI assistant (default)
claude: Anthropic Claude directly
gemini: Google Gemini directly
codex: GitHub Copilot/Codex

VALIDATION INTEGRATION

Build Verification: Compile and build process validation
Test Execution: Unit and integration test validation
Code Quality: Linting and static analysis validation
Functional Testing: End-to-end functionality validation

ERROR CONDITIONS

# Invalid executor tool
Error: Invalid tool: invalid-tool. Must be one of: opencode, claude, gemini, codex
Solution: Use valid executor tool

# Task not found
Error: Task not found: invalid-task-id
Solution: Verify task ID exists

# Execution failure
Error: Task execution failed
Solution: Check external tool availability and network connectivity

# Validation failure
Error: Validation commands failed
Solution: Fix validation errors and retry execution

EXECUTE-LOOP COMMAND

Command: task-o-matic tasks execute-loop

COMMAND SIGNATURE

task-o-matic tasks execute-loop [options]

FILTERING OPTIONS

--status <status>            # Filter tasks by status (todo/in-progress/completed)
--tag <tag>                 # Filter tasks by tag
--ids <ids>                  # Comma-separated list of task IDs to execute

EXECUTOR CONFIGURATION

--tool <tool>                # External tool to use (opencode/claude/gemini/codex, default: opencode)
--max-retries <number>       # Maximum number of retries per task (default: 3)
--try-models <models>        # Progressive model/executor configs for each retry

EXECUTION OPTIONS

--message <message>           # Custom message to send to tool (overrides task plan)
--continue-session            # Continue last session (for error feedback, default: false)
--auto-commit                # Automatically commit changes after each task (default: false)
--dry                        # Show what would be executed without running it (default: false)

PLANNING OPTIONS

--plan                       # Generate an implementation plan before execution (default: false)
--plan-model <model>         # Model/executor to use for planning
--review-plan                # Pause for human review of plan (default: false)

REVIEW OPTIONS

--review                     # Run AI review after execution (default: false)
--review-model <model>        # Model/executor to use for review

VALIDATION OPTIONS

--verify <command>            # Verification command to run after each task (can be used multiple times)
--validate <command>          # Alias for --verify (validation command, can be used multiple times)

EXECUTE-LOOP COMMAND EXAMPLES

#### Basic Loop Execution

# Execute all todo tasks
task-o-matic tasks execute-loop --status todo

# Execute tasks by tag
task-o-matic tasks execute-loop --tag infrastructure

# Execute specific task list
task-o-matic tasks execute-loop --ids "1,task-456,task-789"

# Execute with custom tool
task-o-matic tasks execute-loop \
  --status todo \
  --tool claude \
  --model claude-3.5-sonnet

#### Advanced Loop Configuration

# Execute with retry logic and validation
task-o-matic tasks execute-loop \
  --status todo \
  --max-retries 5 \
  --try-models "gpt-4o-mini,gpt-4o,claude:sonnet-4" \
  --validate "npm test" \
  --validate "npm run lint"

# Execute with planning and review
task-o-matic tasks execute-loop \
  --ids "1,task-456" \
  --plan \
  --review-plan \
  --review \
  --auto-commit

# Execute with session continuation
task-o-matic tasks execute-loop \
  --status in-progress \
  --continue-session \
  --max-retries 3

#### Progressive Model Escalation

# Execute with model escalation
task-o-matic tasks execute-loop \
  --status todo \
  --try-models "openrouter:gpt-4o-mini,openrouter:gpt-4o,openrouter:claude-3.5-sonnet,openrouter:claude-opus-2024"

# Execute with provider escalation
task-o-matic tasks execute-loop \
  --tag critical \
  --try-models "openai:gpt-4o-mini,anthropic:claude-3.5-sonnet,openrouter:anthropic/claude-opus-2024"

# Execute with custom escalation
task-o-matic tasks execute-loop \
  --ids "1,task-456" \
  --try-models "gpt-4o-mini:opencode,gpt-4o:claude,claude-3.5-sonnet:gemini"

#### Comprehensive Loop Execution

# Full-featured loop execution
task-o-matic tasks execute-loop \
  --status todo \
  --tool opencode \
  --max-retries 3 \
  --try-models "openrouter:gpt-4o-mini,openrouter:gpt-4o" \
  --plan \
  --plan-model "opencode:gpt-4o" \
  --review-plan \
  --review \
  --review-model "opencode:gpt-4o" \
  --validate "npm test" \
  --validate "npm run build" \
  --auto-commit

# Dry run to preview execution
task-o-matic tasks execute-loop \
  --status todo \
  --dry \
  --plan \
  --validate "npm test"

EXECUTION LOOP PROCESS

Task Filtering: Select tasks based on status, tags, or IDs
Loop Initialization: Set up retry counters and model escalation
Task Execution: For each task:

- Generate plan (if requested)

- Execute with current model/executor

- Validate results (if requested)

- Review implementation (if requested)

- Commit changes (if requested)

- Retry with next model on failure

Progress Tracking: Monitor success/failure rates
Result Summary: Report overall execution statistics

LOOP EXECUTION FEATURES

Parallel Processing: Configurable concurrency for multiple tasks
Retry Logic: Automatic retry with model escalation
Progressive Enhancement: Each retry can use better models
Error Recovery: Continue after individual task failures
Comprehensive Logging: Detailed execution logs and metrics

ERROR HANDLING IN LOOPS

Individual Task Failures: Continue with next task
Model Escalation: Automatic retry with better models
Validation Failures: Log and continue with next task
Network Issues: Retry with exponential backoff
Partial Success: Report both successful and failed tasks

ERROR CONDITIONS

# No tasks found
Error: No tasks found matching filters
Solution: Adjust filters or create tasks first

# Invalid model escalation
Error: Failed to parse --try-models
Solution: Use correct format: "model1,model2,model3"

# All tasks failed
Error: All 5 task(s) failed
Solution: Check configuration and retry with better models

# Executor validation failure
Error: Invalid tool: invalid-tool
Solution: Use valid executor: opencode, claude, gemini, codex

SUBTASKS COMMAND

Command: task-o-matic tasks subtasks

COMMAND SIGNATURE

task-o-matic tasks subtasks --id <id>

REQUIRED OPTIONS

--id <id>                   # Parent task ID (required)

SUBTASKS COMMAND EXAMPLES

#### Basic Subtask Listing

# List subtasks for task
task-o-matic tasks subtasks --id 1

# List subtasks for complex task
task-o-matic tasks subtasks --id task-shelter-system

# List subtasks for parent task
task-o-matic tasks subtasks --id task-infrastructure-456

#### Subtask Analysis

# Check subtask structure
task-o-matic tasks subtasks --id 1

# Verify subtask hierarchy
task-o-matic tasks subtasks --id task-parent-789

# Review subtask details
task-o-matic tasks subtasks --id task-water-system

SUBTASKS OUTPUT FORMAT

Parent Information: Parent task title and ID
Subtask List: All direct subtasks with details
Hierarchical Display: Indented structure showing relationships
Status Summary: Completion status of each subtask
Metadata: Creation dates, effort estimates, tags

ERROR CONDITIONS

# Task not found
Error: Task not found: invalid-task-id
Solution: Verify parent task ID exists

# No subtasks found
Warning: No subtasks found for task 1
Solution: This is normal for tasks without subtasks

# Invalid task ID format
Error: Invalid task ID format
Solution: Use correct task ID format

TREE COMMAND

Command: task-o-matic tasks tree

COMMAND SIGNATURE

task-o-matic tasks tree [options]

OPTIONAL OPTIONS

--id <id>                   # Root task ID (optional - shows full tree if not specified)

TREE COMMAND EXAMPLES

#### Full Tree Display

# Show complete task tree
task-o-matic tasks tree

# Show tree with statistics
task-o-matic tasks tree --verbose

#### Subtree Display

# Show subtree for specific task
task-o-matic tasks tree --id 1

# Show infrastructure subtree
task-o-matic tasks tree --id task-infrastructure

# Show project phase subtree
task-o-matic tasks tree --id task-phase-1

#### Tree Analysis Examples

# Analyze project structure
task-o-matic tasks tree

# Review specific component
task-o-matic tasks tree --id task-shelter-construction

# Check task dependencies
task-o-matic tasks tree --id task-electrical-system

TREE DISPLAY FEATURES

Hierarchical Structure: Parent-child relationships clearly shown
Status Indicators: Visual indicators for task status
Progress Tracking: Completion percentages for branches
Tag Display: Relevant tags shown for context
Effort Summaries: Cumulative effort estimates

TREE FORMATTING

ASCII Tree: Text-based tree structure with connectors
Color Coding: Status-based color highlighting
Indentation: Clear hierarchical level indication
Metadata Display: Task IDs and key information
Summary Statistics: Overall project progress metrics

ERROR CONDITIONS

# Root task not found
Error: Root task not found: invalid-task-id
Solution: Verify task ID exists in the tree

# Tree structure corruption
Error: Invalid task hierarchy detected
Solution: Check for circular references or missing parents

# No tasks in project
Warning: No tasks found in current project
Solution: Create tasks first with 'task-o-matic tasks create'

NEXT COMMAND

Command: task-o-matic tasks get-next

COMMAND SIGNATURE

task-o-matic tasks get-next [options]

OPTIONAL OPTIONS

-s, --status <status>        # Filter by status (todo/in-progress, default: todo)
-t, --tag <tag>             # Filter by tag
-e, --effort <effort>       # Filter by effort (small/medium/large)
-p, --priority <priority>     # Sort priority (newest/oldest/effort, default: hierarchical)

NEXT COMMAND EXAMPLES

#### Basic Next Task

# Get next todo task (default)
task-o-matic tasks get-next

# Get next in-progress task
task-o-matic tasks get-next --status in-progress

# Get next task by priority
task-o-matic tasks get-next --priority newest
task-o-matic tasks get-next --priority oldest

#### Filtered Next Task

# Get next urgent task
task-o-matic tasks get-next --tag urgent

# Get next small effort task
task-o-matic tasks get-next --effort small

# Get next infrastructure task
task-o-matic tasks get-next --tag infrastructure

# Combined filters
task-o-matic tasks get-next --status todo --tag critical --effort small

#### Priority-Based Selection

# Get newest task
task-o-matic tasks get-next --priority newest

# Get oldest task
task-o-matic tasks get-next --priority oldest

# Get by effort (smallest first)
task-o-matic tasks get-next --priority effort

# Hierarchical order (default)
task-o-matic tasks get-next --priority hierarchical

#### Workflow Integration

# Start work on next task
NEXT_TASK=$(task-o-matic tasks get-next --status todo | grep "ID:" | cut -d' ' -f2)
task-o-matic tasks status --id $NEXT_TASK --status in-progress

# Get next critical task
NEXT_CRITICAL=$(task-o-matic tasks get-next --tag critical | grep "ID:" | cut -d' ' -f2)
task-o-matic tasks execute --id $NEXT_CRITICAL

# Get next small task for quick win
NEXT_SMALL=$(task-o-matic tasks get-next --effort small | grep "ID:" | cut -d' ' -f2)
task-o-matic tasks execute --id $NEXT_SMALL --max-retries 1

NEXT TASK SELECTION ALGORITHM

#### Hierarchical Priority (Default)

Leaf Tasks First: Tasks without subtasks prioritized
Depth-First: Process subtasks before parent tasks
Creation Order: Within same level, older tasks first
Status Filter: Only consider specified status

#### Newest Priority

Creation Date: Most recently created tasks first
Status Filter: Respect status filter
No Hierarchy: Ignore parent-child relationships

#### Oldest Priority

Creation Date: Oldest tasks first
Status Filter: Respect status filter
No Hierarchy: Ignore parent-child relationships

#### Effort Priority

Effort Size: Small effort tasks first
Then Medium: Medium effort tasks
Then Large: Large effort tasks last
Within Effort: Hierarchical ordering

NEXT TASK OUTPUT

Task Details: Title, description, and metadata
Context Information: Parent task and subtasks
Selection Criteria: Why this task was selected
Work Estimates: Effort and complexity indicators
Execution Suggestions: Recommended execution approach

ERROR CONDITIONS

# No tasks found
Warning: No tasks found matching criteria
Solution: Adjust filters or create more tasks

# Invalid status filter
Error: Invalid status: invalid-status
Solution: Use valid status: todo, in-progress, completed

# Invalid effort filter
Error: Invalid effort: invalid-effort
Solution: Use valid effort: small, medium, large

# Invalid priority
Error: Invalid priority: invalid-priority
Solution: Use valid priority: newest, oldest, effort, hierarchical

FIELD OPERATIONS PROTOCOLS

#### TASK LIFECYCLE MANAGEMENT

The tasks commands implement a complete task lifecycle management system:

Creation Phase

- Initial task creation with basic information

- AI enhancement for detailed descriptions

- Parent-child relationship establishment

- Initial tagging and categorization

Planning Phase

- Implementation plan generation

- Documentation research and integration

- Subtask breakdown and dependency analysis

- Resource requirement identification

Execution Phase

- External tool integration for coding

- Progress tracking and status updates

- Validation and verification

- Error handling and retry logic

Completion Phase

- Status finalization and verification

- Result documentation and review

- Knowledge capture for future tasks

- Project progress updates

#### AI INTEGRATION PATTERNS

All task operations support AI integration through standardized patterns:

Provider Abstraction: Unified interface for multiple AI providers
Model Selection: Flexible model configuration per operation
Streaming Support: Real-time AI output for long operations
Context Enhancement: Automatic project context inclusion
Documentation Integration: Context7 MCP tools for documentation retrieval

#### STORAGE INTEGRATION

Tasks are stored using a hierarchical file system approach:

Individual Files: Each task in separate JSON file
Metadata Storage: Rich metadata alongside task data
Hierarchy Maintenance: Parent-child relationships in task data
Atomic Operations: Safe concurrent access to task files
Backup Support: Easy backup and restore capabilities

SURVIVAL SCENARIOS

#### SCENARIO 1: Project Setup and Task Creation

# Initialize project
task-o-matic init init --project-name "wasteland-shelter"

# Create main project tasks
task-o-matic tasks create --title "Design shelter foundation" --ai-enhance
task-o-matic tasks create --title "Install radiation shielding" --ai-enhance
task-o-matic tasks create --title "Set up water purification" --ai-enhance

# Create subtasks
task-o-matic tasks create \
  --title "Excavate foundation area" \
  --parent-id task-foundation \
  --ai-enhance

task-o-matic tasks create \
  --title "Install lead lining" \
  --parent-id task-shielding \
  --ai-enhance

# View task tree
task-o-matic tasks tree

#### SCENARIO 2: Task Management and Progress Tracking

# List current tasks
task-o-matic tasks list --status todo

# Get next task to work on
task-o-matic tasks get-next --status todo

# Start working on task
task-o-matic tasks status --id 1 --status in-progress

# Split complex task into subtasks
task-o-matic tasks split --task-id 2 --stream

# Update task progress
task-o-matic tasks update --id 1 --status completed

#### SCENARIO 3: AI-Enhanced Task Execution

# Execute task with full AI support
task-o-matic tasks execute \
  --id 1 \
  --plan \
  --review-plan \
  --tool claude \
  --validate "npm test" \
  --auto-commit

# Bulk execute todo tasks
task-o-matic tasks execute-loop \
  --status todo \
  --max-retries 3 \
  --try-models "gpt-4o-mini,gpt-4o,claude-3.5-sonnet" \
  --validate "npm test" \
  --auto-commit

# Enhance tasks with latest documentation
task-o-matic tasks enhance --status todo --ai-provider anthropic --stream

#### SCENARIO 4: Project Analysis and Reorganization

# Analyze project structure
task-o-matic tasks tree

# Review task details
task-o-matic tasks show --id 1

# List tasks by category
task-o-matic tasks list --tag infrastructure
task-o-matic tasks list --tag security
task-o-matic tasks list --tag critical

# Reorganize with tags
task-o-matic tasks add-tags --id 1 --tags "phase-1,critical"
task-o-matic tasks remove-tags --id 1 --tags "deprecated,old-priority"

#### SCENARIO 5: Error Recovery and Quality Assurance

# Handle execution failures
task-o-matic tasks execute \
  --id 1 \
  --max-retries 5 \
  --try-models "gpt-4o-mini,gpt-4o,claude-opus-2024" \
  --continue-session

# Review and enhance failed tasks
task-o-matic tasks enhance --task-id 1 --stream

# Validate implementation quality
task-o-matic tasks execute \
  --id 1 \
  --review \
  --review-model claude-opus-2024 \
  --validate "npm test" \
  --validate "npm run lint"

TECHNICAL SPECIFICATIONS

#### TASK DATA MODEL

interface Task {
  id: string;                    // Unique task identifier
  title: string;                 // Task title
  description?: string;            // Detailed task description
  status: 'todo' | 'in-progress' | 'completed';
  effort?: 'small' | 'medium' | 'large';
  tags: string[];               // Task tags
  parentId?: string;             // Parent task ID
  subtaskIds?: string[];         // Child task IDs
  createdAt: Date;               // Creation timestamp
  updatedAt: Date;               // Last modification timestamp
  metadata?: {                  // AI enhancement metadata
    enhanced: boolean;
    provider?: string;
    model?: string;
    confidence?: number;
    sources?: string[];
  };
  plan?: {                      // Implementation plan
    id: string;
    taskId: string;
    plan: string;
    createdAt: Date;
    updatedAt: Date;
  };
  documentation?: {               // Related documentation
    path: string;
    lastFetched: Date;
    recap: string;
    libraries: string[];
  };
}

#### PERFORMANCE CHARACTERISTICS

Task Creation: 50-200ms (without AI), 2-10s (with AI enhancement)
Task Listing: 10-100ms depending on filter complexity
Task Updates: 20-50ms
AI Enhancement: 5-30s depending on task complexity
Task Splitting: 10-60s per task
Task Execution: Variable depending on external tool

#### STORAGE REQUIREMENTS

Task Files: 1-10KB per task
Plan Files: 5-50KB per plan
Documentation Cache: 10-100MB for project
AI Metadata: 1-5KB per enhanced task
Index Overhead: 50-200KB for task indices

#### CONCURRENCY AND THREAD SAFETY

File Locking: Atomic file operations prevent corruption
Concurrent Access: Safe multiple command execution
Cache Coherency: Consistent state across operations
Rollback Support: Transaction-like operations with rollback

Remember: Citizen, in the harsh reality of post-deadline wasteland, these task commands are your survival toolkit. They provide structure, intelligence, and automation that can mean the difference between thriving and perishing. Use them wisely, respect their power, and they will guide your projects to completion even in the most challenging circumstances.

DOCUMENT STATUS: Complete

NEXT REVIEW: After next feature release

CONTACT: Task-O-Matic Task Management Team

TASK MANAGEMENT COMMANDS

COMPLETE DOCUMENTATION

TECHNICAL BULLETIN NO. 002

TASKS COMMANDS - TASK MANAGEMENT FIELD OPERATIONS

⚠️ CRITICAL SURVIVAL NOTICE

COMMAND ARCHITECTURE OVERVIEW

COMPLETE TASK COMMAND DOCUMENTATION

CREATE COMMAND

COMMAND SIGNATURE

REQUIRED OPTIONS

OPTIONAL OPTIONS

CREATE COMMAND EXAMPLES

RETURN VALUES AND EXIT CODES

ERROR CONDITIONS AND EXCEPTIONS

LIST COMMAND

COMMAND SIGNATURE

OPTIONAL OPTIONS

LIST COMMAND EXAMPLES

OUTPUT FORMAT

RETURN VALUES

SHOW COMMAND

COMMAND SIGNATURE

REQUIRED OPTIONS

SHOW COMMAND EXAMPLES

DISPLAYED INFORMATION

ERROR CONDITIONS

UPDATE COMMAND

COMMAND SIGNATURE

REQUIRED OPTIONS

OPTIONAL OPTIONS

UPDATE COMMAND EXAMPLES

VALIDATION RULES

ERROR CONDITIONS

DELETE COMMAND

COMMAND SIGNATURE

REQUIRED OPTIONS

OPTIONAL OPTIONS

DELETE COMMAND EXAMPLES

SAFETY MECHANISMS

ERROR CONDITIONS

STATUS COMMAND

COMMAND SIGNATURE

REQUIRED OPTIONS

STATUS COMMAND EXAMPLES

STATUS VALUES AND MEANINGS

STATUS TRANSITION RULES

ERROR CONDITIONS

TAGS COMMANDS

ADD-TAGS COMMAND SIGNATURE

REMOVE-TAGS COMMAND SIGNATURE

REQUIRED OPTIONS

TAGS COMMAND EXAMPLES

TAG FORMATTING RULES

ERROR CONDITIONS

ENHANCE COMMAND

COMMAND SIGNATURE

FILTERING OPTIONS

OPERATION OPTIONS

AI CONFIGURATION OPTIONS

ENHANCE COMMAND EXAMPLES

ENHANCEMENT PROCESS

ENHANCEMENT OUTPUT

ERROR CONDITIONS

SPLIT COMMAND

COMMAND SIGNATURE

FILTERING OPTIONS

OPERATION OPTIONS

AI CONFIGURATION OPTIONS

SPLIT COMMAND EXAMPLES

SPLITTING PROCESS

SPLITTING CRITERIA

SPLITTING OUTPUT

ERROR CONDITIONS

EXECUTE COMMAND

COMMAND SIGNATURE

REQUIRED OPTIONS

EXECUTOR OPTIONS

EXECUTION CONTROL OPTIONS

PLANNING OPTIONS

REVIEW OPTIONS