spets 0.1.19 → 0.1.20

package/dist/index.js

@@ -2,8 +2,8 @@
 
 // src/index.ts
 import { Command } from "commander";
-import { readFileSync as readFileSync9 } from "fs";
-import { dirname as dirname6, join as join9 } from "path";
+import { readFileSync as readFileSync10 } from "fs";
+import { dirname as dirname5, join as join10 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/commands/init.ts
@@ -589,7 +589,7 @@ function formatDocStatus(status) {
 }
 
 // src/commands/start.ts
-import { execSync as execSync3 } from "child_process";
+import { execSync as execSync2 } from "child_process";
 
 // src/orchestrator/index.ts
 import { readFileSync as readFileSync4, writeFileSync as writeFileSync3, existsSync as existsSync4, mkdirSync as mkdirSync3 } from "fs";
@@ -671,7 +671,56 @@ var Orchestrator = class {
   // ===========================================================================
   // Protocol Response Builders
   // ===========================================================================
-  responseStep(state) {
+  /**
+   * Phase 1: Context gathering
+   */
+  responsePhaseContext(state) {
+    const steps = this.getSteps();
+    const outputPath = this.getOutputPath();
+    let previousOutput;
+    if (state.stepIndex > 1) {
+      const prevStep = steps[state.stepIndex - 2];
+      const prevPath = join4(outputPath, state.taskId, `${prevStep}.md`);
+      if (existsSync4(prevPath)) {
+        previousOutput = prevPath;
+      }
+    }
+    return {
+      type: "phase",
+      phase: "context",
+      step: state.currentStep,
+      stepIndex: state.stepIndex,
+      totalSteps: state.totalSteps,
+      taskId: state.taskId,
+      description: state.description,
+      context: {
+        instruction: this.getStepInstructionPath(state.currentStep),
+        previousOutput
+      },
+      onComplete: `context-done ${state.taskId}`
+    };
+  }
+  /**
+   * Phase 2: Question generation
+   */
+  responsePhaseClarify(state) {
+    return {
+      type: "phase",
+      phase: "clarify",
+      step: state.currentStep,
+      taskId: state.taskId,
+      description: state.description,
+      gatheredContext: state.context || "",
+      context: {
+        instruction: this.getStepInstructionPath(state.currentStep)
+      },
+      onComplete: `clarify-done ${state.taskId}`
+    };
+  }
+  /**
+   * Phase 3: Document generation
+   */
+  responsePhaseGenerate(state) {
     const steps = this.getSteps();
     const outputPath = this.getOutputPath();
     let previousOutput;
@@ -685,12 +734,15 @@ var Orchestrator = class {
     const templatePath = this.getStepTemplatePath(state.currentStep);
     const hasTemplate = existsSync4(templatePath);
     return {
-      type: "step",
+      type: "phase",
+      phase: "generate",
       step: state.currentStep,
       stepIndex: state.stepIndex,
       totalSteps: state.totalSteps,
       taskId: state.taskId,
       description: state.description,
+      gatheredContext: state.context || "",
+      answers: state.answers,
       context: {
         instruction: this.getStepInstructionPath(state.currentStep),
         template: hasTemplate ? templatePath : void 0,
@@ -698,24 +750,25 @@ var Orchestrator = class {
         output: join4(outputPath, state.taskId, `${state.currentStep}.md`),
         revisionFeedback: state.revisionFeedback
       },
-      onComplete: `done ${state.taskId}`
+      onComplete: `generate-done ${state.taskId}`
     };
   }
-  responseCheckpointClarify(state, questions) {
+  /**
+   * Checkpoint: Questions need answers
+   */
+  responseCheckpointClarify(state) {
     return {
       type: "checkpoint",
       checkpoint: "clarify",
       taskId: state.taskId,
       step: state.currentStep,
-      questions: questions.map((q) => ({
-        id: q.id,
-        question: q.question,
-        context: q.context,
-        options: q.options
-      })),
+      questions: state.questions || [],
       onComplete: `clarified ${state.taskId} '<answers_json>'`
     };
   }
+  /**
+   * Checkpoint: Document needs approval
+   */
   responseCheckpointApprove(state) {
     const outputPath = this.getOutputPath();
     return {
@@ -768,7 +821,7 @@ var Orchestrator = class {
   // Command Handlers
   // ===========================================================================
   /**
-   * Initialize a new workflow
+   * Initialize a new workflow - starts at phase_context
    */
   cmdInit(description) {
     try {
@@ -780,62 +833,107 @@ var Orchestrator = class {
         currentStep: steps[0],
         stepIndex: 1,
         totalSteps: steps.length,
-        status: "awaiting_spec",
+        status: "phase_context",
+        phase: "context",
         createdAt: (/* @__PURE__ */ new Date()).toISOString()
       };
       this.saveState(state);
-      return this.responseStep(state);
+      return this.responsePhaseContext(state);
     } catch (e) {
       return this.responseError(e.message);
     }
   }
   /**
-   * Mark current step as done, check for questions or go to approve
+   * Phase 1 complete: Context gathered, move to clarify phase
    */
-  cmdDone(taskId) {
+  cmdContextDone(taskId, context) {
     const state = this.loadState(taskId);
     if (!state) {
       return this.responseError(`No workflow found: ${taskId}`, taskId);
     }
-    const specPath = this.getSpecPath(taskId, state.currentStep);
-    if (!existsSync4(specPath)) {
-      return this.responseError(`Spec not found: ${specPath}`, taskId, state.currentStep);
+    state.context = context;
+    state.status = "phase_clarify";
+    state.phase = "clarify";
+    this.saveState(state);
+    return this.responsePhaseClarify(state);
+  }
+  /**
+   * Phase 2 complete: Questions generated (or none)
+   * If questions exist → checkpoint
+   * If no questions → move to generate phase
+   */
+  cmdClarifyDone(taskId, questions) {
+    const state = this.loadState(taskId);
+    if (!state) {
+      return this.responseError(`No workflow found: ${taskId}`, taskId);
     }
-    const questions = this.checkUnresolvedQuestions(specPath);
     if (questions.length > 0) {
-      state.status = "awaiting_clarify";
+      state.questions = questions;
+      state.status = "clarify_pending";
+      state.phase = "clarify";
       this.saveState(state);
-      return this.responseCheckpointClarify(state, questions);
+      return this.responseCheckpointClarify(state);
     }
-    state.status = "awaiting_approve";
+    state.status = "phase_generate";
+    state.phase = "generate";
     this.saveState(state);
-    return this.responseCheckpointApprove(state);
+    return this.responsePhaseGenerate(state);
   }
   /**
-   * Submit clarification answers
+   * Human answered questions, move to generate phase
    */
   cmdClarified(taskId, answers) {
+    const state = this.loadState(taskId);
+    if (!state) {
+      return this.responseError(`No workflow found: ${taskId}`, taskId);
+    }
+    state.answers = answers;
+    state.status = "phase_generate";
+    state.phase = "generate";
+    this.saveState(state);
+    return this.responsePhaseGenerate(state);
+  }
+  /**
+   * Phase 3 complete: Document generated, move to approve checkpoint
+   */
+  cmdGenerateDone(taskId) {
     const state = this.loadState(taskId);
     if (!state) {
       return this.responseError(`No workflow found: ${taskId}`, taskId);
     }
     const specPath = this.getSpecPath(taskId, state.currentStep);
-    if (existsSync4(specPath)) {
-      const content = readFileSync4(specPath, "utf-8");
-      const { content: body, data } = matter2(content);
-      if (data.open_questions && Array.isArray(data.open_questions)) {
-        data.open_questions = data.open_questions.map((q, i) => ({
-          ...q,
-          resolved: true,
-          answer: answers.find((a) => a.questionId === `q${i + 1}`)?.answer
-        }));
-      }
-      writeFileSync3(specPath, matter2.stringify(body, data));
+    if (!existsSync4(specPath)) {
+      return this.responseError(`Document not found: ${specPath}`, taskId, state.currentStep);
+    }
+    state.status = "approve_pending";
+    state.phase = "review";
+    this.saveState(state);
+    return this.responseCheckpointApprove(state);
+  }
+  /**
+   * @deprecated Use cmdContextDone, cmdClarifyDone, cmdGenerateDone instead
+   */
+  cmdDone(taskId) {
+    const state = this.loadState(taskId);
+    if (!state) {
+      return this.responseError(`No workflow found: ${taskId}`, taskId);
+    }
+    const specPath = this.getSpecPath(taskId, state.currentStep);
+    if (!existsSync4(specPath)) {
+      return this.responseError(`Spec not found: ${specPath}`, taskId, state.currentStep);
+    }
+    const questions = this.checkUnresolvedQuestions(specPath);
+    if (questions.length > 0) {
+      state.questions = questions;
+      state.status = "clarify_pending";
+      state.phase = "clarify";
+      this.saveState(state);
+      return this.responseCheckpointClarify(state);
     }
-    state.status = "awaiting_spec";
-    state.revisionFeedback = `Answers provided: ${JSON.stringify(answers)}`;
+    state.status = "approve_pending";
+    state.phase = "review";
     this.saveState(state);
-    return this.responseStep(state);
+    return this.responseCheckpointApprove(state);
   }
   /**
    * Approve current step and move to next
@@ -857,10 +955,14 @@ var Orchestrator = class {
     if (state.stepIndex < state.totalSteps) {
       state.currentStep = steps[state.stepIndex];
       state.stepIndex += 1;
-      state.status = "awaiting_spec";
+      state.status = "phase_context";
+      state.phase = "context";
+      state.context = void 0;
+      state.questions = void 0;
+      state.answers = void 0;
       state.revisionFeedback = void 0;
       this.saveState(state);
-      return this.responseStep(state);
+      return this.responsePhaseContext(state);
     } else {
       state.status = "completed";
       this.saveState(state);
@@ -868,17 +970,18 @@ var Orchestrator = class {
     }
   }
   /**
-   * Request revision with feedback
+   * Request revision with feedback - goes back to generate phase
    */
   cmdRevise(taskId, feedback) {
     const state = this.loadState(taskId);
     if (!state) {
       return this.responseError(`No workflow found: ${taskId}`, taskId);
     }
-    state.status = "awaiting_spec";
+    state.status = "phase_generate";
+    state.phase = "generate";
     state.revisionFeedback = feedback;
     this.saveState(state);
-    return this.responseStep(state);
+    return this.responsePhaseGenerate(state);
   }
   /**
    * Reject and stop workflow
@@ -921,13 +1024,15 @@ var Orchestrator = class {
       return this.responseError(`No workflow found: ${taskId}`, taskId);
     }
     switch (state.status) {
-      case "awaiting_spec":
-        return this.responseStep(state);
-      case "awaiting_clarify": {
-        const questions = this.checkUnresolvedQuestions(this.getSpecPath(taskId, state.currentStep));
-        return this.responseCheckpointClarify(state, questions);
-      }
-      case "awaiting_approve":
+      case "phase_context":
+        return this.responsePhaseContext(state);
+      case "phase_clarify":
+        return this.responsePhaseClarify(state);
+      case "clarify_pending":
+        return this.responseCheckpointClarify(state);
+      case "phase_generate":
+        return this.responsePhaseGenerate(state);
+      case "approve_pending":
         return this.responseCheckpointApprove(state);
       case "completed":
       case "stopped":
@@ -940,9 +1045,233 @@ var Orchestrator = class {
 };
 
 // src/core/step-executor.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5, writeFileSync as writeFileSync4 } from "fs";
-import { join as join5 } from "path";
+import { existsSync as existsSync6, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
 import matter3 from "gray-matter";
+
+// src/core/prompt-builder.ts
+import { readFileSync as readFileSync5, existsSync as existsSync5 } from "fs";
+import { join as join5 } from "path";
+function buildContextPrompt(params) {
+  const cwd = params.cwd || process.cwd();
+  const stepsDir = getStepsDir(cwd);
+  const isFirstStep = params.stepIndex === 1;
+  const instructionPath = join5(stepsDir, params.step, "instruction.md");
+  const instruction = existsSync5(instructionPath) ? readFileSync5(instructionPath, "utf-8") : "";
+  const parts = [];
+  parts.push("# Context Gathering Phase");
+  parts.push("");
+  parts.push("Your task is to gather context before generating a document.");
+  parts.push("Do NOT generate the document yet - only gather information.");
+  parts.push("");
+  parts.push("## Task Information");
+  parts.push("");
+  parts.push(`- **Task ID**: ${params.taskId}`);
+  parts.push(`- **Current Step**: ${params.step} (${params.stepIndex}/${params.totalSteps})`);
+  parts.push("");
+  if (isFirstStep) {
+    parts.push("## User Request");
+    parts.push("");
+    parts.push(`> ${params.description}`);
+    parts.push("");
+  } else if (params.previousOutput) {
+    parts.push("## Previous Step Output");
+    parts.push("");
+    if (existsSync5(params.previousOutput)) {
+      parts.push(readFileSync5(params.previousOutput, "utf-8"));
+    }
+    parts.push("");
+  }
+  if (instruction) {
+    parts.push("## Step Instruction (Preview)");
+    parts.push("");
+    parts.push("The next phase will use this instruction to generate a document:");
+    parts.push("");
+    parts.push("```");
+    parts.push(instruction.slice(0, 500) + (instruction.length > 500 ? "..." : ""));
+    parts.push("```");
+    parts.push("");
+  }
+  parts.push("## Your Task");
+  parts.push("");
+  parts.push("1. **Analyze** the request/input to understand what is being asked");
+  parts.push("2. **Search** the codebase for relevant files, patterns, conventions");
+  parts.push("3. **Identify** key constraints, dependencies, and considerations");
+  parts.push("");
+  parts.push("## Output Format");
+  parts.push("");
+  parts.push("Output a JSON object with this structure:");
+  parts.push("");
+  parts.push("```json");
+  parts.push("{");
+  parts.push('  "summary": "Brief summary of what you understood and found",');
+  parts.push('  "relevantFiles": ["path/to/file1.ts", "path/to/file2.ts"],');
+  parts.push('  "keyFindings": [');
+  parts.push('    "Finding 1: description",');
+  parts.push('    "Finding 2: description"');
+  parts.push("  ]");
+  parts.push("}");
+  parts.push("```");
+  parts.push("");
+  parts.push("**Important:** Output ONLY the JSON, no other text.");
+  parts.push("");
+  return parts.join("\n");
+}
+function buildClarifyPrompt(params) {
+  const cwd = params.cwd || process.cwd();
+  const stepsDir = getStepsDir(cwd);
+  const instructionPath = join5(stepsDir, params.step, "instruction.md");
+  const instruction = existsSync5(instructionPath) ? readFileSync5(instructionPath, "utf-8") : "";
+  const parts = [];
+  parts.push("# Clarify Phase");
+  parts.push("");
+  parts.push("Your task is to identify any questions that need user input before generating the document.");
+  parts.push("Do NOT generate the document yet - only generate questions if needed.");
+  parts.push("");
+  parts.push("## Task Information");
+  parts.push("");
+  parts.push(`- **Task ID**: ${params.taskId}`);
+  parts.push(`- **Current Step**: ${params.step}`);
+  parts.push(`- **Description**: ${params.description}`);
+  parts.push("");
+  parts.push("## Gathered Context");
+  parts.push("");
+  parts.push(params.gatheredContext);
+  parts.push("");
+  if (instruction) {
+    parts.push("## Step Instruction");
+    parts.push("");
+    parts.push(instruction);
+    parts.push("");
+  }
+  parts.push("## Consider These Questions");
+  parts.push("");
+  parts.push("1. Is the task description clear enough to proceed?");
+  parts.push("2. Are there multiple valid approaches that need user decision?");
+  parts.push("3. Are there ambiguities that could lead to wrong implementation?");
+  parts.push("4. Are there missing requirements or constraints?");
+  parts.push("");
+  parts.push("## Output Format");
+  parts.push("");
+  parts.push("Output a JSON object with questions array:");
+  parts.push("");
+  parts.push("```json");
+  parts.push("{");
+  parts.push('  "questions": [');
+  parts.push("    {");
+  parts.push('      "id": "q1",');
+  parts.push('      "question": "Your specific question?",');
+  parts.push('      "context": "Why this matters for the document",');
+  parts.push('      "options": ["Option A", "Option B"]  // optional');
+  parts.push("    }");
+  parts.push("  ]");
+  parts.push("}");
+  parts.push("```");
+  parts.push("");
+  parts.push('If no questions are needed, return: `{"questions": []}`');
+  parts.push("");
+  parts.push("**Important:** Output ONLY the JSON, no other text.");
+  parts.push("");
+  return parts.join("\n");
+}
+function buildGeneratePrompt(params) {
+  const cwd = params.cwd || process.cwd();
+  const config = loadConfig(cwd);
+  const stepsDir = getStepsDir(cwd);
+  const outputsDir = getOutputsDir(cwd);
+  const isFirstStep = params.stepIndex === 1;
+  const prevStep = params.stepIndex > 1 ? config.steps[params.stepIndex - 2] : null;
+  const instructionPath = join5(stepsDir, params.step, "instruction.md");
+  const templatePath = join5(stepsDir, params.step, "template.md");
+  const outputPath = join5(outputsDir, params.taskId, `${params.step}.md`);
+  if (!existsSync5(instructionPath)) {
+    throw new Error(`Instruction not found: ${instructionPath}`);
+  }
+  const instruction = readFileSync5(instructionPath, "utf-8");
+  const template = existsSync5(templatePath) ? readFileSync5(templatePath, "utf-8") : null;
+  let previousSpec = null;
+  if (prevStep) {
+    const prevPath = join5(outputsDir, params.taskId, `${prevStep}.md`);
+    if (existsSync5(prevPath)) {
+      previousSpec = {
+        step: prevStep,
+        content: readFileSync5(prevPath, "utf-8")
+      };
+    }
+  }
+  const parts = [];
+  parts.push("# Document Generation Phase");
+  parts.push("");
+  parts.push("Generate the document based on the gathered context and user answers.");
+  parts.push("");
+  parts.push("## Step Instruction");
+  parts.push("");
+  parts.push(instruction);
+  parts.push("");
+  if (template) {
+    parts.push("## Document Template");
+    parts.push("");
+    parts.push("**CRITICAL: You MUST follow this template structure completely.**");
+    parts.push("");
+    parts.push(template);
+    parts.push("");
+  }
+  parts.push("## Gathered Context");
+  parts.push("");
+  parts.push(params.gatheredContext);
+  parts.push("");
+  if (params.answers && params.answers.length > 0) {
+    parts.push("## User Answers");
+    parts.push("");
+    for (const answer of params.answers) {
+      parts.push(`- **${answer.questionId}**: ${answer.answer}`);
+    }
+    parts.push("");
+  }
+  if (isFirstStep) {
+    parts.push("## User Request");
+    parts.push("");
+    parts.push(`> ${params.description}`);
+    parts.push("");
+  } else if (previousSpec) {
+    parts.push(`## Input: ${previousSpec.step}.md`);
+    parts.push("");
+    parts.push(previousSpec.content);
+    parts.push("");
+  }
+  parts.push("## Task Context");
+  parts.push("");
+  parts.push(`- **Task ID**: ${params.taskId}`);
+  parts.push(`- **Current Step**: ${params.step} (${params.stepIndex}/${params.totalSteps})`);
+  parts.push("");
+  if (params.revisionFeedback) {
+    parts.push("## Revision Feedback");
+    parts.push("");
+    parts.push("Previous version was not approved. Please revise based on this feedback:");
+    parts.push("");
+    parts.push(`> ${params.revisionFeedback}`);
+    parts.push("");
+  }
+  parts.push("## Output Instructions");
+  parts.push("");
+  parts.push(`Generate the document and save to: \`${outputPath}\``);
+  parts.push("");
+  parts.push("**Required frontmatter:**");
+  parts.push("```yaml");
+  parts.push("---");
+  parts.push(`id: ${params.taskId}`);
+  parts.push(`step: ${params.step}`);
+  parts.push("status: pending_approval");
+  parts.push("---");
+  parts.push("```");
+  parts.push("");
+  return {
+    prompt: parts.join("\n"),
+    outputPath
+  };
+}
+
+// src/core/step-executor.ts
+import { join as join6 } from "path";
 var StepExecutor = class {
   adapter;
   config;
@@ -952,132 +1281,237 @@ var StepExecutor = class {
     this.config = config;
     this.cwd = cwd;
   }
+  // ==========================================================================
+  // Phase 1: Context Gathering
+  // ==========================================================================
+  /**
+   * Execute context phase - AI gathers context
+   * Returns gathered context as string
+   */
+  async executeContextPhase(step, context) {
+    this.adapter.io.notify(`Phase 1/4: Gathering context for ${step}`, "info");
+    const params = {
+      taskId: context.taskId,
+      step,
+      description: context.description,
+      stepIndex: context.stepIndex,
+      totalSteps: context.totalSteps,
+      previousOutput: context.previousOutput,
+      cwd: this.cwd
+    };
+    const prompt = buildContextPrompt(params);
+    const response = await this.adapter.ai.execute({
+      prompt,
+      outputPath: ""
+      // No file output needed
+    });
+    const contextOutput = this.parseContextOutput(response || "");
+    return {
+      phase: "context",
+      context: JSON.stringify(contextOutput)
+    };
+  }
+  // ==========================================================================
+  // Phase 2: Clarify (Question Generation)
+  // ==========================================================================
+  /**
+   * Execute clarify phase - AI generates questions
+   * Returns questions (may be empty)
+   */
+  async executeClarifyPhase(step, context) {
+    this.adapter.io.notify(`Phase 2/4: Generating questions for ${step}`, "info");
+    if (!context.gatheredContext) {
+      throw new Error("Context phase must be completed before clarify phase");
+    }
+    const params = {
+      taskId: context.taskId,
+      step,
+      description: context.description,
+      gatheredContext: context.gatheredContext,
+      cwd: this.cwd
+    };
+    const prompt = buildClarifyPrompt(params);
+    const response = await this.adapter.ai.execute({
+      prompt,
+      outputPath: ""
+      // No file output needed
+    });
+    const clarifyOutput = this.parseClarifyOutput(response || "");
+    if (clarifyOutput.questions.length > 0) {
+      this.adapter.io.notify(`${clarifyOutput.questions.length} question(s) need answers`, "warning");
+    } else {
+      this.adapter.io.notify("No questions needed, proceeding to generate", "info");
+    }
+    return {
+      phase: "clarify",
+      questions: clarifyOutput.questions
+    };
+  }
+  /**
+   * Ask questions to human
+   * Returns answers (or pending if async mode)
+   */
+  async askQuestions(questions) {
+    const answers = await this.adapter.io.askMultiple(questions);
+    if (answers.length === 0) {
+      return { phase: "clarify", questions, pending: true };
+    }
+    return { phase: "clarify", questions: [] };
+  }
+  // ==========================================================================
+  // Phase 3: Generate Document
+  // ==========================================================================
+  /**
+   * Execute generate phase - AI creates document
+   */
+  async executeGeneratePhase(step, context) {
+    this.adapter.io.notify(`Phase 3/4: Generating document for ${step}`, "info");
+    if (!context.gatheredContext) {
+      throw new Error("Context phase must be completed before generate phase");
+    }
+    const params = {
+      taskId: context.taskId,
+      step,
+      description: context.description,
+      stepIndex: context.stepIndex,
+      totalSteps: context.totalSteps,
+      gatheredContext: context.gatheredContext,
+      answers: context.answers,
+      revisionFeedback: context.revisionFeedback,
+      cwd: this.cwd
+    };
+    const { prompt, outputPath } = buildGeneratePrompt(params);
+    await this.adapter.ai.execute({ prompt, outputPath });
+    if (!existsSync6(outputPath)) {
+      throw new Error(`AI did not create document at ${outputPath}`);
+    }
+    this.adapter.io.notify(`Document created: ${outputPath}`, "success");
+    return { phase: "generate" };
+  }
+  // ==========================================================================
+  // Phase 4: Review (Approval)
+  // ==========================================================================
+  /**
+   * Execute review phase - human approves/revises/rejects
+   */
+  async executeReviewPhase(step, context) {
+    this.adapter.io.notify(`Phase 4/4: Review for ${step}`, "info");
+    const outputsDir = getOutputsDir(this.cwd);
+    const outputPath = join6(outputsDir, context.taskId, `${step}.md`);
+    if (!existsSync6(outputPath)) {
+      throw new Error(`Document not found: ${outputPath}`);
+    }
+    const approval = await this.adapter.io.approve(
+      outputPath,
+      step,
+      context.stepIndex,
+      context.totalSteps
+    );
+    if (approval.pending) {
+      return { phase: "review", pending: true };
+    }
+    if (approval.action === "approve") {
+      this.updateDocumentStatus(outputPath, "approved");
+      this.adapter.io.notify(`Step ${step} approved`, "success");
+      return { phase: "review", approved: true };
+    }
+    if (approval.action === "stop") {
+      this.adapter.io.notify(`Workflow stopped at step ${step}`, "info");
+      return { phase: "review", stopped: true };
+    }
+    if (approval.action === "reject") {
+      this.updateDocumentStatus(outputPath, "rejected");
+      this.adapter.io.notify(`Step ${step} rejected`, "error");
+      return { phase: "review", rejected: true };
+    }
+    this.adapter.io.notify(`Revision requested for step ${step}`, "info");
+    return {
+      phase: "review",
+      revisionFeedback: approval.feedback || "Please revise the document"
+    };
+  }
+  // ==========================================================================
+  // Full Step Execution (convenience method)
+  // ==========================================================================
   /**
-   * Execute a single step
+   * Execute all phases of a step
+   * For synchronous environments (CLI) - runs through all phases
+   * For async environments (GitHub) - may return pending
    *
-   * Flow:
-   * 1. Generate document (AI)
-   * 2. Check for open_questions in frontmatter
-   * 3. If questions exist, ask user and regenerate
-   * 4. Request approval
-   * 5. Return result
+   * @deprecated Use individual phase methods for 4-phase control
    */
   async execute(step, context) {
-    const stepsDir = getStepsDir(this.cwd);
-    const outputsDir = getOutputsDir(this.cwd);
-    const instructionPath = join5(stepsDir, step, "instruction.md");
-    const templatePath = join5(stepsDir, step, "template.md");
-    const outputPath = join5(outputsDir, context.taskId, `${step}.md`);
-    let previousOutputPath;
-    if (context.stepIndex > 1) {
-      const steps = this.config.steps;
-      const prevStep = steps[context.stepIndex - 2];
-      const prevPath = join5(outputsDir, context.taskId, `${prevStep}.md`);
-      if (existsSync5(prevPath)) {
-        previousOutputPath = prevPath;
-      }
-    }
-    this.adapter.io.notify(`Starting step: ${step}`, "info");
     let attempts = 0;
     const maxAttempts = 10;
-    let revisionFeedback = context.revisionFeedback;
+    let currentContext = { ...context };
     while (attempts < maxAttempts) {
       attempts++;
-      const converseParams = {
-        instructionPath,
-        templatePath: existsSync5(templatePath) ? templatePath : void 0,
-        previousOutputPath,
-        outputPath,
-        taskId: context.taskId,
-        description: context.description,
-        revisionFeedback
-      };
-      await this.adapter.ai.converse(converseParams);
-      if (!existsSync5(outputPath)) {
-        throw new Error(`AI did not create document at ${outputPath}`);
-      }
-      const questions = this.getUnresolvedQuestions(outputPath);
-      if (questions.length > 0) {
-        this.adapter.io.notify(`${questions.length} question(s) need answers`, "warning");
-        const answers = await this.adapter.io.askMultiple(questions);
-        this.resolveQuestions(outputPath, answers);
-        revisionFeedback = `User answered questions:
-${answers.map((a) => `- ${a.questionId}: ${a.answer}`).join("\n")}
-
-Regenerate the document incorporating these answers.`;
-        this.adapter.io.notify("Regenerating with answers...", "info");
-        continue;
+      if (!currentContext.gatheredContext) {
+        const contextResult = await this.executeContextPhase(step, currentContext);
+        currentContext.gatheredContext = contextResult.context;
       }
-      const approval = await this.adapter.io.approve(
-        outputPath,
-        step,
-        context.stepIndex,
-        context.totalSteps
-      );
-      if (approval.action === "approve") {
-        this.updateDocumentStatus(outputPath, "approved");
-        this.adapter.io.notify(`Step ${step} approved`, "success");
-        return { approved: true, rejected: false, stopped: false };
+      const clarifyResult = await this.executeClarifyPhase(step, currentContext);
+      if (clarifyResult.questions && clarifyResult.questions.length > 0) {
+        const answers = await this.adapter.io.askMultiple(clarifyResult.questions);
+        if (answers.length === 0) {
+          return { phase: "clarify", questions: clarifyResult.questions, pending: true };
+        }
+        currentContext.answers = answers;
       }
-      if (approval.action === "stop") {
-        this.adapter.io.notify(`Workflow stopped at step ${step}`, "info");
-        return { approved: false, rejected: false, stopped: true };
+      await this.executeGeneratePhase(step, currentContext);
+      const reviewResult = await this.executeReviewPhase(step, currentContext);
+      if (reviewResult.pending) {
+        return reviewResult;
       }
-      if (approval.action === "reject") {
-        this.updateDocumentStatus(outputPath, "rejected");
-        this.adapter.io.notify(`Step ${step} rejected`, "error");
-        return { approved: false, rejected: true, stopped: false };
+      if (reviewResult.approved || reviewResult.rejected || reviewResult.stopped) {
+        return reviewResult;
       }
-      revisionFeedback = approval.feedback || "Please revise the document";
+      currentContext.revisionFeedback = reviewResult.revisionFeedback;
       this.adapter.io.notify(`Revising step ${step}...`, "info");
     }
     throw new Error(`Maximum revision attempts (${maxAttempts}) exceeded for step ${step}`);
   }
+  // ==========================================================================
+  // Helpers
+  // ==========================================================================
   /**
-   * Get unresolved questions from document frontmatter
+   * Parse context phase output (JSON)
    */
-  getUnresolvedQuestions(docPath) {
-    const content = readFileSync5(docPath, "utf-8");
-    const { data } = matter3(content);
-    const questions = [];
-    if (data.open_questions && Array.isArray(data.open_questions)) {
-      for (let i = 0; i < data.open_questions.length; i++) {
-        const q = data.open_questions[i];
-        if (!q.resolved) {
-          questions.push({
-            id: `q${i + 1}`,
-            question: q.question,
-            context: q.context,
-            options: q.options
-          });
-        }
+  parseContextOutput(response) {
+    try {
+      const jsonMatch = response.match(/\{[\s\S]*\}/);
+      if (jsonMatch) {
+        return JSON.parse(jsonMatch[0]);
       }
+    } catch {
     }
-    return questions;
+    return {
+      summary: response,
+      relevantFiles: [],
+      keyFindings: []
+    };
   }
   /**
-   * Mark questions as resolved and add answers to frontmatter
+   * Parse clarify phase output (JSON)
    */
-  resolveQuestions(docPath, answers) {
-    const content = readFileSync5(docPath, "utf-8");
-    const { content: body, data } = matter3(content);
-    if (data.open_questions && Array.isArray(data.open_questions)) {
-      data.open_questions = data.open_questions.map((q, i) => {
-        const answer = answers.find((a) => a.questionId === `q${i + 1}`);
-        return {
-          ...q,
-          resolved: true,
-          answer: answer?.answer
-        };
-      });
+  parseClarifyOutput(response) {
+    try {
+      const jsonMatch = response.match(/\{[\s\S]*\}/);
+      if (jsonMatch) {
+        const parsed = JSON.parse(jsonMatch[0]);
+        if (Array.isArray(parsed.questions)) {
+          return parsed;
+        }
+      }
+    } catch {
     }
-    writeFileSync4(docPath, matter3.stringify(body, data));
+    return { questions: [] };
   }
   /**
    * Update document status in frontmatter
    */
   updateDocumentStatus(docPath, status) {
-    const content = readFileSync5(docPath, "utf-8");
+    const content = readFileSync6(docPath, "utf-8");
     const { content: body, data } = matter3(content);
     data.status = status;
     data.updated_at = (/* @__PURE__ */ new Date()).toISOString();
@@ -1087,69 +1521,26 @@ Regenerate the document incorporating these answers.`;
 
 // src/adapters/cli.ts
 import { spawn, spawnSync } from "child_process";
-import { readFileSync as readFileSync6, writeFileSync as writeFileSync5, existsSync as existsSync6, mkdirSync as mkdirSync4 } from "fs";
-import { dirname as dirname4 } from "path";
+import { readFileSync as readFileSync7, writeFileSync as writeFileSync5, existsSync as existsSync7, mkdirSync as mkdirSync4 } from "fs";
+import { dirname as dirname3 } from "path";
 import { input, select, confirm } from "@inquirer/prompts";
 var CLIAIAdapter = class {
   claudeCommand;
   constructor(claudeCommand = "claude") {
     this.claudeCommand = claudeCommand;
   }
-  async converse(params) {
-    const prompt = this.buildPrompt(params);
+  async execute(params) {
     console.log(`
-\u{1F4DD} Generating document for step...`);
-    const response = await this.callClaude(prompt);
-    const outputDir = dirname4(params.outputPath);
-    if (!existsSync6(outputDir)) {
-      mkdirSync4(outputDir, { recursive: true });
-    }
-    writeFileSync5(params.outputPath, response);
-  }
-  buildPrompt(params) {
-    const parts = [];
-    const instruction = readFileSync6(params.instructionPath, "utf-8");
-    parts.push("# Task");
-    parts.push(`You are generating a document as part of a spec-driven development workflow.`);
-    parts.push("");
-    parts.push("## Task Description");
-    parts.push(params.description);
-    parts.push("");
-    parts.push("## Instructions");
-    parts.push(instruction);
-    parts.push("");
-    if (params.templatePath && existsSync6(params.templatePath)) {
-      const template = readFileSync6(params.templatePath, "utf-8");
-      parts.push("## Output Template");
-      parts.push("Follow this template structure:");
-      parts.push(template);
-      parts.push("");
-    }
-    if (params.previousOutputPath && existsSync6(params.previousOutputPath)) {
-      const previousOutput = readFileSync6(params.previousOutputPath, "utf-8");
-      parts.push("## Previous Step Output");
-      parts.push(previousOutput);
-      parts.push("");
-    }
-    if (params.revisionFeedback) {
-      parts.push("## Revision Feedback");
-      parts.push(params.revisionFeedback);
-      parts.push("");
-    }
-    parts.push("## Output Format");
-    parts.push("Generate the document content directly.");
-    parts.push("If you have clarifying questions that MUST be answered, include them in the frontmatter as:");
-    parts.push("```yaml");
-    parts.push("---");
-    parts.push("status: draft");
-    parts.push("open_questions:");
-    parts.push('  - question: "Your question here"');
-    parts.push("    resolved: false");
-    parts.push("---");
-    parts.push("```");
-    parts.push("");
-    parts.push("Only ask questions if absolutely necessary.");
-    return parts.join("\n");
+\u{1F4DD} Generating...`);
+    const response = await this.callClaude(params.prompt);
+    if (params.outputPath) {
+      const outputDir = dirname3(params.outputPath);
+      if (!existsSync7(outputDir)) {
+        mkdirSync4(outputDir, { recursive: true });
+      }
+      writeFileSync5(params.outputPath, response);
+    }
+    return response;
   }
   async callClaude(prompt) {
     return new Promise((resolve, reject) => {
@@ -1216,8 +1607,8 @@ Context: ${question.context}`);
     return answers;
   }
   async approve(specPath, stepName, stepIndex, totalSteps) {
-    if (existsSync6(specPath)) {
-      const doc = readFileSync6(specPath, "utf-8");
+    if (existsSync7(specPath)) {
+      const doc = readFileSync7(specPath, "utf-8");
       console.log("\n" + "=".repeat(60));
       console.log(`\u{1F4C4} ${stepName} Document (Step ${stepIndex}/${totalSteps})`);
       console.log("=".repeat(60));
@@ -1262,17 +1653,17 @@ Context: ${question.context}`);
 };
 var CLISystemAdapter = class {
   readFile(path) {
-    return readFileSync6(path, "utf-8");
+    return readFileSync7(path, "utf-8");
   }
   writeFile(path, content) {
-    const dir = dirname4(path);
-    if (!existsSync6(dir)) {
+    const dir = dirname3(path);
+    if (!existsSync7(dir)) {
       mkdirSync4(dir, { recursive: true });
     }
     writeFileSync5(path, content);
   }
   fileExists(path) {
-    return existsSync6(path);
+    return existsSync7(path);
   }
   exec(command) {
     try {
@@ -1303,76 +1694,25 @@ function createCLIAdapter(claudeCommand = "claude") {
 
 // src/adapters/github.ts
 import { spawn as spawn2, spawnSync as spawnSync2 } from "child_process";
-import { readFileSync as readFileSync7, writeFileSync as writeFileSync6, existsSync as existsSync7, mkdirSync as mkdirSync5 } from "fs";
-import { dirname as dirname5 } from "path";
-var PauseForInputError = class extends Error {
-  constructor(inputType, data) {
-    super(`Paused waiting for ${inputType}`);
-    this.inputType = inputType;
-    this.data = data;
-    this.name = "PauseForInputError";
-  }
-};
+import { readFileSync as readFileSync8, writeFileSync as writeFileSync6, existsSync as existsSync8, mkdirSync as mkdirSync5 } from "fs";
+import { dirname as dirname4 } from "path";
 var GitHubAIAdapter = class {
   claudeCommand;
   constructor(claudeCommand = "claude") {
     this.claudeCommand = claudeCommand;
   }
-  async converse(params) {
-    const prompt = this.buildPrompt(params);
+  async execute(params) {
     console.log(`
-\u{1F4DD} Generating document for step...`);
-    const response = await this.callClaude(prompt);
-    const outputDir = dirname5(params.outputPath);
-    if (!existsSync7(outputDir)) {
-      mkdirSync5(outputDir, { recursive: true });
-    }
-    writeFileSync6(params.outputPath, response);
-  }
-  buildPrompt(params) {
-    const parts = [];
-    const instruction = readFileSync7(params.instructionPath, "utf-8");
-    parts.push("# Task");
-    parts.push(`You are generating a document as part of a spec-driven development workflow.`);
-    parts.push("");
-    parts.push("## Task Description");
-    parts.push(params.description);
-    parts.push("");
-    parts.push("## Instructions");
-    parts.push(instruction);
-    parts.push("");
-    if (params.templatePath && existsSync7(params.templatePath)) {
-      const template = readFileSync7(params.templatePath, "utf-8");
-      parts.push("## Output Template");
-      parts.push("Follow this template structure:");
-      parts.push(template);
-      parts.push("");
-    }
-    if (params.previousOutputPath && existsSync7(params.previousOutputPath)) {
-      const previousOutput = readFileSync7(params.previousOutputPath, "utf-8");
-      parts.push("## Previous Step Output");
-      parts.push(previousOutput);
-      parts.push("");
-    }
-    if (params.revisionFeedback) {
-      parts.push("## Revision Feedback");
-      parts.push(params.revisionFeedback);
-      parts.push("");
-    }
-    parts.push("## Output Format");
-    parts.push("Generate the document content directly.");
-    parts.push("If you have clarifying questions that MUST be answered, include them in the frontmatter as:");
-    parts.push("```yaml");
-    parts.push("---");
-    parts.push("status: draft");
-    parts.push("open_questions:");
-    parts.push('  - question: "Your question here"');
-    parts.push("    resolved: false");
-    parts.push("---");
-    parts.push("```");
-    parts.push("");
-    parts.push("Only ask questions if absolutely necessary.");
-    return parts.join("\n");
+\u{1F4DD} Generating...`);
+    const response = await this.callClaude(params.prompt);
+    if (params.outputPath) {
+      const outputDir = dirname4(params.outputPath);
+      if (!existsSync8(outputDir)) {
+        mkdirSync5(outputDir, { recursive: true });
+      }
+      writeFileSync6(params.outputPath, response);
+    }
+    return response;
   }
   async callClaude(prompt) {
     return new Promise((resolve, reject) => {
@@ -1417,22 +1757,38 @@ var GitHubIOAdapter = class {
     this.taskId = taskId;
   }
   async ask(question) {
-    throw new PauseForInputError("questions", [question]);
+    console.log(`\u{1F4DD} Question queued: ${question.question}`);
+    return "";
   }
   async askMultiple(questions) {
     const comment = this.formatQuestionsComment(questions);
     await this.postComment(comment);
-    console.log("\n\u23F8\uFE0F  Waiting for answers on GitHub...");
-    throw new PauseForInputError("questions", questions);
+    console.log("\n\u23F8\uFE0F  Questions posted to GitHub. Waiting for answers...");
+    console.log("   Answer with /answer command on the Issue/PR.");
+    this.pendingQuestions = questions;
+    return [];
   }
   async approve(specPath, stepName, stepIndex, totalSteps) {
-    const doc = existsSync7(specPath) ? readFileSync7(specPath, "utf-8") : "";
+    const doc = existsSync8(specPath) ? readFileSync8(specPath, "utf-8") : "";
     const comment = this.formatApprovalComment(doc, stepName, stepIndex, totalSteps, specPath);
     await this.postComment(comment);
-    console.log("\n\u23F8\uFE0F  Waiting for approval on GitHub...");
+    console.log("\n\u23F8\uFE0F  Approval request posted to GitHub.");
     console.log("   Comment /approve, /revise <feedback>, or /reject on the Issue/PR.");
-    return { action: "stop" };
+    return { action: "stop", pending: true };
   }
+  /**
+   * Check if there are pending questions awaiting external input
+   */
+  hasPendingQuestions() {
+    return this.pendingQuestions.length > 0;
+  }
+  /**
+   * Get pending questions for serialization
+   */
+  getPendingQuestions() {
+    return this.pendingQuestions;
+  }
+  pendingQuestions = [];
   notify(message, type) {
     const icons = {
       info: "\u2139\uFE0F",
@@ -1527,17 +1883,17 @@ var GitHubIOAdapter = class {
 };
 var GitHubSystemAdapter = class {
   readFile(path) {
-    return readFileSync7(path, "utf-8");
+    return readFileSync8(path, "utf-8");
   }
   writeFile(path, content) {
-    const dir = dirname5(path);
-    if (!existsSync7(dir)) {
+    const dir = dirname4(path);
+    if (!existsSync8(dir)) {
       mkdirSync5(dir, { recursive: true });
     }
     writeFileSync6(path, content);
   }
   fileExists(path) {
-    return existsSync7(path);
+    return existsSync8(path);
   }
   exec(command) {
     try {
@@ -1573,7 +1929,7 @@ function getGitHubInfo(cwd) {
     return { owner: config.owner, repo: config.repo };
   }
   try {
-    const remoteUrl = execSync3("git remote get-url origin", { encoding: "utf-8", cwd }).trim();
+    const remoteUrl = execSync2("git remote get-url origin", { encoding: "utf-8", cwd }).trim();
     const sshMatch = remoteUrl.match(/git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/);
     if (sshMatch) {
       return { owner: sshMatch[1], repo: sshMatch[2] };
@@ -1588,7 +1944,7 @@ function getGitHubInfo(cwd) {
 }
 function getCurrentBranch() {
   try {
-    return execSync3("git branch --show-current", { encoding: "utf-8" }).trim() || void 0;
+    return execSync2("git branch --show-current", { encoding: "utf-8" }).trim() || void 0;
   } catch {
     return void 0;
   }
@@ -1643,7 +1999,7 @@ async function startCommand(query, options) {
   console.log(`
 \u{1F680} Starting workflow: ${query}
 `);
-  if (response.type === "step") {
+  if (response.type === "phase" && response.phase === "context") {
     taskId = response.taskId;
     if (isGitHubMode && "io" in adapter && "setTaskId" in adapter.io) {
       adapter.io.setTaskId(taskId);
@@ -1651,69 +2007,87 @@ async function startCommand(query, options) {
   }
   try {
     while (response.type !== "complete" && response.type !== "error") {
-      if (response.type === "step") {
-        const stepResponse = response;
-        taskId = stepResponse.taskId;
-        console.log(`
---- Step ${stepResponse.stepIndex}/${stepResponse.totalSteps}: ${stepResponse.step} ---
-`);
-        const context = {
-          taskId: stepResponse.taskId,
-          description: stepResponse.description,
-          stepIndex: stepResponse.stepIndex,
-          totalSteps: stepResponse.totalSteps,
-          revisionFeedback: stepResponse.context.revisionFeedback
-        };
-        try {
-          const result = await stepExecutor.execute(stepResponse.step, context);
-          if (result.approved) {
-            response = orchestrator.cmdApprove(taskId);
-          } else if (result.rejected) {
-            response = orchestrator.cmdReject(taskId);
-          } else if (result.stopped) {
-            response = orchestrator.cmdStop(taskId);
-          } else {
-            throw new Error("Unexpected step result");
-          }
-        } catch (error) {
-          if (error instanceof PauseForInputError) {
+      if (response.type === "phase") {
+        const phaseResponse = response;
+        taskId = phaseResponse.taskId;
+        if (phaseResponse.phase === "context") {
+          const contextResp = phaseResponse;
+          console.log(`
+--- Step ${contextResp.stepIndex}/${contextResp.totalSteps}: ${contextResp.step} ---`);
+          console.log("Phase 1/4: Gathering context...\n");
+          const stepContext = {
+            taskId: contextResp.taskId,
+            description: contextResp.description,
+            stepIndex: contextResp.stepIndex,
+            totalSteps: contextResp.totalSteps,
+            previousOutput: contextResp.context.previousOutput
+          };
+          const result = await stepExecutor.executeContextPhase(contextResp.step, stepContext);
+          response = orchestrator.cmdContextDone(taskId, result.context || "");
+        } else if (phaseResponse.phase === "clarify") {
+          const clarifyResp = phaseResponse;
+          console.log("Phase 2/4: Generating questions...\n");
+          const stepContext = {
+            taskId: clarifyResp.taskId,
+            description: clarifyResp.description,
+            stepIndex: 0,
+            // Not needed for clarify
+            totalSteps: 0,
+            gatheredContext: clarifyResp.gatheredContext
+          };
+          const result = await stepExecutor.executeClarifyPhase(clarifyResp.step, stepContext);
+          response = orchestrator.cmdClarifyDone(taskId, result.questions || []);
+        } else if (phaseResponse.phase === "generate") {
+          const generateResp = phaseResponse;
+          console.log("Phase 3/4: Generating document...\n");
+          const stepContext = {
+            taskId: generateResp.taskId,
+            description: generateResp.description,
+            stepIndex: generateResp.stepIndex,
+            totalSteps: generateResp.totalSteps,
+            gatheredContext: generateResp.gatheredContext,
+            answers: generateResp.answers,
+            revisionFeedback: generateResp.context.revisionFeedback
+          };
+          await stepExecutor.executeGeneratePhase(generateResp.step, stepContext);
+          response = orchestrator.cmdGenerateDone(taskId);
+        }
+      } else if (response.type === "checkpoint") {
+        taskId = response.taskId;
+        if (response.checkpoint === "clarify") {
+          const clarifyCheckpoint = response;
+          console.log("Phase 2/4: Questions need answers\n");
+          const answers = await adapter.io.askMultiple(clarifyCheckpoint.questions);
+          if (answers.length === 0) {
             console.log(`
 \u23F8\uFE0F  Workflow paused. Task ID: ${taskId}`);
             console.log("   Resume with: spets resume --task", taskId);
             return;
           }
-          throw error;
-        }
-      } else if (response.type === "checkpoint") {
-        taskId = response.taskId;
-        if (response.checkpoint === "clarify") {
-          adapter.io.notify("Resuming from clarify checkpoint - regenerating step", "warning");
-          response = orchestrator.cmdStatus(taskId);
+          response = orchestrator.cmdClarified(taskId, answers);
         } else if (response.checkpoint === "approve") {
-          const approveResponse = response;
-          try {
-            const approval = await adapter.io.approve(
-              approveResponse.specPath,
-              approveResponse.step,
-              approveResponse.stepIndex,
-              approveResponse.totalSteps
-            );
-            if (approval.action === "approve") {
-              response = orchestrator.cmdApprove(taskId);
-            } else if (approval.action === "revise") {
-              response = orchestrator.cmdRevise(taskId, approval.feedback || "");
-            } else if (approval.action === "reject") {
-              response = orchestrator.cmdReject(taskId);
-            } else {
-              response = orchestrator.cmdStop(taskId);
-            }
-          } catch (error) {
-            if (error instanceof PauseForInputError) {
-              console.log(`
+          const approveCheckpoint = response;
+          console.log("Phase 4/4: Review document\n");
+          const approval = await adapter.io.approve(
+            approveCheckpoint.specPath,
+            approveCheckpoint.step,
+            approveCheckpoint.stepIndex,
+            approveCheckpoint.totalSteps
+          );
+          if (approval.pending) {
+            console.log(`
 \u23F8\uFE0F  Workflow paused. Task ID: ${taskId}`);
-              return;
-            }
-            throw error;
+            console.log("   Resume with: spets resume --task", taskId);
+            return;
+          }
+          if (approval.action === "approve") {
+            response = orchestrator.cmdApprove(taskId);
+          } else if (approval.action === "revise") {
+            response = orchestrator.cmdRevise(taskId, approval.feedback || "");
+          } else if (approval.action === "reject") {
+            response = orchestrator.cmdReject(taskId);
+          } else {
+            response = orchestrator.cmdStop(taskId);
           }
         }
       } else {
@@ -1752,19 +2126,19 @@ Resume with: spets resume --task ${taskId}`);
 
 // src/commands/resume.ts
 import { select as select2 } from "@inquirer/prompts";
-import { existsSync as existsSync8, readdirSync as readdirSync2 } from "fs";
-import { join as join6 } from "path";
+import { existsSync as existsSync9, readdirSync as readdirSync2 } from "fs";
+import { join as join7 } from "path";
 function listResumableTasks(cwd) {
   const outputsDir = getOutputsDir(cwd);
-  if (!existsSync8(outputsDir)) {
+  if (!existsSync9(outputsDir)) {
     return [];
   }
   const tasks = [];
   const taskDirs = readdirSync2(outputsDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
   const orchestrator = new Orchestrator(cwd);
   for (const taskId of taskDirs) {
-    const stateFile = join6(outputsDir, taskId, ".state.json");
-    if (!existsSync8(stateFile)) continue;
+    const stateFile = join7(outputsDir, taskId, ".state.json");
+    if (!existsSync9(stateFile)) continue;
     try {
       const response = orchestrator.cmdStatus(taskId);
       if (response.type === "error") continue;
@@ -1932,8 +2306,8 @@ Resume with: spets resume --task ${taskId}`);
 }
 
 // src/commands/plugin.ts
-import { existsSync as existsSync9, mkdirSync as mkdirSync6, writeFileSync as writeFileSync7, rmSync } from "fs";
-import { join as join7 } from "path";
+import { existsSync as existsSync10, mkdirSync as mkdirSync6, writeFileSync as writeFileSync7, rmSync } from "fs";
+import { join as join8 } from "path";
 import { homedir } from "os";
 async function pluginCommand(action, name) {
   switch (action) {
@@ -1975,10 +2349,10 @@ async function installPlugin(name) {
   installer();
 }
 function installClaudePlugin() {
-  const claudeDir = join7(homedir(), ".claude");
-  const commandsDir = join7(claudeDir, "commands");
+  const claudeDir = join8(homedir(), ".claude");
+  const commandsDir = join8(claudeDir, "commands");
   mkdirSync6(commandsDir, { recursive: true });
-  const skillPath = join7(commandsDir, "spets.md");
+  const skillPath = join8(commandsDir, "spets.md");
   writeFileSync7(skillPath, getClaudeSkillContent());
   console.log("Installed Claude Code plugin.");
   console.log(`Location: ${skillPath}`);
@@ -1991,14 +2365,14 @@ function installClaudePlugin() {
 }
 async function uninstallPlugin(name) {
   if (name === "claude") {
-    const skillPath = join7(homedir(), ".claude", "commands", "spets.md");
-    const legacySkillPath = join7(homedir(), ".claude", "commands", "sdd-do.md");
+    const skillPath = join8(homedir(), ".claude", "commands", "spets.md");
+    const legacySkillPath = join8(homedir(), ".claude", "commands", "sdd-do.md");
     let uninstalled = false;
-    if (existsSync9(skillPath)) {
+    if (existsSync10(skillPath)) {
       rmSync(skillPath);
       uninstalled = true;
     }
-    if (existsSync9(legacySkillPath)) {
+    if (existsSync10(legacySkillPath)) {
       rmSync(legacySkillPath);
       uninstalled = true;
     }
@@ -2017,9 +2391,9 @@ async function listPlugins() {
   console.log("");
   console.log("  claude - Claude Code /spets skill");
   console.log("");
-  const skillPath = join7(homedir(), ".claude", "commands", "spets.md");
-  const legacySkillPath = join7(homedir(), ".claude", "commands", "sdd-do.md");
-  const claudeInstalled = existsSync9(skillPath) || existsSync9(legacySkillPath);
+  const skillPath = join8(homedir(), ".claude", "commands", "spets.md");
+  const legacySkillPath = join8(homedir(), ".claude", "commands", "sdd-do.md");
+  const claudeInstalled = existsSync10(skillPath) || existsSync10(legacySkillPath);
   console.log("Installed:");
   if (claudeInstalled) {
     console.log("  - claude");
@@ -2189,9 +2563,9 @@ request: The user's task description for the workflow
 }
 
 // src/commands/github.ts
-import { execSync as execSync4, spawn as spawn3, spawnSync as spawnSync3 } from "child_process";
-import { readdirSync as readdirSync4, readFileSync as readFileSync8, existsSync as existsSync10 } from "fs";
-import { join as join8 } from "path";
+import { execSync as execSync3, spawn as spawn3, spawnSync as spawnSync3 } from "child_process";
+import { readdirSync as readdirSync4, readFileSync as readFileSync9, existsSync as existsSync11 } from "fs";
+import { join as join9 } from "path";
 function parseGitHubCommand(comment) {
   const trimmed = comment.trim();
   if (trimmed === "/approve") {
@@ -2231,7 +2605,7 @@ function getGitHubInfo2(cwd) {
     return { owner: config.owner, repo: config.repo };
   }
   try {
-    const remoteUrl = execSync4("git remote get-url origin", { encoding: "utf-8", cwd }).trim();
+    const remoteUrl = execSync3("git remote get-url origin", { encoding: "utf-8", cwd }).trim();
     const sshMatch = remoteUrl.match(/git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/);
     if (sshMatch) {
       return { owner: sshMatch[1], repo: sshMatch[2] };
@@ -2246,7 +2620,7 @@ function getGitHubInfo2(cwd) {
 }
 function getCurrentBranch2(cwd) {
   try {
-    return execSync4("git branch --show-current", { encoding: "utf-8", cwd }).trim();
+    return execSync3("git branch --show-current", { encoding: "utf-8", cwd }).trim();
   } catch {
     return void 0;
   }
@@ -2254,7 +2628,7 @@ function getCurrentBranch2(cwd) {
 function findTaskId(cwd, owner, repo, issueOrPr) {
   if (issueOrPr) {
     try {
-      const commentsJson = execSync4(
+      const commentsJson = execSync3(
         `gh api repos/${owner}/${repo}/issues/${issueOrPr}/comments --jq '.[].body'`,
         { encoding: "utf-8" }
       );
@@ -2266,7 +2640,7 @@ function findTaskId(cwd, owner, repo, issueOrPr) {
     }
   }
   const outputsDir = getOutputsDir(cwd);
-  if (existsSync10(outputsDir)) {
+  if (existsSync11(outputsDir)) {
     const taskDirs = readdirSync4(outputsDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort().reverse();
     if (taskDirs.length > 0) {
       return taskDirs[0];
@@ -2323,15 +2697,15 @@ async function githubCommand(options) {
     case "approve": {
       console.log("Approving current step...");
       response = orchestrator.cmdApprove(taskId);
-      if (parsed.createPR && response.type !== "error") {
+      if (parsed.createPR && response.type === "complete") {
         console.log("Creating PR with AI-generated content...");
-        const stepResponse = response;
-        await createPullRequestWithAI(githubConfig, taskId, stepResponse.description || "", cwd);
+        const completeResp = response;
+        await createPullRequestWithAI(githubConfig, taskId, completeResp.message || "", cwd);
       }
-      if (parsed.createIssue && response.type !== "error") {
+      if (parsed.createIssue && response.type === "phase") {
         console.log("Creating/Updating Issue...");
-        const stepResponse = response;
-        await createOrUpdateIssue(githubConfig, taskId, stepResponse.description || "", stepResponse.step);
+        const phaseResp = response;
+        await createOrUpdateIssue(githubConfig, taskId, phaseResp.description || "", phaseResp.step);
       }
       break;
     }
@@ -2356,37 +2730,78 @@ async function githubCommand(options) {
       break;
     }
   }
-  if (response.type === "step") {
-    const stepResponse = response;
-    const stepExecutor = new StepExecutor(adapter, config, cwd);
-    console.log(`
---- Step ${stepResponse.stepIndex}/${stepResponse.totalSteps}: ${stepResponse.step} ---
-`);
-    const context = {
-      taskId: stepResponse.taskId,
-      description: stepResponse.description,
-      stepIndex: stepResponse.stepIndex,
-      totalSteps: stepResponse.totalSteps,
-      revisionFeedback: stepResponse.context.revisionFeedback
-    };
-    try {
-      const result = await stepExecutor.execute(stepResponse.step, context);
-      if (result.approved) {
-        orchestrator.cmdApprove(taskId);
-      } else if (result.rejected) {
-        orchestrator.cmdReject(taskId);
-      } else if (result.stopped) {
-        orchestrator.cmdStop(taskId);
+  const stepExecutor = new StepExecutor(adapter, config, cwd);
+  while (response.type !== "complete" && response.type !== "error") {
+    if (response.type === "phase") {
+      const phaseResponse = response;
+      if (phaseResponse.phase === "context") {
+        const contextResp = phaseResponse;
+        console.log(`
+--- Step ${contextResp.stepIndex}/${contextResp.totalSteps}: ${contextResp.step} ---`);
+        console.log("Phase 1/4: Gathering context...\n");
+        const stepContext = {
+          taskId: contextResp.taskId,
+          description: contextResp.description,
+          stepIndex: contextResp.stepIndex,
+          totalSteps: contextResp.totalSteps,
+          previousOutput: contextResp.context.previousOutput
+        };
+        const result = await stepExecutor.executeContextPhase(contextResp.step, stepContext);
+        response = orchestrator.cmdContextDone(taskId, result.context || "");
+      } else if (phaseResponse.phase === "clarify") {
+        const clarifyResp = phaseResponse;
+        console.log("Phase 2/4: Generating questions...\n");
+        const stepContext = {
+          taskId: clarifyResp.taskId,
+          description: clarifyResp.description,
+          stepIndex: 0,
+          totalSteps: 0,
+          gatheredContext: clarifyResp.gatheredContext
+        };
+        const result = await stepExecutor.executeClarifyPhase(clarifyResp.step, stepContext);
+        response = orchestrator.cmdClarifyDone(taskId, result.questions || []);
+      } else if (phaseResponse.phase === "generate") {
+        const generateResp = phaseResponse;
+        console.log("Phase 3/4: Generating document...\n");
+        const stepContext = {
+          taskId: generateResp.taskId,
+          description: generateResp.description,
+          stepIndex: generateResp.stepIndex,
+          totalSteps: generateResp.totalSteps,
+          gatheredContext: generateResp.gatheredContext,
+          answers: generateResp.answers,
+          revisionFeedback: generateResp.context.revisionFeedback
+        };
+        await stepExecutor.executeGeneratePhase(generateResp.step, stepContext);
+        response = orchestrator.cmdGenerateDone(taskId);
       }
-    } catch (error) {
-      if (error instanceof PauseForInputError) {
+    } else if (response.type === "checkpoint") {
+      if (response.checkpoint === "clarify") {
+        const clarifyCheckpoint = response;
+        console.log("Phase 2/4: Questions need answers\n");
+        await adapter.io.askMultiple(clarifyCheckpoint.questions);
+        console.log(`
+\u23F8\uFE0F  Workflow paused. Waiting for /answer on GitHub.`);
+        return;
+      } else if (response.checkpoint === "approve") {
+        const approveCheckpoint = response;
+        console.log("Phase 4/4: Document ready for review\n");
+        await adapter.io.approve(
+          approveCheckpoint.specPath,
+          approveCheckpoint.step,
+          approveCheckpoint.stepIndex,
+          approveCheckpoint.totalSteps
+        );
         console.log(`
-\u23F8\uFE0F  Workflow paused. Waiting for input on GitHub.`);
+\u23F8\uFE0F  Workflow paused. Waiting for /approve or /revise on GitHub.`);
         return;
       }
-      throw error;
+    } else {
+      console.error(`Unknown response type: ${response.type}`);
+      process.exit(1);
     }
-  } else if (response.type === "complete") {
+  }
+  if (response.type === "complete") {
     const completeResponse = response;
     if (completeResponse.status === "completed") {
       console.log("\u2705 Workflow completed!");
@@ -2431,12 +2846,12 @@ async function postComment(config, body) {
 }
 async function createPullRequestWithAI(config, taskId, userQuery, cwd) {
   const { owner, repo, issueNumber } = config;
-  const outputsDir = join8(getOutputsDir(cwd), taskId);
+  const outputsDir = join9(getOutputsDir(cwd), taskId);
   const outputs = [];
-  if (existsSync10(outputsDir)) {
+  if (existsSync11(outputsDir)) {
     const files = readdirSync4(outputsDir).filter((f) => f.endsWith(".md"));
     for (const file of files) {
-      const content = readFileSync8(join8(outputsDir, file), "utf-8");
+      const content = readFileSync9(join9(outputsDir, file), "utf-8");
       outputs.push({ step: file.replace(".md", ""), content });
     }
   }
@@ -2597,6 +3012,47 @@ async function orchestrateCommand(action, args) {
         outputJSON(result);
         break;
       }
+      case "context-done": {
+        const taskId = args[0];
+        const contextJson = args[1];
+        if (!taskId) {
+          outputError("Task ID is required for context-done");
+          return;
+        }
+        const result = orchestrator.cmdContextDone(taskId, contextJson || "");
+        outputJSON(result);
+        break;
+      }
+      case "clarify-done": {
+        const taskId = args[0];
+        const questionsJson = args[1];
+        if (!taskId) {
+          outputError("Task ID is required for clarify-done");
+          return;
+        }
+        let questions = [];
+        if (questionsJson) {
+          try {
+            questions = JSON.parse(questionsJson);
+          } catch {
+            outputError("Invalid JSON for questions");
+            return;
+          }
+        }
+        const result = orchestrator.cmdClarifyDone(taskId, questions);
+        outputJSON(result);
+        break;
+      }
+      case "generate-done": {
+        const taskId = args[0];
+        if (!taskId) {
+          outputError("Task ID is required for generate-done");
+          return;
+        }
+        const result = orchestrator.cmdGenerateDone(taskId);
+        outputJSON(result);
+        break;
+      }
       case "done": {
         const taskId = args[0];
         if (!taskId) {
@@ -2685,8 +3141,8 @@ async function orchestrateCommand(action, args) {
 }
 
 // src/index.ts
-var __dirname2 = dirname6(fileURLToPath2(import.meta.url));
-var pkg = JSON.parse(readFileSync9(join9(__dirname2, "..", "package.json"), "utf-8"));
+var __dirname2 = dirname5(fileURLToPath2(import.meta.url));
+var pkg = JSON.parse(readFileSync10(join10(__dirname2, "..", "package.json"), "utf-8"));
 var program = new Command();
 program.name("spets").description("Spec Driven Development Execution Framework").version(pkg.version);
 program.command("init").description("Initialize spets in current directory").option("-f, --force", "Overwrite existing config").option("--github", "Add GitHub Actions workflow for PR/Issue integration").action(initCommand);