# Task Planner Architecture

This document outlines the architecture of the `task-planner` skill and its role within the broader OpenClaw skill ecosystem.

## Core Principle: Separation of Concerns

The key design principle is the **separation of planning from execution**. This contrasts with the previous `skill-orchestrator` model, which handled both.

| Component | Responsibility |
|---|---|
| **`task-planner` Skill** | **Planning**: Analyzes a complex query and generates a structured, step-by-step execution plan. It does **not** execute any steps. |
| **OpenClaw Agent** | **Execution**: Receives the plan from `task-planner` and is responsible for executing each step in sequence, managing context, and synthesizing the final result. |

This separation leads to a more robust, flexible, and token-efficient system.

## Workflow Diagram

```mermaid
sequenceDiagram
    participant User
    participant OpenClaw Agent
    participant Task Planner Skill
    participant Business Skill A
    participant Business Skill B

    User->>OpenClaw Agent: Complex query
    OpenClaw Agent->>Task Planner Skill: Call with query
    Task Planner Skill-->>OpenClaw Agent: Return JSON plan

    Note over OpenClaw Agent: Executes Step 0
    OpenClaw Agent->>Business Skill A: Call with Step 0 query
    Business Skill A-->>OpenClaw Agent: Return Step 0 output

    Note over OpenClaw Agent: Executes Step 1 (injects Step 0 output)
    OpenClaw Agent->>Business Skill B: Call with Step 1 query
    Business Skill B-->>OpenClaw Agent: Return Step 1 output

    OpenClaw Agent->>User: Synthesized final answer
```

## Advantages of this Architecture

1.  **Token Efficiency**: The full list of available skills is only processed once during the initial planning phase. Subsequent execution steps only load the context for the specific skill being called, preventing the context window from bloating with irrelevant information.

2.  **Flexibility and Control**: The OpenClaw Agent retains full control over the execution flow. It can inspect the plan, handle errors at each step, retry failed steps, or even ask the user for clarification between steps if necessary. This is not possible when the entire orchestration is a black box inside a single Python script.

3.  **Simplicity and Maintainability**: The `task-planner` script is significantly simpler than the `skill-orchestrator`. Its sole job is to produce a JSON plan. All the complexity of subprocess management, context injection, and error handling is offloaded to the agent, which is designed for these tasks.

4.  **Scalability**: As new business skills are added, the `task-planner` automatically discovers them without any code changes. The linear, step-by-step execution model managed by the agent scales well and avoids the exponential complexity of a monolithic orchestration script.

## Comparison with `skill-orchestrator`

| Feature | `skill-orchestrator` (Old) | `task-planner` (New) |
|---|---|---|
| **Execution Engine** | Internal Python `subprocess` loop | External OpenClaw Agent |
| **Context** | Managed internally; prone to bloat | Managed by Agent; efficient per-step context |
| **Error Handling** | Script-level `try-except` | Agent-level; allows for interactive recovery |
| **Flexibility** | Rigid, pre-defined flow | Adaptive; Agent can deviate from the plan |
| **Token Cost** | Higher overall due to repeated LLM calls for parameter extraction and synthesis within the script | Lower overall; one planning call, then standard agent execution calls |