clawspec 1.0.6 → 1.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawspec",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "type": "module",
   "description": "OpenClaw plugin that orchestrates OpenSpec project workflows with visible main-agent execution.",
   "keywords": [

package/src/index.ts

@@ -188,6 +188,14 @@ const plugin = {
       }, event.content);
     });
 
+    api.on("before_dispatch", async (event, ctx) => {
+      await stateStore.initialize();
+      if (!service) {
+        return;
+      }
+      return await service.handleBeforeDispatch(event, ctx);
+    });
+
     api.on("before_prompt_build", async (event, ctx) => {
       await stateStore.initialize();
       if (!service) {

package/src/orchestrator/service.ts

@@ -125,6 +125,14 @@ type PromptBuildContext = {
   conversationId?: string;
 };
 
+type DispatchContext = {
+  sessionKey?: string;
+  channel?: string;
+  channelId?: string;
+  accountId?: string;
+  conversationId?: string;
+};
+
 type AgentEndEvent = {
   messages: unknown[];
   success: boolean;
@@ -277,6 +285,28 @@ export class ClawSpecService {
     return await this.buildPlanningDiscussionInjection(boundProject, event.prompt);
   }
 
+  async handleBeforeDispatch(
+    event: { content: string; channel?: string },
+    ctx: DispatchContext,
+  ): Promise<{ handled: boolean; text?: string } | void> {
+    const keyword = extractEmbeddedClawSpecKeyword(event.content);
+    if (!keyword || keyword.kind === "plan") {
+      return;
+    }
+
+    const result = await this.executeDirectKeyword(keyword, {
+      channel: event.channel,
+      channelId: ctx.channelId,
+      accountId: ctx.accountId,
+      conversationId: ctx.conversationId,
+      sessionKey: ctx.sessionKey,
+    });
+    return {
+      handled: true,
+      text: result.text ?? "",
+    };
+  }
+
   private async handleKeywordPrompt(
     keyword: ClawSpecKeywordIntent,
     event: PromptBuildEvent,
@@ -298,78 +328,89 @@ export class ClawSpecService {
         }
         return this.buildPluginReplyInjection(event.prompt, planningSync.text ?? "");
       }
+      case "work":
+      case "continue": {
+        const result = await this.executeDirectKeyword(keyword, ctx);
+        return this.buildPluginReplyInjection(event.prompt, result.text ?? "");
+      }
+      case "attach": {
+        const result = await this.executeDirectKeyword(keyword, ctx);
+        return this.buildPluginReplyInjection(event.prompt, result.text ?? "");
+      }
+      case "detach": {
+        const result = await this.executeDirectKeyword(keyword, ctx);
+        return this.buildPluginReplyInjection(event.prompt, result.text ?? "");
+      }
+      case "pause": {
+        const result = await this.executeDirectKeyword(keyword, ctx);
+        return this.buildPluginReplyInjection(event.prompt, result.text ?? "");
+      }
+      case "status": {
+        const result = await this.executeDirectKeyword(keyword, ctx);
+        return this.buildPluginReplyInjection(event.prompt, result.text ?? "");
+      }
+      case "cancel": {
+        const result = await this.executeDirectKeyword(keyword, ctx);
+        return this.buildPluginReplyInjection(event.prompt, result.text ?? "");
+      }
+    }
+  }
+
+  private async executeDirectKeyword(
+    keyword: ClawSpecKeywordIntent,
+    ctx: DispatchContext,
+  ): Promise<PluginCommandResult> {
+    const match = await this.resolveControlProjectForPromptContext(ctx);
+
+    switch (keyword.kind) {
       case "work":
       case "continue": {
         if (!match?.project.repoPath || !match.project.changeName) {
-          return this.buildPluginReplyInjection(
-            event.prompt,
-            "Select a project and create a change first with `/clawspec use <project-name>` and `/clawspec proposal <change-name> [description]`.",
-          );
+          return errorReply("Select a project and create a change first with `/clawspec use <project-name>` and `/clawspec proposal <change-name> [description]`.");
         }
         if (["archived", "cancelled"].includes(match.project.status)) {
-          return this.buildPluginReplyInjection(
-            event.prompt,
-            `Change \`${match.project.changeName}\` is no longer active. Create a new proposal before starting implementation again.`,
-          );
+          return errorReply(`Change \`${match.project.changeName}\` is no longer active. Create a new proposal before starting implementation again.`);
         }
         if (match.project.status === "planning" || match.project.execution?.action === "plan") {
-          return this.buildPluginReplyInjection(
-            event.prompt,
-            `Planning sync for \`${match.project.changeName}\` is still running. Wait for it to finish before starting implementation.`,
-          );
+          return errorReply(`Planning sync for \`${match.project.changeName}\` is still running. Wait for it to finish before starting implementation.`);
         }
         if (keyword.kind === "work" && requiresPlanningSync(match.project)) {
-          return this.buildPluginReplyInjection(
-            event.prompt,
-            buildPlanningRequiredMessage(match.project),
-          );
+          return errorReply(buildPlanningRequiredMessage(match.project));
         }
         if (match.project.execution?.state === "running" || match.project.status === "running") {
-          return this.buildPluginReplyInjection(
-            event.prompt,
-            `Background execution for \`${match.project.changeName}\` is already running.`,
-          );
+          return okReply(`Background execution for \`${match.project.changeName}\` is already running.`);
         }
-        const result = keyword.kind === "continue"
+        return keyword.kind === "continue"
           ? await this.continueProject(match.channelKey)
           : await this.queueWorkProject(match.channelKey, "apply");
-        return this.buildPluginReplyInjection(event.prompt, result.text ?? "");
       }
-      case "attach": {
+      case "attach":
         if (!match) {
-          return this.buildPluginReplyInjection(event.prompt, "No active ClawSpec project is bound to this chat.");
+          return errorReply("No active ClawSpec project is bound to this chat.");
         }
-        const result = await this.attachProject(match.channelKey, ctx.sessionKey);
-        return this.buildPluginReplyInjection(event.prompt, result.text ?? "");
-      }
-      case "detach": {
+        return await this.attachProject(match.channelKey, ctx.sessionKey);
+      case "detach":
         if (!match) {
-          return this.buildPluginReplyInjection(event.prompt, "No active ClawSpec project is bound to this chat.");
+          return errorReply("No active ClawSpec project is bound to this chat.");
         }
-        const result = await this.detachProject(match.channelKey);
-        return this.buildPluginReplyInjection(event.prompt, result.text ?? "");
-      }
-      case "pause": {
+        return await this.detachProject(match.channelKey);
+      case "pause":
         if (!match) {
-          return this.buildPluginReplyInjection(event.prompt, "No active ClawSpec project is bound to this chat.");
+          return errorReply("No active ClawSpec project is bound to this chat.");
         }
-        const result = await this.pauseProject(match.channelKey);
-        return this.buildPluginReplyInjection(event.prompt, result.text ?? "");
-      }
-      case "status": {
+        return await this.pauseProject(match.channelKey);
+      case "status":
         if (!match) {
-          return this.buildPluginReplyInjection(event.prompt, "No active ClawSpec project is bound to this chat.");
+          return errorReply("No active ClawSpec project is bound to this chat.");
         }
-        const result = await this.projectStatus(match.channelKey);
-        return this.buildPluginReplyInjection(event.prompt, result.text ?? "");
-      }
-      case "cancel": {
+        return await this.projectStatus(match.channelKey);
+      case "cancel":
         if (!match) {
-          return this.buildPluginReplyInjection(event.prompt, "No active ClawSpec project is bound to this chat.");
+          return errorReply("No active ClawSpec project is bound to this chat.");
         }
-        const result = await this.cancelProject(match.channelKey);
-        return this.buildPluginReplyInjection(event.prompt, result.text ?? "");
-      }
+        return await this.cancelProject(match.channelKey);
+      case "plan":
+        return errorReply("`cs-plan` must run through the visible planning turn.");
     }
   }
 
@@ -587,6 +628,7 @@ export class ClawSpecService {
         scaffoldOnly: planningContext.scaffoldOnly,
         mode: "sync",
         prefetchedInstructions: instructionResults.map((result) => result.parsed!).filter(Boolean),
+        prefetchedInstructionCommands: instructionResults.map((result) => result.command).filter(Boolean),
       }),
     };
   }
@@ -749,13 +791,19 @@ export class ClawSpecService {
     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`), {
+      const instructionFile = path.join(repoStatePaths.planningInstructionsRoot, `${artifactId}.json`);
+      await writeJsonFile(instructionFile, {
         generatedAt: new Date().toISOString(),
         command: result.command,
         cwd: result.cwd,
         durationMs: result.durationMs,
         instruction: result.parsed,
       });
+      const relativeInstructionFile = normalizeSlashes(path.relative(project.repoPath, instructionFile) || instructionFile);
+      await this.sendChannelUpdate(
+        project.channelKey,
+        `\`${result.command}\` done. Wrote \`${relativeInstructionFile}\`.`,
+      );
     }
 
     return results;

package/src/worker/prompts.ts

@@ -179,6 +179,7 @@ export function buildPlanningPrependContext(params: {
   mode: "discussion" | "sync";
   nextActionHint?: "plan" | "work";
   prefetchedInstructions?: OpenSpecInstructionsResponse[];
+  prefetchedInstructionCommands?: string[];
 }): string {
   const project = params.project;
 
@@ -198,6 +199,7 @@ export function buildPlanningPrependContext(params: {
         "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.",
+        "13. Do not claim that OpenSpec instructions were skipped in this sync turn. The plugin already executed those commands before this turn began.",
       ]
     : [
         "Discussion rules for this turn:",
@@ -243,6 +245,15 @@ export function buildPlanningPrependContext(params: {
           `- ${instruction.artifactId}: ${displayPath(resolveProjectScopedPath(project, instruction.outputPath))}`,
         )
       : []),
+    ...(params.mode === "sync"
+      ? (params.prefetchedInstructions ?? []).flatMap((instruction) => [
+        "",
+        formatPrefetchedInstructionBlock(project, instruction),
+      ])
+      : []),
+    params.mode === "sync" ? "" : "",
+    params.mode === "sync" ? "OpenSpec commands already executed by the plugin before this turn:" : "",
+    ...(params.mode === "sync" ? (params.prefetchedInstructionCommands ?? []).map((command) => `- ${command}`) : []),
     params.scaffoldOnly ? "" : "",
     params.scaffoldOnly ? "Only the change scaffold exists right now. That is expected before planning sync generates the first artifacts." : "",
     "",
@@ -503,3 +514,17 @@ function relativeChangeFile(project: ProjectState, targetPath: string): string {
 function displayPath(targetPath: string): string {
   return targetPath.split(path.sep).join("/");
 }
+
+function formatPrefetchedInstructionBlock(
+  project: ProjectState,
+  instruction: OpenSpecInstructionsResponse,
+): string {
+  const outputPath = displayPath(resolveProjectScopedPath(project, instruction.outputPath));
+  return [
+    `Artifact ${instruction.artifactId} (output: ${outputPath})`,
+    "Instruction:",
+    fence(instruction.instruction || "(empty)", "markdown"),
+    "Template:",
+    fence(instruction.template || "(empty)", "markdown"),
+  ].join("\n");
+}

package/test/helpers/harness.ts

@@ -72,6 +72,7 @@ export async function createServiceHarness(prefix: string): Promise<{
   memoryStore: ProjectMemoryStore;
   workspaceStore: WorkspaceStore;
   watcherManager: FakeWatcherManager;
+  sentMessages: Array<{ to: string; text: string }>;
   workspacePath: string;
   repoPath: string;
   changeDir: string;
@@ -174,6 +175,7 @@ export async function createServiceHarness(prefix: string): Promise<{
   } as Record<string, any>;
 
   const watcherManager = createFakeWatcherManager();
+  const sentMessages: Array<{ to: string; text: string }> = [];
   const service = new ClawSpecService({
     api: {
       config: {
@@ -189,6 +191,18 @@ export async function createServiceHarness(prefix: string): Promise<{
           ],
         },
       },
+      runtime: {
+        channel: {
+          discord: {
+            sendMessageDiscord: async (to: string, text: string) => {
+              sentMessages.push({ to, text });
+            },
+          },
+          telegram: {},
+          slack: {},
+          signal: {},
+        },
+      },
       logger: createLogger(),
     } as any,
     config: {
@@ -221,6 +235,7 @@ export async function createServiceHarness(prefix: string): Promise<{
     memoryStore,
     workspaceStore,
     watcherManager,
+    sentMessages,
     workspacePath,
     repoPath,
     changeDir,

package/test/queue-planning.test.ts

@@ -133,7 +133,7 @@ test("apply reports no new planning notes when the chat context is detached", as
 
 test("cs-plan runs visible planning sync and writes a fresh snapshot", async () => {
   const harness = await createServiceHarness("clawspec-visible-plan-");
-  const { service, stateStore, repoPath } = harness;
+  const { service, stateStore, repoPath, openSpec, sentMessages } = harness;
   const channelKey = "discord:visible-plan:default:main";
   const promptContext = {
     trigger: "user",
@@ -149,6 +149,13 @@ test("cs-plan runs visible planning sync and writes a fresh snapshot", async ()
   await service.proposalProject(channelKey, "demo-change Demo change");
   await service.recordPlanningMessageFromContext(promptContext, "add another API endpoint");
 
+  const instructionCalls: string[] = [];
+  const originalInstructionsArtifact = openSpec.instructionsArtifact;
+  openSpec.instructionsArtifact = async (...args: unknown[]) => {
+    instructionCalls.push(String(args[1]));
+    return await originalInstructionsArtifact(...args);
+  };
+
   const injected = await service.handleBeforePromptBuild(
     { prompt: "cs-plan", messages: [] },
     promptContext,
@@ -157,10 +164,30 @@ test("cs-plan runs visible planning sync and writes a fresh snapshot", async ()
 
   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 ?? "", /OpenSpec commands already executed by the plugin before this turn/);
+  assert.match(injected?.prependContext ?? "", /openspec instructions proposal --change demo-change --json/);
   assert.match(injected?.prependContext ?? "", /planning-instructions[\\/]+proposal\.json/);
+  assert.deepEqual(instructionCalls, ["proposal", "specs", "design", "tasks"]);
   assert.match(injected?.prependContext ?? "", /mandatory final line exactly in this shape/i);
   assert.equal(runningProject?.status, "planning");
   assert.equal(runningProject?.phase, "planning_sync");
+  assert.deepEqual(
+    sentMessages.map((entry) => entry.to),
+    [
+      "channel:visible-plan",
+      "channel:visible-plan",
+      "channel:visible-plan",
+      "channel:visible-plan",
+    ],
+  );
+  assert.match(sentMessages[0]?.text ?? "", /openspec instructions proposal --change demo-change --json/);
+  assert.match(sentMessages[0]?.text ?? "", /planning-instructions\/proposal\.json/);
+  assert.match(sentMessages[1]?.text ?? "", /openspec instructions specs --change demo-change --json/);
+  assert.match(sentMessages[1]?.text ?? "", /planning-instructions\/specs\.json/);
+  assert.match(sentMessages[2]?.text ?? "", /openspec instructions design --change demo-change --json/);
+  assert.match(sentMessages[2]?.text ?? "", /planning-instructions\/design\.json/);
+  assert.match(sentMessages[3]?.text ?? "", /openspec instructions tasks --change demo-change --json/);
+  assert.match(sentMessages[3]?.text ?? "", /planning-instructions\/tasks\.json/);
 
   await service.handleAgentEnd(
     { messages: [], success: true, durationMs: 10 },

package/test/queue-work.test.ts

@@ -65,6 +65,64 @@ test("work queues background implementation", async () => {
   assert.deepEqual(watcherManager.wakeCalls, [channelKey]);
 });
 
+test("before_dispatch intercepts cs-work and queues background implementation directly", async () => {
+  const harness = await createServiceHarness("clawspec-work-dispatch-");
+  const { service, stateStore, watcherManager, repoPath, workspacePath, changeDir } = harness;
+  const channelKey = "discord:work-dispatch:default:main";
+  const tasksPath = path.join(changeDir, "tasks.md");
+  await writeUtf8(tasksPath, "- [ ] 1.1 Build the demo endpoint\n");
+
+  harness.openSpec.instructionsApply = async (cwd: string, changeName: string) => ({
+    command: `openspec instructions apply --change ${changeName} --json`,
+    cwd,
+    stdout: "{}",
+    stderr: "",
+    durationMs: 1,
+    parsed: {
+      changeName,
+      changeDir,
+      schemaName: "spec-driven",
+      contextFiles: { tasks: tasksPath },
+      progress: { total: 1, complete: 0, remaining: 1 },
+      tasks: [{ id: "1.1", description: "Build the demo endpoint", done: false }],
+      state: "ready",
+      instruction: "Implement the remaining task.",
+    },
+  });
+
+  await seedPlanningProject(stateStore, channelKey, {
+    workspacePath,
+    repoPath,
+    projectName: "demo-app",
+    changeName: "queue-work",
+    changeDir,
+    phase: "tasks",
+    status: "ready",
+    planningDirty: false,
+  });
+  await stateStore.updateProject(channelKey, (current) => ({
+    ...current,
+    boundSessionKey: "agent:main:discord:channel:work-dispatch",
+  }));
+
+  const result = await service.handleBeforeDispatch(
+    { content: "cs-work", channel: "discord" },
+    {
+      channelId: "work-dispatch",
+      accountId: "default",
+      conversationId: "main",
+      sessionKey: "agent:main:discord:channel:work-dispatch",
+    },
+  );
+  const project = await stateStore.getActiveProject(channelKey);
+
+  assert.equal(result?.handled, true);
+  assert.match(result?.text ?? "", /Execution Queued/);
+  assert.equal(project?.status, "armed");
+  assert.equal(project?.execution?.action, "work");
+  assert.deepEqual(watcherManager.wakeCalls, [channelKey]);
+});
+
 test("main chat agent end does not clear a background worker run", async () => {
   const harness = await createServiceHarness("clawspec-work-session-");
   const { service, stateStore, repoPath, workspacePath, changeDir } = harness;