clawspec 1.0.7 → 1.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawspec",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "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.");
     }
   }
 
@@ -750,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;
@@ -904,7 +951,8 @@ export class ClawSpecService {
       return;
     }
 
-    const planningProject = await this.findPlanningProjectBySessionKey(ctx.sessionKey);
+    const planningProject = await this.findPlanningProjectBySessionKey(ctx.sessionKey)
+      ?? await this.findPlanningProjectByContext(ctx);
     if (planningProject) {
       await this.finalizePlanningTurn(planningProject, event);
       return;
@@ -2267,6 +2315,27 @@ export class ClawSpecService {
     );
   }
 
+  private async findPlanningProjectByContext(ctx: PromptBuildContext): Promise<ProjectState | undefined> {
+    const routingContext = deriveRoutingContext(ctx);
+    if (!routingContext.channelId) {
+      return undefined;
+    }
+
+    const match = await this.stateStore.findActiveProjectForMessage({
+      channel: routingContext.channel,
+      channelId: routingContext.channelId,
+      accountId: routingContext.accountId,
+      conversationId: routingContext.conversationId,
+    });
+    if (!match) {
+      return undefined;
+    }
+
+    return match.project.status === "planning" && match.project.phase === "planning_sync"
+      ? match.project
+      : undefined;
+  }
+
   private async findDiscussionProjectBySessionKey(sessionKey?: string): Promise<ProjectState | undefined> {
     if (!sessionKey) {
       return undefined;
@@ -3125,6 +3194,10 @@ function isPassiveAssistantPlanningMessage(text: string): boolean {
     return true;
   }
 
+  if (/^heartbeat(?:[_\s-]?(?:ok|ping|alive))?$/i.test(normalized)) {
+    return true;
+  }
+
   const collapsed = normalized.replace(/\s+/g, " ").trim();
   if (/^[▶✓⚠↻ℹ]/u.test(collapsed)) {
     return true;

package/src/worker/prompts.ts

@@ -190,16 +190,18 @@ export function buildPlanningPrependContext(params: {
         "1. Read planning-journal.jsonl, .openspec.yaml, and any planning artifacts that already exist.",
         "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. 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.",
-        "13. Do not claim that OpenSpec instructions were skipped in this sync turn. The plugin already executed those commands before this turn began.",
+        "4. The allowed planning scope is limited to what is explicitly supported by the current user message, the planning journal, existing dependency artifacts, and the prefetched OpenSpec instructions.",
+        "5. Do not invent endpoints, features, constraints, files, acceptance criteria, test scenarios, or architecture details that are not grounded in those sources.",
+        "6. If there is no substantive planning change, say so clearly in chat and do not rewrite artifacts unnecessarily.",
+        "7. If artifacts are missing or stale, update `proposal`, `specs`, `design`, and `tasks` in dependency order using those prefetched OpenSpec instruction files.",
+        "8. Do not generate or rewrite planning artifacts from ad-hoc structure guesses; follow OpenSpec instruction/template constraints only.",
+        "9. Before updating each artifact, post a short chat update naming the artifact you are about to refresh.",
+        "10. After updating each artifact, post a short chat update describing what changed and what artifact comes next.",
+        "11. For any implementation-oriented task item, ensure tasks.md contains an explicit testing task (new tests or updated tests) and a validation command.",
+        "12. Stop after planning artifacts are refreshed and apply-ready. Do not implement code in this turn.",
+        "13. End with a concise summary and a mandatory final line exactly in this shape: `Next: run `cs-work` to start implementation.`",
+        "14. Never scan sibling directories under `openspec/changes`, never switch to another change, and never restore or rewrite unrelated files.",
+        "15. 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:",

package/test/assistant-journal.test.ts

@@ -166,3 +166,38 @@ test("inbound bot/system messages are ignored by planning journal capture", asyn
   assert.equal(project?.planningJournal?.dirty, false);
   assert.equal(project?.planningJournal?.entryCount, 0);
 });
+
+test("heartbeat assistant replies are not appended to the planning journal", async () => {
+  const harness = await createServiceHarness("clawspec-ignore-heartbeat-journal-");
+  const { service, repoPath } = harness;
+  const channelKey = "discord:ignore-heartbeat-journal:default:main";
+  const promptContext = createPromptContext("ignore-heartbeat-journal");
+  const userPrompt = "Add one more API endpoint.";
+
+  await service.startProject(channelKey);
+  await service.useProject(channelKey, "demo-app");
+  await service.proposalProject(channelKey, "demo-change Demo change");
+  await service.recordPlanningMessageFromContext(promptContext, userPrompt);
+  await service.handleBeforePromptBuild(
+    { prompt: userPrompt, messages: [] },
+    promptContext,
+  );
+
+  await service.handleAgentEnd(
+    {
+      success: true,
+      messages: [
+        { role: "user", content: userPrompt },
+        { role: "assistant", content: "HEARTBEAT_OK" },
+      ],
+    },
+    promptContext,
+  );
+
+  const repoStatePaths = getRepoStatePaths(repoPath, "archives");
+  const journalStore = new PlanningJournalStore(repoStatePaths.planningJournalFile);
+  const entries = await journalStore.list("demo-change");
+
+  assert.equal(entries.length, 1);
+  assert.equal(entries[0]?.role, "user");
+});

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, openSpec } = harness;
+  const { service, stateStore, repoPath, openSpec, sentMessages } = harness;
   const channelKey = "discord:visible-plan:default:main";
   const promptContext = {
     trigger: "user",
@@ -168,9 +168,28 @@ test("cs-plan runs visible planning sync and writes a fresh snapshot", async ()
   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 ?? "", /allowed planning scope is limited/i);
+  assert.match(injected?.prependContext ?? "", /Do not invent endpoints, features, constraints, files, acceptance criteria, test scenarios, or architecture details/i);
   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 },
@@ -190,6 +209,48 @@ test("cs-plan runs visible planning sync and writes a fresh snapshot", async ()
   assert.equal(snapshot?.changeName, "demo-change");
 });
 
+test("cs-plan finalizes and writes a fresh snapshot even if agent_end sessionKey changes", async () => {
+  const harness = await createServiceHarness("clawspec-visible-plan-fallback-");
+  const { service, stateStore, repoPath } = harness;
+  const channelKey = "discord:visible-plan-fallback:default:main";
+  const promptContext = {
+    trigger: "user",
+    channel: "discord",
+    channelId: "visible-plan-fallback",
+    accountId: "default",
+    conversationId: "main",
+    sessionKey: "agent:main:discord:channel:visible-plan-fallback",
+  };
+
+  await service.startProject(channelKey);
+  await service.useProject(channelKey, "demo-app");
+  await service.proposalProject(channelKey, "demo-change Demo change");
+  await service.recordPlanningMessageFromContext(promptContext, "add another API endpoint");
+
+  await service.handleBeforePromptBuild(
+    { prompt: "cs-plan", messages: [] },
+    promptContext,
+  );
+
+  await service.handleAgentEnd(
+    { messages: [], success: true, durationMs: 10 },
+    {
+      ...promptContext,
+      sessionKey: "agent:main:discord:channel:visible-plan-fallback:other",
+    },
+  );
+
+  const finalized = await stateStore.getActiveProject(channelKey);
+  const repoStatePaths = getRepoStatePaths(repoPath, "archives");
+  const snapshot = await readJsonFile<any>(repoStatePaths.planningJournalSnapshotFile, null);
+
+  assert.equal(finalized?.status, "ready");
+  assert.equal(finalized?.phase, "tasks");
+  assert.equal(finalized?.planningJournal?.dirty, false);
+  assert.equal(snapshot?.changeName, "demo-change");
+  assert.equal(snapshot?.entryCount, 1);
+});
+
 test("cs-plan clears stale execution control artifacts from earlier worker runs", async () => {
   const harness = await createServiceHarness("clawspec-visible-plan-cleanup-");
   const { service, stateStore, repoPath } = harness;

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;