clawspec 1.0.5 → 1.0.7

package/package.json

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

package/src/orchestrator/service.ts

@@ -23,6 +23,7 @@ import type {
   ExecutionResult,
   OpenSpecApplyInstructionsResponse,
   OpenSpecCommandResult,
+  OpenSpecInstructionsResponse,
   OpenSpecStatusResponse,
   ProjectState,
   TaskCountSummary,
@@ -566,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);
@@ -584,13 +586,20 @@ export class ClawSpecService {
         contextPaths: planningContext.paths,
         scaffoldOnly: planningContext.scaffoldOnly,
         mode: "sync",
+        prefetchedInstructions: instructionResults.map((result) => result.parsed!).filter(Boolean),
+        prefetchedInstructionCommands: instructionResults.map((result) => result.command).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) {
@@ -661,6 +670,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 {
@@ -677,15 +701,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(
@@ -717,7 +732,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(
@@ -728,6 +770,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 {

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;
@@ -75,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,8 @@ export function buildPlanningPrependContext(params: {
   scaffoldOnly?: boolean;
   mode: "discussion" | "sync";
   nextActionHint?: "plan" | "work";
+  prefetchedInstructions?: OpenSpecInstructionsResponse[];
+  prefetchedInstructionCommands?: string[];
 }): string {
   const project = params.project;
 
@@ -185,16 +188,18 @@ 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 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.",
+        "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.",
       ]
     : [
         "Discussion rules for this turn:",
@@ -232,6 +237,23 @@ 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.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." : "",
     "",
@@ -492,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

@@ -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/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 } = 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,
@@ -156,6 +163,11 @@ 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 ?? "", /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");