@calltelemetry/openclaw-linear 0.6.1 → 0.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 CallTelemetry, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -39,8 +39,9 @@ An OpenClaw plugin that connects Linear to AI agents. Issues get triaged automat
 | **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 |
-| **Customizable prompts** | `prompts.yaml` -- edit worker, audit, and rework prompts without rebuilding |
-| **Discord notifications** | Dispatch lifecycle events posted to a Discord channel |
+| **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 |
 
 ---
@@ -74,6 +75,12 @@ sequenceDiagram
     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
 ```
 
 ---
@@ -122,6 +129,23 @@ stateDiagram-v2
 
 All transitions use compare-and-swap (CAS) to prevent races. `dispatch-state.json` is the canonical source of truth.
 
+### Project Planner Pipeline
+
+When `@ctclaw plan this project` is commented on a root issue, the plugin enters planning mode:
+
+```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"]
+```
+
+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.
+
 ### Webhook Event Router
 
 ```mermaid
@@ -129,7 +153,7 @@ 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"]
+    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"]
@@ -180,7 +204,9 @@ openclaw-linear/
     |   |-- 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
+    |   |-- 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
@@ -193,7 +219,8 @@ openclaw-linear/
     |   |-- 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
+    |   |-- 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
@@ -203,7 +230,7 @@ openclaw-linear/
     +-- infra/                 Infrastructure utilities
         |-- cli.ts                 CLI subcommands (auth, status, worktrees, prompts)
         |-- codex-worktree.ts      Git worktree create/remove/status/PR helpers
-        +-- notify.ts              Discord notifier (+ noop fallback)
+        +-- notify.ts              Multi-channel notifier (Discord, Slack, Telegram, Signal)
 ```
 
 ---
@@ -401,6 +428,9 @@ Once set up, the plugin responds to Linear events automatically:
 | 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"` |
 
@@ -435,7 +465,7 @@ Set in `openclaw.json` under the plugin entry:
 | `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 |
-| `flowDiscordChannel` | string | -- | Discord channel ID for notifications |
+| `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 |
@@ -511,17 +541,78 @@ openclaw openclaw-linear prompts validate   # Validate structure and template va
 
 ## Notifications
 
-Configure `flowDiscordChannel` in plugin config with a Discord channel ID. Events:
+Dispatch lifecycle events fan out to any combination of OpenClaw channels -- Discord, Slack, Telegram, Signal, or any channel the runtime supports.
 
-| Event | Message |
-|---|---|
-| Dispatch | `**API-123** dispatched -- Fix auth bug` |
-| Worker started | `**API-123** worker started (attempt 0)` |
-| Audit in progress | `**API-123** audit in progress` |
-| Audit passed | `**API-123** passed audit. PR ready.` |
-| Audit failed | `**API-123** failed audit (attempt 1). Gaps: ...` |
-| Escalation | `**API-123** needs human review -- audit failed 3x` |
-| Watchdog kill | `**API-123** killed by watchdog (no I/O for 120s). Retrying.` |
+### Configuration
+
+Add a `notifications` object to your plugin config:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-linear": {
+        "config": {
+          "notifications": {
+            "targets": [
+              { "channel": "discord", "target": "1471743433566715974" },
+              { "channel": "slack", "target": "C0123456789", "accountId": "my-acct" },
+              { "channel": "telegram", "target": "-1003884997363" }
+            ],
+            "events": {
+              "auditing": false
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**`targets`** -- Array of notification destinations. Each target specifies:
+
+| 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) |
+
+**`events`** -- Per-event-type toggles. All events are enabled by default. Set to `false` to suppress.
+
+### Events
+
+| 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).` |
+
+### Delivery
+
+Messages route through OpenClaw's native runtime channel API:
+
+- **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
+
+Failures are isolated per target -- one channel going down doesn't block the others.
+
+### Notify CLI
+
+```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
+```
 
 ---
 
@@ -649,6 +740,13 @@ 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
 ```
 
 ---

package/index.ts

@@ -7,9 +7,15 @@ import { handleLinearWebhook } from "./src/pipeline/webhook.js";
 import { handleOAuthCallback } from "./src/api/oauth-callback.js";
 import { LinearAgentApi, resolveLinearToken } from "./src/api/linear-api.js";
 import { createDispatchService } from "./src/pipeline/dispatch-service.js";
+import { registerDispatchMethods } from "./src/gateway/dispatch-methods.js";
 import { readDispatchState, lookupSessionMapping, getActiveDispatch } from "./src/pipeline/dispatch-state.js";
 import { triggerAudit, processVerdict, type HookContext } from "./src/pipeline/pipeline.js";
-import { createDiscordNotifier, createNoopNotifier, type NotifyFn } from "./src/infra/notify.js";
+import { createNotifierFromConfig, type NotifyFn } from "./src/infra/notify.js";
+import { readPlanningState, setPlanningCache } from "./src/pipeline/planning-state.js";
+import { createPlannerTools } from "./src/tools/planner-tools.js";
+import { registerDispatchCommands } from "./src/infra/commands.js";
+import { createDispatchHistoryTool } from "./src/tools/dispatch-history-tool.js";
+import { readDispatchState as readStateForHook, listActiveDispatches as listActiveForHook } from "./src/pipeline/dispatch-state.js";
 
 export default function register(api: OpenClawPluginApi) {
   const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
@@ -36,6 +42,15 @@ export default function register(api: OpenClawPluginApi) {
     return createLinearTools(api, ctx);
   });
 
+  // Register planner tools (context injected at runtime via setActivePlannerContext)
+  api.registerTool(() => createPlannerTools());
+
+  // Register dispatch_history tool for agent context
+  api.registerTool(() => createDispatchHistoryTool(api, pluginConfig));
+
+  // Register zero-LLM slash commands for dispatch ops
+  registerDispatchCommands(api);
+
   // Register Linear webhook handler on a dedicated route
   api.registerHttpRoute({
     path: "/linear/webhook",
@@ -63,31 +78,25 @@ export default function register(api: OpenClawPluginApi) {
   // Register dispatch monitor service (stale detection, session hydration, cleanup)
   api.registerService(createDispatchService(api));
 
+  // Register dispatch gateway RPC methods (list, get, retry, escalate, cancel, stats)
+  registerDispatchMethods(api);
+
+  // Hydrate planning state on startup
+  readPlanningState(pluginConfig?.planningStatePath as string | undefined).then((state) => {
+    for (const session of Object.values(state.sessions)) {
+      if (session.status === "interviewing" || session.status === "plan_review") {
+        setPlanningCache(session);
+        api.logger.info(`Planning: restored session for ${session.projectName} (${session.rootIdentifier})`);
+      }
+    }
+  }).catch((err) => api.logger.warn(`Planning state hydration failed: ${err}`));
+
   // ---------------------------------------------------------------------------
   // Dispatch pipeline v2: notifier + agent_end lifecycle hook
   // ---------------------------------------------------------------------------
 
-  // Instantiate notifier (Discord if configured, otherwise noop)
-  const discordBotToken = (() => {
-    try {
-      const config = JSON.parse(
-        require("node:fs").readFileSync(
-          require("node:path").join(process.env.HOME ?? "/home/claw", ".openclaw", "openclaw.json"),
-          "utf8",
-        ),
-      );
-      return config?.channels?.discord?.token as string | undefined;
-    } catch { return undefined; }
-  })();
-  const flowDiscordChannel = pluginConfig?.flowDiscordChannel as string | undefined;
-
-  const notify: NotifyFn = (discordBotToken && flowDiscordChannel)
-    ? createDiscordNotifier(discordBotToken, flowDiscordChannel)
-    : createNoopNotifier();
-
-  if (flowDiscordChannel && discordBotToken) {
-    api.logger.info(`Linear dispatch: Discord notifications enabled (channel: ${flowDiscordChannel})`);
-  }
+  // Instantiate notifier (Discord, Slack, or both — config-driven)
+  const notify: NotifyFn = createNotifierFromConfig(pluginConfig, api.runtime);
 
   // Register agent_end hook — safety net for sessions_spawn sub-agents.
   // In the current implementation, the worker→audit→verdict flow runs inline
@@ -163,6 +172,32 @@ export default function register(api: OpenClawPluginApi) {
     }
   });
 
+  // Inject recent dispatch history as context for worker/audit agents
+  api.on("before_agent_start", async (event: any, ctx: any) => {
+    try {
+      const sessionKey = ctx?.sessionKey ?? "";
+      if (!sessionKey.startsWith("linear-worker-") && !sessionKey.startsWith("linear-audit-")) return;
+
+      const statePath = pluginConfig?.dispatchStatePath as string | undefined;
+      const state = await readStateForHook(statePath);
+      const active = listActiveForHook(state);
+
+      // Include up to 3 recent active dispatches as context
+      const recent = active.slice(0, 3);
+      if (recent.length === 0) return;
+
+      const lines = recent.map(d =>
+        `- **${d.issueIdentifier}** (${d.tier}): ${d.status}, attempt ${d.attempt}`
+      );
+
+      return {
+        prependContext: `<dispatch-history>\nActive dispatches:\n${lines.join("\n")}\n</dispatch-history>\n\n`,
+      };
+    } catch {
+      // Never block agent start for telemetry
+    }
+  });
+
   // Narration Guard: catch short "Let me explore..." responses that narrate intent
   // without actually calling tools, and append a warning for the user.
   const NARRATION_PATTERNS = [

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "openclaw-linear",
   "name": "Linear Agent",
   "description": "Linear integration with OAuth support, agent pipeline, and webhook-driven AI agent lifecycle",
-  "version": "0.2.0",
+  "version": "0.7.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -15,12 +15,45 @@
       "defaultAgentId": { "type": "string", "description": "OpenClaw agent ID to use for pipeline stages" },
       "enableAudit": { "type": "boolean", "description": "Run auditor stage after implementation", "default": true },
       "codexBaseRepo": { "type": "string", "description": "Path to git repo for Codex worktrees", "default": "/home/claw/ai-workspace" },
-      "codexModel": { "type": "string", "description": "Default Codex model (optional — uses Codex default if omitted)" },
-      "codexTimeoutMs": { "type": "number", "description": "Default Codex timeout in milliseconds", "default": 600000 },
       "enableOrchestration": { "type": "boolean", "description": "Allow agents to spawn sub-agents via spawn_agent/ask_agent tools", "default": true },
       "worktreeBaseDir": { "type": "string", "description": "Base directory for persistent git worktrees (default: ~/.openclaw/worktrees)" },
+      "repos": { "type": "object", "description": "Multi-repo map (name → path, e.g. {\"api\": \"/home/claw/api\", \"frontend\": \"/home/claw/frontend\"})", "additionalProperties": { "type": "string" } },
       "dispatchStatePath": { "type": "string", "description": "Path to dispatch state JSON file (default: ~/.openclaw/linear-dispatch-state.json)" },
-      "flowDiscordChannel": { "type": "string", "description": "Discord channel ID for dispatch lifecycle notifications (omit to disable)" },
+      "planningStatePath": { "type": "string", "description": "Path to planning state JSON file (default: ~/.openclaw/linear-planning-state.json)" },
+      "notifications": {
+        "type": "object",
+        "description": "Dispatch lifecycle notification config — fan-out to any combination of channels",
+        "properties": {
+          "targets": {
+            "type": "array",
+            "description": "Notification targets — each routes to an OpenClaw channel",
+            "items": {
+              "type": "object",
+              "required": ["channel", "target"],
+              "properties": {
+                "channel": { "type": "string", "description": "OpenClaw channel name: discord, slack, telegram, signal, etc." },
+                "target": { "type": "string", "description": "Channel/group/user ID to send to" },
+                "accountId": { "type": "string", "description": "Account ID for multi-account channel setups (optional)" }
+              }
+            }
+          },
+          "events": {
+            "type": "object",
+            "description": "Per-event-type toggles (all default true, set false to suppress)",
+            "properties": {
+              "dispatch": { "type": "boolean" },
+              "working": { "type": "boolean" },
+              "auditing": { "type": "boolean" },
+              "audit_pass": { "type": "boolean" },
+              "audit_fail": { "type": "boolean" },
+              "escalation": { "type": "boolean" },
+              "stuck": { "type": "boolean" },
+              "watchdog_kill": { "type": "boolean" }
+            }
+          },
+          "richFormat": { "type": "boolean", "description": "Send rich embeds (Discord) and HTML (Telegram) instead of plain text", "default": false }
+        }
+      },
       "promptsPath": { "type": "string", "description": "Override path for prompts.yaml (default: ships with plugin)" },
       "maxReworkAttempts": { "type": "number", "description": "Max audit failures before escalation", "default": 2 },
       "inactivitySec": { "type": "number", "description": "Kill sessions with no I/O for this many seconds (default: 120)", "default": 120 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calltelemetry/openclaw-linear",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "Linear Agent plugin for OpenClaw — webhook-driven AI pipeline with OAuth, multi-agent routing, and issue triage",
   "type": "module",
   "license": "MIT",
@@ -45,6 +45,7 @@
     ]
   },
   "dependencies": {
+    "cockatiel": "^3.2.1",
     "yaml": "^2.8.2"
   }
 }

package/prompts.yaml

@@ -77,3 +77,50 @@ rework:
 
     Address these specific issues in your rework. Focus on the gaps listed above.
     Remember: you do NOT have linearis access. Just fix the code and return a text summary.
+
+planner:
+  system: |
+    You are a product planning specialist working with Linear. Your job is to interview
+    the user about features they want to build, then decompose them into a well-structured
+    project with epics, issues, and sub-issues connected by a dependency graph.
+
+    STRUCTURE RULES:
+    - Epics are high-level feature areas. Mark them with isEpic=true.
+    - Issues under epics are concrete deliverables with acceptance criteria.
+    - Sub-issues are atomic work units that together complete a parent issue.
+    - Use "blocks" relationships to express ordering: if A must finish before B starts, A blocks B.
+    - Every issue description must include clear acceptance criteria.
+    - Every non-epic issue needs a story point estimate and priority.
+
+    INTERVIEW APPROACH:
+    - Ask ONE focused question at a time. Never dump a questionnaire.
+    - After each user response, create or update issues to capture what you learned.
+    - Briefly summarize what you added before asking your next question.
+    - When the plan feels complete, invite the user to say "finalize plan".
+
+  interview: |
+    ## Project: {{projectName}} ({{rootIdentifier}})
+
+    ### Current Plan
+    {{planSnapshot}}
+
+    ### Recent conversation ({{turnCount}} turns so far)
+    {{commentHistory}}
+
+    ### User just said:
+    > {{userMessage}}
+
+    Continue the planning interview. Use your tools to create/update Linear issues based
+    on the user's input, then respond with a summary of changes and your next question.
+
+  audit_prompt: |
+    The user wants to finalize the plan for {{projectName}}. Run the `audit_plan` tool.
+    If it passes, congratulate and summarize the complete plan.
+    If it fails, list the specific issues that need attention and ask the user to help.
+
+  welcome: |
+    I'm entering planning mode for **{{projectName}}**. I'll interview you about the
+    features you want to build, then structure everything into Linear issues with proper
+    epic hierarchy and dependency chains.
+
+    Let's start — what is this project about, and what are the main feature areas?