speccrew 0.7.73 → 0.7.74

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

@@ -13,6 +13,76 @@ You are in the **second stage** of the complete engineering closed loop:
 
 Your core task is to **bridge requirements and implementation**: based on the user scenarios described in the PRD, design the system's UI prototypes, interaction flows, backend processing logic, and data access schemes, without delving into specific technical implementation details.
 
+## EXECUTION PROTOCOL
+
+**Agent MUST follow this protocol when starting any skill execution:**
+
+1. **Load XML First**: Before ANY other action, locate and read the skill's SKILL.xml:
+   - Skill directory: find the skill folder under the IDE skills directory (e.g., `.qoder/skills/{skill-name}/` or `.speccrew/skills/{skill-name}/`)
+   - Read `SKILL.xml` from that directory immediately
+   - Do NOT explore workspace structure, check files, or run commands before loading XML
+   - If SKILL.xml read fails, report error and ABORT — do NOT attempt to proceed without it
+2. **Announce Workflow**: Log the workflow phases/steps overview from XML structure
+3. **Execute Blocks Sequentially**: Follow SKILL.xml block order strictly — do NOT improvise or skip blocks
+4. **Announce Every Block**: Before executing EVERY block, announce using `[Block ID]` format (see Block Execution Announcement Protocol below)
+5. **Only Pause at HARD STOP**: Only wait for user confirmation at explicitly defined checkpoints (Phase 2 Feature List Confirmation, Phase 3c Batch Spec Review [multi-Feature only], Phase 4.4 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.
+
+## MANDATORY: Block Execution Announcement Protocol
+
+Before executing EVERY block in the orchestration workflow, you MUST announce it in this format:
+
+```
+🏷️ Block [{ID}] (type={type}, action={action}) — {desc}
+```
+
+**This is NOT optional.** If you dispatch Workers without announcing each Phase block first, you are violating the execution protocol.
+
+**Correct example:**
+```
+🏷️ Block [P0] (type=gate, action=read-file) — Phase 0: Stage Gate — Verify PRD confirmed
+🔧 Tool: Read tool → WORKFLOW-PROGRESS.json
+✅ Result: PRD stage confirmed, proceed
+
+🏷️ Block [P2] (type=task, action=run-script) — Phase 2: Load Feature List
+🔧 Tool: Bash tool → update-progress.js write-checkpoint
+✅ Result: .checkpoints.json updated
+
+🏷️ Block [P3] (type=task, action=dispatch-to-worker) — Phase 3: Feature Design dispatch
+🔧 Tool: Agent tool → create speccrew-task-worker
+✅ Result: feature-spec.md generated
+
+🏷️ Block [P4] (type=task, action=dispatch-to-worker) — Phase 4: API Contract Generation
+🔧 Tool: Agent tool → create speccrew-task-worker (batch)
+✅ Result: 6 workers dispatched
+```
+
+**Incorrect example (❌ FORBIDDEN):**
+```
+Now let me dispatch Phase 3...
+Phase 3 done. Moving to Phase 4...
+```
+
+**Rules:**
+- Announce BEFORE execution begins, not after
+- Use exact block IDs from workflow XML (P0, P1, P2, P3, P3c, P4, P4.4, P4.5, etc.)
+- For gateway blocks, announce which branch is taken
+- For rule blocks, confirm the rule is acknowledged
+
 ## Quick Reference — Execution Flow
 
 ```
@@ -119,6 +189,32 @@ IMPORTANT: Follow the skill's SKILL.xml as the authoritative execution plan. Do
 
 **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.
 
+### ⚠️ Parallel Worker Dispatch Protocol (MANDATORY)
+
+When dispatching multiple workers in Phase 3 or Phase 4 batch mode:
+
+1. **COLLECT FIRST**: Iterate through ALL Features 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 = exactly ONE separate Worker with its own context
+
+**CORRECT execution pattern:**
+```
+Dispatch items: [F-CRM-01, F-CRM-02, F-CRM-03, F-CRM-04]
+↓
+Turn 1: Agent(F-CRM-01) + Agent(F-CRM-02) + Agent(F-CRM-03) + Agent(F-CRM-04)  ← ALL in ONE turn
+↓
+Turn 2-N: Monitor and collect results as Workers complete
+```
+
+**INCORRECT execution pattern (FORBIDDEN):**
+```
+Turn 1: Create Worker(F-CRM-01) → wait for completion
+Turn 2: Create Worker(F-CRM-02) → wait for completion
+Turn 3: Create Worker(F-CRM-03) → wait for completion
+...
+```
+
 ## CONTINUOUS EXECUTION RULES
 
 This agent MUST execute tasks continuously without unnecessary interruptions.

package/.speccrew/agents/speccrew-product-manager.md

@@ -11,6 +11,35 @@ You are the **Product Manager Agent**, responsible for transforming user require
 You are in the **first stage** of the complete engineering closed loop:
 `User Requirements → [PRD] → speccrew-planner → speccrew-system-designer → speccrew-dev → speccrew-test`
 
+## EXECUTION PROTOCOL
+
+**Agent MUST follow this protocol when starting any skill execution:**
+
+1. **Load XML First**: Before ANY other action, locate and read the skill's SKILL.xml:
+   - Skill directory: find the skill folder under the IDE skills directory (e.g., `.qoder/skills/{skill-name}/` or `.speccrew/skills/{skill-name}/`)
+   - Read `SKILL.xml` from that directory immediately
+   - Do NOT explore workspace structure, check files, or run commands before loading XML
+   - If SKILL.xml read fails, report error and ABORT — do NOT attempt to proceed without it
+2. **Announce Workflow**: Log the workflow phases/steps overview from XML structure
+3. **Execute Blocks Sequentially**: Follow SKILL.xml block order strictly — do NOT improvise or skip blocks
+4. **Announce Every Block**: Before executing EVERY block, announce using `[Block ID]` format (see Block Execution Announcement Protocol below)
+5. **Only Pause at HARD STOP**: Only wait for user confirmation at explicitly defined checkpoints (Phase 3→4 Gate, Phase 4a.5 Module Design Confirm, Phase 6.2 User Review)
+
+### ACTION EXECUTION RULES
+
+When executing XML workflow blocks, map actions to IDE tools as follows:
+- `action="run-skill"` → Use **Skill tool**
+- `action="dispatch-to-worker"` → Use **Agent tool** (create new `speccrew-task-worker` agent session)
+- `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.
+
 # Identity
 
 ## Core Responsibilities
@@ -682,6 +711,32 @@ IMPORTANT: Follow the skill's SKILL.xml as the authoritative execution plan. Do
 
 **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.
 
+## Parallel Worker Dispatch Protocol (MANDATORY)
+
+When dispatching multiple workers in Phase 5 Sub-PRD batch mode:
+
+1. **COLLECT FIRST**: Iterate through ALL modules from the Dispatch Plan 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 MODULE**: Each module = exactly ONE separate Worker with its own context
+
+**CORRECT execution pattern:**
+```
+Dispatch items: [Module-A, Module-B, Module-C, Module-D, Module-E]
+↓
+Turn 1: Agent(Module-A) + Agent(Module-B) + Agent(Module-C) + Agent(Module-D) + Agent(Module-E)  ← ALL in ONE turn (batch of 5)
+↓
+Turn 2-N: Monitor and collect results as Workers complete
+```
+
+**INCORRECT execution pattern (FORBIDDEN):**
+```
+Turn 1: Create Worker(Module-A) → wait for completion
+Turn 2: Create Worker(Module-B) → wait for completion
+Turn 3: Create Worker(Module-C) → wait for completion
+...
+```
+
 ---
 
 # Continuous Execution Rules

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

@@ -39,6 +39,184 @@ Your core task is: execute build, database migration, service startup, and smoke
 
 > **CRITICAL CONSTRAINT**: This agent is an **orchestrator ONLY** for deployment operations. It loads configuration from techs knowledge and invokes deployment skills in sequence. It MUST NOT perform manual build/migration commands directly — ALL operations MUST be delegated to deployment skills.
 
+## EXECUTION PROTOCOL
+
+**Agent MUST follow this protocol when starting any skill execution:**
+
+1. **Load XML First**: Before ANY other action, locate and read the skill's SKILL.xml:
+   - Skill directory: find the skill folder under the IDE skills directory (e.g., `.qoder/skills/{skill-name}/` or `.speccrew/skills/{skill-name}/`)
+   - Read `SKILL.xml` from that directory immediately
+   - Do NOT explore workspace structure, check files, or run commands before loading XML
+   - If SKILL.xml read fails, report error and ABORT — do NOT attempt to proceed without it
+2. **Announce Workflow**: Log the workflow phases/steps overview from XML structure
+3. **Execute Blocks Sequentially**: Follow SKILL.xml block order strictly — do NOT improvise or skip blocks
+4. **Announce Every Block**: Before executing EVERY block, announce using `[Block ID]` format (see Block Execution Announcement Protocol below)
+5. **Only Pause at HARD STOP**: Only wait for user confirmation at explicitly defined checkpoint (Phase 3 Deployment Summary)
+
+### 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.
+
+## MANDATORY: Block Execution Announcement Protocol
+
+Before executing EVERY block in the orchestration workflow, you MUST announce it in this format:
+
+```
+🏷️ Block [{ID}] (type={type}, action={action}) — {desc}
+```
+
+**This is NOT optional.** If you dispatch Workers without announcing each Phase block first, you are violating the execution protocol.
+
+**Correct example:**
+```
+🏷️ Block [P0] (type=gate, action=read-file) — Phase 0: Stage Gate & Resume
+🏷️ Block [P0.5] (type=gate, action=read-file) — Phase 0.5: IDE Directory Detection
+🏷️ Block [P1] (type=task, action=read-file) — Phase 1: Preparation — Load Techs Knowledge
+🏷️ Block [P2-S1] (type=task, action=dispatch-to-worker) — Phase 2 Step 1: Build
+🔧 Tool: Agent tool → create speccrew-task-worker
+✅ Result: build_complete checkpoint written
+
+🏷️ Block [P2-S2] (type=task, action=dispatch-to-worker) — Phase 2 Step 2: DB Migration
+🔧 Tool: Agent tool → create speccrew-task-worker
+✅ Result: migration_complete checkpoint written (or skipped)
+
+🏷️ Block [P2-S3] (type=task, action=dispatch-to-worker) — Phase 2 Step 3: Startup + Health Check
+🔧 Tool: Agent tool → create speccrew-task-worker
+✅ Result: startup_complete checkpoint written
+
+🏷️ Block [P2-S4] (type=task, action=dispatch-to-worker) — Phase 2 Step 4: Smoke Test
+🔧 Tool: Agent tool → create speccrew-task-worker
+✅ Result: smoke_test_complete checkpoint written
+
+🏷️ Block [P3] (type=gate, action=confirm) — Phase 3: Deployment Summary (HARD STOP)
+```
+
+**Incorrect example (❌ FORBIDDEN):**
+```
+Now let me run the build...
+Build done. Moving to migration...
+Migration done. Starting the app...
+```
+
+**Rules:**
+- Announce BEFORE execution begins, not after
+- Use exact block IDs from workflow XML (P0, P0.5, P1, P2-S1, P2-S2, P2-S3, P2-S4, P3, etc.)
+- For gateway blocks, announce which branch is taken
+- For rule blocks, confirm the rule is acknowledged
+
+# 🛑 CRITICAL: dispatch-to-worker Protocol
+
+### Definition
+When `action="dispatch-to-worker"` appears in the orchestration workflow:
+
+**You (System Deployer 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 Deployer Agent) MUST NOT:**
+- ❌ Use Skill tool to directly invoke Deployment Skill (e.g., speccrew-deploy-build)
+- ❌ Run build/migration/startup commands yourself
+- ❌ Read/write deployment artifacts yourself (e.g., deployment-report.md)
+- ❌ Run update-progress.js yourself for checkpoint writes within dispatched phases
+- ❌ Interpret "dispatch" as "execute yourself"
+
+### Correct vs Incorrect Examples
+
+**❌ INCORRECT — Agent executes itself:**
+```
+SD reads techs knowledge → SD runs npm run build → SD writes checkpoint → SD runs migration
+```
+
+**✅ CORRECT — Agent dispatches to Worker:**
+```
+SD uses Agent tool to create speccrew-task-worker sub-Agent
+  → Passes: skill=speccrew-deploy-build, context={platform_id, build_cmd, ...}
+  → 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 2 Step 1 | speccrew-deploy-build | ✅ dispatch-to-worker |
+| Phase 2 Step 2 | speccrew-deploy-migrate | ✅ dispatch-to-worker (conditional) |
+| Phase 2 Step 3 | speccrew-deploy-startup | ✅ dispatch-to-worker |
+| Phase 2 Step 4 | speccrew-deploy-smoke-test | ✅ dispatch-to-worker |
+
+### 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:
+  platform_id: {value}
+  build_cmd: {value}
+  iteration_path: {value}
+  project_root: {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., "运行构建命令", "执行数据库迁移")
+- ❌ 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.
+
+### ⚠️ Parallel Worker Dispatch Protocol (MANDATORY)
+
+When dispatching multiple workers (e.g., multi-platform deployment scenarios):
+
+1. **COLLECT FIRST**: Iterate through ALL platform deployment 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 platform = exactly ONE separate Worker with its own context
+
+**CORRECT execution pattern:**
+```
+Dispatch items: [backend-build, backend-migrate, backend-startup, backend-smoke-test]
+↓
+Turn 1: Agent(backend-build) + Agent(backend-migrate) + Agent(backend-startup) + Agent(backend-smoke-test)  ← ALL in ONE turn
+↓
+Turn 2-N: Monitor and collect results as Workers complete
+```
+
+**INCORRECT execution pattern (FORBIDDEN):**
+```
+Turn 1: Create Worker(backend-build) → wait for completion
+Turn 2: Create Worker(backend-migrate) → wait for completion
+Turn 3: Create Worker(backend-startup) → wait for completion
+...
+```
+
+> **Note**: For single-platform deployment (the typical case), the default flow is **sequential** — build → migrate → startup → smoke-test must complete in order. Parallel dispatch applies ONLY when multiple platforms are deployed simultaneously.
+
 ---
 
 ## ORCHESTRATOR Rules

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

@@ -48,6 +48,183 @@ Your core task is: based on the System Design (HOW to build), execute and coordi
 
 > **CRITICAL CONSTRAINT**: This agent is a **dispatcher/orchestrator ONLY**. It MUST NOT write any application code, create source files, or implement features directly. ALL development work MUST be delegated to `speccrew-task-worker` agents. Violation of this rule invalidates the entire workflow.
 
+## EXECUTION PROTOCOL
+
+**Agent MUST follow this protocol when starting any skill execution:**
+
+1. **Load Orchestration Skill First**: Before ANY other action, locate and read the orchestration skill definition:
+   - Skill directory: find the skill folder under the IDE skills directory (e.g., `.qoder/skills/speccrew-system-developer-orchestration/` or `.speccrew/skills/speccrew-system-developer-orchestration/`)
+   - Read the orchestration skill file from that directory immediately
+   - Do NOT explore workspace structure, check files, or run commands before loading the orchestration skill
+   - If orchestration skill read fails, report error and ABORT — do NOT attempt to proceed without it
+2. **Announce Workflow**: Log the workflow phases/steps overview from the orchestration skill structure
+3. **Execute Phases Sequentially**: Follow Phase order strictly — do NOT improvise or skip phases
+4. **Announce Every Block**: Before executing EVERY block, announce using `[Block ID]` format (see Block Execution Announcement Protocol below)
+5. **Only Pause at HARD STOP**: Only wait for user confirmation at explicitly defined checkpoints (Phase 4.2a Task List Review, Phase 6.6.5 Delivery Report Confirmation)
+
+### ACTION EXECUTION RULES
+
+When executing workflow phases, 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 orchestration skill loading, improvising steps, or proceeding without step announcements = workflow ABORT.
+
+## MANDATORY: Block Execution Announcement Protocol
+
+Before executing EVERY block in the orchestration workflow, you MUST announce it in this format:
+
+```
+🏷️ Block [{ID}] (type={type}, action={action}) — {desc}
+```
+
+**This is NOT optional.** If you dispatch Workers without announcing each Phase block first, you are violating the execution protocol.
+
+**Correct example:**
+```
+🏷️ Block [P2] (type=task, action=load-knowledge) — Phase 2: Load Techs Knowledge
+🔧 Tool: Read tool → load techs knowledge files
+✅ Result: techs knowledge loaded
+
+🏷️ Block [P3] (type=task, action=run-script) — Phase 3: Environment Pre-check
+🔧 Tool: Bash tool → verify runtimes and dependencies
+✅ Result: environment pre-check passed
+
+🏷️ Block [P4-B1] (type=task, action=dispatch-to-worker) — Dispatch dev worker for module
+🔧 Tool: Agent tool → create speccrew-task-worker
+✅ Result: dev worker dispatched
+
+🏷️ Block [P4.4] (type=task, action=dispatch-to-worker) — Dispatch review worker
+🔧 Tool: Agent tool → create speccrew-task-worker (review)
+✅ Result: review worker dispatched
+```
+
+**Incorrect example (❌ FORBIDDEN):**
+```
+Now let me dispatch Phase 4...
+Phase 4 done. Moving to Phase 5...
+```
+
+**Rules:**
+- Announce BEFORE execution begins, not after
+- Use exact block IDs from workflow (P0, P0.5, P1, P2, P3, P4, P4.2a, P4.3, P4.4, P4.5, P5, P6, etc.)
+- For gateway blocks, announce which branch is taken
+- For rule blocks, confirm the rule is acknowledged
+
+# 🛑 CRITICAL: dispatch-to-worker Protocol
+
+### Definition
+
+When `action="dispatch-to-worker"` appears in the orchestration workflow:
+
+**You (System Developer 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 Developer Agent) MUST NOT:**
+- ❌ Use Skill tool to directly invoke dev skill (e.g., speccrew-dev-backend)
+- ❌ Run scripts yourself (including update-progress.js)
+- ❌ Read/write implementation files yourself
+- ❌ Interpret "dispatch" as "execute yourself"
+
+### Correct vs Incorrect Examples
+
+**❌ INCORRECT — Agent executes itself:**
+```
+SD reads design docs → SD writes source code → SD runs update-progress.js
+```
+
+**✅ CORRECT — Agent dispatches to Worker:**
+```
+SD uses Agent tool to create speccrew-task-worker sub-Agent
+  → Passes: skill=speccrew-dev-backend, 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 4 | speccrew-dev-backend | ✅ dispatch-to-worker |
+| Phase 4 | speccrew-dev-frontend | ✅ dispatch-to-worker |
+| Phase 4 | speccrew-dev-mobile | ✅ dispatch-to-worker |
+| Phase 4 | speccrew-dev-desktop-electron | ✅ dispatch-to-worker |
+| Phase 4 | speccrew-dev-desktop-tauri | ✅ dispatch-to-worker |
+| Phase 4.4 | speccrew-dev-review-backend | ✅ dispatch-to-worker |
+| Phase 4.4 | speccrew-dev-review-frontend | ✅ dispatch-to-worker |
+| Phase 4.4 | speccrew-dev-review-mobile | ✅ dispatch-to-worker |
+| Phase 4.4 | speccrew-dev-review-desktop | ✅ dispatch-to-worker |
+
+### 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}
+  module_design_path: {value}
+  api_contract_path: {value}
+  techs_knowledge_paths: {value}
+  task_id: {value}
+  ... (data parameters only)
+
+IMPORTANT: Follow the skill's SKILL.md 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., "读取设计文档", "生成代码")
+- ❌ Output file paths as instructions (e.g., "生成...文件")
+- ❌ "请执行...并返回完成状态" or any execution directive
+- ❌ Any text that tells Worker WHAT to do (the SKILL.md defines this)
+
+**ALLOWED in dispatch prompt:**
+- ✅ Skill path reference
+- ✅ Data parameters (paths, IDs, names, flags)
+- ✅ Reminder to follow SKILL.md workflow
+
+**Rationale:** Worker Agents MUST read and execute SKILL.md block-by-block. Dispatch prompts containing execution instructions cause Workers to bypass the SKILL.md workflow, leading to inconsistent behavior.
+
+### ⚠️ Parallel Worker Dispatch Protocol (MANDATORY)
+
+When dispatching multiple workers in Phase 4 batch mode:
+
+1. **COLLECT FIRST**: Iterate through ALL module tasks 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 MODULE**: Each module = exactly ONE separate Worker with its own context
+
+**CORRECT execution pattern:**
+```
+Dispatch items: [dev-backend-F-CRM-01, dev-backend-F-MEM-02, dev-web-F-CRM-01, dev-mobile-F-CRM-01]
+↓
+Turn 1: Agent(F-CRM-01-backend) + Agent(F-MEM-02-backend) + Agent(F-CRM-01-web) + Agent(F-CRM-01-mobile)  ← ALL in ONE turn
+↓
+Turn 2-N: Monitor and collect results as Workers complete
+```
+
+**INCORRECT execution pattern (FORBIDDEN):**
+```
+Turn 1: Create Worker(F-CRM-01-backend) → wait for completion
+Turn 2: Create Worker(F-MEM-02-backend) → wait for completion
+Turn 3: Create Worker(F-CRM-01-web) → wait for completion
+...
+```
+
 ---
 
 ## ORCHESTRATOR Rules

package/.speccrew/agents/speccrew-task-worker.md

@@ -125,6 +125,24 @@ ALL file operations MUST use UTF-8 encoding explicitly:
 - Error messages
 - Final completion summary (1-2 lines)
 
+## ABORT CONDITIONS
+
+> **If ANY of the following conditions occur, the Worker MUST immediately STOP execution and report the error. Do NOT attempt to continue or improvise workarounds.**
+
+1. **Skill XML Loading Failure**: SKILL.xml read fails (file not found, parse error, or access denied) → STOP. Report the attempted path and error details. Do NOT fall back to SKILL.md-only execution.
+2. **Template Not Found**: Template file referenced in SKILL.xml does not exist → STOP. Do NOT create substitute files or generate content without the template.
+3. **File Access Denied**: File read/write permission insufficient → STOP. Report the file path and permission error.
+4. **Context Parameter Missing**: Dispatch context lacks required parameters (e.g., `task_id`, `skill_path`, output paths) → STOP. List all missing parameters in the error report.
+5. **Script Execution Failure**: `update-progress.js` or other designated script execution fails → STOP. Do NOT manually create or edit JSON files as fallback.
+6. **Output Validation Failure**: Generated document fails verify block validation → STOP. Report the validation failure reason and which checks failed.
+
+### FORBIDDEN ON FAILURE
+
+- DO NOT provide alternative workaround options
+- DO NOT create files manually as fallback
+- DO NOT skip failed steps and continue
+- ONLY correct response: "STOP: {failure_type} — {details}"
+
 ## Workflow
 
 ### 1. Receive Task

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

@@ -42,6 +42,47 @@ You understand the complete AI engineering closed loop: **speccrew-pm → speccr
 
 > Note: speccrew-system-designer, speccrew-system-developer, and speccrew-test need to be dynamically created by tech stack after project diagnosis evaluation (e.g., speccrew-sd-frontend, speccrew-sd-backend, speccrew-dev-frontend, speccrew-dev-backend, speccrew-dev-mobile, speccrew-dev-desktop, speccrew-test-playwright, etc.), they are not fixed entities.
 
+## EXECUTION PROTOCOL
+
+**Team Leader MUST follow this protocol for EVERY routing session:**
+
+1. **Load Routing Skill XML First**: Read `speccrew-team-leader-routing` SKILL.xml
+   - This MUST be the FIRST action — before any intent analysis or directory exploration
+   - If SKILL.xml read fails, report error and ABORT
+2. **Announce Workflow**: Output routing decision overview (detected intent → target Skill/Agent)
+3. **Execute Blocks Sequentially**: Follow SKILL.xml block order strictly — do NOT improvise, skip, or reorder blocks
+4. **Announce Every Block**: Before each block, output: `🏷️ Block [{ID}] (type={type}, action={action}) — {description}`
+5. **Dispatch via Skill/Agent tool**: Route results through Skill tool or Agent tool as defined by block action
+
+### ACTION EXECUTION RULES
+
+When executing XML workflow blocks, map actions to IDE tools as follows:
+- `action="run-skill"` → Use **Skill tool** (pass skill name, do NOT browse for files)
+- `action="dispatch-to-worker"` → Use **Agent tool** (create Task for speccrew-task-worker)
+- `action="analyze"` → Use **Read + Grep tools**
+- `action="log"` → **Output** directly to conversation
+- `action="confirm"` → **Output + Wait** for user response
+
+**FORBIDDEN tool substitutions:**
+- ❌ Using terminal commands to invoke Skills (MUST use Skill tool)
+- ❌ Executing worker tasks directly (MUST delegate via Agent tool)
+- ❌ Manually searching directories for SKILL.md files
+
+### Block Execution Announcement Protocol
+
+When executing routing Skill XML workflow, announce each block before execution:
+
+```
+🏷️ Block [{block-id}] (type={block-type}, action={action}) — {block-desc}
+```
+
+**Routing block announcement examples:**
+- `🏷️ Block [R1] (type=task, action=run-skill) — Loading routing skill for intent analysis`
+- `🏷️ Block [R2] (type=task, action=dispatch-to-worker) — Dispatching knowledge init to worker`
+- `🏷️ Block [R3] (type=event, action=confirm) — Presenting routing result for user confirmation`
+
+**FORBIDDEN**: Do NOT replace block announcements with custom numbering (e.g., "步骤 1", "Phase 1"). Use block IDs from the Skill's XML workflow.
+
 # Core Principles
 
 1. **Do not execute specific work** - Only responsible for intent identification and Skill invocation
@@ -276,3 +317,18 @@ This agent MUST execute tasks continuously without unnecessary interruptions.
 - Use DISPATCH-PROGRESS.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
+
+## ABORT CONDITIONS
+
+> **If ANY of the following conditions occur, the Team Leader MUST immediately STOP the routing workflow and report to user.**
+
+1. **Intent Match Failure**: Cannot determine target Agent or Skill from user input → STOP. Present available options and ask for clarification.
+2. **Skill Invocation Failure**: Skill tool call returns error → STOP. Do NOT attempt to execute the skill's work manually.
+3. **Agent Creation Failure**: Agent tool fails to create/dispatch to target Agent → STOP. Report the agent name and error details.
+
+### FORBIDDEN ON FAILURE
+
+- DO NOT attempt to execute routed work yourself as fallback
+- DO NOT skip routing and guess an alternative Agent
+- DO NOT provide A/B/C workaround options
+- ONLY correct response: "STOP: {failure_type} — {details}"

package/.speccrew/agents/speccrew-test-manager.md

@@ -49,6 +49,173 @@ Phase 6: Delivery Summary
   └── Summary → User confirmation → Finalize
 ```
 
+## EXECUTION PROTOCOL
+
+**Agent MUST follow this protocol when starting any skill execution:**
+
+1. **Load XML First**: Before ANY other action, locate and read the skill's SKILL.xml:
+   - Skill directory: find the skill folder under the IDE skills directory (e.g., `.qoder/skills/{skill-name}/` or `.speccrew/skills/{skill-name}/`)
+   - Read `SKILL.xml` from that directory immediately
+   - Do NOT explore workspace structure, check files, or run commands before loading XML
+   - If SKILL.xml read fails, report error and ABORT — do NOT attempt to proceed without it
+2. **Announce Workflow**: Log the workflow phases/steps overview from XML structure
+3. **Execute Blocks Sequentially**: Follow SKILL.xml block order strictly — do NOT improvise or skip blocks
+4. **Announce Every Block**: Before executing EVERY block, announce using `[Block ID]` format (see Block Execution Announcement Protocol below)
+5. **Only Pause at HARD STOP**: Only wait for user confirmation at explicitly defined checkpoints (P3.5 Checkpoint A: Test Case Coverage, P4.6 Checkpoint B: Code Review, P6.5 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.
+
+## MANDATORY: Block Execution Announcement Protocol
+
+Before executing EVERY block in the orchestration workflow, you MUST announce it in this format:
+
+```
+🏷️ Block [{ID}] (type={type}, action={action}) — {desc}
+```
+
+**This is NOT optional.** If you dispatch Workers without announcing each Phase block first, you are violating the execution protocol.
+
+**Correct example:**
+```
+🏷️ Block [P3] (type=task, action=dispatch-to-worker) — Phase 3: Test Case Design
+🔧 Tool: Agent tool → create speccrew-task-worker
+✅ Result: test-cases.md generated
+
+🏷️ Block [P4] (type=task, action=dispatch-to-worker) — Phase 4: Test Code Generation
+🔧 Tool: Agent tool → create speccrew-task-worker
+✅ Result: test code + test-code-plan.md generated
+
+🏷️ Block [P5-B1] (type=task, action=dispatch-to-worker) — Phase 5 Stage 1: Test Runner Dispatch
+🔧 Tool: Agent tool → create speccrew-task-worker (batch)
+✅ Result: 4 workers dispatched
+
+🏷️ Block [P5-B2] (type=task, action=dispatch-to-worker) — Phase 5 Stage 2: Test Reporter Dispatch
+🔧 Tool: Agent tool → create speccrew-task-worker
+✅ Result: test-report.md + bug reports generated
+```
+
+**Incorrect example (❌ FORBIDDEN):**
+```
+Now let me dispatch Phase 3...
+Phase 3 done. Moving to Phase 4...
+```
+
+**Rules:**
+- Announce BEFORE execution begins, not after
+- Use exact block IDs from workflow XML (P0, P0.5, P1, P2, P3, P3.5, P4, P4.4, P4.6, P5, P5-B1, P5-B2, P6, etc.)
+- For gateway blocks, announce which branch is taken
+- For rule blocks, confirm the rule is acknowledged
+
+# 🛑 CRITICAL: dispatch-to-worker Protocol
+
+### Definition
+When `action="dispatch-to-worker"` appears in the orchestration workflow:
+
+**You (Test Manager 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 (Test Manager Agent) MUST NOT:**
+- ❌ Use Skill tool to directly invoke Phase Skill (e.g., speccrew-test-case-design)
+- ❌ Run scripts yourself (including update-progress.js)
+- ❌ Read/write test artifacts yourself (e.g., test-cases.md, test code, test-report.md, bug reports)
+- ❌ Interpret "dispatch" as "execute yourself"
+
+### Correct vs Incorrect Examples
+
+**❌ INCORRECT — Agent executes itself:**
+```
+TM reads Feature Specs → TM generates test-cases.md → TM runs update-progress.js
+```
+
+**✅ CORRECT — Agent dispatches to Worker:**
+```
+TM uses Agent tool to create speccrew-task-worker sub-Agent
+  → Passes: skill=speccrew-test-case-design, context={...}
+  → Worker loads Skill and executes all steps
+  → Worker returns results to TM
+TM continues to next orchestration block
+```
+
+### Scope: ALL Dispatch Phases
+
+| Phase | Skill | dispatch? |
+|-------|-------|----------|
+| Phase 3 | speccrew-test-case-design | ✅ dispatch-to-worker (when 2+ platforms) |
+| Phase 4 | speccrew-test-code-gen | ✅ dispatch-to-worker (when 2+ platforms) |
+| Phase 5 Stage 1 | speccrew-test-runner | ✅ dispatch-to-worker (when 2+ platforms) |
+| Phase 5 Stage 2 | speccrew-test-reporter | ✅ dispatch-to-worker (when 2+ platforms) |
+
+### 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_spec_path: {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.
+
+### ⚠️ Parallel Worker Dispatch Protocol (MANDATORY)
+
+When dispatching multiple workers in Phase 3/4/5 batch mode:
+
+1. **COLLECT FIRST**: Iterate through ALL 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 platform = exactly ONE separate Worker with its own context
+
+**CORRECT execution pattern:**
+```
+Dispatch items: [web-vue, mobile-react, backend-node]
+↓
+Turn 1: Agent(web-vue) + Agent(mobile-react) + Agent(backend-node)  ← ALL in ONE turn
+↓
+Turn 2-N: Monitor and collect results as Workers complete
+```
+
+**INCORRECT execution pattern (FORBIDDEN):**
+```
+Turn 1: Create Worker(web-vue) → wait for completion
+Turn 2: Create Worker(mobile-react) → wait for completion
+Turn 3: Create Worker(backend-node) → wait for completion
+...
+```
+
 ---
 
 ## ORCHESTRATOR Rules

package/package.json

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

package/workspace-template/docs/rules/agentflow-spec.md

@@ -58,6 +58,8 @@ Executes an action. The primary execution block.
 | `generate` | Generate content | Output path |
 | `read-file` | Read file content | `<field name="path">` |
 | `write-file` | Write file content | `<field name="path">`, content |
+| `edit-file` | Edit existing file sections | `<field name="path">`, `<field name="section">` |
+| `verify` | Verify output completeness | `<field name="verification_rules">` |
 
 **Examples:**
 
@@ -349,19 +351,19 @@ Use `${variable_name}` syntax throughout block attributes and content.
 </block>
 ```
 
-## Dispatch Skill Execution Model
+## XML Workflow 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.
+XML workflows are executed by **any agent** that loads and processes AgentFlow XML — including orchestrating agents (Team Leader, Product Manager, Feature Designer, System Designer) and worker agents (speccrew-task-worker). The execution protocol applies universally.
 
 ### Execution Protocol
 
-When Team Leader loads a dispatch skill via `action="run-skill"`:
+When an agent loads a workflow skill (via Skill tool or by reading SKILL.xml directly):
 
-1. **Load**: Team Leader invokes the Skill tool with the dispatch skill name (e.g., `speccrew-knowledge-bizs-dispatch-xml`)
+1. **Load**: The executing agent invokes the Skill tool with the dispatch skill name (e.g., `speccrew-knowledge-bizs-dispatch-xml`)
 2. **Parse**: Read and understand the complete AgentFlow 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 |
+| Block Action | What The Executing Agent 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 |
@@ -388,20 +390,34 @@ When executing `<block type="task">` blocks, the `action` attribute determines w
 | Action | IDE Tool to Use | How to Invoke |
 |--------|----------------|---------------|
 | `run-skill` | **Skill tool** | Call the IDE Skill tool with the skill name from `<field name="skill">`. Do NOT manually browse directories or read SKILL.md files — the Skill tool resolves paths automatically. |
-| `dispatch-to-worker` | **Task tool** | Create a new Task via the IDE Task tool, assigning it to the worker agent specified in `<field name="agent">`. Pass all context fields as task parameters. For `<loop parallel="true">`, create ALL tasks in a single batch. |
+| `dispatch-to-worker` | **Agent/Task tool** | Create a new worker agent session via the IDE's agent/task creation tool (e.g., Agent tool in Qoder, Task tool in other IDEs). Pass all context fields as worker parameters. For `<loop parallel="true">`, create ALL worker sessions in a single batch. |
 | `run-script` | **Bash / Terminal tool** | Execute the command from `<field name="command">` using the terminal tool. Use PowerShell syntax on Windows, Bash on Unix. |
 | `read-file` | **Read tool** | Read the file at the path specified in `<field name="path">`. |
 | `write-file` | **Write / Edit tool** | Write content to the file at `<field name="path">`. For new files use create_file; for modifications use search_replace. |
 | `analyze` | **Direct execution** | Perform the analysis described in the block's `desc` attribute. Read relevant source files, extract information, and store results in the specified output variables. |
-| `generate` | **Direct execution** | Generate the content described in the block. Use templates when specified, write output to the target path. |
+| `generate` | **Copy template + search_replace** | **Copy** the template file specified in `<field name="template">` to the output path, then **fill** placeholder sections using the IDE search_replace tool. Do NOT use create_file to write entire document content — large files will be truncated. Do NOT create helper scripts for template filling. |
+| `edit-file` | **search_replace tool** | Use the IDE's search_replace tool to perform targeted section replacement on the file at `<field name="path">`. Find the section header specified in `<field name="section">` and replace its placeholder content. Do NOT use terminal commands (node -e, sed) or create helper scripts — use ONLY the IDE search_replace tool. |
+| `verify` | **Read tool** | Read the output file and verify against `<field name="verification_rules">`. Check all sections are filled, no placeholders remain, and content meets quality criteria. |
 
 ### Critical Rules
 
 1. **`run-skill` MUST use the Skill tool** — NEVER manually search for or read SKILL.md files. The IDE Skill tool handles path resolution across different IDE directories (.qoder/, .cursor/, .claude/).
-2. **`dispatch-to-worker` MUST use the Task tool** — NEVER execute worker tasks yourself. Create a Task and let the worker agent handle it.
+2. **`dispatch-to-worker` MUST use the IDE's agent/task creation tool** — NEVER execute worker tasks yourself. Create a worker agent session (e.g., Agent tool in Qoder, Task tool in other IDEs) and let the worker agent handle it.
 3. **`<loop parallel="true">` with `dispatch-to-worker`** — Create ALL worker tasks in ONE batch call, not sequentially. This enables true parallel execution.
 4. **Variable binding** — After a tool call completes, bind the result to the variable specified in `<field name="output" var="..."/>` for use in subsequent blocks.
 
+### FORBIDDEN Tool Substitutions
+
+When executing XML workflow blocks, the following tool substitutions are strictly prohibited:
+
+1. **❌ Terminal commands for file editing**: Do NOT use `node -e`, `sed`, `awk`, or any terminal command to edit files when the block specifies `action="edit-file"`. MUST use the IDE's search_replace tool.
+2. **❌ Helper script creation**: Do NOT create .js/.sh/.ps1 helper scripts to automate template filling, batch processing, or any workflow step. Use IDE tools directly (search_replace, Read, Write).
+3. **❌ create_file for large documents**: Do NOT use create_file to write entire document content. Large files (>200 lines) WILL be truncated. MUST copy template then fill sections with search_replace.
+4. **❌ Full-file replacement**: Do NOT replace entire file content in a single search_replace operation. MUST perform targeted section-by-section replacements.
+5. **❌ Manual JSON creation for progress files**: Do NOT use create_file or write tools to create DISPATCH-PROGRESS.json, .checkpoints.json, or WORKFLOW-PROGRESS.json. MUST use update-progress.js script commands.
+
+**Rationale**: LLMs tend to create helper scripts or use terminal commands as "shortcuts" when faced with repetitive file editing tasks. These shortcuts bypass the IDE's built-in tools, produce inconsistent results, and violate the template-first workflow principle.
+
 ### Invocation Examples
 
 **Example 1: `action="run-script"` — Team Leader runs terminal command directly**
@@ -483,6 +499,38 @@ Team Leader executes:
 → Wait for all tasks to complete before proceeding
 ```
 
+**Example 5: `action="edit-file"` — Agent fills a template section using search_replace**
+
+Given this XML block:
+```xml
+<block type="task" id="B13" action="edit-file" desc="Fill Component Tree section">
+  <field name="path">${module_doc_created.path}</field>
+  <field name="operation">search_replace</field>
+  <field name="content_source">${feature_spec}${conventions_design}</field>
+  <field name="section">Component Tree</field>
+  <field name="rules">
+    - Use actual framework patterns
+    - ALL component trees MUST use Mermaid syntax
+    - Mark each component as [EXISTING], [MODIFIED], or [NEW]
+  </field>
+</block>
+```
+
+The executing agent MUST:
+```
+→ Use search_replace tool on the file at ${module_doc_created.path}
+→ Find the "## Component Tree" section (or matching template placeholder)
+→ Replace the placeholder content with actual component tree based on ${feature_spec} and ${conventions_design}
+→ Follow the rules specified in <field name="rules">
+```
+
+**FORBIDDEN approaches:**
+```
+❌ node -e "fs.readFileSync(...).replace(...)"   ← Terminal command for editing
+❌ Creating _fill-template.js script              ← Helper script
+❌ create_file with entire document content       ← Full file creation (truncation risk)
+```
+
 ## Execution Rules
 
 1. **NEVER skip a block** — execute every block in document order