template_builderpy Workspace Assembly

2.2 template_builder.py: Workspace Assembly

The template_builder.py script is the core utility responsible for generating the analytical workspace for an investigator. It assembles discrete Markdown templates into a unified document based on the current phase, step, or specific task requirements of the intelligence cycle. By integrating with template-index.json and reference-index.json, it ensures that every stage of the investigation is equipped with the correct structured frameworks (e.g., STEEPLES, Admiralty 6x6, ACH) and database registers.

Overview and Purpose

In the Claude Sleuth ecosystem, an investigation is driven by structured documentation. template_builder.py serves as the "factory" for these documents. It eliminates the manual overhead of finding and combining files by providing a CLI interface to pull together specific templates defined in the system configuration.

Key Responsibilities

• Dynamic Assembly: Combines multiple Markdown files from skills/claude-sleuth/templates/ into a single output stream or file.
• Context Awareness: Uses skills/claude-sleuth/scripts/config.py to resolve which templates belong to which phase or step.
• Reference Integration: Injects phase-specific guidance from skills/claude-sleuth/references/ to provide the AI agent with immediate context on the required tradecraft.

---

Workspace Assembly Logic

The assembly process is governed by the mapping of investigation steps to template categories (Research, Analysis, Database, and Working).

Data Flow Diagram: Template Resolution

This diagram illustrates how template_builder.py (referred to here by its CLI entry point sleuth-template) resolves user flags into file paths.

graph TD
    subgraph "CLI Input"
        A["--phase [1-6]"]
        B["--step [1-15]"]
        C["--task [e.g. t3.xb]"]
        D["--templates [list]"]
    end

    subgraph "Logic: template_builder.py"
        E{"Resolve Request"}
        F["Lookup PHASES / PHASE_FOLDERS"]
        G["Lookup STEP_TEMPLATES"]
        H["Lookup template_index.json"]
    end

    subgraph "Filesystem: skills/claude-sleuth/"
        I["templates/research/*.md"]
        J["templates/analysis/*.md"]
        K["templates/database/*.md"]
        L["templates/working/*.md"]
    end

    A --> E
    B --> E
    C --> E
    D --> E

    E --> F
    E --> G
    E --> H

    F --> I
    G --> J
    H --> K
    H --> L

    I & J & K & L --> M["Unified Workspace Document"]

Loading

---

Configuration & Indices

The builder relies on three primary data sources to locate and validate templates:

1. The Central Config (config.py)

This file contains the STEP_TEMPLATES dictionary, which is the "source of truth" for which files are required to complete a specific step in the 15-step workflow.

Step	Phase	Key Templates Assembled
1	1 (OppStrat)	research/case-decision-log.md
3	2 (IntelEpi)	research/source-grading.md
6	3 (ColEnt)	analysis/pole.md
9	4 (ChronRel)	analysis/chronological-matrix.md
12	5 (HypCog)	analysis/ach.md

2. Reference Index (reference-index.json)

Maps the six phases of the intelligence cycle to their respective folders and primary reference guidance files. This allows the builder to prepend "how-to" instructions to the generated workspace.

• Phase 1 (oppstrat): Maps to direction-foundation.md.
• Phase 4 (chronrel): Maps to process.md.

3. Tooling Inventory (tooling.md)

While not a template itself, template_builder.py can reference tooling.md to provide the investigator with a catalog of 150+ OSINT tools verified for programmatic use, such as Sherlock, Maigret, and Holehe.

---

Implementation Details

Core Functions

The script implements a sequential assembly pattern:

1. Argument Parsing: Handles --phase, --step, and --task. Note that a "Task" (e.g., t8.x) is a sub-unit of a "Step" (e.g., Step 8).
2. Path Resolution: Converts template names (e.g., analysis/pole.md) into absolute paths within the skills/claude-sleuth/templates/ directory.
3. Header Injection: For each template added to the workspace, the builder injects a Markdown header indicating the source file to maintain traceability.
4. Reference Appending: If a phase is specified, the script fetches the corresponding reference file from skills/claude-sleuth/references/ and appends it as an appendix to the workspace.

Workspace Assembly Sequence

This diagram shows the internal function flow when sleuth-template --step 8 is invoked.

sequenceDiagram
    participant CLI as "sleuth-template CLI"
    participant TB as "template_builder.py"
    participant CFG as "config.py"
    participant REF as "reference-index.json"
    participant FS as "Filesystem (Templates)"

    CLI->>TB: main(step=8)
    TB->>CFG: get STEP_TEMPLATES[8]
    CFG-->>TB: ["subject-profiles.md", "family-network-research.md", ...]
    TB->>REF: get phase for step 8
    REF-->>TB: Phase 3 (colent)
    loop for each template
        TB->>FS: read templates/database/subject-profiles.md
        FS-->>TB: content
        TB->>TB: append to workspace buffer
    end
    TB->>FS: read references/colent/resolution.md
    FS-->>TB: reference content
    TB->>TB: append as "Guidance" section
    TB-->>CLI: return final Markdown string

Loading

---

Integration with Task Runner

template_builder.py is frequently called as a subprocess by task_runner.py. When a user executes sleuth-task next, the task runner:

1. Determines the next required step from .sleuth-progress.json.
2. Calls template_builder.py to generate the workspace for that step.
3. Writes the output to the investigation-notebook.md, providing the AI with its primary working environment skills/claude-sleuth/scripts/config.py:174.

---