speccrew 0.6.50 → 0.6.52

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

@@ -76,6 +76,8 @@ You understand the complete AI engineering closed loop: **speccrew-pm → speccr
 # Workflow (XML Block Definition)
 
 > **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.
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>

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

@@ -99,6 +99,8 @@ Stage 4: System Summary
 ## XML Workflow Definition
 
 > **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.
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>

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

@@ -119,6 +119,8 @@ Read `speccrew-workspace/docs/configs/platform-mapping.json` for standardized pl
 ## XML Workflow Definition
 
 > **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.
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>

package/package.json

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

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

@@ -390,12 +390,94 @@ 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
-2. **Read `rule` blocks as constraints** — check them continuously during execution
-3. **`checkpoint` blocks** = persist progress before continuing
-4. **`gateway mode="exclusive"`** = only execute the first matching branch
-5. **`loop parallel="true"`** = dispatch all iterations concurrently
-6. **`rule level="forbidden"`** = immediate stop if violated
-7. **Input/Output blocks** define the contract — respect required parameters
+2. **Literal execution** — each `<block type="task">` is a direct tool-call instruction, NOT a goal description. Pass `<field name="command">` values to the terminal **exactly as written**. Pass `<field name="skill">` values to the Skill tool **exactly as written**. Do NOT rephrase, combine, or improvise alternative commands.
+3. **Read `rule` blocks as constraints** — check them continuously during execution
+4. **`checkpoint` blocks** = persist progress before continuing
+5. **`gateway mode="exclusive"`** = only execute the first matching branch
+6. **`loop parallel="true"`** = dispatch all iterations concurrently
+7. **`rule level="forbidden"`** = immediate stop if violated
+8. **Input/Output blocks** define the contract — respect required parameters