speccrew 0.7.24 → 0.7.26

package/.speccrew/agents/speccrew-task-worker.md

@@ -100,6 +100,13 @@ Receive from the calling Agent:
 
 If the skill file is not found, report an error with the attempted paths.
 
+### Skill Path Resolution
+
+When Worker loads a skill (via `skill_name` or `skill_path` parameter):
+1. Resolve the skill directory path (e.g., `.qoder/skills/speccrew-pm-requirement-clarify/`)
+2. Set `skill_path` variable to the resolved directory path (NOT the SKILL.md file path)
+3. This `skill_path` is passed to the skill's workflow execution context, enabling the skill to reference templates, scripts, and other resources within the skill directory using `${skill_path}/templates/...` syntax
+
 ### 3. Execute Task
 
 **If `skill_path` or `skill_name` is provided:**

package/.speccrew/skills/speccrew-pm-requirement-clarify/SKILL.md

@@ -35,10 +35,37 @@ Applies ISA-95 Stage 1 (Domain Description) for clarification:
 
 ## Templates Used
 
-| Template | Path | Purpose |
-|----------|------|---------|
-| Clarification Questions | `templates/CLARIFICATION-QUESTIONS-TEMPLATE.md` | Round-based questionnaire for user clarification |
-| Clarification Summary | `templates/CLARIFICATION-SUMMARY-TEMPLATE.md` | Final summary document with all Q&A and decisions |
+| Template | Path | When to Load | Purpose |
+|----------|------|-------------|----------|
+| Clarification Questions | `templates/CLARIFICATION-QUESTIONS-TEMPLATE.md` | **Inside Loop L1** (each round) | Round-based questionnaire for user clarification |
+| Clarification Summary | `templates/CLARIFICATION-SUMMARY-TEMPLATE.md` | **After G3 guard passes** (sufficiency_checks_passed == true) | Final summary document with all Q&A and decisions |
+
+> **CRITICAL**: These two templates are used in **separate phases**. NEVER load both templates at the same time.
+> - During the clarification loop: ONLY load `CLARIFICATION-QUESTIONS-TEMPLATE.md`
+> - After ALL sufficiency checks pass: ONLY then load `CLARIFICATION-SUMMARY-TEMPLATE.md`
+
+## Execution Flow (MANDATORY sequence)
+
+```
+Step 1: Read requirement document
+Step 2: Read system knowledge (if exists)
+Step 3: Determine complexity mode (simple/complex/auto-detect)
+Step 4: Initialize loop variables
+Step 5: Clarification Loop (both simple and complex modes):
+  5a. Load CLARIFICATION-QUESTIONS-TEMPLATE.md (ONLY this template)
+  5b. Generate .clarification-questions-round-{N}.md from template
+  5c. *** HARD STOP *** Wait for user to answer questions (user-confirm event)
+  5d. Read user's answered questions file
+  5e. Perform sufficiency checks (MUST have real user answers)
+  5f. If checks fail and rounds remain → back to 5a
+  5g. If checks pass → exit loop
+Step 6: Guard Gateway G3 (sufficiency_checks_passed == true required)
+  6a. Load CLARIFICATION-SUMMARY-TEMPLATE.md (ONLY now)
+  6b. Generate .clarification-summary.md from template
+  6c. Checkpoint: clarification complete
+```
+
+> **FORBIDDEN**: Skipping Step 5c (user-confirm), loading summary template during Step 5, or generating summary without user answers.
 
 ---
 

package/.speccrew/skills/speccrew-pm-requirement-clarify/workflow.agentflow.xml

@@ -86,19 +86,58 @@
     <!-- Step 5: Execute Clarification -->
     <block type="gateway" id="G2" mode="exclusive" desc="Execute clarification based on mode">
       <branch test="${complexity} == 'simple'" name="Simple Mode Clarification">
-        <block type="task" id="B6" action="analyze" desc="Simple mode: 1-3 key questions">
-          <field name="topics">
-            - What to change
-            - What the change is
-            - Business reason
-            - Acceptance criteria
+        <!-- Simple mode: 1 round of key clarification questions -->
+        <block type="rule" id="R-SIMPLE-TEMPLATE" level="mandatory" desc="Simple mode also uses template">
+          <field name="text">MANDATORY: Even in simple mode, clarification questions MUST be generated from CLARIFICATION-QUESTIONS-TEMPLATE.md template.</field>
+          <field name="text">Simple mode generates 1-3 key questions focusing on: scope, acceptance criteria, and business reason.</field>
+        </block>
+
+        <block type="task" id="B6-load-template" action="read-file" desc="Load clarification questions template for simple mode">
+          <field name="path" value="${skill_path}/templates/CLARIFICATION-QUESTIONS-TEMPLATE.md"/>
+          <field name="output" var="questions_template"/>
+        </block>
+
+        <block type="task" id="B6" action="generate" desc="Simple mode: generate 1-3 key clarification questions from template">
+          <field name="template" value="${questions_template}"/>
+          <field name="output_path" value="${iteration_path}/01.product-requirement/.clarification-questions-round-1.md"/>
+          <field name="vars">
+            - round_number: 1
+            - iteration_name: ${iteration_name}
+            - date: ${current_date}
+            - complexity_level: simple
+            - requirement_summary: ${requirement_summary}
           </field>
-          <field name="output" var="clarification_qa"/>
+          <field name="guidance">Simple mode: generate only 1-3 key questions focusing on scope boundaries, acceptance criteria, and business reason. Remove unused category sections from template.</field>
+          <field name="output" var="questions_file"/>
+        </block>
+
+        <block type="rule" id="R-SIMPLE-CONFIRM" level="mandatory" desc="User must answer even in simple mode">
+          <field name="text">MANDATORY: User-confirm event below is a HARD STOP. Worker MUST pause and wait for user response.</field>
+        </block>
+
+        <block type="event" id="E-SIMPLE-CONFIRM" action="user-confirm" desc="Wait for user to answer simple clarification questions">
+          <field name="prompt">📋 澄清问题已生成 (简单模式): ${questions_file}
+
+请：
+1. 查看澄清问题文件
+2. 在文件中填写您的答案
+3. 填写完成后确认继续</field>
+          <field name="skippable" value="false"/>
+        </block>
+
+        <block type="task" id="B6-read-answers" action="read-file" desc="Read user answers for simple mode">
+          <field name="path" value="${questions_file}"/>
+          <field name="output" var="answered_questions"/>
+        </block>
+
+        <block type="task" id="B6-mark-complete" action="set-var" desc="Mark simple mode clarification as complete">
+          <field name="sufficiency_checks_passed" value="true"/>
         </block>
       </branch>
       <branch test="${complexity} == 'complex'" name="Complex Mode Clarification">
         <!-- Clarification Loop -->
         <block type="loop" id="L1" condition="sufficiency_checks_passed == false AND round_number <= max_rounds" desc="Clarification rounds until sufficiency">
+          <!-- ========== PHASE A: Generate Questions (ONLY questions template loaded here) ========== -->
           <!-- MANDATORY: Template-based generation rule -->
           <block type="rule" id="R-TEMPLATE-GENERATION" level="mandatory" desc="Template-based generation is MANDATORY">
             <field name="text">MANDATORY: Clarification questions MUST be generated by loading the template file and performing variable substitution.</field>
@@ -125,6 +164,7 @@
             <field name="output" var="questions_file"/>
           </block>
 
+          <!-- ========== PHASE B: HARD STOP - Wait for User Answers ========== -->
           <!-- MANDATORY: User confirmation cannot be bypassed -->
           <block type="rule" id="R-USER-CONFIRM-MANDATORY" level="mandatory" desc="User-confirm events MUST pause Worker execution">
             <field name="text">MANDATORY: The following user-confirm event is a HARD STOP. Worker MUST pause and present the prompt to user.</field>
@@ -143,6 +183,7 @@
             <field name="skippable" value="false"/>
           </block>
 
+          <!-- ========== PHASE C: Read Answers and Check Sufficiency ========== -->
           <block type="task" id="B8" action="read-file" desc="Read answered questions">
             <field name="path" value="${questions_file}"/>
             <field name="output" var="answered_questions"/>
@@ -178,6 +219,16 @@
           <block type="task" id="B9-increment" action="set-var" desc="Increment round counter">
             <field name="round_number" value="${round_number + 1}"/>
           </block>
+          <!-- ========== END OF LOOP ITERATION - Summary template is NOT loaded here ========== -->
+        </block>
+      </branch>
+      <branch default="true" name="ERROR: Unknown Complexity">
+        <block type="task" id="B-COMPLEXITY-ERROR" action="set-variable" desc="Handle unknown complexity value">
+          <field name="error_type">UNKNOWN_COMPLEXITY</field>
+          <field name="error_message">Complexity mode could not be determined. Value: ${complexity}. Expected 'simple' or 'complex'.</field>
+        </block>
+        <block type="event" id="E-COMPLEXITY-ABORT" action="abort" desc="Abort: unknown complexity">
+          <field name="message">Cannot proceed: complexity mode is '${complexity}', expected 'simple' or 'complex'.</field>
         </block>
       </branch>
     </block>
@@ -194,6 +245,8 @@
     <!-- Step 6: Generate .clarification-summary.md (Guarded by G3) -->
     <block type="gateway" id="G3" mode="exclusive" desc="Guard: Only generate summary if sufficiency checks passed">
       <branch test="${sufficiency_checks_passed} == true" name="Sufficiency Passed - Generate Summary">
+        <!-- ========== SUMMARY GENERATION (Only reached when ALL sufficiency checks passed) ========== -->
+        <!-- NOTE: Summary template is loaded HERE, not in the loop above. This is intentional. -->
         <block type="task" id="B10-load-template" action="read-file" desc="Load summary template">
           <field name="path" value="${skill_path}/templates/CLARIFICATION-SUMMARY-TEMPLATE.md"/>
           <field name="output" var="summary_template"/>
@@ -223,10 +276,15 @@
           <field name="verify" value="file_exists(${summary_path})"/>
         </block>
       </branch>
-      <branch default="true" name="Sufficiency Failed - Exit with Error">
-        <block type="task" id="B-INSUFFICIENCY-EXIT" action="set-variable" desc="Set error status for insufficient clarification">
-          <field name="error_type">INSUFFICIENT_CLARIFICATION</field>
-          <field name="message">Requirement clarification did not achieve sufficiency. Worker exits and returns control to PM Agent.</field>
+      <branch default="true" name="Sufficiency Failed - Abort Workflow">
+        <block type="rule" id="R-ABORT-RULE" level="mandatory" desc="Abort when sufficiency failed">
+          <field name="text">MANDATORY: sufficiency_checks_passed is false. Worker MUST abort workflow immediately.</field>
+          <field name="text">DO NOT attempt to generate .clarification-summary.md.</field>
+          <field name="text">Return control to PM Agent with error status.</field>
+        </block>
+        <block type="event" id="E-INSUFFICIENCY-ABORT" action="abort" desc="Abort: sufficiency checks failed after all rounds">
+          <field name="message">Requirement clarification did not achieve sufficient clarity after ${round_number - 1} round(s). Returning control to PM Agent for user intervention.</field>
+          <field name="error_code">CLARIFICATION_INSUFFICIENT</field>
         </block>
       </branch>
     </block>

package/.speccrew/skills/speccrew-task-worker-execution/workflow.agentflow.xml

@@ -82,8 +82,24 @@
     </branch>
   </block>
 
-  <!-- === Phase 3: 执行任务 === -->
-  <block type="event" id="E5" action="log" desc="开始执行任务">📋 Phase 3: Execute Task</block>
+  <!-- === Phase 3: 设置 skill_path 变量 === -->
+  <block type="event" id="E5" action="log" desc="设置 skill_path 变量">📋 Phase 3: Set skill_path Variable</block>
+
+  <block type="gateway" id="G5b" mode="exclusive" desc="设置 skill_path 目录路径">
+    <branch test="${resolved_skill_path} != null" name="从 resolved_skill_path 推导">
+      <block type="task" id="T5b" action="run-script" desc="提取 skill 目录路径">
+        <field name="command">node -e "const path = require('path'); const skillFilePath = process.env.SKILL_FILE_PATH || '${resolved_skill_path}'; const skillDir = path.dirname(skillFilePath); console.log(skillDir);"</field>
+        <field name="output" var="skill_path"/>
+      </block>
+      <block type="event" id="E5b" action="log" desc="skill_path 已设置">📁 skill_path set to: ${skill_path}</block>
+    </branch>
+    <branch test="true" name="无 skill 路径">
+      <block type="event" id="E5c" action="log" desc="无 skill_path">ℹ️ No skill_path to set</block>
+    </branch>
+  </block>
+
+  <!-- === Phase 4: 执行任务 === -->
+  <block type="event" id="E6" action="log" desc="开始执行任务">📋 Phase 4: Execute Task</block>
 
   <block type="rule" id="R1" level="mandatory" desc="技能执行强制约束">
     如果技能指定通过 run_in_terminal 或 Bash 执行脚本 → 必须通过终端执行
@@ -130,13 +146,14 @@
       <block type="task" id="T8" action="run-skill" desc="执行技能工作流">
         <field name="skill">${resolved_skill_path}</field>
         <field name="context">${context}</field>
+        <field name="skill_path">${skill_path}</field>
       </block>
       <field name="execution_status" value="success"/>
     </branch>
   </block>
 
-  <!-- === Phase 4: 报告结果 === -->
-  <block type="event" id="E10" action="log" desc="开始报告结果">📋 Phase 4: Report Results</block>
+  <!-- === Phase 5: 报告结果 === -->
+  <block type="event" id="E10" action="log" desc="开始报告结果">📋 Phase 5: Report Results</block>
 
   <block type="gateway" id="G7" mode="exclusive" desc="选择报告格式">
     <branch test="${execution_status} == success" name="成功报告">
@@ -163,7 +180,7 @@
     </branch>
   </block>
 
-  <!-- === Phase 5: 完成报告输出 === -->
+  <!-- === Phase 6: 完成报告输出 === -->
   <block type="event" id="E11" action="log" desc="输出结构化完成报告">
 ## Task Completion Report
 - **Status**: ${status}

package/lib/commands/update.js

@@ -211,16 +211,18 @@ function updateSkillsRecursive(srcDir, destDir, stats, currentRelPath = '', ideC
     const relPath = currentRelPath ? path.join(currentRelPath, entry.name) : entry.name;
     
     if (entry.isDirectory()) {
-      // Only process directories with speccrew-* prefix
-      if (!isSpeccrewFile(entry.name)) continue;
-      
-      const dirStats = { added: 0, updated: 0 };
+      // Only check speccrew-* prefix at skills directory level (when currentRelPath is empty)
+      // Once inside a skill directory, all subdirectories should be processed unconditionally
+      if (!currentRelPath && !isSpeccrewFile(entry.name)) continue;
+          
       updateSkillsRecursive(srcPath, destPath, stats, relPath, ideConfig);
     } else {
-      // Files under speccrew-* directory
-      // Check if under speccrew-* parent directory
-      const parentDir = path.basename(srcDir);
-      if (!isSpeccrewFile(parentDir)) continue;
+      // Files - only check speccrew-* prefix at skills directory level
+      // Once inside a skill directory, all files should be processed unconditionally
+      if (!currentRelPath) {
+        const parentDir = path.basename(srcDir);
+        if (!isSpeccrewFile(parentDir)) continue;
+      }
       
       // Apply frontmatter transformation to SKILL.md files (if needed)
       const isSkillMd = entry.name === 'SKILL.md';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speccrew",
-  "version": "0.7.24",
+  "version": "0.7.26",
   "description": "Spec-Driven Development toolkit for AI-powered IDEs",
   "author": "charlesmu99",
   "repository": {