speccrew 0.7.23 → 0.7.25

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

@@ -30,10 +30,18 @@ This agent MUST execute tasks continuously without unnecessary interruptions.
 
 ### When to Pause (ONLY these cases)
 
-1. CHECKPOINT gates defined in workflow (user confirmation required by design)
-2. Ambiguous requirements that genuinely need clarification
-3. Unrecoverable errors that prevent further progress
-4. Security-sensitive operations (e.g., deleting existing files)
+1. **Event blocks with user interaction** (HIGHEST PRIORITY):
+   - `<block type="event" action="user-confirm">` — MUST pause and present prompt to user, wait for explicit confirmation
+   - This applies even in automated dispatch scenarios — user-confirm events override Worker autonomy
+   - FORBIDDEN: Skipping, auto-confirming, or bypassing with reasoning like "automated execution scenario"
+
+2. CHECKPOINT gates defined in workflow (user confirmation required by design)
+
+3. Ambiguous requirements that genuinely need clarification
+
+4. Unrecoverable errors that prevent further progress
+
+5. Security-sensitive operations (e.g., deleting existing files)
 
 ### Batch Execution Behavior
 
@@ -92,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

@@ -86,7 +86,10 @@ Applies ISA-95 Stage 1 (Domain Description) for clarification:
 - Manually write JSON files
 - Auto-proceed to Phase 4 (PRD generation) without PM Agent's user confirmation gate
 - Auto-pass sufficiency checks without actual user answers
-- Write checkpoints in this Skill — checkpoints are managed by orchestration layer
+- **Checkpoint management is FORBIDDEN in this Skill**
+  - MUST NOT create, write, or modify `.checkpoints.json` or any checkpoint files
+  - Checkpoint write operations are the responsibility of the orchestration layer (PM Agent)
+  - After this Skill completes, PM Agent writes checkpoints ONLY after user confirmation is received
 
 ### MANDATORY: User Answer Verification Rule
 
@@ -95,6 +98,13 @@ Applies ISA-95 Stage 1 (Domain Description) for clarification:
 - Checkpoint writing is FORBIDDEN in this Skill — checkpoints are managed by the orchestration layer
 - The sufficiency check result is ONLY valid when based on real user-provided answers
 
+### CRITICAL: User Confirmation Event Enforcement
+
+1. **Event Block = Hard Stop**: Each `<block type="event" action="user-confirm">` (E-ROUND-CONFIRM) MUST trigger a pause. Worker MUST NOT proceed until user provides explicit confirmation.
+2. **No "Automated Scenario" Bypass**: Even in automated dispatch mode (speccrew-task-worker), `user-confirm` events override Worker autonomy. These are explicit user interaction gates, NOT internal automation points.
+3. **Template-Based Generation Only**: All clarification question files (`.clarification-questions-round-{N}.md`) MUST be generated using the loaded template (CLARIFICATION-QUESTIONS-TEMPLATE.md) with variable substitution. Freeform generation is FORBIDDEN.
+4. **Template-Based Summary Only**: The `.clarification-summary.md` MUST be generated using CLARIFICATION-SUMMARY-TEMPLATE.md with variable substitution. Freeform generation is FORBIDDEN.
+
 ### CRITICAL: Summary Generation Guard
 
 Worker MUST strictly enforce the following before generating `.clarification-summary.md`:

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

@@ -99,6 +99,13 @@
       <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">
+          <!-- 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>
+            <field name="text">FORBIDDEN: Freeform generation, manual writing, or creating clarification files without using the loaded template.</field>
+            <field name="text">The generated file must follow the template structure with all placeholders replaced by actual values.</field>
+          </block>
+
           <!-- Load Question Template -->
           <block type="task" id="B7-load-template" action="read-file" desc="Load clarification questions template">
             <field name="path" value="${skill_path}/templates/CLARIFICATION-QUESTIONS-TEMPLATE.md"/>
@@ -118,6 +125,13 @@
             <field name="output" var="questions_file"/>
           </block>
 
+          <!-- 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>
+            <field name="text">FORBIDDEN: Skipping, auto-confirming, or bypassing user-confirm events for ANY reason including "automated execution scenario".</field>
+            <field name="text">Worker MUST wait for explicit user response before proceeding to the next block.</field>
+          </block>
+
           <!-- MANDATORY: Wait for user to answer clarification questions -->
           <block type="event" id="E-ROUND-CONFIRM" action="user-confirm" desc="Wait for user to answer clarification questions">
             <field name="prompt">📋 第 ${round_number} 轮澄清问题已生成: ${questions_file}

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.23",
+  "version": "0.7.25",
   "description": "Spec-Driven Development toolkit for AI-powered IDEs",
   "author": "charlesmu99",
   "repository": {

package/workspace-template/docs/rules/agentflow-spec.md

@@ -184,6 +184,18 @@ Logging, confirmation, and signaling.
 - `action`: `log` | `confirm` | `signal`
 - `level` (for log): `debug` | `info` | `warn` | `error`
 
+#### User-Confirm Event Execution Rules (MANDATORY)
+
+When a Worker encounters `<block type="event" action="user-confirm">`:
+
+1. **MUST pause execution** — Stop all processing and present the prompt to the user
+2. **CANNOT be skipped or auto-confirmed** — Even if Worker considers the scenario "automated"
+3. **Applies to ALL execution modes** — Including dispatch-to-worker, batch processing, and automated scenarios
+4. **`skippable="false"` is absolute** — When set, no bypass mechanism is permitted under any circumstances
+5. **Variable preservation** — Before pausing, ensure all workflow variables are properly set for resumption
+
+`user-confirm` events represent **explicit user interaction gates** in the workflow. They exist to ensure human oversight at critical decision points and MUST NOT be optimized away.
+
 ### error-handler
 
 Try/catch/finally error handling.