speccrew 0.7.55 → 0.7.57

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

@@ -31,8 +31,8 @@ Phase 2: Resource Verification
 Phase 3: Framework Evaluation (HARD STOP)
   └── Dispatch speccrew-sd-framework-evaluate skill → User confirms
         ↓
-Phase 4: Generate DESIGN-OVERVIEW.md
-  └── Create L1 overview with Feature×Platform matrix → Validate completeness
+Phase 4: Generate DESIGN-OVERVIEW.md (WORKER-DISPATCH + HARD STOP)
+  └── Dispatch speccrew-sd-design-overview-generate skill → Wait for worker → Validate → User confirms
         ↓
 Phase 5: Dispatch Per-Platform Skills
   ├── Single Feature + Single Platform → Direct skill invocation
@@ -57,7 +57,6 @@ This agent is an **orchestrator/dispatcher**. For system design execution (Phase
 ### Agent-Allowed Deliverables
 
 This agent MAY directly create/modify ONLY the following files:
-- ✅ `DESIGN-OVERVIEW.md`
 - ✅ `DISPATCH-PROGRESS.json` (via update-progress.js script only)
 - ✅ `.checkpoints.json` (via update-progress.js script only)
 - ✅ Progress summary messages to user
@@ -65,6 +64,9 @@ This agent MAY directly create/modify ONLY the following files:
 > Note: `framework-evaluation.md` is generated **ONLY** by the `speccrew-sd-framework-evaluate` skill.
 > The Agent MUST NOT create or modify this file manually.
 
+> Note: `DESIGN-OVERVIEW.md` is generated **ONLY** by the `speccrew-sd-design-overview-generate` skill dispatched to a worker agent.
+> The Agent MUST NOT create or modify this file manually.
+
 ### FORBIDDEN Actions (When Features ≥ 2 OR Platforms ≥ 2)
 
 1. ❌ DO NOT invoke `speccrew-sd-backend` skill directly
@@ -124,7 +126,7 @@ This agent MUST execute tasks continuously without unnecessary interruptions.
 | Phase 2 | KNOWLEDGE-FIRST | MUST load ALL techs knowledge before Phase 3. DO NOT assume technology stack |
 | Phase 3 | WORKER-DISPATCH | Framework evaluation MUST be dispatched to speccrew-task-worker via **Agent tool**. Agent MUST NOT invoke speccrew-sd-framework-evaluate via Skill tool. |
 | Phase 3 | HARD STOP | User must confirm framework decisions before proceeding to Phase 4 |
-| Phase 4 | AGENT-OWNED | DESIGN-OVERVIEW.md generation is Agent responsibility (not skill-dispatched) |
+| Phase 4 | WORKER-DISPATCH + HARD STOP | DESIGN-OVERVIEW.md generation MUST be dispatched to speccrew-task-worker via **Agent tool**. After worker completes, present summary to user and WAIT for confirmation before Phase 5. |
 | Phase 5 | SKILL-ONLY | Platform design workers MUST use platform-specific design skills. Agent MUST NOT write design documents itself |
 | Phase 6 | HARD STOP | User must confirm all designs before finalizing |
 | ALL | ABORT ON FAILURE | If any skill invocation fails → STOP and report. Do NOT generate content manually as fallback |
@@ -529,6 +531,33 @@ Proceed to Phase 4? (Confirm/Cancel)
 
 ## Phase 4: Generate DESIGN-OVERVIEW.md (L1)
 
+> 🛑 **CRITICAL: Phase 4 dispatch-to-worker Protocol**
+>
+> When executing Phase 4 (Design Overview Generation):
+> 1. Use **Agent tool** to create a new sub-Agent
+> 2. Specify sub-Agent role as **speccrew-task-worker**
+> 3. Pass `skill_path`: `${workspace_path}/.speccrew/skills/speccrew-sd-design-overview-generate/SKILL.md`
+> 4. Pass context parameters: workspace_path, iteration_path, feature_registry_path, techs_manifest_path, framework_evaluation_path, output_path
+> 5. **Wait for Worker completion** before proceeding to validation
+>
+> **FORBIDDEN**:
+> - ❌ DO NOT generate DESIGN-OVERVIEW.md yourself
+> - ❌ DO NOT use Skill tool to invoke speccrew-sd-design-overview-generate
+
+> ⚠️ **HARD STOP — Phase 4.5: DESIGN-OVERVIEW.md Confirmation**
+> After worker completes and DESIGN-OVERVIEW.md passes validation:
+> 1. Present summary to user: feature count, platform count, matrix entries, key design decisions
+> 2. **STOP** — Wait for user explicit confirmation
+> 3. User responses:
+>    - "确认" or "OK" → Update checkpoint, proceed to Phase 5
+>    - "修改" + specific changes → Re-dispatch worker with adjustments
+>    - "取消" → Abort workflow
+> **FORBIDDEN during HARD STOP**:
+> - ❌ DO NOT update checkpoint until user confirms
+> - ❌ DO NOT suggest next steps
+> - ❌ DO NOT proceed to Phase 5
+> - ❌ DO NOT auto-approve even if all validations pass
+
 Create the top-level overview at:
 `{iterations_dir}/{current}/03.system-design/DESIGN-OVERVIEW.md`
 
@@ -1025,7 +1054,7 @@ Otherwise
 - Phase 2: MUST verify ALL techs knowledge files exist (manifest + platform-specific stacks) before Phase 3
 - Phase 3: MUST dispatch speccrew-sd-framework-evaluate via speccrew-task-worker (Agent tool) — DO NOT evaluate yourself and DO NOT invoke via Skill tool
 - Phase 3: User MUST confirm framework decisions (🛑 HARD STOP) before proceeding to Phase 4
-- Phase 4: MUST generate DESIGN-OVERVIEW.md with complete Feature×Platform index BEFORE dispatching platform workers
+- Phase 4: MUST dispatch speccrew-task-worker with speccrew-sd-design-overview-generate skill to generate DESIGN-OVERVIEW.md BEFORE dispatching platform workers
 - Phase 5: MUST use speccrew-task-worker to dispatch platform-specific design skills for parallel execution (never direct skill invocation for batch)
 - Phase 5: MUST use update-progress.js script for ALL progress tracking (DISPATCH-PROGRESS.json, .checkpoints.json, WORKFLOW-PROGRESS.json)
 - Phase 6: MUST collect ALL worker results and present joint summary before requesting user confirmation (🛑 HARD STOP)
@@ -1040,7 +1069,7 @@ Otherwise
 - DO NOT skip framework evaluation checkpoint — user confirmation is mandatory
 - DO NOT assume technology stack without verifying techs knowledge exists
 - DO NOT generate designs for platforms not in techs-manifest
-- DO NOT generate per-platform or per-feature design documents yourself (INDEX.md, {feature-id}-{feature-name}-design.md, etc.) — always dispatch platform design skills via workers. DESIGN-OVERVIEW.md is the ONLY system design document this Agent generates directly
+- DO NOT generate DESIGN-OVERVIEW.md yourself — dispatch speccrew-task-worker with speccrew-sd-design-overview-generate skill. Agent does NOT directly generate ANY system design documents.
 - DO NOT invoke platform design skills directly when 2+ features or 2+ platforms exist — use speccrew-task-worker
 - DO NOT create or manually edit DISPATCH-PROGRESS.json, .checkpoints.json, or WORKFLOW-PROGRESS.json — use update-progress.js script only
 - DO NOT update WORKFLOW-PROGRESS.json status to "confirmed" before joint user confirmation in Phase 6

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

@@ -35,7 +35,7 @@ System Designer 的核心编排技能，负责：
 2. **Preparation** - 加载 Feature Registry，验证文件存在性
 3. **Resource Verification** - 验证技术知识库可用性
 4. **Framework Evaluation** - 派发单个 worker agent 执行框架评估技能，等待 worker 完成并验证 framework-evaluation.md 生成后进入下一阶段（HARD STOP 等待用户确认）
-5. **Design Overview** - 生成 DESIGN-OVERVIEW.md
+5. **Design Overview** - 派发 worker agent 执行 speccrew-sd-design-overview-generate 技能生成 DESIGN-OVERVIEW.md，等待 worker 完成并验证输出
 6. **Platform Dispatch** - 分发各平台设计任务给 Worker
 7. **Joint Confirmation** - 联合确认所有设计文档
 
@@ -105,10 +105,25 @@ This skill MUST execute tasks continuously without unnecessary interruptions.
 
 **CRITICAL**: The `Agent tool` creates a NEW agent session — this is completely different from the `Skill tool` which executes inline.
 
+### Phase 4 Execution Method — Worker Agent Dispatch
+
+**HOW TO DISPATCH**: When executing Phase 4 block P4-B1 (action="dispatch-to-worker"):
+1. Use the **Agent tool** to create a new `speccrew-task-worker` agent
+2. Pass `skill_path` to the worker: `${workspace_path}/.speccrew/skills/speccrew-sd-design-overview-generate/SKILL.md`
+3. Pass context parameters: workspace_path, iteration_path, feature_registry_path (.prd-feature-list.json path), techs_manifest_path (techs-manifest.json path), framework_evaluation_path (framework-evaluation.md path), output_path
+4. **Wait** for the worker agent to complete and return results
+5. After worker completes, verify DESIGN-OVERVIEW.md exists at output_path
+6. Then proceed to Phase 4 checkpoint validation (P4-CP1)
+7. Present DESIGN-OVERVIEW.md summary to user (feature count, platform count, matrix entries)
+8. **⚠️ HARD STOP** — Wait for user explicit confirmation before proceeding to Phase 5
+
+**CRITICAL**: The `Agent tool` creates a NEW agent session — this is completely different from the `Skill tool` which executes inline.
+
 ### HARD STOP Checkpoints
 
 This workflow has **mandatory HARD STOP** checkpoints at:
-- **Phase 3.5**: Framework evaluation confirmation (user MUST approve)
+- **Phase 3.5**: Framework evaluation confirmation (user MUST approve framework decisions)
+- **Phase 4.5**: Design overview confirmation (user MUST approve DESIGN-OVERVIEW.md before Phase 5 dispatch)
 - **Phase 6.1**: Joint design confirmation (user MUST approve all designs)
 
 DO NOT proceed past these checkpoints without explicit user confirmation.
@@ -130,3 +145,5 @@ DO NOT proceed past these checkpoints without explicit user confirmation.
 - **DO NOT create scripts for batch analysis** — Workers handle this via their own skill
 - **DO NOT fallback to inline execution if worker fails** — ABORT instead
 - **DO NOT skip reading workflow.agentflow.xml** — XML is the execution authority
+- **DO NOT generate DESIGN-OVERVIEW.md yourself** — Dispatch speccrew-task-worker with speccrew-sd-design-overview-generate skill
+- **DO NOT use Skill tool for Phase 4 design overview generation** — Skill tool executes inline, Agent tool creates a worker

package/.speccrew/skills/speccrew-system-designer-orchestration/workflow.agentflow.xml

@@ -245,28 +245,55 @@
     </block>
   </sequence>
 
-  <!-- ========== Phase 4: Generate DESIGN-OVERVIEW.md ========== -->
-  <sequence name="Phase 4: Generate DESIGN-OVERVIEW.md">
-    <block type="rule" id="P4-R1" level="mandatory" desc="Agent-Owned Rule">
-      <field name="text">DESIGN-OVERVIEW.md generation is Agent responsibility (not skill-dispatched)</field>
+  <!-- ========== Phase 4: Generate DESIGN-OVERVIEW.md (WORKER-DISPATCH) ========== -->
+  <sequence name="Phase 4: Generate DESIGN-OVERVIEW.md (WORKER-DISPATCH)">
+    <block type="rule" id="P4-R0" level="forbidden" desc="Phase 4 Worker Dispatch Enforcement">
+      <field name="text">FORBIDDEN: Do NOT inline-generate DESIGN-OVERVIEW.md yourself</field>
+      <field name="text">MANDATORY: DESIGN-OVERVIEW.md generation MUST be delegated to worker agent via block P4-B1</field>
+      <field name="text">TOOL MAPPING: action="dispatch-to-worker" → Use Agent tool (NOT Skill tool) to create speccrew-task-worker agent</field>
+      <field name="text">If worker dispatch fails, ABORT — do NOT fallback to inline generation</field>
     </block>
 
-    <block type="task" id="P4-B1" action="write-file" status="pending"
-           desc="Generate DESIGN-OVERVIEW.md">
-      <field name="path">${iterations_dir}/${current_iteration}/03.system-design/DESIGN-OVERVIEW.md</field>
-      <field name="template">design-overview-template</field>
-      <field name="data">
-        iteration: ${current_iteration},
-        platforms: ${techs_manifest.platforms},
-        features: ${feature_registry.features},
-        framework_decisions: ${framework_result.decisions}
+    <block type="task" id="P4-B1" action="dispatch-to-worker" status="pending"
+           desc="Dispatch single worker agent for design overview generation. Use Agent tool, NOT Skill tool.">
+      <field name="agent">speccrew-task-worker</field>
+      <field name="skill">speccrew-sd-design-overview-generate</field>
+      <field name="skill_path">${workspace_path}/.speccrew/skills/speccrew-sd-design-overview-generate/SKILL.md</field>
+      <field name="context">
+        workspace_path: ${workspace_path},
+        iteration_path: ${iterations_dir}/${current_iteration},
+        feature_registry_path: ${iterations_dir}/${current_iteration}/01.product-requirement/.prd-feature-list.json,
+        techs_manifest_path: ${workspace_path}/knowledges/techs/techs-manifest.json,
+        framework_evaluation_path: ${iterations_dir}/${current_iteration}/03.system-design/framework-evaluation.md,
+        output_path: ${iterations_dir}/${current_iteration}/03.system-design/DESIGN-OVERVIEW.md
       </field>
+      <field name="note">Worker receives ALL context above and generates DESIGN-OVERVIEW.md. Orchestrator MUST NOT read feature files or generate this document itself.</field>
     </block>
 
-    <!-- Step 4.1: Validation -->
+    <block type="gateway" id="P4-GW1" mode="wait" desc="Wait for design overview worker to complete">
+      <field name="wait_for">P4-B1</field>
+      <field name="timeout">300</field>
+    </block>
+
+    <block type="task" id="P4-B2" action="read-file" status="pending"
+           desc="Verify DESIGN-OVERVIEW.md was generated by worker">
+      <field name="path">${iterations_dir}/${current_iteration}/03.system-design/DESIGN-OVERVIEW.md</field>
+      <field name="output" var="design_overview_content"/>
+    </block>
+
+    <!-- Validation Checkpoint -->
     <block type="checkpoint" id="P4-CP1" name="design_overview" desc="DESIGN-OVERVIEW validation">
       <field name="conditions">file_exists, has_design_scope_section, has_tech_decisions_section, has_platform_design_index, index_covers_all_feature_platform_combinations</field>
     </block>
+
+    <!-- Phase 4.5: HARD STOP — User must confirm DESIGN-OVERVIEW.md -->
+    <block type="rule" id="P4-HS1" level="mandatory" desc="HARD STOP — DESIGN-OVERVIEW.md confirmation required">
+      <field name="text">⚠️ HARD STOP — WAIT FOR USER CONFIRMATION</field>
+      <field name="text">Present DESIGN-OVERVIEW.md summary to user (feature count, platform count, matrix entries, key sections)</field>
+      <field name="text">User responses: "确认"/"OK" → proceed to Phase 5 | "修改" + changes → re-dispatch worker | "取消" → abort</field>
+      <field name="text">FORBIDDEN: Do NOT update checkpoint, suggest next steps, or proceed to Phase 5 until user explicitly confirms</field>
+      <field name="text">FORBIDDEN: Do NOT auto-approve even if validation passes — user review is mandatory</field>
+    </block>
   </sequence>
 
   <!-- ========== Phase 5: Dispatch Per-Platform Skills ========== -->

package/package.json

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