speccrew 0.6.40 → 0.6.42

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

@@ -75,18 +75,7 @@ You understand the complete AI engineering closed loop: **speccrew-pm → speccr
 
 # Workflow (XML Block Definition)
 
-<!--
-== Block Types ==
-input      : Workflow input parameters (required=mandatory, default=default value)
-output     : Workflow output results (from=data source variable)
-task       : Execution action (action: run-skill | run-script | dispatch-to-worker)
-gateway    : Conditional branch/gate (mode: exclusive | guard | parallel)
-loop       : Iterate collection (over=collection, as=current item)
-event      : Log/confirm/signal (action: log | confirm | signal)
-error-handler : Exception handling (try > catch > finally)
-checkpoint : Persistence milestone (name=checkpoint name, verify=verification condition)
-rule       : Constraint declaration (level: forbidden | mandatory | note)
--->
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `docs/rules/xml-workflow-spec.md`
 
 ```xml
 <workflow id="team-leader-main" status="pending">
@@ -190,16 +179,9 @@ rule       : Constraint declaration (level: forbidden | mandatory | note)
             <block type="rule" id="P05-R-TECHS" level="mandatory" desc="Parallel worker dispatch for techs">
               <field name="text">When techs-dispatch Stage 2 prepares task plans for multiple platforms, dispatch ALL platform workers IN PARALLEL — DO NOT execute sequentially</field>
             </block>
-            <block type="task" id="P05-B5" action="dispatch-to-worker" desc="Dispatch techs-dispatch via Task tool → speccrew-task-worker">
-              <field name="worker">speccrew-task-worker</field>
+            <block type="task" id="P05-B5" action="run-skill" desc="Leader directly invokes techs-dispatch as orchestration playbook">
               <field name="skill">speccrew-knowledge-techs-dispatch-xml</field>
-              <field name="instructions">
-CRITICAL: This skill MUST be invoked via Task tool creating a Worker Agent (speccrew-task-worker), NOT via direct Skill tool call.
-
-Use the Task tool to create a Worker Agent with the skill speccrew-knowledge-techs-dispatch-xml.
-The Worker Agent will load and execute the dispatch workflow autonomously.
-DO NOT call the Skill tool directly for speccrew-knowledge-* skills.
-              </field>
+              <field name="note">Leader directly calls this dispatch skill as an orchestration playbook. The dispatch skill defines the workflow; Leader dispatches downstream workers via Task tool → speccrew-task-worker for each stage.</field>
             </block>
           </branch>
           <branch test="${bizs_kb.exists} == false" name="Bizs Not Initialized">
@@ -207,16 +189,9 @@ DO NOT call the Skill tool directly for speccrew-knowledge-* skills.
             <block type="rule" id="P05-R-BIZS" level="mandatory" desc="Parallel worker dispatch for bizs">
               <field name="text">When bizs-dispatch prepares worker task plans, dispatch ALL workers IN PARALLEL per stage — DO NOT execute sequentially</field>
             </block>
-            <block type="task" id="P05-B6" action="dispatch-to-worker" desc="Dispatch bizs-dispatch via Task tool → speccrew-task-worker">
-              <field name="worker">speccrew-task-worker</field>
+            <block type="task" id="P05-B6" action="run-skill" desc="Leader directly invokes bizs-dispatch as orchestration playbook">
               <field name="skill">speccrew-knowledge-bizs-dispatch-xml</field>
-              <field name="instructions">
-CRITICAL: This skill MUST be invoked via Task tool creating a Worker Agent (speccrew-task-worker), NOT via direct Skill tool call.
-
-Use the Task tool to create a Worker Agent with the skill speccrew-knowledge-bizs-dispatch-xml.
-The Worker Agent will load and execute the dispatch workflow autonomously.
-DO NOT call the Skill tool directly for speccrew-knowledge-* skills.
-              </field>
+              <field name="note">Leader directly calls this dispatch skill as an orchestration playbook. The dispatch skill defines the workflow; Leader dispatches downstream workers via Task tool → speccrew-task-worker for each stage.</field>
             </block>
           </branch>
           <branch default="true" name="Knowledge Base Ready">
@@ -237,7 +212,7 @@ DO NOT call the Skill tool directly for speccrew-knowledge-* skills.
       <field name="text">DO NOT trigger business process Skills (PRD, Solution, Design, Dev) — these are loaded by corresponding role Agents</field>
       <field name="text">DO NOT handle business development requests (feature requirements, code modifications, bug fixes) — prompt user to talk directly to Qoder</field>
       <field name="text">DO NOT delete or modify WORKFLOW-PROGRESS.json (read-only)</field>
-      <field name="text">DO NOT call the Skill tool directly for speccrew-knowledge-* skills (speccrew-knowledge-bizs-dispatch-xml, speccrew-knowledge-techs-dispatch-xml) — MUST use Task tool to create speccrew-task-worker Agent for indirect execution</field>
+      <field name="text">dispatch skills (bizs-dispatch-xml, techs-dispatch-xml) MUST be called directly by Leader via Skill tool as orchestration playbooks. Downstream worker skills (identify-entries, init-features, ui-analyze, etc.) MUST be dispatched via Task tool → speccrew-task-worker.</field>
     </block>
 
     <block type="gateway" id="P1-G1" mode="exclusive" desc="Intent Recognition Routing">
@@ -257,16 +232,9 @@ DO NOT call the Skill tool directly for speccrew-knowledge-* skills.
           <field name="text">When bizs-dispatch prepares worker task plans for multiple features or platforms, dispatch ALL workers IN PARALLEL — DO NOT execute features or platforms sequentially one by one</field>
           <field name="text">Each Worker (analysis, graph, summarize) runs independently — dispatch all of them at once per stage, then monitor completion markers</field>
         </block>
-        <block type="task" id="P1-B3" action="dispatch-to-worker" status="pending" desc="Dispatch bizs-dispatch via Task tool → speccrew-task-worker">
-          <field name="worker">speccrew-task-worker</field>
+        <block type="task" id="P1-B3" action="run-skill" status="pending" desc="Leader directly invokes bizs-dispatch as orchestration playbook">
           <field name="skill">speccrew-knowledge-bizs-dispatch-xml</field>
-          <field name="instructions">
-CRITICAL: This skill MUST be invoked via Task tool creating a Worker Agent (speccrew-task-worker), NOT via direct Skill tool call.
-
-Use the Task tool to create a Worker Agent with the skill speccrew-knowledge-bizs-dispatch-xml.
-The Worker Agent will load and execute the dispatch workflow autonomously.
-DO NOT call the Skill tool directly for speccrew-knowledge-* skills.
-          </field>
+          <field name="note">Leader directly calls this dispatch skill as an orchestration playbook. The dispatch skill defines the workflow; Leader dispatches downstream workers via Task tool → speccrew-task-worker for each stage.</field>
         </block>
       </branch>
       <branch test="${intent} == 'knowledge_techs'" name="Techs Knowledge Base">
@@ -274,16 +242,9 @@ DO NOT call the Skill tool directly for speccrew-knowledge-* skills.
           <field name="text">When techs-dispatch Stage 2 prepares task plans for multiple platforms, dispatch ALL platform workers IN PARALLEL using concurrent task dispatch — DO NOT execute platforms sequentially one by one</field>
           <field name="text">Each platform worker (techs-generate-conventions, techs-generate-ui-style) runs independently — dispatch all of them at once, then monitor completion markers</field>
         </block>
-        <block type="task" id="P1-B4" action="dispatch-to-worker" status="pending" desc="Dispatch techs-dispatch via Task tool → speccrew-task-worker">
-          <field name="worker">speccrew-task-worker</field>
+        <block type="task" id="P1-B4" action="run-skill" status="pending" desc="Leader directly invokes techs-dispatch as orchestration playbook">
           <field name="skill">speccrew-knowledge-techs-dispatch-xml</field>
-          <field name="instructions">
-CRITICAL: This skill MUST be invoked via Task tool creating a Worker Agent (speccrew-task-worker), NOT via direct Skill tool call.
-
-Use the Task tool to create a Worker Agent with the skill speccrew-knowledge-techs-dispatch-xml.
-The Worker Agent will load and execute the dispatch workflow autonomously.
-DO NOT call the Skill tool directly for speccrew-knowledge-* skills.
-          </field>
+          <field name="note">Leader directly calls this dispatch skill as an orchestration playbook. The dispatch skill defines the workflow; Leader dispatches downstream workers via Task tool → speccrew-task-worker for each stage.</field>
         </block>
       </branch>
 

package/.speccrew/skills/speccrew-knowledge-bizs-api-analyze-xml/SKILL.md

@@ -105,18 +105,7 @@ Before executing the workflow, verify the following inputs:
 
 ## Workflow
 
-<!--
-== Block Types ==
-input      : Workflow input parameters (required=mandatory, default=default value)
-output     : Workflow output results (from=data source variable)
-task       : Execute action (action: run-skill | run-script | dispatch-to-worker)
-gateway    : Conditional branch/gate (mode: exclusive | guard | parallel)
-loop       : Iterate over collection (over=collection, as=current item)
-event      : Log/confirm/signal (action: log | confirm | signal)
-error-handler : Exception handling (try > catch > finally)
-checkpoint : Persistent milestone (name=checkpoint name, verify=verification condition)
-rule       : Constraint declaration (level: forbidden | mandatory | note)
--->
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `docs/rules/xml-workflow-spec.md`
 
 ```xml
 <workflow name="api-controller-analysis" version="1.0">

package/.speccrew/skills/speccrew-knowledge-bizs-api-graph-xml/SKILL.md

@@ -71,18 +71,7 @@ This skill operates in **strict sequential execution mode**:
 
 ## Workflow
 
-<!--
-== Block Types ==
-input      : Workflow input parameters (required=mandatory, default=default value)
-output     : Workflow output results (from=data source variable)
-task       : Execute action (action: run-skill | run-script | dispatch-to-worker)
-gateway    : Conditional branch/gate (mode: exclusive | guard | parallel)
-loop       : Iterate over collection (over=collection, as=current item)
-event      : Log/confirm/signal (action: log | confirm | signal)
-error-handler : Exception handling (try > catch > finally)
-checkpoint : Persistent milestone (name=checkpoint name, verify=verification condition)
-rule       : Constraint declaration (level: forbidden | mandatory | note)
--->
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `docs/rules/xml-workflow-spec.md`
 
 ```xml
 <workflow name="api-knowledge-graph-construction" version="1.0">

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

@@ -10,24 +10,29 @@ Orchestrate **bizs knowledge base generation** with a 5-stage pipeline using **X
 
 ## Invocation Method
 
-**CRITICAL**: This skill MUST be invoked via Task tool → speccrew-task-worker, NOT via direct Skill tool call.
+**CRITICAL**: This skill is an **orchestration playbook** — it MUST be loaded directly by Team Leader via Skill tool (NOT via Worker Agent).
 
 ```
-Correct: Use Task tool to create speccrew-task-worker with this skill
-Incorrect: Use Skill tool to call this skill directly
+Correct: Leader uses Skill tool to load this playbook directly
+Incorrect: Dispatch this skill to speccrew-task-worker
 ```
 
-**Why?** This skill requires run_in_terminal capability for script execution, which Worker Agents possess but direct Skill invocations may not support correctly. The Task tool creates a dedicated Worker Agent (speccrew-task-worker) that loads and executes this workflow autonomously.
+**Why?** This skill defines the orchestration workflow and prepares task plans for downstream workers. The Team Leader reads this playbook and dispatches individual worker tasks via Task tool → speccrew-task-worker for each stage.
 
 **Correct Invocation Pattern**:
 ```xml
-<block type="task" action="dispatch-to-worker" desc="Dispatch bizs-dispatch via Task tool">
-  <field name="worker">speccrew-task-worker</field>
+<block type="task" action="run-skill" desc="Leader directly invokes bizs-dispatch as orchestration playbook">
   <field name="skill">speccrew-knowledge-bizs-dispatch-xml</field>
-  <field name="instructions">Execute the bizs knowledge base generation pipeline.</field>
+  <field name="note">Leader directly calls this dispatch skill as an orchestration playbook. The dispatch skill defines the workflow; Leader dispatches downstream workers via Task tool → speccrew-task-worker for each stage.</field>
 </block>
 ```
 
+**Worker Dispatch Rule**:
+- Dispatch skills (bizs-dispatch-xml, techs-dispatch-xml): Leader calls directly via Skill tool
+- Downstream worker skills (identify-entries, init-features, ui-analyze, module-summarize, etc.): Leader dispatches via Task tool → speccrew-task-worker
+
+**FORBIDDEN**: Worker Agents MUST NOT execute this dispatch skill. If a Worker Agent loads this skill, it must report error and abort.
+
 ## Quick Reference — Execution Flow
 
 ```
@@ -80,20 +85,7 @@ Stage 4: System Summary
 ## XML Workflow Definition
 
 <workflow id="bizs-dispatch-main" status="pending" version="1.0" desc="bizs knowledge base generation 5-stage pipeline">
-  <!--
-  == Block Types ==
-  input      : Workflow input parameters (required=mandatory, default=default value)
-  output     : Workflow output results (from=data source variable)
-  task       : Execute action (action: run-skill | run-script | dispatch-to-worker)
-  gateway    : Conditional branch/gate (mode: exclusive | guard | parallel)
-  loop       : Iterate over collection (over=collection, as=current item)
-  event      : Log/confirm/signal (action: log | confirm | signal)
-  error-handler : Exception handling (try > catch > finally)
-  checkpoint : Persistent milestone (name=checkpoint name, verify=verification condition)
-  rule       : Constraint declaration (level: forbidden | mandatory | note)
-  == Field ==
-  field      : Parameter/variable/output (name=param name, var=bind variable, value=value)
-  -->
+  > **REQUIRED**: Before executing this workflow, read the XML workflow specification: `docs/rules/xml-workflow-spec.md`
 
   <!-- ============================================================
        Input Parameters Definition
@@ -114,6 +106,15 @@ Stage 4: System Summary
     <field name="completed_dir" required="true" type="string" desc="Marker file output directory for Worker results (absolute path required)"/>
   </block>
 
+  <!-- ============================================================
+       Global Invocation Rules
+       ============================================================ -->
+  <block type="rule" id="GLOBAL-R-INVOCATION" level="forbidden" desc="Invocation constraints — NEVER violate">
+    <field name="text">This skill is an ORCHESTRATION PLAYBOOK — it MUST be loaded directly by Team Leader via Skill tool</field>
+    <field name="text">Worker Agents MUST NOT execute this dispatch skill — if loaded by a Worker, report error and abort</field>
+    <field name="text">Downstream worker skills (identify-entries, init-features, ui-analyze, module-summarize, etc.) MUST be dispatched via Task tool → speccrew-task-worker</field>
+  </block>
+
   <!-- ============================================================
        Global Continuous Execution Rules
        ============================================================ -->

package/.speccrew/skills/speccrew-knowledge-bizs-identify-entries-xml/SKILL.md

@@ -38,18 +38,7 @@ For each platform, generates:
 
 ## Workflow
 
-<!--
-== Block Types ==
-input      : Workflow input parameters (required=mandatory, default=default value)
-output     : Workflow output results (from=data source variable)
-task       : Execute action (action: run-skill | run-script | dispatch-to-worker)
-gateway    : Conditional branch/gate (mode: exclusive | guard | parallel)
-loop       : Iterate over collection (over=collection, as=current item)
-event      : Log/confirm/signal (action: log | confirm | signal)
-error-handler : Exception handling (try > catch > finally)
-checkpoint : Persistent milestone (name=checkpoint name, verify=verification condition)
-rule       : Constraint declaration (level: forbidden | mandatory | note)
--->
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `docs/rules/xml-workflow-spec.md`
 
 <workflow>
 

package/.speccrew/skills/speccrew-knowledge-bizs-ui-analyze-xml/SKILL.md

@@ -76,18 +76,7 @@ Analyze one specific UI feature from source code, extract business functionality
 
 ## Workflow
 
-<!--
-== Block Types ==
-input      : Workflow input parameters (required=mandatory, default=default value)
-output     : Workflow output results (from=data source variable)
-task       : Execute action (action: run-skill | run-script | dispatch-to-worker)
-gateway    : Conditional branch/gate (mode: exclusive | guard | parallel)
-loop       : Iterate over collection (over=collection, as=current item)
-event      : Log/confirm/signal (action: log | confirm | signal)
-error-handler : Exception handling (try > catch > finally)
-checkpoint : Persistent milestone (name=checkpoint name, verify=verification condition)
-rule       : Constraint declaration (level: forbidden | mandatory | note)
--->
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `docs/rules/xml-workflow-spec.md`
 
 ```xml
 <workflow name="ui-feature-analysis" version="1.0">

package/.speccrew/skills/speccrew-knowledge-bizs-ui-graph-xml/SKILL.md

@@ -44,18 +44,7 @@ This skill automatically adapts to the user's input language. All documentation
 
 ## Workflow
 
-<!--
-== Block Types ==
-input      : Workflow input parameters (required=mandatory, default=default value)
-output     : Workflow output results (from=data source variable)
-task       : Execute action (action: run-skill | run-script | dispatch-to-worker)
-gateway    : Conditional branch/gate (mode: exclusive | guard | parallel)
-loop       : Iterate over collection (over=collection, as=current item)
-event      : Log/confirm/signal (action: log | confirm | signal)
-error-handler : Exception handling (try > catch > finally)
-checkpoint : Persistent milestone (name=checkpoint name, verify=verification condition)
-rule       : Constraint declaration (level: forbidden | mandatory | note)
--->
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `docs/rules/xml-workflow-spec.md`
 
 ```xml
 <workflow name="ui-knowledge-graph-construction" version="1.0">

package/.speccrew/skills/speccrew-knowledge-bizs-ui-style-extract-xml/SKILL.md

@@ -68,18 +68,7 @@ Extract and aggregate **UI design patterns** from bizs pipeline analyzed feature
 
 ## Workflow
 
-<!--
-== Block Types ==
-input      : Workflow input parameters (required=mandatory, default=default value)
-output     : Workflow output results (from=data source variable)
-task       : Execute action (action: run-skill | run-script | dispatch-to-worker)
-gateway    : Conditional branch/gate (mode: exclusive | guard | parallel)
-loop       : Iterate over collection (over=collection, as=current item)
-event      : Log/confirm/signal (action: log | confirm | signal)
-error-handler : Exception handling (try > catch > finally)
-checkpoint : Persistent milestone (name=checkpoint name, verify=verification condition)
-rule       : Constraint declaration (level: forbidden | mandatory | note)
--->
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `docs/rules/xml-workflow-spec.md`
 
 <workflow>
 

package/.speccrew/skills/speccrew-knowledge-module-summarize-xml/SKILL.md

@@ -51,18 +51,7 @@ flowchart TD
     Step6 --> End([End])
 ```
 
-<!--
-== Block Types ==
-input      : Workflow input parameters (required=mandatory, default=default value)
-output     : Workflow output results (from=data source variable)
-task       : Execute action (action: run-skill | run-script | dispatch-to-worker)
-gateway    : Conditional branch/gate (mode: exclusive | guard | parallel)
-loop       : Iterate over collection (over=collection, as=current item)
-event      : Log/confirm/signal (action: log | confirm | signal)
-error-handler : Exception handling (try > catch > finally)
-checkpoint : Persistent milestone (name=checkpoint name, verify=verification condition)
-rule       : Constraint declaration (level: forbidden | mandatory | note)
--->
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `docs/rules/xml-workflow-spec.md`
 
 <workflow>
   <!-- Input Block: Define workflow inputs -->

package/.speccrew/skills/speccrew-knowledge-system-summarize-xml/SKILL.md

@@ -58,18 +58,7 @@ flowchart TD
     Step8 --> End([End])
 ```
 
-<!--
-== Block Types ==
-input      : Workflow input parameters (required=mandatory, default=default value)
-output     : Workflow output results (from=data source variable)
-task       : Execute action (action: run-skill | run-script | dispatch-to-worker)
-gateway    : Conditional branch/gate (mode: exclusive | guard | parallel)
-loop       : Iterate over collection (over=collection, as=current item)
-event      : Log/confirm/signal (action: log | confirm | signal)
-error-handler : Exception handling (try > catch > finally)
-checkpoint : Persistent milestone (name=checkpoint name, verify=verification condition)
-rule       : Constraint declaration (level: forbidden | mandatory | note)
--->
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `docs/rules/xml-workflow-spec.md`
 
 <workflow>
   <!-- Input Block: Define workflow inputs -->

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

@@ -10,24 +10,29 @@ Orchestrate **techs knowledge base generation** with a 3-stage pipeline using **
 
 ## Invocation Method
 
-**CRITICAL**: This skill MUST be invoked via Task tool → speccrew-task-worker, NOT via direct Skill tool call.
+**CRITICAL**: This skill is an **orchestration playbook** — it MUST be loaded directly by Team Leader via Skill tool (NOT via Worker Agent).
 
 ```
-Correct: Use Task tool to create speccrew-task-worker with this skill
-Incorrect: Use Skill tool to call this skill directly
+Correct: Leader uses Skill tool to load this playbook directly
+Incorrect: Dispatch this skill to speccrew-task-worker
 ```
 
-**Why?** This skill requires run_in_terminal capability for script execution, which Worker Agents possess but direct Skill invocations may not support correctly. The Task tool creates a dedicated Worker Agent (speccrew-task-worker) that loads and executes this workflow autonomously.
+**Why?** This skill defines the orchestration workflow and prepares task plans for downstream workers. The Team Leader reads this playbook and dispatches individual worker tasks via Task tool → speccrew-task-worker for each stage.
 
 **Correct Invocation Pattern**:
 ```xml
-<block type="task" action="dispatch-to-worker" desc="Dispatch techs-dispatch via Task tool">
-  <field name="worker">speccrew-task-worker</field>
+<block type="task" action="run-skill" desc="Leader directly invokes techs-dispatch as orchestration playbook">
   <field name="skill">speccrew-knowledge-techs-dispatch-xml</field>
-  <field name="instructions">Execute the techs knowledge base generation pipeline.</field>
+  <field name="note">Leader directly calls this dispatch skill as an orchestration playbook. The dispatch skill defines the workflow; Leader dispatches downstream workers via Task tool → speccrew-task-worker for each stage.</field>
 </block>
 ```
 
+**Worker Dispatch Rule**:
+- Dispatch skills (bizs-dispatch-xml, techs-dispatch-xml): Leader calls directly via Skill tool
+- Downstream worker skills (techs-init, techs-generate-conventions, techs-generate-ui-style, etc.): Leader dispatches via Task tool → speccrew-task-worker
+
+**FORBIDDEN**: Worker Agents MUST NOT execute this dispatch skill. If a Worker Agent loads this skill, it must report error and abort.
+
 ## Quick Reference — Execution Flow
 
 ```
@@ -99,21 +104,9 @@ Read `speccrew-workspace/docs/configs/platform-mapping.json` for standardized pl
 
 ## XML Workflow Definition
 
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `docs/rules/xml-workflow-spec.md`
+
 <workflow id="techs-dispatch-main" status="pending" version="1.0" desc="techs knowledge base generation 3-stage pipeline">
-  <!--
-  == Block Types ==
-  input      : Workflow input parameters (required=mandatory, default=default value)
-  output     : Workflow output results (from=data source variable)
-  task       : Execute action (action: run-skill | run-script | dispatch-to-worker)
-  gateway    : Conditional branch/gate (mode: exclusive | guard | parallel)
-  loop       : Iterate over collection (over=collection, as=current item)
-  event      : Log/confirm/signal (action: log | confirm | signal)
-  error-handler : Exception handling (try > catch > finally)
-  checkpoint : Persistent milestone (name=checkpoint name, verify=verification condition)
-  rule       : Constraint declaration (level: forbidden | mandatory | note)
-  == Field ==
-  field      : Parameter/variable/output (name=param name, var=bind variable, value=value)
-  -->
 
   <!-- ============================================================
        Input Parameters Definition
@@ -127,6 +120,15 @@ Read `speccrew-workspace/docs/configs/platform-mapping.json` for standardized pl
     <field name="ide_skills_dir" required="true" type="string" desc="Absolute path to IDE skills directory (e.g., .qoder/skills, .cursor/skills)"/>
   </block>
 
+  <!-- ============================================================
+       Global Invocation Rules
+       ============================================================ -->
+  <block type="rule" id="GLOBAL-R-INVOCATION" level="forbidden" desc="Invocation constraints — NEVER violate">
+    <field name="text">This skill is an ORCHESTRATION PLAYBOOK — it MUST be loaded directly by Team Leader via Skill tool</field>
+    <field name="text">Worker Agents MUST NOT execute this dispatch skill — if loaded by a Worker, report error and abort</field>
+    <field name="text">Downstream worker skills (techs-init, techs-generate-conventions, techs-generate-ui-style, etc.) MUST be dispatched via Task tool → speccrew-task-worker</field>
+  </block>
+
   <!-- ============================================================
        Global Continuous Execution Rules
        ============================================================ -->

package/.speccrew/skills/speccrew-knowledge-techs-generate-conventions-xml/SKILL.md

@@ -72,18 +72,7 @@ Generate the following documents in `{{output_path}}/`:
 
 ## Workflow
 
-<!--
-== Block Types Schema ==
-input      : Workflow input parameters (required=mandatory, default=default value)
-output     : Workflow output results (from=data source variable)
-task       : Execute action (action: run-skill | run-script | dispatch-to-worker)
-gateway    : Conditional branch/gate (mode: exclusive | guard | parallel)
-loop       : Iterate over collection (over=collection, as=current item)
-event      : Log/confirm/signal (action: log | confirm | signal)
-error-handler : Exception handling (try > catch > finally)
-checkpoint : Persistent milestone (name=checkpoint name, verify=verification condition)
-rule       : Constraint declaration (level: forbidden | mandatory | note)
--->
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `docs/rules/xml-workflow-spec.md`
 
 ```xml
 <workflow name="platform-conventions-generation" version="1.0">

package/.speccrew/skills/speccrew-knowledge-techs-generate-quality-xml/SKILL.md

@@ -34,20 +34,7 @@ Worker Agent (speccrew-task-worker)
 ## XML Workflow Definition
 
 <workflow id="techs-quality-check" status="pending" version="1.0" desc="Quality assurance for tech documentation">
-  <!--
-  == Block Types ==
-  input      : Workflow input parameters (required=mandatory, default=default value)
-  output     : Workflow output results (from=data source variable)
-  task       : Execute action (action: run-skill | run-script | dispatch-to-worker)
-  gateway    : Conditional branch/gate (mode: exclusive | guard | parallel)
-  loop       : Iterate over collection (over=collection, as=current item)
-  event      : Log/confirm/signal (action: log | confirm | signal)
-  error-handler : Exception handling (try > catch > finally)
-  checkpoint : Persistent milestone (name=checkpoint name, verify=verification condition)
-  rule       : Constraint declaration (level: forbidden | mandatory | note)
-  == Field ==
-  field      : Parameter/variable/output (name=param name, var=bind variable, value=value)
-  -->
+  > **REQUIRED**: Before executing this workflow, read the XML workflow specification: `docs/rules/xml-workflow-spec.md`
 
   <!-- ============================================================
        Input Parameters Definition

package/.speccrew/skills/speccrew-knowledge-techs-generate-ui-style-xml/SKILL.md

@@ -41,20 +41,7 @@ Worker Agent (speccrew-task-worker)
 ## XML Workflow Definition
 
 <workflow id="techs-ui-style-generate" status="pending" version="1.0" desc="Generate UI style documents for frontend platform">
-  <!--
-  == Block Types ==
-  input      : Workflow input parameters (required=mandatory, default=default value)
-  output     : Workflow output results (from=data source variable)
-  task       : Execute action (action: run-skill | run-script | dispatch-to-worker)
-  gateway    : Conditional branch/gate (mode: exclusive | guard | parallel)
-  loop       : Iterate over collection (over=collection, as=current item)
-  event      : Log/confirm/signal (action: log | confirm | signal)
-  error-handler : Exception handling (try > catch > finally)
-  checkpoint : Persistent milestone (name=checkpoint name, verify=verification condition)
-  rule       : Constraint declaration (level: forbidden | mandatory | note)
-  == Field ==
-  field      : Parameter/variable/output (name=param name, var=bind variable, value=value)
-  -->
+  > **REQUIRED**: Before executing this workflow, read the XML workflow specification: `docs/rules/xml-workflow-spec.md`
 
   <!-- ============================================================
        Input Parameters Definition

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

@@ -38,18 +38,7 @@ Generate comprehensive technology documentation for a specific platform by analy
 
 ## Workflow
 
-<!--
-== Block Types ==
-input      : Workflow input parameters (required=mandatory, default=default value)
-output     : Workflow output results (from=data source variable)
-task       : Execute action (action: run-skill | run-script | dispatch-to-worker)
-gateway    : Conditional branch/gate (mode: exclusive | guard | parallel)
-loop       : Iterate over collection (over=collection, as=current item)
-event      : Log/confirm/signal (action: log | confirm | signal)
-error-handler : Exception handling (try > catch > finally)
-checkpoint : Persistent milestone (name=checkpoint name, verify=verification condition)
-rule       : Constraint declaration (level: forbidden | mandatory | note)
--->
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `docs/rules/xml-workflow-spec.md`
 
 <workflow>
 

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

@@ -48,18 +48,7 @@ Worker Agent (speccrew-task-worker)
 
 ## Workflow
 
-<!--
-== Block Types ==
-input      : Workflow input parameters (required=mandatory, default=default value)
-output     : Workflow output results (from=data source variable)
-task       : Execute action (action: run-skill | run-script | dispatch-to-worker)
-gateway    : Conditional branch/gate (mode: exclusive | guard | parallel)
-loop       : Iterate over collection (over=collection, as=current item)
-event      : Log/confirm/signal (action: log | confirm | signal)
-error-handler : Exception handling (try > catch > finally)
-checkpoint : Persistent milestone (name=checkpoint name, verify=verification condition)
-rule       : Constraint declaration (level: forbidden | mandatory | note)
--->
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `docs/rules/xml-workflow-spec.md`
 
 <workflow>
 

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

@@ -41,18 +41,7 @@ Worker Agent (speccrew-task-worker)
 
 ## Workflow
 
-<!--
-== Block Types ==
-input      : Workflow input parameters (required=mandatory, default=default value)
-output     : Workflow output results (from=data source variable)
-task       : Execute action (action: run-skill | run-script | dispatch-to-worker)
-gateway    : Conditional branch/gate (mode: exclusive | guard | parallel)
-loop       : Iterate over collection (over=collection, as=current item)
-event      : Log/confirm/signal (action: log | confirm | signal)
-error-handler : Exception handling (try > catch > finally)
-checkpoint : Persistent milestone (name=checkpoint name, verify=verification condition)
-rule       : Constraint declaration (level: forbidden | mandatory | note)
--->
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `docs/rules/xml-workflow-spec.md`
 
 <workflow>
 

package/package.json

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

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

@@ -0,0 +1,340 @@
+# XML Workflow Specification
+
+> This document defines the XML Block workflow format used in SpecCrew skill and agent definitions.
+> **MANDATORY**: Any agent or worker that encounters XML `<workflow>` blocks MUST read and understand this specification before execution.
+
+## Execution Model
+
+This is a **Blockly-style sequential workflow definition**:
+
+- Execute blocks **top-to-bottom in document order** within each `<sequence>`
+- Each `<block>` is one atomic execution unit — complete it fully before moving to the next
+- Do NOT skip, reorder, or selectively execute blocks unless a `<gateway>` directs otherwise
+- Nested blocks within a parent block execute in document order
+
+## Block Types
+
+### input
+
+Defines workflow input parameters. MUST be the first block in a workflow.
+
+```xml
+<block type="input" id="I1" desc="Workflow input parameters">
+  <field name="source_path" required="true" type="string" desc="Source code root directory"/>
+  <field name="platform_id" required="true" type="string" desc="Platform identifier, e.g. web-vue"/>
+  <field name="output_dir" required="false" type="string" default="${workspace}/output" desc="Output directory"/>
+</block>
+```
+
+- `required="true"`: Caller MUST provide this parameter
+- `default`: Used when `required="false"` and caller omits the value
+- Input fields automatically become workflow-scoped variables
+
+### output
+
+Defines workflow output results. MUST be the last block in a workflow.
+
+```xml
+<block type="output" id="O1" desc="Workflow output results">
+  <field name="matched_modules" from="${matcherResult.matched_modules}" type="array" desc="Matched module list"/>
+  <field name="execution_path" from="${executionPath}" type="string" desc="Execution path A or B"/>
+</block>
+```
+
+- `from`: Reference to the variable containing the output value
+
+### task
+
+Executes an action. The primary execution block.
+
+**Action Types:**
+
+| Action | Purpose | Required Fields |
+|--------|---------|-----------------|
+| `run-skill` | Invoke a skill | `<field name="skill">` |
+| `run-script` | Execute a command | `<field name="command">` |
+| `dispatch-to-worker` | Delegate to a worker agent | `<field name="agent">` |
+| `analyze` | Perform analysis | Context fields |
+| `generate` | Generate content | Output path |
+| `read-file` | Read file content | `<field name="path">` |
+| `write-file` | Write file content | `<field name="path">`, content |
+
+**Examples:**
+
+```xml
+<!-- Run a skill -->
+<block type="task" id="B1" action="run-skill" desc="Execute module matcher skill">
+  <field name="skill">speccrew-knowledge-module-matcher</field>
+  <field name="source_path" value="${source_path}"/>
+  <field name="output" var="matcherResult"/>
+</block>
+
+<!-- Run a script -->
+<block type="task" id="B2" action="run-script" desc="Check knowledge directory">
+  <field name="command">node scripts/check-knowledge.js --dir ${knowledgeDir}</field>
+  <field name="output" var="checkResult"/>
+</block>
+
+<!-- Dispatch to worker -->
+<block type="task" id="B3" action="dispatch-to-worker" desc="Dispatch worker for analysis">
+  <field name="agent">speccrew-task-worker</field>
+  <field name="skill_path">${task.skill_path}/SKILL.md</field>
+  <field name="context">{"module": "${task.module}"}</field>
+</block>
+```
+
+### gateway
+
+Conditional branching and guard checks.
+
+**Modes:**
+
+| Mode | Behavior |
+|------|----------|
+| `exclusive` | Execute ONLY the first matching `<branch>` |
+| `guard` | Continue if `test` passes, otherwise execute `fail-action` |
+| `parallel` | Execute ALL branches concurrently |
+
+**Exclusive Gateway:**
+
+```xml
+<block type="gateway" id="G1" mode="exclusive" desc="Select execution path">
+  <branch test="${knowledgeStatus.exists} == true" name="Incremental Update">
+    <block type="task" action="run-skill" desc="Run incremental sync">...</block>
+  </branch>
+  <branch test="${knowledgeStatus.exists} == false" name="Full Init">
+    <block type="task" action="run-skill" desc="Run full initialization">...</block>
+  </branch>
+  <branch default="true" name="Fallback">
+    <block type="event" action="log" level="error">Unknown state</block>
+  </branch>
+</block>
+```
+
+**Guard Gateway:**
+
+```xml
+<block type="gateway" id="G2" mode="guard" 
+        test="${matcherResult.matched_modules.length} > 0"
+        fail-action="stop" 
+        desc="Validate at least one module matched">
+  <field name="message">No modules matched. Check source path and platform config.</field>
+</block>
+```
+
+- `fail-action`: `stop` | `retry` | `skip` | `fallback`
+
+**Parallel Gateway:**
+
+```xml
+<block type="gateway" id="G3" mode="parallel" desc="Execute all branches concurrently">
+  <branch name="Analyze users">
+    <block type="task" action="dispatch-to-worker">...</block>
+  </branch>
+  <branch name="Analyze orders">
+    <block type="task" action="dispatch-to-worker">...</block>
+  </branch>
+</block>
+```
+
+### loop
+
+Iterate over a collection.
+
+```xml
+<block type="loop" id="L1" over="${tasks}" as="task" 
+        parallel="true" max-concurrency="5"
+        desc="Process each task">
+  <block type="task" action="dispatch-to-worker" desc="Dispatch worker for ${task.name}">
+    <field name="agent">speccrew-task-worker</field>
+    <field name="skill_path">${task.skill_path}/SKILL.md</field>
+  </block>
+</block>
+```
+
+- `over`: Collection variable to iterate (e.g., `${tasks}`)
+- `as`: Variable name for current item (e.g., `task` → use as `${task}`)
+- `parallel="true"`: Execute all iterations concurrently
+- `max-concurrency`: Limit concurrent executions
+
+### event
+
+Logging, confirmation, and signaling.
+
+```xml
+<!-- Log event -->
+<block type="event" action="log" level="info" desc="Log progress">
+  Processing ${tasks.length} tasks
+</block>
+
+<!-- Confirm event (pauses for user input) -->
+<block type="event" action="confirm" title="Confirm modules" type="yesno" desc="Wait for user confirmation">
+  <field name="preview">Matched ${matcherResult.matched_modules.length} modules. Continue?</field>
+  <on-confirm>
+    <field name="confirmed" value="true"/>
+  </on-confirm>
+  <on-cancel>
+    <field name="workflow.status" value="cancelled"/>
+  </on-cancel>
+</block>
+```
+
+- `action`: `log` | `confirm` | `signal`
+- `level` (for log): `debug` | `info` | `warn` | `error`
+
+### error-handler
+
+Try/catch/finally error handling.
+
+```xml
+<block type="error-handler" id="EH1" desc="Handle worker dispatch errors">
+  <try>
+    <block type="loop" over="${tasks}" as="task">
+      <block type="task" action="dispatch-to-worker">...</block>
+    </block>
+  </try>
+  <catch error-type="timeout">
+    <block type="event" action="log" level="error">Timeout: ${error.taskId}</block>
+  </catch>
+  <catch>
+    <block type="event" action="log" level="error">Unexpected: ${error.message}</block>
+  </catch>
+  <finally>
+    <block type="event" action="log" level="info">Batch completed</block>
+  </finally>
+</block>
+```
+
+### checkpoint
+
+Persist progress milestone. Supports resume-from-checkpoint.
+
+```xml
+<block type="checkpoint" id="CP1" name="matcher_completed" desc="Module matching done">
+  <field name="file" value="${progressFile}"/>
+  <field name="verify" value="${matcherResult.matched_modules.length} > 0"/>
+</block>
+```
+
+- `name`: Unique checkpoint identifier for the progress file
+- `verify`: Condition to evaluate; if true, checkpoint is marked as `passed`
+- During resume, skip all blocks until the first non-passed checkpoint
+
+### rule
+
+Declare constraints. NOT an action block — these are enforced continuously.
+
+**Levels:**
+
+| Level | Meaning |
+|-------|---------|
+| `forbidden` | MUST NOT do this. Violation causes immediate stop. |
+| `mandatory` | MUST do this. Required for correctness. |
+| `note` | Guidance hint. Recommended but not enforced. |
+
+```xml
+<!-- FORBIDDEN rules -->
+<block type="rule" id="R1" level="forbidden" desc="Phase 4 constraints">
+  <field name="text">DO NOT generate Sub-PRDs yourself — MUST dispatch Workers</field>
+  <field name="text">DO NOT use create_file to manually create progress JSON</field>
+  <field name="text">DO NOT fabricate timestamps — let scripts generate them</field>
+</block>
+
+<!-- MANDATORY rules -->
+<block type="rule" id="R2" level="mandatory" desc="Execution sequence gate">
+  <field name="text">MUST execute B2→B3→B4→B5 in order, no skipping</field>
+</block>
+```
+
+**Placement**: Put `<rule>` blocks directly before the steps they govern. This ensures the LLM "sees" the constraint when executing those steps.
+
+## Variable References
+
+Use `${variable_name}` syntax throughout block attributes and content.
+
+```xml
+<!-- Simple variable -->
+<field name="platform" value="${platform_id}"/>
+
+<!-- Object property -->
+<field name="count" value="${matcherResult.matched_modules.length}"/>
+
+<!-- Array index -->
+<field name="first" value="${matcherResult.matched_modules[0].name}"/>
+```
+
+**Built-in Variables:**
+
+| Variable | Description |
+|----------|-------------|
+| `${workspace}` | Workspace root directory |
+| `${platform}` | Current platform identifier |
+| `${timestamp}` | Current ISO timestamp |
+| `${workflow.id}` | Current workflow ID |
+| `${workflow.status}` | Current workflow status |
+
+## Common Patterns
+
+### Sequential Pipeline
+
+```xml
+<workflow id="pipeline" status="pending">
+  <block type="input" id="I1">...</block>
+  <sequence id="S1">
+    <block type="task" id="B1" action="run-skill">...</block>
+    <block type="task" id="B2" action="run-script">...</block>
+    <block type="task" id="B3" action="dispatch-to-worker">...</block>
+  </sequence>
+  <block type="output" id="O1">...</block>
+</workflow>
+```
+
+### Conditional Branching
+
+```xml
+<block type="gateway" mode="exclusive" desc="Route based on result">
+  <branch test="${result.count} > 10" name="Many items">
+    <block type="task" action="run-skill" desc="Batch process">...</block>
+  </branch>
+  <branch default="true" name="Few items">
+    <block type="task" action="run-skill" desc="Single process">...</block>
+  </branch>
+</block>
+```
+
+### Parallel Worker Dispatch
+
+```xml
+<block type="loop" over="${modules}" as="module" parallel="true" max-concurrency="5">
+  <block type="task" action="dispatch-to-worker" desc="Analyze ${module.name}">
+    <field name="agent">speccrew-analyzer</field>
+    <field name="context">{"module": "${module.name}"}</field>
+  </block>
+</block>
+```
+
+### Error Recovery
+
+```xml
+<block type="error-handler" desc="Robust processing">
+  <try>
+    <block type="task" action="run-skill" desc="Primary operation">...</block>
+  </try>
+  <catch error-type="timeout">
+    <block type="task" action="run-skill" desc="Fallback operation">...</block>
+  </catch>
+  <finally>
+    <block type="checkpoint" name="done" desc="Mark complete">...</block>
+  </finally>
+</block>
+```
+
+## 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