speccrew 0.6.45 → 0.6.47

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

@@ -420,6 +420,27 @@ When executing XML workflow blocks, map actions to IDE tools as follows:
 
 **FORBIDDEN**: Do NOT manually search directories for SKILL.md files. Do NOT execute worker tasks yourself — always delegate via Task tool.
 
+## DISPATCH SKILL EXECUTION PROTOCOL
+
+When you load a dispatch skill (e.g., `speccrew-knowledge-bizs-dispatch-xml` or `speccrew-knowledge-techs-dispatch-xml`) via the Skill tool:
+
+1. **You ARE the executor** — do NOT delegate the entire workflow to someone else
+2. **Read the XML workflow** in the loaded SKILL.md from top to bottom
+3. **Execute each block** according to its `action` attribute:
+   - `run-script` → Terminal tool
+   - `run-skill` → Skill tool (do NOT browse directories for SKILL.md)
+   - `dispatch-to-worker` → Task tool (create Task for speccrew-task-worker)
+4. **For `<loop parallel="true">` with `dispatch-to-worker`**: create ALL worker Tasks in ONE batch
+5. **For `<event action="confirm">`**: present to user and wait
+6. **For `<checkpoint>`**: verify condition before proceeding to next stage
+7. **Execute ALL stages in sequence** — Stage 0 → 1a → 1b → 1c → 2 → 3 → 4 (or as defined)
+
+**CRITICAL FORBIDDEN BEHAVIORS**:
+- Do NOT run terminal commands as a substitute for calling a Skill via Skill tool
+- Do NOT manually create JSON files when a Skill should generate them
+- Do NOT execute analysis work that should be dispatched to a Worker via Task tool
+- Do NOT stop between stages to ask the user for direction
+
 ## CONTINUOUS EXECUTION RULES
 
 This agent MUST execute tasks continuously without unnecessary interruptions.

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

@@ -4,6 +4,20 @@ description: Dispatch bizs knowledge base generation tasks with 5-stage pipeline
 tools: Read, Write, Task, Bash
 ---
 
+> **⚠️ MANDATORY EXECUTION PROTOCOL — READ BEFORE EXECUTING ANY BLOCK**
+>
+> **Step 1**: Load XML workflow specification: `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`
+> - `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.
+
 # Bizs Knowledge Dispatch (XML Block Version)
 
 Orchestrate **bizs knowledge base generation** with a 5-stage pipeline using **XML Block system**: Feature Inventory → Feature Analysis + Graph Write → Module Summarize → UI Style Pattern Extract → System Summary.
@@ -85,7 +99,6 @@ 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">
-  > **REQUIRED**: Before executing this workflow, read the XML workflow specification: `docs/rules/xml-workflow-spec.md`
 
   <!-- ============================================================
        Input Parameters Definition
@@ -810,41 +823,11 @@ Failure rate exceeds 50%, terminating entire pipeline
 
 ---
 
-## Input/Output Specification (Supplementary)
-
-### Input Parameters
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `source_path` | Source code path (can be a subdirectory; auto-detects platform root by traversing upward) | project root |
-| `language` | User's language code (e.g., "zh", "en") | **REQUIRED** |
-| `sync_mode` | `"full"` or `"incremental"` | `"full"` |
-| `base_commit` | (incremental only) Git base commit hash | — |
-| `head_commit` | (incremental only) Git HEAD commit hash | `HEAD` |
-| `changed_files` | (incremental only) Pre-computed changed file list | — |
-| `max_concurrent_workers` | Maximum parallel Worker Agents | `5` |
-| `workspace_path` | **(required)** Absolute path to speccrew-workspace directory | — |
-| `sync_state_bizs_dir` | **(required)** Absolute path to `knowledges/base/sync-state/knowledge-bizs/` | — |
-| `ide_skills_dir` | **(required)** Absolute path to IDE skills directory (e.g., `.qoder/skills`, `.cursor/skills`) | — |
-| `configs_dir` | **(required)** Absolute path to `docs/configs/` directory | — |
-| `graph_root` | Graph data output root path (absolute path preferred) | `{workspace_path}/knowledges/bizs/graph` |
-| `completed_dir` | **(required)** Marker file output directory for Worker results (absolute path required) | — |
-
-> **MANDATORY**: All path parameters MUST be absolute paths provided by the caller. DO NOT use ListDir to search for script locations. DO NOT construct paths by guessing or relative path resolution.
-
-### Output Files
-
-- Entry directories: `{sync_state_bizs_dir}/entry-dirs-{platform}.json`
-- Feature inventory: `{sync_state_bizs_dir}/features-{platform}.json`
-- Feature docs: `{workspace_path}/knowledges/bizs/{platform}/{module}/features/*.md`
-- Module overviews: `{workspace_path}/knowledges/bizs/{platform}/{module}/*-overview.md`
-- UI style patterns: `{workspace_path}/knowledges/techs/{platform_id}/ui-style-patterns/` (page-types/, components/, layouts/)
-- System overview: `{workspace_path}/knowledges/bizs/system-overview.md`
-- Graph data: `{workspace_path}/knowledges/bizs/graph/`
+## Appendix: Reference
 
----
+### Skill Routing Table (Stage 2)
 
-## Skill Routing Table (Stage 2)
+> **Note**: Detailed routing logic is defined in XML Stage 2 gateway (S2-G1).
 
 | platformType | skill_name | Description |
 |--------------|------------|-------------|
@@ -853,11 +836,9 @@ Failure rate exceeds 50%, terminating entire pipeline
 | `desktop` | `speccrew-knowledge-bizs-ui-analyze-xml` | Desktop apps (Electron/WPF) |
 | `backend` | `speccrew-knowledge-bizs-api-analyze-xml` | Backend APIs (Java/Python/Node.js) |
 
-> **CRITICAL**: Use this routing table to select the correct skill for each feature.
-
 ---
 
-## Platform Types
+### Platform Types
 
 | Platform Type | Platform Subtype | Description |
 |---------------|------------------|-------------|
@@ -868,9 +849,9 @@ Failure rate exceeds 50%, terminating entire pipeline
 
 ---
 
-## Worker Completion Marker Format
+### Worker Completion Marker Format
 
-### Marker File Naming Convention
+#### Marker File Naming Convention
 
 **Pattern**: `{module}-{subpath}-{fileName}.{type}.json`
 
@@ -889,7 +870,7 @@ Failure rate exceeds 50%, terminating entire pipeline
 | `user/admin/UserController.java` | `user-admin-UserController.done.json` |
 | `order/api/v2/OrderService.java` | `order-api-v2-OrderService.done.json` |
 
-### .done.json Required Fields
+#### .done.json Required Fields
 
 ```json
 {
@@ -907,9 +888,9 @@ Failure rate exceeds 50%, terminating entire pipeline
 
 ---
 
-## Batch Processing Details
+### Batch Processing Details
 
-### get-batch Script Output Format
+#### get-batch Script Output Format
 
 ```json
 {
@@ -930,7 +911,7 @@ Failure rate exceeds 50%, terminating entire pipeline
 }
 ```
 
-### process-results Script Behavior
+#### process-results Script Behavior
 
 - Scans `.done.json` files → updates feature status to `completed` in features-*.json
 - Scans `.graph-done.json` files → confirms graph data generation complete
@@ -939,128 +920,14 @@ Failure rate exceeds 50%, terminating entire pipeline
 
 ---
 
-## Stateless Design (Context Recovery)
-
-Dispatch adopts a fully stateless file-driven design. If context compression or interruption occurs during execution:
-
-- No need to memorize any batch state or Worker output
-- Re-execute loop: `get-batch` will automatically recover from file state, skipping completed and in-progress features
-- `process-results` will process all uncleaned marker files
-- The entire flow is safely re-entrant
-
----
-
-## Large-Scale Scenario Guidance
-
-When modules contain **more than 20 Features**:
-
-- **Single Agent Limit**: A single Worker Agent can reliably process ~20 features per session due to context window constraints. Beyond this, context degradation may cause incomplete document generation.
-- **Multi-Worker Strategy**: For modules with >20 features, the calling Agent should dispatch multiple Worker Agents in parallel, each handling a non-overlapping subset of features.
-- **Resume Support**: The `get-next-batch` script naturally supports resume across sessions — it skips features that already have `.done` files.
-- **Validation After Completion**: After all features are marked `analyzed=true`, run `process-batch-results` with `--validateDocs --syncStatePath` to verify document completeness.
-
----
-
-## Error Handling Strategy
-
-| Stage | Failure Scenario | Handling | Retry |
-|-------|-----------------|----------|-------|
-| Stage 0 | Platform detection fails | Abort pipeline, report error | No retry |
-| Stage 1a | Entry directory recognition fails | Abort pipeline, report platform details | No retry |
-| Stage 1b | Script execution fails | Abort pipeline, report error | No retry |
-| Stage 1c | Feature merge fails | Abort pipeline, do not proceed to Stage 2 until resolved | No retry |
-| Stage 2 | Single Worker fails | Mark feature as `failed`, continue other Workers | No auto-retry |
-| Stage 2 | Failure rate > 50% | Abort pipeline, report all failures | — |
-| Stage 3 | Single Worker fails | Skip that module, continue others | Retry once |
-| Stage 3.5 | Pattern extraction fails | Continue pipeline, report warning | — |
-| Stage 4 | Worker fails | Abort, preserve all generated content | Retry once |
-
-**Failed Feature Handling**: Features marked as `failed` via `update-feature-status` script retain their error details in `features-{platform}.json` for manual inspection or re-run.
-
----
-
-## Task Completion Report Format
+### Stateless Design
 
-Upon completing all stages, output the following structured report:
-
-```json
-{
-  "status": "success | partial | failed",
-  "skill": "speccrew-knowledge-bizs-dispatch-xml",
-  "stages_completed": ["stage_0", "stage_1a", "stage_1b", "stage_1c", "stage_2", "stage_3", "stage_3.5", "stage_4"],
-  "stages_failed": [],
-  "output_summary": {
-    "platforms_processed": ["web-vue", "backend-system"],
-    "features_analyzed": 32,
-    "modules_summarized": 8,
-    "ui_patterns_extracted": 15,
-    "system_overview_generated": true
-  },
-  "output_files": [
-    "knowledges/bizs/{platform}/{module}/features/*.md",
-    "knowledges/bizs/{platform}/{module}/*-overview.md",
-    "knowledges/techs/{platform_id}/ui-style-patterns/",
-    "knowledges/bizs/system-overview.md",
-    "knowledges/bizs/graph/"
-  ],
-  "errors": [],
-  "next_steps": ["Initialize techs knowledge base"]
-}
-```
-
----
-
-## Return Value Structure
-
-After all 5 stages complete, return a summary object to the caller:
-
-```json
-{
-  "status": "completed",
-  "pipeline": "bizs",
-  "stages": {
-    "stage0": { "status": "completed", "platforms": 2 },
-    "stage1a": { "status": "completed", "platforms": 2, "modules": 12 },
-    "stage1b": { "status": "completed", "platforms": 2, "features": 32 },
-    "stage1c": { "status": "completed", "mode": "full" },
-    "stage2": { "status": "completed", "analyzed": 32, "failed": 0, "graphWritten": 32 },
-    "stage3": { "status": "completed", "modules": 8, "failed": 0 },
-    "stage3_5": { "status": "completed", "platforms": 2, "patterns": 15 },
-    "stage4": { "status": "completed" }
-  },
-  "output": {
-    "system_overview": "{workspace_path}/knowledges/bizs/system-overview.md",
-    "graph_root": "{workspace_path}/knowledges/bizs/graph/"
-  }
-}
-```
+Dispatch adopts a fully stateless file-driven design. Re-execute loop to recover: `get-batch` auto-recovers from file state; `process-results` handles uncleaned markers. The entire flow is safely re-entrant.
 
 ---
 
-## CONTINUOUS EXECUTION RULES
-
-This skill MUST execute all stages continuously without unnecessary interruptions.
-
-### FORBIDDEN Interruptions
-
-1. DO NOT ask user "Should I continue?" after completing a stage
-2. DO NOT suggest "Let me split this into batches" or "Let's do this in parts"
-3. DO NOT pause to list what you plan to do next — just do it
-4. DO NOT ask for confirmation before generating output files
-5. DO NOT warn about "large number of files" — proceed with generation
-6. DO NOT offer "Should I proceed with the remaining items?"
-7. DO NOT present options like "Full execution / Sample execution / Pause"
-
-### When to Pause (ONLY these cases)
+### Large-Scale Scenario Guidance
 
-1. Explicit `<event action="confirm">` blocks in the workflow (e.g., Stage 0 platform confirmation)
-2. Ambiguous requirements that genuinely need clarification
-3. Unrecoverable errors that prevent further progress (failure rate > 50%)
-4. Security-sensitive operations (e.g., deleting existing files)
+For modules with >20 features: dispatch multiple Worker Agents in parallel (each handles a subset). Use `get-next-batch` for resume support across sessions. Run `process-batch-results --validateDocs` after completion to verify.
 
-### Batch Execution Behavior
 
-- When multiple features need processing, process ALL of them sequentially without asking
-- Use marker files (.done.json) to track progress, enabling resumption if interrupted by context limits
-- If context window is approaching limit, save progress to checkpoint and inform user how to resume
-- NEVER voluntarily stop mid-batch to ask if user wants to continue

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

@@ -4,6 +4,20 @@ description: Dispatch techs knowledge base generation tasks with 3-stage pipelin
 tools: Read, Write, Task, Bash
 ---
 
+> **⚠️ MANDATORY EXECUTION PROTOCOL — READ BEFORE EXECUTING ANY BLOCK**
+>
+> **Step 1**: Load XML workflow specification: `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`
+> - `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.
+
 # Techs Knowledge Dispatch (XML Block Version)
 
 Orchestrate **techs knowledge base generation** with a 3-stage pipeline using **XML Block system**: Platform Detection → Tech Doc Generation → Root Index.
@@ -610,11 +624,13 @@ Stage 3 complete. Root INDEX.md generated.
 
 ---
 
-## Worker Completion Marker Format
+## Appendix: Reference
+
+### Worker Completion Marker Format
 
 Each Worker MUST create a completion marker file after generating documents.
 
-### Conventions Worker Done File
+#### Conventions Worker Done File
 
 **File**: `{completed_dir}/{platform_id}.done-conventions.json`
 
@@ -634,7 +650,7 @@ Each Worker MUST create a completion marker file after generating documents.
 }
 ```
 
-### UI-Style Worker Done File
+#### UI-Style Worker Done File
 
 **File**: `{completed_dir}/{platform_id}.done-ui-style.json`
 
@@ -659,7 +675,7 @@ Each Worker MUST create a completion marker file after generating documents.
 
 If a Worker encounters a fatal error, it should still attempt to create the done file with `status: "failed"` and include error details in an `"error"` field.
 
-### Quality Worker Done File
+#### Quality Worker Done File
 
 **File**: `{completed_dir}/{platform_id}.quality-done.json`
 
@@ -677,7 +693,7 @@ If a Worker encounters a fatal error, it should still attempt to create the done
 
 ---
 
-## Platform Status Tracking Fields
+### Platform Status Tracking Fields
 
 Each platform entry in techs-manifest.json includes status tracking fields for monitoring the analysis pipeline progress:
 
@@ -721,7 +737,7 @@ pending → processing → completed
 
 ---
 
-## Output per Platform
+### Output per Platform
 
 ```
 speccrew-workspace/knowledges/techs/{platform_id}/
@@ -759,9 +775,9 @@ speccrew-workspace/knowledges/techs/{platform_id}/
 
 ---
 
-## Error Handling
+### Error Handling
 
-### Error Handling Strategy
+#### Error Handling Strategy
 
 ```
 ON Worker Failure:
@@ -774,7 +790,7 @@ ON Worker Failure:
      - IF some platforms succeeded → CONTINUE to Stage 3 with successful platforms only
 ```
 
-### Stage-Level Failure Handling
+#### Stage-Level Failure Handling
 
 | Stage | Failure Handling |
 |-------|-----------------|
@@ -783,7 +799,7 @@ ON Worker Failure:
 | Stage 2.5 | Continue pipeline, report warnings |
 | Stage 3 | Abort if Stage 2 had critical failures |
 
-### Worker Failure Details
+#### Worker Failure Details
 
 **When a Worker Agent fails:**
 - **No automatic retry**: Worker failures are recorded as-is
@@ -793,7 +809,7 @@ ON Worker Failure:
 
 ---
 
-## Checklist
+### Checklist
 
 - [ ] Stage 1: Platform manifest generated with techs-manifest.json
 - [ ] Stage 2: All platforms processed in parallel
@@ -801,89 +817,9 @@ ON Worker Failure:
 - [ ] Stage 3: Root INDEX.md generated with Agent mapping
 - [ ] Stage 3: `stage3-status.json` generated with index info
 
-### Document Completeness Verification
+#### Document Completeness Verification
 - [ ] Each platform directory contains required documents: INDEX.md, tech-stack.md, architecture.md, conventions-design.md, conventions-dev.md, conventions-unit-test.md, conventions-system-test.md, conventions-build.md
 - [ ] `conventions-data.md` exists only for appropriate platforms (backend required, others optional)
 - [ ] All documents include file reference blocks (pure Markdown format for VS Code preview compatibility)
 - [ ] All documents include AI-TAG and AI-CONTEXT comments
 - [ ] techs/INDEX.md links only to existing documents
-
----
-
-## Task Completion Report Format
-
-Upon completing all stages, output the following structured report:
-
-```json
-{
-  "status": "success | partial | failed",
-  "skill": "speccrew-knowledge-techs-dispatch-xml",
-  "stages_completed": ["stage_1", "stage_2", "stage_2_5", "stage_3"],
-  "stages_failed": [],
-  "output_summary": {
-    "platforms_processed": ["frontend", "backend"],
-    "docs_generated_per_platform": {"frontend": 5, "backend": 4},
-    "root_index_generated": true,
-    "cross_platform_check_passed": true
-  },
-  "output_files": [
-    "knowledges/techs/{platform}/README.md",
-    "knowledges/techs/{platform}/conventions.md",
-    "knowledges/techs/README.md"
-  ],
-  "errors": [],
-  "next_steps": ["Review generated tech documentation"]
-}
-```
-
----
-
-## Return Value Structure
-
-After all 3 stages complete, return a summary object to the caller:
-
-```json
-{
-  "status": "completed",
-  "pipeline": "techs",
-  "stages": {
-    "stage1": { "status": "completed", "platforms": 3 },
-    "stage2": { "status": "completed", "completed": 3, "failed": 0 },
-    "stage3": { "status": "completed" }
-  },
-  "output": {
-    "index": "speccrew-workspace/knowledges/techs/INDEX.md",
-    "manifest": "speccrew-workspace/knowledges/base/sync-state/knowledge-techs/techs-manifest.json"
-  }
-}
-```
-
----
-
-## CONTINUOUS EXECUTION RULES
-
-This skill MUST execute all stages continuously without unnecessary interruptions.
-
-### FORBIDDEN Interruptions
-
-1. DO NOT ask user "Should I continue?" after completing a stage
-2. DO NOT suggest "Let me split this into batches" or "Let's do this in parts"
-3. DO NOT pause to list what you plan to do next — just do it
-4. DO NOT ask for confirmation before generating output files
-5. DO NOT warn about "large number of files" — proceed with generation
-6. DO NOT offer "Should I proceed with the remaining items?"
-7. DO NOT present options like "Full execution / Sample execution / Pause"
-
-### When to Pause (ONLY these cases)
-
-1. Explicit `<event action="confirm">` blocks in the workflow (e.g., platform confirmation if needed)
-2. Ambiguous requirements that genuinely need clarification
-3. Unrecoverable errors that prevent further progress (failure rate > 50%)
-4. Security-sensitive operations (e.g., deleting existing files)
-
-### Batch Execution Behavior
-
-- When multiple platforms need processing, process ALL of them without asking
-- Use marker files (.done.json) to track progress, enabling resumption if interrupted by context limits
-- If context window is approaching limit, save progress to checkpoint and inform user how to resume
-- NEVER voluntarily stop mid-batch to ask if user wants to continue

package/package.json

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

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

@@ -329,6 +329,38 @@ Use `${variable_name}` syntax throughout block attributes and content.
 </block>
 ```
 
+## Dispatch Skill Execution Model
+
+Dispatch skills (naming pattern: `*-dispatch-xml`) are **orchestration playbooks** loaded directly by Team Leader via the Skill tool. They contain the complete multi-stage workflow definition.
+
+### Execution Protocol
+
+When Team Leader loads a dispatch skill via `action="run-skill"`:
+
+1. **Load**: Team Leader invokes the Skill tool with the dispatch skill name (e.g., `speccrew-knowledge-bizs-dispatch-xml`)
+2. **Parse**: Read and understand the complete XML workflow in the loaded SKILL.md
+3. **Execute block-by-block**: Walk through each Stage's blocks in document order, mapping each `action` attribute to the correct IDE tool:
+
+| Block Action | What Team Leader MUST Do |
+|---|---|
+| `action="run-script"` | Execute the command via **Terminal tool** (PowerShell/Bash) |
+| `action="run-skill"` | Invoke the skill via **Skill tool** — do NOT manually read SKILL.md files |
+| `action="dispatch-to-worker"` | Create Task via **Task tool**, assign to `speccrew-task-worker` |
+| `action="analyze"` | Perform analysis directly (read files, extract info) |
+| `action="generate"` | Generate content directly (use templates, write output) |
+| `action="confirm"` (event) | Present confirmation to user, wait for response |
+
+4. **Respect control flow**: Honor `<gateway>` branches, `<loop parallel="true">` concurrency, and `<checkpoint>` verification
+5. **Continuous execution**: Proceed from Stage N to Stage N+1 automatically — ONLY pause at explicit `<event action="confirm">` blocks
+
+### FORBIDDEN During Dispatch Execution
+
+- **NEVER** execute commands manually when a block says `action="run-skill"` — use the Skill tool
+- **NEVER** do a worker's job yourself when a block says `action="dispatch-to-worker"` — use the Task tool
+- **NEVER** skip stages or blocks
+- **NEVER** pause between stages to ask "Should I continue?"
+- **NEVER** improvise your own approach — follow the XML blocks exactly
+
 ## Action to IDE Tool Mapping
 
 When executing `<block type="task">` blocks, the `action` attribute determines which **IDE tool** to invoke. Do NOT interpret actions freely — use the exact tool specified below: