task_runnerpy Investigation State Machine

task_runner.py: Investigation State Machine

The following files were used as context for generating this wiki page:

• .gitignore
• README.md
• skills/claude-sleuth/scripts/init.py
• skills/claude-sleuth/scripts/config.py

The task_runner.py script serves as the primary orchestrator for the Claude Sleuth investigation pipeline. It enforces a linear 56-task sequence across six distinct phases, managing state persistence, dependency injection, and phase-transition gates.

Purpose and Scope

The Task Runner is designed to provide a "hard gate" for investigative rigor. It ensures that an analyst cannot proceed to high-level reasoning (Phase 5) or reporting (Phase 6) without first completing the foundational steps of strategic planning, collection, and entity resolution README.md:50-52. It acts as a bridge between the high-level intelligence cycle and the low-level execution of Python scripts and Markdown templates.

State Management: .sleuth-progress.json

Investigation progress is persisted in a local JSON file named .sleuth-progress.json skills/claude-sleuth/scripts/task_runner.py:53-54. This file tracks the current task ID, completed tasks, and the overall state of the investigation.

State Structure

The state file maintains the following schema:

• current_task: The ID of the active task (e.g., "t1.1").
• completed_tasks: A list of all task IDs that have been finalized via the done command.
• investigation_id: A unique identifier used for CSDb (Cloudflare D1) synchronization.

Data Flow: State Persistence

The diagram below illustrates how task_runner.py interacts with the state file and the configuration metadata.

Task Runner State Flow

graph TD
    subgraph "Filesystem"
        StateFile[".sleuth-progress.json"]
        Config["config.py"]
    end

    subgraph "task_runner.py"
        LoadState["load_progress()"]
        SaveState["save_progress()"]
        CmdNext["do_next()"]
        CmdDone["do_done()"]
    end

    StateFile --> LoadState
    Config --> CmdNext
    CmdNext --> SaveState
    CmdDone --> SaveState
    SaveState --> StateFile

Loading

Sources: skills/claude-sleuth/scripts/task_runner.py:53-75, skills/claude-sleuth/scripts/config.py:1-8

Command Reference

The task_runner.py provides several CLI commands to navigate the investigation README.md:54-60.

Command	Function	Implementation
next	Displays the current task requirements, scripts, and templates.	do_next() skills/claude-sleuth/scripts/task_runner.py:186-218
done	Marks the current task as complete and advances the state.	do_done() skills/claude-sleuth/scripts/task_runner.py:220-250
status	Shows a progress overview across all 6 phases.	do_status() skills/claude-sleuth/scripts/task_runner.py:252-290
jump <id>	Moves the state to a specific task ID (e.g., t6.2).	do_jump() skills/claude-sleuth/scripts/task_runner.py:304-323
peek <id>	Views details of a future task without changing state.	do_peek() skills/claude-sleuth/scripts/task_runner.py:325-341
notebook	Opens or displays the investigation-notebook.md.	do_notebook() skills/claude-sleuth/scripts/task_runner.py:343-356
reset	Wipes the .sleuth-progress.json file to start over.	do_reset() skills/claude-sleuth/scripts/task_runner.py:358-372

Phase-Transition Gate Logic

The pipeline is divided into 6 phases skills/claude-sleuth/scripts/config.py:13-44. The task_runner.py enforces transitions between these phases by checking the current task ID against the PHASES metadata.

When a user executes done on the final task of a phase (e.g., t2.5 for Phase 1), the runner triggers a phase transition check. It validates that all required steps within that phase's folder (defined in PHASE_FOLDERS) have been addressed skills/claude-sleuth/scripts/config.py:49-56.

Automatic Dependency Installation

One of the most critical features of next is the automatic invocation of setup.py.

1. When a task is loaded, task_runner.py identifies the required scripts from STEP_SCRIPTS skills/claude-sleuth/scripts/config.py:94-110.
2. It looks up the required module groups for those scripts in SCRIPT_MODULES skills/claude-sleuth/scripts/config.py:190-192.
3. It calls scripts/setup.py --modules <names> to ensure the environment is ready before the analyst begins work skills/claude-sleuth/scripts/task_runner.py:171-184.

Code Entity Mapping

The following diagram bridges the natural language concepts of the investigation to the specific Python entities in task_runner.py and config.py.

Investigation Concept to Code Mapping

classDiagram
    class InvestigationState {
        +current_task: string
        +completed_tasks: list
        +investigation_id: uuid
    }

    class TaskRunner {
        +do_next()
        +do_done()
        +do_status()
        +check_dependencies()
    }

    class ConfigMetadata {
        +PHASES: dict
        +STEP_TEMPLATES: dict
        +STEP_SCRIPTS: dict
        +STEP_MCP_TOOLS: dict
    }

    TaskRunner --> InvestigationState : updates
    TaskRunner --> ConfigMetadata : reads
    TaskRunner --> SetupScript : calls via subprocess

Loading

Sources: skills/claude-sleuth/scripts/task_runner.py:36-51, skills/claude-sleuth/scripts/config.py:13-185

Task Execution Lifecycle

When an analyst interacts with a task, the system follows a strict lifecycle to ensure all resources (templates, scripts, and tools) are available.

Task Lifecycle Diagram

sequenceDiagram
    participant Analyst
    participant TR as task_runner.py
    participant CFG as config.py
    participant SU as setup.py
    participant TB as template_builder.py

    Analyst->>TR: next
    TR->>CFG: Get STEP_SCRIPTS & STEP_TEMPLATES
    TR->>SU: Check & Install Modules (SCRIPT_MODULES)
    TR->>TB: Assemble Workspace (STEP_TEMPLATES)
    TR-->>Analyst: Display Task Requirements & MCP Tools
    Analyst->>TR: done
    TR->>TR: Update .sleuth-progress.json
    TR-->>Analyst: Advance to Next Task

Loading

Sources: skills/claude-sleuth/scripts/task_runner.py:186-218, skills/claude-sleuth/scripts/task_runner.py:220-250, skills/claude-sleuth/scripts/config.py:73-110

---