@calltelemetry/openclaw-linear 0.7.1 → 0.8.1

package/README.md

@@ -3,348 +3,492 @@
 [![OpenClaw](https://img.shields.io/badge/OpenClaw-v2026.2+-blue)](https://github.com/calltelemetry/openclaw)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
-An OpenClaw plugin that connects Linear to AI agents. Issues get triaged automatically, agents respond to `@mentions`, and a worker-audit pipeline runs when you assign work -- with an inactivity watchdog that kills and respawns stuck sessions.
+Connect Linear to AI agents. Issues get triaged, implemented, and audited — automatically.
 
 ---
 
-## Table of Contents
-
-- [Features](#features)
-- [How It Works](#how-it-works)
-- [Architecture](#architecture)
-- [Project Layout](#project-layout)
-- [Getting Started](#getting-started)
-- [Usage](#usage)
-- [Configuration](#configuration)
-- [Prompt Customization](#prompt-customization)
-- [Notifications](#notifications)
-- [Coding Tool](#coding-tool-code_run)
-- [Inactivity Watchdog](#inactivity-watchdog)
-- [CLI Reference](#cli-reference)
-- [Troubleshooting](#troubleshooting)
-- [License](#license)
+## What It Does
+
+- **New issue?** Agent estimates story points, adds labels, sets priority.
+- **Assign to agent?** A worker implements it, an independent auditor verifies it, done.
+- **Comment anything?** The bot understands natural language — no magic commands needed.
+- **Say "let's plan the features"?** A planner interviews you, writes user stories, and builds your full issue hierarchy.
+- **Plan looks good?** A different AI model automatically audits the plan before dispatch.
+- **Agent goes silent?** A watchdog kills it and retries automatically.
+- **Want updates?** Get notified on Discord, Slack, Telegram, or Signal.
 
 ---
 
-## Features
-
-| Feature | Description |
-|---------|-------------|
-| **Auto-triage** | New issues get story point estimates, labels, and priority automatically |
-| **@mention routing** | `@qa`, `@infra`, `@docs` in comments route to specialized agents |
-| **Worker-audit pipeline** | Assign an issue and a worker implements it, then an independent auditor verifies |
-| **Hard-enforced audit** | Audit triggers in plugin code, not as an LLM decision. Workers cannot self-certify. |
-| **Inactivity watchdog** | Kills agent sessions with no I/O, retries once, escalates on double failure |
-| **Branded replies** | Each agent posts with its own name and avatar in Linear |
-| **Real-time progress** | Agent activity (thinking, acting, responding) streams to Linear's UI |
-| **Unified `code_run`** | One tool, three backends (Codex, Claude Code, Gemini), configurable per agent |
-| **Issue management** | Agents use `linearis` CLI to update status, close issues, add comments |
-| **Project planner** | Interactive interview builds out Linear issue hierarchies with dependency DAGs |
-| **Customizable prompts** | `prompts.yaml` -- edit worker, audit, planner, and rework prompts without rebuilding |
-| **Multi-channel notifications** | Dispatch events fan out to Discord, Slack, Telegram, Signal, or any OpenClaw channel |
-| **Artifact logging** | Every dispatch writes structured logs to `.claw/` in the worktree |
+## Quick Start
 
----
+### 1. Install the plugin
 
-## How It Works
-
-```mermaid
-sequenceDiagram
-    participant You
-    participant Linear
-    participant Plugin
-    participant Agents
-
-    You->>Linear: Create issue
-    Linear->>Plugin: Webhook (Issue.create)
-    Plugin->>Agents: Triage agent
-    Agents-->>Plugin: Estimate + labels
-    Plugin-->>Linear: Update issue
-    Plugin-->>Linear: Post assessment
-
-    You->>Linear: Assign to agent
-    Linear->>Plugin: Webhook (Issue.update)
-    Plugin->>Agents: Worker agent
-    Agents-->>Linear: Streaming status
-    Plugin->>Agents: Audit agent (automatic)
-    Agents-->>Plugin: JSON verdict
-    Plugin-->>Linear: Result comment
-
-    You->>Linear: Comment "@qa review"
-    Linear->>Plugin: Webhook (Comment)
-    Plugin->>Agents: QA agent
-    Agents-->>Plugin: Response
-    Plugin-->>Linear: Branded comment
-
-    You->>Linear: Comment "@ctclaw plan this project"
-    Linear->>Plugin: Webhook (Comment)
-    Plugin->>Agents: Planner agent
-    Agents-->>Linear: Creates epics + issues + dependency DAG
-    Agents-->>Linear: Interview question
+```bash
+openclaw plugins install @calltelemetry/openclaw-linear
 ```
 
----
+### 2. Create a Linear OAuth app
+
+Go to **Linear Settings > API > Applications** and create an app:
 
-## Architecture
+- Set **Webhook URL** to `https://your-domain.com/linear/webhook`
+- Set **Redirect URI** to `https://your-domain.com/linear/oauth/callback`
+- Enable events: **Agent Sessions**, **Comments**, **Issues**
+- Save your **Client ID** and **Client Secret**
 
-### Dispatch Pipeline (v2)
+> You also need a **workspace webhook** (Settings > API > Webhooks) pointing to the same URL with Comment + Issue + User events enabled. Both webhooks are required.
+
+### 3. Set credentials
+
+```bash
+export LINEAR_CLIENT_ID="your_client_id"
+export LINEAR_CLIENT_SECRET="your_client_secret"
+```
+
+For systemd services, add these to your unit file:
+
+```ini
+[Service]
+Environment=LINEAR_CLIENT_ID=your_client_id
+Environment=LINEAR_CLIENT_SECRET=your_client_secret
+```
+
+Then reload: `systemctl --user daemon-reload && systemctl --user restart openclaw-gateway`
 
-When an issue is assigned, the plugin runs a multi-stage pipeline:
+### 4. Authorize
 
-```mermaid
-flowchart TD
-    A[Issue Assigned] --> B["**DISPATCH**<br/>Tier assessment, worktree creation,<br/>state registration"]
-    B --> C["**WORKER** *(sub-agent)*<br/>Plans + implements solution.<br/>Posts summary comment.<br/>CANNOT mark issue as Done."]
-    C -->|"plugin code — automatic,<br/>not LLM-mediated"| D["**AUDIT** *(sub-agent)*<br/>Independent auditor reads issue body,<br/>verifies criteria, runs tests,<br/>returns JSON verdict."]
-    D --> E["**VERDICT** *(plugin code)*"]
-    E -->|PASS| F["Done + notify"]
-    E -->|"FAIL ≤ max"| G["Rework (attempt++)"]
-    G --> C
-    E -->|"FAIL > max"| H["Stuck + escalate"]
+```bash
+openclaw openclaw-linear auth
 ```
 
-### Hard-Enforced vs. LLM-Mediated
+This opens your browser. Approve the authorization, then restart:
 
-| Layer | Mechanism | Can be skipped? |
-|-------|-----------|-----------------|
-| Worker spawn | Plugin code (`runAgent`) | No |
-| Audit trigger | Plugin code (fires after worker completes) | No |
-| Verdict processing | Plugin code (pass/fail/escalate) | No |
-| Inactivity watchdog | Plugin code (timer-based kill + retry) | No |
-| Worker implementation | LLM-mediated (agent decides how to code) | N/A |
-| Audit evaluation | LLM-mediated (agent decides if criteria are met) | N/A |
+```bash
+systemctl --user restart openclaw-gateway
+```
 
-### State Machine
+### 5. Verify
 
-```mermaid
-stateDiagram-v2
-    [*] --> DISPATCHED
-    DISPATCHED --> WORKING
-    WORKING --> AUDITING
-    AUDITING --> DONE
-    AUDITING --> WORKING : FAIL (attempt++)
-    WORKING --> STUCK : watchdog kill 2x
-    AUDITING --> STUCK : attempt > max
+```bash
+openclaw openclaw-linear status
 ```
 
-All transitions use compare-and-swap (CAS) to prevent races. `dispatch-state.json` is the canonical source of truth.
+You should see a valid token and connected status. Check the gateway logs for a clean startup:
 
-### Project Planner Pipeline
+```
+Linear agent extension registered (agent: default, token: profile, orchestration: enabled)
+```
 
-When `@ctclaw plan this project` is commented on a root issue, the plugin enters planning mode:
+Test the webhook endpoint:
 
-```mermaid
-flowchart TD
-    A["Comment: 'plan this project'"] --> B["INITIATE<br/>Register session, post welcome"]
-    B --> C["INTERVIEW<br/>Agent asks questions,<br/>creates issues + DAG"]
-    C -->|user responds| C
-    C -->|"'finalize plan'"| D["AUDIT<br/>DAG validation, completeness checks"]
-    D -->|Pass| E["APPROVED<br/>Project ready for dispatch"]
-    D -->|Fail| C
-    C -->|"'abandon'"| F["ABANDONED"]
+```bash
+curl -s -X POST https://your-domain.com/linear/webhook \
+  -H "Content-Type: application/json" \
+  -d '{"type":"test","action":"ping"}'
+# Returns: "ok"
 ```
 
-During planning mode, the planner creates epics, sub-issues, and dependency relationships (`blocks`/`blocked_by`) via 5 dedicated tools. Issue dispatch is blocked for projects in planning mode.
+That's it. Create an issue in Linear and watch the agent respond.
+
+---
+
+## How It Works — Step by Step
 
-### Webhook Event Router
+Every issue moves through a clear pipeline. Here's exactly what happens at each stage and what you'll see in Linear.
 
-```mermaid
-flowchart TD
-    A["POST /linear/webhook"] --> B{"Event Type"}
-    B --> C["AgentSessionEvent.created → Dispatch pipeline"]
-    B --> D["AgentSessionEvent.prompted → Resume session"]
-    B --> E["Comment.create → @mention routing<br/>or planning mode"]
-    B --> F["Issue.create → Auto-triage"]
-    B --> G["Issue.update → Dispatch if assigned"]
-    B --> H["AppUserNotification → Direct response"]
+```
+ ┌─────────┐    ┌──────────┐    ┌────────┐    ┌───────┐    ┌──────────┐
+ │ Triage  │───▶│ Dispatch │───▶│ Worker │───▶│ Audit │───▶│  Done ✔  │
+ │(auto)   │    │(you      │    │(auto)  │    │(auto) │    │          │
+ │         │    │ assign)  │    │        │    │       │    └──────────┘
+ └─────────┘    └──────────┘    └────────┘    └───┬───┘
+                                                  │
+                                    ┌─────────────┤
+                                    ▼             ▼
+                              ┌──────────┐  ┌───────────────┐
+                              │ Rework   │  │ Needs Your    │
+                              │ (auto    │  │ Help ⚠        │
+                              │  retry)  │  │ (escalated)   │
+                              └────┬─────┘  └───────────────┘
+                                   │
+                                   └──▶ back to Worker
 ```
 
-All handlers respond `200 OK` within 5 seconds (Linear requirement), then process asynchronously.
+### Stage 1: Triage (automatic)
 
-### Two Webhook Systems
+**Trigger:** You create a new issue.
 
-Linear delivers events through two separate webhook paths:
+The agent reads your issue, estimates story points, adds labels, sets priority, and posts an assessment comment — all within seconds.
 
-1. **Workspace webhook** (Settings > API > Webhooks) -- Comment, Issue, User events
-2. **OAuth app webhook** (Settings > API > Applications) -- `AgentSessionEvent` (created/prompted)
+**What you'll see in Linear:**
 
-Both must point to: `https://<your-domain>/linear/webhook`
+> **[Mal]** This looks like a medium complexity change — the search API integration touches both the backend GraphQL schema and the frontend query layer. I've estimated 3 points and tagged it `backend` + `frontend`.
 
-### Deduplication
+The estimate, labels, and priority are applied silently to the issue fields. You don't need to do anything.
 
-A 60-second sliding window prevents double-handling:
+### Stage 2: Dispatch (you assign the issue)
 
-| Key Pattern | Prevents |
-|---|---|
-| `session:{id}` | Same session processed by both Issue.update and AgentSessionEvent |
-| `comment:{id}` | Same comment webhook delivered twice |
-| `assigned:{issueId}:{viewerId}` | Rapid re-assignment events |
-| `issue-create:{id}` | Duplicate Issue.create webhooks |
+**Trigger:** You assign the issue to the agent (or it gets auto-assigned after planning).
+
+The agent assesses complexity, picks an appropriate model, creates an isolated git worktree, and starts working.
+
+**What you'll see in Linear:**
+
+> **Dispatched** as **senior** (anthropic/claude-opus-4-6)
+> > Complex multi-service refactor with migration concerns
+>
+> Worktree: `/home/claw/worktrees/ENG-100` (fresh)
+> Branch: `codex/ENG-100`
+>
+> **Status:** Worker is starting now. An independent audit runs automatically after implementation.
+>
+> **While you wait:**
+> - Check progress: `/dispatch status ENG-100`
+> - Cancel: `/dispatch escalate ENG-100 "reason"`
+> - All dispatches: `/dispatch list`
+
+**Complexity tiers:**
+
+| Tier | Model | When |
+|---|---|---|
+| Junior | claude-haiku-4-5 | Simple config changes, typos, one-file fixes |
+| Medior | claude-sonnet-4-6 | Standard features, multi-file changes |
+| Senior | claude-opus-4-6 | Complex refactors, architecture changes |
+
+### Stage 3: Implementation (automatic)
+
+The worker agent reads the issue, plans its approach, writes code, and runs tests — all in the isolated worktree. You don't need to do anything during this stage.
+
+If this is a **retry** after a failed audit, the worker gets the previous audit feedback as context so it knows exactly what to fix.
+
+**Notifications you'll receive:**
+> `ENG-100 working on it (attempt 1)`
+
+### Stage 4: Audit (automatic)
+
+After the worker finishes, a separate auditor agent independently verifies the work. The auditor checks the issue requirements against what was actually implemented.
+
+This is **not optional** — the worker cannot mark its own work as done. The audit is triggered by the plugin, not by the AI.
+
+**Notifications you'll receive:**
+> `ENG-100 checking the work...`
+
+### Stage 5: Verdict
+
+The audit produces one of three outcomes:
+
+#### Pass — Issue is done
+
+The issue is marked done automatically. A summary is posted.
+
+**What you'll see in Linear:**
+
+> ## Done
+>
+> This issue has been implemented and verified.
+>
+> **What was checked:**
+> - API endpoint returns correct response format
+> - Tests pass for edge cases
+> - Error handling covers timeout scenarios
+>
+> **Test results:** 14 tests passed, 0 failed
+>
+> ---
+> *Completed on attempt 1. Artifacts: `/home/claw/worktrees/ENG-100/.claw/`*
+
+**Notification:** `✅ ENG-100 done! Ready for review.`
+
+#### Fail (retries left) — Automatic rework
+
+The worker gets the audit feedback and tries again. You don't need to do anything.
+
+**What you'll see in Linear:**
+
+> ## Needs More Work
+>
+> The implementation was checked and some things need to be addressed. Retrying automatically.
+>
+> **Attempt 1 of 3**
+>
+> **What needs fixing:**
+> - Missing input validation on the search endpoint
+> - No test for empty query string
+>
+> **Test results:** 12 passed, 2 failed
+
+**Notification:** `ENG-100 needs more work (attempt 1). Issues: missing validation, no empty query test`
+
+#### Fail (no retries left) — Needs your help
+
+After all retries are exhausted (default: 3 attempts), the issue is escalated to you.
+
+**What you'll see in Linear:**
+
+> ## Needs Your Help
+>
+> The automatic retries didn't fix these issues:
+>
+> **What went wrong:**
+> - Search pagination still returns duplicate results
+> - Integration test flaky on CI
+>
+> **Test results:** 10 passed, 4 failed
+>
+> ---
+> *Please review and either:*
+> - *Update the issue description with clearer requirements, then re-assign*
+> - *Fix the issues manually in the worktree at `/home/claw/worktrees/ENG-100`*
+
+**Notification:** `🚨 ENG-100 needs your help — couldn't fix it after 3 tries`
+
+**What you can do:**
+1. **Clarify the issue** — Add more detail to the description, then re-assign to try again
+2. **Fix it yourself** — The agent's work is in the worktree, ready to edit
+3. **Force retry** — `/dispatch retry ENG-100`
+4. **Check logs** — Worker output in `.claw/worker-*.md`, audit verdicts in `.claw/audit-*.json`
+
+### Stage 6: Timeout (if the agent goes silent)
+
+If the agent produces no output for 2 minutes (configurable), the watchdog kills it and retries once. If the retry also times out, the issue is escalated.
+
+**What you'll see in Linear:**
+
+> ## Agent Timed Out
+>
+> The agent stopped responding for over 120s and was automatically restarted, but the retry also failed.
+>
+> **What to do:** Re-assign this issue to try again. If it keeps timing out, the issue might be too complex — try breaking it into smaller issues.
+
+**Notification:** `⚡ ENG-100 timed out (no activity for 120s). Will retry.`
+
+### What's in the worktree
+
+Every dispatch creates a `.claw/` folder inside the worktree with everything the agent did:
+
+```
+/home/claw/worktrees/ENG-100/
+├── .claw/
+│   ├── manifest.json       # Issue metadata, tier, status, attempt count
+│   ├── worker-0.md         # What the worker did on attempt 1
+│   ├── worker-1.md         # What the worker did on attempt 2 (if retried)
+│   ├── audit-0.json        # Audit verdict for attempt 1
+│   ├── audit-1.json        # Audit verdict for attempt 2
+│   ├── log.jsonl           # Timeline of every phase with timing
+│   └── summary.md          # Final summary (written on done or stuck)
+├── src/                    # ← your code, modified by the agent
+├── tests/
+└── ...
+```
+
+If something went wrong, start with `log.jsonl` — it shows every phase, how long it took, and a preview of the output.
 
 ---
 
-## Project Layout
-
-```
-openclaw-linear/
-|-- index.ts                  Plugin entry point, route/hook/service registration
-|-- openclaw.plugin.json      Plugin metadata and config schema
-|-- prompts.yaml              Externalized worker/audit/rework prompt templates
-|-- coding-tools.json         Backend config (default tool, per-agent overrides)
-|-- package.json
-|-- README.md
-|-- docs/
-|   |-- architecture.md       Internal architecture reference
-|   +-- troubleshooting.md    Diagnostic commands and common issues
-+-- src/
-    |-- pipeline/              Core dispatch lifecycle
-    |   |-- webhook.ts             Event router -- 6 webhook handlers, dispatch logic
-    |   |-- pipeline.ts            v2 pipeline: spawnWorker, triggerAudit, processVerdict
-    |   |-- dispatch-state.ts      File-backed state, CAS transitions, session mapping
-    |   |-- dispatch-service.ts    Background monitor: stale detection, recovery, cleanup
-    |   |-- active-session.ts      In-memory session registry (issueId -> session)
-    |   |-- tier-assess.ts         Issue complexity assessment (junior/medior/senior)
-    |   |-- artifacts.ts           .claw/ directory: manifest, logs, verdicts, summaries
-    |   |-- planner.ts             Project planner orchestration (interview, audit)
-    |   +-- planning-state.ts      File-backed planning state (mirrors dispatch-state)
-    |
-    |-- agent/                 Agent execution & monitoring
-    |   |-- agent.ts               Embedded runner + subprocess fallback, retry on watchdog kill
-    |   +-- watchdog.ts            InactivityWatchdog class + per-agent config resolver
-    |
-    |-- tools/                 Tool registration & CLI backends
-    |   |-- tools.ts               Tool registration (code_run + orchestration)
-    |   |-- code-tool.ts           Unified code_run dispatcher
-    |   |-- cli-shared.ts          Shared helpers (buildLinearApi, resolveSession, defaults)
-    |   |-- claude-tool.ts         Claude Code CLI runner (JSONL -> Linear activities)
-    |   |-- codex-tool.ts          Codex CLI runner (JSONL -> Linear activities)
-    |   |-- gemini-tool.ts         Gemini CLI runner (JSONL -> Linear activities)
-    |   |-- orchestration-tools.ts spawn_agent / ask_agent for multi-agent delegation
-    |   +-- planner-tools.ts       5 planning tools (create/link/update issues, audit DAG)
-    |
-    |-- api/                   Linear API & auth
-    |   |-- linear-api.ts          GraphQL client, token resolution, auto-refresh
-    |   |-- auth.ts                OAuth provider registration
-    |   +-- oauth-callback.ts      HTTP handler for OAuth redirect
-    |
-    +-- infra/                 Infrastructure utilities
-        |-- cli.ts                 CLI subcommands (auth, status, worktrees, prompts)
-        |-- codex-worktree.ts      Git worktree create/remove/status/PR helpers
-        +-- notify.ts              Multi-channel notifier (Discord, Slack, Telegram, Signal)
+## Comment Routing — Talk Naturally
+
+You don't need to memorize magic commands. The bot uses an LLM-based intent classifier to understand what you want from any comment.
+
+```
+User comment → Intent Classifier (small model, ~2s) → Route to handler
+                         ↓ (on failure)
+                    Regex fallback → Route to handler
 ```
 
+**What the bot understands:**
+
+| What you say | What happens |
+|---|---|
+| "let's plan the features for this" | Starts planning interview |
+| "looks good, ship it" (during planning) | Runs plan audit + cross-model review |
+| "nevermind, cancel this" (during planning) | Exits planning mode |
+| "hey kaylee can you look at this?" | Routes to Kaylee (no `@` needed) |
+| "what can I do here?" | Default agent responds (not silently dropped) |
+| "fix the search bug" | Default agent dispatches work |
+
+`@mentions` still work as a fast path — if you write `@kaylee`, the classifier is skipped entirely for speed.
+
+> **Tip:** Configure `classifierAgentId` to point to a small/fast model agent (like Haiku) for low-latency, low-cost intent classification. The classifier only needs ~300 tokens per call.
+
 ---
 
-## Getting Started
+## Planning a Project
 
-### Prerequisites
+For larger work, the planner helps you break a project into issues with dependencies, then dispatches them automatically.
 
-- **OpenClaw** gateway running (v2026.2+)
-- **Linear** workspace with API access
-- **Public URL** for webhook delivery (Cloudflare Tunnel recommended)
-- **Coding CLIs** (at least one): `codex`, `claude`, `gemini` -- installed in PATH
-- **linearis** CLI -- for issue management
+### Start planning
 
-### 1. Install the Plugin
+Comment on any issue that belongs to a Linear project — use natural language:
 
-```bash
-openclaw plugins install @calltelemetry/openclaw-linear
-```
+> "let's plan out the features for this project"
 
-### 2. Create a Linear OAuth App
+The planner enters **interview mode** and asks you questions one at a time:
 
-Go to **Linear Settings > API > Applications** and create a new application:
+> I'm entering planning mode for **Search Feature**. I'll interview you about the features you want to build, then structure everything into Linear issues.
+>
+> Let's start — what is this project about, and what are the main feature areas?
 
-- **Webhook URL:** `https://<your-domain>/linear/webhook`
-- **Redirect URI:** `https://<your-domain>/linear/oauth/callback`
-- Enable webhook events: **Agent Sessions**, **Comments**, **Issues**
+### Build the plan
 
-Save the **Client ID** and **Client Secret**.
+Reply with your ideas. The planner creates issues with **user stories** and **acceptance criteria**, sets dependencies, and asks follow-up questions:
 
-### 3. Set Credentials
+> I've created 3 issues:
+> - **PROJ-2:** Build search API endpoint (3 pts, blocks PROJ-3)
+> - **PROJ-3:** Search results page (2 pts, blocked by PROJ-2)
+> - **PROJ-4:** Autocomplete suggestions (1 pt, independent)
+>
+> For PROJ-2, here's what I wrote for acceptance criteria:
+> - *Given* a user sends a search query, *When* results exist, *Then* they are returned with pagination
+>
+> Does that cover it? Should the autocomplete call a separate endpoint or share the search API?
 
-Add to your gateway environment or plugin config:
+The planner proactively asks for:
+- **User stories** — "As a [role], I want [feature] so that [benefit]"
+- **Acceptance criteria** — Given/When/Then format
+- **UAT test scenarios** — How to manually verify the feature
 
-```bash
-export LINEAR_CLIENT_ID="your_client_id"
-export LINEAR_CLIENT_SECRET="your_client_secret"
-```
+Keep replying until the plan looks right. The planner updates issues in real time.
 
-For systemd:
+### Finalize & Cross-Model Review
 
-```ini
-[Service]
-Environment=LINEAR_CLIENT_ID=your_client_id
-Environment=LINEAR_CLIENT_SECRET=your_client_secret
-```
+When you're happy, say something like "looks good" or "finalize plan". The planner runs a validation check:
+- Every issue has a description (50+ characters) with acceptance criteria
+- Every non-epic issue has an estimate and priority
+- No circular dependencies in the DAG
 
-Then reload: `systemctl --user daemon-reload && systemctl --user restart openclaw-gateway`
+**If validation passes, a cross-model review runs automatically:**
 
-### 4. Expose the Gateway
+> ## Plan Passed Checks
+>
+> **3 issues** with valid dependency graph.
+>
+> Let me have **Codex** audit this and make recommendations.
 
-Linear needs HTTPS access to deliver webhooks. [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) is recommended.
+A different AI model (always the complement of your primary model) reviews the plan for gaps:
 
-```bash
-# Install cloudflared
-sudo dnf install -y cloudflared   # RHEL/Rocky/Alma
+| Your primary model | Auto-reviewer |
+|---|---|
+| Claude / Anthropic | Codex |
+| Codex / OpenAI | Gemini |
+| Gemini / Google | Codex |
+| Other (Kimi, Mistral, etc.) | Gemini |
 
-# Create and configure tunnel
-cloudflared tunnel login
-cloudflared tunnel create openclaw
-cloudflared tunnel route dns openclaw linear.yourdomain.com
-```
+After the review, the planner summarizes recommendations and asks you to approve:
 
-Create `~/.cloudflared/config.yml`:
+> Codex suggested adding error handling scenarios to PROJ-2 and noted PROJ-4 could be split into frontend/backend. I've updated PROJ-2's acceptance criteria. The PROJ-4 split is optional — your call.
+>
+> If you're happy with this plan, say **approve plan** to start dispatching.
 
-```yaml
-tunnel: <TUNNEL_ID>
-credentials-file: ~/.cloudflared/<TUNNEL_ID>.json
+**If validation fails:**
 
-ingress:
-  - hostname: linear.yourdomain.com
-    service: http://localhost:18789
-  - service: http_status:404
-```
+> ## Plan Audit Failed
+>
+> **Problems:**
+> - PROJ-2: description too short (< 50 chars)
+> - PROJ-3: missing estimate
+>
+> **Warnings:**
+> - PROJ-4: no acceptance criteria found in description
+>
+> Please address these issues, then say "finalize plan" again.
 
-Start the tunnel:
+Fix the issues and try again. You can also say "cancel" or "stop planning" to exit without dispatching.
 
-```bash
-sudo cloudflared service install
-sudo systemctl enable --now cloudflared
-```
+### DAG dispatch progress
 
-Verify:
+After approval, issues are assigned to the agent automatically in dependency order. Up to 3 issues run in parallel.
 
-```bash
-curl -s https://linear.yourdomain.com/linear/webhook \
-  -X POST -H "Content-Type: application/json" \
-  -d '{"type":"test","action":"ping"}'
-# Should return: "ok"
-```
+> `📊 Search Feature: 2/3 complete`
 
-### 5. Authorize with Linear
+When everything is done:
 
-```bash
-openclaw openclaw-linear auth
-```
+> `✅ Search Feature: complete (3/3 issues)`
 
-This opens your browser to authorize the agent. Then restart and verify:
+If an issue gets stuck (all retries failed), dependent issues are blocked and you'll be notified.
 
-```bash
-systemctl --user restart openclaw-gateway
-openclaw openclaw-linear status
+---
+
+## Quick Reference
+
+| What you do in Linear | What happens |
+|---|---|
+| Create a new issue | Agent triages — adds estimate, labels, priority |
+| Assign an issue to the agent | Worker → Audit → Done (or retry, or escalate) |
+| Comment anything on an issue | Intent classifier routes to the right handler |
+| Mention an agent by name (with or without `@`) | That agent responds |
+| Ask a question or request work | Default agent handles it |
+| Say "plan this project" (on a project issue) | Planning interview starts |
+| Reply during planning | Issues created/updated with user stories & AC |
+| Say "looks good" / "finalize plan" | Validates → cross-model review → approval |
+| Say "approve plan" (after review) | Dispatches all issues in dependency order |
+| Say "cancel" / "abandon planning" | Exits planning mode |
+| `/dispatch list` | Shows all active dispatches |
+| `/dispatch retry CT-123` | Re-runs a stuck dispatch |
+| `/dispatch status CT-123` | Detailed dispatch info |
+| Add `<!-- repos: api, frontend -->` to issue body | Multi-repo dispatch |
+
+---
+
+## Configuration
+
+Add settings under the plugin entry in `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-linear": {
+        "config": {
+          "defaultAgentId": "coder",
+          "maxReworkAttempts": 2,
+          "enableAudit": true
+        }
+      }
+    }
+  }
+}
 ```
 
-### 6. Configure Agents
+### Plugin Settings
 
-Create `~/.openclaw/agent-profiles.json`:
+| Key | Type | Default | What it does |
+|---|---|---|---|
+| `defaultAgentId` | string | `"default"` | Which agent runs the pipeline |
+| `classifierAgentId` | string | — | Agent for intent classification (use a small/fast model like Haiku) |
+| `plannerReviewModel` | string | auto | Cross-model plan reviewer: `"claude"`, `"codex"`, or `"gemini"`. Auto-detects the complement of your primary model. |
+| `enableAudit` | boolean | `true` | Run auditor after implementation |
+| `enableOrchestration` | boolean | `true` | Allow `spawn_agent` / `ask_agent` tools |
+| `maxReworkAttempts` | number | `2` | Max audit failures before escalation |
+| `codexBaseRepo` | string | `"/home/claw/ai-workspace"` | Git repo for worktrees |
+| `worktreeBaseDir` | string | `"~/.openclaw/worktrees"` | Where worktrees are created |
+| `repos` | object | — | Multi-repo map (see [Multi-Repo](#multi-repo)) |
+| `dispatchStatePath` | string | `"~/.openclaw/linear-dispatch-state.json"` | Dispatch state file |
+| `planningStatePath` | string | `"~/.openclaw/linear-planning-state.json"` | Planning session state file |
+| `promptsPath` | string | — | Custom prompts file path |
+| `notifications` | object | — | Notification targets (see [Notifications](#notifications)) |
+| `inactivitySec` | number | `120` | Kill agent if silent this long |
+| `maxTotalSec` | number | `7200` | Max total agent session time |
+| `toolTimeoutSec` | number | `600` | Max single `code_run` time |
+| `claudeApiKey` | string | — | Anthropic API key for Claude CLI (passed as `ANTHROPIC_API_KEY` env var). Required if using Claude backend. |
+
+### Environment Variables
+
+| Variable | Required | What it does |
+|---|---|---|
+| `LINEAR_CLIENT_ID` | Yes | OAuth app client ID |
+| `LINEAR_CLIENT_SECRET` | Yes | OAuth app client secret |
+| `LINEAR_API_KEY` | No | Personal API key (fallback) |
+
+### Agent Profiles
+
+Define your agents in `~/.openclaw/agent-profiles.json`:
 
 ```json
 {
   "agents": {
     "coder": {
       "label": "Coder",
-      "mission": "Full-stack engineer. Plans, implements, and ships code.",
+      "mission": "Full-stack engineer. Plans, implements, ships.",
       "isDefault": true,
       "mentionAliases": ["coder"],
       "avatarUrl": "https://example.com/coder.png",
@@ -356,27 +500,30 @@ Create `~/.openclaw/agent-profiles.json`:
     },
     "qa": {
       "label": "QA",
-      "mission": "Test engineer. Quality guardian, test strategy.",
-      "mentionAliases": ["qa", "tester"],
-      "watchdog": {
-        "inactivitySec": 120,
-        "maxTotalSec": 3600,
-        "toolTimeoutSec": 600
-      }
+      "mission": "Test engineer. Reviews code, writes tests.",
+      "mentionAliases": ["qa", "tester"]
     }
   }
 }
 ```
 
-Each agent name must match an agent in `~/.openclaw/openclaw.json`. One agent must have `isDefault: true` -- this agent handles issue assignments and the dispatch pipeline.
+One agent must have `"isDefault": true` — that's the one that handles triage and the dispatch pipeline.
+
+### Coding Tools
 
-### 7. Configure Coding Tools
+Create `coding-tools.json` in the plugin root to configure which CLI backend agents use:
 
-Create `coding-tools.json` in the plugin root:
+> **Warning — Claude Code (Anthropic) and headless/automated usage**
+>
+> Calling Claude Code via CLI in a headless or automated context (which is how this plugin
+> uses it) may violate [Anthropic's Terms of Service](https://www.anthropic.com/terms).
+> The default backend is **Codex CLI** (OpenAI). **Gemini CLI** (Google) is used as the
+> cross-model reviewer. If you choose to use Claude despite this, you do so at your own risk.
+> See [Claude API Key](#claude-api-key) below for opt-in configuration.
 
 ```json
 {
-  "codingTool": "claude",
+  "codingTool": "codex",
   "agentCodingTools": {},
   "backends": {
     "claude": { "aliases": ["claude", "claude code", "anthropic"] },
@@ -386,166 +533,155 @@ Create `coding-tools.json` in the plugin root:
 }
 ```
 
-### 8. Install linearis
+The agent calls `code_run` without knowing which backend is active. Resolution order: explicit `backend` parameter > per-agent override > global default > `"codex"`.
 
-```bash
-npm install -g linearis
-npx clawhub install linearis
-echo "lin_api_YOUR_KEY" > ~/.linear_api_token
-```
-
-### 9. Verify
+#### Claude API Key
 
-```bash
-systemctl --user restart openclaw-gateway
-```
+If you opt in to using Claude as a backend (despite the TOS concerns noted above), you can
+provide an Anthropic API key so the Claude CLI authenticates via API key instead of its
+built-in interactive auth.
 
-Check logs for a clean startup:
+Set `claudeApiKey` in the plugin config:
 
-```
-[plugins] Linear agent extension registered (agent: default, token: profile,
-  codex: codex-cli 0.101.0, claude: 2.1.45, gemini: 0.28.2, orchestration: enabled)
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-linear": {
+        "config": {
+          "claudeApiKey": "sk-ant-..."
+        }
+      }
+    }
+  }
+}
 ```
 
-Test the webhook:
-
-```bash
-curl -s -X POST https://your-domain.com/linear/webhook \
-  -H "Content-Type: application/json" \
-  -d '{"type":"test","action":"ping"}'
-# Should return: "ok"
-```
+The key is passed to the Claude CLI subprocess as the `ANTHROPIC_API_KEY` environment variable.
+You can also set `ANTHROPIC_API_KEY` as a process-level environment variable (e.g., in your
+systemd unit file) as a fallback. The plugin config value takes precedence if both are set.
 
 ---
 
-## Usage
+## Notifications
 
-Once set up, the plugin responds to Linear events automatically:
+Get notified when dispatches start, pass audit, fail, or get stuck.
 
-| What you do in Linear | What happens |
-|---|---|
-| Create a new issue | Agent triages it (estimate, labels, priority) and posts an assessment |
-| Assign an issue to the agent | Worker-audit pipeline runs with watchdog protection |
-| Trigger an agent session | Agent responds directly in the session |
-| Comment `@qa check the tests` | QA agent responds with its expertise |
-| Comment `@ctclaw plan this project` | Planner agent enters interview mode, builds issue DAG |
-| Reply during planning mode | Planner creates/updates issues and asks next question |
-| Comment "finalize plan" | DAG audit runs: cycles, orphans, missing estimates/priorities |
-| Ask "close this issue" | Agent runs `linearis issues update API-123 --status Done` |
-| Ask "use gemini to review" | Agent calls `code_run` with `backend: "gemini"` |
+### Setup
+
+```json
+{
+  "notifications": {
+    "targets": [
+      { "channel": "discord", "target": "1471743433566715974" },
+      { "channel": "telegram", "target": "-1003884997363" },
+      { "channel": "slack", "target": "C0123456789", "accountId": "my-acct" }
+    ],
+    "events": {
+      "auditing": false
+    },
+    "richFormat": true
+  }
+}
+```
 
-### Pipeline Behavior
+- **`targets`** — Where to send notifications (channel name + ID)
+- **`events`** — Toggle specific events off (all on by default)
+- **`richFormat`** — Set to `true` for Discord embeds with colors and Telegram HTML formatting
 
-When an issue is assigned:
+### Events
 
-1. **Tier assessment** -- Evaluates complexity (junior/medior/senior), selects model tier
-2. **Worktree creation** -- Isolated git worktree for the implementation
-3. **Worker runs** -- Worker agent plans and implements, posts summary comment
-4. **Audit runs** -- Independent auditor verifies against issue body, returns JSON verdict
-5. **Verdict** -- Pass: issue done. Fail: worker re-spawns with gaps (up to `maxReworkAttempts`). Too many failures: stuck + escalation notification.
-6. **Watchdog** -- If the worker goes silent (no I/O), the watchdog kills it and retries once. Double failure escalates to stuck.
+| Event | When it fires |
+|---|---|
+| `dispatch` | Issue dispatched to pipeline |
+| `working` | Worker started |
+| `auditing` | Audit in progress |
+| `audit_pass` | Audit passed, issue done |
+| `audit_fail` | Audit failed, worker retrying |
+| `escalation` | Too many failures, needs human |
+| `stuck` | Dispatch stale for 2+ hours |
+| `watchdog_kill` | Agent killed for inactivity |
 
-Workers **cannot** mark issues as done -- that's handled entirely by plugin verdict processing code.
+### Test It
+
+```bash
+openclaw openclaw-linear notify test              # Test all targets
+openclaw openclaw-linear notify test --channel discord  # Test one channel
+openclaw openclaw-linear notify status             # Show config
+```
 
 ---
 
-## Configuration
+## Prompt Customization
 
-### Plugin Config
+Worker, audit, and rework prompts live in `prompts.yaml`. You can customize them without rebuilding.
 
-Set in `openclaw.json` under the plugin entry:
+### Three Layers
 
-| Key | Type | Default | Description |
-|---|---|---|---|
-| `defaultAgentId` | string | `"default"` | Agent ID for pipeline workers and audit |
-| `enableAudit` | boolean | `true` | Run auditor stage after implementation |
-| `enableOrchestration` | boolean | `true` | Allow `spawn_agent`/`ask_agent` tools |
-| `codexBaseRepo` | string | `"/home/claw/ai-workspace"` | Git repo for worktrees |
-| `codexModel` | string | -- | Default Codex model |
-| `codexTimeoutMs` | number | `600000` | Legacy timeout for coding CLIs (ms) |
-| `worktreeBaseDir` | string | `"~/.openclaw/worktrees"` | Base directory for worktrees |
-| `dispatchStatePath` | string | `"~/.openclaw/linear-dispatch-state.json"` | Dispatch state file |
-| `notifications` | object | -- | [Notification targets and event toggles](#notifications) |
-| `promptsPath` | string | -- | Override path for `prompts.yaml` |
-| `maxReworkAttempts` | number | `2` | Max audit failures before escalation |
-| `inactivitySec` | number | `120` | Kill sessions with no I/O for this long |
-| `maxTotalSec` | number | `7200` | Max total agent session runtime |
-| `toolTimeoutSec` | number | `600` | Max runtime for a single `code_run` invocation |
+Prompts merge in this order (later layers override earlier ones):
 
-### Environment Variables
+1. **Built-in defaults** — Ship with the plugin, always available
+2. **Your global file** — Set `promptsPath` in config to point to your custom YAML
+3. **Per-project file** — Drop a `prompts.yaml` in the worktree's `.claw/` folder
 
-| Variable | Required | Description |
-|---|---|---|
-| `LINEAR_CLIENT_ID` | Yes | OAuth app client ID |
-| `LINEAR_CLIENT_SECRET` | Yes | OAuth app client secret |
-| `LINEAR_API_KEY` | No | Personal API key (fallback if no OAuth) |
-| `LINEAR_REDIRECT_URI` | No | Override the OAuth callback URL |
-| `OPENCLAW_GATEWAY_PORT` | No | Gateway port (default: 18789) |
+Each layer only overrides the specific sections you define. Everything else keeps its default.
 
-### Agent Profile Fields
+### Example Custom Prompts
 
-| Field | Required | Description |
-|---|---|---|
-| `label` | Yes | Display name on Linear comments |
-| `mission` | Yes | Role description (injected as context) |
-| `isDefault` | One agent | Handles triage and the dispatch pipeline |
-| `mentionAliases` | Yes | `@mention` triggers (e.g., `["qa", "tester"]`) |
-| `avatarUrl` | No | Avatar URL for branded comments |
-| `watchdog.inactivitySec` | No | Inactivity kill threshold (default: 120) |
-| `watchdog.maxTotalSec` | No | Max total session runtime (default: 7200) |
-| `watchdog.toolTimeoutSec` | No | Max single `code_run` runtime (default: 600) |
+```yaml
+worker:
+  system: "You are a senior engineer. Write clean, tested code."
+  task: |
+    Issue: {{identifier}} — {{title}}
 
----
+    {{description}}
 
-## Prompt Customization
+    Workspace: {{worktreePath}}
 
-Worker, audit, and rework prompts live in `prompts.yaml`. Edit to customize without rebuilding.
+    Implement this issue. Write tests. Commit your work.
 
-### Managing Prompts
+audit:
+  system: "You are a strict code auditor."
 
-```bash
-openclaw openclaw-linear prompts show       # Print current prompts.yaml
-openclaw openclaw-linear prompts path       # Print resolved file path
-openclaw openclaw-linear prompts validate   # Validate structure and template variables
+rework:
+  addendum: |
+    PREVIOUS AUDIT FAILED. Fix these gaps:
+    {{gaps}}
 ```
 
 ### Template Variables
 
-| Variable | Description |
+| Variable | What it contains |
 |---|---|
-| `{{identifier}}` | Issue identifier (e.g., `API-123`) |
+| `{{identifier}}` | Issue ID (e.g., `API-123`) |
 | `{{title}}` | Issue title |
 | `{{description}}` | Full issue body |
 | `{{worktreePath}}` | Path to the git worktree |
-| `{{tier}}` | Assessed complexity tier |
-| `{{attempt}}` | Current attempt number (0-based) |
-| `{{gaps}}` | Audit gaps from previous attempt (rework only) |
+| `{{tier}}` | Complexity tier (junior/medior/senior) |
+| `{{attempt}}` | Current attempt number |
+| `{{gaps}}` | Audit gaps from previous attempt |
+| `{{projectName}}` | Project name (planner prompts) |
+| `{{planSnapshot}}` | Current plan structure (planner prompts) |
+| `{{reviewModel}}` | Name of cross-model reviewer (planner review) |
+| `{{crossModelFeedback}}` | Review recommendations (planner review) |
 
-### Override Path
+### CLI
 
-```json
-{
-  "plugins": {
-    "entries": {
-      "openclaw-linear": {
-        "config": {
-          "promptsPath": "/path/to/my/prompts.yaml"
-        }
-      }
-    }
-  }
-}
+```bash
+openclaw openclaw-linear prompts show       # View current prompts
+openclaw openclaw-linear prompts path       # Show file path
+openclaw openclaw-linear prompts validate   # Check for errors
 ```
 
 ---
 
-## Notifications
+## Multi-Repo
 
-Dispatch lifecycle events fan out to any combination of OpenClaw channels -- Discord, Slack, Telegram, Signal, or any channel the runtime supports.
+Sometimes a feature touches more than one repo — your API and your frontend, for example. Multi-repo lets the agent work on both at the same time, in separate worktrees.
 
-### Configuration
+### Step 1: Tell the plugin where your repos live
 
-Add a `notifications` object to your plugin config:
+Add a `repos` map to your plugin config in `openclaw.json`. The **key** is a short name you pick, the **value** is the absolute path to that repo on disk:
 
 ```json
 {
@@ -553,15 +689,10 @@ Add a `notifications` object to your plugin config:
     "entries": {
       "openclaw-linear": {
         "config": {
-          "notifications": {
-            "targets": [
-              { "channel": "discord", "target": "1471743433566715974" },
-              { "channel": "slack", "target": "C0123456789", "accountId": "my-acct" },
-              { "channel": "telegram", "target": "-1003884997363" }
-            ],
-            "events": {
-              "auditing": false
-            }
+          "repos": {
+            "api": "/home/claw/repos/api",
+            "frontend": "/home/claw/repos/frontend",
+            "shared": "/home/claw/repos/shared-libs"
           }
         }
       }
@@ -570,162 +701,301 @@ Add a `notifications` object to your plugin config:
 }
 ```
 
-**`targets`** -- Array of notification destinations. Each target specifies:
+Restart the gateway after saving: `systemctl --user restart openclaw-gateway`
 
-| Field | Required | Description |
-|---|---|---|
-| `channel` | Yes | OpenClaw channel name: `discord`, `slack`, `telegram`, `signal`, etc. |
-| `target` | Yes | Channel/group/user ID to send to |
-| `accountId` | No | Account ID for multi-account setups (Slack) |
+### Step 1.5: Sync labels to Linear (optional)
 
-**`events`** -- Per-event-type toggles. All events are enabled by default. Set to `false` to suppress.
+If you plan to use labels (Method B below) to tag issues, run this to create the `repo:xxx` labels automatically:
 
-### Events
+```bash
+openclaw openclaw-linear repos sync
+```
 
-| Event | Kind | Example Message |
-|---|---|---|
-| Dispatch | `dispatch` | `API-123 dispatched -- Fix auth bug` |
-| Worker started | `working` | `API-123 worker started (attempt 0)` |
-| Audit in progress | `auditing` | `API-123 audit in progress` |
-| Audit passed | `audit_pass` | `API-123 passed audit. PR ready.` |
-| Audit failed | `audit_fail` | `API-123 failed audit (attempt 1). Gaps: no tests, missing validation` |
-| Escalation | `escalation` | `API-123 needs human review -- audit failed 3x` |
-| Stale detection | `stuck` | `API-123 stuck -- stale 2h` |
-| Watchdog kill | `watchdog_kill` | `API-123 killed by watchdog (no I/O for 120s). Retrying (attempt 0).` |
+This reads your `repos` config and creates matching labels (`repo:api`, `repo:frontend`, etc.) in every Linear team. To preview without creating anything:
 
-### Delivery
+```bash
+openclaw openclaw-linear repos check
+```
 
-Messages route through OpenClaw's native runtime channel API:
+The check command also validates your repo paths — it'll warn you if a path doesn't exist, isn't a git repo, or is a **submodule** (which won't work with multi-repo dispatch).
 
-- **Discord** -- `runtime.channel.discord.sendMessageDiscord()`
-- **Slack** -- `runtime.channel.slack.sendMessageSlack()` (passes `accountId` for multi-workspace)
-- **Telegram** -- `runtime.channel.telegram.sendMessageTelegram()` (silent mode)
-- **Signal** -- `runtime.channel.signal.sendMessageSignal()`
-- **Other** -- Falls back to `openclaw message send` CLI
+### Step 2: Tag the issue
 
-Failures are isolated per target -- one channel going down doesn't block the others.
+When you write an issue in Linear that needs multiple repos, tell the plugin which ones. Pick **one** of these methods:
 
-### Notify CLI
+#### Method A: HTML comment in the issue body (recommended)
 
-```bash
-openclaw openclaw-linear notify status                  # Show configured targets and suppressed events
-openclaw openclaw-linear notify test                    # Send test notification to all targets
-openclaw openclaw-linear notify test --channel discord  # Test only discord targets
-openclaw openclaw-linear notify setup                   # Interactive target setup
+Put this line anywhere in the issue description — it's invisible in Linear's UI:
+
+```
+<!-- repos: api, frontend -->
+```
+
+Full example of what an issue body might look like:
+
+```
+The search endpoint needs to be added to the API, and the frontend
+needs a new search page that calls it.
+
+<!-- repos: api, frontend -->
+
+Acceptance criteria:
+- GET /api/search?q=term returns results
+- /search page renders results with pagination
 ```
 
+#### Method B: Linear labels
+
+Create labels in Linear called `repo:api` and `repo:frontend`, then add them to the issue. The part after `repo:` must match the key in your config.
+
+#### Method C: Do nothing (config default)
+
+If you don't tag the issue at all, the plugin uses your `codexBaseRepo` setting (a single repo). This is how it worked before multi-repo existed — nothing changes for single-repo issues.
+
+### What happens when you dispatch
+
+When the agent picks up a multi-repo issue, the dispatch comment tells you:
+
+> **Dispatched** as **senior** (anthropic/claude-opus-4-6)
+>
+> Worktrees:
+> - `api` → `/home/claw/worktrees/ENG-100/api`
+> - `frontend` → `/home/claw/worktrees/ENG-100/frontend`
+>
+> Branch: `codex/ENG-100`
+
+The agent gets access to all the worktrees and can edit files across repos in one session. Each repo gets its own git branch.
+
+### Priority order
+
+If an issue has both a body marker and labels, the body marker wins. Full order:
+
+1. `<!-- repos: ... -->` in the issue body
+2. `repo:xxx` labels on the issue
+3. `codexBaseRepo` from config (single repo fallback)
+
+### Common mistakes
+
+| Problem | Fix |
+|---|---|
+| Agent only sees one repo | The name in `<!-- repos: api -->` must exactly match a key in your `repos` config. Check spelling. |
+| "Could not create worktree" error | The path in your `repos` config doesn't exist, or it's not a git repo. Run `ls /home/claw/repos/api/.git` to check. |
+| Comment marker not detected | Must be `<!-- repos: name1, name2 -->` with the exact format. No extra spaces around `<!--` or `-->`. |
+| Labels not picked up | Labels must be formatted `repo:name` (lowercase, no spaces). The `name` part must match a `repos` config key. |
+
 ---
 
-## Coding Tool (`code_run`)
+## Dispatch Management
 
-One tool dispatches to three CLI backends. Agents call `code_run` without knowing which backend is active.
+### Slash Commands
 
-### Supported Backends
+Type these in any agent session — they run instantly, no AI involved:
 
-| Backend | CLI | Stream Format | Key Flags |
-|---|---|---|---|
-| **Claude Code** (Anthropic) | `claude` | JSONL (`stream-json`) | `--print`, `--dangerously-skip-permissions` |
-| **Codex** (OpenAI) | `codex` | JSONL | `--full-auto`, `--ephemeral` |
-| **Gemini CLI** (Google) | `gemini` | JSONL (`stream-json`) | `--yolo`, `-o stream-json` |
+| Command | What it does |
+|---|---|
+| `/dispatch list` | Show all active dispatches with age, tier, status |
+| `/dispatch status CT-123` | Detailed info for one dispatch |
+| `/dispatch retry CT-123` | Re-run a stuck dispatch |
+| `/dispatch escalate CT-123 "needs review"` | Force a dispatch to stuck status |
 
-All three backends have inactivity watchdog protection. Each line of JSONL output ticks the watchdog timer. If a CLI goes silent beyond the configured threshold, the process is killed with SIGTERM (+ SIGKILL after 5s).
+### Gateway API
 
-### Backend Resolution Priority
+For programmatic access, the plugin registers these RPC methods:
 
-1. **Explicit `backend` parameter** -- Agent passes `backend: "gemini"` (or any alias)
-2. **Per-agent override** -- `agentCodingTools` in `coding-tools.json`
-3. **Global default** -- `codingTool` in `coding-tools.json`
-4. **Hardcoded fallback** -- `"claude"`
+| Method | What it does |
+|---|---|
+| `dispatch.list` | List dispatches (filterable by status, tier) |
+| `dispatch.get` | Get full dispatch details |
+| `dispatch.retry` | Re-dispatch a stuck issue |
+| `dispatch.escalate` | Force-stuck with a reason |
+| `dispatch.cancel` | Remove an active dispatch |
+| `dispatch.stats` | Counts by status and tier |
 
 ---
 
-## Inactivity Watchdog
+## Watchdog
+
+If an agent goes silent (LLM timeout, API hang, CLI lockup), the watchdog handles it automatically:
 
-Agent sessions can go silent when LLM providers rate-limit, APIs hang, or CLI tools lock up. The watchdog detects silence and kills stuck sessions.
+1. No output for `inactivitySec` → kill and retry once
+2. Second silence → escalate to stuck (you get notified, see [Stage 6](#stage-6-timeout-if-the-agent-goes-silent) above)
 
-### How It Works
+| Setting | Default | What it controls |
+|---|---|---|
+| `inactivitySec` | 120s | Kill if no output for this long |
+| `maxTotalSec` | 7200s (2 hrs) | Hard ceiling on total session time |
+| `toolTimeoutSec` | 600s (10 min) | Max time for a single `code_run` call |
 
-```mermaid
-flowchart TD
-    A[Agent starts] --> B["Watchdog timer starts<br/>(inactivitySec countdown)"]
-    B --> C{"I/O event?"}
-    C -->|"JSONL line, stderr,<br/>stream callback"| D[Timer resets]
-    D --> C
-    C -->|"No I/O for inactivitySec"| E[KILL]
-    E --> F[Retry once]
-    F -->|Success| G[Continue pipeline]
-    F -->|Killed again| H["STUCK (escalation)"]
-    B --> I{"Total runtime<br/>> maxTotalSec?"}
-    I -->|Yes| J["KILL (no retry)"]
+Configure per-agent in `agent-profiles.json` or globally in plugin config.
+
+---
+
+## Testing & Verification
+
+### Health check
+
+Run the doctor to verify your setup. It checks auth, config, prompts, connectivity, and dispatch health — and tells you exactly how to fix anything that's wrong:
+
+```bash
+openclaw openclaw-linear doctor
 ```
 
-### Three Timeout Dimensions
+Example output:
 
-| Timeout | Scope | Default | Description |
-|---------|-------|---------|-------------|
-| `inactivitySec` | Per I/O gap | 120s (2 min) | Kill if no stdout/stderr/callback for this long |
-| `maxTotalSec` | Per agent session | 7200s (2 hrs) | Hard ceiling on total session runtime |
-| `toolTimeoutSec` | Per `code_run` call | 600s (10 min) | Max runtime for a single CLI invocation |
+```
+┌──────────────────────────────────────────────┐
+│            Linear Plugin Doctor              │
+└──────────────────────────────────────────────┘
 
-### Config Resolution Order
+  Authentication & Tokens
+  ✔ Access token found (source: profile)
+  ✔ Token not expired (23h remaining)
+  ✔ API reachable — logged in as Test (TestOrg)
 
-1. **Agent profile** -- `~/.openclaw/agent-profiles.json` `agents.{id}.watchdog`
-2. **Plugin config** -- `openclaw.json` `inactivitySec` / `maxTotalSec` / `toolTimeoutSec`
-3. **Hardcoded defaults** -- 120s / 7200s / 600s
+  Agent Configuration
+  ✔ agent-profiles.json loaded (2 agents)
+  ✔ Default agent: coder
 
-### Per-Agent Configuration
+  Coding Tools
+  ✔ coding-tools.json loaded (default: codex)
+  ✔ codex: found at /usr/local/bin/codex
 
-```json
-{
-  "agents": {
-    "coder": {
-      "watchdog": {
-        "inactivitySec": 180,
-        "maxTotalSec": 7200,
-        "toolTimeoutSec": 900
-      }
-    },
-    "reviewer": {
-      "watchdog": {
-        "inactivitySec": 60,
-        "maxTotalSec": 600,
-        "toolTimeoutSec": 300
-      }
-    }
-  }
-}
+  Files & Directories
+  ✔ Dispatch state: 1 active, 5 completed
+  ✔ Prompts valid (5/5 sections, 4/4 variables)
+
+  Connectivity
+  ✔ Linear API reachable
+  ✔ Webhook gateway responding
+
+  Dispatch Health
+  ✔ No stale dispatches
+  ⚠ 2 completed dispatches older than 7 days
+    → Run: openclaw openclaw-linear doctor --fix to clean up
+
+  Summary: 11 passed, 1 warning, 0 errors
 ```
 
-### Artifact Logging
+Every warning and error includes a `→` line telling you what to do. Run `doctor --fix` to auto-repair what it can.
 
-Every dispatch writes structured artifacts to `.claw/` in the worktree:
+### Unit tests
 
+454 tests covering the full pipeline — triage, dispatch, audit, planning, intent classification, cross-model review, notifications, and infrastructure:
+
+```bash
+cd ~/claw-extensions/linear
+npx vitest run                   # Run all tests
+npx vitest run --reporter=verbose  # See every test name
+npx vitest run src/pipeline/     # Just pipeline tests
 ```
-.claw/
-  manifest.json       Issue metadata + lifecycle timestamps
-  plan.md             Implementation plan
-  worker-{N}.md       Worker output per attempt (truncated to 8KB)
-  audit-{N}.json      Audit verdict per attempt
-  log.jsonl           Append-only structured interaction log
-  summary.md          Agent-curated final summary
+
+### UAT (live integration tests)
+
+The UAT script runs against your real Linear workspace. It creates actual issues, triggers the pipeline, and verifies the results.
+
+```bash
+# Run all UAT scenarios
+npx tsx scripts/uat-linear.ts
+
+# Run a specific scenario
+npx tsx scripts/uat-linear.ts --test dispatch
+npx tsx scripts/uat-linear.ts --test planning
+npx tsx scripts/uat-linear.ts --test mention
+npx tsx scripts/uat-linear.ts --test intent
 ```
 
-Watchdog kills are logged to `log.jsonl` with phase `"watchdog"`:
+**What each scenario does:**
+
+#### `--test dispatch` (Single issue, full pipeline)
+
+1. Creates a test issue in Linear
+2. Assigns it to the agent
+3. Waits for the dispatch comment (confirms the agent picked it up)
+4. Waits for the audit result (pass, fail, or escalation)
+5. Reports success/failure with timing
+
+**Expected output:**
 
-```json
-{
-  "ts": "2026-02-18T12:00:00Z",
-  "phase": "watchdog",
-  "attempt": 0,
-  "agent": "coder",
-  "success": false,
-  "watchdog": {
-    "reason": "inactivity",
-    "silenceSec": 120,
-    "thresholdSec": 120,
-    "retried": true
-  }
-}
+```
+[dispatch] Created issue ENG-200: "UAT: simple config tweak"
+[dispatch] Assigned to agent — waiting for dispatch comment...
+[dispatch] ✔ Dispatch confirmed (12s) — assessed as junior
+[dispatch] Waiting for audit result...
+[dispatch] ✔ Audit passed (94s) — issue marked done
+[dispatch] Total: 106s
+```
+
+#### `--test planning` (Project planning flow)
+
+1. Creates a root issue in a test project
+2. Posts `plan this project` comment
+3. Waits for the planner's welcome message
+4. Posts feature requirements
+5. Waits for the planner to create issues
+6. Posts `finalize plan`
+7. Waits for plan approval or failure
+
+**Expected output:**
+
+```
+[planning] Created project "UAT Planning Test"
+[planning] Posted "plan this project" — waiting for welcome...
+[planning] ✔ Welcome received (8s)
+[planning] Posted feature description — waiting for response...
+[planning] ✔ Planner created 3 issues (15s)
+[planning] Posted "finalize plan" — waiting for audit...
+[planning] ✔ Plan approved (6s) — 3 issues queued for dispatch
+[planning] Total: 29s
+```
+
+#### `--test mention` (Agent routing)
+
+1. Creates a test issue
+2. Posts a comment mentioning a specific agent (e.g., `@kaylee`)
+3. Waits for that agent to respond
+4. Verifies the response came from the right agent
+
+**Expected output:**
+
+```
+[mention] Created issue ENG-201
+[mention] Posted "@kaylee analyze this issue"
+[mention] ✔ Kaylee responded (18s)
+[mention] Total: 18s
+```
+
+#### `--test intent` (Natural language routing)
+
+1. Creates a test issue and posts a question (no `@mention`)
+2. Verifies the bot responds (not silently dropped)
+3. Posts a comment with an agent name but no `@` prefix
+4. Verifies that agent responds
+5. Tests plan review flow with cross-model audit
+
+**Expected output:**
+
+```
+[intent] Created issue ENG-202
+[intent] Posted "what can I do with this?" — waiting for response...
+[intent] ✔ Bot responded to question (12s)
+[intent] Posted "hey kaylee analyze this" — waiting for response...
+[intent] ✔ Kaylee responded without @mention (15s)
+[intent] Total: 27s
+```
+
+### Verify notifications
+
+```bash
+openclaw openclaw-linear notify test              # Send test to all targets
+openclaw openclaw-linear notify test --channel discord  # Test one channel
+openclaw openclaw-linear notify status             # Show what's configured
+```
+
+### Verify prompts
+
+```bash
+openclaw openclaw-linear prompts validate   # Check for template errors
+openclaw openclaw-linear prompts show       # View the active prompts
 ```
 
 ---
@@ -733,20 +1003,39 @@ Watchdog kills are logged to `log.jsonl` with phase `"watchdog"`:
 ## CLI Reference
 
 ```bash
-openclaw openclaw-linear auth              # Run OAuth authorization
-openclaw openclaw-linear status            # Check connection and token status
-openclaw openclaw-linear worktrees         # List active worktrees
+# Auth & status
+openclaw openclaw-linear auth                      # Run OAuth flow
+openclaw openclaw-linear status                    # Check connection
+
+# Worktrees
+openclaw openclaw-linear worktrees                 # List active worktrees
 openclaw openclaw-linear worktrees --prune <path>  # Remove a worktree
-openclaw openclaw-linear prompts show      # Print current prompts
-openclaw openclaw-linear prompts path      # Print resolved prompts file path
-openclaw openclaw-linear prompts validate  # Validate prompt structure
-openclaw openclaw-linear notify status     # Show notification targets and event toggles
-openclaw openclaw-linear notify test       # Send test notification to all targets
-openclaw openclaw-linear notify test --channel slack  # Test specific channel only
-openclaw openclaw-linear notify setup      # Interactive notification target setup
-openclaw openclaw-linear doctor            # Run comprehensive health checks
-openclaw openclaw-linear doctor --fix      # Auto-fix safe issues
-openclaw openclaw-linear doctor --json     # Output results as JSON
+
+# Multi-repo
+openclaw openclaw-linear repos check               # Validate paths, preview labels
+openclaw openclaw-linear repos sync                # Create missing repo: labels in Linear
+
+# Prompts
+openclaw openclaw-linear prompts show              # View current prompts
+openclaw openclaw-linear prompts path              # Show file path
+openclaw openclaw-linear prompts validate          # Check for errors
+
+# Notifications
+openclaw openclaw-linear notify status             # Show targets & events
+openclaw openclaw-linear notify test               # Test all targets
+openclaw openclaw-linear notify test --channel discord  # Test one channel
+openclaw openclaw-linear notify setup              # Interactive setup
+
+# Dispatch
+/dispatch list                                     # Active dispatches
+/dispatch status <identifier>                      # Dispatch details
+/dispatch retry <identifier>                       # Re-run stuck dispatch
+/dispatch escalate <identifier> [reason]           # Force to stuck
+
+# Health
+openclaw openclaw-linear doctor                    # Run health checks
+openclaw openclaw-linear doctor --fix              # Auto-fix issues
+openclaw openclaw-linear doctor --json             # JSON output
 ```
 
 ---
@@ -759,25 +1048,34 @@ Quick checks:
 systemctl --user status openclaw-gateway        # Is the gateway running?
 openclaw openclaw-linear status                  # Is the token valid?
 journalctl --user -u openclaw-gateway -f         # Watch live logs
-linearis issues list -l 1                        # Is linearis authenticated?
-openclaw openclaw-linear prompts validate        # Are prompts valid?
 ```
 
 ### Common Issues
 
-| Problem | Cause | Fix |
-|---|---|---|
-| Agent goes silent, no response | LLM provider timeout or rate limit | Watchdog auto-kills after `inactivitySec` and retries. Check logs for `Watchdog KILL`. |
-| Dispatch stuck after watchdog | Both retry attempts failed | Check `.claw/log.jsonl` for watchdog entries. Re-assign issue to retry. |
-| Agent says "closing" but doesn't | No issue management tool | Install `linearis`: `npx clawhub install linearis` |
-| `code_run` uses wrong backend | Config mismatch | Check `coding-tools.json` |
-| Claude Code "nested session" error | `CLAUDECODE` env var set | Plugin handles this automatically |
-| Gateway rejects plugin config keys | Strict validator | Custom config goes in `coding-tools.json` |
-| Webhook events not arriving | Wrong URL | Both webhooks must point to `/linear/webhook` |
-| OAuth token expired | Tokens expire ~24h | Auto-refreshes; restart gateway if stuck |
-| Audit always fails | Bad prompt template | Run `openclaw openclaw-linear prompts validate` |
-
-See [docs/troubleshooting.md](docs/troubleshooting.md) for detailed diagnostic commands.
+| Problem | Fix |
+|---|---|
+| Agent goes silent | Watchdog auto-kills after `inactivitySec` and retries. Check logs for `Watchdog KILL`. |
+| Dispatch stuck after watchdog | Both retries failed. Check `.claw/log.jsonl`. Re-assign issue to restart. |
+| `code_run` uses wrong backend | Check `coding-tools.json` — explicit backend > per-agent > global default. |
+| Webhook events not arriving | Both webhooks must point to `/linear/webhook`. Check tunnel is running. |
+| OAuth token expired | Auto-refreshes. If stuck, re-run `openclaw openclaw-linear auth` and restart. |
+| Audit always fails | Run `openclaw openclaw-linear prompts validate` to check prompt syntax. |
+| Multi-repo not detected | Markers must be `<!-- repos: name1, name2 -->`. Names must match `repos` config keys. |
+| `/dispatch` not responding | Restart gateway. Check plugin loaded with `openclaw doctor`. |
+| Comments ignored (no response) | Check logs for intent classification results. If classifier fails, regex fallback may not match. |
+| Intent classifier slow | Set `classifierAgentId` to a small model agent (Haiku). Default uses your primary model. |
+| Cross-model review fails | The reviewer model CLI must be installed. Check logs for "cross-model review unavailable". |
+| Rich notifications are plain text | Set `"richFormat": true` in notifications config. |
+| Gateway rejects config keys | Strict validator. Run `openclaw doctor --fix`. |
+
+For detailed diagnostics, see [docs/troubleshooting.md](docs/troubleshooting.md).
+
+---
+
+## Further Reading
+
+- [Architecture](docs/architecture.md) — Internal design, state machines, diagrams
+- [Troubleshooting](docs/troubleshooting.md) — Diagnostic commands, curl examples, log analysis
 
 ---