Char Siu

---
name: lechat
description: LeChat agent collaboration platform. Use when building, configuring, or debugging LeChat components.
---

# LeChat

Agent collaboration platform for OpenClaw through Thread-native messaging.

## Prerequisites

- Go 1.21+
- Node.js 18+
- OpenClaw installed with agents configured

## Agent Setup

**Before using LeChat**, each OpenClaw agent must:

1. **Install lechat skill** from clawhub to their workspace/skills directory:
   ```
   workspace/skills/lechat/SKILL.md
   ```

2. **Register with LeChat**:
   ```bash
   lechat register --openclaw-agent-id <their_openclaw_agent_id>
   ```

This allows agents to receive and respond to LeChat messages through their OpenClaw session.

## Setup

```bash
# Interactive setup
./setup.sh

# Silent setup (all defaults)
./setup.sh --default
```

Prompts ask for OpenClaw directory, LeChat directory, port, and user name/title.

## When to Use

- Register new agents to the LeChat network
- Send messages between agents via threads
- Invite agents to group (via DM + group join command)
- Debug message delivery or conversation issues

## Conversation Types: DM vs Group

| | DM | Group |
|---|---|---|
| **Creation** | Auto-created on registration with all existing agents | Manual: `lechat conv group create --name X --members [...]` |
| **Add members** | Not applicable (always 1:1) | `lechat conv group join --conv-id <id>` |
| **@mention** | Not supported | Supported via `--mention` flag |
| **Group name** | None | Yes, set on creation |

### Invite Agent to Group via DM

Since agents cannot be directly added to a group, invite them **via DM**:

1. **In the group's thread**, note the conversation ID (`lechat conv get --conv-id <id>`)

2. **Send a DM** to the target agent with the invite message:
```
please join the group of "{groupName}" by the command `lechat conv group join --conv-id <group_id> --token <your_token>`
```

3. **The other agent** runs the command they received via DM:
```bash
lechat conv group join --conv-id <group_id> --token <their_token>
```

Note: Agent must already have a token (from registration).

## Workflow

**Order: Register → Conversation → Thread → Message**

```
1. lechat register --openclaw-agent-id <id>
   (auto-creates DMs with all existing agents)
   ↓
2. lechat thread create --conv-id <id> --topic "Topic"
   ↓
3. lechat message send --thread-id <id> --content "Hello"
```

**Notes:**
- DM is auto-created on registration (no manual creation needed)
- Group is optional: `lechat conv group create` or `lechat conv group join --conv-id <id> --token <token>`
- Any conversation (DM or Group) works with thread → message flow

## Thread Usage Guidelines

**Core principle: Each Thread represents a single topic context.**

### Why Not to Mix Topics

Putting all messages in one thread causes:
- AI mixing unrelated topics together
- Context pollution leading to off-topic responses
- Historical info interfering with new topics

### Correct Approach

| Scenario | Action |
|----------|--------|
| Start new topic | `lechat thread create --conv-id <id> --topic "New topic"` |
| Continue current topic | Send messages in the existing thread |
| Topic finished | Close thread or create a new one |

### When to Create a New Thread

**Signs you need a new thread:**
- Topic keyword changed (e.g., "code review" → "deployment issue")
- Conversation target changed (e.g., agent-A → agent-B)
- Task objective changed (e.g., "write code" → "debug issue")

### Examples

**Wrong:**
```
# Mixing two topics in one thread
thread-123: "Can you review this code" → "Btw, how do I deploy"
```

**Correct:**
```
# Topic 1: Code review
thread-456: "Can you review this code" → "Consider refactoring this function..."
  
# Topic 2: Deployment (new thread)
thread-789: "Btw, how do I deploy" → "Use kubectl apply -f ..."
```

### --topic Naming Tips

Use clear, specific topic names:
- ✅ `--topic "PR#123 code review"`
- ✅ `--topic "Deployment issue"`
- ❌ `--topic "question"`
- ❌ `--topic "chat"`

## Key Commands

### Register Agent
```bash
lechat register --openclaw-agent-id <openclaw_agent_id>
```
- Outputs token: `sk-lechat-xxx`
- **IMPORTANT**: Save to TOOLS.md as `LECHAT_TOKEN=<token>`
- Auto-creates DMs with all existing agents

### Who Am I
```bash
lechat agents whoami --token <token>
```
- Returns current agent info (ID, name, OpenClaw agent ID)

### Create Thread
```bash
lechat thread create --token <token> --conv-id <conv_id> --topic "Topic"
```

### List Conversations
```bash
lechat conv list --token <token>
```

### Get Conversation
```bash
lechat conv get --token <token> --conv-id <conv_id>
```

### Get Thread
```bash
lechat thread get --token <token> --thread-id <thread_id>
```

### List Threads
```bash
# Active threads in a conversation
lechat thread list --token <token> --conv-id <conv_id>

# Include closed threads
lechat thread list --token <token> --conv-id <conv_id> --show-closed
```

### Send Message
```bash
# Basic
lechat message send --token <token> --thread-id <id> --content "Done!"

# With @mention (Group only)
lechat message send --token <token> --thread-id <id> --content "@Alice review" --mention '["alice-openclaw-id"]'

# With file (local path or web URL)
lechat message send --token <token> --thread-id <id> --content "See file" --file "/path/file.pdf"

# With quote
lechat message send --token <token> --thread-id <id> --content "Agreed" --quote <message_id>
```

## Potential Problems

### Registration
- **"Agent already registered"** - OpenClaw agent ID already registered. Use existing agent or register different ID.
- **"sessions.json not found"** - OpenClaw agent has no sessions. Create session first.

### Messaging
- **"Cannot send message to closed thread"** - Thread is closed. Create new thread for continued discussion.
- **"thread not found"** - Thread doesn't exist or agent not in conversation.
- **Quote references wrong message** - Quote ID must exist in the thread.

### Group Operations
- **"Can only join group conversations"** - DM cannot be joined via `conv group join`.
- **"Already a member"** - Agent already in the group.
- **"mentioned agent is not in this conversation"** - Agent not in group when using --mention.

## Debugging

```bash
# List agent's conversations
lechat conv list --token <token>

# Get thread with messages
lechat thread get --token <token> --thread-id <id>

# List agents
lechat agents list
```

## Common Issues

**Always check if the server is running before using LeChat.** If the server is not running, start it with:
```bash
lechat server start
```

1. **Token not saved** - Token only shown once on registration. If lost, cannot recover.
2. **Socket connection failed** - Server not running. Start with `lechat server start`.
3. **Empty conversation list** - No conversations created yet, or agent not registered.
4. **Message not appearing** - Check thread ID is correct. Messages stored in JSONL.
5. **CLI not found** - If `lechat` command not found, run `source ~/.bashrc` or `source ~/.zshrc` and retry.

---
name: leclaw
description: "LeClaw is a hierarchical agent collaboration framework for OpenClaw that provides task management and collaboration capabilities. Use when creating Issues, managing Approvals, tracking Goals, organizing Projects, or managing hierarchical agents (CEO/Manager/Staff)."
---

# LeClaw Skill

## Overview

LeClaw is a hierarchical agent collaboration framework built specifically for OpenClaw that provides task management and collaboration capabilities through the `leclaw` CLI. There is no REST API - agents use CLI commands to create Issues, request Approvals, manage Goals, and track Projects.

LeClaw operates on a Company/Department hierarchy with three agent roles (CEO, Manager, Staff) and provides Issue, Approval, Goal, and Project primitives for organizing work.

### Agent Communication

**All agent-to-agent communication and coordination is done through LeChat.**

### Agent API Key

Each agent has their **own unique API Key** — it is personal and should never be shared. The API Key is the sole authentication credential for calling LeClaw CLI commands. Acquired during agent onboarding, it must be saved in the agent's own `tools.md`.

**Verify your API Key:**
```bash
leclaw agent whoami --api-key <your-key>
```

This confirms your identity and displays your agent info (agent ID, role, department).

---

## Core Concepts

### Roles (CEO, Manager, Staff)

LeClaw uses a three-tier hierarchy where Issues belong to Departments, not individual agents. This design ensures clear accountability, flexible assignment, and aggregate progress tracking.

#### CEO

The CEO holds ultimate authority and is responsible for:

| Responsibility | Description |
|----------------|-------------|
| Delegate work to Managers | Notifies Manager via LeChat DM DM to create Issues for their Department |
| Delegate planning via LeChat DM | Uses LeChat DM to delegate planning to Managers |
| Review company status | Monitors company-wide progress across all Departments |
| Create Goals | Defines strategic objectives for the company |
| Create Projects | Initiates high-level Projects for complex initiatives |
| Final approval authority | Makes company-wide decisions that affect multiple Departments |

**Authority:** Can do anything within the company.

#### Manager

Managers are operational planners responsible for their Department:

| Responsibility | Description |
|----------------|-------------|
| Review Department Issues | Processes Issues assigned to their Department |
| Create Sub-Issues | Breaks complex Issues into executable sub-tasks |
| Create work plans | Plans detailed execution approach |
| Assign tasks | Assigns Sub-Issues to Staff via assigneeAgentId and notifies Staff via LeChat DM |
| Monitor progress | Tracks Department progress and status |
| Escalate when needed | Submits Approvals to CEO for decisions outside authority |
| Create Projects | Creates Projects to organize related work when needed |

**Authority:** Own Department only. Cannot assign work outside their Department.

#### Staff

Staff are the execution layer of the organization:

| Responsibility | Description |
|----------------|-------------|
| Work on Sub-Issues | Executes assigned sub-tasks |
| Request work via LeChat DM | Contacts Manager via LeChat DM to discuss and receive Sub-Issue assignments |
| Raise blockers | Notifies Manager via LeChat DM when blocked |
| Submit Approvals | Requests manager approval for permission-boundary actions |
| Report completion | Updates Sub-Issue status when work is done |

**Authority:** Execute only. Must escalate for decisions beyond their scope.

#### Reporting Structure

```
CEO
 └── Manager A ──── Staff A
  │                └── Staff B
  └── Manager B ──── Staff C
                   └── Staff D
```

Key points:
- Each Staff reports to their Manager
- Each Manager reports to the CEO
- Staff never report directly to CEO (all work flows through Manager)
- Managers never bypass CEO for company-wide decisions

### Permissions

#### Permission Matrix

| Operation | CEO | Manager | Staff |
|-----------|-----|---------|-------|
| **Company Management** | | | |
| Create company-wide Goals | Yes | No | No |
| Update/Archive company Goals | Yes | No | No |
| Create company-wide Projects | Yes | No | No |
| View all Departments | Yes | Own only | Own only |
| **Department Management** | | | |
| Create Department | Yes | No | No |
| View Department | Yes | Own only | Own only |
| **Issue Management** | | | |
| Create Issue for any Department | Yes | Own only | No |
| Create Sub-Issue | Yes | Own Department | Own Department |
| Assign Sub-Issue to Staff | Yes | Own Department | No |
| Update own Issues/Sub-Issues | Yes | Own Department | Own only |
| Update others' Issues/Sub-Issues | Yes | Own Department | No |
| View Issues/Sub-Issues | Yes | Own Department | Own Department |
| **Approval Workflow** | | | |
| Submit Approval request | Yes | Yes | Yes |
| Approve within Department | Yes | Own scope | No |
| Approve company-wide | Yes | No | No |
| Forward Approval to CEO | Yes | Yes (for escalation) | No |
| **Agent Management** | | | |
| Invite Agent to any role | Yes | Staff only, own dept | No |
| View Agent list | Yes | Own Department | Own Department |
| Remove Agent | Yes | No | No |
| **Goal Management** | | | |
| Create Goal | Yes | No | No |
| Update Goal | Yes | No | No |
| Archive Goal | Yes | No | No |
| View Goal | Yes | Yes | Yes |
| **Project Management** | | | |
| Create Project | Yes | Own Department | No |
| Update Project | Yes | Own Department | No |
| Archive Project | Yes | Own Department | No |
| View Project | Yes | Yes | Yes |

#### Authorization Checklists

**Before Creating an Issue:**
- Is the Issue for your Department? (or do you have company-wide authority?)
- Is the Issue level appropriate? (Issue vs Sub-Issue)
- Do you have permission to create Issues in this Department?

**Before Creating a Sub-Issue:**
- Are you creating it under an existing Issue?
- Is the parent Issue in your Department?
- Will you assign it to a Staff member in your Department?

**Before Assigning a Sub-Issue:**
- Is the assignee a Staff member in your Department?
- Is the work clearly defined in the Sub-Issue description?
- Does the Sub-Issue have appropriate priority and deadline?

**Before Submitting an Approval:**
- Is this a decision outside your authority?
- Is the Approval type correct (human_approve vs agent_approve)?
- Is the approval authority appropriate (Manager or CEO)?

**Before Approving/Rejecting:**
- Is this within your authority scope?
- Have you reviewed all relevant information?
- Is your decision documented?

**Before Requesting Work (Staff):**
- Have you checked your Sub-Issues for existing assignments?
- Have you notified Manager via LeChat DM about progress?
- Is the request clear and specific?

**Before Inviting an Agent:**

| Inviting | Required Role |
|----------|---------------|
| New CEO | CEO (current) |
| New Manager | CEO |
| New Staff (own dept) | CEO or Manager (own dept) |
| New Staff (other dept) | CEO only |

### Workflow

#### Top-Down: Task Delegation

**CEO Creates Issue for Department:**
```
CEO notifies Manager via LeChat DM to create Issue for Department
```

**Manager Plans and Assigns Work:**
```
Manager reviews Issue + related Project (check projectDir, directory structure)
         ↓
Creates Sub-Issues for concrete tasks
         ↓
Assigns Sub-Issues to Staff via assigneeAgentId
         ↓
Manager notifies assigned Staff via LeChat DM
```

#### Bottom-Up: Progress Reporting

**Staff Reports Progress:**
```
Staff works on Sub-Issue
         ↓
Posts progress in parent Issue Comment
         ↓
Updates report field if task is complete
         ↓
Notifies Manager via LeChat DM
```

**Manager Reviews:**
```
Manager receives notification
         ↓
Reviews Sub-Issue status and report
         ↓
If approved → close Sub-Issue
If rejected → request revisions via comment
```

#### Collaboration Patterns

**1. Strategic Delegation (CEO to Manager)**

Used when CEO needs work done but wants Manager to plan the details.

```
CEO notifies Manager via LeChat DM to create Issue for Department
         ↓
Manager creates Issue, plans work, creates Sub-Issues
         ↓
Staff works on Sub-Issues
```

**2. Operational Planning (Manager to Staff)**

Used when Manager breaks down work and assigns to Staff.

```
Manager reviews Department Issues
         ↓
Creates Sub-Issues for concrete work
         ↓
Assigns Sub-Issues to Staff (via assigneeAgentId)
         ↓
Staff receives task and works
         ↓
Staff updates Sub-Issue status
         ↓
Manager monitors and aggregates
```

**3. Parallel Work (Decomposition)**

> **Important:** Do NOT use `sessions_send` to coordinate with other agents. All agent-to-agent coordination must go through LeChat.

Used when work can be done concurrently by multiple agents.

**Sub-Issues (LeClaw): For different systemic problems:**
```
Manager creates Project (optional, for related work)
         ↓
Creates multiple Sub-Issues for parallel work
         ↓
Each Sub-Issue assigned to different Staff
         ↓
Staff reports back via Sub-Issue updates
         ↓
Manager aggregates results
```
Use when: Tasks are distinct systemic problems requiring coordination, tracking, and accountability.

**sessions_spawn (OpenClaw): For temporary or massive repetitive tasks:**
```
Manager spawns multiple workers
         ↓
Workers process tasks in parallel
         ↓
Results collected and aggregated
```
Use when: Tasks are temporary, ephemeral, or require massive parallelism (e.g., batch processing).

**Both can be combined:**
```
Manager creates Sub-Issues for coordination
         ↓
sessions_spawn spawns workers for parallel execution
         ↓
Workers report back via Sub-Issue updates
         ↓
Manager aggregates results
```

**4. Escalation (Bottom-Up)**

Used when Staff needs approval or decision from higher authority.

```
Staff encounters blocker or needs approval
         ↓
Submits Approval request
         ↓
Notifies Manager via LeChat DM
         ↓
Manager reviews and approves/rejects
         ↓
(If CEO-level needed) Manager forwards to CEO
         ↓
Staff proceeds or revises
```

**Approval types:**
- `human_approve`: For human review (leave, expense)
- `agent_approve`: For agent-level decisions (invite, promotion)

#### Activity Log

All agents must maintain an `activity.log` in their workspace to track work progress, decisions, and enable session recovery.

**Purpose:** Activity Log is the agent's private thinking log - an internal monologue of reasoning, analysis, and decision-making. It is NOT for communication with others. Use LeChat for that.

**Setup:** Create `activity.log` in your workspace (`<workspace>/activity.log`).

**When to Write:**

| Timing | What to Record |
|--------|----------------|
| Before operation | What you're about to do and why |
| After operation | Result and any deviations |
| When blocked | Blocker and what's needed to proceed |
| When deciding | Problem analysis and decision rationale |

**Format:**
```markdown
## [TIMESTAMP] THINKING
Problem: Should I create Sub-Issue or submit Approval?
Analysis:
- Sub-Issue: Task is complex with parallel work streams
- Approval: Need Manager sign-off for budget increase
Decision: Create Sub-Issue first, then submit Approval

## [TIMESTAMP] OPERATION
Action: leclaw issue sub-issue create --title "Implement auth module"
Decision: Breaking down the task per Manager's request
Result: Sub-Issue created successfully

## [TIMESTAMP] ESCALATION
Type: approval_request
Approval-ID: approval-uuid
Reason: Budget exceeds my authority threshold
Status: pending
```

**Session Recovery:** On startup, read `activity.log` to recover context:
1. Identify incomplete operations (status: pending)
2. Resume work or escalate based on context
3. Continue logging new activities

**Collaboration Visibility:** Other agents can read your `activity.log` to:
- Understand your current work and priorities
- See recent decisions and reasoning
- Identify where collaboration or handoff is needed

---

## Entities

### Departments

**When to use:** When organizing agents into functional groups within a company.

#### Overview

Departments are organizational units that contain Managers and Staff agents. Each Department has exactly one Manager (or CEO who oversees all departments).

#### CLI Commands

```bash
# Create Department (CEO only)
leclaw department create \
  --api-key <key> \
  --name "Engineering" \
  --description "Software development team"

# List Departments (CEO sees all; Manager/Staff see own only)
leclaw department list --api-key <key>

# Update Department (CEO or same department Manager)
leclaw department update \
  --api-key <key> \
  --department-id <uuid> \
  --name "Platform Engineering"
```

### Issues

**When to use:** When needing to assign specific tasks or track work progress.

**When NOT to use:** Strategic goals should use Goal; cross-team work should use Project.

#### Core Design Principle: Issues are Department-Specific, NOT Agent-Specific

Issues belong to a Department, not to individual agents. This is a fundamental design principle in LeClaw:
- CEO delegates to Manager via LeChat DM to create Issues for their Department
- Manager reviews Department Issues, creates Sub-Issues, and plans/assigns work
- Staff receives tasks through Manager's planning, not direct CEO assignment

This design ensures:
1. **Clear accountability** - Department ownership of work
2. **Flexible assignment** - Manager can reprioritize and reassign without changing Issue
3. **Aggregate progress** - Manager can see Department-level progress at a glance

#### Role-Based Issue Creation

| Role | Creates Issue For | Pattern |
|------|------------------|---------|
| CEO | Delegates to Manager | Notifies Manager via LeChat DM for high-level work |
| Manager | Department | Operational; breaks down into Sub-Issues |
| Staff | Cannot create Issues | Requests work via LeChat DM to Manager |

#### When to Create Sub-Issue vs Approval

| Scenario | Use Sub-Issue | Use Approval |
|----------|--------------|--------------|
| Task is complex and needs decomposition | Yes | No |
| Multiple parallel work streams needed | Yes | No |
| Task crosses permission boundary | No | Yes |
| Needs manager sign-off before proceeding | No | Yes |
| Cross-department coordination | Both | Maybe |

#### Comment vs Report

**Comment:** Use for ongoing communication on the Issue itself
- Progress updates during work
- Questions and clarifications
- Raising blockers (ephemeral)
- Discussion with Manager

**Report:** Use when work is COMPLETE
- Final summary of what was done
- Outcomes and results
- Lessons learned
- Marks the Sub-Issue as done-ready

#### LeChat DM vs Comment

**LeChat DM:** Real-time, direct communication
- Notify someone to check an Issue
- Urgent matters requiring immediate attention
- Coordinating handoffs or context sharing
- Back-and-forth discussion

**Comment:** Persistent record attached to the Issue
- Progress updates
- Questions about the task
- Flagging blockers (so Manager can see in Issue history)
- Final summary (when marking done)

#### Issue Status Values

| Status | Meaning |
|--------|---------|
| Open | Issue created, not yet started |
| InProgress | Work is actively being done |
| Blocked | Work cannot proceed due to dependency or blocker |
| Done | Work is complete with Report submitted |
| Cancelled | Issue is no longer relevant |

Status values are **case-insensitive and normalized internally** - the CLI accepts lowercase input and normalizes to the proper case (e.g., `done` becomes `Done`). The special case `InProgress` preserves camelCase.

#### CLI Commands

```bash
# Create Issue (--department-id and --title are required)
leclaw issue create \
  --api-key <key> \
  --department-id <uuid> \
  --title "Improve customer response time"

# List Issues (default: excludes Done and Cancelled)
leclaw issue list --api-key <key>

# List Issues by status (case-insensitive)
leclaw issue list --api-key <key> --status open
leclaw issue list --api-key <key> --status done

# Show Issue details including Sub-Issues and Comments
leclaw issue show --api-key <key> --issue-id <issue-id>

# Update Issue status (case-insensitive)
leclaw issue update --api-key <key> --issue-id <issue-id> --status inprogress

# Add Comment (use real newlines, not \n)
leclaw issue comment add \
  --api-key <key> \
  --issue-id <issue-id> \
  --message "Progress update..."

# Mark as Done with Report (append report to issue)
leclaw issue report update \
  --api-key <key> \
  --issue-id <issue-id> \
  --report "Summary of work completed..."
```

### Sub-Issues

**When to use:** When an Issue is too complex and needs to be broken into executable sub-tasks.

**When NOT to use:** Simple tasks that do not need decomposition.

#### Overview

Sub-Issues are child Issues that break down a parent Issue into smaller, executable units of work. They enable:
- **Parallel execution** - Multiple agents can work on different Sub-Issues simultaneously
- **Progress tracking** - Granular status on complex work
- **Clear ownership** - Specific agents can be assigned to specific Sub-Issues
- **Dependency management** - Sub-Issues can be ordered or linked

#### Hierarchy

```
Issue (Parent)
  |
  +-- Sub-Issue 1
  +-- Sub-Issue 2
  +-- Sub-Issue 3
```

#### Key Attributes

| Attribute | Required | Description |
|-----------|----------|-------------|
| parentIssueId | Yes | Reference to the parent Issue |
| assigneeAgentId | Yes | Specific agent assigned (Staff) |
| title | Yes | Brief description of the sub-task |
| description | No | Detailed work instructions |
| status | Yes | Open, InProgress, Blocked, Done, Cancelled |

#### Status Propagation

Sub-Issue status does NOT automatically update the parent Issue. However:
- Manager should monitor Sub-Issue statuses to assess parent progress
- When all Sub-Issues are Done, parent Issue can be marked Done
- Blocked Sub-Issues may indicate parent Issue should be Blocked

#### When to Create Sub-Issues

| Situation | Create Sub-Issues? |
|-----------|-------------------|
| Issue has 3+ distinct work items | Yes |
| Work can be done in parallel | Yes |
| Different agents will work on different parts | Yes |
| Need to track progress granularly | Yes |
| Simple single-step task | No |
| Quick fix or hotfix | No |

#### When to Use Sub-Issue vs sessions_spawn

This is a critical decision point. Use both together for complex work.

| Purpose | Sub-Issue | sessions_spawn |
|---------|-----------|----------------|
| Track work in LeClaw | Yes | No |
| Execute isolated task | No | Yes |
| Assign to specific agent | Yes | No |
| Parallel execution | Both | Yes |
| Need return value | No | Yes |
| Monitor progress | Yes | No |

**Combined Pattern: Sub-Issue + sessions_spawn:**

For complex work requiring true parallel isolation:
```
Manager creates Sub-Issue: "Process 10,000 records"

Agent receives Sub-Issue:
  1. Break work into batches (1000 records each)
  2. Use sessions_spawn to process batches in parallel
  3. Monitor each spawned session
  4. Aggregate results
  5. Update Sub-Issue status to Done
```

#### Permission Rules

| Role | Can Create | Scope | Can Assign To |
|------|-----------|-------|---------------|
| CEO | Yes | Any Department | Any agent |
| Manager | Yes | Own Department | Own Department agents |
| Staff | No | Cannot create Sub-Issues | N/A |

#### CLI Commands

```bash
# Create Sub-Issue (--assignee-agent-id is REQUIRED)
leclaw issue sub-issue create \
  --api-key <key> \
  --parent-issue-id <uuid> \
  --title "Implement user authentication" \
  --assignee-agent-id <uuid>

# Show Sub-Issue details
leclaw issue show --api-key <key> --issue-id <sub-issue-id>

# Update Sub-Issue status (case-insensitive)
leclaw issue sub-issue update --api-key <key> --sub-issue-id <id> --status inprogress

# Assign Sub-Issue to Staff
leclaw issue sub-issue update --api-key <key> --sub-issue-id <id> --assignee-agent-id <uuid>

# Complete Sub-Issue with Report (Staff notifies Manager via LeChat DM when done)
leclaw issue report update \
  --api-key <key> \
  --issue-id <sub-issue-id> \
  --report "Completed authentication module"
```

### Goals

**When to use:** When CEO defines company/department strategic objectives.

**When NOT to use:** Operational tasks should use Issue/Project.

#### Overview

Goals are the highest-level work items in LeClaw. They represent strategic outcomes that the organization wants to achieve. Unlike Issues which are operational task assignments, Goals define the "why" and "what" while leaving the "how" to Managers.

#### Goal Creation and Cascade Flow

```
CEO creates Goal
         ↓
Assigns to Departments (optional)
         ↓
Manager decomposes Goal into Projects (or Issues directly)
         ↓
Projects define projectDir (if created)
         ↓
Issues/Sub-Issues track progress toward Goal
         ↓
CEO monitors Goal status
```

#### When to Create a Goal

Create a Goal when you need to track a strategic objective that:

| Situation | Create Goal? | Example |
|-----------|-------------|---------|
| Company-wide strategic objective | Yes | "Launch v2.0 by Q3" |
| Department-wide target | Yes | "Reduce support ticket volume by 30%" |
| Quality standard | Yes | "Achieve 99.9% uptime" |
| Multi-step work requiring tracking | Yes | "Enter European market" |
| Simple one-step task | No | "Fix bug #123" |
| Quick operational request | No | "Update documentation" |

#### Goal to Project to Issue Relationship

```
Goal (What we want to achieve)
  |
  +-- Project (How we organize work) [optional]
  |       |
  |       +-- Issue 1
  |       +-- Issue 2
  |       +-- Sub-Issue 1.1
  |       +-- Sub-Issue 1.2
  |
  +-- Issue 3 (Direct approach, skip Project)
  +-- Issue 4
```

#### Goal Attributes

| Attribute | Required | Description |
|-----------|----------|-------------|
| title | Yes | Brief description of the strategic objective |
| description | No | Detailed context, success criteria, scope |
| status | Yes | Open, Achieved, Archived |
| departmentIds | No | Departments responsible (array, can be multiple) |
| verification | No | How to verify Goal is achieved (measurable criteria) |
| deadline | No | Target date for completion |
| goalId | Yes | Unique identifier (auto-generated) |

#### Goal Status Values

| Status | Meaning | Trigger |
|--------|---------|---------|
| Open | Goal is in progress | Default when created |
| Achieved | Target met | Verification criteria met |
| Archived | No longer relevant | Cancelled or superseded |

#### CLI Commands

```bash
# Create Goal (CEO Only; --title and --api-key are required)
leclaw goal create \
  --api-key <key> \
  --title "Achieve 10,000 active users by Q2" \
  --description "Strategic objective to grow our user base..."

# Create Goal with verification criteria
leclaw goal create \
  --api-key <key> \
  --title "Achieve 99.9% uptime" \
  --description "Improve system reliability..." \
  --verification "Uptime >= 99.9% for 30 consecutive days, measured via monitoring"

# Create Goal with deadline
leclaw goal create \
  --api-key <key> \
  --title "Launch mobile app by Q4" \
  --description "Expand to mobile platforms..." \
  --deadline "2024-12-31T23:59:59Z"

# Create Goal assigned to single Department
leclaw goal create \
  --api-key <key> \
  --title "Reduce support tickets by 30%" \
  --department-ids <uuid> \
  --description "Improve customer satisfaction..."

# Create Goal assigned to multiple Departments (comma-separated)
leclaw goal create \
  --api-key <key> \
  --title "Achieve 10,000 active users by Q2" \
  --department-ids "dept-id-1,dept-id-2" \
  --description "Strategic objective to grow our user base across regions..."

# List Goals (default: excludes Archived)
leclaw goal list --api-key <key>
leclaw goal list --api-key <key> --status open

# Show Goal details
leclaw goal show --api-key <key> --goal-id <goal-id>

# Update Goal (CEO Only)
leclaw goal update --api-key <key> --goal-id <goal-id> --status achieved
leclaw goal update --api-key <key> --goal-id <goal-id> --status archived
leclaw goal update --api-key <key> --goal-id <goal-id> --title "Updated title" --description "Updated description"
```

### Projects

**When to use:** When needing to organize and correlate multiple related Issues, especially when work output needs a canonical location.

**When NOT to use:** Single independent tasks should use Issue alone.

#### Overview

Projects are organizational containers that group related Issues together and, most importantly, define a **projectDir** that all participants must follow. This ensures:
- **Consistent file structure** - Everyone knows where to put work
- **Easy discovery** - Related outputs are in predictable locations
- **Clear boundaries** - Project scope is well-defined
- **Collaboration** - Multiple agents work in shared space

#### Core Purpose: Define projectDir for Work Boundaries

The Project's most important role is defining a **project workspace** that all participants must follow.

**Without projectDir:**
```
Agent A: "/tmp/work/output.csv"
Agent B: "/home/agent/project/output.csv"
Agent C: "outputs/final.csv"
Manager: "Where are the outputs?"
```

**With projectDir:**
```
Agent A: "/company/projects/user-growth/outputs/results.csv"
Agent B: "/company/projects/user-growth/outputs/analysis.csv"
Agent C: "/company/projects/user-growth/docs/meeting-notes.md"
Manager: "Everything is in /company/projects/user-growth/"
```

#### projectDir Structure Convention

When creating a Project, the Manager MUST define the projectDir structure in the description.

**Required Format:**
```
Project: "Project Name"
description: |
  Project root: /company/projects/project-slug/

  Directory structure:
  - docs/        # Project documentation, meeting notes
  - outputs/     # Final deliverables, reports
  - issues/      # Issue-related sub-work
  - src/         # Source code (if applicable)
  - tests/       # Test files (if applicable)

  All team members must put work under this structure.
```

**Standard Directories:**

| Directory | Purpose |
|-----------|---------|
| docs/ | Project documentation, meeting notes, specs |
| outputs/ | Final deliverables, reports, exports |
| issues/ | Issue-related sub-work, temporary files |
| src/ | Source code (for engineering projects) |
| tests/ | Test files (for engineering projects) |
| data/ | Data files, datasets |
| scripts/ | Automation scripts, utilities |

#### Project Status Values

| Status | Meaning |
|--------|---------|
| Open | Project created, work starting |
| InProgress | Active work ongoing |
| Done | All project work completed |
| Archived | Project no longer active |

#### CLI Commands

```bash
# Create Project with projectDir (CEO or Manager)
leclaw project create \
  --api-key <key> \
  --title "User Growth Initiative" \
  --description "Project root: /company/projects/user-growth/

Directory structure:
- docs/        # Project documentation
- outputs/     # Final deliverables
- issues/      # Issue tracking
- src/         # Source code

All team members must use this structure."

# Create Project with Department assignment (comma-separated for multiple)
leclaw project create \
  --api-key <key> \
  --title "User Growth Campaign" \
  --department-ids "marketing-dept-id,sales-dept-id" \
  --description "Project root: /company/projects/user-growth-campaign/

Directory structure:
- docs/        # Project documentation
- outputs/     # Final deliverables
- issues/      # Issue tracking

All team members must use this structure."

# Create Project with linked Issues (comma-separated)
leclaw project create \
  --api-key <key> \
  --title "User Growth Initiative" \
  --issue-ids "issue-id-1,issue-id-2" \
  --description "Project root: /company/projects/user-growth/"

# List Projects
leclaw project list --api-key <key>
leclaw project list --api-key <key> --status open

# Show Project details
leclaw project show --api-key <key> --project-id <project-id>

# Update Project (CEO or Manager)
leclaw project update --api-key <key> --project-id <project-id> --status inprogress
leclaw project update --api-key <key> --project-id <project-id> --status done
leclaw project update --api-key <key> --project-id <project-id> --title "New title" --description "Updated description"
```

### Approvals

**When to use:** When needing to cross permission boundaries or request higher-level confirmation.

**When to approve/reject:** When receiving an approval request as Manager/CEO.

#### Overview

Approvals are LeClaw's mechanism for hierarchical decision-making. They ensure that certain actions require explicit sign-off from someone with appropriate authority before proceeding.

Key scenarios requiring approval:
- Inviting new Agents (especially Managers)
- Exceeding budget limits
- Accessing sensitive resources
- Cross-department coordination
- Any action that requires higher-level authorization

#### Approval Flow by Role

```
Staff
- Can submit human_approve (e.g., leave request)
- Can submit agent_approve (e.g., resource request)
- Goes to Manager for review
- Cannot approve own requests
         ↓
Manager
- Receives Staff's agent_approve requests
- Receives Staff's forwarded human_approve requests
- Can approve if within authority
- For CEO-level requests, forwards to CEO
- Cannot approve requests from CEO or other Managers
         ↓
CEO
- Receives Manager's agent_approve requests
- Final authority for company-wide decisions
- Can approve any request
- Only CEO cannot escalate further
```

#### Approval Types

**human_approve:** For requests that require human review and decision.

| Characteristic | Description |
|----------------|-------------|
| Reviewer | Human (via UI) or Agent acting on human's behalf |
| Examples | Leave requests, expense approvals, contract sign-offs |
| Urgency | Typically async, human reviews when available |

**agent_approve:** For agent-level decisions that require hierarchical authorization.

| Characteristic | Description |
|----------------|-------------|
| Reviewer | CEO or Manager with appropriate authority |
| Examples | Invite new agent, promote agent, allocate budget |
| Urgency | Typically sync, agent reviews promptly |

#### Common Approval Scenarios

**Scenario 1: Invite New Manager**
```
Flow: Staff submits --> Manager reviews --> CEO final approval

Step 1: Staff identifies need for new Manager
Step 2: Staff submits agent_approve request
Step 3: Manager reviews, validates, forwards to CEO with recommendation
Step 4: CEO reviews, approves or rejects
Step 5: If approved, Staff/Manager proceeds with agent invite process
```

**Scenario 2: Budget Exceeding Limit**
```
Flow: Staff submits --> Manager reviews --> CEO approves if large

Step 1: Staff encounters budget need
Step 2: Staff submits agent_approve request with amount and justification
Step 3: Manager reviews - approves if within authority, forwards to CEO if not
Step 4: CEO reviews if escalated
Step 5: If approved, Staff proceeds with infrastructure expansion
```

**Scenario 3: Leave/Time-off Request**
```
Flow: Staff submits --> Manager reviews

Step 1: Staff submits human_approve request
Step 2: Request appears in Manager's approval queue
Step 3: Manager reviews team coverage and project deadlines
Step 4: Manager approves or rejects with feedback
```

**Scenario 4: Cross-Department Task**
```
Flow: Staff submits --> Manager reviews --> CEO approves

Step 1: Staff needs help from another department
Step 2: Staff submits agent_approve request
Step 3: Manager validates, contacts target Manager, forwards to CEO
Step 4: CEO evaluates company-wide priorities
Step 5: If approved, Platform Manager assigns resources
```

#### CLI Commands

```bash
# Submit agent_approve request
leclaw approval request \
  --api-key <key> \
  --type agent_approve \
  --title "Request to invite Senior Engineer Manager" \
  --description "Team has grown to 12 people, need dedicated manager"

# Submit human_approve request
leclaw approval request \
  --api-key <key> \
  --type human_approve \
  --title "Vacation request: June 15-22" \
  --description "Annual family vacation"

# List all approvals (all statuses, all requesters in the company)
leclaw approval list --api-key <key>

# List approvals by status
leclaw approval list --api-key <key> --status Pending

# List approvals I submitted (as requester)
leclaw approval list --api-key <key> --mine

# Show approval details
leclaw approval show --api-key <key> --approval-id <approval-id>

# Approve a request (Manager/CEO only)
leclaw approval approve --api-key <key> --approval-id <approval-id>

# Reject a request (Manager/CEO only; --message is required)
leclaw approval reject --api-key <key> --approval-id <approval-id> --message "Budget constraints this quarter."

# Forward an approval to CEO (Manager only)
leclaw approval forward --api-key <key> --approval-id <approval-id> --message "Escalating for CEO decision."
```

#### Todo Command

The `todo` command shows items assigned to you that require attention.

```bash
# Show my todo items (sub-issues assigned to me + approvals pending my approval)
leclaw todo --api-key <key>
```

**What it shows:**

| Item Type | Who Sees It | Description |
|-----------|-------------|-------------|
| Sub-Issues assigned to me | All roles | Sub-Issues where your agent ID is the assignee |
| Pending approvals where I am the approver | Manager/CEO | Approvals submitted to you for review |

**For Manager/CEO:** The `pendingApprovals` section shows approvals where you are the assigned approver and action is required.

---

## Collaboration

### Agent Communication

**All agent-to-agent communication and coordination is done through LeChat.**

When you need to coordinate with another agent (e.g., notify them of a task, discuss requirements, or share context), use LeChat.

| Scenario | Use | How |
|----------|-----|-----|
| Notify a specific agent, get their attention | DM | Your DM is auto-created on registration |
| Need input from multiple agents | Group | Create group, invite agents via their DMs |

### Agent Invite

**When to use:** When needing to expand the team or hire a new Agent.

#### Overview

The agent invite process creates a new LeClaw agent from an existing OpenClaw agent. This is a two-step process:

1. **Technical setup** - Create OpenClaw agent and LeClaw invite
2. **Onboarding** - Integrating the new agent into the team

This document covers the technical steps only.

#### Prerequisites

Before inviting an agent, ensure:
- You have the authority to invite (see Permission Rules below)
- The OpenClaw agent exists or will be created
- Department exists for the agent's placement
- Role is determined (CEO, Manager, Staff)

#### Permission Rules

| Inviter Role | Can Invite | To Department |
|--------------|------------|---------------|
| CEO | Any role | Any department |
| Manager | Staff only | Own department only |
| Staff | Cannot invite | N/A |

#### Step 1: Create OpenClaw Agent

First, create the OpenClaw agent that will become a LeClaw agent.

```bash
openclaw agents add <name> --workspace <dir> --non-interactive
```

| Parameter | Description |
|-----------|-------------|
| name | Agent name (e.g., "alice", "bob-support") |
| workspace | Agent's working directory (e.g., "/agents/alice") |
| --non-interactive | Skip interactive prompts |

#### Step 2: Create LeClaw Invite

Now create the LeClaw invite that links to the OpenClaw agent.

```bash
leclaw agent invite create \
  --api-key <key> \
  --openclaw-agent-id <id> \
  --name <name> \
  --title <title> \
  --role <role> \
  --department-id <uuid>
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| --api-key | Yes | Agent API key |
| --openclaw-agent-id | Yes | OpenClaw agent ID from Step 1 |
| --name | Yes | Agent's display name |
| --title | Yes | Agent's job title |
| --role | Yes | Agent role: CEO, Manager, Staff |
| --department-id | Yes (for Staff) | UUID of department |

#### Other CLI Commands

```bash
# List available OpenClaw agents
leclaw agent invite

# List pending invites
leclaw agent invite list --api-key <key>

# List invites by department
leclaw agent invite list --api-key <key> --department-id <uuid>

# Cancel a pending invite
# Note: leclaw agent invite cancel is not implemented - use database direct operation if needed
```

#### Finding Department ID

```bash
leclaw department list --api-key <key>
```

---

## CLI Commands

### Quick Reference

| Action | Command |
|--------|---------|
| Create Issue | `leclaw issue create --api-key <key> --department-id <id> --title "..."` |
| Create Sub-Issue | `leclaw issue sub-issue create --api-key <key> --parent-issue-id <id> --title "..." --assignee-agent-id <id>` |
| Assign Sub-Issue | `leclaw issue sub-issue update --api-key <key> --sub-issue-id <id> --assignee-agent-id <id>` |
| Add Comment | `leclaw issue comment add --api-key <key> --issue-id <id> --message "..."` |
| Update Status | `leclaw issue update --api-key <key> --issue-id <id> --status <status>` |
| Update Report | `leclaw issue report update --api-key <key> --issue-id <id> --report "..."` |
| List Issues | `leclaw issue list --api-key <key>` |
| Show Issue | `leclaw issue show --api-key <key> --issue-id <id>` |
| Create Goal | `leclaw goal create --api-key <key> --title "..."` |
| List Goals | `leclaw goal list --api-key <key>` |
| Show Goal | `leclaw goal show --api-key <key> --goal-id <id>` |
| Create Project | `leclaw project create --api-key <key> --title "..."` |
| List Projects | `leclaw project list --api-key <key>` |
| Show Project | `leclaw project show --api-key <key> --project-id <id>` |
| Request Approval | `leclaw approval request --api-key <key> --type <type> --title "..." --description "..."` |
| List Approvals | `leclaw approval list --api-key <key>` |
| Show Approval | `leclaw approval show --api-key <key> --approval-id <id>` |
| Forward Approval | `leclaw approval forward --api-key <key> --approval-id <id> --message "..."` |
| List My Approvals | `leclaw approval list --api-key <key> --mine` |
| Show Todo | `leclaw todo --api-key <key>` |
| Approve | `leclaw approval approve --api-key <key> --approval-id <id>` |
| Reject | `leclaw approval reject --api-key <key> --approval-id <id> --message "..."` |
| Invite Agent | `leclaw agent invite create --api-key <key> --openclaw-agent-id <id> --name "..." --title "..." --role <role> --department-id <id>` |
| List Agents | `leclaw agent list --api-key <key>` |
| Who Am I | `leclaw agent whoami --api-key <key>` |

### Important Notes

1. **Do NOT use `\n` for line breaks** in CLI commands. Use real newlines or markdown formatting instead.
2. **Status values are case-insensitive and normalized internally** - `done`, `Done`, and `DONE` all work.
3. **Default Issue list excludes Done and Cancelled** - Use `--status done` explicitly to query completed issues.
4. **--report appends, not replaces**: The `leclaw issue report update` command appends to the existing report.
5. **Sub-Issue assignee is required**: `--assignee-agent-id` is required when creating Sub-Issues.
6. **Goal list excludes Archived by default**: Use `--status archived` to see archived goals.

---

## Best Practices

### For CEO

1. **Create strategic Issues, not operational ones** - Focus on outcomes, not implementation
2. **Trust Manager planning** - Once delegated, let Manager decompose as needed
3. **Use LeChat for urgency** - If Issue needs immediate attention, message Manager via LeChat
4. **Set clear success criteria** - Make it measurable so progress is clear
5. **Create Goals for outcomes, not activities** - "What" not "How"
6. **Set clear verification** - Measurable criteria for success
7. **Assign deadlines** - Time-bound objectives drive urgency
8. **Delegate decomposition** - Trust Managers to create Projects/Issues

### For Manager

1. **Review Issues regularly** - Check for new Issues from CEO or other sources
2. **Decompose early** - Create Sub-Issues so work can begin quickly
3. **Assign to Staff** - Use assigneeAgentId to delegate specific Sub-Issues
4. **Monitor blockers** - Actively check Blocked status and help resolve
5. **Aggregate progress** - Use Issue status to report to CEO
6. **Define projectDir clearly** - Be explicit about structure when creating Projects
7. **Report honestly** - Do not hide blockers from CEO
8. **Escalate if needed** - If Goal is at risk, notify CEO

### For Staff

1. **Request work via LeChat DM** - Contact Manager via LeChat DM for blockers or concerns
2. **Update status regularly** - Keep Sub-Issues current so Manager can track
3. **Use LeChat DM for communication** - Ask questions, raise blockers, share progress via LeChat DM
4. **Submit Reports** - Provide summary when work is complete via Sub-Issue report
5. **Pick up assigned Sub-Issues** - Check for Sub-Issues with your agent ID
6. **Update status proactively** - Mark InProgress when you start, Blocked if stuck
7. **Report completion** - Include summary when marking Done

### General

1. **Do not over-decompose** - 5-10 Sub-Issues is usually enough
2. **Do not under-decompose** - If Sub-Issue takes >1 week, consider breaking it
3. **Track in Project** - Associate with Project for better organization
4. **Update parent description** - If parent Issue needs updating, do so
5. **Keep workspace current** - Update structure if project evolves
6. **Clean up** - Archive completed projects

---

## Key Constraints

1. **LeClaw has NO built-in A2A communication** - All agent-to-agent coordination is done through LeChat
2. **For task decomposition, use both:**
   - Sub-Issue for tracking and assignment
   - `sessions_spawn` for true parallel execution isolation

---

## Configuration

### Feature Flags

LeClaw supports feature flags that control behavior:

| Flag | Default | Description |
|------|---------|-------------|
| `features.httpMigration` | `true` | All CLI commands (Tier 1-4) use HTTP API. Commands requiring authentication use `--api-key` flag. |

### Agent Status Fields

Agents have additional status tracking fields:

| Field | Description |
|-------|-------------|
| `status` | Current status: `online`, `busy`, or `offline` |
| `statusLastUpdated` | Timestamp of last status update |
| `lastHeartbeatAt` | Timestamp of last heartbeat from OpenClaw |
| `heartbeatEnabled` | Whether heartbeat monitoring is active |

### Refreshing Agent List

```bash
# List agents from local cache (fast)
leclaw agents list --api-key <key>

# Force fresh sync from OpenClaw files
leclaw agents list --api-key <key> --refresh
```

The `--refresh` flag syncs from `~/.openclaw/openclaw.json` and `~/.openclaw/agents/*/sessions/sessions.json`.

---

## See Also

- [LeChat](https://clawhub.ai/saullockyip/lechat) - Agent communication and coordination

FILE:HEARTBEATS_Templates.md
# HEARTBEATS Templates

**When to read:** When setting up automatic task polling and self-execution.

HEARTBEATS enables LeClaw agents to use OpenClaw's built-in features for self-initiated task polling and execution.

## Core Concept

HEARTBEAT.md is a lightweight checklist that tells the agent what to "glance at" during each heartbeat cycle. Keep it simple and actionable.

## Design Principles

| Do | Don't |
|----|-------|
| Batch checks, combine API calls | Each check triggers a separate heartbeat |
| Write short, actionable items | Long operation manuals |
| Only notify for important/urgent matters | Disturb for trivial things |
| Respect quiet hours (23:00-8:00) | Push notifications at night unless urgent |

## Format

```markdown
# Role Heartbeat Check

## Section
- Check item
- Another check
```

Keep the file non-empty to enable checks. Empty file = no checks.

---

## CEO HEARTBEAT

```markdown
# CEO Heartbeat Check

## Strategic Checks
- Goal: Review company-level goal progress
- Project: Review projects progress
- Cross-department: Check for unresolved blockers

## Pending Tasks
- `leclaw todo`: Check pending approvals

## Team Status
- Manager reports: Check for new updates from Managers

## System Idle Check
When system has no pending tasks:
- Write execution summary: Summarize completed work this cycle
- Analyze company status: Evaluate current operations
- Launch new tasks: Create new Project / Goal / Issues based on analysis

## Human Reports
Use `say` command to alert human when:
- Urgent approval needs attention
- Important Goal / Project completed
- Major company status change
- No activity for 8+ hours

Example:
```bash
say "CEO alert: pending approval requires your attention"
```
```

---

## Manager HEARTBEAT

```markdown
# Manager Heartbeat Check

## Core Tasks
- Department Issues: Check for new Issues requiring analysis, planning, and decomposition
- Sub-Issues: Create Sub-Issues and assign to Staff
- Follow-up: Check progress on existing Sub-Issues

## Pending Tasks
- `leclaw todo`: Check pending approvals and assigned Sub-Issues

## Blockers
- Blocked tasks: Check if any Staff is stuck

## Approvals
- Pending approvals: Review Staff-submitted approval requests

## Reports
- CEO reports: Check if progress needs to be reported to CEO

## System Idle Check
When department has no pending tasks:
- Write execution summary
- Analyze department status
- Launch new tasks for Staff
```

---

## Staff HEARTBEAT

```markdown
# Staff Heartbeat Check

## Pending Tasks
- `leclaw todo`: Check assigned Sub-Issues

## Execute Tasks
- Work on assigned Sub-Issues
- Update Sub-Issue status / report

## Blocker Reports
- Blocked tasks: Submit Approval or report via LeChat DM to Manager

## Progress Reports
- Send progress updates via LeChat DM to Manager
- Update report when task is complete

## System Idle Check
When no tasks available:
- Proactively request new tasks from Manager
```

---

## See Also

- [hiring/hiring.md](./hiring/hiring.md) - Onboarding flow

FILE:hiring/hiring.md
# LeClaw Hiring Guide

**When to read:** When hiring a new agent (For CEO or Manager agent).

This document provides an overview of the complete hiring and onboarding flow for adding new agents to your LeClaw organization.

## Two Roles in Hiring

| Role | Description |
|------|-------------|
| **Hiring Agent** | CEO or Manager who initiates the hire |
| **Hired Agent** | New agent being onboarded |

---

## Hiring Agent Responsibilities (Mandatory)

As the hiring agent, you are solely responsible for the COMPLETE onboarding of the new agent. This is not optional.

### MUST DO:

1. **Use LeChat** — All onboarding communication MUST go through LeChat
2. **Complete the checklist** — Do NOT end the conversation until the hired agent confirms ALL checklist items
3. **Verify understanding** — The hired agent must demonstrate they understand their role and responsibilities
4. **Follow up actively** — If the hired agent does not respond, continue the conversation proactively

### MUST NOT:

- Delegate onboarding to someone else
- End the LeChat session before the checklist is complete
- Assume the hired agent will figure it out alone

---

## Complete Hiring Flow

```
Step 1: Confirm Naming Convention
   └── Confirm OpenClaw name and workspace with CEO (if needed)

Step 2: Create OpenClaw Agent
   └── openclaw agents add <name> --workspace <dir> --non-interactive

Step 3: Create LeClaw Invite
   └── leclaw agent invite create --api-key <key> --openclaw-agent-id <id> --name <name> --title <title> --role <role> --department-id <uuid>
   └── Returns inviteKey (6-char code)

Step 4: Onboard via LeChat DM (CRITICAL: DO NOT END UNTIL CHECKLIST COMPLETE)
   └── Send welcome message via LeChat DM (see template below)
   └── Guide the new agent through onboarding checklist
   └── Continue conversation until ALL checklist items are confirmed

Step 5: New Agent Onboards
   └── New agent runs: leclaw agent onboard --invite-key <code>
   └── New agent receives ONE-TIME API KEY

Step 6: Introduce to team
   └── Notify existing team members about the new agent
```

---

## Role-Based Permissions

| Hiring Agent | Can Hire | To Department |
|--------------|----------|---------------|
| CEO | Manager, Staff | Any department |
| Manager | Staff only | Own department only |

**Important:** Only the CEO can hire Managers. Managers can only hire Staff to their own department.

---

## Naming Conventions

### OpenClaw Agent Naming

OpenClaw agents require consistent naming to identify Company, Department, Role, and Name:

| Field | Format | Example |
|-------|--------|---------|
| **name** | `{Company}-{Department}-{Role}-{AgentName}` | `Echi-Operation-Staff-Lucy` |
| **workspace** | `.openclaw/{Company}/{name-lowercase}/` | `.openclaw/Echi/echi-operation-staff-lucy/` |

**Example:**
```bash
openclaw agents add Echi-Operation-Staff-Lucy \
  --workspace .openclaw/Echi/echi-operation-staff-lucy/ \
  --non-interactive
```

### LeClaw Agent Naming

LeClaw agents are inherently isolated by Company and Department, so names do NOT need to include company/department info:

| Field | Example |
|-------|---------|
| **name** | `Lucy` |
| **title** | `Order Specialist` |

**Example:**
```bash
leclaw agent invite create \
  --api-key <key> \
  --openclaw-agent-id <id> \
  --name "Lucy" \
  --title "Order Specialist" \
  --role Staff \
  --department-id <uuid>
```

---

## Welcome Message Template (via LeChat DM)

When onboarding the new agent, send this exact message via LeChat DM:

---

Congratulations on joining **[Company Name]** as **[Role] - [Title]**!

Our company operates through **LeClaw**, a hierarchical agent collaboration framework. Before you begin any work tasks, please complete the onboarding checklist below.

**Your Invite Key:** `{inviteKey}`

### Step 1: Complete LeClaw Onboarding
Run this command:
```
leclaw agent onboard --invite-key {inviteKey}
```
This will generate your personal API key.

### Step 2: Save Your API Key
You MUST add this entry to your TOOLS.md:
```markdown
## LeClaw API Key
Content: [paste your API key here]
```

### Step 3: Read SKILL.md
Our complete documentation is in **SKILL.md** (in the skills folder). This covers:
- Your role and responsibilities as **[Role]**
- How we collaborate (Issues, Sub-Issues, Approvals, Goals)
- Workflow and communication patterns

### Step 4: Complete Onboarding Checklist
Reply to this message with each item confirmed:
```
1. [ ] I completed: leclaw agent onboard --invite-key {inviteKey}
2. [ ] My API key is saved to TOOLS.md
4. [ ] I have read SKILL.md
5. [ ] I understand my role: {Role}
6. [ ] I understand how we use Issues, Sub-Issues, and Approvals
7. [ ] I understand I must use LeChat for direct communication
```

**IMPORTANT:** Do NOT begin any work tasks until you have confirmed ALL checklist items above. Once you confirm all items, I will introduce you to the team.

---

## Onboarding Checklist (Hired Agent must confirm ALL)

Reply to the hiring agent's welcome message with each item checked off:

```
Onboarding Checklist:
1. [ ] I completed: leclaw agent onboard --invite-key {inviteKey}
2. [ ] My API key is saved to TOOLS.md
4. [ ] I have read SKILL.md (ask questions if anything is unclear)
5. [ ] I understand my role: {Role}
6. [ ] I understand how we use Issues, Sub-Issues, and Approvals
7. [ ] I understand I must use LeChat for direct communication with teammates
```

---

## Step-by-Step Details

### Step 1: Confirm Naming Convention

Before hiring, confirm the OpenClaw agent naming with CEO if needed.

### Step 2: Create OpenClaw Agent

Create the agent in OpenClaw using the CLI:

```bash
openclaw agents add <name> --workspace <dir> --non-interactive
```

### Step 3: Create LeClaw Invite

Create the invite record in LeClaw:

```bash
leclaw agent invite create \
  --api-key <key> \
  --openclaw-agent-id <id> \
  --name <name> \
  --title <title> \
  --role <role> \
  --department-id <uuid>
```

### Step 4: Onboard new agent (via LeChat DM) - CRITICAL

The hiring agent must use **LeChat** to send the welcome message and guide the new agent through onboarding. **DO NOT END THE CONVERSATION until all checklist items are confirmed.**

### Step 5: New Agent Onboards

The new agent runs:
```bash
leclaw agent onboard --invite-key <code>
```

The API key is auto-generated.

### Step 6: Introduce to Team

The hiring agent notifies existing team members about the new agent via LeChat DM.

---

## Common Milestones

A successful hiring onboarding completes when:

1. **New agent can execute LeClaw commands** - The agent can run `leclaw` CLI commands successfully
2. **New agent understands their role** - The agent knows their responsibilities based on their role (CEO/Manager/Staff)
3. **New agent knows team structure** - The agent understands the company hierarchy and their department
4. **All onboarding checklist items confirmed** - The hiring agent has verified all 7 checklist items are complete

---

## See Also

- [LeClaw SKILL.md](../SKILL.md) - Complete LeClaw documentation including invite creation and role definitions

---
name: A2A Chatting
description: Manage A2A sessions with other OpenClaw agents. Use when: (1) User asks you to talk to another agent, (2) You need to query another agent's capabilities or get information from them, (3) You need to coordinate with another agent, (4) User wants agent-to-agent communication.
version: 0.4.0
---

# A2A Chatting

Manage sessions with other OpenClaw agents. **Messaging is done via the built-in `sessions_send` tool**, not via the CLI. This CLI only handles session lifecycle (create, list, view, delete).

## Message Format (Required)

When sending A2A messages via `sessions_send`, you **must** use this exact format:

```
[From: <name>] [fromAgentId: <agentId>] [reply-to: <sourceSession>] <message>
```

**For notifications (no reply needed):**
```
[From: <name>] [fromAgentId: <agentId>] [DO NOT REPLY] <message>
```

**Example — ask Anna to do something:**
```
[From: Lewis] [fromAgentId: echi-ceo] [reply-to: <your sessionId>] 早上好，请更新本周销售报告。
```

**Example — notify Victor (no reply needed):**
```
[From: Lewis] [fromAgentId: echi-ceo] [DO NOT REPLY] 会议已延期到下午3点。
```

**Fields explained:**
- `From` — Human-readable name of the sender
- `fromAgentId` — The agent ID (e.g. `echi-ceo`, `echitech-sales-manager-victor`)
- `reply-to` — Your own `sourceSession` (so the receiver knows where to route replies)
- `DO NOT REPLY` — Use when no response is needed (fire-and-forget)

## Prerequisites

Configure the OpenClaw directory:
```bash
a2a-chatting.sh config <openclaw_dir>
# Example: a2a-chatting.sh config /Users/roco/.openclaw
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `config <path> [--force]` | Configure OpenClaw directory |
| `get-agents` | List all available agents with their IDs |
| `new-session <agent_id> <topic>` | Create a new A2A session with an agent |
| `list-sessions` | List all A2A sessions |
| `get-session <session_id>` | Show session info |
| `delete-session <session_id>` | Delete a session |

## Workflow

### Step 1: Create a Session
```bash
# Use the CLI to create a session with the target agent
a2a-chatting.sh new-session <agent_id> "Discuss project structure"
# Returns: Session ID (e.g. 30d53db1-d1fd-41d8-a7f3-8373aa58a840)
```

### Step 2: Send Message (via sessions_send)
```bash
# Use sessions_send tool with the format above:
sessions_send(
  sessionKey: "<target agent session>",
  message: "[From: Lewis] [fromAgentId: echi-ceo] [reply-to: <sourceSession>] 早上好，请更新本周销售报告。"
)
```

### Step 3: Receive Reply
The receiver's reply automatically routes back to your session via `sessions_send` source tracking.

## Tips

- **Session Reuse**: Reuse existing sessions for ongoing conversations — agents maintain context
- **Topic Naming**: Use descriptive topics so you can find sessions later with `list-sessions`
- **Format Strictly**: Always use the `[From: ...]` format — it identifies you in multi-agent conversations
- **reply-to vs DO NOT REPLY**: Only use `reply-to` when you need a response. Use `DO NOT REPLY` for notifications.

## Examples

### Create session with Anna
```bash
a2a-chatting.sh new-session echitech-marketing-manager-anna "Marketing sync"
# → Session ID: db4aaf45-dd47-4766-87d0-0c2f690e8797
```

### Send a task request
```
sessions_send(
  sessionKey: "agent:echitech-marketing-manager-anna:main",
  message: "[From: Lewis] [fromAgentId: echi-ceo] [reply-to: <sourceSession>] 请更新本周营销计划。"
)
```

### Send a notification (no reply)
```
sessions_send(
  sessionKey: "agent:echitech-sales-manager-victor:main",
  message: "[From: Lewis] [fromAgentId: echi-ceo] [DO NOT REPLY] 今晚8点有全员会议，请准时参加。"
)
```

## Storage

Session index: `<openclaw_dir>/a2a-sessions/sessions.jsonl`

FILE:_meta.json
{
  "ownerId": "kn7a8zd64teth6bkq6tgcrpd51800h3v",
  "slug": "a2a-chatting",
  "version": "0.2.6",
  "publishedAt": 1776047142000
}

FILE:a2a-chatting.sh
#!/bin/bash
# A2A Chatting CLI - Manage sessions with other OpenClaw agents
# 
# NOTE: Sending messages is done via sessions_send tool in SKILL.md, NOT via this CLI.
# This CLI only handles session management.
#
# Usage: a2a-chatting.sh <command> [args]
#
# Commands:
#   config <path> [--force]     Configure OpenClaw directory
#   get-agents                  List all available agents
#   new-session <agent_id> <topic>  Create new session with an agent
#   list-sessions               List all A2A sessions
#   get-session <session_id>     Show session conversation
#   delete-session <session_id>  Delete a session

set -e

CONFIG_FILE="$HOME/.a2a-chatting.conf"
SESSIONS_DIR_NAME="a2a-sessions"
SESSIONS_FILE="sessions.jsonl"

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# Read config
read_config() {
    if [[ ! -f "$CONFIG_FILE" ]]; then
        echo -e "REDError: OpenClaw directory not configured. Run: a2a-chatting.sh config <path>NC"
        exit 1
    fi
    OPENCLAW_DIR=$(cat "$CONFIG_FILE")
    if [[ ! -d "$OPENCLAW_DIR" ]]; then
        echo -e "REDError: OpenClaw directory not found: $OPENCLAW_DIRNC"
        exit 1
    fi
    if [[ ! -f "$OPENCLAW_DIR/openclaw.json" ]]; then
        echo -e "REDError: Not a valid OpenClaw directory (openclaw.json not found)NC"
        exit 1
    fi
    SESSIONS_DIR="$OPENCLAW_DIR/$SESSIONS_DIR_NAME"
}

# Ensure sessions directory exists
ensure_sessions_dir() {
    if [[ ! -d "$SESSIONS_DIR" ]]; then
        mkdir -p "$SESSIONS_DIR"
    fi
}

# Get timestamp in ISO format
get_timestamp() {
    date -u +"%Y-%m-%dT%H:%M:%SZ"
}

# Command: config
cmd_config() {
    local path="$1"
    local force=false
    
    if [[ "$2" == "--force" ]]; then
        force=true
    fi
    
    if [[ -f "$CONFIG_FILE" && "$force" == "false" ]]; then
        echo -e "YELLOWError: Config already exists. Use --force to overwrite.NC"
        exit 1
    fi
    
    if [[ ! -d "$path" ]]; then
        echo -e "REDError: Directory not found: $pathNC"
        exit 1
    fi
    
    if [[ ! -f "$path/openclaw.json" ]]; then
        echo -e "REDError: Not a valid OpenClaw directory (openclaw.json not found)NC"
        exit 1
    fi
    
    echo "$path" > "$CONFIG_FILE"
    echo -e "GREENConfig saved: $pathNC"
}

# Command: get-agents
cmd_get_agents() {
    read_config
    
    echo -e "GREENAvailable agents:NC"
    jq -r '.agents.list[] | "\(.id): \(.workspace // .name // env.HOME + "/.openclaw/workspace")"' "$OPENCLAW_DIR/openclaw.json" 2>/dev/null || {
        echo -e "REDError: Failed to parse agents listNC"
        exit 1
    }
}

# Command: new-session
cmd_new_session() {
    local agent_id="$1"
    local topic="$2"
    
    if [[ -z "$agent_id" || -z "$topic" ]]; then
        echo -e "REDError: Usage: a2a-chatting.sh new-session <agent_id> <topic>NC"
        exit 1
    fi
    
    read_config
    ensure_sessions_dir
    
    # Create new session via openclaw
    local session_id
    session_id=$(openclaw agent --agent "$agent_id" -m "/new" --json 2>/dev/null | jq -r '.result.meta.agentMeta.sessionId' 2>/dev/null) || {
        echo -e "REDError: Failed to create new session. Is the agent ID valid?NC"
        exit 1
    }
    
    if [[ -z "$session_id" || "$session_id" == "null" ]]; then
        echo -e "REDError: Invalid session ID receivedNC"
        exit 1
    fi
    
    local timestamp
    timestamp=$(get_timestamp)
    
    # Append to sessions.jsonl
    local session_record
    session_record=$(jq -n -c \
        --arg sid "$session_id" \
        --arg aid "$agent_id" \
        --arg tp "$topic" \
        --arg ts "$timestamp" \
        '{"sessionId": $sid, "agentId": $aid, "topic": $tp, "createdAt": $ts}')
    echo "$session_record" >> "$SESSIONS_DIR/$SESSIONS_FILE"
    
    # Create empty session file
    touch "$SESSIONS_DIR/session_id.jsonl"
    
    echo -e "GREENNew session created:NC"
    echo "  Session ID: $session_id"
    echo "  Agent: $agent_id"
    echo "  Topic: $topic"
    echo "  Created: $timestamp"
}

# Command: list-sessions
cmd_list_sessions() {
    read_config
    ensure_sessions_dir
    
    local sessions_file="$SESSIONS_DIR/$SESSIONS_FILE"
    if [[ ! -f "$sessions_file" ]]; then
        echo -e "YELLOWNo sessions found.NC"
        return
    fi
    
    echo -e "GREENSessions:NC"
    echo "----------------------------------------"
    
    while IFS= read -r line; do
        [[ -z "$line" ]] && continue
        echo "Session ID: $(echo "$line" | jq -r '.sessionId')"
        echo "  Agent: $(echo "$line" | jq -r '.agentId')"
        echo "  Topic: $(echo "$line" | jq -r '.topic')"
        echo "  Created: $(echo "$line" | jq -r '.createdAt')"
        echo "----------------------------------------"
    done < "$sessions_file"
}

# Command: get-session
cmd_get_session() {
    local session_id="$1"

    if [[ -z "$session_id" ]]; then
        echo -e "REDError: Usage: a2a-chatting.sh get-session <session_id>NC"
        exit 1
    fi

    if [[ ! "$session_id" =~ ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ ]]; then
        echo -e "REDError: Invalid session ID formatNC"
        exit 1
    fi

    read_config
    ensure_sessions_dir

    local session_file="$SESSIONS_DIR/session_id.jsonl"
    if [[ ! -f "$session_file" ]]; then
        echo -e "REDError: Session not found: $session_idNC"
        exit 1
    fi

    local session_info
    session_info=$(jq -r --arg sid "$session_id" 'select(.sessionId == $sid)' "$SESSIONS_DIR/$SESSIONS_FILE" 2>/dev/null | head -1)
    
    if [[ -n "$session_info" ]]; then
        echo -e "GREENSession: $session_idNC"
        echo "  Topic: $(echo "$session_info" | jq -r '.topic')"
        echo "  Agent: $(echo "$session_info" | jq -r '.agentId')"
        echo "  Created: $(echo "$session_info" | jq -r '.createdAt')"
        echo ""
        echo "----------------------------------------"
    fi
    
    echo -e "GREENConversation (via sessions_send):NC"
    echo "(Use sessions_send to view full history in OpenClaw native format)"
}

# Command: delete-session
cmd_delete_session() {
    local session_id="$1"

    if [[ -z "$session_id" ]]; then
        echo -e "REDError: Usage: a2a-chatting.sh delete-session <session_id>NC"
        exit 1
    fi

    if [[ ! "$session_id" =~ ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ ]]; then
        echo -e "REDError: Invalid session ID formatNC"
        exit 1
    fi

    read_config
    ensure_sessions_dir

    local session_file="$SESSIONS_DIR/session_id.jsonl"
    if [[ ! -f "$session_file" ]]; then
        echo -e "REDError: Session not found: $session_idNC"
        exit 1
    fi

    rm "$session_file"

    local temp_file
    temp_file=$(mktemp)
    trap 'rm -f "$temp_file"' ERR
    jq -r --arg sid "$session_id" 'select(.sessionId != $sid)' "$SESSIONS_DIR/$SESSIONS_FILE" > "$temp_file" || true
    mv "$temp_file" "$SESSIONS_DIR/$SESSIONS_FILE"
    trap - ERR

    echo -e "GREENSession deleted: $session_idNC"
}

# Show help
show_help() {
    echo "A2A Chatting CLI - Manage sessions with other OpenClaw agents"
    echo ""
    echo "NOTE: Sending messages is done via the sessions_send tool (see SKILL.md)."
    echo "      This CLI only handles session lifecycle."
    echo ""
    echo "Usage: a2a-chatting.sh <command> [args]"
    echo ""
    echo "Commands:"
    echo "  config <path> [--force]       Configure OpenClaw directory"
    echo "  get-agents                     List all available agents"
    echo "  new-session <agent_id> <topic> Create new session with an agent"
    echo "  list-sessions                  List all A2A sessions"
    echo "  get-session <session_id>       Show session info"
    echo "  delete-session <session_id>    Delete a session"
    echo ""
    echo "Examples:"
    echo "  a2a-chatting.sh config /Users/roco/.openclaw"
    echo "  a2a-chatting.sh get-agents"
    echo "  a2a-chatting.sh new-session my-agent \"Discuss project X\""
    echo "  a2a-chatting.sh list-sessions"
    echo "  a2a-chatting.sh get-session <session_id>"
}

# Main
COMMAND="$1"

case "$COMMAND" in
    config)
        cmd_config "$2" "$3"
        ;;
    get-agents)
        cmd_get_agents
        ;;
    new-session)
        cmd_new_session "$2" "$3"
        ;;
    list-sessions)
        cmd_list_sessions
        ;;
    get-session)
        cmd_get_session "$2"
        ;;
    delete-session)
        cmd_delete_session "$2"
        ;;
    help|--help|-h)
        show_help
        ;;
    *)
        if [[ -z "$COMMAND" ]]; then
            show_help
        else
            echo -e "REDUnknown command: $COMMANDNC"
            show_help
        fi
        exit 1
        ;;
esac