@laurentenhoor/devclaw 0.1.0

package/docs/ONBOARDING.md

@@ -0,0 +1,251 @@
+# DevClaw — Onboarding Guide
+
+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` |
+| [`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 |
+
+## Step 1: Install the plugin
+
+```bash
+# Copy to extensions directory (auto-discovered on next restart)
+cp -r devclaw ~/.openclaw/extensions/
+```
+
+Verify:
+```bash
+openclaw plugins list
+# Should show: DevClaw | devclaw | loaded
+```
+
+## Step 2: Run setup
+
+There are three ways to set up DevClaw:
+
+### Option A: Conversational onboarding (recommended)
+
+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 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
+
+```bash
+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 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
+# Create new agent with default models
+openclaw devclaw setup --new-agent "My Dev Orchestrator"
+
+# Configure existing agent with custom models
+openclaw devclaw setup --agent my-orchestrator \
+  --junior "anthropic/claude-haiku-4-5" \
+  --senior "anthropic/claude-opus-4-5"
+```
+
+### Option C: Tool call (agent-driven)
+
+**Conversational onboarding via tool:**
+```json
+onboard({ "mode": "first-run" })
+```
+
+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": {
+    "dev": {
+      "junior": "anthropic/claude-haiku-4-5",
+      "senior": "anthropic/claude-opus-4-5"
+    },
+    "qa": {
+      "reviewer": "anthropic/claude-sonnet-4-5"
+    }
+  }
+})
+```
+
+## Step 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. **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. 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
+
+If you didn't bind a channel during setup:
+
+**Option A: Manually edit `openclaw.json`**
+
+```json
+{
+  "bindings": [
+    {
+      "agentId": "my-orchestrator",
+      "match": {
+        "channel": "telegram"
+      }
+    }
+  ]
+}
+```
+
+For group-specific bindings:
+```json
+{
+  "agentId": "my-orchestrator",
+  "match": {
+    "channel": "telegram",
+    "peer": {
+      "kind": "group",
+      "id": "-1234567890"
+    }
+  }
+}
+```
+
+Restart OpenClaw after editing.
+
+**Option B: Add bot to Telegram/WhatsApp group**
+
+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.
+
+## Step 4: Register your project
+
+Go to the Telegram/WhatsApp group for the project and tell the orchestrator agent:
+
+> "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 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": "Project: my-project",
+      "baseBranch": "development",
+      "deployBranch": "development",
+      "channel": "telegram",
+      "roleExecution": "parallel",
+      "dev": {
+        "active": false,
+        "issueId": null,
+        "startTime": null,
+        "level": null,
+        "sessions": { "junior": null, "medior": null, "senior": null }
+      },
+      "qa": {
+        "active": false,
+        "issueId": null,
+        "startTime": null,
+        "level": null,
+        "sessions": { "reviewer": null, "tester": null }
+      }
+    }
+  }
+}
+```
+
+**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.
+
+## 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 && 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
+
+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 `status` and report the "To Do" issue. Then:
+
+> "Pick up issue #1 for DEV"
+
+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 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 levels
+
+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.
+
+| 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 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 (`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 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 (`work_finish`) | Workers self-report. Scheduler dispatches next role. |
+| 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 | `health` checks active vs alive |
+| Queue scanning | Plugin | `status` queries issue tracker per project |

package/docs/QA_WORKFLOW.md

@@ -0,0 +1,120 @@
+# DevClaw — QA Workflow
+
+Quality Assurance in DevClaw follows a structured workflow that ensures every review is documented and traceable.
+
+## Required Steps
+
+### 1. Review the Code
+
+- Pull latest from the base branch
+- Run tests and linting
+- Verify changes address issue requirements
+- Check for regressions in related functionality
+
+### 2. Document Your Review (REQUIRED)
+
+Before completing your task, you MUST create a review comment using `task_comment`:
+
+```javascript
+task_comment({
+  projectGroupId: "<group-id>",
+  issueId: <issue-number>,
+  body: "## QA Review\n\n**Tested:**\n- [List what you tested]\n\n**Results:**\n- [Pass/fail details]\n\n**Environment:**\n- [Test environment details]",
+  authorRole: "qa"
+})
+```
+
+### 3. Complete the Task
+
+After posting your comment, call `work_finish`:
+
+```javascript
+work_finish({
+  role: "qa",
+  projectGroupId: "<group-id>",
+  result: "pass",  // or "fail", "refine", "blocked"
+  summary: "Brief summary of review outcome"
+})
+```
+
+## QA Results
+
+| Result | Label transition | Meaning |
+|---|---|---|
+| `"pass"` | Testing → Done | Approved. Issue closed. |
+| `"fail"` | Testing → To Improve | Issues found. Issue reopened, sent back to DEV. |
+| `"refine"` | Testing → Refining | Needs human decision. Pipeline pauses. |
+| `"blocked"` | Testing → To Test | Cannot complete (env issues, etc.). Returns to QA queue. |
+
+## Why Comments Are Required
+
+1. **Audit Trail** — Every review decision is documented in the issue tracker
+2. **Knowledge Sharing** — Future reviewers understand what was tested
+3. **Quality Metrics** — Enables tracking of test coverage
+4. **Debugging** — When issues arise later, we know what was checked
+5. **Compliance** — Some projects require documented QA evidence
+
+## Comment Templates
+
+### For Passing Reviews
+
+```markdown
+## QA Review
+
+**Tested:**
+- Feature A: [specific test cases]
+- Feature B: [specific test cases]
+- Edge cases: [list]
+
+**Results:** All tests passed. No regressions found.
+
+**Environment:**
+- Browser/Platform: [details]
+- Version: [details]
+- Test data: [if relevant]
+
+**Notes:** [Optional observations or recommendations]
+```
+
+### For Failing Reviews
+
+```markdown
+## QA Review — Issues Found
+
+**Tested:**
+- [What you tested]
+
+**Issues Found:**
+1. [Issue description with steps to reproduce]
+2. [Issue description with expected vs actual behavior]
+
+**Environment:**
+- [Test environment details]
+
+**Severity:** [Critical/Major/Minor]
+```
+
+## Enforcement
+
+QA workers receive instructions via role templates to:
+- Always call `task_comment` BEFORE `work_finish`
+- Include specific details about what was tested
+- Document results, environment, and any notes
+
+Prompt templates affected:
+- `projects/roles/<project>/qa.md`
+- All project-specific QA templates should follow this pattern
+
+## Best Practices
+
+1. **Be Specific** — Don't just say "tested the feature" — list what you tested
+2. **Include Environment** — Version numbers, browser, OS can matter
+3. **Document Edge Cases** — If you tested special scenarios, note them
+4. **Reference Requirements** — Link back to acceptance criteria from the issue
+5. **Use Screenshots** — For UI issues, screenshots help (link in comment)
+
+## Related
+
+- Tool: [`task_comment`](TOOLS.md#task_comment) — Add comments to issues
+- Tool: [`work_finish`](TOOLS.md#work_finish) — Complete QA tasks
+- Config: [`projects/roles/<project>/qa.md`](CONFIGURATION.md#role-instruction-files) — QA role instructions

package/docs/ROADMAP.md

@@ -0,0 +1,96 @@
+# DevClaw — Roadmap
+
+## Configurable Roles
+
+Currently DevClaw has two hardcoded roles: **DEV** and **QA**. Each project gets one worker slot per role. The pipeline is fixed: DEV writes code, QA reviews it.
+
+This works for the common case but breaks down when you want:
+- A **design** role that creates mockups before DEV starts
+- A **devops** role that handles deployment after QA passes
+- A **PM** role that triages and prioritizes the backlog
+- Multiple DEV workers in parallel (e.g. frontend + backend)
+- A project with no QA step at all
+
+### Planned: role configuration per project
+
+Roles become a configurable list instead of a hardcoded pair. Each role defines:
+- **Name** — e.g. `design`, `dev`, `qa`, `devops`
+- **Levels** — which developer levels can be assigned (e.g. design only needs `medior`)
+- **Pipeline position** — where it sits in the task lifecycle
+- **Worker count** — how many concurrent workers (default: 1)
+
+```json
+{
+  "roles": {
+    "dev": { "levels": ["junior", "medior", "senior"], "workers": 1 },
+    "qa": { "levels": ["reviewer", "tester"], "workers": 1 },
+    "devops": { "levels": ["medior", "senior"], "workers": 1 }
+  },
+  "pipeline": ["dev", "qa", "devops"]
+}
+```
+
+The pipeline definition replaces the hardcoded `Doing → To Test → Testing → Done` flow. Labels and transitions are generated from the pipeline config. The scheduler follows the pipeline order when filling free slots.
+
+### Open questions
+
+- How do custom labels map? Generate from role names, or let users define?
+- Should roles have their own instruction files (`projects/roles/<project>/<role>.md`) — yes, this already works
+- How to handle parallel roles (e.g. frontend + backend DEV in parallel before QA)?
+
+---
+
+## Channel-agnostic Groups
+
+Currently DevClaw maps projects to **Telegram group IDs**. The `projectGroupId` is a Telegram-specific negative number. This means:
+- WhatsApp groups can't be used as project channels (partially supported now via `channel` field)
+- Discord, Slack, or other channels are excluded
+- The naming (`groupId`, `groupName`) is Telegram-specific
+
+### Planned: abstract channel binding
+
+Replace Telegram-specific group IDs with a generic channel identifier that works across any OpenClaw channel.
+
+```json
+{
+  "projects": {
+    "whatsapp:120363140032870788@g.us": {
+      "name": "my-project",
+      "channel": "whatsapp",
+      "peer": "120363140032870788@g.us",
+      ...
+    },
+    "telegram:-1234567890": {
+      "name": "other-project",
+      "channel": "telegram",
+      "peer": "-1234567890",
+      ...
+    }
+  }
+}
+```
+
+Key changes:
+- `projectGroupId` becomes a composite key: `<channel>:<peerId>`
+- `project_register` accepts `channel` + `peerId` instead of `projectGroupId`
+- Project lookup uses the composite key from the message context
+- All tool params, state keys, and docs updated accordingly
+- Backward compatible: existing Telegram-only keys migrated on read
+
+This enables any OpenClaw channel (Telegram, WhatsApp, Discord, Slack, etc.) to host a project.
+
+### Open questions
+
+- Should one project be bindable to multiple channels? (e.g. Telegram for devs, WhatsApp for stakeholder updates)
+- How does the orchestrator agent handle cross-channel context?
+
+---
+
+## Other Ideas
+
+- **Jira provider** — `IssueProvider` interface already abstracts GitHub/GitLab; Jira is the obvious next addition
+- **Deployment integration** — `work_finish` QA pass could trigger a deploy step via webhook or CLI
+- **Cost tracking** — log token usage per task/level, surface in `status`
+- **Priority scoring** — automatic priority assignment based on labels, age, and dependencies
+- **Session archival** — auto-archive idle sessions after configurable timeout (currently indefinite)
+- **Progressive delegation** — track QA pass rates per level and auto-promote (see [Management Theory](MANAGEMENT.md))