speccrew 0.7.25 → 0.7.27

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

@@ -112,9 +112,11 @@ When Worker loads a skill (via `skill_name` or `skill_path` parameter):
 **If `skill_path` or `skill_name` is provided:**
 1. If `skill_path` is provided, use it directly; otherwise use Skill Discovery
 2. If Skill file does not exist, immediately report error
-3. If `context` parameters exist, substitute them into placeholders in the Skill
-4. Strictly execute according to the workflow defined in the Skill
-5. Complete the task and output results
+3. **Read SKILL.md** to understand skill overview, constraints, and templates
+4. **Read workflow.agentflow.xml** — this is the AUTHORITATIVE execution definition
+5. If `context` parameters exist, substitute them into placeholders
+6. **Execute blocks defined in workflow.agentflow.xml sequentially** (top-to-bottom, announcing each block)
+7. Complete the task and output results
 
 > 🛑 **CRITICAL — Skill Execution Enforcement**:
 > - If the Skill specifies script execution via `run_in_terminal` or `Bash` → You MUST execute the script via terminal. DO NOT substitute with manual file creation.
@@ -122,6 +124,23 @@ When Worker loads a skill (via `skill_name` or `skill_path` parameter):
 > - If the Skill contains MANDATORY/FORBIDDEN constraints → You MUST follow them strictly.
 > - DO NOT improvise alternative execution paths. If a step fails, report the error — do not attempt workarounds.
 
+### MANDATORY: XML Workflow Loading Protocol
+
+When executing any Skill that contains `workflow.agentflow.xml`:
+
+1. **SKILL.md is METADATA ONLY** — it provides overview, constraints, and template references. It is NOT the execution plan.
+2. **workflow.agentflow.xml is the AUTHORITATIVE execution plan** — Worker MUST read this file and execute its blocks in sequential document order.
+3. **FORBIDDEN**: Starting task execution based solely on SKILL.md without reading workflow.agentflow.xml.
+4. **FORBIDDEN**: Summarizing or paraphrasing the workflow — execute blocks exactly as defined.
+5. **FORBIDDEN**: Skipping, reordering, or merging blocks.
+
+**Execution sequence:**
+```
+Read SKILL.md → Read workflow.agentflow.xml → Execute blocks in XML order → Report results
+```
+
+If workflow.agentflow.xml does not exist in the skill directory, fall back to SKILL.md-based execution.
+
 ### XML Workflow Block Announcement Protocol
 
 When executing a Skill that uses XML workflow format (`<workflow>` root element), you MUST follow the Block Execution Announcement Protocol defined in `docs/rules/agentflow-spec.md`:
@@ -211,10 +230,14 @@ When the task fails or is blocked, output:
 **MUST DO:**
 - If `skill_name` is provided, MUST use Skill Discovery to resolve the full path and strictly follow the Skill definition
 - If `skill_name` is provided but Skill file does not exist, immediately report error
+- If Skill directory contains workflow.agentflow.xml, MUST read it and execute blocks in sequential order — this is the authoritative execution plan
+- MUST announce each XML block before execution using the Block Announcement Protocol
 - Only process the single task assigned to the current Worker
 
 **MUST NOT DO:**
 - Do not skip or ignore a provided Skill file
+- Do not execute tasks based solely on SKILL.md when workflow.agentflow.xml exists — the XML workflow is authoritative
+- Do not skip reading workflow.agentflow.xml even if SKILL.md seems sufficient
 - Do not actively modify code beyond the task scope
 - Do not overstep to handle other tasks
 - Do not assume context information not provided

package/.speccrew/skills/speccrew-pm-phase0-init/SKILL.md

@@ -31,6 +31,12 @@ Applies workspace initialization principles:
 - Progress tracking via WORKFLOW-PROGRESS.json
 - Checkpoint recovery for session continuity
 
+## Templates Used
+
+| Template | Path | Purpose |
+|----------|------|---------|
+| WORKFLOW-PROGRESS | `templates/WORKFLOW-PROGRESS-TEMPLATE.json` | Standard workflow progress tracking with 7 predefined stages |
+
 ## Output Deliverables
 
 | Deliverable | Path | Description |
@@ -68,9 +74,15 @@ Applies workspace initialization principles:
 - Compute all path variables as absolute paths
 - Check for active iteration before creating new one
 - Copy requirement document to iteration's 00.docs directory
+- Create EXACTLY two subdirectories: `00.docs/` (original requirement documents) and `01.product-requirement/` (PRD and clarification outputs)
+- Initialize `WORKFLOW-PROGRESS.json` from `WORKFLOW-PROGRESS-TEMPLATE.json` template — stage names MUST match template exactly (01_prd, 02_feature_design, etc.)
 
 **Must not do:**
 - Manually create WORKFLOW-PROGRESS.json via Write/Edit tools
 - Skip checkpoint recovery check
 - Use relative paths in Worker dispatches
 - Create iteration directory without proper naming convention
+- Pre-create directories for later phases (`02.feature-design/`, `03.system-design/`, `04.development/`, `05.deployment/`, `06.system-test/`, `07.delivery/`) — each phase creates its own directory when needed
+- Invent directory names not defined in `workspace-structure.md`
+- Manually write WORKFLOW-PROGRESS.json content — MUST use template + update-progress.js script
+- Invent custom stage names (e.g., phase0_initialization, phase1_requirement_analysis) — use template-defined names only

package/.speccrew/skills/speccrew-pm-phase0-init/templates/WORKFLOW-PROGRESS-TEMPLATE.json

@@ -0,0 +1,56 @@
+{
+  "created_at": "{created_at}",
+  "updated_at": "{updated_at}",
+  "current_stage": null,
+  "stages": {
+    "01_prd": {
+      "status": "pending",
+      "started_at": null,
+      "completed_at": null,
+      "confirmed_at": null,
+      "output": null
+    },
+    "02_feature_design": {
+      "status": "pending",
+      "started_at": null,
+      "completed_at": null,
+      "confirmed_at": null,
+      "output": null
+    },
+    "03_system_design": {
+      "status": "pending",
+      "started_at": null,
+      "completed_at": null,
+      "confirmed_at": null,
+      "output": null
+    },
+    "04_development": {
+      "status": "pending",
+      "started_at": null,
+      "completed_at": null,
+      "confirmed_at": null,
+      "output": null
+    },
+    "05_deployment": {
+      "status": "pending",
+      "started_at": null,
+      "completed_at": null,
+      "confirmed_at": null,
+      "output": null
+    },
+    "06_system_test": {
+      "status": "pending",
+      "started_at": null,
+      "completed_at": null,
+      "confirmed_at": null,
+      "output": null
+    },
+    "07_delivery": {
+      "status": "pending",
+      "started_at": null,
+      "completed_at": null,
+      "confirmed_at": null,
+      "output": null
+    }
+  }
+}

package/.speccrew/skills/speccrew-pm-phase0-init/workflow.agentflow.xml

@@ -19,6 +19,8 @@
     <field name="text">ALL WORKFLOW-PROGRESS.json operations MUST use update-progress.js script</field>
     <field name="text">ALL path variables MUST be absolute paths</field>
     <field name="text">Check for active iteration before creating new one</field>
+    <field name="text">Phase 0 MUST create EXACTLY TWO subdirectories: 00.docs and 01.product-requirement</field>
+    <field name="text">FORBIDDEN: Pre-creating directories for later phases (02.feature-design, 03.system-design, 04.development, etc.). Each phase creates its own directory when needed.</field>
   </block>
 
   <block type="rule" id="R2" level="forbidden" desc="Phase 0 Forbidden Actions">
@@ -118,7 +120,24 @@
         <block type="task" id="P0-1-B9" action="run-script" status="pending" desc="Copy requirement document to iteration">
           <field name="command">Copy-Item "${user_requirement}" "${iteration_path}/00.docs/" -ErrorAction SilentlyContinue</field>
         </block>
-        
+                
+        <!-- Step 2.7: Load WORKFLOW-PROGRESS template -->
+        <block type="task" id="P0-1-B9A" action="read-file" status="pending" desc="Load WORKFLOW-PROGRESS template">
+          <field name="path" value="${skill_path}/templates/WORKFLOW-PROGRESS-TEMPLATE.json"/>
+          <field name="output" var="workflow_progress_template"/>
+        </block>
+                
+        <!-- Step 2.8: Generate initial WORKFLOW-PROGRESS.json from template -->
+        <block type="task" id="P0-1-B9B" action="generate" status="pending" desc="Create WORKFLOW-PROGRESS.json from template">
+          <field name="template" value="${workflow_progress_template}"/>
+          <field name="output_path" value="${iteration_path}/WORKFLOW-PROGRESS.json"/>
+          <field name="vars">
+            - created_at: ${current_timestamp}
+            - updated_at: ${current_timestamp}
+          </field>
+          <field name="output" var="workflow_progress_path"/>
+        </block>
+                
         <!-- Step 0.1.1: Initialize WORKFLOW-PROGRESS.json -->
         <block type="task" id="P0-1-B10" action="run-script" status="pending" desc="Initialize WORKFLOW-PROGRESS.json via script">
           <!-- MANDATORY: Use update-progress.js script -->

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

@@ -134,7 +134,21 @@
         <field name="output" var="skill_definition"/>
       </block>
       <block type="event" id="E8" action="log" desc="加载技能">📄 Loaded skill: ${resolved_skill_path}</block>
+            
+      <!-- MANDATORY: Load XML Workflow Definition -->
+      <block type="rule" id="R-WORKFLOW-FIRST" level="mandatory" desc="XML workflow is the authoritative execution definition">
+        <field name="text">MANDATORY: workflow.agentflow.xml is the AUTHORITATIVE execution definition. SKILL.md is supplementary context only.</field>
+        <field name="text">Worker MUST read workflow.agentflow.xml BEFORE starting any task execution.</field>
+        <field name="text">Worker MUST execute ONLY the blocks defined in workflow.agentflow.xml, in sequential document order.</field>
+        <field name="text">FORBIDDEN: Executing tasks based solely on SKILL.md description without reading the XML workflow.</field>
+      </block>
       
+      <block type="task" id="T6b" action="read-file" desc="MANDATORY: Read XML workflow definition">
+        <field name="path">${skill_path}/workflow.agentflow.xml</field>
+        <field name="output" var="skill_workflow_xml"/>
+      </block>
+      <block type="event" id="E8b" action="log" desc="Loaded XML workflow">📄 Loaded workflow: ${skill_path}/workflow.agentflow.xml — This is the AUTHORITATIVE execution plan. Execute blocks in document order.</block>
+            
       <!-- 加载 AgentFlow 规范 -->
       <block type="task" id="T7" action="read-file" desc="读取 AgentFlow 规范">
         <field name="path">${workspace_root}/speccrew-workspace/docs/rules/agentflow-spec.md</field>
@@ -143,10 +157,12 @@
       <block type="event" id="E9" action="log" desc="加载规范">📖 Loaded AgentFlow specification</block>
       
       <!-- 执行技能工作流 -->
-      <block type="task" id="T8" action="run-skill" desc="执行技能工作流">
+      <block type="task" id="T8" action="run-skill" desc="Execute skill workflow — follow XML blocks sequentially">
         <field name="skill">${resolved_skill_path}</field>
         <field name="context">${context}</field>
         <field name="skill_path">${skill_path}</field>
+        <field name="workflow_xml">${skill_workflow_xml}</field>
+        <field name="execution_mode">xml-block-sequential</field>
       </block>
       <field name="execution_status" value="success"/>
     </branch>

package/package.json

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