Ralphban

CRITICAL:

• description is the unique identifier - must be unique across all tasks
• category, description, and steps are required fields
• status defaults to pending if omitted

3. Visualize in VS Code

Open the file in VS Code with Ralphban extension installed. The Kanban board appears in the sidebar.

Task Schema Reference

Required Fields

Optional Fields

Default Categories

frontend, backend, database, testing, documentation, infrastructure, security, functional

Custom categories can be configured in VS Code settings: ralphban.categories.

Critical Rules

Always Do

✅ Use unique description values - this is the task's ID ✅ Include at least one step in the steps array (can be empty []) ✅ Set status to in_progress when an agent starts working on a task ✅ Use dependencies array to express task ordering for agents ✅ Name files to match patterns: *.prd.json, prd.json, or tasks.json

Never Do

❌ Duplicate description values across tasks - causes lookup failures ❌ Move completed tasks back to pending (extension enforces this) ❌ Use passes: true without also setting status: "completed" ❌ Omit required fields (category, description, steps) ❌ Put task files outside workspace root without updating filePatterns

Status State Machine

pending ──────► in_progress ──────► completed
    │               │                    ▲
    │               │                    │
    └───────────────┴──► cancelled ──────┘
                              (passes: false)

Status meanings:

• pending: Not started, waiting in backlog
• in_progress: Agent is actively working on this task
• completed: Task finished successfully
• cancelled: Task abandoned or blocked

The passes field:

• null or undefined: Use status to determine completion
• true: Explicitly passed (forces completed state)
• false: Explicitly failed (forces cancelled state)

Common Patterns

Pattern 1: Feature Breakdown PRD

[
  {
    "category": "backend",
    "description": "Create user authentication API",
    "status": "pending",
    "priority": "high",
    "steps": [
      "Define auth endpoints (/login, /logout, /refresh)",
      "Implement JWT token generation",
      "Add password hashing with bcrypt",
      "Create middleware for protected routes"
    ],
    "dependencies": []
  },
  {
    "category": "frontend",
    "description": "Build login form component",
    "status": "pending",
    "priority": "high",
    "steps": [
      "Create LoginForm.tsx with email/password fields",
      "Add form validation with error states",
      "Connect to auth API endpoints",
      "Handle loading and error states"
    ],
    "dependencies": ["Create user authentication API"]
  },
  {
    "category": "testing",
    "description": "Write auth integration tests",
    "status": "pending",
    "priority": "medium",
    "steps": [
      "Test successful login flow",
      "Test invalid credentials handling",
      "Test token refresh mechanism",
      "Test logout and session cleanup"
    ],
    "dependencies": [
      "Create user authentication API",
      "Build login form component"
    ]
  }
]

When to use: Breaking down features into agent-executable tasks with clear dependencies.

Pattern 2: Agent Status Updates

When an agent picks up a task:

{
  "description": "Create user authentication API",
  "status": "in_progress"
}

When task completes:

{
  "description": "Create user authentication API",
  "status": "completed",
  "passes": true
}

When task fails:

{
  "description": "Create user authentication API",
  "status": "cancelled",
  "passes": false
}

Pattern 3: Minimal Task (Agent-Generated)

{
  "category": "functional",
  "description": "Verify checkout flow handles empty cart",
  "steps": [
    "Navigate to checkout with empty cart",
    "Verify error message appears",
    "Confirm redirect to cart page"
  ]
}

Status and other fields default appropriately for pending tasks.

File Pattern Configuration

Ralphban discovers task files via glob patterns. Default patterns:

{
  "ralphban.filePatterns": [
    "**/*.prd.json",
    "**/prd.json",
    "**/tasks.json"
  ]
}

Recommended naming conventions:

• prd.json - Main project PRD in repo root
• feature-name.prd.json - Feature-specific task files
• plans/sprint-1.prd.json - Organized by sprint/phase

Integration with LLM Agents

Bash Script Pattern (from Matt Pocock)

#!/bin/bash
# Process tasks one at a time

TASKS_FILE="prd.json"

# Get next pending task
NEXT_TASK=$(jq -r '[.[] | select(.status == "pending")][0].description' "$TASKS_FILE")

if [ -n "$NEXT_TASK" ] && [ "$NEXT_TASK" != "null" ]; then
  # Mark as in_progress
  jq --arg desc "$NEXT_TASK" \
    '(.[] | select(.description == $desc)).status = "in_progress"' \
    "$TASKS_FILE" > tmp.json && mv tmp.json "$TASKS_FILE"

  # Feed to agent
  echo "Working on: $NEXT_TASK"
  # ... agent execution here ...

  # Mark complete
  jq --arg desc "$NEXT_TASK" \
    '(.[] | select(.description == $desc)).status = "completed" |
     (.[] | select(.description == $desc)).passes = true' \
    "$TASKS_FILE" > tmp.json && mv tmp.json "$TASKS_FILE"
fi

Dependency Resolution

Before starting a task, check that all dependencies are completed:

# Check if task is ready (all deps completed)
is_ready() {
  local task_desc="$1"
  local deps=$(jq -r --arg desc "$task_desc" \
    '.[] | select(.description == $desc).dependencies // []' "$TASKS_FILE")

  for dep in $(echo "$deps" | jq -r '.[]'); do
    status=$(jq -r --arg d "$dep" \
      '.[] | select(.description == $d).status' "$TASKS_FILE")
    if [ "$status" != "completed" ]; then
      return 1
    fi
  done
  return 0
}

Known Issues Prevention

This skill prevents 3 documented issues:

Issue #1: Task Not Found on Status Update

Error: Task "..." not found Source: Tasks are matched by exact description string Why It Happens: Description was modified or has whitespace differences Prevention: Never modify description after creation; use exact match when updating

Issue #2: Invalid Schema Validation

Error: Invalid task file: missing required field Source: AJV schema validation in jsonParser.ts Why It Happens: Missing category, description, or steps field Prevention: Always include all three required fields, even if steps: []

Issue #3: Completed Tasks Revert

Error: Tasks snap back to completed column Source: Business rule in UI prevents completed → pending/in_progress Why It Happens: Attempting to move completed tasks backward Prevention: Once completed, create new task if retry needed; don't modify status backward

VS Code Configuration

{
  "ralphban.filePatterns": ["**/*.prd.json", "**/tasks.json"],
  "ralphban.categories": [
    "frontend",
    "backend",
    "database",
    "testing",
    "documentation",
    "infrastructure",
    "security",
    "functional"
  ],
  "ralphban.featureFlags.enablePercentageCounter": true,
  "ralphban.featureFlags.enableDragDrop": true,
  "ralphban.featureFlags.enableFilters": true
}

Official Documentation

• Ralphban Extension: https://github.com/carlosiborra/ralphban
• Ralph-style Task Decomposition: https://x.com/mattpocockuk/status/2008200878633931247
• Anthropic Agent Harnesses: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents

Package Versions (Verified 2025-01-31)

{
  "name": "ralphban",
  "version": "1.0.2",
  "engines": {
    "vscode": "^1.100.0"
  },
  "dependencies": {
    "ajv": "^8.17.1",
    "minimatch": "^10.1.1"
  }
}

Complete Task Template

Copy this template for new task files:

[
  {
    "category": "functional",
    "description": "Task description here",
    "status": "pending",
    "priority": "medium",
    "steps": [
      "First step",
      "Second step",
      "Third step"
    ],
    "dependencies": [],
    "passes": null
  }
]

Troubleshooting

Problem: Tasks not appearing in Kanban

Solution: Verify file matches ralphban.filePatterns glob. Check Output → Ralphban for errors.

Problem: Drag and drop not working

Solution: Check ralphban.featureFlags.enableDragDrop is true. Completed tasks cannot move backward.

Problem: Schema validation errors

Solution: Ensure valid JSON array, each task has category, description, steps. Use VS Code's JSON validation.

Problem: Dependencies not visualized

Solution: Dependencies reference other tasks by exact description string. Typos break the link.

Complete Setup Checklist

• Task file uses valid JSON array format
• Each task has category, description, steps fields
• All description values are unique
• File matches ralphban.filePatterns glob
• Dependencies reference existing task descriptions exactly
• VS Code has Ralphban extension installed (for visualization)