@calltelemetry/openclaw-linear 0.9.11 → 0.9.14

package/README.md

@@ -847,6 +847,7 @@ Add settings under the plugin entry in `openclaw.json`:
 | `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)) |
+| `projectName` | string | — | Human-readable project name (injected into agent prompts) |
 | `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 |
@@ -1044,6 +1045,17 @@ Guidance is cached per-team (24h TTL) so comment webhooks (which don't carry gui
 }
 ```
 
+### Project Context — CLAUDE.md & AGENTS.md
+
+Agents are instructed to read two files from the repo root before starting work:
+
+- **CLAUDE.md** — Project conventions, tech stack, build/test commands, architecture. This is the same convention used by Claude Code and other AI coding tools.
+- **AGENTS.md** — Behavioral guidelines, code style rules, workflow conventions (branch naming, commit format, etc.).
+
+These files are the primary way agents learn about your project. Without them, agents will explore the codebase but may miss conventions.
+
+Run `openclaw openclaw-linear doctor` to check if these files exist. The doctor output includes templates to get started.
+
 ### Example Custom Prompts
 
 ```yaml
@@ -1083,6 +1095,7 @@ rework:
 | `{{reviewModel}}` | Name of cross-model reviewer (planner review) |
 | `{{crossModelFeedback}}` | Review recommendations (planner review) |
 | `{{guidance}}` | Linear workspace/team guidance (if available, empty string otherwise) |
+| `{{projectContext}}` | Project context from config (project name, repo paths). Framework/build/test info belongs in CLAUDE.md. |
 
 ### CLI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calltelemetry/openclaw-linear",
-  "version": "0.9.11",
+  "version": "0.9.14",
   "description": "Linear Agent plugin for OpenClaw — webhook-driven AI pipeline with OAuth, multi-agent routing, and issue triage",
   "type": "module",
   "license": "MIT",

package/prompts.yaml

@@ -1,7 +1,8 @@
 # prompts.yaml — Externalized phase prompts for the Linear dispatch pipeline.
 #
 # Template variables: {{identifier}}, {{title}}, {{description}},
-#   {{worktreePath}}, {{gaps}}, {{tier}}, {{attempt}}, {{guidance}}
+#   {{worktreePath}}, {{gaps}}, {{tier}}, {{attempt}}, {{guidance}},
+#   {{projectContext}}
 #
 # Edit these to customize worker/audit behavior without rebuilding the plugin.
 # Override path via `promptsPath` in plugin config.
@@ -25,16 +26,24 @@ worker:
     {{description}}
 
     Worktree: {{worktreePath}}
+    {{projectContext}}
+
+    Before writing any code, read these files in the worktree root (if they exist):
+    - CLAUDE.md — project conventions, tech stack, build/test commands, architecture
+    - AGENTS.md — behavioral guidelines, code style, workflow rules
+    These files are your primary source of truth for how this project works.
+    If they don't exist, explore the codebase to understand conventions before coding.
 
     Instructions:
     1. Read the issue body carefully — it defines what needs to be done
     2. If the description is vague or missing, implement a reasonable interpretation and note your assumptions
-    3. Plan your approach
-    4. Implement the solution in the worktree
-    5. Run tests to verify your changes
-    6. If tests fail, diagnose and fix the failures before returning — do not return with failing tests unless you've exhausted your ability to fix them
-    7. Commit your work with a clear commit message
-    8. Return a text summary: what you changed, what tests passed, any assumptions you made, and any open questions
+    3. Read CLAUDE.md and AGENTS.md in the worktree, then explore the codebase to understand the existing architecture
+    4. Plan your approach
+    5. Implement the solution in the worktree
+    6. Run tests to verify your changes
+    7. If tests fail, diagnose and fix the failures before returning — do not return with failing tests unless you've exhausted your ability to fix them
+    8. Commit your work with a clear commit message
+    9. Return a text summary: what you changed, what tests passed, any assumptions you made, and any open questions
 
     Your text output will be captured automatically. Do NOT use linear_issues or attempt to post comments.
     {{guidance}}
@@ -60,6 +69,12 @@ audit:
     {{description}}
 
     Worktree: {{worktreePath}}
+    {{projectContext}}
+
+    Before auditing, read these files in the worktree root (if they exist):
+    - CLAUDE.md — project conventions, tech stack, build/test commands
+    - AGENTS.md — behavioral guidelines, code style, workflow rules
+    These define the project's standards. Use them to evaluate code quality.
 
     Checklist:
     1. Identify ALL acceptance criteria from the issue body

package/src/__test__/fixtures/recorded-sub-issue-flow.ts

@@ -2,7 +2,7 @@
  * Recorded API responses from sub-issue decomposition smoke test.
  * Auto-generated — do not edit manually.
  * Re-generate by running: npx vitest run src/__test__/smoke-linear-api.test.ts
- * Last recorded: 2026-02-22T02:38:53.901Z
+ * Last recorded: 2026-02-22T03:40:54.418Z
  */
 
 export const RECORDED = {
@@ -44,20 +44,20 @@ export const RECORDED = {
     }
   ],
   "createParent": {
-    "id": "953324f8-878f-40ba-b773-8d8815ee7987",
-    "identifier": "UAT-320"
+    "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
+    "identifier": "UAT-438"
   },
   "createSubIssue1": {
-    "id": "69ce9a01-3bdb-4f4a-a882-e28e23d1b628",
-    "identifier": "UAT-321"
+    "id": "4caa7593-5a51-4795-b98c-29e532589dfe",
+    "identifier": "UAT-439"
   },
   "createSubIssue2": {
-    "id": "b39cc5eb-ec05-44aa-917b-562a290ecab6",
-    "identifier": "UAT-322"
+    "id": "0519065b-95eb-4752-966b-2099bbc5f3d1",
+    "identifier": "UAT-440"
   },
   "subIssue1Details": {
-    "id": "69ce9a01-3bdb-4f4a-a882-e28e23d1b628",
-    "identifier": "UAT-321",
+    "id": "4caa7593-5a51-4795-b98c-29e532589dfe",
+    "identifier": "UAT-439",
     "title": "[SMOKE TEST] Sub-Issue 1: Backend API",
     "description": "Implement the backend search API endpoint.\n\nGiven a search query, when the API is called, then matching results are returned.",
     "estimate": 2,
@@ -83,16 +83,16 @@ export const RECORDED = {
     },
     "project": null,
     "parent": {
-      "id": "953324f8-878f-40ba-b773-8d8815ee7987",
-      "identifier": "UAT-320"
+      "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
+      "identifier": "UAT-438"
     },
     "relations": {
       "nodes": []
     }
   },
   "subIssue2Details": {
-    "id": "b39cc5eb-ec05-44aa-917b-562a290ecab6",
-    "identifier": "UAT-322",
+    "id": "0519065b-95eb-4752-966b-2099bbc5f3d1",
+    "identifier": "UAT-440",
     "title": "[SMOKE TEST] Sub-Issue 2: Frontend UI",
     "description": "Build the frontend search UI component.\n\nGiven the search page loads, when the user types a query, then results display in real-time.",
     "estimate": 3,
@@ -118,18 +118,18 @@ export const RECORDED = {
     },
     "project": null,
     "parent": {
-      "id": "953324f8-878f-40ba-b773-8d8815ee7987",
-      "identifier": "UAT-320"
+      "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
+      "identifier": "UAT-438"
     },
     "relations": {
       "nodes": []
     }
   },
   "parentDetails": {
-    "id": "953324f8-878f-40ba-b773-8d8815ee7987",
-    "identifier": "UAT-320",
+    "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
+    "identifier": "UAT-438",
     "title": "[SMOKE TEST] Sub-Issue Parent: Search Feature",
-    "description": "Auto-generated by smoke test to verify sub-issue decomposition.\n\nThis parent issue should have two sub-issues created under it.\n\nCreated: 2026-02-22T02:38:52.132Z",
+    "description": "Auto-generated by smoke test to verify sub-issue decomposition.\n\nThis parent issue should have two sub-issues created under it.\n\nCreated: 2026-02-22T03:40:52.229Z",
     "estimate": null,
     "state": {
       "name": "Backlog",
@@ -149,7 +149,13 @@ export const RECORDED = {
       "issueEstimationType": "tShirt"
     },
     "comments": {
-      "nodes": []
+      "nodes": [
+        {
+          "body": "This thread is for an agent session with ctclaw.",
+          "user": null,
+          "createdAt": "2026-02-22T03:40:53.165Z"
+        }
+      ]
     },
     "project": null,
     "parent": null,
@@ -158,11 +164,11 @@ export const RECORDED = {
     }
   },
   "createRelation": {
-    "id": "9207d26d-d65d-45a2-ac76-b9233acea181"
+    "id": "185dfd6c-362e-48a4-b717-e900407ced84"
   },
   "subIssue1WithRelation": {
-    "id": "69ce9a01-3bdb-4f4a-a882-e28e23d1b628",
-    "identifier": "UAT-321",
+    "id": "4caa7593-5a51-4795-b98c-29e532589dfe",
+    "identifier": "UAT-439",
     "title": "[SMOKE TEST] Sub-Issue 1: Backend API",
     "description": "Implement the backend search API endpoint.\n\nGiven a search query, when the API is called, then matching results are returned.",
     "estimate": 2,
@@ -184,20 +190,26 @@ export const RECORDED = {
       "issueEstimationType": "tShirt"
     },
     "comments": {
-      "nodes": []
+      "nodes": [
+        {
+          "body": "This thread is for an agent session with ctclaw.",
+          "user": null,
+          "createdAt": "2026-02-22T03:40:53.603Z"
+        }
+      ]
     },
     "project": null,
     "parent": {
-      "id": "953324f8-878f-40ba-b773-8d8815ee7987",
-      "identifier": "UAT-320"
+      "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
+      "identifier": "UAT-438"
     },
     "relations": {
       "nodes": [
         {
           "type": "blocks",
           "relatedIssue": {
-            "id": "b39cc5eb-ec05-44aa-917b-562a290ecab6",
-            "identifier": "UAT-322",
+            "id": "0519065b-95eb-4752-966b-2099bbc5f3d1",
+            "identifier": "UAT-440",
             "title": "[SMOKE TEST] Sub-Issue 2: Frontend UI"
           }
         }
@@ -205,8 +217,8 @@ export const RECORDED = {
     }
   },
   "subIssue2WithRelation": {
-    "id": "b39cc5eb-ec05-44aa-917b-562a290ecab6",
-    "identifier": "UAT-322",
+    "id": "0519065b-95eb-4752-966b-2099bbc5f3d1",
+    "identifier": "UAT-440",
     "title": "[SMOKE TEST] Sub-Issue 2: Frontend UI",
     "description": "Build the frontend search UI component.\n\nGiven the search page loads, when the user types a query, then results display in real-time.",
     "estimate": 3,
@@ -232,14 +244,14 @@ export const RECORDED = {
         {
           "body": "This thread is for an agent session with ctclaw.",
           "user": null,
-          "createdAt": "2026-02-22T02:38:53.699Z"
+          "createdAt": "2026-02-22T03:40:53.840Z"
         }
       ]
     },
     "project": null,
     "parent": {
-      "id": "953324f8-878f-40ba-b773-8d8815ee7987",
-      "identifier": "UAT-320"
+      "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
+      "identifier": "UAT-438"
     },
     "relations": {
       "nodes": []

package/src/__test__/smoke-linear-api.test.ts

@@ -14,6 +14,7 @@ import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { LinearAgentApi } from "../api/linear-api.js";
+import { createLinearIssuesTool } from "../tools/linear-issues-tool.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -684,6 +685,147 @@ describe("Linear API smoke tests", () => {
     });
   });
 
+  // ---------------------------------------------------------------------------
+  // Tool-level sub-issue creation (linear_issues tool)
+  // ---------------------------------------------------------------------------
+
+  describe("tool-level sub-issue creation (linear_issues tool)", () => {
+    let toolParentIdentifier: string | null = null;
+    let toolSubIdentifier: string | null = null;
+    let toolParentId: string | null = null;
+    let toolSubId: string | null = null;
+    let tool: any;
+
+    function parseToolResult(result: any): any {
+      if (result?.content && Array.isArray(result.content)) {
+        const textBlock = result.content.find((r: any) => r.type === "text");
+        if (textBlock) return JSON.parse(textBlock.text);
+      }
+      if (result?.details) return result.details;
+      return typeof result === "string" ? JSON.parse(result) : result;
+    }
+
+    it("instantiates linear_issues tool with real credentials", () => {
+      const apiKey = loadApiKey();
+      const pluginApi = {
+        logger: {
+          info: (...args: any[]) => console.log("[tool-smoke]", ...args),
+          warn: (...args: any[]) => console.warn("[tool-smoke]", ...args),
+          error: (...args: any[]) => console.error("[tool-smoke]", ...args),
+          debug: () => {},
+        },
+        pluginConfig: { accessToken: apiKey },
+      };
+      tool = createLinearIssuesTool(pluginApi as any);
+      expect(tool).toBeTruthy();
+      expect(tool.name).toBe("linear_issues");
+    });
+
+    it("creates a parent issue via tool action=create", async () => {
+      const result = parseToolResult(
+        await tool.execute("smoke-call-1", {
+          action: "create",
+          title: "[SMOKE TEST] Tool Sub-Issue Parent",
+          description:
+            "Auto-generated by tool-level smoke test.\n" +
+            "Tests linear_issues tool can create parent + sub-issues.\n\n" +
+            `Created: ${new Date().toISOString()}`,
+          teamId: TEAM_ID,
+          priority: 4,
+        }),
+      );
+
+      expect(result.error).toBeUndefined();
+      expect(result.success).toBe(true);
+      expect(result.identifier).toBeTruthy();
+      expect(result.id).toBeTruthy();
+
+      toolParentIdentifier = result.identifier;
+      toolParentId = result.id;
+      console.log(`Tool created parent: ${result.identifier} (${result.id})`);
+    });
+
+    it("reads parent issue via tool action=read (by identifier)", async () => {
+      expect(toolParentIdentifier).toBeTruthy();
+
+      const result = parseToolResult(
+        await tool.execute("smoke-call-2", {
+          action: "read",
+          issueId: toolParentIdentifier!,
+        }),
+      );
+
+      expect(result.error).toBeUndefined();
+      expect(result.identifier).toBe(toolParentIdentifier);
+      expect(result.title).toContain("[SMOKE TEST]");
+      expect(result.team.id).toBe(TEAM_ID);
+      expect(result.parent).toBeNull();
+      console.log(`Tool read parent: ${result.identifier} (status=${result.status})`);
+    });
+
+    it("creates a sub-issue via tool action=create with parentIssueId (identifier)", async () => {
+      expect(toolParentIdentifier).toBeTruthy();
+
+      const result = parseToolResult(
+        await tool.execute("smoke-call-3", {
+          action: "create",
+          title: "[SMOKE TEST] Tool Sub-Issue: Backend work",
+          description:
+            "Sub-issue created via linear_issues tool with parentIssueId.\n" +
+            "Verifies identifier → UUID resolution and teamId inheritance.",
+          parentIssueId: toolParentIdentifier!,
+          priority: 3,
+          estimate: 2,
+        }),
+      );
+
+      expect(result.error).toBeUndefined();
+      expect(result.success).toBe(true);
+      expect(result.identifier).toBeTruthy();
+      expect(result.id).toBeTruthy();
+      expect(result.parentIssueId).toBe(toolParentIdentifier);
+
+      toolSubIdentifier = result.identifier;
+      toolSubId = result.id;
+      console.log(`Tool created sub-issue: ${result.identifier} (parent=${toolParentIdentifier})`);
+    });
+
+    it("verifies sub-issue has correct parent via tool action=read", async () => {
+      expect(toolSubIdentifier).toBeTruthy();
+
+      const result = parseToolResult(
+        await tool.execute("smoke-call-4", {
+          action: "read",
+          issueId: toolSubIdentifier!,
+        }),
+      );
+
+      expect(result.error).toBeUndefined();
+      expect(result.identifier).toBe(toolSubIdentifier);
+      expect(result.parent).not.toBeNull();
+      expect(result.parent.identifier).toBe(toolParentIdentifier);
+      // teamId was inherited from parent (not provided explicitly in create)
+      expect(result.team.id).toBe(TEAM_ID);
+      console.log(`Tool sub-issue parent confirmed: ${result.parent.identifier}`);
+    });
+
+    it("cleans up: cancels tool-created issues", async () => {
+      const states = await api.getTeamStates(TEAM_ID);
+      const canceledState = states.find(
+        (s) => s.type === "canceled" || s.name.toLowerCase().includes("cancel"),
+      );
+
+      for (const id of [toolSubId, toolParentId]) {
+        if (!id || !canceledState) continue;
+        try {
+          await api.updateIssue(id, { stateId: canceledState.id });
+        } catch {
+          // Best effort
+        }
+      }
+    });
+  });
+
   describe("cleanup", () => {
     it("cancels the smoke test issue", async () => {
       if (!smokeIssueId) return;

package/src/__test__/webhook-scenarios.test.ts

@@ -82,6 +82,7 @@ vi.mock("../pipeline/pipeline.js", () => ({
   runPlannerStage: vi.fn().mockResolvedValue("mock plan"),
   runFullPipeline: vi.fn().mockResolvedValue(undefined),
   resumePipeline: vi.fn().mockResolvedValue(undefined),
+  buildProjectContext: () => "",
 }));
 
 vi.mock("../pipeline/active-session.js", () => ({
@@ -787,4 +788,47 @@ describe("webhook scenario tests — full handler flows", () => {
       expect(msg).toContain("Cached guidance from session event");
     });
   });
+
+  describe("Sub-issue guidance in agent prompt", () => {
+    it("created: triaged issue includes sub-issue guidance with parentIssueId", async () => {
+      // Issue is "In Progress" (type: "started") — triaged, so full tool access
+      mockGetIssueDetails.mockResolvedValue(makeIssueDetails({
+        state: { name: "In Progress", type: "started" },
+      }));
+
+      const api = createApi();
+      const payload = makeAgentSessionEventCreated();
+      await postWebhook(api, payload);
+
+      await waitForMock(mockClearActiveSession);
+
+      expect(mockRunAgent).toHaveBeenCalledOnce();
+      const msg = mockRunAgent.mock.calls[0][0].message;
+
+      // Verify sub-issue guidance text includes the correct parentIssueId
+      expect(msg).toContain("Sub-issue guidance");
+      expect(msg).toContain("break it into sub-issues");
+      expect(msg).toContain('parentIssueId="ENG-123"');
+    });
+
+    it("created: backlog issue does NOT include sub-issue guidance", async () => {
+      // Issue is "Backlog" (type: "backlog") — untriaged, so read-only tool access
+      mockGetIssueDetails.mockResolvedValue(makeIssueDetails({
+        state: { name: "Backlog", type: "backlog" },
+      }));
+
+      const api = createApi();
+      const payload = makeAgentSessionEventCreated();
+      await postWebhook(api, payload);
+
+      await waitForMock(mockClearActiveSession);
+
+      expect(mockRunAgent).toHaveBeenCalledOnce();
+      const msg = mockRunAgent.mock.calls[0][0].message;
+
+      // Backlog issues get READ ONLY access — no sub-issue guidance
+      expect(msg).not.toContain("Sub-issue guidance");
+      expect(msg).toContain("READ ONLY");
+    });
+  });
 });

package/src/agent/agent.ts

@@ -323,7 +323,7 @@ async function runEmbedded(
       }
     },
 
-    // Raw agent events — capture tool starts/ends
+    // Raw agent events — capture tool starts/ends/updates
     onAgentEvent: (evt) => {
       watchdog.tick();
       const { stream, data } = evt;
@@ -333,16 +333,30 @@ async function runEmbedded(
       const phase = String(data.phase ?? "");
       const toolName = String(data.name ?? "tool");
       const meta = typeof data.meta === "string" ? data.meta : "";
+      const input = typeof data.input === "string" ? data.input : "";
 
-      // Tool execution start — emit action with tool name + meta
+      // Tool execution start — emit action with tool name + available context
       if (phase === "start") {
         lastToolAction = toolName;
-        emit({ type: "action", action: `Running ${toolName}`, parameter: meta.slice(0, 200) || toolName });
+        const detail = input || meta || toolName;
+        emit({ type: "action", action: `Running ${toolName}`, parameter: detail.slice(0, 300) });
+      }
+
+      // Tool execution update — partial progress (keeps Linear UI alive for long tools)
+      if (phase === "update") {
+        const detail = meta || input || "in progress";
+        emit({ type: "action", action: `${toolName}`, parameter: detail.slice(0, 300) });
+      }
+
+      // Tool execution completed successfully
+      if (phase === "result" && !data.isError) {
+        const detail = meta ? meta.slice(0, 300) : "completed";
+        emit({ type: "action", action: `${toolName} done`, parameter: detail });
       }
 
       // Tool execution result with error
       if (phase === "result" && data.isError) {
-        emit({ type: "action", action: `${toolName} failed`, parameter: meta.slice(0, 200) || "error" });
+        emit({ type: "action", action: `${toolName} failed`, parameter: (meta || "error").slice(0, 300) });
       }
     },