RAZOR STUDIO⚙ TASK-O-MATIC v0.1.1⚙ DOCS⚙ TUTORIALS⚙ BYOK
USER: DEVELOPER
MAINFRAME TERMINAL #113

WORKFLOW COMMANDS

WORKFLOW TERMINAL
⚡ WORKFLOW USAGE EXAMPLES
Run interactive workflow: bun x task-o-matic workflow
Quick setup with defaults: bun x task-o-matic workflow --skip-all
Auto-accept AI suggestions: bun x task-o-matic workflow --auto-accept
Load config from file: bun x task-o-matic workflow --config-file workflow.json
Skip PRD step: bun x task-o-matic workflow --skip-prd
Custom project setup: bun x task-o-matic workflow --project-name "MyApp" --frontend next --backend hono
← Back to CLI Overview

COMPLETE DOCUMENTATION

TECHNICAL BULLETIN NO. 003

PLAN COMMANDS - IMPLEMENTATION PLANNING FIELD OPERATIONS

DOCUMENT ID: task-o-matic-cli-plan-commands-v1
CLEARANCE: All Personnel

MANDATORY COMPLIANCE: Yes

⚠️ CRITICAL SURVIVAL NOTICE

Citizen, implementation planning is your compass in the post-deadline wasteland. Without proper planning, you're just coding blindly into radioactive fog. These plan commands provide AI-powered strategic thinking, dependency analysis, and step-by-step implementation guidance that separates successful projects from failed expeditions.

COMMAND ARCHITECTURE OVERVIEW

The plan command group represents the strategic planning layer of Task-O-Matic. It bridges the gap between high-level task definitions and concrete implementation by providing detailed, AI-generated implementation plans. The architecture supports plan creation, management, and integration with execution workflows.

Strategic Planning Components:

  • AI-Powered Planning: Leverages multiple AI models for plan generation
  • Context Integration: Automatically includes project structure and documentation
  • Dependency Analysis: Identifies and plans for task dependencies
  • Plan Management: Store, retrieve, and update implementation plans
  • Execution Integration: Seamless handoff to task execution workflows

COMPLETE PLAN COMMAND DOCUMENTATION

PLAN COMMAND (CREATE)

Command: task-o-matic tasks plan

COMMAND SIGNATURE

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

REQUIRED OPTIONS

--id <id>                   # Task or subtask ID to plan (required)

OPTIONAL OPTIONS

--stream                     # Show streaming AI output during planning
--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)

PLAN CREATE EXAMPLES

#### Basic Plan Creation

# Create plan for task
task-o-matic tasks plan --id task-123

# Create plan with streaming
task-o-matic tasks plan --id task-123 --stream

# Create plan for subtask
task-o-matic tasks plan --id task-123-456

#### AI-Enhanced Plan Creation

# Plan with custom AI provider
task-o-matic tasks plan \
  --id task-123 \
  --ai-provider anthropic \
  --ai-model claude-3.5-sonnet

# Plan with reasoning enabled
task-o-matic tasks plan \
  --id task-123 \
  --ai-provider openrouter \
  --ai-model anthropic/claude-3.5-sonnet \
  --reasoning 2048

# Plan with streaming and custom model
task-o-matic tasks plan \
  --id task-complex-789 \
  --stream \
  --ai-provider openai \
  --ai-model gpt-4

#### Advanced Planning Scenarios

# Plan for complex infrastructure task
task-o-matic tasks plan \
  --id task-shelter-foundation \
  --stream \
  --ai-provider anthropic \
  --ai-model claude-opus-2024

# Plan for security-critical task
task-o-matic tasks plan \
  --id task-authentication-system \
  --ai-provider openrouter \
  --ai-model anthropic/claude-3.5-sonnet \
  --reasoning 4096

# Plan for research and development task
task-o-matic tasks plan \
  --id task-radiation-research \
  --stream \
  --ai-provider openai \
  --ai-model o1-preview \
  --reasoning 8192

PLAN CREATION PROCESS

  • Task Analysis: Analyze task complexity, requirements, and context
  • Context Gathering: Collect project structure, dependencies, and related tasks
  • Documentation Research: Fetch relevant documentation via Context7
  • AI Planning: Generate detailed implementation plan using AI
  • Dependency Analysis: Identify and plan for task dependencies
  • Plan Validation: Verify plan completeness and feasibility
  • Storage: Save plan with metadata for future reference

PLAN CONTENT STRUCTURE

  • Implementation Steps: Detailed step-by-step instructions
  • Dependencies: Required libraries, tools, and prerequisites
  • File Structure: Recommended file and directory organization
  • Code Examples: Sample code snippets and patterns
  • Testing Strategy: Recommended testing approaches
  • Integration Points: How the implementation connects to existing code
  • Risk Assessment: Potential challenges and mitigation strategies

PLAN OUTPUT FORMAT

📋 Implementation Plan for: Build Radiation Detection System

## Overview
[High-level description of implementation approach]

## Prerequisites
[Required tools, libraries, and setup]

## Implementation Steps

### Step 1: Set up Geiger counter interface
- [Detailed instructions for hardware integration]
- [Code examples and configuration]
- [Testing procedures]

### Step 2: Implement data processing pipeline
- [Signal processing algorithms]
- [Data filtering and validation]
- [Storage integration]

### Step 3: Create alerting system
- [Threshold configuration]
- [Notification mechanisms]
- [User interface components]

## Testing Strategy
[Unit testing approach]
[Integration testing plan]
[Performance testing requirements]

## Integration Considerations
[How this connects to existing shelter systems]
[API endpoints and data flow]
[Configuration management]

## Risk Mitigation
[Potential challenges and solutions]
[Alternative approaches if primary fails]

ERROR CONDITIONS

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

# AI planning failure
Error: Failed to generate implementation plan
Solution: Check AI provider configuration and network connectivity

# Insufficient task context
Error: Cannot create plan for task without description
Solution: Enhance task with more details first

# Plan already exists
Warning: Plan already exists for task task-123
Solution: Use --force to overwrite or delete existing plan first

GET-PLAN COMMAND

Command: task-o-matic tasks get-plan

COMMAND SIGNATURE

task-o-matic tasks get-plan --id <id>

REQUIRED OPTIONS

--id <id>                   # Task or subtask ID (required)

GET-PLAN EXAMPLES

#### Basic Plan Retrieval

# Get plan for task
task-o-matic tasks get-plan --id task-123

# Get plan for subtask
task-o-matic tasks get-plan --id task-123-456

# Get plan for complex task
task-o-matic tasks get-plan --id task-shelter-system

#### Plan Analysis Examples

# Review plan before execution
task-o-matic tasks get-plan --id task-123
task-o-matic tasks execute --id task-123

# Compare plans across tasks
task-o-matic tasks get-plan --id task-authentication
task-o-matic tasks get-plan --id task-authorization

# Get plan for dependency analysis
task-o-matic tasks get-plan --id task-database-setup
task-o-matic tasks get-plan --id task-api-integration

PLAN DISPLAY FORMAT

  • Task Information: Task title, ID, and current status
  • Plan Metadata: Creation date, last modified, AI model used
  • Plan Content: Full implementation plan with structured sections
  • Related Tasks: Dependencies and connected tasks
  • Execution History: Previous executions based on this plan

ERROR CONDITIONS

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

# Plan not found
Warning: No plan found for task task-123
Solution: Create plan first with 'task-o-matic tasks plan'

# Invalid plan file
Error: Plan file corrupted or invalid format
Solution: Delete and recreate plan

LIST-PLAN COMMAND

Command: task-o-matic tasks list-plan

COMMAND SIGNATURE

task-o-matic tasks list-plan

LIST-PLAN EXAMPLES

#### Basic Plan Listing

# List all plans
task-o-matic tasks list-plan

# List plans with details
task-o-matic tasks list-plan --verbose

#### Plan Management Examples

# Review all project plans
task-o-matic tasks list-plan

# Check plan coverage
task-o-matic tasks list-plan
task-o-matic tasks list --status todo

# Identify missing plans
task-o-matic tasks list-plan
# Compare with task list to find tasks without plans

PLAN LIST OUTPUT

📋 Implementation Plans

Task ID                    | Task Title                    | Created    | Status
---------------------------|------------------------------|------------|--------
task-123                  | Build radiation detector       | 2024-01-15 | Ready
task-456                  | Set up water purification     | 2024-01-16 | In Progress
task-789                  | Install ventilation system    | 2024-01-17 | Not Started

Total: 3 plans

PLAN ANALYSIS FEATURES

  • Coverage Analysis: Identify tasks without plans
  • Status Tracking: Monitor plan execution status
  • Age Analysis: Find stale or outdated plans
  • Dependency Mapping: Visualize plan dependencies
  • Quality Metrics: Plan completeness and detail level

ERROR CONDITIONS

# No plans found
Warning: No implementation plans found
Solution: Create plans with 'task-o-matic tasks plan'

# Storage access error
Error: Failed to read plan directory
Solution: Check file permissions and disk space

# Plan corruption
Error: Some plan files are corrupted
Solution: Recreate corrupted plans

SET-PLAN COMMAND

Command: task-o-matic tasks set-plan

COMMAND SIGNATURE

task-o-matic tasks set-plan --id <id> [options]

REQUIRED OPTIONS

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

MUTUALLY EXCLUSIVE OPTIONS

--plan <text>               # Plan text (use quotes for multi-line)
--plan-file <path>           # Path to file containing plan

SET-PLAN EXAMPLES

#### Direct Plan Setting

# Set plan from command line
task-o-matic tasks set-plan \
  --id task-123 \
  --plan "## Implementation Steps\n1. Set up hardware interface\n2. Implement data processing\n3. Create alerting system"

# Set plan with multiline text
task-o-matic tasks set-plan \
  --id task-123 \
  --plan "## Step 1: Hardware Setup
- Configure Geiger counter interface
- Calibrate detection thresholds
- Test data acquisition

## Step 2: Software Implementation
- Implement signal processing algorithms
- Create data storage layer
- Build user interface"

#### File-Based Plan Setting

# Set plan from file
task-o-matic tasks set-plan \
  --id task-123 \
  --plan-file ./implementation-plan.md

# Set plan from external document
task-o-matic tasks set-plan \
  --id task-456 \
  --plan-file ./docs/shelter-construction-plan.md

# Set plan from generated document
task-o-matic tasks set-plan \
  --id task-789 \
  --plan-file ./ai-generated-plan.md

#### Template-Based Plan Setting

# Create plan file from template
cat > task-plan.md << EOF
# Implementation Plan: $(task-o-matic tasks show --id task-123 --format title)

## Overview
[Implementation approach description]

## Prerequisites
- [List required tools and libraries]
- [Environment setup requirements]

## Implementation Steps
### Step 1: [Step title]
- [Detailed instructions]
- [Code examples]
- [Testing procedures]

### Step 2: [Step title]
- [Detailed instructions]
- [Integration considerations]

## Testing Strategy
- [Unit testing approach]
- [Integration testing plan]
- [Performance requirements]

## Risk Mitigation
- [Potential challenges]
- [Alternative approaches]
- [Contingency plans]
EOF

# Set plan from template file
task-o-matic tasks set-plan \
  --id task-123 \
  --plan-file ./task-plan.md

PLAN VALIDATION

  • Task Existence: Verify task exists before setting plan
  • Content Validation: Ensure plan content is meaningful
  • Format Validation: Check for proper markdown structure
  • Size Limits: Verify plan doesn't exceed storage limits
  • Permission Check: Ensure write access to plan directory

ERROR CONDITIONS

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

# Missing plan content
Error: Either --plan or --plan-file must be specified
Solution: Provide plan content directly or via file

# Both options specified
Error: Cannot specify both --plan and --plan-file
Solution: Use either direct content or file, not both

# File not found
Error: Plan file not found: ./plan.md
Solution: Verify file path and permissions

# Invalid plan format
Error: Plan content validation failed
Solution: Ensure plan has proper structure and content

DELETE-PLAN COMMAND

Command: task-o-matic tasks delete-plan

COMMAND SIGNATURE

task-o-matic tasks delete-plan --id <id>

REQUIRED OPTIONS

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

DELETE-PLAN EXAMPLES

#### Basic Plan Deletion

# Delete plan for task
task-o-matic tasks delete-plan --id task-123

# Delete plan for subtask
task-o-matic tasks delete-plan --id task-123-456

# Delete plan for completed task
task-o-matic tasks delete-plan --id task-completed-789

#### Bulk Plan Management

# Delete plans for completed tasks
for task_id in $(task-o-matic tasks list --status completed --format id); do
  task-o-matic tasks delete-plan --id $task_id
done

# Delete outdated plans
task-o-matic tasks delete-plan --id task-old-plan-123
task-o-matic tasks delete-plan --id task-old-plan-456

# Clean up unused plans
task-o-matic tasks delete-plan --id task-abandoned-789

PLAN DELETION SAFETY

  • Confirmation Required: Shows plan details before deletion
  • Backup Suggestion: Suggests backing up important plans
  • Cascade Check: Verifies no dependent tasks need this plan
  • Recovery Warning: Warns about permanent deletion
  • Audit Trail: Maintains deletion log for recovery

ERROR CONDITIONS

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

# Plan not found
Warning: No plan found for task task-123
Solution: No action needed - plan doesn't exist

# Deletion confirmation required
Error: Use --force to confirm plan deletion
Solution: Add --force flag or use interactive confirmation

# Permission denied
Error: Cannot delete plan file: Permission denied
Solution: Check file permissions and directory access

FIELD OPERATIONS PROTOCOLS

#### PLAN LIFECYCLE MANAGEMENT

The plan commands implement a complete plan lifecycle management system:

  • Plan Creation Phase

- Task analysis and context gathering

- AI-powered plan generation

- Dependency identification

- Risk assessment and mitigation

- Plan validation and storage

  • Plan Retrieval Phase

- Plan lookup and loading

- Metadata validation and display

- Related task information integration

- Execution history tracking

  • Plan Management Phase

- Plan updates and modifications

- Version control and change tracking

- Bulk operations and batch processing

- Quality assurance and validation

  • Plan Execution Phase

- Integration with task execution workflows

- Progress tracking against plan steps

- Deviation handling and adaptation

- Completion validation and review

#### AI INTEGRATION PATTERNS

Plan operations leverage AI through standardized patterns:

  • Context-Aware Planning: Automatic inclusion of project structure and dependencies
  • Multi-Model Support: Flexible AI provider and model selection
  • Streaming Responses: Real-time plan generation for complex tasks
  • Reasoning Integration: Enhanced planning with AI reasoning capabilities
  • Documentation Enhancement: Context7 integration for relevant documentation

#### PLAN STORAGE ARCHITECTURE

Plans are stored using a structured approach:

  • Individual Files: Each plan in separate markdown file
  • Metadata Storage: Plan metadata alongside content
  • Task Integration: Direct linkage to parent tasks
  • Version Control: Plan change tracking and history
  • Backup Support: Easy backup and restore capabilities

SURVIVAL SCENARIOS

#### SCENARIO 1: Complex Infrastructure Planning

# Create comprehensive plan for shelter system
task-o-matic tasks plan \
  --id task-shelter-infrastructure \
  --stream \
  --ai-provider anthropic \
  --ai-model claude-opus-2024

# Review generated plan
task-o-matic tasks get-plan --id task-shelter-infrastructure

# Execute based on plan
task-o-matic tasks execute \
  --id task-shelter-infrastructure \
  --plan \
  --review-plan

#### SCENARIO 2: Security System Implementation

# Plan security-critical authentication
task-o-matic tasks plan \
  --id task-authentication-system \
  --ai-provider openrouter \
  --ai-model anthropic/claude-3.5-sonnet \
  --reasoning 4096

# Set custom security plan
task-o-matic tasks set-plan \
  --id task-security-audit \
  --plan-file ./security-compliance-plan.md

# Review all security plans
task-o-matic tasks list-plan | grep -i security

#### SCENARIO 3: Research and Development Tasks

# Plan R&D task with comprehensive analysis
task-o-matic tasks plan \
  --id task-radiation-research \
  --stream \
  --ai-provider openai \
  --ai-model o1-preview \
  --reasoning 8192

# Create plan from external research
task-o-matic tasks set-plan \
  --id task-research-findings \
  --plan-file ./external-research-plan.md

# Validate research plan completeness
task-o-matic tasks get-plan --id task-radiation-research

#### SCENARIO 4: Integration and Migration Planning

# Plan system integration task
task-o-matic tasks plan \
  --id task-system-integration \
  --ai-provider anthropic \
  --ai-model claude-3.5-sonnet

# Plan data migration strategy
task-o-matic tasks plan \
  --id task-data-migration \
  --stream

# Review integration dependencies
task-o-matic tasks list-plan | grep integration

#### SCENARIO 5: Emergency Response Planning

# Plan emergency system implementation
task-o-matic tasks plan \
  --id task-emergency-response \
  --ai-provider openrouter \
  --ai-model anthropic/claude-3.5-sonnet \
  --reasoning 2048

# Create contingency plans
task-o-matic tasks set-plan \
  --id task-contingency-plan \
  --plan-file ./emergency-procedures.md

# Update existing emergency plan
task-o-matic tasks set-plan \
  --id task-emergency-updates \
  --plan "## Updated Emergency Procedures\n### New Alert Levels\n### Modified Response Protocols"

TECHNICAL SPECIFICATIONS

#### PLAN DATA MODEL

interface ImplementationPlan {
  id: string;                    // Unique plan identifier
  taskId: string;               // Associated task ID
  plan: string;                  // Plan content in markdown
  createdAt: Date;               // Plan creation timestamp
  updatedAt: Date;               // Last modification timestamp
  metadata?: {                   // Plan generation metadata
    aiProvider?: string;
    aiModel?: string;
    reasoning?: boolean;
    confidence?: number;
    sources?: string[];
  };
  version?: number;               // Plan version for change tracking
  status?: 'draft' | 'ready' | 'in-progress' | 'completed';
}

#### PERFORMANCE CHARACTERISTICS

  • Plan Generation: 5-30 seconds depending on task complexity
  • Plan Retrieval: 10-50ms
  • Plan Storage: 20-100ms
  • Plan Listing: 50-200ms depending on number of plans
  • AI Processing: 2-10s for AI model inference
  • Context Gathering: 100-500ms for project analysis

#### STORAGE REQUIREMENTS

  • Plan Files: 5-50KB per plan
  • Metadata Storage: 1-2KB per plan
  • Index Overhead: 10-50KB for plan indices
  • Backup Storage: 2-100MB for plan backups
  • Cache Storage: 10-50MB for AI context cache

#### CONCURRENCY AND SAFETY

  • Atomic Operations: Safe concurrent plan access
  • File Locking: Prevents corruption during updates
  • Version Control: Track plan changes and enable rollback
  • Validation Pipeline: Ensure plan quality and completeness
  • Error Recovery: Graceful handling of AI failures

Remember: Citizen, in the unpredictable environment of post-deadline wasteland, implementation planning is your strategic advantage. These plan commands provide the intelligence and foresight needed to navigate complex technical challenges. Use them to think before you act, plan before you build, and strategize before you execute.

DOCUMENT STATUS: Complete

NEXT REVIEW: After AI model updates

CONTACT: Task-O-Matic Planning Team