@calltelemetry/openclaw-linear 0.9.11 → 0.9.12

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.12",
   "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:20:08.396Z
  */
 
 export const RECORDED = {
@@ -44,20 +44,20 @@ export const RECORDED = {
     }
   ],
   "createParent": {
-    "id": "953324f8-878f-40ba-b773-8d8815ee7987",
-    "identifier": "UAT-320"
+    "id": "2becfd65-c313-4d4b-9362-b3ac431872c6",
+    "identifier": "UAT-354"
   },
   "createSubIssue1": {
-    "id": "69ce9a01-3bdb-4f4a-a882-e28e23d1b628",
-    "identifier": "UAT-321"
+    "id": "b7433275-83a2-4e6e-a98c-5fe2b3aa1147",
+    "identifier": "UAT-355"
   },
   "createSubIssue2": {
-    "id": "b39cc5eb-ec05-44aa-917b-562a290ecab6",
-    "identifier": "UAT-322"
+    "id": "3526cea7-2261-4eee-bd8a-5206e12c6124",
+    "identifier": "UAT-356"
   },
   "subIssue1Details": {
-    "id": "69ce9a01-3bdb-4f4a-a882-e28e23d1b628",
-    "identifier": "UAT-321",
+    "id": "b7433275-83a2-4e6e-a98c-5fe2b3aa1147",
+    "identifier": "UAT-355",
     "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": "2becfd65-c313-4d4b-9362-b3ac431872c6",
+      "identifier": "UAT-354"
     },
     "relations": {
       "nodes": []
     }
   },
   "subIssue2Details": {
-    "id": "b39cc5eb-ec05-44aa-917b-562a290ecab6",
-    "identifier": "UAT-322",
+    "id": "3526cea7-2261-4eee-bd8a-5206e12c6124",
+    "identifier": "UAT-356",
     "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": "2becfd65-c313-4d4b-9362-b3ac431872c6",
+      "identifier": "UAT-354"
     },
     "relations": {
       "nodes": []
     }
   },
   "parentDetails": {
-    "id": "953324f8-878f-40ba-b773-8d8815ee7987",
-    "identifier": "UAT-320",
+    "id": "2becfd65-c313-4d4b-9362-b3ac431872c6",
+    "identifier": "UAT-354",
     "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:20:04.703Z",
     "estimate": null,
     "state": {
       "name": "Backlog",
@@ -158,11 +158,11 @@ export const RECORDED = {
     }
   },
   "createRelation": {
-    "id": "9207d26d-d65d-45a2-ac76-b9233acea181"
+    "id": "a9cac881-3d13-45ab-b000-855777698d71"
   },
   "subIssue1WithRelation": {
-    "id": "69ce9a01-3bdb-4f4a-a882-e28e23d1b628",
-    "identifier": "UAT-321",
+    "id": "b7433275-83a2-4e6e-a98c-5fe2b3aa1147",
+    "identifier": "UAT-355",
     "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 +184,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:20:06.930Z"
+        }
+      ]
     },
     "project": null,
     "parent": {
-      "id": "953324f8-878f-40ba-b773-8d8815ee7987",
-      "identifier": "UAT-320"
+      "id": "2becfd65-c313-4d4b-9362-b3ac431872c6",
+      "identifier": "UAT-354"
     },
     "relations": {
       "nodes": [
         {
           "type": "blocks",
           "relatedIssue": {
-            "id": "b39cc5eb-ec05-44aa-917b-562a290ecab6",
-            "identifier": "UAT-322",
+            "id": "3526cea7-2261-4eee-bd8a-5206e12c6124",
+            "identifier": "UAT-356",
             "title": "[SMOKE TEST] Sub-Issue 2: Frontend UI"
           }
         }
@@ -205,8 +211,8 @@ export const RECORDED = {
     }
   },
   "subIssue2WithRelation": {
-    "id": "b39cc5eb-ec05-44aa-917b-562a290ecab6",
-    "identifier": "UAT-322",
+    "id": "3526cea7-2261-4eee-bd8a-5206e12c6124",
+    "identifier": "UAT-356",
     "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 +238,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:20:06.960Z"
         }
       ]
     },
     "project": null,
     "parent": {
-      "id": "953324f8-878f-40ba-b773-8d8815ee7987",
-      "identifier": "UAT-320"
+      "id": "2becfd65-c313-4d4b-9362-b3ac431872c6",
+      "identifier": "UAT-354"
     },
     "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/infra/doctor.ts

@@ -484,6 +484,112 @@ export async function checkFilesAndDirs(pluginConfig?: Record<string, unknown>,
     checks.push(fail(`Base repo does not exist: ${baseRepo}`, undefined, "Set codexBaseRepo in plugin config to your git repository path"));
   }
 
+  // CLAUDE.md in base repo
+  if (existsSync(baseRepo)) {
+    const claudeMdPath = join(baseRepo, "CLAUDE.md");
+    if (existsSync(claudeMdPath)) {
+      try {
+        const stat = statSync(claudeMdPath);
+        const sizeKb = Math.round(stat.size / 1024);
+        checks.push(pass(`CLAUDE.md found in base repo (${sizeKb}KB)`));
+      } catch {
+        checks.push(pass("CLAUDE.md found in base repo"));
+      }
+    } else {
+      checks.push(warn(
+        "No CLAUDE.md in base repo",
+        `Expected at: ${claudeMdPath}`,
+        {
+          fix: [
+            `Create ${claudeMdPath} — this is how agents learn your project.`,
+            "",
+            "Template:",
+            "  # Project Name",
+            "",
+            "  ## Tech Stack",
+            "  - Language/framework here",
+            "",
+            "  ## Build",
+            "  ```bash",
+            "  your build command here",
+            "  ```",
+            "",
+            "  ## Test",
+            "  ```bash",
+            "  your test command here",
+            "  ```",
+            "",
+            "  ## Architecture",
+            "  Brief description of directory structure and key patterns.",
+          ].join("\n"),
+        },
+      ));
+    }
+  }
+
+  // AGENTS.md in base repo
+  if (existsSync(baseRepo)) {
+    const agentsMdPath = join(baseRepo, "AGENTS.md");
+    if (existsSync(agentsMdPath)) {
+      try {
+        const stat = statSync(agentsMdPath);
+        const sizeKb = Math.round(stat.size / 1024);
+        checks.push(pass(`AGENTS.md found in base repo (${sizeKb}KB)`));
+      } catch {
+        checks.push(pass("AGENTS.md found in base repo"));
+      }
+    } else {
+      checks.push(warn(
+        "No AGENTS.md in base repo",
+        `Expected at: ${agentsMdPath}`,
+        {
+          fix: [
+            `Create ${agentsMdPath} — this tells agents how to work on your project.`,
+            "",
+            "Template:",
+            "  # Agent Guidelines",
+            "",
+            "  ## Code Style",
+            "  - Patterns and conventions to follow",
+            "",
+            "  ## Workflow",
+            "  - Branch naming, commit messages, PR process",
+            "",
+            "  ## Do / Don't",
+            "  - Rules agents must follow in this codebase",
+          ].join("\n"),
+        },
+      ));
+    }
+  }
+
+  // Multi-repo path validation
+  const repos = pluginConfig?.repos as Record<string, string> | undefined;
+  if (repos && typeof repos === "object") {
+    for (const [name, repoPath] of Object.entries(repos)) {
+      if (typeof repoPath !== "string") continue;
+      const resolved = repoPath.startsWith("~/") ? repoPath.replace("~", homedir()) : repoPath;
+      if (!existsSync(resolved)) {
+        checks.push(fail(
+          `Repo "${name}": path does not exist: ${resolved}`,
+          undefined,
+          `Verify the path in plugin config repos.${name}, or create the directory and run: git init ${resolved}`,
+        ));
+      } else {
+        try {
+          execFileSync("git", ["rev-parse", "--git-dir"], { cwd: resolved, encoding: "utf8", timeout: 5_000 });
+          checks.push(pass(`Repo "${name}": valid git repo`));
+        } catch {
+          checks.push(fail(
+            `Repo "${name}": not a git repo at ${resolved}`,
+            undefined,
+            `Run: git init ${resolved}`,
+          ));
+        }
+      }
+    }
+  }
+
   // Prompts
   try {
     clearPromptCache();

package/src/pipeline/pipeline.test.ts

@@ -52,6 +52,7 @@ import {
   parseVerdict,
   buildWorkerTask,
   buildAuditTask,
+  buildProjectContext,
   loadPrompts,
   loadRawPromptYaml,
   clearPromptCache,
@@ -238,6 +239,100 @@ describe("buildAuditTask", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// buildProjectContext
+// ---------------------------------------------------------------------------
+
+describe("buildProjectContext", () => {
+  it("returns empty string when no config", () => {
+    expect(buildProjectContext()).toBe("");
+    expect(buildProjectContext(undefined)).toBe("");
+  });
+
+  it("returns empty string when config has no relevant keys", () => {
+    expect(buildProjectContext({ someOtherKey: "value" })).toBe("");
+  });
+
+  it("includes project name", () => {
+    const ctx = buildProjectContext({ projectName: "CallTelemetry" });
+    expect(ctx).toContain("Project: CallTelemetry");
+  });
+
+  it("includes single repo from codexBaseRepo", () => {
+    const ctx = buildProjectContext({ codexBaseRepo: "/home/claw/ai-workspace" });
+    expect(ctx).toContain("Repo: /home/claw/ai-workspace");
+  });
+
+  it("includes multi-repo map", () => {
+    const ctx = buildProjectContext({
+      repos: { api: "/home/repos/api", frontend: "/home/repos/frontend" },
+    });
+    expect(ctx).toContain("Repos:");
+    expect(ctx).toContain("api (/home/repos/api)");
+    expect(ctx).toContain("frontend (/home/repos/frontend)");
+  });
+
+  it("prefers repos over codexBaseRepo when both present", () => {
+    const ctx = buildProjectContext({
+      codexBaseRepo: "/home/claw/fallback",
+      repos: { main: "/home/claw/main" },
+    });
+    expect(ctx).toContain("Repos:");
+    expect(ctx).not.toContain("Repo: /home/claw/fallback");
+  });
+
+  it("ignores framework, buildCommand, testCommand (belong in CLAUDE.md)", () => {
+    const ctx = buildProjectContext({
+      framework: "Phoenix/Elixir",
+      buildCommand: "mix compile",
+      testCommand: "mix test",
+    });
+    expect(ctx).toBe("");
+  });
+
+  it("includes projectName + repo together", () => {
+    const ctx = buildProjectContext({
+      projectName: "MyApp",
+      codexBaseRepo: "/repo",
+    });
+    expect(ctx).toContain("## Project Context");
+    expect(ctx).toContain("Project: MyApp");
+    expect(ctx).toContain("Repo: /repo");
+  });
+
+  it("injects projectContext into worker prompt", () => {
+    clearPromptCache();
+    const issue: IssueContext = { id: "1", identifier: "X-1", title: "test", description: "desc" };
+    const { task } = buildWorkerTask(issue, "/wt", {
+      pluginConfig: { projectName: "TestProject" },
+    });
+    expect(task).toContain("Project: TestProject");
+  });
+
+  it("injects projectContext into audit prompt", () => {
+    clearPromptCache();
+    const issue: IssueContext = { id: "1", identifier: "X-1", title: "test", description: "desc" };
+    const { task } = buildAuditTask(issue, "/wt", { projectName: "TestProject" });
+    expect(task).toContain("Project: TestProject");
+  });
+
+  it("worker prompt instructs reading CLAUDE.md and AGENTS.md", () => {
+    clearPromptCache();
+    const issue: IssueContext = { id: "1", identifier: "X-1", title: "test", description: "desc" };
+    const { task } = buildWorkerTask(issue, "/wt");
+    expect(task).toContain("CLAUDE.md");
+    expect(task).toContain("AGENTS.md");
+  });
+
+  it("audit prompt instructs reading CLAUDE.md and AGENTS.md", () => {
+    clearPromptCache();
+    const issue: IssueContext = { id: "1", identifier: "X-1", title: "test", description: "desc" };
+    const { task } = buildAuditTask(issue, "/wt");
+    expect(task).toContain("CLAUDE.md");
+    expect(task).toContain("AGENTS.md");
+  });
+});
+
 // ---------------------------------------------------------------------------
 // loadPrompts / clearPromptCache
 // ---------------------------------------------------------------------------

package/src/pipeline/pipeline.ts

@@ -63,11 +63,11 @@ interface PromptTemplates {
 const DEFAULT_PROMPTS: PromptTemplates = {
   worker: {
     system: "You are a coding worker implementing a Linear issue. Your ONLY job is to write code and return a text summary. Do NOT attempt to update, close, comment on, or modify the Linear issue. Do NOT mark the issue as Done.",
-    task: "Implement issue {{identifier}}: {{title}}\n\nIssue body:\n{{description}}\n\nWorktree: {{worktreePath}}\n\nImplement the solution, run tests, commit your work, and return a text summary.",
+    task: "Implement issue {{identifier}}: {{title}}\n\nIssue body:\n{{description}}\n\nWorktree: {{worktreePath}}\n{{projectContext}}\n\nBefore coding, read CLAUDE.md and AGENTS.md in the worktree root for project conventions and guidelines. If they don't exist, explore the codebase first.\n\nImplement the solution, run tests, commit your work, and return a text summary.",
   },
   audit: {
     system: "You are an independent auditor. The Linear issue body is the SOURCE OF TRUTH. Worker comments are secondary evidence.",
-    task: 'Audit issue {{identifier}}: {{title}}\n\nIssue body:\n{{description}}\n\nWorktree: {{worktreePath}}\n\nReturn JSON verdict: {"pass": true/false, "criteria": [...], "gaps": [...], "testResults": "..."}',
+    task: 'Audit issue {{identifier}}: {{title}}\n\nIssue body:\n{{description}}\n\nWorktree: {{worktreePath}}\n{{projectContext}}\n\nRead CLAUDE.md and AGENTS.md in the worktree root for project standards.\n\nReturn JSON verdict: {"pass": true/false, "criteria": [...], "gaps": [...], "testResults": "..."}',
   },
   rework: {
     addendum: "PREVIOUS AUDIT FAILED (attempt {{attempt}}). Gaps:\n{{gaps}}\n\nAddress these specific issues. Preserve correct code from prior attempts.",
@@ -167,6 +167,39 @@ export function clearPromptCache(): void {
   _projectPromptCache.clear();
 }
 
+// ---------------------------------------------------------------------------
+// Project context builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a project context block from plugin config.
+ *
+ * Provides structural info only: project name and repo paths.
+ * Framework, build/test commands, and conventions belong in CLAUDE.md
+ * and AGENTS.md in the repo root — agents are instructed to read those.
+ */
+export function buildProjectContext(pluginConfig?: Record<string, unknown>): string {
+  if (!pluginConfig) return "";
+
+  const lines: string[] = [];
+
+  // Project name
+  const projectName = pluginConfig.projectName as string | undefined;
+  if (projectName) lines.push(`Project: ${projectName}`);
+
+  // Repo(s)
+  const repos = pluginConfig.repos as Record<string, string> | undefined;
+  const baseRepo = pluginConfig.codexBaseRepo as string | undefined;
+  if (repos && Object.keys(repos).length > 0) {
+    lines.push(`Repos: ${Object.entries(repos).map(([k, v]) => `${k} (${v})`).join(", ")}`);
+  } else if (baseRepo) {
+    lines.push(`Repo: ${baseRepo}`);
+  }
+
+  if (lines.length === 0) return "";
+  return "## Project Context\n" + lines.join("\n");
+}
+
 // ---------------------------------------------------------------------------
 // Task builders
 // ---------------------------------------------------------------------------
@@ -199,6 +232,7 @@ export function buildWorkerTask(
     guidance: opts?.guidance
       ? `\n---\n## IMPORTANT — Workspace Guidance (MUST follow)\nThe workspace owner has set the following mandatory instructions. You MUST incorporate these into your response:\n\n${opts.guidance.slice(0, 2000)}\n---`
       : "",
+    projectContext: buildProjectContext(opts?.pluginConfig),
   };
 
   let task = renderTemplate(prompts.worker.task, vars);
@@ -233,6 +267,7 @@ export function buildAuditTask(
     guidance: opts?.guidance
       ? `\n---\n## IMPORTANT — Workspace Guidance (MUST follow)\nThe workspace owner has set the following mandatory instructions. You MUST incorporate these into your response:\n\n${opts.guidance.slice(0, 2000)}\n---`
       : "",
+    projectContext: buildProjectContext(pluginConfig),
   };
 
   return {

package/src/pipeline/webhook.test.ts

@@ -141,6 +141,7 @@ vi.mock("./pipeline.js", () => ({
   runFullPipeline: runFullPipelineMock,
   resumePipeline: resumePipelineMock,
   spawnWorker: spawnWorkerMock,
+  buildProjectContext: () => "",
 }));
 
 vi.mock("../api/linear-api.js", () => ({

package/src/pipeline/webhook.ts

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { LinearAgentApi, resolveLinearToken } from "../api/linear-api.js";
-import { spawnWorker, type HookContext } from "./pipeline.js";
+import { spawnWorker, buildProjectContext, type HookContext } from "./pipeline.js";
 import { setActiveSession, clearActiveSession, getIssueAffinity, _configureAffinityTtl, _resetAffinityForTesting } from "./active-session.js";
 import { readDispatchState, getActiveDispatch, registerDispatch, updateDispatchStatus, completeDispatch, removeActiveDispatch } from "./dispatch-state.js";
 import { createNotifierFromConfig, type NotifyFn } from "../infra/notify.js";
@@ -1236,6 +1236,7 @@ export async function handleLinearWebhook(
           ? formatGuidanceAppendix(triageGuidance)
           : "";
 
+        const projectCtx = buildProjectContext(pluginConfig);
         const message = [
           `IMPORTANT: You are triaging a new Linear issue. You MUST respond with a JSON block containing your triage decisions, followed by your assessment as plain text.`,
           ``,
@@ -1246,6 +1247,7 @@ export async function handleLinearWebhook(
           `**Description:**`,
           description,
           ``,
+          ...(projectCtx ? [projectCtx, ``] : []),
           `## Your Triage Tasks`,
           ``,
           `1. **Story Points** — Estimate complexity using ${estimationType} scale (1=trivial, 2=small, 3=medium, 5=large, 8=very large, 13=epic)`,

package/src/tools/linear-issues-tool.test.ts

@@ -342,7 +342,7 @@ describe("linear_issues tool", () => {
         projectId: "proj-1",
         title: "Sub-task: handle edge case",
         description: "Fix the edge case for empty input",
-        parentId: "ENG-123",
+        parentId: "issue-1",  // Resolved UUID from getIssueDetails, not the identifier "ENG-123"
       });
       expect(result.success).toBe(true);
       expect(result.identifier).toBe("ENG-201");

package/src/tools/linear-issues-tool.ts

@@ -86,12 +86,14 @@ async function handleCreate(api: LinearAgentApi, params: ToolParams) {
   // Resolve teamId: explicit param, or derive from parent issue
   let teamId = params.teamId;
   let projectId = params.projectId;
+  let resolvedParentId: string | undefined;
 
   if (params.parentIssueId) {
-    // Fetch parent to get teamId and projectId
+    // Fetch parent to get teamId, projectId, and resolved UUID
     const parent = await api.getIssueDetails(params.parentIssueId);
     teamId = teamId ?? parent.team.id;
     projectId = projectId ?? parent.project?.id ?? undefined;
+    resolvedParentId = parent.id;
   }
 
   if (!teamId) {
@@ -106,7 +108,7 @@ async function handleCreate(api: LinearAgentApi, params: ToolParams) {
   };
 
   if (params.description) input.description = params.description;
-  if (params.parentIssueId) input.parentId = params.parentIssueId;
+  if (resolvedParentId) input.parentId = resolvedParentId;
   if (projectId) input.projectId = projectId;
   if (params.priority != null) input.priority = params.priority;
   if (params.estimate != null) input.estimate = params.estimate;