speccrew 0.7.26 → 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-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.26",
+  "version": "0.7.27",
   "description": "Spec-Driven Development toolkit for AI-powered IDEs",
   "author": "charlesmu99",
   "repository": {