@calltelemetry/openclaw-linear 0.9.11 → 0.9.14

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";
@@ -477,7 +477,14 @@ export async function handleLinearWebhook(
       commentContext ? `\n**Conversation:**\n${commentContext}` : "",
       userMessage ? `\n**Latest message:**\n> ${userMessage}` : "",
       ``,
-      `Respond to the user's request. For work requests, dispatch via \`code_run\` and summarize the result. Be concise and action-oriented.`,
+      `## Scope Rules`,
+      `1. **Read the issue first.** The issue title + description define your scope. Everything you do must serve the issue as written.`,
+      `2. **\`code_run\` is ONLY for issue-body work.** Only dispatch \`code_run\` when the issue description contains implementation requirements. A greeting, question, or conversational issue gets a conversational response — NOT code_run.`,
+      `3. **Comments explore, issue body builds.** User comments may explore scope or ask questions but NEVER trigger \`code_run\` alone. If a comment requests new implementation, update the issue description first, then build from the issue text.`,
+      `4. **Plan before building.** For non-trivial work, respond with a plan first. Only dispatch \`code_run\` after the plan is clear and grounded in the issue body.`,
+      `5. **Match response to request.** Greeting → greet. Question → answer. No implementation requirements → no code_run.`,
+      ``,
+      `Respond within the scope defined above. Be concise and action-oriented.`,
     ].filter(Boolean).join("\n");
 
     // Run agent directly (non-blocking)
@@ -720,7 +727,12 @@ export async function handleLinearWebhook(
         commentContext ? `\n**Recent conversation:**\n${commentContext}` : "",
         `\n**User's follow-up message:**\n> ${userMessage}`,
         ``,
-        `Respond to the user's follow-up. For work requests, dispatch via \`code_run\`. Be concise and action-oriented.`,
+        `## Scope Rules`,
+        `1. **The issue body is your scope.** Re-read the description above before acting.`,
+        `2. **Comments explore, issue body builds.** The follow-up may refine understanding or ask questions — NEVER dispatch \`code_run\` from a comment alone. If the user requests implementation, suggest updating the issue description first.`,
+        `3. **Match response to request.** Answer questions with answers. Do NOT escalate conversational messages into builds.`,
+        ``,
+        `Respond to the follow-up within the scope defined above. Be concise and action-oriented.`,
       ].filter(Boolean).join("\n");
 
       setActiveSession({
@@ -1236,6 +1248,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 +1259,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/code-tool.ts

@@ -178,6 +178,11 @@ export function createCodeTool(
       required: ["prompt"],
     },
     execute: async (toolCallId: string, params: CliToolParams & { backend?: string }, ...rest: unknown[]) => {
+      // Extract onUpdate callback for progress reporting to Linear
+      const onUpdate = typeof rest[1] === "function"
+        ? rest[1] as (update: Record<string, unknown>) => void
+        : undefined;
+
       // Resolve backend: explicit alias → per-agent config → global default
       const currentSession = getCurrentSession();
       const agentId = currentSession?.agentId;
@@ -189,6 +194,13 @@ export function createCodeTool(
 
       api.logger.info(`code_run: backend=${backend} agent=${agentId ?? "unknown"}`);
 
+      // Emit prompt summary so Linear users see what's being built
+      const promptSummary = (params.prompt ?? "").slice(0, 200);
+      api.logger.info(`code_run prompt: [${backend}] ${promptSummary}`);
+      if (onUpdate) {
+        try { onUpdate({ status: "running", summary: `[${backend}] ${promptSummary}` }); } catch {}
+      }
+
       const result = await runner(api, params, pluginConfig);
 
       return jsonResult({

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;