@yannelli/paseo-linear-plugin 1.0.1 → 1.1.0-alpha.0

package/shared/live.ts

@@ -0,0 +1,248 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+import { McpHttpServerSchema, ToolPolicySchema } from "./agent-tools";
+import { type AreaRef, areasIn } from "./knowledge";
+import { IssueCardSchema, WorkflowStateSchema } from "./linear";
+
+// Contracts for Linear Live, todo sync, and project setup. Agents the plugin starts for itself
+// carry their own labels so they get no pill, no sync, and no place in the linked agent list.
+
+export const MapFileSchema = z.object({
+  path: z.string().min(1),
+  /** Issue key the file belongs to: the parent or one of its sub-issues. */
+  issue: z.string().min(1),
+});
+export type MapFile = z.infer<typeof MapFileSchema>;
+
+export const IssueMapSchema = z.object({
+  identifier: z.string(),
+  source: z.enum(["semantic", "explore"]),
+  files: z.array(MapFileSchema),
+  createdAt: z.string(),
+});
+export type IssueMap = z.infer<typeof IssueMapSchema>;
+
+export const JobSchema = z.object({
+  id: z.string(),
+  status: z.enum(["running", "done", "failed"]),
+  agentId: z.string().nullable(),
+  error: z.string().nullable(),
+  startedAt: z.string(),
+});
+export type Job = z.infer<typeof JobSchema>;
+
+/** What the explore agent must return. */
+export const ExploreResultSchema = z.object({
+  files: z.array(z.object({ path: z.string().min(1), issue: z.string().min(1) })).max(200),
+});
+
+export const InitProposalSchema = z.object({
+  instructions: z.string().default(""),
+  steps: z.array(z.string()).default([]),
+  implement: z.string().default(""),
+  review: z.string().default(""),
+  /** Saved to the project knowledge at once; not part of the prompt proposal. */
+  summary: z.string().default(""),
+  areas: z.array(z.object({ path: z.string(), summary: z.string() })).max(80).default([]),
+});
+export type InitProposal = z.infer<typeof InitProposalSchema>;
+
+/** Files an explore run may list; the map shows this many and more. */
+export const MAX_EXPLORE_FILES = 150;
+export const MAX_LIST_DIRS = 40;
+export const MAX_DIR_ENTRIES = 60;
+
+export const listFilesRpc = defineRpc({
+  name: "linear.live.files",
+  input: z.object({ agentId: z.string().min(1), dirs: z.array(z.string()).max(MAX_LIST_DIRS) }),
+  output: z.object({
+    dirs: z.array(z.object({ dir: z.string(), files: z.array(z.string()), truncated: z.boolean() })),
+  }),
+});
+
+const SubagentLogSchema = z.object({
+  id: z.string(),
+  type: z.string(),
+  description: z.string(),
+  /** The parent's call that started it, when Claude recorded one. */
+  toolUseId: z.string().nullable(),
+  updatedAt: z.number(),
+  /** Its last reply ended the run. */
+  finished: z.boolean(),
+  items: z.array(
+    z.object({
+      type: z.literal("tool_call"),
+      callId: z.string(),
+      name: z.string(),
+      status: z.enum(["running", "completed", "failed"]),
+      detail: z.record(z.string(), z.unknown()),
+    }),
+  ),
+});
+export type SubagentLog = z.infer<typeof SubagentLogSchema>;
+
+/** Tool calls of the subagents an agent started inside its provider. */
+export const subagentLogsRpc = defineRpc({
+  name: "linear.live.subagents",
+  input: z.object({ agentId: z.string().min(1) }),
+  output: z.object({ runs: z.array(SubagentLogSchema) }),
+});
+
+/** Forgets the saved explore map of the agent's issue, so the map falls back to ticket text. */
+export const clearMapRpc = defineRpc({
+  name: "linear.live.map.clear",
+  input: z.object({ agentId: z.string().min(1) }),
+  output: z.object({ cleared: z.boolean() }),
+});
+
+export const liveMapRpc = defineRpc({
+  name: "linear.live.map",
+  input: z.object({ identifier: z.string().min(1) }),
+  output: z.object({ map: IssueMapSchema.nullable(), job: JobSchema.nullable() }),
+});
+
+export const exploreRpc = defineRpc({
+  name: "linear.live.explore",
+  input: z.object({ agentId: z.string().min(1), force: z.boolean().default(false) }),
+  output: z.object({ job: JobSchema }),
+});
+
+export const LaunchConfigSchema = z.object({
+  provider: z.string().min(1),
+  thinkingOptionId: z.string().optional(),
+  modeId: z.string().optional(),
+  /** Only the folder of the issue's Claude Code hooks; see agent-hooks.ts. */
+  providerOptions: z.object({ extraArgs: z.object({ "plugin-dir": z.string().min(1) }) }).optional(),
+  /** Only the plugin's own MCP server; see agent-tools.ts. */
+  mcpServers: z.object({ linear: McpHttpServerSchema }).optional(),
+  toolPolicy: ToolPolicySchema.optional(),
+});
+
+// The daemon maps the files first and then starts the agent, so closing the app mid-way
+// still starts it. With a saved map, or when exploring cannot start, the agent starts now.
+export const LaunchInputSchema = z.object({
+  workspaceId: z.string().min(1),
+  identifier: z.string().min(1),
+  keyScope: z.string().nullable(),
+  agent: z.object({
+    config: LaunchConfigSchema,
+    title: z.string(),
+    prompt: z.string(),
+    labels: z.record(z.string(), z.string()),
+  }),
+  card: IssueCardSchema,
+});
+export type LaunchInput = z.infer<typeof LaunchInputSchema>;
+
+export const launchAfterExploreRpc = defineRpc({
+  name: "linear.live.launch",
+  input: LaunchInputSchema,
+  output: z.object({ agentId: z.string().nullable(), job: JobSchema }),
+});
+
+export const SyncMoveSchema = z.object({
+  identifier: z.string(),
+  from: WorkflowStateSchema,
+  to: WorkflowStateSchema,
+});
+
+export const syncNowRpc = defineRpc({
+  name: "linear.sync.now",
+  input: z.object({ agentId: z.string().min(1) }),
+  output: z.object({ moves: z.array(SyncMoveSchema), skipped: z.string().nullable() }),
+});
+
+export const initStartRpc = defineRpc({
+  name: "linear.init.start",
+  input: z.object({ projectId: z.string().min(1), rootPath: z.string().min(1) }),
+  output: z.object({ job: JobSchema }),
+});
+
+export const initStatusRpc = defineRpc({
+  name: "linear.init.status",
+  input: z.object({ jobId: z.string().min(1) }),
+  output: z.object({ job: JobSchema.nullable(), proposal: InitProposalSchema.nullable() }),
+});
+
+const EXTENSIONS =
+  "ts|tsx|js|jsx|mjs|cjs|py|go|rs|rb|java|kt|swift|c|cc|cpp|h|hpp|cs|php|vue|svelte|css|scss|html|md|mdx|json|ya?ml|toml|sql|sh|prisma|graphql";
+const PATH = new RegExp(
+  `(?:^|[\\s\`'"(\\[])((?:[\\w@.-]+/)*[\\w@.-]+\\.(?:${EXTENSIONS}))(?=$|[\\s\`'")\\],.:;!?])`,
+  "g",
+);
+const DIRECTORY = /`((?:[\w@.-]+\/)+)`/g;
+const ISSUE_KEY = /\b[A-Z][A-Z0-9]*-\d+\b/g;
+
+export function pathsIn(text: string): string[] {
+  const found = new Set<string>();
+  for (const match of text.matchAll(PATH)) if (match[1]) found.add(match[1].replace(/^\.\//, ""));
+  for (const match of text.matchAll(DIRECTORY)) if (match[1]) found.add(match[1]);
+  return [...found].filter((path) => !/^https?:/.test(path) && !path.includes("//"));
+}
+
+export interface SemanticIssue {
+  identifier: string;
+  title: string;
+  description: string | null;
+  children: readonly { identifier: string; title: string }[];
+}
+
+/** What project knowledge adds to a ticket-text map. */
+export interface MapHints {
+  /** Ticket paths matched to real files, such as "linear.ts" to "server/linear.ts". */
+  resolved?: ReadonlyMap<string, string>;
+  /** A service or package the text names puts its folder on the map. */
+  areas?: readonly AreaRef[];
+}
+
+// Linear sends sub-issue titles but not their descriptions, so a path in the parent's text
+// belongs to the sub-issue its line names and otherwise to the parent.
+export function semanticMap(issue: SemanticIssue, now = new Date(), hints: MapHints = {}): IssueMap {
+  const owners = new Map<string, string>();
+  const childKeys = new Set(issue.children.map((child) => child.identifier.toUpperCase()));
+  const found = (text: string) => [
+    ...pathsIn(text).map((path) => hints.resolved?.get(path) ?? path),
+    ...areasIn(text, hints.areas ?? []).map((area) => area.path),
+  ];
+  for (const child of issue.children) {
+    for (const path of found(child.title)) owners.set(path, child.identifier);
+  }
+  const lines = `${issue.title}\n${issue.description ?? ""}`.split("\n");
+  for (const line of lines) {
+    const named = (line.match(ISSUE_KEY) ?? []).find((key) => childKeys.has(key));
+    for (const path of found(line)) {
+      if (!owners.has(path)) owners.set(path, named ?? issue.identifier);
+    }
+  }
+  return {
+    identifier: issue.identifier,
+    source: "semantic",
+    files: [...owners].map(([path, owner]) => ({ path, issue: owner })),
+    createdAt: now.toISOString(),
+  };
+}
+
+/** Parses the last JSON object in an agent reply: a fenced block, the whole text, or braces. */
+export function lastJsonObject(reply: string): unknown {
+  const fences = [...reply.matchAll(/```(?:json)?\s*\n([\s\S]*?)```/g)].reverse();
+  const candidates = [...fences.map((match) => match[1] ?? ""), reply.trim()];
+  const start = reply.indexOf("{");
+  const end = reply.lastIndexOf("}");
+  if (start >= 0 && end > start) candidates.push(reply.slice(start, end + 1));
+  for (const candidate of candidates) {
+    try {
+      const value: unknown = JSON.parse(candidate);
+      if (value && typeof value === "object" && !Array.isArray(value)) return value;
+    } catch {
+      // Not JSON; try the next candidate.
+    }
+  }
+  return null;
+}
+
+/** Directory of a repo path, with a trailing slash, or "" for the root. */
+export function dirOf(path: string): string {
+  if (path.endsWith("/")) return path;
+  const index = path.lastIndexOf("/");
+  return index < 0 ? "" : path.slice(0, index + 1);
+}

package/shared/map-model.ts

@@ -0,0 +1,240 @@
+import type { DirTouch, FileTouch } from "./activity";
+import { type AreaRef, areaLabel, areaOf, whereLabel } from "./knowledge";
+import { dirOf, type MapFile } from "./live";
+
+// The Linear Live map: predicted files and touched files grouped into folder zones, and the
+// column layout for those zones. Pure, so it runs in tests without React Native.
+
+const MAX_GHOSTS = 4;
+/** Listing chips are hidden once a zone has this many real tiles. */
+const GHOSTS_UNTIL = 6;
+
+export interface MapTile {
+  path: string;
+  name: string;
+  owner: string | null;
+  ghost: boolean;
+  onMap: boolean;
+  touch: "none" | "read" | "edited" | "created";
+  added: number;
+  removed: number;
+}
+
+export type ZoneExplored = "none" | "listed" | "searched";
+
+export interface MapZone {
+  dir: string;
+  tiles: MapTile[];
+  /** Files in the zone that are on the map. */
+  predicted: number;
+  /** Files in the zone the agent read or changed. */
+  touched: number;
+  /** Touched files that are on the map. */
+  hits: number;
+  explored: ZoneExplored;
+  /** The service, package, or main folder the zone is in, from the project knowledge. */
+  area: AreaRef | null;
+}
+
+/** Touched files the map did not predict, grouped by where they are. */
+export interface OffMapGroup {
+  where: string;
+  files: number;
+}
+
+export interface MapModel {
+  zones: MapZone[];
+  touched: number;
+  hits: number;
+  offMap: OffMapGroup[];
+}
+
+// Search hits alone do not count: one broad search would flood the map with off-map tiles.
+function isTouched(file: FileTouch): boolean {
+  return file.reads + file.edits > 0;
+}
+
+function touchState(file: FileTouch | undefined): MapTile["touch"] {
+  if (!file) return "none";
+  if (file.created) return "created";
+  return file.edits > 0 ? "edited" : "read";
+}
+
+interface Predictions {
+  files: ReadonlyMap<string, string>;
+  dirs: ReadonlyMap<string, string>;
+}
+
+// A map entry ending in "/" names a directory: it seeds a zone and owns the files inside.
+function predictions(files: readonly MapFile[]): Predictions {
+  const paths = new Map<string, string>();
+  const dirs = new Map<string, string>();
+  for (const file of files) {
+    const target = file.path.endsWith("/") ? dirs : paths;
+    if (!target.has(file.path)) target.set(file.path, file.issue.toUpperCase());
+  }
+  return { files: paths, dirs };
+}
+
+function ownerOf(path: string, predicted: Predictions): string | null {
+  const direct = predicted.files.get(path);
+  if (direct) return direct;
+  for (const [dir, owner] of predicted.dirs) if (path.startsWith(dir)) return owner;
+  return null;
+}
+
+/** Zone directories: predicted ones in map order, then touched ones by name. */
+export function zoneDirs(files: readonly MapFile[], touches: readonly FileTouch[]): string[] {
+  const dirs = new Set(files.map((file) => dirOf(file.path)));
+  const extra = touches.filter(isTouched).map((file) => dirOf(file.path));
+  for (const dir of [...new Set(extra)].sort()) dirs.add(dir);
+  return [...dirs];
+}
+
+// A listed folder counts for itself; a recursive search counts for every folder under it,
+// except a search of the whole repository, which would mark every zone.
+function exploredState(dir: string, dirs: readonly DirTouch[]): ZoneExplored {
+  let state: ZoneExplored = "none";
+  for (const touch of dirs) {
+    const covers = touch.path === dir || (touch.deep && touch.path !== "" && dir.startsWith(touch.path));
+    if (covers && touch.deep) return "searched";
+    if (covers) state = "listed";
+  }
+  return state;
+}
+
+export function buildMapModel(
+  files: readonly MapFile[],
+  touches: readonly FileTouch[],
+  listing: ReadonlyMap<string, readonly string[]>,
+  dirs: readonly DirTouch[] = [],
+  areas: readonly AreaRef[] = [],
+): MapModel {
+  const predicted = predictions(files);
+  const touched = new Map(touches.filter(isTouched).map((file) => [file.path, file]));
+  const zones = zoneDirs(files, touches).map((dir): MapZone => {
+    const inZone = (path: string) => dirOf(path) === dir;
+    const real = new Set([...predicted.files.keys(), ...touched.keys()].filter(inZone));
+    const tiles = [...real].sort().map((path): MapTile => {
+      const touch = touched.get(path);
+      const owner = ownerOf(path, predicted);
+      return {
+        path,
+        name: path.slice(dir.length),
+        owner,
+        ghost: false,
+        onMap: owner !== null,
+        touch: touchState(touch),
+        added: touch?.added ?? 0,
+        removed: touch?.removed ?? 0,
+      };
+    });
+    const ghosts = (tiles.length >= GHOSTS_UNTIL ? [] : (listing.get(dir) ?? []))
+      .filter((name) => !real.has(`${dir}${name}`))
+      .slice(0, MAX_GHOSTS)
+      .map((name): MapTile => {
+        const path = `${dir}${name}`;
+        const owner = ownerOf(path, predicted);
+        const onMap = owner !== null;
+        return { path, name, owner, ghost: true, onMap, touch: "none", added: 0, removed: 0 };
+      });
+    return {
+      dir,
+      tiles: [...tiles, ...ghosts],
+      predicted: tiles.filter((tile) => tile.onMap).length,
+      touched: tiles.filter((tile) => tile.touch !== "none").length,
+      hits: tiles.filter((tile) => tile.touch !== "none" && tile.onMap).length,
+      explored: exploredState(dir, dirs),
+      area: areaOf(dir, areas),
+    };
+  });
+  let hits = 0;
+  const off = new Map<string, number>();
+  for (const path of touched.keys()) {
+    if (ownerOf(path, predicted)) hits += 1;
+    else off.set(whereLabel(path, areas), (off.get(whereLabel(path, areas)) ?? 0) + 1);
+  }
+  const offMap = [...off]
+    .map(([where, count]) => ({ where, files: count }))
+    .sort((a, b) => b.files - a.files || a.where.localeCompare(b.where));
+  return { zones, touched: touched.size, hits, offMap };
+}
+
+export function hitRateLine(model: MapModel): string {
+  if (model.touched === 0) return "No files touched yet";
+  const noun = model.touched === 1 ? "file" : "files";
+  return `${model.touched} ${noun} touched, ${model.hits} on the map`;
+}
+
+const OFF_MAP_SHOWN = 4;
+
+/** Such as "Off the map: billing-api · service (3), docs (1)"; null when all are on it. */
+export function offMapLine(model: MapModel): string | null {
+  if (model.offMap.length === 0) return null;
+  const shown = model.offMap.slice(0, OFF_MAP_SHOWN).map((group) => `${group.where} (${group.files})`);
+  const more = model.offMap.length - OFF_MAP_SHOWN;
+  return `Off the map: ${shown.join(", ")}${more > 0 ? `, ${more} more` : ""}`;
+}
+
+/** Where the file is when the agent touched it off the map; null on the map or untouched. */
+export function offMapWhere(model: MapModel, path: string | null, areas: readonly AreaRef[]): string | null {
+  if (!path) return null;
+  for (const zone of model.zones) {
+    const tile = zone.tiles.find((entry) => entry.path === path && !entry.ghost);
+    if (tile) return tile.touch !== "none" && !tile.onMap ? whereLabel(path, areas) : null;
+  }
+  return null;
+}
+
+/** The area a zone header names; only the part its folder name does not already say. */
+export function zoneAreaLabel(zone: MapZone): string | null {
+  const area = zone.area;
+  if (!area || area.path === "") return null;
+  const folder = area.path.replace(/\/$/, "").split("/").pop();
+  if (zone.dir !== area.path || area.name !== folder) return areaLabel(area);
+  return area.role || (area.kind === "folder" ? null : area.kind);
+}
+
+export const ZONE_GAP = 10;
+
+// Rough zone height from its tiles, so zones can go to the shortest column. Tiles wrap, so
+// count how many fit per row by name length.
+function zoneHeight(zone: MapZone, width: number): number {
+  const inner = Math.max(120, width - 26);
+  let rows = 1;
+  let used = 0;
+  for (const tile of zone.tiles) {
+    const tileWidth = Math.min(inner, 32 + tile.name.length * 7);
+    if (used > 0 && used + tileWidth > inner) {
+      rows += 1;
+      used = 0;
+    }
+    used += tileWidth + 6;
+  }
+  return 46 + rows * 32;
+}
+
+/**
+ * Splits zones into columns in map order. A zone in `placed` keeps its column; a new zone
+ * goes to the shortest column and is added to `placed`.
+ */
+export function masonry(
+  zones: readonly MapZone[],
+  columns: number,
+  width: number,
+  placed: Map<string, number>,
+): MapZone[][] {
+  const result: MapZone[][] = Array.from({ length: columns }, () => []);
+  const heights: number[] = Array.from({ length: columns }, () => 0);
+  const columnWidth = (width - ZONE_GAP * (columns - 1)) / columns;
+  for (const zone of zones) {
+    let column = placed.get(zone.dir);
+    if (column === undefined || column >= columns) {
+      column = heights.indexOf(Math.min(...heights));
+      placed.set(zone.dir, column);
+    }
+    result[column]?.push(zone);
+    heights[column] = (heights[column] ?? 0) + zoneHeight(zone, columnWidth) + ZONE_GAP;
+  }
+  return result;
+}

package/shared/project-setup.ts

@@ -0,0 +1,56 @@
+import type { InitProposal } from "./live";
+import type { ProjectConfig } from "./settings";
+
+// A setup proposal shows only fields that change; accepted fields append to the prompts.
+export type ProposalField = "instructions" | "steps" | "implement" | "review";
+type PromptProposal = Pick<InitProposal, ProposalField>;
+
+export interface FieldDiff {
+  field: ProposalField;
+  label: string;
+  current: string;
+  proposed: string;
+}
+
+export function proposalDiffs(config: ProjectConfig, proposal: PromptProposal): FieldDiff[] {
+  const steps = proposal.steps.map((step) => step.trim()).filter(Boolean);
+  const rows: FieldDiff[] = [
+    {
+      field: "instructions",
+      label: "Project instructions",
+      current: config.instructions.trim(),
+      proposed: proposal.instructions.trim(),
+    },
+    {
+      field: "steps",
+      label: "Project steps",
+      current: config.steps.join("\n"),
+      proposed: steps.join("\n"),
+    },
+    {
+      field: "implement",
+      label: "Implement: append to the prompt",
+      current: config.implement.mode === "default" ? "" : config.implement.text.trim(),
+      proposed: proposal.implement.trim(),
+    },
+    {
+      field: "review",
+      label: "Review: append to the prompt",
+      current: config.review.mode === "default" ? "" : config.review.text.trim(),
+      proposed: proposal.review.trim(),
+    },
+  ];
+  return rows.filter((row) => row.proposed && row.proposed !== row.current);
+}
+
+export function applyProposal(
+  proposal: PromptProposal,
+  fields: ReadonlySet<ProposalField>,
+): Partial<ProjectConfig> {
+  const patch: Partial<ProjectConfig> = {};
+  if (fields.has("instructions")) patch.instructions = proposal.instructions.trim();
+  if (fields.has("steps")) patch.steps = proposal.steps.map((s) => s.trim()).filter(Boolean);
+  if (fields.has("implement")) patch.implement = { mode: "append", text: proposal.implement.trim() };
+  if (fields.has("review")) patch.review = { mode: "append", text: proposal.review.trim() };
+  return patch;
+}

package/shared/prompts.ts

@@ -1,5 +1,7 @@
+import { TOOLS_SERVER } from "./agent-tools";
 import type { IssueDetail } from "./linear";
-import type { AgentAction, LinearSettings, ProjectConfig } from "./settings";
+import type { AgentAction, Guidance, LinearSettings, ProjectConfig } from "./settings";
+import { todoConventionLine } from "./todo-sync";
 
 export const DEFAULT_TEMPLATES: Record<AgentAction, string> = {
   implement: [
@@ -111,6 +113,91 @@ export interface ComposePromptInput {
   project: ProjectConfig | null;
   includeComments: boolean;
   extraInstructions: string;
+  /** Launch options that add instructions; the project's saved ones when omitted. */
+  guidance?: Guidance;
+  /** The Linear tools the agent gets; all of them when omitted. */
+  tools?: PromptTools;
+}
+
+/** What the prompt may tell the agent about the plugin's linear MCP server. */
+export interface PromptTools {
+  /** The agent gets the server. */
+  enabled: boolean;
+  /** The server has edit_issue. */
+  allowEdits: boolean;
+  /** Agents that start_agent may run at the same time; 0 has no limit. */
+  maxAgents: number;
+  /** Sub-issues that the user gave an agent, with the agent's name. */
+  assignments: readonly { identifier: string; label: string }[];
+}
+
+export const ALL_TOOLS: PromptTools = { enabled: true, allowEdits: true, maxAgents: 0, assignments: [] };
+
+const limitLine = (max: number) =>
+  `- Run at most ${max} of these agents at the same time. start_agent refuses more until one of them finishes.`;
+
+/** The instructions each guidance option adds, in prompt order. */
+export function guidanceSections(issue: IssueDetail, guidance: Guidance, tools: PromptTools = ALL_TOOLS): string[] {
+  const sections: string[] = [];
+  const example = issue.children[0]?.identifier ?? issue.identifier;
+  const edits = tools.enabled && tools.allowEdits;
+  if (guidance.updateLinear) {
+    const lines = [
+      "Keep Linear current while you work:",
+      `- Start each todo with the issue key it is for, such as "${example}: add the form".`,
+      "- Mark a todo in progress when you start it and completed when it is done. Linear Live moves the issue from these todos.",
+    ];
+    if (edits) {
+      lines.push(
+        `- Use the ${TOOLS_SERVER} MCP tools: read_issue shows an issue, and edit_issue changes its description.`,
+        "- When you finish a task list item in a description, check it off: replace `- [ ] item` with `- [x] item`.",
+        "- When the plan changes, update the description. Do not post comments.",
+      );
+    } else if (tools.enabled) {
+      lines.push(`- Use the ${TOOLS_SERVER} MCP tool read_issue to read an issue. Do not change descriptions or post comments.`);
+    } else lines.push("- Do not change the issue or post comments.");
+    sections.push(lines.join("\n"));
+  }
+  if (guidance.subagentKeys) {
+    sections.push(
+      [
+        "When you start a subagent:",
+        `- Begin its description and its prompt with the Linear issue key it works on, such as "${example}: review the form".`,
+        "- Tell it to put that key in the first line of its reply, and to state the new key if its work moves to another issue.",
+      ].join("\n"),
+    );
+  }
+  // Handing off work needs start_agent, so without the tools these sections are left out.
+  const handOff = tools.enabled && guidance.paseoSubagents;
+  const assigned = tools.enabled ? tools.assignments : [];
+  if (handOff) {
+    sections.push(
+      [
+        "Hand off work to Paseo agents, not to your built-in subagent tool:",
+        `- Start each one with the ${TOOLS_SERVER} start_agent tool, one agent for each sub-issue. It runs on your provider and model${assigned.length > 0 ? ", or on the agent the user chose for the sub-issue" : ""}.`,
+        "- Set its thinking to fit the task: low for search and reading, medium for routine edits, high for design, debugging, and review.",
+        `- Start its title with the issue key, such as "${example}: write the tests". Give the full task in its prompt, because it does not see your conversation.`,
+        "- Call wait_agent for each agent and read its result before you continue.",
+        ...(tools.maxAgents > 0 ? [limitLine(tools.maxAgents)] : []),
+      ].join("\n"),
+    );
+  }
+  if (assigned.length > 0) {
+    const lines = [
+      `The user chose an agent for these sub-issues. Start one agent for each of them with the ${TOOLS_SERVER} start_agent tool. The plugin runs it on the chosen agent. Do not do this work yourself.`,
+      ...assigned.map((entry) => `- ${entry.identifier}: ${entry.label}`),
+    ];
+    if (!handOff) {
+      lines.push(
+        "For each of these agents:",
+        `- Start its title with the issue key, such as "${assigned[0]?.identifier}: write the tests". Give the full task in its prompt, because it does not see your conversation.`,
+        "- Call wait_agent for each agent and read its result before you continue.",
+        ...(tools.maxAgents > 0 ? [limitLine(tools.maxAgents)] : []),
+      );
+    }
+    sections.push(lines.join("\n"));
+  }
+  return sections;
 }
 
 export function composePrompt(input: ComposePromptInput): string {
@@ -128,6 +215,8 @@ export function composePrompt(input: ComposePromptInput): string {
   ];
   // A template that drops {{issue}} still gets the snapshot so the agent never works blind.
   if (!/\{\{\s*issue\s*\}\}/.test(template)) sections.push(snapshot);
+  const convention = input.action === "implement" ? todoConventionLine(issue.children) : null;
+  if (convention) sections.push(convention);
   const instructions = project?.instructions.trim();
   if (instructions) sections.push(`Project instructions:\n${instructions}`);
   const steps = project?.steps.map((step) => step.trim()).filter(Boolean) ?? [];
@@ -136,6 +225,8 @@ export function composePrompt(input: ComposePromptInput): string {
       `Project steps:\n${steps.map((step, index) => `${index + 1}. ${step}`).join("\n")}`,
     );
   }
+  const guidance = input.guidance ?? project?.guidance;
+  if (guidance) sections.push(...guidanceSections(issue, guidance, input.tools));
   const extra = input.extraInstructions.trim();
   if (extra) sections.push(`Additional instructions:\n${extra}`);
   return sections.join("\n\n");
@@ -147,4 +238,20 @@ export function agentTitle(action: AgentAction, issue: { identifier: string; tit
   return `${prefix}: ${title}`.slice(0, 120);
 }
 
-export const AGENT_LABELS = { issue: "linear.issue", action: "linear.action" } as const;
+export const AGENT_LABELS = {
+  issue: "linear.issue",
+  action: "linear.action",
+  /** The Paseo project whose Linear key loaded the issue. */
+  project: "linear.project",
+  explore: "linear.explore",
+  init: "linear.init",
+  /** The grant of the agent's Linear MCP tools, so a tool call can find its agent. */
+  tools: "linear.tools",
+  /** The grant whose start_agent call made this agent. */
+  startedBy: "linear.started-by",
+} as const;
+
+/** Agents the plugin starts for itself: explore and project setup. */
+export function isInternalAgent(labels: Readonly<Record<string, string>> | undefined): boolean {
+  return Boolean(labels?.[AGENT_LABELS.explore] || labels?.[AGENT_LABELS.init]);
+}