Task Harness

Task Harness Plugin

A Claude Code plugin that enables continuous development by executing a defined list of tasks sequentially with intelligent linkage between task completions.

Key Feature: Dynamic Planning

Unlike traditional task runners where you specify exactly HOW to do each task, Task Harness uses dynamic planning:

• You define WHAT (objectives, constraints, success criteria)
• Claude plans HOW at runtime, in isolation for each task
• Context flows forward - previous work is available if needed

This allows Claude to adapt its approach based on actual outcomes rather than following rigid scripts.

Overview

Task Harness layers on top of the ralph-loop plugin to provide:

• Sequential Task Execution: Execute multiple development tasks in order
• Parallel Task Groups: Execute related tasks concurrently
• Intelligent Linkage: Automatic transition from completed tasks to next tasks
• Validation Support: External validation commands to verify task completion
• Retry Logic: Automatic retries with exponential backoff on failures
• Context Passing: Share outputs and state between tasks
• Session Management: Track progress, cancel, and resume sessions
• Serena MCP Integration: LSP-based code discovery before task execution
• Plugin Suggestions: Contextual plugin recommendations per task

Architecture

User runs: /task-harness start tasks.yaml
    │
    ▼
Task harness loads YAML → creates state file → builds Task 1 prompt
    │
    ▼
Delegates to: /ralph-loop "<task-1-prompt>" --completion-promise "TASK_COMPLETE"
    │
    ▼
Ralph-loop iterates → Claude works on Task 1
    │
    ▼
Claude outputs: <promise>TASK_COMPLETE</promise>
    │
    ▼
Task harness stop hook detects completion:
  - Runs validation (if configured)
  - If pass: marks task complete, builds Task 2 prompt
  - Updates ralph-loop state with new prompt
    │
    ▼
Ralph-loop continues iterating → Claude works on Task 2
    │
    ▼
Repeat until all tasks complete or failure
    │
    ▼
Final task completes → harness allows ralph-loop to exit

Installation

Install to your local plugins directory:

# Plugin location
~/.claude/plugins/local-plugins/task-harness/

Requirements:

1. ralph-loop plugin is installed and working
2. jq is available (for JSON processing)
3. yq is recommended (for YAML parsing, falls back to basic parsing)

Install yq via: scoop install yq or choco install yq or brew install yq

Quick Start

1. Create a task list YAML file

harness:
  metadata:
    name: "my-feature"
    description: "Implement a new feature"

  global_config:
    max_iterations_per_task: 20
    retry_policy:
      max_retries: 2

  tasks:
    # Define WHAT, not HOW - Claude plans each task
    - id: "plan"
      name: "Plan the Feature"

      objective: |
        Create a design document for the feature covering
        architecture, data models, and implementation approach.

      constraints:
        must_use: ["existing patterns in codebase"]
        scope: "Design only - do not implement"

      success_criteria:
        required_files:
          - "docs/feature-design.md"

      completion_detection:
        method: "promise"
        promise_text: "DESIGN_COMPLETE"

    - id: "implement"
      name: "Implement the Feature"
      depends_on: ["plan"]

      objective: |
        Implement the feature based on the design from the
        previous task. Follow the architecture decisions made.

      constraints:
        must_use: ["TypeScript", "existing service patterns"]

      hints:
        relevant_files:
          - "src/services/*.ts"

      success_criteria:
        required_files:
          - "src/features/my-feature.ts"
        validation_command: "npm test -- --testPathPattern=feature"

      completion_detection:
        method: "hybrid"
        promise_text: "IMPLEMENT_COMPLETE"
        validation_command: "npm test -- --testPathPattern=feature"

2. Start the task harness

/task-harness start tasks/my-feature.yaml

3. Monitor progress

/task-harness status

4. Cancel if needed

/cancel-harness

Commands

/task-harness start <yaml-file>

Start a new task harness session.

Arguments:

• yaml-file - Path to YAML task list (required)
• --session-id - Custom session ID (optional)
• --max-iterations - Max iterations per task (default: 50)

Example:

/task-harness start tasks/my-feature.yaml

/task-harness status [session-id]

Check status of active or recent sessions.

Output includes:

• Session progress (X/Y tasks)
• Current task name and status
• Retry and iteration counts
• Last validation result

/cancel-harness [session-id]

Cancel an active session.

Behavior:

• Lists active sessions if no ID provided
• Preserves progress for later resume
• Delegates to /cancel-ralph to stop iteration

/task-harness resume <session-id>

Resume a cancelled, failed, or blocked session.

Arguments:

• session-id - Session to resume (required)
• --from-task N - Override resume point to task N (optional)

Behavior:

• Validates session is resumable (cancelled/failed/blocked)
• Finds resume point (last incomplete task)
• Resets session status to "running"
• Restarts ralph-loop with task prompt

Example:

# Resume from where it stopped
/task-harness resume 1234567890-12345

# Resume from specific task
/task-harness resume 1234567890-12345 --from-task 3

Task Definition Schema

See docs/yaml-schema.md for the complete schema.

Key Fields

Field	Description
id	Unique task identifier
name	Human-readable task name
prompt	Instructions for Claude
phase	Logical grouping (planning, implementation, testing, etc.)
depends_on	Array of task IDs that must complete first
completion_detection	How to detect task completion
success_criteria	Additional validation requirements
max_iterations	Per-task iteration limit

Completion Detection Methods

1. Promise (default): Look for <promise>TEXT</promise> in output
2. External Validation: Run a command and check exit code
3. Hybrid: Both promise AND validation required

Example with Validation

- id: "write-tests"
  name: "Write Tests"
  prompt: |
    Write tests for the authentication module.
    When tests pass, output: <promise>TASK_COMPLETE</promise>
  completion_detection:
    method: "external_validation"
    validation_command: "npm test -- --testPathPattern=auth"
  success_criteria:
    required_files:
      - "tests/auth.test.js"
    tests_must_pass:
      command: "npm test -- --testPathPattern=auth"

State Management

Session State Location

.claude/task-harness/
├── sessions/           # Active session state
│   └── {session-id}.json
├── logs/              # Execution logs
│   └── {session-id}.log
├── validation/        # Validation results
│   └── task-{index}-{timestamp}.json
├── checkpoints/       # Rollback points
│   └── {session-id}-{task-id}.json
└── archive/           # Archived sessions

State File Structure

{
  "version": "2.2",
  "schema": "dynamic-planning-parallel-serena",
  "sessionId": "1234567890-12345",
  "harnessName": "implement-auth-feature",
  "status": "running",
  "currentTaskIndex": 1,
  "totalTasks": 5,
  "parallelGroups": {
    "research": {
      "status": "completed",
      "taskIds": ["research-api", "research-models"],
      "completedTasks": ["research-api", "research-models"],
      "failedTasks": []
    }
  },
  "serena": {
    "enabled": true,
    "project_name": "root"
  },
  "tasks": [
    {
      "id": "plan-auth",
      "name": "Plan Authentication Feature",
      "status": "complete",
      "retryCount": 0,
      "iteration": 12,
      "use_serena": true,
      "serena_search": {
        "find_symbols": ["AuthService"],
        "search_patterns": []
      }
    },
    {
      "id": "implement-user-model",
      "name": "Implement User Model",
      "status": "in_progress",
      "retryCount": 0,
      "iteration": 5
    }
  ]
}

Error Handling

Retry Policy

When a task fails validation:

1. Increment retry counter
2. Calculate backoff delay (exponential with jitter)
3. Re-inject task prompt with failure context
4. Continue iteration

After max retries (default: 2):

• Halt the harness
• Mark session as "failed"
• Preserve state for debugging

BLOCKED State

If Claude cannot proceed, it can output:

<promise>BLOCKED</promise>

This immediately halts the harness and notifies the user.

Parallel Task Groups

Execute multiple tasks concurrently using parallel groups. Tasks in the same group run simultaneously using Claude's Task tool with background execution.

Defining Parallel Groups

tasks:
  - id: "research-api"
    name: "Research API Patterns"
    parallel_group: "research"
    parallel_priority: 1
    objective: "Research existing API patterns in the codebase"

  - id: "research-models"
    name: "Research Data Models"
    parallel_group: "research"
    parallel_priority: 2
    objective: "Research existing data models"

  - id: "implement"
    name: "Implement Feature"
    depends_on: ["research-api", "research-models"]
    objective: "Implement feature using patterns discovered"

Key Fields

Field	Description
parallel_group	Group name - tasks with same group run concurrently
parallel_priority	Error reporting order (1 = first)

Global Configuration

global_config:
  parallel_config:
    continue_on_failure: true    # Continue if some parallel tasks fail
    fail_fast: false             # Stop group on first failure
    max_parallel_tasks: 5        # Limit concurrent tasks

Execution Flow

1. Sequential tasks before group execute normally
2. When parallel group starts, all tasks launch concurrently
3. Each task works independently
4. Group completes when ALL tasks finish
5. Next sequential task begins

Serena MCP Integration

Use Serena's LSP-based code intelligence for pre-task codebase exploration. This helps Claude understand existing patterns before implementing.

Enabling Serena Search

tasks:
  - id: "implement-service"
    name: "Implement Service"
    use_serena: true
    serena_search:
      find_symbols: ["BaseService", "UserModel"]
      search_patterns: ["class.*extends.*Service"]
      explore_paths: ["src/services", "src/models"]
      inject_context: true
      max_results: 10

Serena Search Options

Field	Description
find_symbols	Symbol names to locate via LSP
search_patterns	Regex patterns to search
explore_paths	Directories to get symbol overviews
inject_context	Include results in prompt (default: true)
max_results	Limit results per search (default: 10)

Global Serena Configuration

global_config:
  serena:
    enabled: true
    project_name: "root"
    fallback_to_grep: true       # Use Grep/Glob if Serena unavailable
    max_context_chars: 5000      # Limit context size

Anti-Duplication Protocol

Serena integration enforces the SEARCH BEFORE CREATE principle:

1. Search for existing implementations before creating new code
2. If exact match found → Use existing
3. If similar found → Extend existing
4. If base class found → Inherit from it
5. If nothing found → Create new following patterns

Fallback Commands

When Serena is unavailable, the harness generates equivalent Grep/Glob commands.

Plugin Suggestions

Task Harness can suggest relevant plugins based on task phase and objective keywords.

Automatic Suggestions

Suggestions are enabled by default and based on:

1. Task Phase: testing → run-tests, security → security-scan
2. Objective Keywords: "database" → db-migrate, "api" → api-documentation-generator

Configuration

tasks:
  - id: "write-tests"
    phase: "testing"
    auto_suggest_plugins: true   # Enable auto-suggestions (default)
    suggested_plugins:           # Explicit suggestions
      - "run-tests"
      - "test-automator"

Phase-to-Plugin Mapping

Phase	Suggested Plugins
planning	task-router, plan-and-execute
implementation	code-review-ai, lint-check
testing	run-tests, test-automator
documentation	api-documentation-generator
security	security-scan, api-security-scanner
database	db-migrate, database-schema-designer
deployment	ci-cd-pipeline-builder, docker-compose-generator

Keyword Detection

Plugins are also suggested based on objective keywords:

• test, spec, jest → run-tests
• security, auth → security-scan
• database, migration → db-migrate
• api, endpoint → api-documentation-generator
• deploy, docker → ci-cd-pipeline-builder
• review, refactor → code-review-ai

Suggestions are informational only - Claude decides if/when to use them.

Integration with Ralph-Loop

Task Harness does NOT replace ralph-loop. Instead:

1. Ralph-loop handles: Iteration, stop hook interception, session management
2. Task harness adds: Task sequencing, validation, context passing

State Coordination

• Ralph-loop state: .claude/ralph-loops/{session-id}.md
• Task harness state: .claude/task-harness/sessions/{session-id}.json

The stop hook reads both and coordinates task transitions.

Scripts

Located in the plugin's scripts/ directory:

setup-task-harness.sh

Initialize a session from YAML:

$PLUGIN_DIR/scripts/setup-task-harness.sh tasks.yaml [session-id]

validate-task.sh

Run validation for a specific task:

$PLUGIN_DIR/scripts/validate-task.sh <session-id> <task-index>

cleanup-harness.sh

Archive or delete session files:

$PLUGIN_DIR/scripts/cleanup-harness.sh <session-id> [--archive|--delete]

serena-search.sh

Generate Serena MCP search commands for pre-task discovery:

$PLUGIN_DIR/scripts/serena-search.sh <session-id> <task-index>

parallel-executor.sh

Generate prompts for parallel task group execution:

$PLUGIN_DIR/scripts/parallel-executor.sh <session-id> <group-name>

suggest-plugins.sh

Generate plugin suggestions based on task phase and keywords:

$PLUGIN_DIR/scripts/suggest-plugins.sh <session-id> <task-index>

Examples

See the examples/ directory in the plugin for sample task lists:

• feature-complete.yaml - Full feature implementation workflow (5-task auth feature)
• parallel-research.yaml - Parallel task group example with research phase

Troubleshooting

Task not advancing

1. Check if completion promise is in output
2. Verify validation command exits with 0
3. Check .claude/task-harness/logs/{session-id}.log

Validation failing

1. Run validation manually via the plugin's script
2. Check validation result in .claude/task-harness/validation/

Session stuck

1. Check status: /task-harness status
2. Cancel and restart: /cancel-harness <session-id>
3. Review logs for errors

Dependencies

• ralph-loop plugin: Required for iteration mechanism
• jq: Required for JSON processing
• yq: Optional but recommended for YAML parsing

License

MIT