clawspec 1.0.0

package/src/watchers/notifier.ts

@@ -0,0 +1,69 @@
+import type { OpenClawPluginApi, PluginLogger } from "openclaw/plugin-sdk";
+import { parseChannelKey } from "../utils/channel-key.ts";
+
+type ClawSpecNotifierOptions = {
+  api: OpenClawPluginApi;
+  logger: PluginLogger;
+};
+
+export class ClawSpecNotifier {
+  readonly api: OpenClawPluginApi;
+  readonly logger: PluginLogger;
+
+  constructor(options: ClawSpecNotifierOptions) {
+    this.api = options.api;
+    this.logger = options.logger;
+  }
+
+  async send(channelKey: string, text: string): Promise<void> {
+    const route = parseChannelKey(channelKey);
+    const accountId = route.accountId && route.accountId !== "default" ? route.accountId : undefined;
+
+    try {
+      switch (route.channel) {
+        case "discord":
+          await this.api.runtime.channel.discord.sendMessageDiscord(`channel:${route.channelId}`, text, {
+            cfg: this.api.config,
+            accountId,
+            silent: true,
+          });
+          return;
+        case "telegram":
+          await this.api.runtime.channel.telegram.sendMessageTelegram(route.channelId, text, {
+            cfg: this.api.config,
+            accountId,
+            silent: true,
+            messageThreadId: parseOptionalNumber(route.conversationId),
+          });
+          return;
+        case "slack":
+          await this.api.runtime.channel.slack.sendMessageSlack(route.channelId, text, {
+            cfg: this.api.config,
+            accountId,
+            threadTs: route.conversationId !== "main" ? route.conversationId : undefined,
+          });
+          return;
+        case "signal":
+          await this.api.runtime.channel.signal.sendMessageSignal(route.channelId, text, {
+            cfg: this.api.config,
+            accountId,
+          });
+          return;
+        default:
+          this.logger.info(`[clawspec] watcher update (${route.channel} ${route.channelId}): ${text}`);
+      }
+    } catch (error) {
+      this.logger.warn(
+        `[clawspec] failed to send watcher update to ${channelKey}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+}
+
+function parseOptionalNumber(value: string): number | undefined {
+  if (!value || value === "main") {
+    return undefined;
+  }
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}

package/src/worker/prompts.ts

@@ -0,0 +1,484 @@
+import path from "node:path";
+import type {
+  ExecutionMode,
+  OpenSpecApplyInstructionsResponse,
+  OpenSpecInstructionsResponse,
+  ProjectState,
+} from "../types.ts";
+import type { RepoStatePaths } from "../utils/paths.ts";
+import { resolveProjectScopedPath } from "../utils/paths.ts";
+
+export function buildExecutionSystemContext(repoPath: string, importedSkills?: string): string {
+  return [
+    "You are the ClawSpec execution worker running inside the user's visible OpenClaw chat.",
+    `Repository: ${repoPath}`,
+    "Core rules:",
+    "- Current ClawSpec state overrides any prior session memory, hook-generated memory, or recalled project notes.",
+    "- Ignore any remembered change names, tasks, or feature ideas that do not match the active repository and active change for this turn.",
+    "- The active change named in the execution context is the only valid OpenSpec change for this turn.",
+    "- Never read from, write to, or reference files under `openspec/changes/<other-change>`.",
+    "- Never rely on Memory Search results for unrelated historical changes. If memory mentions another change, treat it as stale and ignore it.",
+    "- OpenSpec is the canonical workflow source.",
+    "- tasks.md is the only task source of truth.",
+    "- Keep changes minimal and scoped to the active change.",
+    "- Use the repo-local ClawSpec control and result files exactly as instructed.",
+    "- Keep going until the change is done, paused, cancelled, blocked, or a true clarification is required.",
+    "- Progress reporting is mandatory in normal chat messages: announce each artifact refresh, each task start, each task completion, and the final status.",
+    importedSkills ? "" : "",
+    importedSkills ? "Use these imported OpenSpec workflow skills only where they are consistent with the active repository, active change, and current phase. If they conflict, follow the ClawSpec rules above." : "",
+    importedSkills ?? "",
+  ].join("\n");
+}
+
+export function buildPlanningSystemContext(params: {
+  repoPath: string;
+  importedSkills?: string;
+  mode: "discussion" | "sync";
+}): string {
+  return [
+    "You are the ClawSpec planning assistant running inside the user's visible OpenClaw chat.",
+    `Repository: ${params.repoPath}`,
+    params.mode === "sync"
+      ? "This turn is a deliberate planning sync turn. Refresh OpenSpec artifacts and stop before implementation."
+      : "This turn is a planning discussion turn. Explore and refine the change without implementing code.",
+    "Core rules:",
+    "- Current ClawSpec state overrides any prior session memory, hook-generated memory, or recalled project notes.",
+    "- Ignore any remembered change names, requirements, or feature threads that do not match the active repository and active change for this turn.",
+    "- The active change named in the planning context is the only valid OpenSpec change for this turn.",
+    "- Never create, switch to, inspect, or cite another OpenSpec change directory unless the user explicitly cancels or archives the current change first.",
+    "- Never rely on Memory Search results for unrelated historical changes. If memory mentions another change, treat it as stale and ignore it.",
+    "- OpenSpec is the canonical workflow source.",
+    "- proposal.md, specs, design.md, and tasks.md define planning state.",
+    "- Do not implement product code while in planning mode.",
+    "- Keep discussion grounded in the active repository and change.",
+    params.mode === "discussion"
+      ? "- Ordinary discussion mode never starts planning sync by itself. Only an explicit `cs-plan` request may start planning refresh."
+      : "- This sync turn is allowed to inspect and update planning artifacts for the active change.",
+    params.importedSkills ? "" : "",
+    params.importedSkills ? "Use these imported OpenSpec workflow skills only where they are consistent with the active repository, active change, and current phase. If they conflict, follow the ClawSpec rules above." : "",
+    params.importedSkills ?? "",
+  ].join("\n");
+}
+
+export function buildProjectSystemContext(params: {
+  repoPath: string;
+}): string {
+  return [
+    "You are the ClawSpec project assistant running inside the user's visible OpenClaw chat.",
+    `Repository: ${params.repoPath}`,
+    "Core rules:",
+    "- Current ClawSpec project selection overrides any prior session memory, hook-generated memory, or recalled project notes.",
+    "- Ignore remembered change names or project ideas unless the user explicitly re-selects or re-proposes them in this chat.",
+    "- Treat the selected repository as the default project context for this turn.",
+    "- If the user says 'this project', they mean the selected repository shown below.",
+    "- There is no active OpenSpec change yet unless the prompt says otherwise.",
+    "- Help the user discuss requirements, repo structure, and next steps without inventing a change name.",
+    "- If the user is ready to start structured planning, tell them to run `/clawspec proposal <change-name> [description]`.",
+  ].join("\n");
+}
+
+export function buildExecutionPrependContext(params: {
+  project: ProjectState;
+  mode: ExecutionMode;
+  userPrompt: string;
+  repoStatePaths: RepoStatePaths;
+}): string {
+  const project = params.project;
+  const changeName = project.changeName ?? "";
+  const tasksPath = project.repoPath && project.changeName
+    ? path.join(project.repoPath, "openspec", "changes", project.changeName, "tasks.md")
+    : "unknown";
+  const taskCounts = project.taskCounts;
+  const progressLabel = taskCounts
+    ? `${taskCounts.complete}/${taskCounts.total} complete, ${taskCounts.remaining} remaining`
+    : "unknown";
+
+  const resultTemplate = JSON.stringify({
+    version: 1,
+    changeName,
+    mode: params.mode,
+    status: "done",
+    timestamp: "ISO-8601 timestamp",
+    summary: "Short execution summary",
+    progressMade: true,
+    completedTask: "optional task id + description",
+    currentArtifact: "optional artifact id",
+    changedFiles: ["relative/path.ts"],
+    notes: ["short note"],
+    blocker: "optional blocker",
+    taskCounts: { total: 0, complete: 0, remaining: 0 },
+    remainingTasks: 0,
+  }, null, 2);
+
+  return [
+    "ClawSpec execution mode is armed for this chat.",
+    `Change: ${changeName}`,
+    `Mode: ${params.mode}`,
+    `Workspace: ${project.workspacePath ?? "_unknown_"}`,
+    `Repo path: ${project.repoPath ?? "_unknown_"}`,
+    `Change directory: ${project.changeDir ?? "_unknown_"}`,
+    "",
+    "Current user message that triggered this run:",
+    fence(params.userPrompt || "(empty)"),
+    "",
+    "Read these files before making decisions:",
+    `- ${params.repoStatePaths.stateFile}`,
+    `- ${params.repoStatePaths.executionControlFile}`,
+    `- ${params.repoStatePaths.planningJournalFile}`,
+    `- ${tasksPath}`,
+    project.changeDir ? `- ${displayPath(path.join(project.changeDir, "proposal.md"))}` : "",
+    project.changeDir ? `- ${displayPath(path.join(project.changeDir, "design.md"))}` : "",
+    project.changeDir ? `- ${displayPath(path.join(project.changeDir, "specs", "**", "*.md"))}` : "",
+    "",
+    "Required workflow:",
+    "1. Before any tool call or file edit, send a kickoff message in this shape: `Execution started for <change>. Phase: <planning-sync|implementation>. Progress: <complete>/<total> complete, <remaining> remaining. Next: <artifact or task>.`",
+    `   Current known progress: ${progressLabel}.`,
+    "2. Read execution-control.json first. If cancelRequested is true, stop safely, write execution-result.json with status `cancelled`, and do not continue implementation.",
+    "3. If pauseRequested is true before starting new work, stop safely, write execution-result.json with status `paused`, and do not continue implementation.",
+    "4. If planning-journal state is dirty or planning artifacts are missing, sync `proposal`, `specs`, `design`, and `tasks` in order using `openspec instructions <artifact> --change <name> --json`.",
+    "5. After planning sync, run `openspec instructions apply --change <name> --json`, read the returned context files, and use that instruction as the implementation guide.",
+    "6. Execute unchecked tasks from tasks.md sequentially. Each time a task is fully complete, update its checkbox from `- [ ]` to `- [x]` immediately.",
+    "7. Between artifacts and tasks, re-check execution-control.json for pauseRequested or cancelRequested.",
+    "8. Keep OpenSpec command activity visible by running those commands normally in this chat.",
+    "9. Keep the user informed in this chat with explicit progress messages.",
+    "10. Before each planning artifact refresh, send a short message naming the artifact you are about to refresh.",
+    "11. After each planning artifact refresh, send a short message saying what changed and what artifact comes next.",
+    "12. Before each implementation task, send a progress message in this shape: `Working on task <id>: <description>`.",
+    "13. Right after each completed task, send a progress message in this shape: `Completed task <id>: <summary>. Files: <file list or none>. Next: <next task or done>.`",
+    "14. If you hit a blocker, do not stop silently. Before ending, send a chat message in this shape: `Blocked: <exact reason>. Affected: <artifact or task ids>. Next: <what the user needs to do>.`",
+    "15. When the whole run finishes, send one short final summary that lists completed tasks, key changed files, and whether the change is done or blocked.",
+    "",
+    "Support-file updates required during this run:",
+    `- Update ${params.repoStatePaths.latestSummaryFile} with the latest concise status.`,
+    `- Append meaningful milestones to ${params.repoStatePaths.progressFile}.`,
+    `- Update ${params.repoStatePaths.changedFilesFile} with changed relative paths when you know them.`,
+    `- Append important reasoning or decisions to ${params.repoStatePaths.decisionLogFile}.`,
+    "",
+    `Before you stop for any reason, write ${params.repoStatePaths.executionResultFile} as valid JSON using this shape:`,
+    fence(resultTemplate, "json"),
+    "",
+    "Status rules for execution-result.json:",
+    "- `done`: all tasks complete.",
+    "- `paused`: pauseRequested was honored at a safe boundary.",
+    "- `cancelled`: cancelRequested was honored at a safe boundary.",
+    "- `blocked`: you hit a real blocker or missing requirement.",
+    "- `running`: only if you are deliberately yielding with work still in progress and no blocker; avoid this unless necessary.",
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+export function buildPlanningPrependContext(params: {
+  project: ProjectState;
+  userPrompt: string;
+  repoStatePaths: RepoStatePaths;
+  contextPaths: string[];
+  scaffoldOnly?: boolean;
+  mode: "discussion" | "sync";
+  nextActionHint?: "plan" | "work";
+}): string {
+  const project = params.project;
+
+  const workflow = params.mode === "sync"
+    ? [
+        "Required workflow for this turn:",
+        "0. The active change directory shown above is the only OpenSpec change directory you may inspect or modify in this turn.",
+        "1. Read planning-journal.jsonl, .openspec.yaml, and any planning artifacts that already exist.",
+        "2. Use the current visible chat context plus the planning journal to decide whether there are substantive new requirements, constraints, or design changes since the last planning sync.",
+        "3. If there is no substantive planning change, say so clearly in chat and do not rewrite artifacts unnecessarily.",
+        "4. Run `openspec status --change <name> --json` to inspect artifact readiness.",
+        "5. If artifacts are missing or stale, use `openspec instructions <artifact> --change <name> --json` and update `proposal`, `specs`, `design`, and `tasks` in dependency order.",
+        "6. Keep OpenSpec command activity visible by running those commands normally in this chat.",
+        "7. Before updating each artifact, post a short chat update naming the artifact you are about to refresh.",
+        "8. After updating each artifact, post a short chat update describing what changed and what artifact comes next.",
+        "9. Stop after planning artifacts are refreshed and apply-ready. Do not implement code in this turn.",
+        "10. End with a concise summary of what changed, what remains open, and tell the user to say `cs-work` when they want implementation to start.",
+        "11. Never scan sibling directories under `openspec/changes`, never switch to another change, and never restore or rewrite unrelated files.",
+      ]
+    : [
+        "Discussion rules for this turn:",
+        "1. Treat this chat as active OpenSpec planning for the current change.",
+        "2. Use the imported skills to explore scope, requirements, and design tradeoffs.",
+        "3. Do not implement code.",
+        "4. Do not tell the user to run `/clawspec use` again. This repo and change are already active in this chat.",
+        "5. Do not tell the user to start a second proposal for the same repo while this change is active.",
+        "6. If the user is actually describing a separate feature that should be a new change, explain that the current active change must be cancelled or archived first. Do not silently switch changes.",
+        "7. Missing `proposal.md`, `design.md`, `specs`, or `tasks.md` is normal before `cs-plan` runs. Do not treat missing planning artifacts as an error during discussion.",
+        "8. Only update planning artifacts if the user explicitly asks or if they send `cs-plan` in a later turn.",
+        "9. Do not edit any files, do not run git checkout/reset/restore, and do not create or modify OpenSpec artifacts during ordinary discussion turns.",
+        "10. Do not run `openspec status`, `openspec instructions`, `openspec apply`, or any other planning command during ordinary discussion turns.",
+        "11. Do not scan sibling directories under `openspec/changes`, do not inspect proposal/design/spec/tasks unless the user explicitly asks to review those files, and do not inspect any change other than the active one shown above.",
+        "12. Do not say planning has started, queued, refreshed, synced, or completed unless the user explicitly sent `cs-plan` in this same turn.",
+        "13. If the current user message adds, removes, or changes requirements, treat that as pending planning input, discuss it briefly, and explicitly tell the user that `cs-plan` is the next step before any further implementation.",
+        "14. When the current user message changes requirements, do not say the next step is `cs-work`, `continue implementation`, or anything equivalent in that same reply.",
+        "15. If you consult Memory Search at all, only use the active change name; never search for unrelated historical change names.",
+        params.nextActionHint === "plan"
+          ? "16. Remind the user to continue describing requirements if needed, then run `cs-plan`. Do not tell them to start `cs-work` yet."
+          : "16. Only mention `cs-work` as the next step when the current user message is not introducing new requirements. Any new requirement changes must point back to `cs-plan` first.",
+      ];
+
+  return [
+    params.mode === "sync"
+      ? "ClawSpec planning sync is active for this turn."
+      : "ClawSpec planning discussion mode is active for this turn.",
+    `Change: ${project.changeName ?? ""}`,
+    `Workspace: ${project.workspacePath ?? "_unknown_"}`,
+    `Repo path: ${project.repoPath ?? "_unknown_"}`,
+    `Change directory: ${project.changeDir ?? "_unknown_"}`,
+    "",
+    "Current user message:",
+    fence(params.userPrompt || "(empty)"),
+    "",
+    "Read these files before responding:",
+    ...params.contextPaths.map((contextPath) => `- ${contextPath}`),
+    params.scaffoldOnly ? "" : "",
+    params.scaffoldOnly ? "Only the change scaffold exists right now. That is expected before planning sync generates the first artifacts." : "",
+    "",
+    ...workflow,
+  ].join("\n");
+}
+
+export function buildProjectPrependContext(params: {
+  project: ProjectState;
+  userPrompt: string;
+}): string {
+  const project = params.project;
+  return [
+    "ClawSpec project context is active for this turn.",
+    `Project: ${project.projectName ?? "_unknown_"}`,
+    `Workspace: ${project.workspacePath ?? "_unknown_"}`,
+    `Repo path: ${project.repoPath ?? "_unknown_"}`,
+    "",
+    "Current user message:",
+    fence(params.userPrompt || "(empty)"),
+    "",
+    "Discussion rules for this turn:",
+    "1. Treat this repository as the user's current project context.",
+    "2. If the user refers to 'this project', map it to the repo path above.",
+    "3. Do not assume there is an active change yet.",
+    "4. If the user starts describing work they want to build, help refine it and tell them to create a new change with `/clawspec proposal <change-name> [description]` when they are ready.",
+  ].join("\n");
+}
+
+export function buildPluginReplySystemContext(): string {
+  return [
+    "The ClawSpec plugin already handled the control request before this turn.",
+    "Use the prepared result below to answer the user.",
+    "Do not run extra project workflow commands or edit files unless the prepared result explicitly asks for follow-up discussion.",
+  ].join("\n");
+}
+
+export function buildPluginReplyPrependContext(params: {
+  userPrompt: string;
+  resultText: string;
+  followUp?: string;
+}): string {
+  return [
+    "ClawSpec plugin result for this turn:",
+    fence(params.resultText, "markdown"),
+    params.followUp ? "" : "",
+    params.followUp ? `Follow-up guidance: ${params.followUp}` : "",
+    "",
+    "Current user message:",
+    fence(params.userPrompt || "(empty)"),
+    "",
+    "Respond to the user with the result and the follow-up guidance. Keep the wording direct.",
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+export function buildAcpPlanningTurnPrompt(params: {
+  project: ProjectState;
+  repoStatePaths: RepoStatePaths;
+  instructions: OpenSpecInstructionsResponse;
+  importedSkills?: string;
+}): string {
+  const dependencyPaths = params.instructions.dependencies
+    .filter((dependency) => dependency.done)
+    .map((dependency) => resolveProjectScopedPath(params.project, dependency.path));
+  const outputPath = resolveProjectScopedPath(params.project, params.instructions.outputPath);
+
+  return [
+    "You are the ClawSpec background planning worker.",
+    "Do not post chat messages. Communicate only through files.",
+    `Repository: ${params.project.repoPath ?? "_unknown_"}`,
+    `Change: ${params.project.changeName ?? "_unknown_"}`,
+    `Artifact: ${params.instructions.artifactId}`,
+    `Output path: ${outputPath}`,
+    importedSkillBlock(params.importedSkills),
+    "",
+    "Required behavior:",
+    "- Only work on the active change shown above.",
+    "- Never inspect or modify sibling directories under `openspec/changes`.",
+    "- Read the dependency files first if they exist.",
+    "- Follow the supplied OpenSpec instruction and template exactly enough to produce a valid artifact.",
+    "- Do not implement product code in this turn.",
+    "- Do not update any artifact other than the requested output path.",
+    `- Before stopping, write ${params.repoStatePaths.executionResultFile} as valid JSON.`,
+    "",
+    "Files to read first:",
+    `- ${params.repoStatePaths.stateFile}`,
+    `- ${params.repoStatePaths.planningJournalFile}`,
+    `- ${pathOrUnknown(params.project.changeDir, ".openspec.yaml")}`,
+    ...dependencyPaths.map((dependencyPath) => `- ${dependencyPath}`),
+    "",
+    "OpenSpec artifact instruction:",
+    fence(params.instructions.instruction, "markdown"),
+    "",
+    "OpenSpec artifact template:",
+    fence(params.instructions.template, "markdown"),
+    "",
+    "Execution result JSON template:",
+    fence(JSON.stringify({
+      version: 1,
+      changeName: params.project.changeName ?? "",
+      mode: "apply",
+      status: "running",
+      timestamp: "ISO-8601 timestamp",
+      summary: `Updated ${params.instructions.artifactId}.`,
+      progressMade: true,
+      currentArtifact: params.instructions.artifactId,
+      changedFiles: [relativeChangeFile(params.project, outputPath)],
+      notes: ["Short note about what changed"],
+      taskCounts: params.project.taskCounts ?? { total: 0, complete: 0, remaining: 0 },
+    }, null, 2), "json"),
+    "",
+    "If you are blocked, write `status: \"blocked\"` and set `blocker` plus a concise summary.",
+    "If you finish successfully, keep the status as `running` so the watcher can continue with the next artifact.",
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+export function buildAcpImplementationTurnPrompt(params: {
+  project: ProjectState;
+  repoStatePaths: RepoStatePaths;
+  apply: OpenSpecApplyInstructionsResponse;
+  task: { id: string; description: string };
+  tasks: Array<{ id: string; description: string }>;
+  mode: ExecutionMode;
+  importedSkills?: string;
+}): string {
+  const contextPaths = Object.values(params.apply.contextFiles).map((contextPath) =>
+    resolveProjectScopedPath(params.project, contextPath));
+  const tasksPath = params.project.repoPath && params.project.changeName
+    ? path.join(params.project.repoPath, "openspec", "changes", params.project.changeName, "tasks.md")
+    : "unknown";
+  const contextLabels = contextPaths.map((contextPath) => displayPath(contextPath));
+  const firstContextLabel = contextLabels[0] ?? displayPath(tasksPath);
+  const afterContextLabel = contextLabels[1] ?? `start task ${params.task.id}`;
+
+  const taskList = params.tasks.map((task) => `- ${task.id} ${task.description}`).join("\n");
+
+  return [
+    "You are the ClawSpec background implementation worker.",
+    "Do not post chat messages. Communicate only through files.",
+    `Repository: ${params.project.repoPath ?? "_unknown_"}`,
+    `Change: ${params.project.changeName ?? "_unknown_"}`,
+    `Mode: ${params.mode}`,
+    importedSkillBlock(params.importedSkills),
+    "",
+    "Tasks to implement (in order):",
+    taskList,
+    "",
+    "Required behavior:",
+    "- Implement ALL tasks listed above, one by one, in order.",
+    "- Read the context files first.",
+    "- Keep changes minimal and scoped to the active change.",
+    "- Do not inspect or modify sibling `openspec/changes/<other-change>` directories.",
+    `- Update ${tasksPath} by switching each task from \`- [ ]\` to \`- [x]\` as you complete it.`,
+    `- Append short progress events to ${params.repoStatePaths.workerProgressFile} as valid JSON Lines.`,
+    "- Progress events must be human-readable, one line each, and must match the actual work completed.",
+    `- Every progress event must include \`current\` (current task number) and \`total\` (total task count for this run).`,
+    `- Do not stay silent until \`task_start\`. Emit context-loading progress first.`,
+    `- Before reading the context bundle, append one \`status\` event like: \`Preparing ${params.task.id}: loading context. Next: read ${firstContextLabel}.\``,
+    "- After reading each context file, append one `status` event naming the file you just loaded and what comes next.",
+    `- After the last context file is loaded, append one \`status\` event like: \`Context ready for ${params.task.id}. Next: start implementation. This can take a little time, so please wait.\``,
+    `- Before each task starts, append a \`task_start\` event with a message like: \`Start ${params.task.id}: <short description>. Next: <next step>.\``,
+    `- Right after each task is complete, append a \`task_done\` event with a message like: \`Done ${params.task.id}: <short summary>. Changed <n> files: <preview or none>. Next: <next step or done>.\``,
+    "- If you hit a blocker, append one `blocked` event before writing the final execution result.",
+    `- After completing ALL tasks (or if blocked), write ${params.repoStatePaths.executionResultFile} as valid JSON.`,
+    "- If a task cannot be completed safely, stop and write `status: \"blocked\"` with a concise blocker message.",
+    "",
+    "OpenSpec apply instruction:",
+    fence(params.apply.instruction, "markdown"),
+    "",
+    "Context files to read first:",
+    ...contextPaths.map((contextPath) => `- ${contextPath}`),
+    "",
+    "Worker progress JSONL event template:",
+    fence(JSON.stringify({
+      version: 1,
+      timestamp: "ISO-8601 timestamp",
+      kind: "status",
+      current: 1,
+      total: params.tasks.length,
+      taskId: params.task.id,
+      message: `Preparing ${params.task.id}: loading context. Next: read ${firstContextLabel}.`,
+    }, null, 2), "json"),
+    "",
+    "Worker progress JSONL task-start example:",
+    fence(JSON.stringify({
+      version: 1,
+      timestamp: "ISO-8601 timestamp",
+      kind: "task_start",
+      current: 1,
+      total: params.tasks.length,
+      taskId: params.task.id,
+      message: `Start ${params.task.id}: ${params.task.description}. Next: ${params.tasks[1]?.id ?? afterContextLabel}.`,
+    }, null, 2), "json"),
+    "",
+    "Execution result JSON template:",
+    fence(JSON.stringify({
+      version: 1,
+      changeName: params.project.changeName ?? "",
+      mode: params.mode,
+      status: "done",
+      timestamp: "ISO-8601 timestamp",
+      summary: `Completed ${params.tasks.length} tasks.`,
+      progressMade: true,
+      completedTask: `${params.tasks[params.tasks.length - 1]?.id ?? ""} ${params.tasks[params.tasks.length - 1]?.description ?? ""}`,
+      changedFiles: ["relative/path.ts"],
+      notes: ["Short note about what was done"],
+      taskCounts: { total: params.apply.progress.total, complete: params.apply.progress.total, remaining: 0 },
+      remainingTasks: 0,
+    }, null, 2), "json"),
+    "",
+    "If all tasks are complete, set `status: \"done\"`.",
+    "If you completed some but got blocked on a later task, set `status: \"blocked\"` and list only what was accomplished.",
+    "If more tasks remain after those listed above, set `status: \"running\"`.",
+    "Never set `paused` or `cancelled` yourself; the watcher handles those states.",
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+function fence(text: string, language = "text"): string {
+  return `\`\`\`${language}\n${text}\n\`\`\``;
+}
+
+function importedSkillBlock(importedSkills?: string): string {
+  if (!importedSkills) {
+    return "";
+  }
+  return [
+    "Imported OpenSpec workflow skills:",
+    importedSkills,
+  ].join("\n");
+}
+
+function pathOrUnknown(rootPath: string | undefined, leafName: string): string {
+  return rootPath ? path.join(rootPath, leafName) : path.join("_unknown_", leafName);
+}
+
+function relativeChangeFile(project: ProjectState, targetPath: string): string {
+  if (!project.repoPath) {
+    return targetPath;
+  }
+  return path.relative(project.repoPath, resolveProjectScopedPath(project, targetPath)).split(path.sep).join("/");
+}
+
+function displayPath(targetPath: string): string {
+  return targetPath.split(path.sep).join("/");
+}

package/src/worker/skills.ts

@@ -0,0 +1,52 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readUtf8 } from "../utils/fs.ts";
+
+export type ClawSpecSkillKey = "apply" | "explore" | "propose";
+
+const skillCache = new Map<ClawSpecSkillKey, string>();
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+const skillPaths: Record<ClawSpecSkillKey, string> = {
+  apply: path.join(repoRoot, "skills", "openspec-apply-change.md"),
+  explore: path.join(repoRoot, "skills", "openspec-explore.md"),
+  propose: path.join(repoRoot, "skills", "openspec-propose.md"),
+};
+
+export async function loadClawSpecSkillBundle(keys: ClawSpecSkillKey[]): Promise<string> {
+  const uniqueKeys = Array.from(new Set(keys));
+  const sections: string[] = [];
+
+  for (const key of uniqueKeys) {
+    const body = await loadClawSpecSkill(key);
+    sections.push([
+      `## Imported Skill: ${skillName(key)}`,
+      "",
+      body.trim(),
+    ].join("\n"));
+  }
+
+  return sections.join("\n\n");
+}
+
+async function loadClawSpecSkill(key: ClawSpecSkillKey): Promise<string> {
+  const cached = skillCache.get(key);
+  if (cached) {
+    return cached;
+  }
+
+  const body = await readUtf8(skillPaths[key]);
+  skillCache.set(key, body);
+  return body;
+}
+
+function skillName(key: ClawSpecSkillKey): string {
+  switch (key) {
+    case "apply":
+      return "openspec-apply-change";
+    case "explore":
+      return "openspec-explore";
+    case "propose":
+      return "openspec-propose";
+  }
+}