clawspec 1.0.4 → 1.0.6

package/README.md

@@ -224,15 +224,28 @@ If your host disables plugin hooks globally, keyword-based workflow will not wor
 
 ### 1. Install the plugin
 
-Recommended public install after publishing to npm:
+You can install ClawSpec in three common ways:
+
+Option A: OpenClaw plugin installer (recommended)
 
 ```powershell
 openclaw plugins install clawspec@latest
 ```
 
-`@latest` always resolves to the newest published ClawSpec release on npm.
+Option B: ClawHub CLI installer
+
+```powershell
+npx clawhub@latest install clawspec
+```
 
-Current OpenClaw builds do not accept raw GitHub URLs as ordinary plugin install specs. A GitHub repo by itself is not enough for `openclaw plugins install`; the standard public path is an npm package spec such as `clawspec@latest`.
+Option C: npm package tarball (manual fallback)
+
+```powershell
+$pkg = npm pack clawspec@latest
+openclaw plugins install $pkg
+```
+
+`@latest` always resolves to the newest published ClawSpec release on npm.
 
 If you want an unreleased commit before npm publish, clone the repository and install from the local checkout or a downloaded `.tgz` archive instead.
 

package/README.zh-CN.md

@@ -229,15 +229,28 @@ ClawSpec 依赖这几个 OpenClaw hook：
 
 ### 1. 安装插件
 
-npm 发布后的标准安装方式：
+常见安装方式有三种：
+
+方式 A：通过 OpenClaw 插件安装器（推荐）
 
 ```powershell
 openclaw plugins install clawspec@latest
 ```
 
-`@latest` 会始终解析到 npm 上最新发布的 ClawSpec 版本。
+方式 B：通过 ClawHub CLI 安装
+
+```powershell
+npx clawhub@latest install clawspec
+```
 
-当前 OpenClaw 一般不接受把 GitHub 仓库 URL 直接当作普通插件安装源。也就是说，单独一个 GitHub repo 还不够，公开安装路径通常还是 npm 包规格，例如 `clawspec@latest`。
+方式 C：通过 npm 包手工安装（兜底）
+
+```powershell
+$pkg = npm pack clawspec@latest
+openclaw plugins install $pkg
+```
+
+`@latest` 会始终解析到 npm 上最新发布的 ClawSpec 版本。
 
 如果你要安装一个还没发布到 npm 的提交，请改用本地 checkout 或下载好的 `.tgz` 包安装。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawspec",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "type": "module",
   "description": "OpenClaw plugin that orchestrates OpenSpec project workflows with visible main-agent execution.",
   "keywords": [
@@ -46,7 +46,7 @@
   "scripts": {
     "check": "node --experimental-strip-types -e \"import('./index.ts')\"",
     "test": "node --experimental-strip-types --test --test-reporter spec test/*.test.ts",
-    "test:fast": "node --experimental-strip-types --test --test-reporter spec test/acp-client.test.ts test/acpx-dependency.test.ts test/assistant-journal.test.ts test/command-surface.test.ts test/config.test.ts test/detach-attach.test.ts test/file-lock.test.ts test/fs-utils.test.ts test/helpers.test.ts test/keywords.test.ts test/notifier.test.ts test/openspec-dependency.test.ts test/pause-cancel.test.ts test/planning-journal.test.ts test/plugin-registration.test.ts test/project-memory.test.ts test/proposal.test.ts test/queue-planning.test.ts test/queue-work.test.ts test/service-archive.test.ts test/shell-command.test.ts test/state-store.test.ts test/tasks-and-checkpoint.test.ts test/use-project.test.ts test/worker-command.test.ts test/worker-io-helper.test.ts test/worker-skills.test.ts",
+    "test:fast": "node --experimental-strip-types --test --test-reporter spec test/acp-client.test.ts test/acpx-dependency.test.ts test/assistant-journal.test.ts test/command-surface.test.ts test/config.test.ts test/detach-attach.test.ts test/file-lock.test.ts test/fs-utils.test.ts test/helpers.test.ts test/keywords.test.ts test/notifier.test.ts test/openspec-dependency.test.ts test/paths-utils.test.ts test/pause-cancel.test.ts test/planning-journal.test.ts test/plugin-registration.test.ts test/project-memory.test.ts test/proposal.test.ts test/queue-planning.test.ts test/queue-work.test.ts test/service-archive.test.ts test/shell-command.test.ts test/state-store.test.ts test/tasks-and-checkpoint.test.ts test/use-project.test.ts test/worker-command.test.ts test/worker-io-helper.test.ts test/worker-skills.test.ts",
     "test:slow": "node --experimental-strip-types --test --test-reporter spec test/watcher-planning.test.ts test/watcher-work.test.ts test/recovery.test.ts"
   },
   "engines": {

package/src/control/keywords.ts

@@ -29,20 +29,21 @@ const COMMAND_ALIASES: Record<string, ClawSpecKeywordKind> = {
 
 export function parseClawSpecKeyword(text: string): ClawSpecKeywordIntent | null {
   const trimmed = text.trim();
-  if (!trimmed.toLowerCase().startsWith("cs-")) {
+  if (!trimmed) {
     return null;
   }
 
   const firstWhitespace = trimmed.search(/\s/);
   const rawCommand = firstWhitespace === -1 ? trimmed : trimmed.slice(0, firstWhitespace);
-  const kind = COMMAND_ALIASES[rawCommand.toLowerCase()];
+  const normalizedCommand = normalizeKeywordCommand(rawCommand);
+  const kind = COMMAND_ALIASES[normalizedCommand];
   if (!kind) {
     return null;
   }
 
   return {
     kind,
-    command: rawCommand.toLowerCase(),
+    command: normalizedCommand,
     args: firstWhitespace === -1 ? "" : trimmed.slice(firstWhitespace + 1).trim(),
     raw: trimmed,
   };
@@ -52,21 +53,27 @@ export function isClawSpecKeywordText(text: string): boolean {
   return parseClawSpecKeyword(text) !== null;
 }
 
-const EMBEDDED_KEYWORD_PATTERN = new RegExp(
-  `(?:^|\\r?\\n)\\s*(cs-(?:${Object.keys(COMMAND_ALIASES).map((k) => k.slice(3)).join("|")})(?:[^\\S\\r\\n]+[^\\r\\n]+)?)\\s*(?=\\r?\\n|$)`,
-  "i",
-);
-
 export function extractEmbeddedClawSpecKeyword(text: string): ClawSpecKeywordIntent | null {
   const direct = parseClawSpecKeyword(text);
   if (direct) {
     return direct;
   }
 
-  const embeddedMatch = text.match(EMBEDDED_KEYWORD_PATTERN);
-  if (!embeddedMatch?.[1]) {
-    return null;
+  for (const line of text.split(/\r?\n/)) {
+    const parsed = parseClawSpecKeyword(line.trim());
+    if (parsed) {
+      return parsed;
+    }
   }
 
-  return parseClawSpecKeyword(embeddedMatch[1]);
+  return null;
+}
+
+function normalizeKeywordCommand(rawCommand: string): string {
+  return rawCommand
+    .trim()
+    .replace(/^`+|`+$/g, "")
+    .replace(/^\/+/, "")
+    .replace(/[。！？!?,，；;：:]+$/u, "")
+    .toLowerCase();
 }

package/src/dependencies/openspec.ts

@@ -70,22 +70,26 @@ export async function ensureOpenSpecCli(
   }
 
   options.logger?.warn?.(
-    `[clawspec] openspec CLI not found (${globalCheck.message}); installing plugin-local ${OPENSPEC_PACKAGE_NAME}`,
+    `[clawspec] openspec CLI not ready (${globalCheck.message}); installing plugin-local ${OPENSPEC_PACKAGE_NAME}`,
   );
 
   const install = await runner({
     command: "npm",
-    args: ["install", "--omit=dev", "--no-save", "--package-lock=false", OPENSPEC_PACKAGE_NAME],
+    args: [
+      "install",
+      "--omit=dev",
+      "--no-save",
+      "--package-lock=false",
+      OPENSPEC_PACKAGE_NAME,
+    ],
     cwd: options.pluginRoot,
     env,
   });
   if (install.error || (install.code ?? 0) !== 0) {
     if (isMissingCommandResult(install, "npm")) {
-      throw new Error("npm is required to install plugin-local openspec but was not found on PATH");
+      throw new Error(buildOpenSpecInstallMessage("npm is not available on PATH"));
     }
-    throw new Error(
-      `failed to install plugin-local openspec: ${describeCommandFailure(install, "npm install")}`,
-    );
+    throw new Error(`failed to install plugin-local openspec: ${describeCommandFailure(install, "npm install")}`);
   }
 
   const postcheck = await checkOpenSpecVersion(runner, {
@@ -105,6 +109,14 @@ export async function ensureOpenSpecCli(
   };
 }
 
+export function buildOpenSpecInstallMessage(reason: string): string {
+  return [
+    `OpenSpec CLI is required but not available (${reason}).`,
+    "Install OpenSpec, then retry your command:",
+    "`npm install -g @fission-ai/openspec`",
+  ].join("\n");
+}
+
 async function checkOpenSpecVersion(
   runner: CommandRunner,
   params: {

package/src/index.ts

@@ -142,6 +142,20 @@ const plugin = {
             text: "ClawSpec is still bootstrapping dependencies. Try again in a moment.",
           };
         }
+        const subcommand = parseSubcommand(ctx.args);
+        if (requiresOpenSpec(subcommand)) {
+          try {
+            await ensureOpenSpecCli({
+              pluginRoot: PLUGIN_ROOT,
+              logger: api.logger,
+            });
+          } catch (error) {
+            return {
+              ok: false,
+              text: error instanceof Error ? error.message : String(error),
+            };
+          }
+        }
         return service.handleProjectCommand(ctx);
       },
     });
@@ -157,6 +171,20 @@ const plugin = {
         accountId: ctx.accountId,
         conversationId: ctx.conversationId,
         sessionKey: (ctx as { sessionKey?: string }).sessionKey,
+        from: event.from,
+        metadata: event.metadata,
+      }, event.content);
+    });
+
+    api.on("message_sent", async (event, ctx) => {
+      await stateStore.initialize();
+      if (!service || !event.success) {
+        return;
+      }
+      service.recordOutboundMessageFromContext({
+        channelId: ctx.channelId,
+        accountId: ctx.accountId,
+        conversationId: ctx.conversationId,
       }, event.content);
     });
 
@@ -179,3 +207,22 @@ const plugin = {
 };
 
 export default plugin;
+
+function parseSubcommand(args: string | undefined): string {
+  const trimmed = (args ?? "").trim();
+  if (!trimmed) {
+    return "";
+  }
+  const [first] = trimmed.split(/\s+/);
+  return (first ?? "").toLowerCase();
+}
+
+function requiresOpenSpec(subcommand: string): boolean {
+  return [
+    "use",
+    "proposal",
+    "continue",
+    "status",
+    "archive",
+  ].includes(subcommand);
+}

package/src/orchestrator/service.ts

@@ -23,12 +23,17 @@ import type {
   ExecutionResult,
   OpenSpecApplyInstructionsResponse,
   OpenSpecCommandResult,
+  OpenSpecInstructionsResponse,
   OpenSpecStatusResponse,
   ProjectState,
   TaskCountSummary,
 } from "../types.ts";
 import { splitSubcommand, tokenizeArgs } from "../utils/args.ts";
-import { buildChannelKeyFromCommand, buildLegacyChannelKeyFromCommand } from "../utils/channel-key.ts";
+import {
+  buildChannelKeyFromCommand,
+  buildLegacyChannelKeyFromCommand,
+  parseChannelKey,
+} from "../utils/channel-key.ts";
 import {
   appendUtf8,
   directoryExists,
@@ -562,6 +567,7 @@ export class ClawSpecService {
   private async buildPlanningSyncInjection(
     project: ProjectState,
     userPrompt: string,
+    instructionResults: Array<OpenSpecCommandResult<OpenSpecInstructionsResponse>>,
   ): Promise<{ prependContext?: string; prependSystemContext?: string }> {
     const repoStatePaths = getRepoStatePaths(project.repoPath!, this.archiveDirName);
     await this.ensureProjectSupportFiles(project);
@@ -580,13 +586,19 @@ export class ClawSpecService {
         contextPaths: planningContext.paths,
         scaffoldOnly: planningContext.scaffoldOnly,
         mode: "sync",
+        prefetchedInstructions: instructionResults.map((result) => result.parsed!).filter(Boolean),
       }),
     };
   }
 
   private async preparePlanningSync(channelKey: string): Promise<
     | { result: PluginCommandResult }
-    | { project: ProjectState; outputs: OpenSpecCommandResult[]; repoStatePaths: RepoStatePaths }
+    | {
+      project: ProjectState;
+      outputs: OpenSpecCommandResult[];
+      repoStatePaths: RepoStatePaths;
+      instructionResults: Array<OpenSpecCommandResult<OpenSpecInstructionsResponse>>;
+    }
   > {
     const project = await this.requireActiveProject(channelKey);
     if (!project.repoPath || !project.projectName || !project.changeName) {
@@ -657,6 +669,21 @@ export class ClawSpecService {
       }
       const statusResult = await this.openSpec.status(project.repoPath, project.changeName);
       outputs.push(statusResult);
+      const instructionResults = await this.refreshPlanningInstructionFiles(project, repoStatePaths);
+      outputs.push(...instructionResults);
+      await this.writeLatestSummary(
+        repoStatePaths,
+        `Planning instructions refreshed for ${project.changeName} via OpenSpec CLI.`,
+      );
+      await removeIfExists(repoStatePaths.executionControlFile);
+      await removeIfExists(repoStatePaths.executionResultFile);
+      await removeIfExists(repoStatePaths.workerProgressFile);
+      return {
+        project,
+        outputs,
+        repoStatePaths,
+        instructionResults,
+      };
     } catch (error) {
       if (error instanceof OpenSpecCommandError) {
         return {
@@ -673,15 +700,6 @@ export class ClawSpecService {
       }
       throw error;
     }
-
-    await removeIfExists(repoStatePaths.executionControlFile);
-    await removeIfExists(repoStatePaths.executionResultFile);
-    await removeIfExists(repoStatePaths.workerProgressFile);
-    return {
-      project,
-      outputs,
-      repoStatePaths,
-    };
   }
 
   private async startVisiblePlanningSync(
@@ -713,7 +731,34 @@ export class ClawSpecService {
       lastExecutionAt: startedAt,
     }));
 
-    return await this.buildPlanningSyncInjection(runningProject, userPrompt);
+    return await this.buildPlanningSyncInjection(runningProject, userPrompt, prepared.instructionResults);
+  }
+
+  private async refreshPlanningInstructionFiles(
+    project: ProjectState,
+    repoStatePaths: RepoStatePaths,
+  ): Promise<Array<OpenSpecCommandResult<OpenSpecInstructionsResponse>>> {
+    if (!project.repoPath || !project.changeName) {
+      return [];
+    }
+
+    const artifactIds = ["proposal", "specs", "design", "tasks"] as const;
+    await ensureDir(repoStatePaths.planningInstructionsRoot);
+    const results: Array<OpenSpecCommandResult<OpenSpecInstructionsResponse>> = [];
+
+    for (const artifactId of artifactIds) {
+      const result = await this.openSpec.instructionsArtifact(project.repoPath, artifactId, project.changeName);
+      results.push(result);
+      await writeJsonFile(path.join(repoStatePaths.planningInstructionsRoot, `${artifactId}.json`), {
+        generatedAt: new Date().toISOString(),
+        command: result.command,
+        cwd: result.cwd,
+        durationMs: result.durationMs,
+        instruction: result.parsed,
+      });
+    }
+
+    return results;
   }
 
   private async collectPlanningContextPaths(
@@ -724,6 +769,17 @@ export class ClawSpecService {
       repoStatePaths.stateFile,
       repoStatePaths.planningJournalFile,
     ];
+    const instructionFiles = [
+      path.join(repoStatePaths.planningInstructionsRoot, "proposal.json"),
+      path.join(repoStatePaths.planningInstructionsRoot, "specs.json"),
+      path.join(repoStatePaths.planningInstructionsRoot, "design.json"),
+      path.join(repoStatePaths.planningInstructionsRoot, "tasks.json"),
+    ];
+    for (const instructionFile of instructionFiles) {
+      if (await pathExists(instructionFile)) {
+        paths.push(instructionFile);
+      }
+    }
 
     if (!project.changeDir) {
       return {
@@ -955,7 +1011,11 @@ export class ClawSpecService {
   async workspaceProject(channelKey: string, rawArgs: string): Promise<PluginCommandResult> {
     const currentWorkspace = await this.workspaceStore.getCurrentWorkspace(channelKey);
     const project = await this.ensureSessionProject(channelKey, currentWorkspace);
-    const requested = rawArgs.trim();
+    const parsedArg = this.parseSinglePathArgument(rawArgs, "Usage: `/clawspec workspace <path>`.\nIf the path contains spaces, wrap it in quotes.");
+    if ("error" in parsedArg) {
+      return errorReply(parsedArg.error);
+    }
+    const requested = parsedArg.value;
 
     if (!requested) {
       return okReply(await this.buildWorkspaceText(project));
@@ -1003,7 +1063,11 @@ export class ClawSpecService {
   async useProject(channelKey: string, rawArgs: string): Promise<PluginCommandResult> {
     const workspacePath = await this.workspaceStore.getCurrentWorkspace(channelKey);
     const project = await this.ensureSessionProject(channelKey, workspacePath);
-    const input = rawArgs.trim();
+    const parsedArg = this.parseSinglePathArgument(rawArgs, "Usage: `/clawspec use <project-name>`.\nIf the project path contains spaces, wrap it in quotes.");
+    if ("error" in parsedArg) {
+      return errorReply(parsedArg.error);
+    }
+    const input = parsedArg.value;
 
     if (!input) {
       return okReply(await this.buildWorkspaceText(project));
@@ -1854,6 +1918,7 @@ export class ClawSpecService {
     channelId?: string;
     accountId?: string;
     conversationId?: string;
+    from?: string;
     metadata?: Record<string, unknown>;
   }, text: string): boolean {
     const normalized = sanitizePlanningMessageText(text).trim();
@@ -1862,6 +1927,10 @@ export class ClawSpecService {
     }
 
     const metadata = params.metadata;
+    const normalizedFrom = params.from?.trim().toLowerCase();
+    if (normalizedFrom && ["assistant", "bot", "system", "plugin", "agent", "tool", "worker"].includes(normalizedFrom)) {
+      return true;
+    }
     const selfFlags = [
       metadata?.fromSelf,
       metadata?.isSelf,
@@ -1874,6 +1943,20 @@ export class ClawSpecService {
       return true;
     }
 
+    const metadataRoles = [
+      metadata?.role,
+      metadata?.senderRole,
+      metadata?.authorRole,
+      metadata?.messageRole,
+      metadata?.sourceRole,
+      metadata?.actorRole,
+    ]
+      .filter((value): value is string => typeof value === "string")
+      .map((value) => value.trim().toLowerCase());
+    if (metadataRoles.some((value) => ["assistant", "bot", "system", "plugin", "agent", "tool", "worker"].includes(value))) {
+      return true;
+    }
+
     const scopeKey = this.buildMessageScopeKey(params);
     const now = Date.now();
     const entries = (this.recentOutboundMessages.get(scopeKey) ?? [])
@@ -1897,6 +1980,118 @@ export class ClawSpecService {
     ].join(":");
   }
 
+  private parseSinglePathArgument(
+    rawArgs: string,
+    usageMessage: string,
+  ): { value: string } | { error: string } {
+    const trimmed = rawArgs.trim();
+    if (!trimmed) {
+      return { value: "" };
+    }
+
+    const firstChar = trimmed[0];
+    if (firstChar === "\"" || firstChar === "'") {
+      if (trimmed.length < 2 || !trimmed.endsWith(firstChar)) {
+        return { error: "Unterminated quoted argument." };
+      }
+      const inner = trimmed.slice(1, -1).trim();
+      return { value: inner };
+    }
+
+    if (/\s/.test(trimmed)) {
+      return { error: usageMessage };
+    }
+
+    return { value: trimmed };
+  }
+
+  private async maybeSendPlanningNextStepNotice(project: ProjectState, event: AgentEndEvent): Promise<void> {
+    if (!project.changeName) {
+      return;
+    }
+
+    const latestAssistantText = sanitizePlanningMessageText(extractLatestMessageTextByRole(event.messages, "assistant") ?? "").toLowerCase();
+    const alreadyContainsNextStep = latestAssistantText.includes("cs-work")
+      || latestAssistantText.includes("/clawspec archive")
+      || latestAssistantText.includes("run `cs-plan`");
+    if (alreadyContainsNextStep) {
+      return;
+    }
+
+    const projectLabel = project.projectName ?? "project";
+    if (project.status === "ready" && project.phase === "tasks") {
+      await this.sendChannelUpdate(
+        project.channelKey,
+        `✅ ${projectLabel}-${project.changeName} Planning ready. Next: run \`cs-work\` to start implementation.`,
+      );
+      return;
+    }
+
+    if (project.status === "done") {
+      await this.sendChannelUpdate(
+        project.channelKey,
+        `🏁 ${projectLabel}-${project.changeName} Planning complete and tasks are already done. Next: use \`/clawspec archive\`.`,
+      );
+      return;
+    }
+
+    if (project.status === "blocked") {
+      await this.sendChannelUpdate(
+        project.channelKey,
+        `⚠ ${projectLabel}-${project.changeName} Planning blocked. Next: review blockers, then run \`cs-plan\` again.`,
+      );
+    }
+  }
+
+  private async sendChannelUpdate(channelKey: string, text: string): Promise<void> {
+    const runtime = (this.api as { runtime?: OpenClawPluginApi["runtime"] }).runtime;
+    if (!runtime?.channel) {
+      return;
+    }
+
+    const route = parseChannelKey(channelKey);
+    const accountId = route.accountId && route.accountId !== "default" ? route.accountId : undefined;
+
+    try {
+      switch (route.channel) {
+        case "discord":
+          await runtime.channel.discord.sendMessageDiscord(`channel:${route.channelId}`, text, {
+            cfg: this.api.config,
+            accountId,
+            silent: true,
+          });
+          return;
+        case "telegram":
+          await runtime.channel.telegram.sendMessageTelegram(route.channelId, text, {
+            cfg: this.api.config,
+            accountId,
+            silent: true,
+            messageThreadId: parseOptionalNumber(route.conversationId),
+          });
+          return;
+        case "slack":
+          await runtime.channel.slack.sendMessageSlack(route.channelId, text, {
+            cfg: this.api.config,
+            accountId,
+            threadTs: route.conversationId !== "main" ? route.conversationId : undefined,
+          });
+          return;
+        case "signal":
+          await runtime.channel.signal.sendMessageSignal(route.channelId, text, {
+            cfg: this.api.config,
+            accountId,
+          });
+          return;
+        default:
+          this.logger.info(`[clawspec] planning notice (${route.channel} ${route.channelId}): ${text}`);
+      }
+    } catch (error) {
+      this.logger.warn(
+        `[clawspec] failed to send planning notice to ${channelKey}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
   private async ensureSessionProject(channelKey: string, workspacePath: string): Promise<ProjectState> {
     const existing = await this.stateStore.getActiveProject(channelKey);
     if (existing) {
@@ -2200,7 +2395,7 @@ export class ClawSpecService {
     }
     await this.writeLatestSummary(repoStatePaths, latestSummary);
 
-    await this.stateStore.updateProject(project.channelKey, (current) => ({
+    const finalized = await this.stateStore.updateProject(project.channelKey, (current) => ({
       ...current,
       status,
       phase,
@@ -2219,6 +2414,8 @@ export class ClawSpecService {
         lastSyncedAt,
       },
     }));
+
+    await this.maybeSendPlanningNextStepNotice(finalized, event);
   }
 
   private resolvePostRunStatus(
@@ -3008,6 +3205,14 @@ function isWorkflowControlLine(line: string): boolean {
     || lower === "`cs-work` is not available yet.";
 }
 
+function parseOptionalNumber(value: string): number | undefined {
+  if (!value || value === "main") {
+    return undefined;
+  }
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }

package/src/utils/paths.ts

@@ -14,6 +14,7 @@ export type RepoStatePaths = {
   latestSummaryFile: string;
   planningJournalFile: string;
   planningJournalSnapshotFile: string;
+  planningInstructionsRoot: string;
   rollbackManifestFile: string;
   snapshotsRoot: string;
   archivesRoot: string;
@@ -40,7 +41,8 @@ export function expandHomeDir(input: string): string {
 
 export function resolveUserPath(input: string, baseDir = process.cwd()): string {
   const expanded = expandHomeDir(input);
-  return path.isAbsolute(expanded) ? path.normalize(expanded) : path.resolve(baseDir, expanded);
+  const isAbsolute = path.isAbsolute(expanded) || path.win32.isAbsolute(expanded);
+  return isAbsolute ? path.normalize(expanded) : path.resolve(baseDir, expanded);
 }
 
 export function getProjectMemoryFilePath(stateDir: string): string {
@@ -74,6 +76,7 @@ export function getRepoStatePaths(repoPath: string, archiveDirName: string): Rep
     latestSummaryFile: path.join(root, "latest-summary.md"),
     planningJournalFile: path.join(root, "planning-journal.jsonl"),
     planningJournalSnapshotFile: path.join(root, "planning-journal.snapshot.json"),
+    planningInstructionsRoot: path.join(root, "planning-instructions"),
     rollbackManifestFile: path.join(root, "rollback-manifest.json"),
     snapshotsRoot: path.join(root, "snapshots"),
     archivesRoot: path.join(root, archiveDirName),

package/src/worker/prompts.ts

@@ -139,6 +139,7 @@ export function buildExecutionPrependContext(params: {
     "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.",
+    "6.1 For code-change tasks, add or update automated tests before marking the task done, and report the test command/result in progress updates.",
     "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.",
@@ -177,6 +178,7 @@ export function buildPlanningPrependContext(params: {
   scaffoldOnly?: boolean;
   mode: "discussion" | "sync";
   nextActionHint?: "plan" | "work";
+  prefetchedInstructions?: OpenSpecInstructionsResponse[];
 }): string {
   const project = params.project;
 
@@ -185,16 +187,17 @@ export function buildPlanningPrependContext(params: {
         "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.",
+        "2. Treat the prefetched OpenSpec instruction files in this context as the authoritative source for artifact structure, output paths, and writing guidance.",
+        "3. 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.",
+        "4. If there is no substantive planning change, say so clearly in chat and do not rewrite artifacts unnecessarily.",
+        "5. If artifacts are missing or stale, update `proposal`, `specs`, `design`, and `tasks` in dependency order using those prefetched OpenSpec instruction files.",
+        "6. Do not generate or rewrite planning artifacts from ad-hoc structure guesses; follow OpenSpec instruction/template constraints only.",
         "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.",
+        "9. For any implementation-oriented task item, ensure tasks.md contains an explicit testing task (new tests or updated tests) and a validation command.",
+        "10. Stop after planning artifacts are refreshed and apply-ready. Do not implement code in this turn.",
+        "11. End with a concise summary and a mandatory final line exactly in this shape: `Next: run `cs-work` to start implementation.`",
+        "12. Never scan sibling directories under `openspec/changes`, never switch to another change, and never restore or rewrite unrelated files.",
       ]
     : [
         "Discussion rules for this turn:",
@@ -232,6 +235,14 @@ export function buildPlanningPrependContext(params: {
     "",
     "Read these files before responding:",
     ...params.contextPaths.map((contextPath) => `- ${contextPath}`),
+    params.mode === "sync" ? "" : "",
+    params.mode === "sync" ? "Prefetched OpenSpec instructions for this turn:" : "",
+    ...(params.mode === "sync"
+      ? (params.prefetchedInstructions ?? [])
+        .map((instruction) =>
+          `- ${instruction.artifactId}: ${displayPath(resolveProjectScopedPath(project, instruction.outputPath))}`,
+        )
+      : []),
     params.scaffoldOnly ? "" : "",
     params.scaffoldOnly ? "Only the change scaffold exists right now. That is expected before planning sync generates the first artifacts." : "",
     "",

package/test/assistant-journal.test.ts

@@ -134,3 +134,35 @@ test("assistant discussion replies are not journaled after the chat is detached"
 
   assert.equal(entries.length, 0);
 });
+
+test("inbound bot/system messages are ignored by planning journal capture", async () => {
+  const harness = await createServiceHarness("clawspec-ignore-bot-inbound-");
+  const { service, stateStore, repoPath } = harness;
+  const channelKey = "discord:ignore-bot-inbound:default:main";
+  const promptContext = createPromptContext("ignore-bot-inbound");
+
+  await service.startProject(channelKey);
+  await service.useProject(channelKey, "demo-app");
+  await service.proposalProject(channelKey, "demo-change Demo change");
+
+  await service.recordPlanningMessageFromContext(
+    {
+      ...promptContext,
+      from: "assistant",
+      metadata: {
+        role: "assistant",
+        fromSelf: true,
+      },
+    },
+    "Planning ready. Next: run `cs-work` to start implementation.",
+  );
+
+  const repoStatePaths = getRepoStatePaths(repoPath, "archives");
+  const journalStore = new PlanningJournalStore(repoStatePaths.planningJournalFile);
+  const entries = await journalStore.list("demo-change");
+  const project = await stateStore.getActiveProject(channelKey);
+
+  assert.equal(entries.length, 0);
+  assert.equal(project?.planningJournal?.dirty, false);
+  assert.equal(project?.planningJournal?.entryCount, 0);
+});

package/test/helpers/harness.ts

@@ -133,6 +133,27 @@ export async function createServiceHarness(prefix: string): Promise<{
         ],
       },
     }),
+    instructionsArtifact: async (cwd: string, artifactId: string, changeName: string) => ({
+      command: `openspec instructions ${artifactId} --change ${changeName} --json`,
+      cwd,
+      stdout: "{}",
+      stderr: "",
+      durationMs: 1,
+      parsed: {
+        changeName,
+        artifactId,
+        schemaName: "spec-driven",
+        changeDir,
+        outputPath: artifactId === "specs"
+          ? path.join(changeDir, "specs", "demo-spec", "spec.md")
+          : path.join(changeDir, `${artifactId}.md`),
+        description: `Refresh ${artifactId}`,
+        instruction: `Use ${artifactId} template`,
+        template: `# ${artifactId}`,
+        dependencies: [],
+        unlocks: [],
+      },
+    }),
     instructionsApply: async (cwd: string, changeName: string) => ({
       command: `openspec instructions apply --change ${changeName} --json`,
       cwd,

package/test/keywords.test.ts

@@ -51,6 +51,12 @@ test("parseClawSpecKeyword trims input", () => {
   assert.equal(result?.kind, "work");
 });
 
+test("parseClawSpecKeyword accepts slash-prefixed and punctuated control words", () => {
+  assert.equal(parseClawSpecKeyword("/cs-work")?.kind, "work");
+  assert.equal(parseClawSpecKeyword("`cs-plan`")?.kind, "plan");
+  assert.equal(parseClawSpecKeyword("cs-work。")?.kind, "work");
+});
+
 test("isClawSpecKeywordText returns boolean correctly", () => {
   assert.equal(isClawSpecKeywordText("cs-plan"), true);
   assert.equal(isClawSpecKeywordText("hello"), false);
@@ -69,6 +75,12 @@ test("extractEmbeddedClawSpecKeyword finds keyword with args in multiline text",
   assert.equal(result?.args, "hello world");
 });
 
+test("extractEmbeddedClawSpecKeyword finds slash-prefixed keyword in multiline text", () => {
+  const text = "Summary:\n/cs-work\nProceed please.";
+  const result = extractEmbeddedClawSpecKeyword(text);
+  assert.equal(result?.kind, "work");
+});
+
 test("extractEmbeddedClawSpecKeyword returns direct match for single-line input", () => {
   const result = extractEmbeddedClawSpecKeyword("cs-status");
   assert.equal(result?.kind, "status");

package/test/openspec-dependency.test.ts

@@ -1,7 +1,7 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import path from "node:path";
-import { ensureOpenSpecCli, OPENSPEC_PACKAGE_NAME } from "../src/dependencies/openspec.ts";
+import { buildOpenSpecInstallMessage, ensureOpenSpecCli } from "../src/dependencies/openspec.ts";
 
 const ROOT_PREFIX = process.platform === "win32" ? "C:\\clawspec-test" : "/tmp/clawspec-test";
 
@@ -33,35 +33,36 @@ test("ensureOpenSpecCli uses the global openspec command when available", async
   assert.equal(calls.some((call) => call.command === "npm"), false);
 });
 
-test("ensureOpenSpecCli installs a plugin-local openspec when none is available", async () => {
+test("ensureOpenSpecCli installs plugin-local openspec when local and global are unavailable", async () => {
   const calls: Array<{ command: string; args: string[] }> = [];
-  let localCheckCount = 0;
-
   const result = await ensureOpenSpecCli({
     pluginRoot: ROOT_PREFIX,
     runner: async ({ command, args }) => {
       calls.push({ command, args });
       if (command === LOCAL_COMMAND) {
-        localCheckCount += 1;
-        if (localCheckCount === 1) {
-          return { code: 1, stdout: "", stderr: "not found" };
+        const versionChecks = calls.filter((call) => call.command === LOCAL_COMMAND && call.args[0] === "--version").length;
+        if (versionChecks >= 2) {
+          return { code: 0, stdout: "1.2.3\n", stderr: "" };
         }
-        return { code: 0, stdout: "1.2.0\n", stderr: "" };
+        return { code: 1, stdout: "", stderr: "not found" };
       }
       if (command === "openspec") {
         return { code: 1, stdout: "", stderr: "not found" };
       }
       if (command === "npm") {
-        return { code: 0, stdout: "installed\n", stderr: "" };
+        return { code: 0, stdout: "installed", stderr: "" };
       }
       return { code: 1, stdout: "", stderr: "unexpected command" };
     },
   });
 
   assert.equal(result.source, "local");
-  assert.equal(result.version, "1.2.0");
-  assert.equal(
-    calls.some((call) => call.command === "npm" && call.args.includes(OPENSPEC_PACKAGE_NAME)),
-    true,
-  );
+  assert.equal(result.version, "1.2.3");
+  assert.equal(calls.some((call) => call.command === "npm"), true);
+});
+
+test("buildOpenSpecInstallMessage includes install command", () => {
+  const message = buildOpenSpecInstallMessage("not found");
+  assert.match(message, /npm install -g @fission-ai\/openspec/);
+  assert.match(message, /not found/);
 });

package/test/paths-utils.test.ts

@@ -0,0 +1,30 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { resolveUserPath } from "../src/utils/paths.ts";
+
+test("resolveUserPath expands home directory shorthand", () => {
+  const actual = resolveUserPath("~/Desktop/workspace/ai_workspace", "/tmp/base");
+  const expected = path.join(os.homedir(), "Desktop", "workspace", "ai_workspace");
+  assert.equal(actual, expected);
+});
+
+test("resolveUserPath resolves relative path against base directory", () => {
+  const base = path.join(os.homedir(), "clawspec", "workspace");
+  const actual = resolveUserPath("demo-app", base);
+  assert.equal(actual, path.resolve(base, "demo-app"));
+});
+
+test("resolveUserPath keeps POSIX absolute path absolute", () => {
+  const absolute = "/tmp/clawspec-posix-absolute";
+  const actual = resolveUserPath(absolute, "/tmp/base");
+  assert.equal(actual, path.normalize(absolute));
+});
+
+test("resolveUserPath keeps Windows drive absolute path absolute on all platforms", () => {
+  const absolute = "C:\\Users\\dev\\workspace\\demo";
+  const actual = resolveUserPath(absolute, "/tmp/base");
+  assert.equal(actual, path.normalize(absolute));
+});
+

package/test/queue-planning.test.ts

@@ -156,6 +156,9 @@ test("cs-plan runs visible planning sync and writes a fresh snapshot", async ()
   const runningProject = await stateStore.getActiveProject(channelKey);
 
   assert.match(injected?.prependContext ?? "", /ClawSpec planning sync is active for this turn/);
+  assert.match(injected?.prependContext ?? "", /Prefetched OpenSpec instructions for this turn/);
+  assert.match(injected?.prependContext ?? "", /planning-instructions[\\/]+proposal\.json/);
+  assert.match(injected?.prependContext ?? "", /mandatory final line exactly in this shape/i);
   assert.equal(runningProject?.status, "planning");
   assert.equal(runningProject?.phase, "planning_sync");
 
@@ -172,6 +175,7 @@ test("cs-plan runs visible planning sync and writes a fresh snapshot", async ()
   assert.equal(finalized?.status, "ready");
   assert.equal(finalized?.phase, "tasks");
   assert.equal(finalized?.planningJournal?.dirty, false);
+  assert.match(finalized?.latestSummary ?? "", /Say `cs-work` to start implementation/);
   assert.equal(snapshotExists, true);
   assert.equal(snapshot?.changeName, "demo-change");
 });

package/test/use-project.test.ts

@@ -1,5 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import os from "node:os";
 import path from "node:path";
 import { pathExists } from "../src/utils/fs.ts";
 import { createServiceHarness } from "./helpers/harness.ts";
@@ -17,3 +18,50 @@ test("useProject initializes repo and selects project", async () => {
   assert.equal(project?.repoPath, path.join(workspacePath, "demo-app"));
   assert.equal(await pathExists(path.join(workspacePath, "demo-app", "openspec", "config.yaml")), true);
 });
+
+test("workspaceProject resolves quoted home-relative path without nesting into default workspace", async () => {
+  const harness = await createServiceHarness("clawspec-workspace-home-");
+  const { service, stateStore, workspacePath } = harness;
+  const channelKey = "discord:workspace-home:default:main";
+
+  await service.startProject(channelKey);
+  const result = await service.workspaceProject(channelKey, "\"~/Desktop/workspace/ai_workspacce\"");
+  const project = await stateStore.getActiveProject(channelKey);
+  const expected = path.join(os.homedir(), "Desktop", "workspace", "ai_workspacce");
+
+  assert.match(result.text ?? "", /Workspace switched/);
+  assert.equal(project?.workspacePath, expected);
+  assert.equal(project?.workspacePath?.includes(workspacePath), false);
+});
+
+test("workspaceProject keeps absolute paths as absolute targets", async () => {
+  const harness = await createServiceHarness("clawspec-workspace-abs-");
+  const { service, stateStore } = harness;
+  const channelKey = "discord:workspace-abs:default:main";
+
+  await service.startProject(channelKey);
+
+  const unixAbsolute = process.platform === "win32" ? "/var/tmp/clawspec-abs" : "/tmp/clawspec-abs";
+  await service.workspaceProject(channelKey, unixAbsolute);
+  const projectAfterUnix = await stateStore.getActiveProject(channelKey);
+  assert.equal(projectAfterUnix?.workspacePath, path.normalize(unixAbsolute));
+
+  const driveAbsolute = "C:\\Users\\dev\\workspace\\clawspec-abs";
+  await service.workspaceProject(channelKey, driveAbsolute);
+  const projectAfterDrive = await stateStore.getActiveProject(channelKey);
+  assert.equal(projectAfterDrive?.workspacePath, path.normalize(driveAbsolute));
+});
+
+test("useProject accepts quoted project names with spaces", async () => {
+  const harness = await createServiceHarness("clawspec-use-project-space-");
+  const { service, stateStore, workspacePath } = harness;
+  const channelKey = "discord:use-project-space:default:main";
+
+  await service.startProject(channelKey);
+  const result = await service.useProject(channelKey, "\"team app\"");
+  const project = await stateStore.getActiveProject(channelKey);
+
+  assert.match(result.text ?? "", /Project Selected/);
+  assert.equal(project?.projectName, "team app");
+  assert.equal(project?.repoPath, path.join(workspacePath, "team app"));
+});