speccrew 0.6.56 → 0.6.59

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

@@ -353,6 +353,21 @@ Before executing the workflow, verify the following inputs:
   </block>
   
   <!-- ==================== STEP 5A: COPY TEMPLATE TO DOCUMENT PATH ==================== -->
+  <!-- Document Output Path Rule -->
+  <block type="rule" id="R-DOCPATH" level="mandatory" desc="Document output path MUST use documentPath parameter">
+    <field name="text">
+      The output document file MUST be created at the EXACT path specified by ${documentPath} input parameter.
+      DO NOT use the template file name (e.g., FEATURE-DETAIL-TEMPLATE-*.md) as the output file name.
+      The documentPath already contains the correct target path including file name (e.g., speccrew-workspace/knowledges/bizs/backend-system/admin/cache/cache_controller.md).
+      Before creating the file, ensure the parent directory exists (create if necessary).
+    </field>
+  </block>
+
+  <!-- Ensure Document Output Directory Exists -->
+  <block type="task" id="B14a" action="run-script" desc="Ensure document output directory exists">
+    <field name="command">node -e "require('fs').mkdirSync(require('path').dirname('${documentPath}'), {recursive: true})"</field>
+  </block>
+
   <!-- Replace Top-Level Placeholders -->
   <block type="task" id="B14" action="replace-placeholders" desc="Replace template placeholders">
     <field name="template" value="${templateContent}"/>

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

@@ -278,13 +278,17 @@ Continue with knowledge base generation?
   <sequence id="S1a" name="Stage 1a: Entry Directory Recognition" status="pending" desc="Identify entry directories for each platform and classify into business modules">
     
     <block type="rule" id="S1a-R1" level="mandatory" desc="Stage 1a mandatory rules">
-      <field name="text">This stage is executed DIRECTLY by the dispatch agent (Leader), NOT delegated to a Worker Agent</field>
+      <field name="text">ALL platform entry directory recognition tasks MUST be dispatched IN PARALLEL — sequential execution is FORBIDDEN</field>
+      <field name="text">ALL Worker dispatch calls in S1a-L1 MUST be issued SIMULTANEOUSLY in a SINGLE orchestration turn</field>
+      <field name="text">DO NOT wait for any Worker to complete before dispatching the next Worker</field>
+      <field name="text">Dispatch all ${max_concurrent_workers} workers at once, then wait for ALL to complete</field>
+      <field name="text">Sequential one-by-one dispatch is STRICTLY FORBIDDEN</field>
     </block>
 
-    <block type="loop" id="S1a-L1" over="${platforms}" as="platform" desc="Iterate each platform to identify entry directories">
+    <block type="loop" id="S1a-L1" over="${platforms}" as="platform" parallel="true" max-concurrency="${max_concurrent_workers}" desc="Dispatch entry directory recognition for each platform IN PARALLEL">
       <!-- Step 1: Read source directory tree -->
-      <block type="task" id="S1a-B1" action="run-skill" status="pending" desc="Invoke entry identification Skill">
-        <field name="skill">speccrew-knowledge-bizs-identify-entries-xml</field>
+      <block type="task" id="S1a-B1" action="dispatch-to-worker" status="pending" desc="Dispatch entry identification to Worker">
+        <field name="worker">speccrew-knowledge-bizs-identify-entries-xml</field>
         <field name="source_path" value="${platform.sourcePath}"/>
         <field name="platform_id" value="${platform.platformId}"/>
         <field name="platform_type" value="${platform.platformType}"/>
@@ -317,11 +321,15 @@ Continue with knowledge base generation?
   <sequence id="S1b" name="Stage 1b: Generate Feature Inventory" status="pending" desc="Generate Feature inventory for each platform">
     
     <block type="rule" id="S1b-R1" level="mandatory" desc="Stage 1b mandatory rules">
-      <field name="text">This stage is executed DIRECTLY by the dispatch agent (Leader), NOT delegated to a Worker Agent</field>
+      <field name="text">ALL platform feature inventory generation tasks MUST be dispatched IN PARALLEL — sequential execution is FORBIDDEN</field>
+      <field name="text">ALL Worker dispatch calls in S1b-L1 MUST be issued SIMULTANEOUSLY in a SINGLE orchestration turn</field>
+      <field name="text">DO NOT wait for any Worker to complete before dispatching the next Worker</field>
+      <field name="text">Dispatch all ${max_concurrent_workers} workers at once, then wait for ALL to complete</field>
+      <field name="text">Sequential one-by-one dispatch is STRICTLY FORBIDDEN</field>
       <field name="text">Worker Agents do not have run_in_terminal capability, which is required for script execution</field>
     </block>
 
-    <block type="loop" id="S1b-L1" over="${platforms}" as="platform" desc="Generate Feature inventory for each platform">
+    <block type="loop" id="S1b-L1" over="${platforms}" as="platform" parallel="true" max-concurrency="${max_concurrent_workers}" desc="Generate Feature inventory for each platform IN PARALLEL">
       <!-- Step 1: Read platform mapping config -->
       <block type="task" id="S1b-B1" action="run-script" status="pending" desc="Read platform mapping config">
         <field name="command">node "${ide_skills_dir}/speccrew-knowledge-bizs-init-features/scripts/generate-inventory.js"</field>
@@ -422,6 +430,10 @@ Continue with knowledge base generation?
       <field name="text">MUST use batch-orchestrator for batch management — DO NOT manually track batches</field>
       <field name="text">MUST dispatch Workers for feature analysis — DO NOT analyze features yourself</field>
       <field name="text">ALL workers for the same stage MUST be dispatched in PARALLEL — sequential execution is FORBIDDEN</field>
+      <field name="text">ALL Worker dispatch calls in S2-L2 MUST be issued SIMULTANEOUSLY in a SINGLE orchestration turn</field>
+      <field name="text">DO NOT wait for any Worker to complete before dispatching the next Worker</field>
+      <field name="text">Dispatch all ${max_concurrent_workers} workers at once, then wait for ALL to complete</field>
+      <field name="text">Sequential one-by-one dispatch is STRICTLY FORBIDDEN</field>
       <field name="text">Monitor completion via marker files, NOT by polling worker status</field>
     </block>
 
@@ -470,6 +482,7 @@ Continue with knowledge base generation?
           </block>
 
           <!-- Step 2: Dispatch Worker for each Feature -->
+          <!-- PARALLEL EXECUTION MANDATORY: All Workers MUST be dispatched SIMULTANEOUSLY in ONE turn -->
           <block type="loop" id="S2-L2" over="${batch_response.batch}" as="feature" parallel="true" max-concurrency="${max_concurrent_workers}" desc="Dispatch analysis Worker for each Feature">
             
             <!-- Route to different Skill based on platformType -->
@@ -552,6 +565,7 @@ Requirements:
           </block>
 
           <!-- Step 2.5: Dispatch Graph Worker -->
+          <!-- PARALLEL EXECUTION MANDATORY: All Graph Workers MUST be dispatched SIMULTANEOUSLY in ONE turn -->
           <block type="loop" id="S2-L25" over="${batch_response.batch}" as="feature" parallel="true" max-concurrency="${max_concurrent_workers}" desc="Dispatch Graph Worker for each Feature IN PARALLEL">
             <block type="gateway" id="S2-G2" mode="exclusive" desc="Route Graph Worker based on analysis type">
               <branch test="${feature.platformType} == 'backend'" name="API Graph">
@@ -656,6 +670,11 @@ Requirements:
     
     <block type="rule" id="S3-R1" level="mandatory" desc="Stage 3 mandatory rules">
       <field name="text">Worker dispatch is handled by the calling Agent (Team Leader). This Skill only prepares the task plan and parameters.</field>
+      <field name="text">ALL module summary workers MUST be dispatched IN PARALLEL — sequential execution is FORBIDDEN</field>
+      <field name="text">ALL Worker dispatch calls in S3-L2 MUST be issued SIMULTANEOUSLY in a SINGLE orchestration turn</field>
+      <field name="text">DO NOT wait for any Worker to complete before dispatching the next Worker</field>
+      <field name="text">Dispatch all ${max_concurrent_workers} workers at once, then wait for ALL to complete</field>
+      <field name="text">Sequential one-by-one dispatch is STRICTLY FORBIDDEN</field>
       <field name="text">Workers MUST NOT create any temporary scripts or workaround files</field>
     </block>
 
@@ -666,7 +685,7 @@ Requirements:
     </block>
 
     <!-- Step 2: Prepare module summary tasks for each platform -->
-    <block type="loop" id="S3-L1" over="${platforms}" as="platform" desc="Prepare module summary tasks for each platform">
+    <block type="loop" id="S3-L1" over="${platforms}" as="platform" parallel="true" max-concurrency="${max_concurrent_workers}" desc="Prepare module summary tasks for each platform IN PARALLEL">
       <!-- Step 2.1: Read platform features -->
       <block type="task" id="S3-B2" action="run-script" status="pending" desc="Read platform features">
         <field name="command">node -e "console.log(require('fs').readFileSync('${sync_state_bizs_dir}/features-${platform.platformId}.json', 'utf8'))"</field>
@@ -680,6 +699,7 @@ Requirements:
       </block>
 
       <!-- Step 2.3: Dispatch Worker for each module -->
+      <!-- PARALLEL EXECUTION MANDATORY: All Module Summary Workers MUST be dispatched SIMULTANEOUSLY in ONE turn -->
       <block type="loop" id="S3-L2" over="${platform_modules}" as="module_name" parallel="true" max-concurrency="${max_concurrent_workers}" desc="Dispatch summary Worker for each module">
         <block type="task" id="S3-B4" action="dispatch-to-worker" status="pending" desc="Dispatch module summary Worker">
           <field name="worker">speccrew-knowledge-module-summarize-xml</field>
@@ -725,10 +745,15 @@ Requirements:
     <block type="rule" id="S35-R1" level="mandatory" desc="Stage 3.5 mandatory rules">
       <field name="text">Worker dispatch is handled by the calling Agent (Team Leader). This Skill only prepares the task plan and parameters.</field>
       <field name="text">ALL UI style extraction workers MUST be dispatched IN PARALLEL — sequential execution is FORBIDDEN</field>
+      <field name="text">ALL Worker dispatch calls in S35-L1 MUST be issued SIMULTANEOUSLY in a SINGLE orchestration turn</field>
+      <field name="text">DO NOT wait for any Worker to complete before dispatching the next Worker</field>
+      <field name="text">Dispatch all ${max_concurrent_workers} workers at once, then wait for ALL to complete</field>
+      <field name="text">Sequential one-by-one dispatch is STRICTLY FORBIDDEN</field>
       <field name="text">This stage writes to techs knowledge base, not bizs knowledge base</field>
     </block>
 
     <!-- Dispatch UI Style Extract Worker for each frontend platform -->
+    <!-- PARALLEL EXECUTION MANDATORY: All UI Style Workers MUST be dispatched SIMULTANEOUSLY in ONE turn -->
     <block type="loop" id="S35-L1" over="${platforms}" as="platform" parallel="true" max-concurrency="${max_concurrent_workers}" desc="Dispatch UI style extraction Workers for frontend platforms IN PARALLEL">
       <block type="gateway" id="S35-G1" mode="exclusive" desc="Execute for UI platforms only">
         <branch test="${platform.platformType} in ['web', 'mobile', 'desktop']" name="UI platform">

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

@@ -63,6 +63,14 @@ For each platform, generates:
     <field name="text">Do not include leading or trailing slashes in entryDirs paths</field>
   </block>
 
+  <block type="rule" id="R-TECHSTACK" level="mandatory" desc="techStack values MUST match tech-stack-mappings.json keys">
+    <field name="text">
+      The techStack array values MUST exactly match keys defined in tech-stack-mappings.json (e.g., "fastapi", "vue3", "uniapp").
+      DO NOT prefix with language name (e.g., use "fastapi" NOT "python-fastapi", use "express" NOT "node-express").
+      The tech_identifier input parameter value should be used as the primary techStack entry.
+    </field>
+  </block>
+
   <!-- ============================================================
        Global Continuous Execution Rules
        ============================================================ -->

package/.speccrew/skills/speccrew-knowledge-bizs-init-features/scripts/generate-inventory.js

@@ -110,6 +110,21 @@ function parseArgs() {
   return params;
 }
 
+/**
+ * Parse boolean parameter from string value
+ * @param {string|boolean} value - Parameter value
+ * @param {boolean} defaultValue - Default value if not provided
+ * @returns {boolean} Parsed boolean value
+ */
+function parseBooleanParam(value, defaultValue = false) {
+  if (value === undefined || value === null) return defaultValue;
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') {
+    return value.toLowerCase() === 'true';
+  }
+  return defaultValue;
+}
+
 // Normalize path separators to forward slashes
 function normalizePath(filePath) {
   if (!filePath) return '';
@@ -215,6 +230,23 @@ function loadPlatformConfig(platformId, projectRoot) {
   return platformConfig;
 }
 
+/**
+ * Normalize tech identifier by removing common language prefixes.
+ * @param {string} id - Tech identifier like "python-fastapi", "node-express"
+ * @returns {string} Normalized identifier like "fastapi", "express"
+ */
+function normalizeTechIdentifier(id) {
+  if (!id) return id;
+  // Remove common language prefixes: python-, node-, java-, etc.
+  const prefixes = ['python-', 'node-', 'java-', 'kotlin-', 'swift-', 'dart-', 'go-', 'rust-', 'php-', 'ruby-'];
+  for (const prefix of prefixes) {
+    if (id.toLowerCase().startsWith(prefix)) {
+      return id.substring(prefix.length);
+    }
+  }
+  return id;
+}
+
 /**
  * Load tech stack configuration from tech-stack-mappings.json
  * @param {string} platformType - Platform type like "backend", "web"
@@ -228,21 +260,38 @@ function loadTechStackConfig(platformType, framework, projectRoot) {
     console.error(`Warning: tech-stack-mappings.json not found at ${configPath}`);
     return { extensions: [], exclude_file_suffixes: [] };
   }
-  
+
   const configContent = fs.readFileSync(configPath, 'utf8');
   const config = JSON.parse(configContent);
-  
-  if (config.tech_stacks && 
-      config.tech_stacks[platformType] && 
+
+  // Try exact match first
+  let techConfig = null;
+  if (config.tech_stacks &&
+      config.tech_stacks[platformType] &&
       config.tech_stacks[platformType][framework]) {
-    const techConfig = config.tech_stacks[platformType][framework];
+    techConfig = config.tech_stacks[platformType][framework];
+  }
+
+  // If not found, try normalized identifier (remove language prefix)
+  if (!techConfig) {
+    const normalizedFramework = normalizeTechIdentifier(framework);
+    if (normalizedFramework !== framework &&
+        config.tech_stacks &&
+        config.tech_stacks[platformType] &&
+        config.tech_stacks[platformType][normalizedFramework]) {
+      techConfig = config.tech_stacks[platformType][normalizedFramework];
+      console.log(`Using normalized tech identifier: ${framework} → ${normalizedFramework}`);
+    }
+  }
+
+  if (techConfig) {
     return {
       extensions: techConfig.extensions || [],
       exclude_file_suffixes: techConfig.exclude_file_suffixes || [],
       exclude_file_names: techConfig.exclude_file_names || []
     };
   }
-  
+
   return { extensions: [], exclude_file_suffixes: [], exclude_file_names: [] };
 }
 
@@ -389,7 +438,7 @@ function findFilesInDir(dir, extensions, baseDir) {
  * @param {string} outputDir - Output directory for features JSON
  * @returns {boolean} Success status
  */
-function generateFromEntryDirs(entryDirsData, platformConfig, projectRoot, outputDir) {
+function generateFromEntryDirs(entryDirsData, platformConfig, projectRoot, outputDir, overwrite) {
   const { platformId, sourcePath, modules } = entryDirsData;
   const { platformType, platformSubtype, framework } = platformConfig;
   
@@ -506,8 +555,8 @@ function generateFromEntryDirs(entryDirsData, platformConfig, projectRoot, outpu
   const outputFileName = `features-${platformId}.json`;
   const outputPath = path.join(outputDir, outputFileName);
 
-  // Incremental: if features file already exists, write to *.new.json
-  const actualOutputPath = fs.existsSync(outputPath)
+  // Incremental: if features file already exists and overwrite is not set, write to *.new.json
+  const actualOutputPath = (!overwrite && fs.existsSync(outputPath))
     ? outputPath.replace(/\.json$/, '.new.json')
     : outputPath;
 
@@ -566,6 +615,9 @@ function findFiles(dir, extensions, excludeDirs, baseDir) {
 function main() {
   const params = parseArgs();
 
+  // Parse overwrite parameter (default: false for backward compatibility)
+  const overwrite = parseBooleanParam(params.overwrite, false);
+
   // Check for whitelist mode (--entryDirsFile provided)
   if (params.entryDirsFile) {
     // Whitelist mode: scan only specified entry directories
@@ -654,7 +706,7 @@ function main() {
     }
     
     // Generate features from entry dirs
-    const success = generateFromEntryDirs(entryDirsData, platformConfig, projectRoot, outputDir);
+    const success = generateFromEntryDirs(entryDirsData, platformConfig, projectRoot, outputDir, overwrite);
     process.exit(success ? 0 : 1);
   }
 
@@ -696,38 +748,53 @@ function main() {
         
         // Load tech-stack-specific exclude_dirs
         let techExcludeDirs = [];
-        if (config.tech_stacks && 
-            config.tech_stacks[platformType] && 
+        let effectiveTechIdentifier = techIdentifier;
+
+        // Try exact match first
+        if (config.tech_stacks &&
+            config.tech_stacks[platformType] &&
             config.tech_stacks[platformType][techIdentifier] &&
             config.tech_stacks[platformType][techIdentifier].exclude_dirs) {
           techExcludeDirs = config.tech_stacks[platformType][techIdentifier].exclude_dirs;
+        } else {
+          // Try normalized identifier (remove language prefix like "python-fastapi" → "fastapi")
+          const normalizedIdentifier = normalizeTechIdentifier(techIdentifier);
+          if (normalizedIdentifier !== techIdentifier &&
+              config.tech_stacks &&
+              config.tech_stacks[platformType] &&
+              config.tech_stacks[platformType][normalizedIdentifier] &&
+              config.tech_stacks[platformType][normalizedIdentifier].exclude_dirs) {
+            techExcludeDirs = config.tech_stacks[platformType][normalizedIdentifier].exclude_dirs;
+            effectiveTechIdentifier = normalizedIdentifier;
+            console.log(`Using normalized tech identifier for exclude_dirs: ${techIdentifier} → ${normalizedIdentifier}`);
+          }
         }
-        
+
         // Load global exclude_dirs (applies to all platforms)
         const globalExcludeDirs = config.global_exclude_dirs || [];
-        
+
         // Merge: global + tech-specific
         const mergedDirs = [...new Set([...globalExcludeDirs, ...techExcludeDirs])];
         excludeDirsStr = JSON.stringify(mergedDirs);
         console.log(`Loaded exclude_dirs from tech-stack-mappings.json (${globalExcludeDirs.length} global + ${techExcludeDirs.length} tech-specific = ${mergedDirs.length} total)`);
-        
+
         // Load tech-stack-specific exclude_file_suffixes
-        if (config.tech_stacks && 
-            config.tech_stacks[platformType] && 
-            config.tech_stacks[platformType][techIdentifier] &&
-            config.tech_stacks[platformType][techIdentifier].exclude_file_suffixes) {
-          excludeFileSuffixes = config.tech_stacks[platformType][techIdentifier].exclude_file_suffixes;
+        if (config.tech_stacks &&
+            config.tech_stacks[platformType] &&
+            config.tech_stacks[platformType][effectiveTechIdentifier] &&
+            config.tech_stacks[platformType][effectiveTechIdentifier].exclude_file_suffixes) {
+          excludeFileSuffixes = config.tech_stacks[platformType][effectiveTechIdentifier].exclude_file_suffixes;
           if (excludeFileSuffixes.length > 0) {
             console.log(`Loaded exclude_file_suffixes from tech-stack-mappings.json: ${excludeFileSuffixes.join(', ')}`);
           }
         }
-        
+
         // Load tech-stack-specific exclude_file_names
-        if (config.tech_stacks && 
-            config.tech_stacks[platformType] && 
-            config.tech_stacks[platformType][techIdentifier] &&
-            config.tech_stacks[platformType][techIdentifier].exclude_file_names) {
-          excludeFileNames = config.tech_stacks[platformType][techIdentifier].exclude_file_names;
+        if (config.tech_stacks &&
+            config.tech_stacks[platformType] &&
+            config.tech_stacks[platformType][effectiveTechIdentifier] &&
+            config.tech_stacks[platformType][effectiveTechIdentifier].exclude_file_names) {
+          excludeFileNames = config.tech_stacks[platformType][effectiveTechIdentifier].exclude_file_names;
           if (excludeFileNames.length > 0) {
             console.log(`Loaded exclude_file_names from tech-stack-mappings.json: ${excludeFileNames.join(', ')}`);
           }
@@ -924,8 +991,8 @@ function main() {
     fs.mkdirSync(syncStateDir, { recursive: true });
   }
 
-  // Incremental: if features file already exists, write to *.new.json
-  const actualOutputPath = fs.existsSync(outputPath)
+  // Incremental: if features file already exists and overwrite is not set, write to *.new.json
+  const actualOutputPath = (!overwrite && fs.existsSync(outputPath))
     ? outputPath.replace(/\.json$/, '.new.json')
     : outputPath;
 

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

@@ -285,6 +285,21 @@ Analyze one specific UI feature from source code, extract business functionality
 
   <!-- ==================== STEP 5A: COPY TEMPLATE TO DOCUMENT PATH ==================== -->
   <sequence id="S5a" name="Step 5a: Copy Template" status="pending" desc="Copy template to document path">
+    <!-- Document Output Path Rule -->
+    <block type="rule" id="R-DOCPATH" level="mandatory" desc="Document output path MUST use documentPath parameter">
+      <field name="text">
+        The output document file MUST be created at the EXACT path specified by ${documentPath} input parameter.
+        DO NOT use the template file name (e.g., FEATURE-DETAIL-TEMPLATE-*.md) as the output file name.
+        The documentPath already contains the correct target path including file name (e.g., speccrew-workspace/knowledges/bizs/web-vue/src/views/system/user/index.md).
+        Before creating the file, ensure the parent directory exists (create if necessary).
+      </field>
+    </block>
+
+    <!-- Ensure Document Output Directory Exists -->
+    <block type="task" id="B5a0" action="run-script" desc="Ensure document output directory exists">
+      <field name="command">node -e "require('fs').mkdirSync(require('path').dirname('${documentPath}'), {recursive: true})"</field>
+    </block>
+
     <!-- Prepare Placeholder Replacements -->
     <block type="task" id="B5a1" action="analyze" desc="Prepare replacements">
       <field name="language" value="${language}"/>

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

@@ -264,12 +264,17 @@ Output: ${sync_state_techs_dir}/techs-manifest.json</field>
       <field name="text">DO NOT finish one platform before starting the next — this wastes time and violates the pipeline design</field>
       <field name="text">The calling Agent MUST use concurrent task dispatch (e.g., dispatch 3 workers in one turn for 3 platforms)</field>
       <field name="text">Sequential platform-by-platform execution is FORBIDDEN</field>
+      <field name="text">Loops S2-L1, S2-L2, S2-L3, and S2-L4 have parallel="true" and MUST execute concurrently for ALL platforms</field>
+      <field name="text">ALL platform status updates (S2-L1) MUST be done SIMULTANEOUSLY in PARALLEL</field>
+      <field name="text">ALL conventions worker task preparations (S2-L2) MUST be done SIMULTANEOUSLY in PARALLEL</field>
+      <field name="text">ALL UI-style worker task preparations (S2-L3) MUST be done SIMULTANEOUSLY in PARALLEL</field>
     </block>
 
     <block type="rule" id="S2-R2" level="forbidden" desc="Stage 2 forbidden actions">
       <field name="text">DO NOT process platforms sequentially — PARALLEL execution is MANDATORY</field>
       <field name="text">DO NOT wait for one platform to complete before starting another</field>
       <field name="text">DO NOT proceed to Stage 2.5 until ALL workers have completed or failed</field>
+      <field name="text">Sequential execution of S2-L1, S2-L2, S2-L3, or S2-L4 is STRICTLY FORBIDDEN</field>
     </block>
 
     <!-- Step 0: Ensure completed_dir exists -->
@@ -278,7 +283,7 @@ Output: ${sync_state_techs_dir}/techs-manifest.json</field>
     </block>
 
     <!-- Step 1: Update manifest status to processing -->
-    <block type="loop" id="S2-L1" over="${techs_manifest.platforms}" as="platform" desc="Update each platform status to processing">
+    <block type="loop" id="S2-L1" over="${techs_manifest.platforms}" as="platform" parallel="true" max-concurrency="${techs_manifest.platforms.length}" desc="Update each platform status to processing">
       <block type="task" id="S2-B1a" action="run-script" status="pending" desc="Update platform status in manifest">
         <field name="command">node -e "
 const fs = require('fs');
@@ -304,7 +309,7 @@ if (platform) {
     <field name="message">Preparing conventions worker task plans for ${techs_manifest.platforms.length} platforms...</field>
     </block>
 
-    <block type="loop" id="S2-L2" over="${techs_manifest.platforms}" as="platform" desc="Prepare conventions worker task for each platform">
+    <block type="loop" id="S2-L2" over="${techs_manifest.platforms}" as="platform" parallel="true" max-concurrency="${techs_manifest.platforms.length}" desc="Prepare conventions worker task for each platform">
       <block type="task" id="S2-B2" action="prepare-task" status="pending" desc="Prepare conventions worker task specification">
         <field name="skill_name">speccrew-knowledge-techs-generate-conventions-xml</field>
         <field name="context">
@@ -327,7 +332,7 @@ if (platform) {
     <field name="message">Preparing UI-style worker task plans for frontend platforms...</field>
     </block>
 
-    <block type="loop" id="S2-L3" over="${techs_manifest.platforms}" as="platform" desc="Prepare UI-style worker task for frontend platforms">
+    <block type="loop" id="S2-L3" over="${techs_manifest.platforms}" as="platform" parallel="true" max-concurrency="${techs_manifest.platforms.length}" desc="Prepare UI-style worker task for frontend platforms">
       <block type="gateway" id="S2-G1" mode="guard" test="${platform.platform_type} IN ['web', 'mobile', 'desktop']" fail-action="skip" desc="Only for frontend platforms">
         <field name="message">Skipping UI-style for backend platform: ${platform.platform_id}</field>
       </block>
@@ -352,6 +357,12 @@ if (platform) {
     </block>
 
     <!-- Step 5: Monitor Completion Markers -->
+    <block type="rule" id="S2-R3" level="mandatory" desc="Platform monitoring parallel execution rule">
+      <field name="text">ALL platform monitoring tasks MUST be dispatched SIMULTANEOUSLY in a SINGLE orchestration turn</field>
+      <field name="text">DO NOT process platforms one-by-one. Sequential execution is FORBIDDEN</field>
+      <field name="text">ALL completion marker checks for ALL platforms MUST run in PARALLEL</field>
+    </block>
+
     <block type="loop" id="S2-L4" over="${techs_manifest.platforms}" as="platform" parallel="true" max-concurrency="${techs_manifest.platforms.length}" desc="Monitor completion markers for each platform">
       
       <!-- Check conventions worker marker -->
@@ -440,6 +451,9 @@ if (platform) {
       <field name="text">MUST scan ALL completion markers before proceeding</field>
       <field name="text">MUST verify document existence and completeness</field>
       <field name="text">MUST update stage2-status.json with verification results</field>
+      <field name="text">ALL platform scans MUST be executed SIMULTANEOUSLY in PARALLEL — sequential scanning is FORBIDDEN</field>
+      <field name="text">ALL platform integrity checks MUST be executed SIMULTANEOUSLY in PARALLEL — sequential verification is FORBIDDEN</field>
+      <field name="text">Stage 2.5 loops S2_5-L1 and S2_5-L2 have parallel="true" and MUST execute concurrently</field>
     </block>
 
     <!-- Step A: Scan Completion Markers -->
@@ -447,7 +461,7 @@ if (platform) {
     <field name="message">Stage 2.5 Step A: Scanning completion markers...</field>
     </block>
 
-    <block type="loop" id="S2_5-L1" over="${techs_manifest.platforms}" as="platform" desc="Scan markers for each platform">
+    <block type="loop" id="S2_5-L1" over="${techs_manifest.platforms}" as="platform" parallel="true" max-concurrency="${techs_manifest.platforms.length}" desc="Scan markers for each platform">
       <block type="task" id="S2_5-B1" action="run-script" status="pending" desc="Check all markers for platform">
         <field name="command">node -e "
 const fs = require('fs');
@@ -473,7 +487,7 @@ console.log(JSON.stringify(markers));
     <field name="message">Stage 2.5 Step B: Verifying output integrity...</field>
     </block>
 
-    <block type="loop" id="S2_5-L2" over="${techs_manifest.platforms}" as="platform" desc="Verify documents for each platform">
+    <block type="loop" id="S2_5-L2" over="${techs_manifest.platforms}" as="platform" parallel="true" max-concurrency="${techs_manifest.platforms.length}" desc="Verify documents for each platform">
       <block type="task" id="S2_5-B2" action="run-script" status="pending" desc="Check required documents exist">
         <field name="command">node -e "
 const fs = require('fs');

package/package.json

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

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

@@ -481,3 +481,20 @@ Team Leader executes:
 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
+
+### Block Execution Announcement Protocol
+
+Before executing each `<block>`, the agent MUST announce the block being executed. The announcement format is:
+
+```
+📋 Block [{block-id}] (type={block-type}, action={action}) — {block-desc}
+```
+
+**Rules:**
+1. The announcement MUST be made BEFORE the block execution begins, not after.
+2. ALL block types require announcement: `task`, `loop`, `checkpoint`, `rule`, `gateway`, `input`, `output`.
+3. For `<block type="loop">` blocks, announce the loop entry with iteration context (e.g., "Loop [S2-L2] — Iterating over ${batch}, 5 items, parallel=true").
+4. For `<block type="checkpoint">` blocks, announce the checkpoint and its validation result.
+5. For `<block type="rule">` blocks, announce the rule being applied.
+6. This protocol applies to ALL agents executing XML workflows — both orchestrating agents (Team Leader) and worker agents.
+7. Nested blocks inside loops should also be announced for each iteration.