Task Visualizer Skill (v2.26)

Provides ASCII and Mermaid visualization of task dependencies, following Gastown patterns for multi-agent orchestration.

Features

• ASCII dependency graphs
• Status tracking with icons
• Blocked task detection
• Parallel execution hints
• Mermaid diagram generation

ASCII Visualization Format

┌─────────────────────────────────────────────────────────────────┐
│                    TASK DEPENDENCY GRAPH                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ✓ #1 Design API architecture ──────────────────► COMPLETED    │
│            │                                                    │
│  ┌─────────┴─────────┐                                         │
│  │                   │                                         │
│  ▼                   ▼                                         │
│  ✓ #2 Create        ✓ #3 Implement                             │
│    project            data models                              │
│    structure          COMPLETED                                │
│    COMPLETED             │                                     │
│        │                 │                                     │
│        └────────┬────────┘                                     │
│                 │                                              │
│                 ▼                                              │
│  ⚙ #4 Implement REST API endpoints ────────► IN_PROGRESS      │
│        ⚠ blocked by #2, #3 (now resolved)                     │
│                 │                                              │
│  ┌──────────────┴──────────────┐                               │
│  │                             │                               │
│  ▼                             ▼                               │
│  ○ #5 Write                   ○ #6 Create API                  │
│    integration                   documentation                 │
│    tests                         PENDING                       │
│    PENDING                       ⚠ blocked by #4               │
│    ⚠ blocked by #4                                             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Status Icons

Usage

Read Tasks

# Read current tasks from .ralph/tasks.json
cat .ralph/tasks.json | jq '.tasks'

Visualize Dependencies

Generate ASCII visualization:

Task #1 Design    ─────────► RESOLVED
                      │
          ┌───────────┴───────────┐
          ▼                       ▼
Task #2 Structure          Task #3 Models
   RESOLVED                   RESOLVED
          │                       │
          └───────────┬───────────┘
                      ▼
            Task #4 Endpoints
              ⚠ blocked by #2, #3

Mermaid Generation

Generate Mermaid diagram for documentation:

flowchart TB
    T1[✓ Design API] --> T2[✓ Project Structure]
    T1 --> T3[✓ Data Models]
    T2 --> T4[⚙ REST Endpoints]
    T3 --> T4
    T4 --> T5[○ Integration Tests]
    T4 --> T6[○ API Documentation]

    style T1 fill:#90EE90
    style T2 fill:#90EE90
    style T3 fill:#90EE90
    style T4 fill:#FFD700
    style T5 fill:#D3D3D3
    style T6 fill:#D3D3D3

Parallel Execution Detection

Tasks that share the same dependencies can run in parallel:

PARALLEL EXECUTION HINT:
Tasks #5 and #6 can run in parallel after #4 completes.
Suggested agent assignment:
  - #5 (tests): Codex (gpt-5.2-codex)
  - #6 (docs): Gemini (gemini-2.5-pro)

Integration with Ralph

ralph tasks           # Show all tasks with visualization
ralph tasks --graph   # ASCII dependency graph
ralph tasks --mermaid # Mermaid diagram
ralph tasks --blocked # Show only blocked tasks
ralph tasks --parallel # Show parallelizable tasks

Task Persistence

Tasks are stored in .ralph/tasks.json and survive:

• Session restarts
• Agent failures
• Claude Code restarts

Recovery pattern:

1. Read .ralph/tasks.json
2. Find tasks with status in_progress or pending
3. Resume execution from last checkpoint

Security: Schema Validation (CWE-1286 Prevention)

MANDATORY: All task operations MUST validate against .ralph/tasks-schema.json:

Before Reading Tasks

# Validate JSON structure before parsing
if ! jq empty .ralph/tasks.json 2>/dev/null; then
  ERROR: "Invalid JSON in tasks.json - file may be corrupted"
  RECOVERY: "Backup current file and reinitialize"
fi

# Validate against schema (if ajv installed)
if command -v ajv &>/dev/null; then
  ajv validate -s .ralph/tasks-schema.json -d .ralph/tasks.json
fi

Before Writing Tasks

# Validate task content before writing
validate_task_content() {
  local content="$1"
  # Check maxLength (2000 chars)
  if [ ${#content} -gt 2000 ]; then
    ERROR: "Task content exceeds 2000 character limit"
  fi
  # Check for forbidden characters (injection prevention)
  if [[ "$content" =~ [\<\>\{\}\$\`] ]]; then
    ERROR: "Task content contains forbidden characters: < > { } $ \`"
  fi
}

Input Sanitization Rules

Safe Task Creation Example

# SAFE: Sanitized task creation
new_task:
  id: $(jq '.tasks | length + 1' .ralph/tasks.json)
  content: $(validate_task_content "$USER_INPUT")  # MUST validate
  status: "pending"  # MUST be enum value
  created_at: $(date -u +"%Y-%m-%dT%H:%M:%SZ")