The Task Runner CLI Tools

The Task Runner & CLI Tools

The Claude Sleuth toolkit is orchestrated by three primary CLI entry points that manage the investigation lifecycle, environment dependencies, and workspace generation. These tools ensure that the 6-phase intelligence cycle is followed with technical rigor, enforcing "hard gates" between phases and providing the analyst with the necessary scripts and templates at each step.

System Orchestration Overview

The CLI tools bridge the gap between high-level intelligence tradecraft (Natural Language Space) and the underlying Python execution environment (Code Entity Space).

CLI Command	Code Entity	Primary Responsibility
sleuth-task	scripts/task_runner.py	Manages the 56-task state machine and progress tracking.
sleuth-template	scripts/template_builder.py	Generates Markdown workspaces from the templates/ library.
sleuth-setup	scripts/setup.py	Handles modular dependency installation (e.g., geo, social).

Workflow Integration Diagram

This diagram illustrates how the CLI tools interact with the local filesystem and the investigation state to move an analyst through the intelligence cycle.

graph TD
    subgraph "Natural Language Space (Analyst Interface)"
        "Analyst_Input"["Analyst Commands (next/done/status)"]
        "Markdown_Workspace"["Investigation Notebook & Templates"]
    end

    subgraph "Code Entity Space (System Logic)"
        TR["scripts/task_runner.py"]
        TB["scripts/template_builder.py"]
        SU["scripts/setup.py"]
        CONF["scripts/config.py"]
        STATE[".sleuth-progress.json"]
    end

    "Analyst_Input" -- "Invokes" --> TR
    TR -- "Reads/Writes" --> STATE
    TR -- "References" --> CONF
    TR -- "Triggers" --> TB
    TR -- "Calls" --> SU
    TB -- "Reads" --> "templates/*.md"
    TB -- "Outputs" --> "Markdown_Workspace"
    SU -- "Installs" --> "Python_Environment"

    style TR stroke-width:2px
    style TB stroke-width:2px
    style SU stroke-width:2px

Loading

---

[2.1] task_runner.py: Investigation State Machine

The task_runner.py script is the central nervous system of the toolkit. It enforces a linear progression through 56 specific tasks across 6 phases. It prevents "phase skipping" by requiring transition conditions to be met before advancing.

• State Persistence: Progress is tracked in a local .sleuth-progress.json file.
• Command Set: Supports next (get current task), done (complete task), status (view pipeline), jump (administrative override), and notebook (view findings).
• Dynamic Resource Mapping: For every task, it queries config.py to identify which Python scripts, Markdown templates, and MCP tools are required for that specific step.

For details on the state machine logic and phase-gate enforcement, see task_runner.py: Investigation State Machine.

---

[2.2] template_builder.py: Workspace Assembly

The template_builder.py tool is responsible for constructing the analyst's working environment. Rather than forcing the analyst to manually copy files, it assembles relevant Markdown templates into a cohesive workspace based on the current investigation stage.

• Granular Assembly: Can build workspaces by --phase, --step, or individual --task.
• Template Mapping: Uses STEP_TEMPLATES in config.py to pull from the templates/ directory (e.g., analysis/pole.md or research/source-grading.md).
• Standardized Output: Ensures all generated documents follow the project's rigorous data standards (Admiralty 6x6, ACH, and ICD 203).

For details on template concatenation and the reference index, see template_builder.py: Workspace Assembly.

---

[2.3] setup.py: Dependency Module Installer

To keep the core installation lightweight, Claude Sleuth uses a modular dependency system managed by setup.py. This allows the toolkit to support heavy libraries (like playwright for evidence preservation or networkx for graph analysis) only when needed.

• Modular Groups: Dependencies are categorized into groups such as core, geo, social, corporate, and nlp.
• Automatic Invocation: The task_runner.py automatically triggers setup.py when a task requires a script with uninstalled dependencies.
• Verification: Includes a --list flag to audit installed modules and a --dry-run mode for environment testing.

For details on the dependency mapping and installation flags, see setup.py: Dependency Module Installer.

---

CLI Entry Point Mapping

The following diagram maps the CLI entry points defined in the environment to their respective script implementations and data sources.

graph LR
    subgraph "CLI Entry Points (pyproject.toml)"
        ST["sleuth-task"]
        SS["sleuth-setup"]
        SB["sleuth-template"]
    end

    subgraph "Script Implementation"
        TR_PY["scripts/task_runner.py"]
        SU_PY["scripts/setup.py"]
        TB_PY["scripts/template_builder.py"]
    end

    subgraph "Data & Configuration"
        C_PY["scripts/config.py"]
        P_JSON[".sleuth-progress.json"]
        T_DIR["templates/"]
    end

    ST --> TR_PY
    SS --> SU_PY
    SB --> TB_PY

    TR_PY --> C_PY
    TR_PY --> P_JSON
    TB_PY --> C_PY
    TB_PY --> T_DIR
    SU_PY --> C_PY

Loading

---