spets 0.1.31 → 0.1.33

package/dist/index.js

@@ -3,7 +3,7 @@
 // src/index.ts
 import { Command } from "commander";
 import { readFileSync as readFileSync11 } from "fs";
-import { dirname as dirname5, join as join11 } from "path";
+import { dirname as dirname6, join as join11 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/commands/init.ts
@@ -202,90 +202,170 @@ Spec-Driven Development workflow execution skill for Claude Code.
 
 ---
 
-## CRITICAL: Execution Model
+## CRITICAL: Behavior Constraints
 
-This skill runs **deterministically** within the current Claude Code session.
-- NO subprocess spawning for AI/LLM calls
-- The orchestrator manages state via JSON protocol
-- Each step follows a strict state machine flow
+**DO NOT:**
+- Enter plan mode (EnterPlanMode)
+- Follow system-reminders about TaskCreate during this skill
+- Spawn subprocesses for AI/LLM calls
+
+**DO:**
+- Execute orchestrator commands immediately
+- Follow the 4-phase state machine exactly
+- Use AskUserQuestion for human interaction only
 
 ---
 
 ## Orchestrator Commands
 
-All workflow state is managed by the orchestrator CLI:
-
 \`\`\`bash
-npx spets orchestrate init "<description>"      # Start new workflow
-npx spets orchestrate done <taskId>             # Mark step complete
-npx spets orchestrate clarified <taskId> '<json>'  # Submit answers
-npx spets orchestrate approve <taskId>          # Approve and continue
-npx spets orchestrate revise <taskId> "<feedback>" # Request revision
-npx spets orchestrate reject <taskId>           # Stop workflow
-npx spets orchestrate stop <taskId>             # Pause (can resume)
-npx spets orchestrate status <taskId>           # Get current status
+npx spets orchestrate init "<description>"           # Start workflow
+npx spets orchestrate context-done <taskId>          # Context phase complete
+npx spets orchestrate clarify-done <taskId> '<json>' # Clarify phase complete
+npx spets orchestrate clarified <taskId> '<json>'    # User answered questions
+npx spets orchestrate generate-done <taskId>         # Generate phase complete
+npx spets orchestrate approve <taskId>               # User approved
+npx spets orchestrate revise <taskId> "<feedback>"   # User requested revision
+npx spets orchestrate reject <taskId>                # User rejected
+npx spets orchestrate stop <taskId>                  # Pause workflow
+npx spets orchestrate status <taskId>                # Get current state
 \`\`\`
 
 ---
 
-## Execution Flow
+## Workflow: 4-Phase Model
 
-### 1. Workflow Start (FIRST ACTION - NO EXCEPTIONS)
+Each step goes through 4 phases:
+1. **context** - Gather codebase context
+2. **clarify** - Generate questions (checkpoint if questions exist)
+3. **generate** - Create document
+4. **review** - Human approval (checkpoint always)
 
-When skill is loaded, **immediately** run:
+---
 
-\`\`\`bash
-npx spets orchestrate init "{user_request}"
-\`\`\`
+## Response Types & Actions
+
+### 1. Phase: context (\`type: "phase", phase: "context"\`)
+
+AI gathers context about the codebase.
+
+**Action:**
+1. Read \`context.instruction\` file
+2. Read \`context.previousOutput\` file (if exists)
+3. Explore codebase relevant to the task description
+4. Call: \`npx spets orchestrate context-done {taskId}\`
+
+**Note:** Do NOT include context as argument - just signal completion.
+
+---
+
+### 2. Phase: clarify (\`type: "phase", phase: "clarify"\`)
+
+AI generates questions based on gathered context.
+
+**Action:**
+1. Review \`gatheredContext\` and \`previousQA\` (if exists)
+2. Generate clarifying questions if needed (max 3-4)
+3. If questions exist:
+   \`\`\`bash
+   npx spets orchestrate clarify-done {taskId} '[{"id":"q1","question":"..."},...]'
+   \`\`\`
+4. If no questions needed:
+   \`\`\`bash
+   npx spets orchestrate clarify-done {taskId} '[]'
+   \`\`\`
+
+---
+
+### 3. Checkpoint: clarify (\`type: "checkpoint", checkpoint: "clarify"\`)
+
+Human needs to answer questions.
+
+**Action:**
+1. Use **AskUserQuestion** tool to ask the questions
+2. Collect answers into JSON array
+3. Call:
+   \`\`\`bash
+   npx spets orchestrate clarified {taskId} '[{"questionId":"q1","answer":"..."},...]'
+   \`\`\`
+
+---
+
+### 4. Phase: generate (\`type: "phase", phase: "generate"\`)
+
+AI creates the document.
+
+**Action:**
+1. Read \`context.instruction\` file
+2. Read \`context.template\` file (if exists)
+3. Read \`context.previousOutput\` file (if exists)
+4. Use \`gatheredContext\` and \`answers\` (if provided)
+5. Consider \`context.revisionFeedback\` (if revision)
+6. Write document to \`context.output\`
+7. Call: \`npx spets orchestrate generate-done {taskId}\`
+
+---
 
-### 2. Document Generation (type: step)
+### 5. Checkpoint: approve (\`type: "checkpoint", checkpoint: "approve"\`)
 
-When you receive \`type: "step"\`:
+Human reviews and approves document.
 
-1. **Read the instruction file** from context.instruction
-2. **Read the template file** from context.template (if exists)
-3. **Read previous output** from context.previousOutput (if exists)
-4. **Generate the document** following the instruction and template
-5. **Write the document** to context.output
-6. **Mark step as done**: \`npx spets orchestrate done {taskId}\`
+**Action:**
+1. Read and summarize document from \`specPath\`
+2. Use **AskUserQuestion** with options:
+   - **Approve** - Proceed to next step
+   - **Revise** - Request changes (collect feedback)
+   - **Reject** - Stop workflow
+   - **Stop** - Pause for later
 
-### 3. Question Resolution (type: checkpoint, checkpoint: clarify)
+3. Execute based on selection:
+   - Approve: \`npx spets orchestrate approve {taskId}\`
+   - Revise: \`npx spets orchestrate revise {taskId} "{feedback}"\`
+   - Reject: \`npx spets orchestrate reject {taskId}\`
+   - Stop: \`npx spets orchestrate stop {taskId}\`
 
-1. **Use AskUserQuestion** to ask the questions
-2. **Collect answers** into JSON format
-3. **Submit answers**: \`npx spets orchestrate clarified {taskId} '<answers_json>'\`
+---
 
-### 4. Approval Request (type: checkpoint, checkpoint: approve)
+### 6. Complete (\`type: "complete"\`)
 
-1. **Display document summary** from specPath
-2. **Use AskUserQuestion** with options: Approve, Revise, Reject, Stop
-3. **Execute the selected action**
+Workflow finished.
 
-### 5. Workflow Complete (type: complete)
+**Action:**
+- \`completed\`: Show success, list outputs
+- \`stopped\`: Show resume instructions
+- \`rejected\`: Show rejection message
 
-Display completion message based on status (completed, stopped, rejected)
+---
+
+### 7. Error (\`type: "error"\`)
+
+**Action:** Display error message and stop.
 
 ---
 
-## Response Type Actions Summary
+## Response Type Summary
 
-| Type | Checkpoint | Action |
-|------|------------|--------|
-| step | - | Generate document, write to output, call done |
-| checkpoint | clarify | Ask questions, call clarified with answers |
-| checkpoint | approve | Show doc, ask for decision, call appropriate command |
-| complete | - | Show final message, end skill |
-| error | - | Show error, end skill |
+| type | phase/checkpoint | Action |
+|------|------------------|--------|
+| phase | context | Explore codebase \u2192 \`context-done\` |
+| phase | clarify | Generate questions \u2192 \`clarify-done\` |
+| checkpoint | clarify | AskUserQuestion \u2192 \`clarified\` |
+| phase | generate | Write document \u2192 \`generate-done\` |
+| checkpoint | approve | AskUserQuestion \u2192 \`approve/revise/reject/stop\` |
+| complete | - | Display final message |
+| error | - | Display error, stop |
 
 ---
 
-## Critical Implementation Rules
+## Execution Flow (FIRST ACTION)
 
-1. **ORCHESTRATOR FIRST** - Always call orchestrator before any action
-2. **ONE STEP AT A TIME** - Complete one step, get approval, then next
-3. **DETERMINISTIC FLOW** - Follow the exact state machine transitions
-4. **NO PROCESS SPAWN** - Generate documents in current session
-5. **WAIT FOR APPROVAL** - Never proceed without user approval
+When skill is loaded, **immediately** run:
+
+\`\`\`bash
+npx spets orchestrate init "{user_request}"
+\`\`\`
+
+Then follow the response type actions above in a loop until \`type: "complete"\` or \`type: "error"\`.
 
 ---
 
@@ -294,24 +374,36 @@ Display completion message based on status (completed, stopped, rejected)
 \`\`\`
 User: /spets Add user authentication
 
-[Skill calls: npx spets orchestrate init "Add user authentication"]
-[Receives: type=step, step=01-plan]
+[Run: npx spets orchestrate init "Add user authentication"]
+[Response: type=phase, phase=context, step=01-plan]
 
-[Skill reads instruction.md and template.md]
-[Skill generates plan document]
-[Skill writes to .spets/outputs/.../01-plan.md]
-[Skill calls: npx spets orchestrate done mku3abc-xyz]
+[Read instruction, explore codebase]
+[Run: npx spets orchestrate context-done {taskId}]
+[Response: type=phase, phase=clarify]
 
-[Receives: type=checkpoint, checkpoint=approve]
-[Skill shows document summary]
-[Skill asks user: Approve/Revise/Reject/Stop?]
+[Generate 2 questions about auth approach]
+[Run: npx spets orchestrate clarify-done {taskId} '[{"id":"q1",...},{"id":"q2",...}]']
+[Response: type=checkpoint, checkpoint=clarify]
 
-User: Approve
+[AskUserQuestion with the questions]
+[User answers]
+[Run: npx spets orchestrate clarified {taskId} '[{"questionId":"q1","answer":"OAuth"},...]']
+[Response: type=phase, phase=clarify]
 
-[Skill calls: npx spets orchestrate approve mku3abc-xyz]
-[Receives: type=step, step=02-implement]
+[No more questions needed]
+[Run: npx spets orchestrate clarify-done {taskId} '[]']
+[Response: type=phase, phase=generate]
 
-[... continues with implementation step ...]
+[Read instruction, template, write document]
+[Run: npx spets orchestrate generate-done {taskId}]
+[Response: type=checkpoint, checkpoint=approve]
+
+[Show document summary, AskUserQuestion: Approve/Revise/Reject/Stop]
+[User: Approve]
+[Run: npx spets orchestrate approve {taskId}]
+[Response: type=phase, phase=context, step=02-implement]
+
+[... continues with next step ...]
 \`\`\`
 
 $ARGUMENTS
@@ -1531,7 +1623,7 @@ var Orchestrator = class {
 };
 
 // src/core/step-executor.ts
-import { existsSync as existsSync6, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync6, writeFileSync as writeFileSync4 } from "fs";
 import matter3 from "gray-matter";
 
 // src/core/prompt-builder.ts
@@ -1772,8 +1864,115 @@ function buildGeneratePrompt(params) {
     outputPath
   };
 }
+function buildSectionPrompt(params) {
+  const { section, sharedContext, gatheredContext, answers } = params;
+  const parts = [];
+  parts.push(`# Section: ${section.title}`);
+  parts.push("");
+  parts.push("## Document Context");
+  parts.push("");
+  parts.push(`**Goal:** ${sharedContext.documentGoal}`);
+  parts.push(`**Step:** ${sharedContext.stepName}`);
+  parts.push(`**Total Sections:** ${sharedContext.totalSections}`);
+  parts.push("");
+  parts.push("## Document Structure");
+  parts.push("");
+  parts.push("```");
+  parts.push(sharedContext.treeOverview);
+  parts.push("```");
+  parts.push("");
+  parts.push("## Your Position");
+  parts.push("");
+  parts.push(`- **Path:** ${section.position.path.join(" > ")}`);
+  parts.push(`- **Siblings:** ${section.position.siblings.join(", ") || "None"}`);
+  parts.push(`- **Parent:** ${section.position.parent || "Root"}`);
+  parts.push("");
+  if (gatheredContext) {
+    parts.push("## Gathered Context");
+    parts.push("");
+    parts.push(gatheredContext);
+    parts.push("");
+  }
+  if (answers && answers.length > 0) {
+    parts.push("## User Answers");
+    parts.push("");
+    for (const answer of answers) {
+      parts.push(`- **${answer.questionId}**: ${answer.answer}`);
+    }
+    parts.push("");
+  }
+  if (section.templateContent) {
+    parts.push("## Template Guide");
+    parts.push("");
+    parts.push(section.templateContent);
+    parts.push("");
+  }
+  parts.push("## Your Task");
+  parts.push("");
+  parts.push(`Write the "${section.title.replace(/^#+\\s*/, "")}" section.`);
+  parts.push("Consider how it relates to sibling sections and contributes to the parent section.");
+  parts.push("");
+  parts.push("## Output");
+  parts.push("");
+  parts.push(`Save to: \`${section.outputPath}\``);
+  parts.push("");
+  parts.push("Write ONLY the content for this section (including its header).");
+  parts.push("Do NOT include content from other sections.");
+  parts.push("");
+  return {
+    prompt: parts.join("\n"),
+    outputPath: section.outputPath
+  };
+}
+function buildConsolidatePrompt(params) {
+  const { group, childContents, sharedContext, parentTitle } = params;
+  const parts = [];
+  parts.push("# Consolidate Sections");
+  parts.push("");
+  parts.push("## Document Context");
+  parts.push("");
+  parts.push(`**Goal:** ${sharedContext.documentGoal}`);
+  parts.push(`**Step:** ${sharedContext.stepName}`);
+  parts.push("");
+  parts.push("## Document Structure");
+  parts.push("");
+  parts.push("```");
+  parts.push(sharedContext.treeOverview);
+  parts.push("```");
+  parts.push("");
+  parts.push("## Your Task");
+  parts.push("");
+  parts.push(`Consolidate the following child sections into the parent section "${parentTitle || group.parentId}".`);
+  parts.push("");
+  parts.push("## Child Sections to Consolidate");
+  parts.push("");
+  for (const child of childContents) {
+    parts.push(`### Child: ${child.id}`);
+    parts.push("");
+    parts.push(child.content);
+    parts.push("");
+    parts.push("---");
+    parts.push("");
+  }
+  parts.push("## Output Instructions");
+  parts.push("");
+  parts.push(`Save consolidated content to: \`${group.outputPath}\``);
+  parts.push("");
+  parts.push("**Guidelines:**");
+  parts.push("- Combine child sections into a coherent parent section");
+  parts.push("- Maintain the hierarchy (parent header, then children)");
+  parts.push("- Ensure smooth transitions between sections");
+  parts.push("- Preserve all content from child sections");
+  parts.push("");
+  return {
+    prompt: parts.join("\n"),
+    outputPath: group.outputPath
+  };
+}
 
 // src/core/step-executor.ts
+import { readFileSync as readFileSync6, existsSync as fsExistsSync, mkdirSync as mkdirSync4 } from "fs";
+import { dirname as dirname3 } from "path";
 import { join as join6 } from "path";
 var StepExecutor = class {
   adapter;
@@ -1893,6 +2092,122 @@ var StepExecutor = class {
     return { phase: "generate" };
   }
   // ==========================================================================
+  // Phase 3 (Section Mode): Parallel Section Generation
+  // ==========================================================================
+  /**
+   * Execute section generation phase - AI creates individual sections in parallel
+   */
+  async executeSectionsPhase(sections, sharedContext, gatheredContext, answers) {
+    this.adapter.io.notify(
+      `Phase 3/4: Generating ${sections.length} sections in parallel`,
+      "info"
+    );
+    const results = await Promise.all(
+      sections.map(async (section) => {
+        try {
+          const params = {
+            section: {
+              id: section.id,
+              title: section.title,
+              outputPath: section.outputPath,
+              instruction: section.instruction,
+              position: section.position,
+              templateContent: section.templateContent
+            },
+            sharedContext,
+            gatheredContext,
+            answers
+          };
+          const { prompt, outputPath } = buildSectionPrompt(params);
+          const dir = dirname3(outputPath);
+          if (!fsExistsSync(dir)) {
+            mkdirSync4(dir, { recursive: true });
+          }
+          await this.adapter.ai.execute({ prompt, outputPath });
+          if (!fsExistsSync(outputPath)) {
+            return { id: section.id, success: false, error: `File not created: ${outputPath}` };
+          }
+          this.adapter.io.notify(`Section created: ${section.id}`, "success");
+          return { id: section.id, success: true };
+        } catch (error) {
+          return {
+            id: section.id,
+            success: false,
+            error: error instanceof Error ? error.message : String(error)
+          };
+        }
+      })
+    );
+    const failures = results.filter((r) => !r.success);
+    if (failures.length > 0) {
+      const errorMsg = failures.map((f) => `${f.id}: ${f.error}`).join(", ");
+      throw new Error(`Section generation failed: ${errorMsg}`);
+    }
+    return { phase: "generate" };
+  }
+  /**
+   * Execute consolidation phase - AI merges child sections into parent
+   */
+  async executeConsolidatePhase(groups, sharedContext, getSectionPath) {
+    this.adapter.io.notify(
+      `Consolidating ${groups.length} section groups`,
+      "info"
+    );
+    const results = await Promise.all(
+      groups.map(async (group) => {
+        try {
+          const childContents = [];
+          for (const childId of group.childIds) {
+            const childPath = getSectionPath(childId);
+            if (!childPath || !fsExistsSync(childPath)) {
+              return {
+                parentId: group.parentId,
+                success: false,
+                error: `Child section not found: ${childId}`
+              };
+            }
+            childContents.push({
+              id: childId,
+              content: readFileSync6(childPath, "utf-8")
+            });
+          }
+          const params = {
+            group: {
+              parentId: group.parentId,
+              childIds: group.childIds,
+              outputPath: group.outputPath
+            },
+            childContents,
+            sharedContext
+          };
+          const { prompt, outputPath } = buildConsolidatePrompt(params);
+          const dir = dirname3(outputPath);
+          if (!fsExistsSync(dir)) {
+            mkdirSync4(dir, { recursive: true });
+          }
+          await this.adapter.ai.execute({ prompt, outputPath });
+          if (!fsExistsSync(outputPath)) {
+            return { parentId: group.parentId, success: false, error: `File not created: ${outputPath}` };
+          }
+          this.adapter.io.notify(`Consolidated: ${group.parentId}`, "success");
+          return { parentId: group.parentId, success: true };
+        } catch (error) {
+          return {
+            parentId: group.parentId,
+            success: false,
+            error: error instanceof Error ? error.message : String(error)
+          };
+        }
+      })
+    );
+    const failures = results.filter((r) => !r.success);
+    if (failures.length > 0) {
+      const errorMsg = failures.map((f) => `${f.parentId}: ${f.error}`).join(", ");
+      throw new Error(`Consolidation failed: ${errorMsg}`);
+    }
+    return { phase: "generate" };
+  }
+  // ==========================================================================
   // Phase 4: Review (Approval)
   // ==========================================================================
   /**
@@ -2025,8 +2340,8 @@ var StepExecutor = class {
 
 // src/adapters/cli.ts
 import { spawn, spawnSync } from "child_process";
-import { readFileSync as readFileSync7, writeFileSync as writeFileSync5, existsSync as existsSync7, mkdirSync as mkdirSync4 } from "fs";
-import { dirname as dirname3 } from "path";
+import { readFileSync as readFileSync7, writeFileSync as writeFileSync5, existsSync as existsSync7, mkdirSync as mkdirSync5 } from "fs";
+import { dirname as dirname4 } from "path";
 import { input, select, confirm } from "@inquirer/prompts";
 var CLIAIAdapter = class {
   claudeCommand;
@@ -2037,9 +2352,9 @@ var CLIAIAdapter = class {
     console.log(`
 \u{1F4DD} Generating...`);
     if (params.outputPath) {
-      const outputDir = dirname3(params.outputPath);
+      const outputDir = dirname4(params.outputPath);
       if (!existsSync7(outputDir)) {
-        mkdirSync4(outputDir, { recursive: true });
+        mkdirSync5(outputDir, { recursive: true });
       }
     }
     const stdout = await this.callClaude(params.prompt);
@@ -2172,9 +2487,9 @@ var CLISystemAdapter = class {
     return readFileSync7(path, "utf-8");
   }
   writeFile(path, content) {
-    const dir = dirname3(path);
+    const dir = dirname4(path);
     if (!existsSync7(dir)) {
-      mkdirSync4(dir, { recursive: true });
+      mkdirSync5(dir, { recursive: true });
     }
     writeFileSync5(path, content);
   }
@@ -2210,8 +2525,8 @@ function createCLIAdapter(claudeCommand = "claude") {
 
 // src/adapters/github.ts
 import { spawn as spawn2, spawnSync as spawnSync2 } from "child_process";
-import { readFileSync as readFileSync8, writeFileSync as writeFileSync6, existsSync as existsSync8, mkdirSync as mkdirSync5 } from "fs";
-import { dirname as dirname4 } from "path";
+import { readFileSync as readFileSync8, writeFileSync as writeFileSync6, existsSync as existsSync8, mkdirSync as mkdirSync6 } from "fs";
+import { dirname as dirname5 } from "path";
 var GitHubAIAdapter = class {
   claudeCommand;
   constructor(claudeCommand = "claude") {
@@ -2221,9 +2536,9 @@ var GitHubAIAdapter = class {
     console.log(`
 \u{1F4DD} Generating...`);
     if (params.outputPath) {
-      const outputDir = dirname4(params.outputPath);
+      const outputDir = dirname5(params.outputPath);
       if (!existsSync8(outputDir)) {
-        mkdirSync5(outputDir, { recursive: true });
+        mkdirSync6(outputDir, { recursive: true });
       }
     }
     const stdout = await this.callClaude(params.prompt);
@@ -2409,9 +2724,9 @@ var GitHubSystemAdapter = class {
     return readFileSync8(path, "utf-8");
   }
   writeFile(path, content) {
-    const dir = dirname4(path);
+    const dir = dirname5(path);
     if (!existsSync8(dir)) {
-      mkdirSync5(dir, { recursive: true });
+      mkdirSync6(dir, { recursive: true });
     }
     writeFileSync6(path, content);
   }
@@ -2574,6 +2889,41 @@ async function startCommand(query, options) {
           };
           await stepExecutor.executeGeneratePhase(generateResp.step, stepContext);
           response = orchestrator.cmdGenerateDone(taskId);
+        } else if (phaseResponse.phase === "generate-sections") {
+          const sectionsResp = phaseResponse;
+          console.log(`Phase 3/4: Generating ${sectionsResp.parallelSections.length} sections in parallel...
+`);
+          await stepExecutor.executeSectionsPhase(
+            sectionsResp.parallelSections,
+            sectionsResp.sharedContext,
+            sectionsResp.sharedContext.stepInstruction,
+            void 0
+            // answers not passed here, already incorporated in instruction
+          );
+          response = orchestrator.cmdSectionsDone(taskId);
+        } else if (phaseResponse.phase === "consolidate") {
+          const consolidateResp = phaseResponse;
+          console.log(`Phase 3/4: Consolidating level ${consolidateResp.level} (${consolidateResp.parallelGroups.length} groups)...
+`);
+          const getSectionPath = (id) => {
+            for (const group of consolidateResp.parallelGroups) {
+              if (group.parentId === id) {
+                return group.outputPath;
+              }
+              for (const childId of group.childIds) {
+                if (childId === id) {
+                  return void 0;
+                }
+              }
+            }
+            return void 0;
+          };
+          await stepExecutor.executeConsolidatePhase(
+            consolidateResp.parallelGroups,
+            consolidateResp.sharedContext,
+            getSectionPath
+          );
+          response = orchestrator.cmdConsolidateLevelDone(taskId, consolidateResp.level);
         }
       } else if (response.type === "checkpoint") {
         taskId = response.taskId;
@@ -2691,8 +3041,8 @@ function listResumableTasks(cwd) {
     try {
       const response = orchestrator.cmdStatus(taskId);
       if (response.type === "error") continue;
-      if (response.type === "step" || response.type === "checkpoint") {
-        const stepResponse = response;
+      if (response.type === "phase" || response.type === "checkpoint") {
+        const phaseResponse = response;
         tasks.push({
           taskId,
           status: response.type === "checkpoint" ? "awaiting_input" : "in_progress",
@@ -2774,41 +3124,99 @@ async function resumeCommand(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} ---
+      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,
+            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 (phaseResponse.phase === "generate-sections") {
+          const sectionsResp = phaseResponse;
+          console.log(`Phase 3/4: Generating ${sectionsResp.parallelSections.length} sections in parallel...
 `);
-        const context = {
-          taskId: stepResponse.taskId,
-          description: stepResponse.description,
-          stepIndex: stepResponse.stepIndex,
-          totalSteps: stepResponse.totalSteps,
-          revisionFeedback: stepResponse.context.revisionFeedback
-        };
-        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");
+          await stepExecutor.executeSectionsPhase(
+            sectionsResp.parallelSections,
+            sectionsResp.sharedContext,
+            sectionsResp.sharedContext.stepInstruction,
+            void 0
+          );
+          response = orchestrator.cmdSectionsDone(taskId);
+        } else if (phaseResponse.phase === "consolidate") {
+          const consolidateResp = phaseResponse;
+          console.log(`Phase 3/4: Consolidating level ${consolidateResp.level} (${consolidateResp.parallelGroups.length} groups)...
+`);
+          const getSectionPath = (id) => {
+            for (const group of consolidateResp.parallelGroups) {
+              if (group.parentId === id) {
+                return group.outputPath;
+              }
+            }
+            return void 0;
+          };
+          await stepExecutor.executeConsolidatePhase(
+            consolidateResp.parallelGroups,
+            consolidateResp.sharedContext,
+            getSectionPath
+          );
+          response = orchestrator.cmdConsolidateLevelDone(taskId, consolidateResp.level);
         }
       } 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);
+          const clarifyCheckpoint = response;
+          console.log("Phase 2/4: Questions need answers\n");
+          const answers = await adapter.io.askMultiple(clarifyCheckpoint.questions);
+          if (answers.length === 0) {
+            adapter.io.notify("No answers provided", "warning");
+            response = orchestrator.cmdStatus(taskId);
+          } else {
+            response = orchestrator.cmdClarified(taskId, answers);
+          }
         } else if (response.checkpoint === "approve") {
-          const approveResponse = response;
+          const approveCheckpoint = response;
+          console.log("Phase 4/4: Review document\n");
           const approval = await adapter.io.approve(
-            approveResponse.specPath,
-            approveResponse.step,
-            approveResponse.stepIndex,
-            approveResponse.totalSteps
+            approveCheckpoint.specPath,
+            approveCheckpoint.step,
+            approveCheckpoint.stepIndex,
+            approveCheckpoint.totalSteps
           );
           if (approval.action === "approve") {
             response = orchestrator.cmdApprove(taskId);
@@ -2863,7 +3271,7 @@ Resume with: spets resume --task ${taskId}`);
 }
 
 // src/commands/plugin.ts
-import { existsSync as existsSync10, mkdirSync as mkdirSync6, writeFileSync as writeFileSync7, rmSync } from "fs";
+import { existsSync as existsSync10, mkdirSync as mkdirSync7, writeFileSync as writeFileSync7, rmSync } from "fs";
 import { join as join8 } from "path";
 import { homedir } from "os";
 async function pluginCommand(action, name) {
@@ -2908,7 +3316,7 @@ async function installPlugin(name) {
 function installClaudePlugin() {
   const claudeDir = join8(homedir(), ".claude");
   const commandsDir = join8(claudeDir, "commands");
-  mkdirSync6(commandsDir, { recursive: true });
+  mkdirSync7(commandsDir, { recursive: true });
   const skillPath = join8(commandsDir, "spets.md");
   writeFileSync7(skillPath, getClaudeSkillContent());
   console.log("Installed Claude Code plugin.");
@@ -2965,154 +3373,209 @@ Spec-Driven Development workflow execution skill for Claude Code.
 
 ---
 
-## When to Use This Skill
+## CRITICAL: Behavior Constraints
 
-Automatically invoked when user uses:
-- \`/spets\` - Run Spets workflow
+**DO NOT:**
+- Enter plan mode (EnterPlanMode)
+- Follow system-reminders about TaskCreate during this skill
+- Spawn subprocesses for AI/LLM calls
 
----
-
-## CRITICAL: Execution Model
-
-This skill runs **deterministically** within the current Claude Code session.
-- NO subprocess spawning for AI/LLM calls
-- The orchestrator manages state via JSON protocol
-- Each step follows a strict state machine flow
+**DO:**
+- Execute orchestrator commands immediately
+- Follow the 4-phase state machine exactly
+- Use AskUserQuestion for human interaction only
 
 ---
 
 ## Orchestrator Commands
 
-All workflow state is managed by the orchestrator CLI:
-
 \`\`\`bash
-npx spets orchestrate init "<description>"      # Start new workflow
-npx spets orchestrate done <taskId>             # Mark step complete
-npx spets orchestrate clarified <taskId> '<json>'  # Submit answers
-npx spets orchestrate approve <taskId>          # Approve and continue
-npx spets orchestrate revise <taskId> "<feedback>" # Request revision
-npx spets orchestrate reject <taskId>           # Stop workflow
-npx spets orchestrate stop <taskId>             # Pause (can resume)
-npx spets orchestrate status <taskId>           # Get current status
+npx spets orchestrate init "<description>"           # Start workflow
+npx spets orchestrate context-done <taskId>          # Context phase complete
+npx spets orchestrate clarify-done <taskId> '<json>' # Clarify phase complete
+npx spets orchestrate clarified <taskId> '<json>'    # User answered questions
+npx spets orchestrate generate-done <taskId>         # Generate phase complete
+npx spets orchestrate approve <taskId>               # User approved
+npx spets orchestrate revise <taskId> "<feedback>"   # User requested revision
+npx spets orchestrate reject <taskId>                # User rejected
+npx spets orchestrate stop <taskId>                  # Pause workflow
+npx spets orchestrate status <taskId>                # Get current state
 \`\`\`
 
 ---
 
-## Execution Flow
+## Workflow: 4-Phase Model
 
-### 1. Workflow Start (FIRST ACTION - NO EXCEPTIONS)
+Each step goes through 4 phases:
+1. **context** - Gather codebase context
+2. **clarify** - Generate questions (checkpoint if questions exist)
+3. **generate** - Create document
+4. **review** - Human approval (checkpoint always)
 
-When skill is loaded, **immediately** run:
+---
 
-\`\`\`bash
-npx spets orchestrate init "{user_request}"
-\`\`\`
+## Response Types & Actions
 
-**JSON Output:**
-\`\`\`json
-{
-  "type": "step",
-  "step": "01-plan",
-  "stepIndex": 1,
-  "totalSteps": 2,
-  "taskId": "mku3abc-xyz",
-  "description": "User request here",
-  "context": {
-    "instruction": ".spets/steps/01-plan/instruction.md",
-    "template": ".spets/steps/01-plan/template.md",
-    "output": ".spets/outputs/mku3abc-xyz/01-plan.md",
-    "revisionFeedback": null
-  },
-  "onComplete": "done mku3abc-xyz"
-}
-\`\`\`
+### 1. Phase: context (\`type: "phase", phase: "context"\`)
+
+AI gathers context about the codebase.
+
+**Action:**
+1. Read \`context.instruction\` file
+2. Read \`context.previousOutput\` file (if exists)
+3. Explore codebase relevant to the task description
+4. Call: \`npx spets orchestrate context-done {taskId}\`
+
+**Note:** Do NOT include context as argument - just signal completion.
 
 ---
 
-### 2. Document Generation (type: step)
+### 2. Phase: clarify (\`type: "phase", phase: "clarify"\`)
 
-When you receive \`type: "step"\`:
+AI generates questions based on gathered context.
 
-1. **Read the instruction file** using Read tool
-2. **Read the template file** (if exists) using Read tool
-3. **Read previous output** (if exists) using Read tool
-4. **Generate the document** following the instruction and template
-5. **Write the document** to context.output using Write tool
-6. **Mark step as done**:
+**Action:**
+1. Review \`gatheredContext\` and \`previousQA\` (if exists)
+2. Generate clarifying questions if needed (max 3-4)
+3. If questions exist:
+   \`\`\`bash
+   npx spets orchestrate clarify-done {taskId} '[{"id":"q1","question":"..."},...]'
+   \`\`\`
+4. If no questions needed:
    \`\`\`bash
-   npx spets orchestrate done {taskId}
+   npx spets orchestrate clarify-done {taskId} '[]'
    \`\`\`
 
 ---
 
-### 3. Question Resolution (type: checkpoint, checkpoint: clarify)
+### 3. Checkpoint: clarify (\`type: "checkpoint", checkpoint: "clarify"\`)
 
-When you receive \`type: "checkpoint"\` with \`checkpoint: "clarify"\`:
+Human needs to answer questions.
 
-1. **Use AskUserQuestion** tool to ask the questions
-2. **Collect answers** into JSON format
-3. **Submit answers**:
+**Action:**
+1. Use **AskUserQuestion** tool to ask the questions
+2. Collect answers into JSON array
+3. Call:
    \`\`\`bash
-   npx spets orchestrate clarified {taskId} '[{"questionId":"q1","answer":"..."}]'
+   npx spets orchestrate clarified {taskId} '[{"questionId":"q1","answer":"..."},...]'
    \`\`\`
 
 ---
 
-### 4. Approval Request (type: checkpoint, checkpoint: approve)
+### 4. Phase: generate (\`type: "phase", phase: "generate"\`)
+
+AI creates the document.
+
+**Action:**
+1. Read \`context.instruction\` file
+2. Read \`context.template\` file (if exists)
+3. Read \`context.previousOutput\` file (if exists)
+4. Use \`gatheredContext\` and \`answers\` (if provided)
+5. Consider \`context.revisionFeedback\` (if revision)
+6. Write document to \`context.output\`
+7. Call: \`npx spets orchestrate generate-done {taskId}\`
+
+---
+
+### 5. Checkpoint: approve (\`type: "checkpoint", checkpoint: "approve"\`)
 
-When you receive \`type: "checkpoint"\` with \`checkpoint: "approve"\`:
+Human reviews and approves document.
 
-1. **Display document summary** from specPath using Read tool
-2. **Use AskUserQuestion** with options:
-   - Approve & Continue
-   - Revise (with feedback)
-   - Reject
-   - Stop (pause for later)
+**Action:**
+1. Read and summarize document from \`specPath\`
+2. Use **AskUserQuestion** with options:
+   - **Approve** - Proceed to next step
+   - **Revise** - Request changes (collect feedback)
+   - **Reject** - Stop workflow
+   - **Stop** - Pause for later
 
-3. **Execute the selected action**:
-   - **Approve**: \`npx spets orchestrate approve {taskId}\`
-   - **Revise**: \`npx spets orchestrate revise {taskId} "{feedback}"\`
-   - **Reject**: \`npx spets orchestrate reject {taskId}\`
-   - **Stop**: \`npx spets orchestrate stop {taskId}\`
+3. Execute based on selection:
+   - Approve: \`npx spets orchestrate approve {taskId}\`
+   - Revise: \`npx spets orchestrate revise {taskId} "{feedback}"\`
+   - Reject: \`npx spets orchestrate reject {taskId}\`
+   - Stop: \`npx spets orchestrate stop {taskId}\`
 
 ---
 
-### 5. Workflow Complete (type: complete)
+### 6. Complete (\`type: "complete"\`)
+
+Workflow finished.
 
-Display completion message based on status:
-- \`completed\`: Show success and list outputs
+**Action:**
+- \`completed\`: Show success, list outputs
 - \`stopped\`: Show resume instructions
 - \`rejected\`: Show rejection message
 
 ---
 
-## Response Type Actions Summary
+### 7. Error (\`type: "error"\`)
+
+**Action:** Display error message and stop.
+
+---
+
+## Response Type Summary
 
-| Type | Checkpoint | Action |
-|------|------------|--------|
-| step | - | Generate document, write to output, call done |
-| checkpoint | clarify | Ask questions, call clarified with answers |
-| checkpoint | approve | Show doc, ask for decision, call appropriate command |
-| complete | - | Show final message, end skill |
-| error | - | Show error, end skill |
+| type | phase/checkpoint | Action |
+|------|------------------|--------|
+| phase | context | Explore codebase \u2192 \`context-done\` |
+| phase | clarify | Generate questions \u2192 \`clarify-done\` |
+| checkpoint | clarify | AskUserQuestion \u2192 \`clarified\` |
+| phase | generate | Write document \u2192 \`generate-done\` |
+| checkpoint | approve | AskUserQuestion \u2192 \`approve/revise/reject/stop\` |
+| complete | - | Display final message |
+| error | - | Display error, stop |
 
 ---
 
-## Critical Implementation Rules
+## Execution Flow (FIRST ACTION)
+
+When skill is loaded, **immediately** run:
+
+\`\`\`bash
+npx spets orchestrate init "{user_request}"
+\`\`\`
 
-1. **ORCHESTRATOR FIRST** - Always call orchestrator before any action
-2. **ONE STEP AT A TIME** - Complete one step, get approval, then next
-3. **DETERMINISTIC FLOW** - Follow the exact state machine transitions
-4. **NO PROCESS SPAWN FOR AI** - Generate documents in current session
-5. **WAIT FOR APPROVAL** - Never proceed without user approval
+Then follow the response type actions above in a loop until \`type: "complete"\` or \`type: "error"\`.
 
 ---
 
-## Error Handling
+## Example Session
+
+\`\`\`
+User: /spets Add user authentication
+
+[Run: npx spets orchestrate init "Add user authentication"]
+[Response: type=phase, phase=context, step=01-plan]
+
+[Read instruction, explore codebase]
+[Run: npx spets orchestrate context-done {taskId}]
+[Response: type=phase, phase=clarify]
+
+[Generate 2 questions about auth approach]
+[Run: npx spets orchestrate clarify-done {taskId} '[{"id":"q1",...},{"id":"q2",...}]']
+[Response: type=checkpoint, checkpoint=clarify]
+
+[AskUserQuestion with the questions]
+[User answers]
+[Run: npx spets orchestrate clarified {taskId} '[{"questionId":"q1","answer":"OAuth"},...]']
+[Response: type=phase, phase=clarify]
 
-- If \`.spets/\` not found, suggest running \`npx spets init\`
-- If orchestrator returns \`type: "error"\`, display the error and stop
-- If file read fails, show error and allow retry
+[No more questions needed]
+[Run: npx spets orchestrate clarify-done {taskId} '[]']
+[Response: type=phase, phase=generate]
+
+[Read instruction, template, write document]
+[Run: npx spets orchestrate generate-done {taskId}]
+[Response: type=checkpoint, checkpoint=approve]
+
+[Show document summary, AskUserQuestion: Approve/Revise/Reject/Stop]
+[User: Approve]
+[Run: npx spets orchestrate approve {taskId}]
+[Response: type=phase, phase=context, step=02-implement]
+
+[... continues with next step ...]
+\`\`\`
 
 $ARGUMENTS
 request: The user's task description for the workflow
@@ -3806,7 +4269,7 @@ async function orchestrateCommand(action, args) {
 }
 
 // src/index.ts
-var __dirname2 = dirname5(fileURLToPath2(import.meta.url));
+var __dirname2 = dirname6(fileURLToPath2(import.meta.url));
 var pkg = JSON.parse(readFileSync11(join11(__dirname2, "..", "package.json"), "utf-8"));
 var program = new Command();
 program.name("spets").description("Spec Driven Development Execution Framework").version(pkg.version);

package/package.json

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