clawspec 1.0.3 → 1.0.5

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.3",
+  "version": "1.0.5",
   "type": "module",
   "description": "OpenClaw plugin that orchestrates OpenSpec project workflows with visible main-agent execution.",
   "keywords": [
@@ -32,7 +32,10 @@
   "openclaw": {
     "extensions": [
       "./index.ts"
-    ]
+    ],
+    "compat": {
+      "pluginApi": ">=2026.3.24"
+    }
   },
   "peerDependencies": {
     "openclaw": ">=0.0.0"
@@ -43,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

@@ -28,7 +28,11 @@ import type {
   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,
@@ -955,7 +959,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 +1011,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 +1866,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 +1875,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 +1891,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 +1928,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 +2343,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 +2362,8 @@ export class ClawSpecService {
         lastSyncedAt,
       },
     }));
+
+    await this.maybeSendPlanningNextStepNotice(finalized, event);
   }
 
   private resolvePostRunStatus(
@@ -3008,6 +3153,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

@@ -40,7 +40,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 {

package/src/worker/prompts.ts

@@ -193,7 +193,7 @@ export function buildPlanningPrependContext(params: {
         "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.",
+        "10. End with a concise summary and a mandatory final line exactly in this shape: `Next: run `cs-work` to start implementation.`",
         "11. Never scan sibling directories under `openspec/changes`, never switch to another change, and never restore or rewrite unrelated files.",
       ]
     : [

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/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,7 @@ 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 ?? "", /mandatory final line exactly in this shape/i);
   assert.equal(runningProject?.status, "planning");
   assert.equal(runningProject?.phase, "planning_sync");
 
@@ -172,6 +173,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"));
+});