spets 0.2.1 → 0.2.2

package/dist/index.js

@@ -273,62 +273,37 @@ async function listPlugins() {
 function getClaudeSkillContent() {
   return `# Spets Executor
 
-You execute spets orchestrator commands. Parse JSON, follow instructions, repeat.
+You execute spets workflow commands. Follow orchestrator instructions exactly.
 
 ## Startup
 
 IF \`$ARGUMENTS\` starts with "resume":
-  1. RUN \`npx spets orchestrate resume\`
+  RUN \`npx spets orchestrate resume\`
+ELSE IF \`$ARGUMENTS\` starts with "list":
+  RUN \`npx spets orchestrate list\`
 ELSE:
-  1. RUN \`npx spets orchestrate init "$ARGUMENTS"\`
-
-Then GOTO **Loop**.
+  RUN \`npx spets orchestrate init "$ARGUMENTS"\`
 
 ## Loop
 
-1. PARSE JSON response
-2. SWITCH on \`type\`:
-
-### type="phase"
-  - EXECUTE what \`prompt\` says
-  - RUN \`onComplete\` with your output as JSON argument
-  - GOTO Loop
-
-### type="checkpoint", checkpoint="clarify"
-  - ASK user each decision in \`decisions[]\` using AskUserQuestion
-  - Format each decision as a question with its options
-  - RUN \`onComplete\` with \`[{decisionId, selectedOptionId}, ...]\`
-  - GOTO Loop
+1. Parse the JSON response
+2. Read the \`instructions\` field
+3. Follow the instructions exactly
+4. Repeat until the response says to stop
 
-### type="checkpoint", checkpoint="approve"
-  - READ \`specPath\`, summarize key points to user
-  - ASK user using AskUserQuestion with options: Approve / Revise / Reject / Stop
-  - RUN matching \`onComplete\` based on user's choice
-  - GOTO Loop
+## Rules
 
-### type="checkpoint", checkpoint="knowledge"
-  - Show \`suggestedKnowledge[]\` to user
-  - ASK user if they want to save, modify, or skip
-  - If save: RUN \`onComplete\` with entries JSON
-  - If skip: RUN \`onSkip\`
-  - GOTO Loop
-
-### type="list"
-  - Show \`tasks[]\` to user with taskId, description, status, currentStep
-  - ASK user which task to resume
-  - RUN \`npx spets orchestrate resume <selectedTaskId>\`
-  - GOTO Loop
-
-### type="complete" or "error"
-  - PRINT message
-  - STOP
+- NEVER skip or modify orchestrator commands
+- NEVER improvise steps \u2014 only do what instructions say
+- Always pass JSON output as a single-quoted string argument
+- Minify JSON when passing as command arguments
 
 ## Forbidden
 
 EnterPlanMode, TaskCreate, TaskUpdate
 
 $ARGUMENTS
-description: Task description for the workflow (or "resume" to continue a previous workflow)
+description: Task description for the workflow (or "resume" to list/continue previous workflows)
 `;
 }
 function getCodexSkillContent() {
@@ -339,65 +314,37 @@ description: SDD workflow executor - orchestrator-controlled spec-driven develop
 
 # Spets Executor
 
-You execute spets orchestrator commands. Parse JSON, follow instructions, repeat.
+You execute spets workflow commands. Follow orchestrator instructions exactly.
 
 ## Startup
 
 IF \`$ARGUMENTS\` starts with "resume":
-  1. RUN \`npx spets orchestrate resume\`
+  RUN \`npx spets orchestrate resume\`
+ELSE IF \`$ARGUMENTS\` starts with "list":
+  RUN \`npx spets orchestrate list\`
 ELSE:
-  1. RUN \`npx spets orchestrate init "$ARGUMENTS"\`
-
-Then GOTO **Loop**.
+  RUN \`npx spets orchestrate init "$ARGUMENTS"\`
 
 ## Loop
 
-1. PARSE JSON response
-2. SWITCH on \`type\`:
+1. Parse the JSON response
+2. Read the \`instructions\` field
+3. Follow the instructions exactly
+4. Repeat until the response says to stop
 
-### type="phase"
-  - EXECUTE what \`prompt\` says
-  - RUN \`onComplete\` with your output as minified JSON argument
-  - GOTO Loop
+## Rules
 
-### type="checkpoint", checkpoint="clarify"
-  - FORMAT decisions as table for user:
-    | # | Decision | Context | Options |
-    |---|----------|---------|---------|
-    | d1 | ... | ... | 1. ... 2. ... |
-  - ASK user to pick an option for each decision
-  - RUN \`onComplete\` with \`[{decisionId, selectedOptionId}, ...]\`
-  - GOTO Loop
-
-### type="checkpoint", checkpoint="approve"
-  - READ \`specPath\`, summarize key points to user
-  - ASK user with options: Approve / Revise / Reject / Stop
-  - RUN matching \`onComplete\` based on user's choice
-  - GOTO Loop
-
-### type="checkpoint", checkpoint="knowledge"
-  - Show \`suggestedKnowledge[]\` to user
-  - ASK user if they want to save, modify, or skip
-  - If save: RUN \`onComplete\` with entries JSON
-  - If skip: RUN \`onSkip\`
-  - GOTO Loop
-
-### type="list"
-  - Show \`tasks[]\` to user with taskId, description, status, currentStep
-  - ASK user which task to resume
-  - RUN \`npx spets orchestrate resume <selectedTaskId>\`
-  - GOTO Loop
-
-### type="complete" or "error"
-  - PRINT message
-  - STOP
+- NEVER skip or modify orchestrator commands
+- NEVER improvise steps \u2014 only do what instructions say
+- Always pass JSON output as a single-quoted string argument
+- Minify JSON when passing as command arguments
 
 ## Forbidden
 
 Planning mode, task tracking tools
 
 $ARGUMENTS
-description: Task description for the workflow (or "resume" to continue a previous workflow)
+description: Task description for the workflow (or "resume" to list/continue previous workflows)
 `;
 }
 function getGeminiSkillContent() {
@@ -408,61 +355,37 @@ description: SDD workflow executor - orchestrator-controlled spec-driven develop
 
 # Spets Executor
 
-You execute spets orchestrator commands. Parse JSON, follow instructions, repeat.
+You execute spets workflow commands. Follow orchestrator instructions exactly.
 
 ## Startup
 
 IF \`$ARGUMENTS\` starts with "resume":
-  1. RUN \`npx spets orchestrate resume\`
+  RUN \`npx spets orchestrate resume\`
+ELSE IF \`$ARGUMENTS\` starts with "list":
+  RUN \`npx spets orchestrate list\`
 ELSE:
-  1. RUN \`npx spets orchestrate init "$ARGUMENTS"\`
-
-Then GOTO **Loop**.
+  RUN \`npx spets orchestrate init "$ARGUMENTS"\`
 
 ## Loop
 
-1. PARSE JSON response
-2. SWITCH on \`type\`:
+1. Parse the JSON response
+2. Read the \`instructions\` field
+3. Follow the instructions exactly
+4. Repeat until the response says to stop
 
-### type="phase"
-  - EXECUTE what \`prompt\` says
-  - RUN \`onComplete\` with your output as JSON argument
-  - GOTO Loop
+## Rules
 
-### type="checkpoint", checkpoint="clarify"
-  - ASK user each decision in \`decisions[]\`
-  - RUN \`onComplete\` with \`[{decisionId, selectedOptionId}, ...]\`
-  - GOTO Loop
-
-### type="checkpoint", checkpoint="approve"
-  - READ \`specPath\`, summarize key points to user
-  - ASK user with options: Approve / Revise / Reject / Stop
-  - RUN matching \`onComplete\` based on user's choice
-  - GOTO Loop
-
-### type="checkpoint", checkpoint="knowledge"
-  - Show \`suggestedKnowledge[]\` to user
-  - ASK user if they want to save, modify, or skip
-  - If save: RUN \`onComplete\` with entries JSON
-  - If skip: RUN \`onSkip\`
-  - GOTO Loop
-
-### type="list"
-  - Show \`tasks[]\` to user with taskId, description, status, currentStep
-  - ASK user which task to resume
-  - RUN \`npx spets orchestrate resume <selectedTaskId>\`
-  - GOTO Loop
-
-### type="complete" or "error"
-  - PRINT message
-  - STOP
+- NEVER skip or modify orchestrator commands
+- NEVER improvise steps \u2014 only do what instructions say
+- Always pass JSON output as a single-quoted string argument
+- Minify JSON when passing as command arguments
 
 ## Forbidden
 
 Planning mode, task tracking tools
 
 $ARGUMENTS
-description: Task description for the workflow (or "resume" to continue a previous workflow)
+description: Task description for the workflow (or "resume" to list/continue previous workflows)
 `;
 }
 
@@ -504,19 +427,26 @@ async function initCommand(options) {
   const hookTemplate = join2(__dirname, "..", "templates", "hooks", "cleanup-branch.sh");
   if (existsSync2(hookTemplate)) {
     const hookDest = join2(spetsDir, "hooks", "cleanup-branch.sh");
-    cpSync(hookTemplate, hookDest);
-    try {
-      execSync(`chmod +x "${hookDest}"`);
-    } catch {
+    if (!existsSync2(hookDest)) {
+      cpSync(hookTemplate, hookDest);
+      try {
+        execSync(`chmod +x "${hookDest}"`);
+      } catch {
+      }
     }
   }
   const knowledgeGuideTemplate = join2(__dirname, "..", "templates", "knowledge", "guide.md");
   if (existsSync2(knowledgeGuideTemplate)) {
     const guideDest = join2(spetsDir, "knowledge", "guide.md");
-    cpSync(knowledgeGuideTemplate, guideDest);
+    if (!existsSync2(guideDest)) {
+      cpSync(knowledgeGuideTemplate, guideDest);
+    }
   }
   const githubInfo = getGitHubInfoFromRemote();
-  writeFileSync2(join2(spetsDir, "config.yml"), getDefaultConfig(githubInfo));
+  const configPath = join2(spetsDir, "config.yml");
+  if (!existsSync2(configPath)) {
+    writeFileSync2(configPath, getDefaultConfig(githubInfo));
+  }
   createDefaultSteps(spetsDir);
   createClaudeCommand(cwd);
   printEnhancedInitOutput(options);
@@ -740,20 +670,23 @@ async function runInteractiveSetup(cwd, spetsDir, options) {
   const hookTemplate = join2(__dirname, "..", "templates", "hooks", "cleanup-branch.sh");
   if (existsSync2(hookTemplate)) {
     const hookDest = join2(spetsDir, "hooks", "cleanup-branch.sh");
-    cpSync(hookTemplate, hookDest);
-    try {
-      execSync(`chmod +x "${hookDest}"`);
-    } catch {
+    if (!existsSync2(hookDest)) {
+      cpSync(hookTemplate, hookDest);
+      try {
+        execSync(`chmod +x "${hookDest}"`);
+      } catch {
+      }
     }
   }
   const knowledgeGuideTemplate = join2(__dirname, "..", "templates", "knowledge", "guide.md");
-  if (existsSync2(knowledgeGuideTemplate)) {
-    cpSync(knowledgeGuideTemplate, join2(spetsDir, "knowledge", "guide.md"));
+  const guideDest = join2(spetsDir, "knowledge", "guide.md");
+  if (existsSync2(knowledgeGuideTemplate) && !existsSync2(guideDest)) {
+    cpSync(knowledgeGuideTemplate, guideDest);
+  }
+  const configPath = join2(spetsDir, "config.yml");
+  if (!existsSync2(configPath)) {
+    writeFileSync2(configPath, getDefaultConfig(githubInfo, { agent, githubEnabled }));
   }
-  writeFileSync2(
-    join2(spetsDir, "config.yml"),
-    getDefaultConfig(githubInfo, { agent, githubEnabled })
-  );
   createDefaultSteps(spetsDir);
   createClaudeCommand(cwd);
   if (githubEnabled && githubInfo) {
@@ -765,10 +698,16 @@ async function runInteractiveSetup(cwd, spetsDir, options) {
 function createDefaultSteps(spetsDir) {
   const planDir = join2(spetsDir, "steps", "01-plan");
   mkdirSync2(planDir, { recursive: true });
-  writeFileSync2(join2(planDir, "template.md"), getPlanTemplate());
+  const planTemplatePath = join2(planDir, "template.md");
+  if (!existsSync2(planTemplatePath)) {
+    writeFileSync2(planTemplatePath, getPlanTemplate());
+  }
   const implementDir = join2(spetsDir, "steps", "02-implement");
   mkdirSync2(implementDir, { recursive: true });
-  writeFileSync2(join2(implementDir, "template.md"), getImplementTemplate());
+  const implementTemplatePath = join2(implementDir, "template.md");
+  if (!existsSync2(implementTemplatePath)) {
+    writeFileSync2(implementTemplatePath, getImplementTemplate());
+  }
 }
 function getPlanTemplate() {
   const fullTemplate = readFileSync(join2(__dirname, "..", "templates", "steps", "01-plan", "template.md"), "utf-8");
@@ -1753,6 +1692,36 @@ function buildKnowledgeExtractPrompt(params) {
   return parts.join("\n");
 }
 
+// src/orchestrator/instructions.ts
+function phaseWithJsonOutput(onComplete) {
+  return `Execute the prompt. Then run:
+  ${onComplete} '<your_json_output>'`;
+}
+function phaseExecute(outputFile, onComplete) {
+  return `Execute the prompt \u2014 write the document to ${outputFile}. Then run:
+  ${onComplete}`;
+}
+function checkpointClarify(onComplete) {
+  return [
+    `Present each decision to the user with its options. Collect their choices. Then run:`,
+    `  ${onComplete} '<answers_json>'`,
+    `Answer format: [{decisionId, selectedOptionId, customInput?}, ...]`
+  ].join("\n");
+}
+function checkpointApprove(specPath, cmds) {
+  return [
+    `Read the document at ${specPath}. Summarize key points to the user. Ask: Approve / Revise / Reject / Stop. Then run the matching command:`,
+    `  approve: ${cmds.approve}`,
+    `  revise: ${cmds.revise}`,
+    `  reject: ${cmds.reject}`,
+    `  stop: ${cmds.stop}`
+  ].join("\n");
+}
+var PRINT_MESSAGE_AND_STOP = "Print the message. Stop.";
+var PRINT_ERROR_AND_STOP = "Print the error. Stop.";
+var LIST_TASKS = "Show tasks to user. Ask which to resume. Run:\n  npx spets orchestrate resume <selectedTaskId>";
+var LIST_EMPTY = "No resumable tasks found. Show this to the user. Stop.";
+
 // src/orchestrator/responses.ts
 function buildPhaseExploreResponse(cwd, state) {
   const steps = getSteps(cwd);
@@ -1774,6 +1743,7 @@ function buildPhaseExploreResponse(cwd, state) {
     previousOutput,
     cwd
   });
+  const onComplete = `npx spets orchestrate explore-done ${state.taskId}`;
   return {
     type: "phase",
     phase: "explore",
@@ -1786,7 +1756,8 @@ function buildPhaseExploreResponse(cwd, state) {
     context: {
       previousOutput
     },
-    onComplete: `npx spets orchestrate explore-done ${state.taskId}`
+    onComplete,
+    instructions: phaseWithJsonOutput(onComplete)
   };
 }
 function buildPhaseClarifyResponse(cwd, state) {
@@ -1801,6 +1772,7 @@ function buildPhaseClarifyResponse(cwd, state) {
     // Legacy support
     cwd
   });
+  const onComplete = `npx spets orchestrate clarify-done ${state.taskId}`;
   return {
     type: "phase",
     phase: "clarify",
@@ -1812,7 +1784,8 @@ function buildPhaseClarifyResponse(cwd, state) {
     previousDecisions: state.decisionHistory,
     previousQA: state.qaHistory,
     // Legacy support
-    onComplete: `npx spets orchestrate clarify-done ${state.taskId}`
+    onComplete,
+    instructions: phaseWithJsonOutput(onComplete)
   };
 }
 function buildPhaseExecuteResponse(cwd, state) {
@@ -1855,6 +1828,8 @@ ${issues}`;
     verifyFeedback,
     cwd
   });
+  const onComplete = `npx spets orchestrate execute-done ${state.taskId}`;
+  const outputFile = join9(outputPath, state.taskId, `${state.currentStep}.md`);
   return {
     type: "phase",
     phase: "execute",
@@ -1869,11 +1844,12 @@ ${issues}`;
     context: {
       template: hasTemplate ? templatePath : void 0,
       previousOutput,
-      output: join9(outputPath, state.taskId, `${state.currentStep}.md`),
+      output: outputFile,
       revisionFeedback: state.revisionFeedback,
       verifyFeedback
     },
-    onComplete: `npx spets orchestrate execute-done ${state.taskId}`
+    onComplete,
+    instructions: phaseExecute(outputFile, onComplete)
   };
 }
 function buildPhaseVerifyResponse(cwd, state) {
@@ -1892,6 +1868,7 @@ function buildPhaseVerifyResponse(cwd, state) {
     loadedKnowledge: state.loadedKnowledge?.map((k) => ({ filename: k.filename, content: k.content })),
     cwd
   });
+  const onComplete = `npx spets orchestrate verify-done ${state.taskId}`;
   return {
     type: "phase",
     phase: "verify",
@@ -1907,7 +1884,8 @@ function buildPhaseVerifyResponse(cwd, state) {
       template: hasTemplate ? templatePath : void 0,
       document: documentPath
     },
-    onComplete: `npx spets orchestrate verify-done ${state.taskId}`
+    onComplete,
+    instructions: phaseWithJsonOutput(onComplete)
   };
 }
 function buildPhaseKnowledgeResponse(cwd, state) {
@@ -1920,6 +1898,7 @@ function buildPhaseKnowledgeResponse(cwd, state) {
     guide,
     cwd
   });
+  const onComplete = `npx spets orchestrate knowledge-extract-done ${state.taskId}`;
   return {
     type: "phase",
     phase: "knowledge",
@@ -1932,21 +1911,31 @@ function buildPhaseKnowledgeResponse(cwd, state) {
       totalSteps: state.totalSteps
     },
     guide,
-    onComplete: `npx spets orchestrate knowledge-extract-done ${state.taskId}`
+    onComplete,
+    instructions: phaseWithJsonOutput(onComplete)
   };
 }
 function buildCheckpointClarifyResponse(state) {
+  const onComplete = `npx spets orchestrate clarified ${state.taskId}`;
   return {
     type: "checkpoint",
     checkpoint: "clarify",
     taskId: state.taskId,
     step: state.currentStep,
     decisions: state.decisions || [],
-    onComplete: `npx spets orchestrate clarified ${state.taskId} '<answers_json>'`
+    onComplete: `${onComplete} '<answers_json>'`,
+    instructions: checkpointClarify(onComplete)
   };
 }
 function buildCheckpointApproveResponse(cwd, state) {
   const outputPath = getOutputPath(cwd);
+  const specPath = join9(outputPath, state.taskId, `${state.currentStep}.md`);
+  const cmds = {
+    approve: `npx spets orchestrate approve ${state.taskId}`,
+    revise: `npx spets orchestrate revise ${state.taskId} '<feedback>'`,
+    reject: `npx spets orchestrate reject ${state.taskId}`,
+    stop: `npx spets orchestrate stop ${state.taskId}`
+  };
   return {
     type: "checkpoint",
     checkpoint: "approve",
@@ -1954,14 +1943,10 @@ function buildCheckpointApproveResponse(cwd, state) {
     step: state.currentStep,
     stepIndex: state.stepIndex,
     totalSteps: state.totalSteps,
-    specPath: join9(outputPath, state.taskId, `${state.currentStep}.md`),
+    specPath,
     options: ["approve", "revise", "reject", "stop"],
-    onComplete: {
-      approve: `npx spets orchestrate approve ${state.taskId}`,
-      revise: `npx spets orchestrate revise ${state.taskId} '<feedback>'`,
-      reject: `npx spets orchestrate reject ${state.taskId}`,
-      stop: `npx spets orchestrate stop ${state.taskId}`
-    }
+    onComplete: cmds,
+    instructions: checkpointApprove(specPath, cmds)
   };
 }
 function buildCompleteResponse(cwd, state, status) {
@@ -1984,11 +1969,12 @@ function buildCompleteResponse(cwd, state, status) {
     status,
     taskId: state.taskId,
     outputs,
-    message: messages[status]
+    message: messages[status],
+    instructions: PRINT_MESSAGE_AND_STOP
   };
 }
 function buildErrorResponse(error, taskId, step) {
-  const response = { type: "error", error };
+  const response = { type: "error", error, instructions: PRINT_ERROR_AND_STOP };
   if (taskId) response.taskId = taskId;
   if (step) response.step = step;
   return response;
@@ -2330,7 +2316,7 @@ var Orchestrator = class {
     const outputPath = getOutputPath(this.cwd);
     const tasks = [];
     if (!existsSync11(outputPath)) {
-      return { type: "list", tasks: [] };
+      return { type: "list", tasks: [], instructions: LIST_EMPTY };
     }
     const dirs = readdirSync2(outputPath, { withFileTypes: true }).filter((d) => d.isDirectory());
     for (const dir of dirs) {
@@ -2352,7 +2338,11 @@ var Orchestrator = class {
       const bTime = b.updatedAt ? new Date(b.updatedAt).getTime() : 0;
       return bTime - aTime;
     });
-    return { type: "list", tasks };
+    return {
+      type: "list",
+      tasks,
+      instructions: tasks.length > 0 ? LIST_TASKS : LIST_EMPTY
+    };
   }
   /**
    * Get current workflow status

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spets",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Spec Driven Development Execution Framework",
   "type": "module",
   "main": "dist/index.js",