peter/devclaw-gitea
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dc3a7fcf9e59fd3f7243c77b91eddf75873ce5b6
devclaw-gitea/docs/TOOLS.md
Claude 9d1e253f11 docs: remove auto-chaining, reframe around scheduling system 
Auto-chaining was removed from the codebase. All docs now describe the
scheduling model: work_finish transitions labels, the heartbeat's tick
pass (which also fires immediately after every work_finish) detects
available work and fills free slots. Removed autoChain config references.

Files updated: README.md, README2.md, docs/TOOLS.md, ARCHITECTURE.md,
ROADMAP.md, MANAGEMENT.md, ONBOARDING.md, lib/templates.ts

https://claude.ai/code/session_01R3rGevPY748gP4uK2ggYag
2026-02-11 04:20:25 +00:00

362 lines
13 KiB
Markdown
Raw Blame History

# DevClaw — Tools Reference
Complete reference for all 11 tools registered by DevClaw. See [`index.ts`](../index.ts) for registration.
## Worker Lifecycle
### `work_start`
Pick up a task from the issue queue. Handles level assignment, label transition, session creation/reuse, task dispatch, and audit logging — all in one call.
**Source:** [`lib/tools/work-start.ts`](../lib/tools/work-start.ts)
**Context:** Only works in project group chats.
**Parameters:**
| Parameter | Type | Required | Description |
|---|---|---|---|
| `issueId` | number | No | Issue ID. If omitted, picks next by priority. |
| `role` | `"dev"` \| `"qa"` | No | Worker role. Auto-detected from issue label if omitted. |
| `projectGroupId` | string | No | Project group ID. Auto-detected from group context. |
| `level` | string | No | Developer level (`junior`, `medior`, `senior`, `reviewer`). Auto-detected if omitted. |
**What it does atomically:**
1. Resolves project from `projects.json`
2. Validates no active worker for this role
3. Fetches issue from tracker, verifies correct label state
4. Assigns level (LLM-chosen via `level` param → label detection → keyword heuristic fallback)
5. Resolves level to model ID via config or defaults
6. Loads prompt instructions from `projects/roles/<project>/<role>.md`
7. Looks up existing session for assigned level (session-per-level)
8. Transitions label (e.g. `To Do` → `Doing`)
9. Creates session via Gateway RPC if new (`sessions.patch`)
10. Dispatches task to worker session via CLI (`openclaw gateway call agent`)
11. Updates `projects.json` state (active, issueId, level, session key)
12. Writes audit log entries (work_start + model_selection)
13. Sends notification
14. Returns announcement text
**Level selection priority:**
1. `level` parameter (LLM-selected) — highest priority
2. Issue label (e.g. a label named "junior" or "senior")
3. Keyword heuristic from `model-selector.ts` — fallback
**Execution guards:**
- Rejects if role already has an active worker
- Respects `roleExecution` (sequential: rejects if other role is active)
**On failure:** Rolls back label transition. No orphaned state.
---
### `work_finish`
Complete a task with a result. Called by workers (DEV/QA sub-agent sessions) directly, or by the orchestrator.
**Source:** [`lib/tools/work-finish.ts`](../lib/tools/work-finish.ts)
**Parameters:**
| Parameter | Type | Required | Description |
|---|---|---|---|
| `role` | `"dev"` \| `"qa"` | Yes | Worker role |
| `result` | string | Yes | Completion result (see table below) |
| `projectGroupId` | string | Yes | Project group ID |
| `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 |
|---|---|---|---|
| DEV | `"done"` | Doing → To Test | git pull, auto-detect PR URL |
| DEV | `"blocked"` | Doing → To Do | Task returns to queue |
| QA | `"pass"` | Testing → Done | Issue closed |
| QA | `"fail"` | Testing → To Improve | Issue reopened |
| QA | `"refine"` | Testing → Refining | Awaits human decision |
| QA | `"blocked"` | Testing → To Test | Task returns to QA queue |
**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 Test` 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/task-create.ts`](../lib/tools/task-create.ts)
**Parameters:**
| Parameter | Type | Required | Description |
|---|---|---|---|
| `projectGroupId` | string | Yes | Project group ID |
| `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 DEV 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_update`
Change an issue's state label manually without going through the full pickup/complete flow.
**Source:** [`lib/tools/task-update.ts`](../lib/tools/task-update.ts)
**Parameters:**
| Parameter | Type | Required | Description |
|---|---|---|---|
| `projectGroupId` | string | Yes | Project group ID |
| `issueId` | number | Yes | Issue ID to update |
| `state` | StateLabel | Yes | New state label |
| `reason` | string | No | Audit log reason for the change |
**Valid states:** `Planning`, `To Do`, `Doing`, `To Test`, `Testing`, `Done`, `To Improve`, `Refining`
**Use cases:**
- Manual state adjustments (e.g. `Planning → To Do` after approval)
- Failed auto-transitions that need correction
- Bulk state changes by orchestrator
---
### `task_comment`
Add a comment to an issue for feedback, notes, or discussion.
**Source:** [`lib/tools/task-comment.ts`](../lib/tools/task-comment.ts)
**Parameters:**
| Parameter | Type | Required | Description |
|---|---|---|---|
| `projectGroupId` | string | Yes | Project group ID |
| `issueId` | number | Yes | Issue ID to comment on |
| `body` | string | Yes | Comment body (markdown) |
| `authorRole` | `"dev"` \| `"qa"` \| `"orchestrator"` | No | Attribution role prefix |
**Use cases:**
- QA adds review feedback before pass/fail decision
- DEV 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.
---
## Operations
### `status`
Lightweight queue + worker state dashboard.
**Source:** [`lib/tools/status.ts`](../lib/tools/status.ts)
**Context:** Auto-filters to project in group chats. Shows all projects in DMs.
**Parameters:**
| Parameter | Type | Required | Description |
|---|---|---|---|
| `projectGroupId` | string | No | Filter to specific project. Omit for all. |
**Returns per project:**
- Worker state: active/idle, current issue, level, start time
- Queue counts: To Do, To Test, To Improve
- Role execution mode
---
### `health`
Worker health scan with optional auto-fix.
**Source:** [`lib/tools/health.ts`](../lib/tools/health.ts)
**Context:** Auto-filters to project in group chats.
**Parameters:**
| Parameter | Type | Required | Description |
|---|---|---|---|
| `projectGroupId` | string | No | Filter to specific project. 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 |
---
### `work_heartbeat`
Manual trigger for heartbeat: health fix + queue dispatch. Same logic as the background heartbeat service, but invoked on demand.
**Source:** [`lib/tools/work-heartbeat.ts`](../lib/tools/work-heartbeat.ts)
**Parameters:**
| Parameter | Type | Required | Description |
|---|---|---|---|
| `projectGroupId` | string | No | Target single project. Omit for all. |
| `dryRun` | boolean | No | Report only, don't dispatch. Default: `false`. |
| `maxPickups` | number | No | Max worker dispatches per tick. |
| `activeSessions` | string[] | No | Active session IDs for zombie detection. |
**Two-pass sweep:**
1. **Health pass** — Runs `checkWorkerHealth` per project per role. Auto-fixes zombies, stale workers, orphaned state.
2. **Tick pass** — Calls `projectTick` per project. Fills free worker slots by priority (To Improve > To Test > To Do).
**Execution guards:**
- `projectExecution: "sequential"` — only one project active at a time
- `roleExecution: "sequential"` — only one role (DEV or QA) active at a time per project (enforced in `projectTick`)
---
## Setup
### `project_register`
One-time project setup. Creates state labels, scaffolds prompt files, adds project to state.
**Source:** [`lib/tools/project-register.ts`](../lib/tools/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 | DEV/QA 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 8 state labels (idempotent — safe to run again)
5. Adds project entry to `projects.json` with empty worker state
- DEV sessions: `{ junior: null, medior: null, senior: null }`
- QA sessions: `{ reviewer: null, tester: null }`
6. Scaffolds prompt files: `projects/roles/<project>/dev.md` and `qa.md`
7. Writes audit log
---
### `setup`
Agent + workspace initialization.
**Source:** [`lib/tools/setup.ts`](../lib/tools/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#model-tiers)) |
| `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, `projects/projects.json`
5. Configures model tiers in `openclaw.json`
---
### `onboard`
Conversational onboarding guide. Returns step-by-step instructions for the agent to walk the user through setup.
**Source:** [`lib/tools/onboard.ts`](../lib/tools/onboard.ts)
**Context:** Works in DMs and via-agent. Blocks group chats (setup should not happen in project groups).
**Parameters:**
| Parameter | Type | Required | Description |
|---|---|---|---|
| `mode` | `"first-run"` \| `"reconfigure"` | No | Auto-detected from current state |
**Flow:**
1. Call `onboard` — returns QA-style step-by-step instructions
2. Agent walks user through: agent selection, channel binding, model tiers
3. Agent calls `setup` with collected answers
4. User registers projects via `project_register` in group chats
---
## Completion Rules Reference
The pipeline service (`lib/services/pipeline.ts`) defines declarative completion rules:
```
dev:done → Doing → To Test (git pull, detect PR)
dev:blocked → Doing → To Do (return to queue)
qa:pass → Testing → Done (close issue)
qa:fail → Testing → To Improve (reopen issue)
qa:refine → Testing → Refining (await human decision)
qa:blocked → Testing → To Test (return to QA queue)
```
## Issue Priority Order
When the heartbeat or `work_heartbeat` fills free worker slots, issues are prioritized:
1. **To Improve** — QA failures get fixed first (highest priority)
2. **To Test** — Completed DEV work gets reviewed next
3. **To Do** — Fresh tasks are picked up last
This ensures the pipeline clears its backlog before starting new work.
Reference in New Issue View Git Blame Copy Permalink