speccrew 0.6.51 → 0.6.53

package/.speccrew/agents/speccrew-team-leader-xml.md

@@ -77,7 +77,15 @@ You understand the complete AI engineering closed loop: **speccrew-pm → speccr
 
 > **REQUIRED**: Before executing this workflow, read the XML workflow specification: `speccrew-workspace/docs/rules/xml-workflow-spec.md`
 >
-> After reading the specification, parse the XML workflow below and **strictly execute each `<block>` in document order**. Every `<block type="task">` is a literal tool-call instruction — use the `action` attribute to determine which IDE tool to invoke, and pass the `<field name="command">` or `<field name="skill">` value **exactly as written**. Do NOT interpret the workflow as a goal description or improvise your own approach.
+> After reading the specification, parse the XML workflow below and **strictly execute each `<block>` in document order**. For EVERY block, you MUST announce it before execution:
+>
+> ```
+> 📋 Block [ID] (action=[action]) — [desc]
+> 🔧 Tool: [which IDE tool to call]
+> ✅ Result: [output or status]
+> ```
+>
+> Use the `action` attribute to determine which IDE tool to invoke, and pass the `<field name="command">` or `<field name="skill">` value **exactly as written**. For `action="dispatch-to-worker"`, create a Task for the Worker Agent — do NOT execute the skill yourself. Do NOT interpret the workflow as a goal description or improvise your own approach.
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>

package/.speccrew/skills/speccrew-knowledge-bizs-dispatch-xml/SKILL.md

@@ -8,15 +8,28 @@ tools: Read, Write, Task, Bash
 >
 > **Step 1**: Load XML workflow specification: `speccrew-workspace/docs/rules/xml-workflow-spec.md` — this defines all block types and action-to-tool mappings
 >
-> **Step 2**: Execute this SKILL.md's XML workflow **block by block in document order**:
-> - `action="run-script"` → Execute via **Terminal tool** (PowerShell/Bash)
-> - `action="run-skill"` → Invoke via **Skill tool** (do NOT manually read SKILL.md files or browse directories)
-> - `action="dispatch-to-worker"` → Create **Task** via **Task tool** for `speccrew-task-worker`
+> **Step 2**: Execute this SKILL.md's XML workflow **block by block in document order**. For EVERY block, you MUST follow this 3-step cycle:
+>
+> ```
+> 📋 Block [ID] (action=[action]) — [desc]
+> 🔧 Tool: [which IDE tool to call]
+> ✅ Result: [output or status]
+> ```
+>
+> Action-to-tool mapping:
+> - `action="run-script"` → Execute via **Terminal tool** (pass the `<field name="command">` value EXACTLY)
+> - `action="run-skill"` → Invoke via **Skill tool** (pass the `<field name="skill">` value EXACTLY)
+> - `action="dispatch-to-worker"` → Create **Task** via **Task tool** for `speccrew-task-worker` (Worker loads and executes the skill, NOT you)
 > - `action="confirm"` (event) → Present to user and wait for response
 >
 > **Step 3**: Execute ALL stages sequentially without pausing (only stop at explicit `<event action="confirm">` blocks)
 >
-> **FORBIDDEN**: Do NOT run terminal commands as substitute for Skill tool calls. Do NOT do Worker's job yourself. Do NOT skip blocks or improvise.
+> **FORBIDDEN**:
+> - Do NOT skip the block announcement format above — every block must be announced before execution
+> - Do NOT run terminal commands as substitute for Skill tool calls
+> - Do NOT do Worker's job yourself — when `action="dispatch-to-worker"`, create a Task and let Worker handle it
+> - Do NOT skip blocks or improvise your own commands
+> - Do NOT read a skill's SKILL.md file yourself — use the Skill tool which resolves paths automatically
 
 # Bizs Knowledge Dispatch (XML Block Version)
 

package/.speccrew/skills/speccrew-knowledge-techs-dispatch-xml/SKILL.md

@@ -8,15 +8,28 @@ tools: Read, Write, Task, Bash
 >
 > **Step 1**: Load XML workflow specification: `speccrew-workspace/docs/rules/xml-workflow-spec.md` — this defines all block types and action-to-tool mappings
 >
-> **Step 2**: Execute this SKILL.md's XML workflow **block by block in document order**:
-> - `action="run-script"` → Execute via **Terminal tool** (PowerShell/Bash)
-> - `action="run-skill"` → Invoke via **Skill tool** (do NOT manually read SKILL.md files or browse directories)
-> - `action="dispatch-to-worker"` → Create **Task** via **Task tool** for `speccrew-task-worker`
+> **Step 2**: Execute this SKILL.md's XML workflow **block by block in document order**. For EVERY block, you MUST follow this 3-step cycle:
+>
+> ```
+> 📋 Block [ID] (action=[action]) — [desc]
+> 🔧 Tool: [which IDE tool to call]
+> ✅ Result: [output or status]
+> ```
+>
+> Action-to-tool mapping:
+> - `action="run-script"` → Execute via **Terminal tool** (pass the `<field name="command">` value EXACTLY)
+> - `action="run-skill"` → Invoke via **Skill tool** (pass the `<field name="skill">` value EXACTLY)
+> - `action="dispatch-to-worker"` → Create **Task** via **Task tool** for `speccrew-task-worker` (Worker loads and executes the skill, NOT you)
 > - `action="confirm"` (event) → Present to user and wait for response
 >
 > **Step 3**: Execute ALL stages sequentially without pausing (only stop at explicit `<event action="confirm">` blocks)
 >
-> **FORBIDDEN**: Do NOT run terminal commands as substitute for Skill tool calls. Do NOT do Worker's job yourself. Do NOT skip blocks or improvise.
+> **FORBIDDEN**:
+> - Do NOT skip the block announcement format above — every block must be announced before execution
+> - Do NOT run terminal commands as substitute for Skill tool calls
+> - Do NOT do Worker's job yourself — when `action="dispatch-to-worker"`, create a Task and let Worker handle it
+> - Do NOT skip blocks or improvise your own commands
+> - Do NOT read a skill's SKILL.md file yourself — use the Skill tool which resolves paths automatically
 
 # Techs Knowledge Dispatch (XML Block Version)
 

package/package.json

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

package/workspace-template/docs/rules/xml-workflow-spec.md

@@ -390,6 +390,87 @@ When executing `<block type="task">` blocks, the `action` attribute determines w
 3. **`<loop parallel="true">` with `dispatch-to-worker`** — Create ALL worker tasks in ONE batch call, not sequentially. This enables true parallel execution.
 4. **Variable binding** — After a tool call completes, bind the result to the variable specified in `<field name="output" var="..."/>` for use in subsequent blocks.
 
+### Invocation Examples
+
+**Example 1: `action="run-script"` — Team Leader runs terminal command directly**
+
+Given this XML block:
+```xml
+<block type="task" id="S0-B4" action="run-script" desc="Generate platforms.json">
+  <field name="command">node scripts/generate-platforms.js</field>
+  <field name="output" var="platforms_file"/>
+</block>
+```
+
+Team Leader executes:
+```
+→ Call run_in_terminal(command="node scripts/generate-platforms.js")
+→ Store result in variable ${platforms_file}
+```
+
+**Example 2: `action="run-skill"` — Team Leader loads a Skill (dispatch playbook)**
+
+Given this XML block:
+```xml
+<block type="task" id="B3" action="run-skill" desc="Load dispatch playbook">
+  <field name="skill">speccrew-knowledge-bizs-dispatch-xml</field>
+</block>
+```
+
+Team Leader executes:
+```
+→ Call Skill(name="speccrew-knowledge-bizs-dispatch-xml")
+→ Read and execute the loaded workflow block-by-block
+```
+
+**Example 3: `action="dispatch-to-worker"` — Team Leader creates Task for Worker Agent**
+
+Given this XML block:
+```xml
+<block type="task" id="S1-B1" action="dispatch-to-worker" desc="Identify entry directories for backend">
+  <field name="agent">speccrew-task-worker</field>
+  <field name="skill">speccrew-knowledge-bizs-identify-entries-xml</field>
+  <field name="context_platform_id">${platform.platformId}</field>
+  <field name="context_source_path">${platform.sourcePath}</field>
+  <field name="output" var="entry_result"/>
+</block>
+```
+
+Team Leader executes:
+```
+→ Call Task tool to create a new task:
+    - Assign to: speccrew-task-worker
+    - Worker must call: Skill(name="speccrew-knowledge-bizs-identify-entries-xml")
+    - Pass context: platform_id=backend-system, source_path=d:/dev/project/backend
+→ Wait for Worker Agent to complete the task
+→ Store Worker's result in variable ${entry_result}
+```
+
+**CRITICAL**: When block says `action="dispatch-to-worker"`, Team Leader MUST NOT load the skill itself or execute it directly. Team Leader creates a Task, Worker Agent loads and executes the skill.
+
+**Example 4: `<loop parallel="true">` with `dispatch-to-worker` — Batch dispatch**
+
+Given this XML block:
+```xml
+<block type="loop" id="S1-L1" over="${platforms}" var="platform" parallel="true">
+  <block type="task" id="S1-B1" action="dispatch-to-worker" desc="Identify entries">
+    <field name="agent">speccrew-task-worker</field>
+    <field name="skill">speccrew-knowledge-bizs-identify-entries-xml</field>
+    <field name="context_platform_id">${platform.platformId}</field>
+  </block>
+</block>
+```
+
+Team Leader executes:
+```
+→ For each platform in ${platforms}, create a Task in ONE batch:
+    - Task 1: Worker runs identify-entries-xml for backend-system
+    - Task 2: Worker runs identify-entries-xml for frontend-web
+    - Task 3: Worker runs identify-entries-xml for mobile-app
+→ All 3 tasks run in parallel on Worker Agents
+→ Wait for all tasks to complete before proceeding
+```
+
 ## Execution Rules
 
 1. **NEVER skip a block** — execute every block in document order