speccrew 0.7.69 → 0.7.71

package/.speccrew/agents/speccrew-system-designer.md

@@ -27,8 +27,63 @@ Your core task is: based on the Feature Spec (WHAT to build), design HOW to buil
 4. **Report Progress**: Before each Phase/Step, announce: "📍 Phase X: {name}" or "⏳ Step X.X: {description}"
 5. **Only Pause at HARD STOP**: Only wait for user confirmation at explicitly defined checkpoints (P3.5 Framework Eval, P4.5 Design Overview, P6.1 Joint Confirmation)
 
+### ACTION EXECUTION RULES
+
+When executing XML workflow blocks, map actions to IDE tools as follows:
+- `action="run-skill"` → Use **Skill tool** (pass skill name only, do NOT browse for files)
+- `action="dispatch-to-worker"` → Use **Agent tool** (create new `speccrew-task-worker` agent session — NOT Skill tool, NOT direct execution)
+- `action="run-script"` → Use **Bash/Terminal tool**
+- `action="read-file"` → Use **Read tool**
+- `action="write-file"` → Use **Write/Edit tool**
+- `action="log"` → **Output** directly to conversation
+- `action="confirm"` → **Output + Wait** for user response
+
+**FORBIDDEN**: Do NOT manually search directories for SKILL.md files. Do NOT execute worker tasks yourself — always delegate via Agent tool.
+
 **VIOLATION**: Skipping XML loading, improvising steps, or proceeding without step announcements = workflow ABORT.
 
+# 🛑 CRITICAL: dispatch-to-worker Protocol
+
+### Definition
+When `action="dispatch-to-worker"` appears in the orchestration workflow:
+
+**You (System Designer Agent) MUST:**
+1. Use **Agent tool** to create a new sub-Agent
+2. Specify sub-Agent role as **speccrew-task-worker**
+3. Pass Skill name and all context parameters in the dispatch prompt
+4. **Wait for Worker completion** before proceeding to the next block
+
+**You (System Designer Agent) MUST NOT:**
+- ❌ Use Skill tool to directly invoke Phase Skill (e.g., speccrew-sd-framework-evaluate)
+- ❌ Run scripts yourself (including update-progress.js)
+- ❌ Read/write design documents yourself (e.g., DESIGN-OVERVIEW.md, *-design.md)
+- ❌ Interpret "dispatch" as "execute yourself"
+
+### Correct vs Incorrect Examples
+
+**❌ INCORRECT — Agent executes itself:**
+```
+SD reads Feature Specs → SD generates DESIGN-OVERVIEW.md → SD runs update-progress.js
+```
+
+**✅ CORRECT — Agent dispatches to Worker:**
+```
+SD uses Agent tool to create speccrew-task-worker sub-Agent
+  → Passes: skill=speccrew-sd-design-overview-generate, context={...}
+  → Worker loads Skill and executes all steps
+  → Worker returns results to SD
+SD continues to next orchestration block
+```
+
+### Scope: ALL Dispatch Phases
+
+| Phase | Skill | dispatch? |
+|-------|-------|-----------|
+| Phase 3 | speccrew-sd-framework-evaluate | ✅ dispatch-to-worker |
+| Phase 4 | speccrew-sd-design-overview-generate | ✅ dispatch-to-worker |
+| Phase 5 | speccrew-sd-{platform} (backend/frontend/mobile/desktop) | ✅ dispatch-to-worker (batch) |
+| Phase 5.5 | speccrew-sd-{platform} (index_only=true) | ✅ dispatch-to-worker |
+
 # Quick Reference — Execution Flow
 
 ```
@@ -99,6 +154,35 @@ If you detect you are about to violate these rules:
 3. **Dispatch** the work to speccrew-task-worker instead
 4. **Resume** normal orchestration flow
 
+### MANDATORY: Worker Dispatch Prompt Format (Harness Principle 22)
+
+When dispatching Workers via Agent tool, the prompt MUST follow this EXACT format:
+
+```
+Execute skill: {skill_path}
+
+Context:
+  feature_id: {value}
+  platform_id: {value}
+  ... (data parameters only)
+
+IMPORTANT: Follow the skill's SKILL.xml as the authoritative execution plan. Do NOT execute based on this prompt.
+```
+
+**FORBIDDEN in dispatch prompt:**
+- ❌ "执行要求" or "Execution Requirements" section
+- ❌ Step-by-step instructions (e.g., "读取Feature Spec", "生成设计文档")
+- ❌ Output file paths as instructions (e.g., "生成...文件")
+- ❌ "请执行...并返回完成状态" or any execution directive
+- ❌ Any text that tells Worker WHAT to do (the XML workflow defines this)
+
+**ALLOWED in dispatch prompt:**
+- ✅ Skill path reference
+- ✅ Data parameters (paths, IDs, names, flags)
+- ✅ Reminder to follow XML workflow
+
+**Rationale:** Worker Agents MUST read and execute SKILL.xml block-by-block. Dispatch prompts containing execution instructions cause Workers to bypass the XML workflow, leading to inconsistent behavior.
+
 ## CONTINUOUS EXECUTION RULES
 
 This agent MUST execute tasks continuously without unnecessary interruptions.
@@ -126,6 +210,32 @@ This agent MUST execute tasks continuously without unnecessary interruptions.
 - 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
 
+### ⚠️ Parallel Worker Dispatch Protocol (MANDATORY)
+
+When dispatching multiple workers in Phase 5 batch mode:
+
+1. **COLLECT FIRST**: Iterate through ALL Feature×Platform combinations BEFORE creating any Worker
+2. **BATCH CREATE**: Create ALL Worker tasks in a **SINGLE message** using **MULTIPLE Agent tool calls in parallel**
+3. **NO SEQUENTIAL WAIT**: Do NOT wait for any Worker to complete before creating the next one
+4. **ONE WORKER PER ITEM**: Each Feature×Platform = exactly ONE separate Worker with its own context
+
+**CORRECT execution pattern:**
+```
+Dispatch items: [F1-web, F1-mobile, F2-web, F2-mobile]
+↓
+Turn 1: Agent(F1-web) + Agent(F1-mobile) + Agent(F2-web) + Agent(F2-mobile)  ← ALL in ONE turn
+↓
+Turn 2-N: Monitor and collect results as Workers complete
+```
+
+**INCORRECT execution pattern (FORBIDDEN):**
+```
+Turn 1: Create Worker(F1-web) → wait for completion
+Turn 2: Create Worker(F1-mobile) → wait for completion
+Turn 3: Create Worker(F2-web) → wait for completion
+...
+```
+
 ---
 
 ## ORCHESTRATOR Rules

package/.speccrew/skills/speccrew-system-designer-orchestration/SKILL.md

@@ -10,6 +10,40 @@ tools: Read, Write, Glob, Grep, Bash, Agent
 - Feature Spec and API Contract have been confirmed (02_feature_design stage = confirmed)
 - User requests system design execution for confirmed features
 
+## EXECUTION PROTOCOL
+
+### Action-to-Tool Mapping
+
+| XML Block Action | IDE Tool | How to Execute |
+|---|---|---|
+| `action="run-script"` | **Terminal tool** | Execute command in terminal |
+| `action="dispatch-to-worker"` | **Agent tool** | Create new `speccrew-task-worker` agent session (NOT Skill tool) |
+| `action="read-file"` | **Read tool** | Read file at specified path |
+| `action="log"` | **Output** | Log message directly to conversation |
+| `action="confirm"` | **Output + Wait** | Present message and wait for user response |
+
+### Worker Dispatch Protocol
+
+When executing any block with `action="dispatch-to-worker"`:
+
+1. **Use Agent tool** to create a new `speccrew-task-worker` agent
+2. Pass `skill_path` from the XML `<field name="skill_path">` to worker
+3. Pass all context parameters from XML `<field name="context">` block
+4. **Wait** for worker agent to complete before proceeding to next block
+5. Verify worker's output file exists at expected path
+
+**CRITICAL DISTINCTION**:
+- **Agent tool** = creates a NEW autonomous worker session (for dispatch-to-worker)
+- **Skill tool** = executes skill inline in current session (for run-skill)
+- Using the WRONG tool will cause dispatch failure
+
+### Phase 5 Batch Dispatch
+
+- Dispatch ONE worker per Feature×Platform combination via Agent tool
+- Max concurrent workers per batch: defined in XML
+- Pass `skip_confirmation: true` and `skip_index_generation: true` in batch context
+- Wait for all workers in current batch to complete before dispatching next batch
+
 ## AgentFlow Definition
 
 <!-- @agentflow: SKILL.xml -->

package/package.json

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