start

Start Task Harness Session

Initializes and starts a task harness session to execute sequential development tasks with quality gates and validation.

Overview

The start skill launches a task harness session from a YAML configuration file. It:

• Parses the YAML task definition using yq (with fallback to basic parsing)
• Validates the dependency graph for circular dependencies
• Dry-run mode: Preview tasks without creating a session (use --dry-run flag)
• Creates session state in .claude/task-harness/sessions/
• Routes to the appropriate workflow (ralph-loop, feature-todo, or plan-and-execute)
• Begins execution of the first task

If no YAML file is provided, an interactive wizard helps create one.

Prerequisites

• ralph-loop plugin - Required for iterative task execution
• jq - Required for JSON processing
• yq - Recommended for proper YAML parsing (falls back to basic parsing)
• Task YAML file - Containing harness configuration and task definitions

Instructions

Step 1: Validate Input

If $ARGUMENTS is empty, launch the /task-harness:create wizard to generate a YAML file interactively.

If a file path is provided, verify it exists:

[[ -f "$ARGUMENTS" ]] || echo "ERROR: YAML file not found"

Step 2: Initialize Session

Run the setup script to create session state:

bash ~/.claude/plugins/local-plugins/task-harness/scripts/setup-task-harness.sh "$YAML_FILE"

This validates dependencies, parses tasks, and creates the session JSON.

Step 3: Read Session State

Load the generated state file from .claude/task-harness/sessions/{session-id}.json to get:

• Session ID
• First task details (objective, constraints, hints)
• Completion promise text
• Workflow type

Step 4: Route to Workflow

Based on the task's workflow field:

Workflow Value	Routes To	Use Case
feature-todo	/feature-todo:implement	New greenfield features
plan-and-execute	/plan-and-execute	Improvements, refactoring
ralph-loop (default)	/ralph-loop	Simple tasks, direct execution

Step 5: Begin Execution

For default ralph-loop workflow:

/ralph-loop "<task-prompt>" --completion-promise "TASK_COMPLETE"

The stop hook automatically handles task transitions and quality gates.

Output

Upon successful start:

Task Harness Started
====================
Session ID: 1234567890-12345
Harness: implement-auth-feature
Tasks: 5 total

Starting Task 1: Design Authentication System
Workflow: ralph-loop
Promise: DESIGN_COMPLETE

Error Handling

Error	Cause	Resolution
YAML file not found	Invalid path	Check file path and try again
Circular dependency	Task A depends on B which depends on A	Review depends_on fields in YAML
Invalid task reference	depends_on references non-existent task	Ensure all referenced task IDs exist
yq not found	yq not installed	Install yq or use basic parsing mode

If setup fails, check .claude/task-harness/logs/ for detailed error messages.

Examples

Example 1: Start from YAML file

User: /task-harness:start tasks/auth-implementation.yaml

Skill: Parses YAML, validates dependencies, creates session, starts first task

Result:
Task Harness Started
====================
Session ID: 1736789012-54321
Harness: implement-auth-feature
Tasks: 5 total
Starting Task 1: Design Authentication System

Example 2: Start without YAML (wizard mode)

User: /task-harness:start

Skill: No file provided, launches interactive wizard

Result: Wizard asks for plan source, generates YAML, then starts execution

Example 3: Start with feature-todo workflow

# tasks/new-feature.yaml
harness:
  tasks:
    - id: "feat-001"
      workflow: "feature-todo"
      name: "Implement User Dashboard"

User: /task-harness:start tasks/new-feature.yaml

Skill: Detects feature-todo workflow, routes to /feature-todo:implement

Result: 12-stage feature implementation workflow begins

Example 4: Dry-run preview

User: /task-harness:start tasks/auth-implementation.yaml --dry-run

Skill: Parses YAML, validates, displays preview without creating session

Result:
========================================
DRY RUN - Task Harness Preview
========================================
File: tasks/auth-implementation.yaml
Harness Name: implement-auth
Total Tasks: 3
Default Workflow: ralph-loop

Tasks to Execute:
----------------------------------------
 1. [design-auth] Design Authentication System
    Workflow: ralph-loop | Phase: planning
    Depends on: none
 2. [implement-auth] Implement Authentication
    Workflow: ralph-loop | Phase: implementation
    Depends on: design-auth
 3. [test-auth] Write Auth Tests
    Workflow: ralph-loop | Phase: testing
    Depends on: implement-auth

Quality Gates Summary:
----------------------------------------
  Tasks with tests: 1
  Tasks with validation_command: 2

========================================
Validation: PASSED
Ready to execute: /task-harness:start tasks/auth-implementation.yaml
========================================

Resources

• {baseDir}/docs/yaml-schema.md - Complete YAML schema documentation
• {baseDir}/examples/feature-complete.yaml - Example 5-task workflow
• {baseDir}/scripts/setup-task-harness.sh - Session initialization script