# DevClaw — Tools Reference

Complete reference for all tools registered by DevClaw. See [`index.ts`](../index.ts) for registration.

## Task Lifecycle

### `task_start`

Advance an issue to the next queue. State-agnostic — works from any HOLD or QUEUE state. The heartbeat handles actual dispatch on its next cycle.

**Source:** [`lib/tools/tasks/task-start.ts`](../lib/tools/tasks/task-start.ts)

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `projectSlug` | string | Yes | Project slug (e.g. 'my-webapp') |
| `issueId` | number | Yes | Issue ID to advance |
| `level` | string | No | Level hint (`junior`, `medior`, `senior`). Applied as a role:level label. |

**Behavior by current state type:**

| State type | Action | Example |
|---|---|---|
| HOLD (Planning, Refining) | Follows APPROVE transition to target queue | Planning → To Do |
| QUEUE (To Do, To Improve, etc.) | No-op (already queued), applies level if provided | Stays in To Do |
| ACTIVE (Doing, Reviewing, etc.) | Error — already being worked on | — |
| TERMINAL (Done, Rejected) | Error — cannot start | — |

**Level hint:** If `level` is provided, a `role:level` label is applied (e.g. `developer:senior`). The heartbeat respects this when dispatching.

---

### `work_finish`

Complete a task with a result. Called by workers (DEVELOPER/TESTER/ARCHITECT sub-agent sessions) directly, or by the orchestrator.

**Source:** [`lib/tools/worker/work-finish.ts`](../lib/tools/worker/work-finish.ts)

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `role` | `"developer"` \| `"tester"` \| `"architect"` \| `"reviewer"` | Yes | Worker role |
| `result` | string | Yes | Completion result (see table below) |
| `projectSlug` | string | Yes | Project slug (e.g. 'my-webapp') |
| `summary` | string | No | Brief summary for the announcement |
| `prUrl` | string | No | PR/MR URL (auto-detected if omitted) |

**Valid results by role:**

| Role | Result | Label transition | Side effects |
|---|---|---|---|
| developer | `"done"` | Doing → To Review | auto-detect PR URL. Heartbeat polls PR status. |
| developer | `"blocked"` | Doing → Refining | Awaits human decision |
| reviewer | `"approve"` | Reviewing → Done | merge PR, git pull, close issue |
| reviewer | `"reject"` | Reviewing → To Improve | Sent back to developer |
| reviewer | `"blocked"` | Reviewing → Refining | Awaits human decision |
| tester | `"pass"` | Testing → Done | Issue closed (only when test phase enabled) |
| tester | `"fail"` | Testing → To Improve | Issue reopened (only when test phase enabled) |
| tester | `"refine"` | Testing → Refining | Awaits human decision |
| tester | `"blocked"` | Testing → Refining | Awaits human decision |
| architect | `"done"` | Researching → Done | Research complete, implementation tasks created |
| architect | `"blocked"` | Researching → Refining | Awaits human decision |

**What it does atomically:**

1. Validates role:result combination
2. Resolves project and active worker
3. Executes completion via pipeline service (label transition + side effects)
4. Deactivates worker (sessions map preserved for reuse)
5. Sends notification
6. Ticks queue to fill free worker slots
7. Writes audit log

**Scheduling:** After completion, `work_finish` ticks the queue. The scheduler sees the new label (`To Review` or `To Improve`) and dispatches the next worker if a slot is free.

---

## Task Management

### `task_create`

Create a new issue in the project's issue tracker.

**Source:** [`lib/tools/tasks/task-create.ts`](../lib/tools/tasks/task-create.ts)

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `projectSlug` | string | Yes | Project slug (e.g. 'my-webapp') |
| `title` | string | Yes | Issue title |
| `description` | string | No | Full issue body (markdown) |
| `label` | StateLabel | No | State label. Defaults to `"Planning"`. |
| `assignees` | string[] | No | GitHub/GitLab usernames to assign |
| `pickup` | boolean | No | If true, immediately pick up for DEVELOPER after creation |

**Use cases:**

- Orchestrator creates tasks from chat messages
- Workers file follow-up bugs discovered during development
- Breaking down epics into smaller tasks

**Default behavior:** Creates issues in `"Planning"` state. Only use `"To Do"` when the user explicitly requests immediate work.

---

### `task_set_level`

Set the developer level hint on a HOLD-state issue (Planning, Refining).

**Source:** [`lib/tools/tasks/task-set-level.ts`](../lib/tools/tasks/task-set-level.ts)

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `projectSlug` | string | Yes | Project slug (e.g. 'my-webapp') |
| `issueId` | number | Yes | Issue ID to update |
| `level` | string | Yes | The role:level hint (e.g. 'senior', 'junior') |
| `reason` | string | No | Audit log reason for the change |

Only works on issues in HOLD states (Planning, Refining). The level is applied as a `role:level` label and respected by the heartbeat when the issue is later advanced via `task_start`.

**Use cases:**

- Override assigned level before advancing (e.g. set to senior for complex task)
- Pre-set level on held issues before `task_start` moves them to the queue

---

### `task_comment`

Add a comment to an issue for feedback, notes, or discussion.

**Source:** [`lib/tools/tasks/task-comment.ts`](../lib/tools/tasks/task-comment.ts)

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `projectSlug` | string | Yes | Project slug (e.g. 'my-webapp') |
| `issueId` | number | Yes | Issue ID to comment on |
| `body` | string | Yes | Comment body (markdown) |
| `authorRole` | `"developer"` \| `"tester"` \| `"architect"` \| `"reviewer"` \| `"orchestrator"` | No | Attribution role prefix |

**Use cases:**

- TESTER adds review feedback before pass/fail decision
- DEVELOPER posts implementation notes or progress updates
- Orchestrator adds summary comments

When `authorRole` is provided, the comment is prefixed with a role emoji and attribution label.

### `task_edit_body`

Update issue title and/or description. Only allowed when the issue is in the initial workflow state (e.g. "Planning") or an active architect state (e.g. "Researching"). Prevents editing in-progress work.

**Source:** [`lib/tools/tasks/task-edit-body.ts`](../lib/tools/tasks/task-edit-body.ts)

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `projectSlug` | string | Yes | Project slug |
| `issueId` | number | Yes | Issue ID to edit |
| `title` | string | No | New title for the issue |
| `body` | string | No | New body/description for the issue |
| `reason` | string | No | Why the edit was made (for audit trail) |
| `addComment` | boolean | No | Post an auto-comment noting the edit. Default: `true`. |

At least one of `title` or `body` must be provided.

**Audit:** Logs the edit with timestamp, caller, and a diff summary. Optionally posts an auto-comment on the issue for traceability.

---

### `task_owner`

Claim issue ownership for this instance. Adds an `owner:{instanceName}` label so this instance owns the issue for queue scanning and dispatch. Supports claiming a single issue or all unclaimed queued issues.

**Source:** [`lib/tools/tasks/task-owner.ts`](../lib/tools/tasks/task-owner.ts)

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `channelId` | string | Yes | Current chat/group ID |
| `projectSlug` | string | No | Project slug (resolved from channel if omitted) |
| `issueId` | number | No | Specific issue to claim. Omit to claim all unclaimed queued issues. |
| `force` | boolean | No | Transfer ownership from another instance. Default: `false`. |

**Use cases:**

- Multi-instance deployments where each instance handles a subset of issues
- Transfer ownership of an issue between instances

---

## Operations

### `tasks_status`

Full project dashboard showing all non-terminal state types with issue details.

**Source:** [`lib/tools/tasks/tasks-status.ts`](../lib/tools/tasks/tasks-status.ts)

**Context:** Auto-filters to project in group chats. Shows all projects in DMs.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `projectSlug` | string | No | Filter to specific project. Omit for all. |

**Returns per project:**

- **hold** — Waiting for input (Planning, Refining): issue IDs, titles, URLs
- **active** — Work in progress (Doing, Reviewing, etc.): issue IDs, titles, URLs
- **queue** — Queued for work (To Do, To Improve, To Review): issue IDs, titles, URLs
- Worker state per role: active/idle, current issue, level, start time
- Active workflow summary: review policy, test phase status, state flow
- Summary totals: `totalHold`, `totalActive`, `totalQueued`

---

### `project_status`

Instant local project info for the current channel. Returns registration details, channel bindings, worker slot states, workflow config, and execution settings — all from local data, no issue tracker API calls.

**Source:** [`lib/tools/admin/project-status.ts`](../lib/tools/admin/project-status.ts)

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `channelId` | string | Yes | Current chat/group ID |

**Returns:**

- Project registration: name, repo, base branch, deploy URL, provider
- Channel bindings: linked channels with types
- Worker slots: per-role active/idle state, current issue, level
- Workflow config: review policy, test phase, state flow
- Execution settings: role execution mode

**Use cases:**

- Quick check of project setup without querying the issue tracker
- Verify channel bindings and worker slot configuration
- Use `tasks_status` instead when you need live issue counts from the tracker

---

### `task_list`

Browse and search issues by workflow state. Returns individual issues grouped by state label.

**Source:** [`lib/tools/tasks/task-list.ts`](../lib/tools/tasks/task-list.ts)

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `projectSlug` | string | Yes | Project slug |
| `stateType` | `"queue"` \| `"active"` \| `"hold"` \| `"terminal"` \| `"all"` | No | Filter by state type. Default: all non-terminal. |
| `label` | string | No | Specific state label (e.g. `"Planning"`, `"Done"`). Overrides `stateType`. |
| `search` | string | No | Text search in issue titles (case-insensitive). |
| `limit` | number | No | Max issues per state. Default: 20. |

**Returns per matching state:**

- State label, type, and role
- Issue list: ID, title, URL
- Total count (before limit)

**Use cases:**

- Browse all issues in Planning: `{ projectSlug: "my-app", label: "Planning" }`
- Find blocked work: `{ projectSlug: "my-app", stateType: "hold" }`
- Search across queues: `{ projectSlug: "my-app", stateType: "queue", search: "auth" }`
- View completed work: `{ projectSlug: "my-app", stateType: "terminal" }`

**Note:** When browsing terminal states (Done), the tool queries closed issues from the provider.

---

### `health`

Worker health scan with optional auto-fix.

**Source:** [`lib/tools/admin/health.ts`](../lib/tools/admin/health.ts)

**Context:** Auto-filters to project in group chats.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `projectSlug` | string | No | Project slug. Omit for all. |
| `fix` | boolean | No | Apply fixes for detected issues. Default: `false` (read-only). |
| `activeSessions` | string[] | No | Active session IDs for zombie detection. |

**Health checks:**

| Issue | Severity | Detection | Auto-fix |
|---|---|---|---|
| Active worker with no session key | Critical | `active=true` but no session in map | Deactivate worker |
| Active worker whose session is dead | Critical | Session key not in active sessions list | Deactivate worker, revert label |
| Worker active >2 hours | Warning | `startTime` older than 2h | Deactivate worker, revert label to queue |
| Inactive worker with lingering issue ID | Warning | `active=false` but `issueId` still set | Clear issueId |

---

## Setup

### `project_register`

One-time project setup. Creates state labels, scaffolds project directory with override instructions, adds project to state.

**Source:** [`lib/tools/admin/project-register.ts`](../lib/tools/admin/project-register.ts)

**Context:** Only works in the Telegram/WhatsApp group being registered.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `projectGroupId` | string | No | Auto-detected from current group if omitted |
| `name` | string | Yes | Short project name (e.g. `my-webapp`) |
| `repo` | string | Yes | Path to git repo (e.g. `~/git/my-project`) |
| `groupName` | string | No | Display name. Defaults to `Project: {name}`. |
| `baseBranch` | string | Yes | Base branch for development |
| `deployBranch` | string | No | Deploy branch. Defaults to baseBranch. |
| `deployUrl` | string | No | Deployment URL |
| `roleExecution` | `"parallel"` \| `"sequential"` | No | DEVELOPER/TESTER parallelism. Default: `"parallel"`. |

**What it does atomically:**

1. Validates project not already registered
2. Resolves repo path, auto-detects GitHub/GitLab from git remote
3. Verifies provider health (CLI installed and authenticated)
4. Creates all state labels (idempotent — safe to run again)
5. Adds project entry to `projects.json` with empty worker state for all registered roles
6. Scaffolds project directory with `prompts/` folder and `README.md` explaining prompt and workflow overrides
7. Writes audit log

---

### `setup`

Agent + workspace initialization.

**Source:** [`lib/tools/admin/setup.ts`](../lib/tools/admin/setup.ts)

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `newAgentName` | string | No | Create a new agent. Omit to configure current workspace. |
| `channelBinding` | `"telegram"` \| `"whatsapp"` | No | Channel to bind (with `newAgentName` only) |
| `migrateFrom` | string | No | Agent ID to migrate channel binding from |
| `models` | object | No | Model overrides per role and level (see [Configuration](CONFIGURATION.md#role-configuration)) |
| `projectExecution` | `"parallel"` \| `"sequential"` | No | Project execution mode |

**What it does:**

1. Creates a new agent or configures existing workspace
2. Optionally binds messaging channel (Telegram/WhatsApp)
3. Optionally migrates channel binding from another agent
4. Writes workspace files: AGENTS.md, HEARTBEAT.md, IDENTITY.md, TOOLS.md, SOUL.md, `devclaw/projects.json`, `devclaw/workflow.yaml`
5. Scaffolds default prompt files for all roles

---

### `onboard`

Conversational onboarding guide. Returns step-by-step instructions for the agent to walk the user through setup.

**Source:** [`lib/tools/admin/onboard.ts`](../lib/tools/admin/onboard.ts)

**Note:** Call this before `setup` to get step-by-step guidance.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `mode` | `"first-run"` \| `"reconfigure"` | No | Auto-detected from current state |

---

### `workflow_guide`

Reference guide for workflow configuration. Call before making any workflow changes.

**Source:** [`lib/tools/admin/workflow-guide.ts`](../lib/tools/admin/workflow-guide.ts)

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `topic` | string | No | Narrow to: `overview`, `states`, `roles`, `review`, `testing`, `timeouts`, `overrides`. Omit for full guide. |

**Returns:** Comprehensive documentation about the workflow config structure, valid values (enums vs free-form), config layer system, and common customization recipes.

**Use cases:**

- User asks to change review policy → call `workflow_guide` first, then edit `workflow.yaml`
- User asks to enable test phase → call `workflow_guide("testing")` for step-by-step
- User asks about config options → call `workflow_guide("overview")` for the full picture

---

### `research_task`

Spawn an architect for a design investigation. Creates a `To Research` issue with rich context and dispatches an architect worker through `To Research` → `Researching` states.

**Source:** [`lib/tools/tasks/research-task.ts`](../lib/tools/tasks/research-task.ts)

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `projectSlug` | string | Yes | Project slug (e.g. 'my-webapp') |
| `title` | string | Yes | Design task title |
| `description` | string | Yes | Detailed background context for the architect |
| `focusAreas` | string[] | No | Specific areas to investigate |
| `complexity` | `"simple"` \| `"medium"` \| `"complex"` | No | Guides level selection. Default: `"medium"`. |

---

## Completion Rules Reference

The pipeline service (`lib/services/pipeline.ts`) derives completion rules from the workflow config.

**Default flow (human review, no test phase):**

```
developer:done    → Doing     → To Review    (detect PR, heartbeat polls PR status)
developer:blocked → Doing     → Refining     (awaits human decision)
reviewer:approve  → Reviewing → Done         (merge PR, git pull, close issue)
reviewer:reject   → Reviewing → To Improve   (sent back to developer)
reviewer:blocked  → Reviewing → Refining     (awaits human decision)
architect:done    → Researching → Done          (research complete, implementation tasks created)
architect:blocked → Researching → Refining     (awaits human decision)
```

**With test phase enabled:**

```
tester:pass       → Testing   → Done         (close issue)
tester:fail       → Testing   → To Improve   (reopen issue)
tester:refine     → Testing   → Refining     (awaits human decision)
tester:blocked    → Testing   → Refining     (awaits human decision)
```

**Heartbeat auto-transitions (on "To Review" state):**

```
PR approved       → To Review → Done         (merge PR, git pull, close issue)
PR comments       → To Review → To Improve   (developer fixes)
Merge conflict    → To Review → To Improve   (developer resolves)
```

## Issue Priority Order

When the heartbeat fills free worker slots, issues are prioritized:

1. **To Improve** — Review failures get fixed first (highest priority)
2. **To Review** — Completed developer work awaits review (priority 2)
3. **To Do** — Fresh tasks are picked up last

This ensures the pipeline clears its backlog before starting new work.

---

## Maintenance

### `sync_labels`

Sync GitHub/GitLab labels with the current workflow config. Creates any missing state labels, role:level labels, and step routing labels from the resolved (three-layer merged) config.

**Source:** [`lib/tools/admin/sync-labels.ts`](../lib/tools/admin/sync-labels.ts)

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `projectSlug` | string | No | Project slug to sync. Omit to sync all registered projects. |

**What it does:**

1. Loads the resolved workflow config (built-in → workspace → project)
2. Derives all required labels: state labels, role:level labels, step routing labels
3. Creates any missing labels on the GitHub/GitLab repo via the provider
4. Reports created vs. already-existing labels

**When to use:** After editing `workflow.yaml` to add custom states, change label names, or enable the test phase.

---

### `channel_link`

Link a chat/channel to a project. If the channel is already linked to a different project, the old bond is removed first (auto-detach).

**Source:** [`lib/tools/admin/channel-link.ts`](../lib/tools/admin/channel-link.ts)

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `channelId` | string | Yes | Chat/group ID to link |
| `project` | string | Yes | Project name or slug to link to |

**Use cases:**

- Connect a new chat to an existing project
- Switch which project a chat controls

---

### `channel_unlink`

Remove a channel from a project. Validates that the channel exists and prevents removing the last channel (projects must have at least one notification endpoint).

**Source:** [`lib/tools/admin/channel-unlink.ts`](../lib/tools/admin/channel-unlink.ts)

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `channelId` | string | Yes | Channel ID to remove |
| `project` | string | Yes | Project name or slug |

---

### `channel_list`

List channels for a project or all projects. Shows channel type, ID, name, and event subscriptions.

**Source:** [`lib/tools/admin/channel-list.ts`](../lib/tools/admin/channel-list.ts)

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `project` | string | No | Project name or slug. Omit to list channels for all projects. |

---

### `config`

Manage DevClaw workspace configuration. Supports three actions: reset config files to defaults, diff against defaults, and show version info.

**Source:** [`lib/tools/admin/config.ts`](../lib/tools/admin/config.ts)

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `action` | `"reset"` \| `"diff"` \| `"version"` | Yes | Action to perform |
| `scope` | `"prompts"` \| `"workflow"` \| `"all"` | No | Reset scope (only for `action: "reset"`) |

**Actions:**

| Action | Description |
|---|---|
| `reset` | Reset config files to package defaults. Creates `.bak` backups. Use `scope` to target: `prompts` (role prompts only), `workflow` (workflow.yaml only), `all` (everything). |
| `diff` | Show differences between current `workflow.yaml` and the built-in default template. Helps identify customizations and see what changed in new versions. |
| `version` | Show DevClaw package version and workspace tracked version. |