🔄 Workflow Engine

👤 Who it's for: Developers / integrators
⏱️ Read time: ~6 minutes
💡 In one line: Tasks have a complete lifecycle from plan to execution — every step is traceable.

YingClaw has a built-in workflow engine that ensures task execution is structured, traceable, and recoverable, preventing complex tasks from losing direction mid-way.

---

Task Lifecycle

Every task progresses through four explicit phases from creation to completion:

Status	Meaning	Trigger Condition
pending	Awaiting execution	Task just created
in_progress	Executing	Agent begins processing
completed	Done	All steps executed successfully
cancelled	Cancelled	User terminated or execution failed irrecoverably

---

Core Tools

todo — Task List

Create and manage step-by-step task plans:

{
  "merge": false,
  "todos": [
    { "id": "step-1", "content": "Analyze project structure", "status": "pending" },
    { "id": "step-2", "content": "Identify performance bottlenecks", "status": "pending" },
    { "id": "step-3", "content": "Execute optimizations", "status": "pending" },
    { "id": "step-4", "content": "Verify results", "status": "pending" }
  ]
}

Use merge: true to incrementally update existing tasks without resubmitting the full list.

delegate — Dispatch

Delegate specific steps to sub-agents:

{
  "prompt": "Analyze type safety issues in all TypeScript files under src/",
  "agents": [
    { "name": "ts-checker", "role": "TypeScript type-checking expert" }
  ]
}

assess_workload — Workload Assessment

Evaluate project scale before execution to prevent context overflow:

{}

Automatically scans file count, total size, code complexity, and other metrics.

---

Four Phases in Detail

Phase 1: Requirement Clarification

• Confirm task objectives, scope, and success criteria
• Identify potential ambiguities and constraints
• Align with the user on expected deliverables

Phase 2: Project Assessment

• Call assess_workload to scan the project
• Count files, total size, complexity
• Determine if task splitting is needed to prevent context overflow

Phase 3: Plan Confirmation

• Use todo to create a step-by-step plan
• Each step has a unique ID and clear description
• Present the plan to the user and wait for confirmation

Phase 4: Execution

• Use delegate to dispatch steps sequentially
• Auto-update todo status after each step completes
• Support parallel execution of independent steps

---

Error Handling

Situation	Strategy
Single step failure	Auto-mark as cancelled, record error cause
Partial failure	Keep completed steps, re-plan failed ones
Total failure	Suggest narrowing scope or adjusting strategy, then retry
User interruption	Mark all in-progress tasks as cancelled

---

Parallel Execution

For independent subtasks, pass an agents array for parallel execution:

{
  "prompt": "Simultaneously check frontend and backend code quality",
  "agents": [
    { "name": "frontend-checker", "role": "Check React component code" },
    { "name": "backend-checker", "role": "Check API route code" }
  ]
}

Both agents execute simultaneously; results are aggregated before returning.

---

Cost Control

Mechanism	Description
Independent context	Each sub-agent has its own context window, no interference
Iteration limits	max_iterations limits tool calls per agent
Auto-termination	Auto-terminate when limit is reached, returning existing results

---

Next Steps

Learn about YingClaw's multi-channel connectivity:

👉 Channels →