peter/devclaw-gitea
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: overhaul documentation for consistency with implementation

Browse Source 
Complete documentation rewrite to match the current codebase:

- README: add benefits section (process consistency, token savings with
  estimates, project isolation, continuous planning, feedback loops,
  role-based prompts, atomic operations, audit trail), task workflow
  with state diagram, model-to-role mapping tables, installation guide
- New TOOLS.md: complete reference for all 11 tools with parameters,
  behavior, and execution guards
- New CONFIGURATION.md: full config reference for openclaw.json,
  projects.json, heartbeat, notifications, workspace layout
- Fix tool names across all docs: task_pickup→work_start,
  task_complete→work_finish
- Fix tier model: QA has reviewer/tester levels, not flat "qa"
- Fix config schema: nested models.dev.*/models.qa.* structure
- Fix prompt path: projects/roles/ not projects/prompts/
- Fix worker state: uses "level" field not "model"/"tier"
- Fix MANAGEMENT.md: remove incorrect model references
- Fix TESTING.md: update model config example to nested structure
- Remove VERIFICATION.md (one-off checklist, no longer needed)
- Add cross-references between all docs pages

https://claude.ai/code/session_01R3rGevPY748gP4uK2ggYag
This commit is contained in:
Claude
2026-02-10 20:13:22 +00:00
parent ead4807797
commit 553efcc146
11 changed files with 1388 additions and 897 deletions
Download Patch File Download Diff File Expand all files Collapse all files

173
docs/ONBOARDING.md
View File

@@ -1,18 +1,18 @@
# DevClaw — Onboarding Guide
## What you need before starting
Step-by-step setup: install the plugin, configure an agent, register projects, and run your first task.
## Prerequisites
| Requirement | Why | How to check |
|---|---|---|
| [OpenClaw](https://openclaw.ai) installed | DevClaw is an OpenClaw plugin | `openclaw --version` |
| Node.js >= 20 | Runtime for plugin | `node --version` |
| [`glab`](https://gitlab.com/gitlab-org/cli) or [`gh`](https://cli.github.com) CLI | Issue tracker provider (auto-detected from remote) | `glab --version` or `gh --version` |
| CLI authenticated | Plugin calls glab/gh for every label transition | `glab auth status` or `gh auth status` |
| A GitLab/GitHub repo with issues | The task backlog lives in the issue tracker | `glab issue list` or `gh issue list` from your repo |
| [`gh`](https://cli.github.com) or [`glab`](https://gitlab.com/gitlab-org/cli) CLI | Issue tracker provider (auto-detected from git remote) | `gh --version` or `glab --version` |
| CLI authenticated | Plugin calls gh/glab for every label transition | `gh auth status` or `glab auth status` |
| A GitHub/GitLab repo with issues | The task backlog lives in the issue tracker | `gh issue list` or `glab issue list` from your repo |
## Setup
### 1. Install the plugin
## Step 1: Install the plugin
```bash
# Copy to extensions directory (auto-discovered on next restart)
@@ -25,21 +25,21 @@ openclaw plugins list
# Should show: DevClaw | devclaw | loaded
```
### 2. Run setup
## Step 2: Run setup
There are three ways to set up DevClaw:
#### Option A: Conversational onboarding (recommended)
### Option A: Conversational onboarding (recommended)
Call the `devclaw_onboard` tool from any agent that has the DevClaw plugin loaded. The agent will walk you through configuration step by step — asking about:
Call the `onboard` tool from any agent that has the DevClaw plugin loaded. The agent walks you through configuration step by step — asking about:
- Agent selection (current or create new)
- Channel binding (telegram/whatsapp/none) — for new agents only
- Model tiers (accept defaults or customize)
- Model levels (accept defaults or customize)
- Optional project registration
The tool returns instructions that guide the agent through the QA-style setup conversation.
#### Option B: CLI wizard
### Option B: CLI wizard
```bash
openclaw devclaw setup
@@ -48,12 +48,13 @@ openclaw devclaw setup
The setup wizard walks you through:
1. **Agent** — Create a new orchestrator agent or configure an existing one
2. **Developer team** — Choose which LLM model powers each developer tier:
- **Junior** (fast, cheap tasks) — default: `anthropic/claude-haiku-4-5`
- **Medior** (standard tasks) — default: `anthropic/claude-sonnet-4-5`
- **Senior** (complex tasks) — default: `anthropic/claude-opus-4-5`
- **QA** (code review) — default: `anthropic/claude-sonnet-4-5`
3. **Workspace** — Writes AGENTS.md, HEARTBEAT.md, role templates, and initializes memory
2. **Developer team** — Choose which LLM model powers each developer level:
- **DEV junior** (fast, cheap tasks) — default: `anthropic/claude-haiku-4-5`
- **DEV medior** (standard tasks) — default: `anthropic/claude-sonnet-4-5`
- **DEV senior** (complex tasks) — default: `anthropic/claude-opus-4-5`
- **QA reviewer** (code review) — default: `anthropic/claude-sonnet-4-5`
- **QA tester** (manual testing) — default: `anthropic/claude-haiku-4-5`
3. **Workspace** — Writes AGENTS.md, HEARTBEAT.md, role templates, and initializes state
Non-interactive mode:
```bash
@@ -66,45 +67,45 @@ openclaw devclaw setup --agent my-orchestrator \
--senior "anthropic/claude-opus-4-5"
```
#### Option C: Tool call (agent-driven)
### Option C: Tool call (agent-driven)
**Conversational onboarding via tool:**
```json
devclaw_onboard({ mode: "first-run" })
onboard({ "mode": "first-run" })
```
The tool returns step-by-step instructions that guide the agent through the QA-style setup conversation.
The tool returns step-by-step instructions that guide the agent through the setup conversation.
**Direct setup (skip conversation):**
```json
{
setup({
"newAgentName": "My Dev Orchestrator",
"channelBinding": "telegram",
"models": {
"junior": "anthropic/claude-haiku-4-5",
"senior": "anthropic/claude-opus-4-5"
"dev": {
"junior": "anthropic/claude-haiku-4-5",
"senior": "anthropic/claude-opus-4-5"
},
"qa": {
"reviewer": "anthropic/claude-sonnet-4-5"
}
}
}
})
```
This calls `devclaw_setup` directly without conversational prompts.
## Step 3: Channel binding (optional, for new agents)
### 3. Channel binding (optional, for new agents)
If you created a new agent during conversational onboarding and selected a channel binding (telegram/whatsapp), the agent is automatically bound and will receive messages from that channel. **Skip to step 4.**
If you created a new agent during conversational onboarding and selected a channel binding (telegram/whatsapp), the agent is automatically bound. **Skip to step 4.**
**Smart Migration**: If an existing agent already has a channel-wide binding (e.g., the old orchestrator receives all telegram messages), the onboarding agent will:
1. Call `analyze_channel_bindings` to detect the conflict
1. Detect the conflict
2. Ask if you want to migrate the binding from the old agent to the new one
3. If you confirm, the binding is automatically moved — no manual config edit needed
This is useful when you're replacing an old orchestrator with a new one.
If you didn't bind a channel during setup:
If you didn't bind a channel during setup, you have two options:
**Option A: Manually edit `openclaw.json`**
**Option A: Manually edit `openclaw.json`** (for existing agents or post-creation binding)
Add an entry to the `bindings` array:
```json
{
"bindings": [
@@ -136,131 +137,115 @@ Restart OpenClaw after editing.
**Option B: Add bot to Telegram/WhatsApp group**
If using a channel-wide binding (no peer filter), the agent will receive all messages from that channel. Add your orchestrator bot to the relevant Telegram group for the project.
If using a channel-wide binding (no peer filter), the agent receives all messages from that channel. Add your orchestrator bot to the relevant Telegram group.
### 4. Register your project
## Step 4: Register your project
Tell the orchestrator agent to register a new project:
Go to the Telegram/WhatsApp group for the project and tell the orchestrator agent:
> "Register project my-project at ~/git/my-project for group -1234567890 with base branch development"
> "Register project my-project at ~/git/my-project with base branch development"
The agent calls `project_register`, which atomically:
- Validates the repo and auto-detects GitHub/GitLab from remote
- Creates all 8 state labels (idempotent)
- Scaffolds prompt instruction files (`projects/prompts/<project>/dev.md` and `qa.md`)
- Adds the project entry to `projects.json` with `autoChain: false`
- Scaffolds role instruction files (`projects/roles/<project>/dev.md` and `qa.md`)
- Adds the project entry to `projects.json`
- Logs the registration event
**Initial state in `projects.json`:**
```json
{
"projects": {
"-1234567890": {
"name": "my-project",
"repo": "~/git/my-project",
"groupName": "Dev - My Project",
"deployUrl": "",
"groupName": "Project: my-project",
"baseBranch": "development",
"deployBranch": "development",
"autoChain": false,
"channel": "telegram",
"roleExecution": "parallel",
"dev": {
"active": false,
"issueId": null,
"startTime": null,
"model": null,
"level": null,
"sessions": { "junior": null, "medior": null, "senior": null }
},
"qa": {
"active": false,
"issueId": null,
"startTime": null,
"model": null,
"sessions": { "qa": null }
"level": null,
"sessions": { "reviewer": null, "tester": null }
}
}
}
}
```
**Manual fallback:** If you prefer CLI control, you can still create labels manually with `glab label create` and edit `projects.json` directly. See the [Architecture docs](ARCHITECTURE.md) for label names and colors.
**Finding the Telegram group ID:** The group ID is the numeric ID of your Telegram supergroup (a negative number like `-1234567890`). When you call `project_register` from within the group, the ID is auto-detected from context.
**Finding the Telegram group ID:** The group ID is the numeric ID of your Telegram supergroup (a negative number like `-1234567890`). You can find it via the Telegram bot API or from message metadata in OpenClaw logs.
### 5. Create your first issue
## Step 5: Create your first issue
Issues can be created in multiple ways:
- **Via the agent** — Ask the orchestrator in the Telegram group: "Create an issue for adding a login page" (uses `task_create`)
- **Via workers** — DEV/QA workers can call `task_create` to file follow-up bugs they discover
- **Via CLI** — `cd ~/git/my-project && glab issue create --title "My first task" --label "To Do"` (or `gh issue create`)
- **Via CLI** — `cd ~/git/my-project && gh issue create --title "My first task" --label "To Do"` (or `glab issue create`)
- **Via web UI** — Create an issue and add the "To Do" label
### 6. Test the pipeline
Note: `task_create` defaults to the "Planning" label. Use "To Do" explicitly when the task is ready for immediate work.
## Step 6: Test the pipeline
Ask the agent in the Telegram group:
> "Check the queue status"
The agent should call `queue_status` and report the "To Do" issue. Then:
The agent should call `status` and report the "To Do" issue. Then:
> "Pick up issue #1 for DEV"
The agent calls `task_pickup`, which assigns a developer tier, transitions the label to "Doing", creates or reuses a worker session, and dispatches the task — all in one call. The agent just posts the announcement.
The agent calls `work_start`, which assigns a developer level, transitions the label to "Doing", creates or reuses a worker session, and dispatches the task — all in one call. The agent posts the announcement.
## Adding more projects
Tell the agent to register a new project (step 3) and add the bot to the new Telegram group (step 4). That's it — `project_register` handles labels and state setup.
Tell the agent to register a new project (step 4) from within the new project's Telegram group. That's it — `project_register` handles labels and state setup.
Each project is fully isolated — separate queue, separate workers, separate state.
## Developer tiers
## Developer levels
DevClaw assigns tasks to developer tiers instead of raw model names. This makes the system intuitive — you're assigning a "junior dev" to fix a typo, not configuring model parameters.
DevClaw assigns tasks to developer levels instead of raw model names. This makes the system intuitive — you're assigning a "junior dev" to fix a typo, not configuring model parameters.
| Tier | Role | Default model | When to assign |
|------|------|---------------|----------------|
| **junior** | Junior developer | `anthropic/claude-haiku-4-5` | Typos, single-file fixes, CSS changes |
| **medior** | Mid-level developer | `anthropic/claude-sonnet-4-5` | Features, bug fixes, multi-file changes |
| **senior** | Senior developer | `anthropic/claude-opus-4-5` | Architecture, migrations, system-wide refactoring |
| **qa** | QA engineer | `anthropic/claude-sonnet-4-5` | Code review, test validation |
| Role | Level | Default model | When to assign |
|------|-------|---------------|----------------|
| DEV | **junior** | `anthropic/claude-haiku-4-5` | Typos, single-file fixes, CSS changes |
| DEV | **medior** | `anthropic/claude-sonnet-4-5` | Features, bug fixes, multi-file changes |
| DEV | **senior** | `anthropic/claude-opus-4-5` | Architecture, migrations, system-wide refactoring |
| QA | **reviewer** | `anthropic/claude-sonnet-4-5` | Code review, test validation |
| QA | **tester** | `anthropic/claude-haiku-4-5` | Manual testing, smoke tests |
Change which model powers each tier in `openclaw.json`:
```json
{
"plugins": {
"entries": {
"devclaw": {
"config": {
"models": {
"junior": "anthropic/claude-haiku-4-5",
"medior": "anthropic/claude-sonnet-4-5",
"senior": "anthropic/claude-opus-4-5",
"qa": "anthropic/claude-sonnet-4-5"
}
}
}
}
}
}
```
Change which model powers each level in `openclaw.json` — see [Configuration](CONFIGURATION.md#model-tiers).
## What the plugin handles vs. what you handle
| Responsibility | Who | Details |
|---|---|---|
| Plugin installation | You (once) | `cp -r devclaw ~/.openclaw/extensions/` |
| Agent + workspace setup | Plugin (`devclaw_setup`) | Creates agent, configures models, writes workspace files |
| Channel binding analysis | Plugin (`analyze_channel_bindings`) | Detects channel conflicts, validates channel configuration |
| Channel binding migration | Plugin (`devclaw_setup` with `migrateFrom`) | Automatically moves channel-wide bindings between agents |
| Label setup | Plugin (`project_register`) | 8 labels, created idempotently via `IssueProvider` |
| Prompt file scaffolding | Plugin (`project_register`) | Creates `projects/prompts/<project>/dev.md` and `qa.md` |
| Agent + workspace setup | Plugin (`setup`) | Creates agent, configures models, writes workspace files |
| Channel binding migration | Plugin (`setup` with `migrateFrom`) | Automatically moves channel-wide bindings between agents |
| Label setup | Plugin (`project_register`) | 8 labels, created idempotently via IssueProvider |
| Prompt file scaffolding | Plugin (`project_register`) | Creates `projects/roles/<project>/dev.md` and `qa.md` |
| Project registration | Plugin (`project_register`) | Entry in `projects.json` with empty worker state |
| Telegram group setup | You (once per project) | Add bot to group |
| Issue creation | Plugin (`task_create`) | Orchestrator or workers create issues from chat |
| Label transitions | Plugin | Atomic label transitions via issue tracker CLI |
| Developer assignment | Plugin | LLM-selected tier by orchestrator, keyword heuristic fallback |
| Label transitions | Plugin | Atomic transitions via issue tracker CLI |
| Developer assignment | Plugin | LLM-selected level by orchestrator, keyword heuristic fallback |
| State management | Plugin | Atomic read/write to `projects.json` |
| Session management | Plugin | Creates, reuses, and dispatches to sessions via CLI. Agent never touches session tools. |
| Task completion | Plugin (`task_complete`) | Workers self-report. Auto-chains if enabled. |
| Prompt instructions | Plugin (`task_pickup`) | Loaded from `projects/prompts/<project>/<role>.md`, appended to task message |
| Task completion | Plugin (`work_finish`) | Workers self-report. Auto-chains if enabled. |
| Prompt instructions | Plugin (`work_start`) | Loaded from `projects/roles/<project>/<role>.md`, appended to task message |
| Audit logging | Plugin | Automatic NDJSON append per tool call |
| Zombie detection | Plugin | `session_health` checks active vs alive |
| Queue scanning | Plugin | `queue_status` queries issue tracker per project |
| Zombie detection | Plugin | `health` checks active vs alive |
| Queue scanning | Plugin | `status` queries issue tracker per project |