speccrew 0.7.27 → 0.7.29

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

@@ -143,6 +143,19 @@ This agent MUST execute tasks continuously without unnecessary interruptions.
 2. **FORBIDDEN: Manual JSON creation** — DO NOT use `create_file` or `write` to create progress/checkpoint JSON files. ALWAYS use the appropriate `update-progress.js` command.
 3. **FORBIDDEN: Timestamp parameters** — DO NOT pass `--started-at`, `--completed-at`, or `--confirmed-at` parameters to `update-progress.js` commands. These parameters are deprecated.
 
+## update-progress.js Command Reference
+
+| Command | Purpose | Key Parameters |
+|---------|---------|----------------|
+| `init` | Initialize DISPATCH-PROGRESS.json | `--file`, `--stage`, `--tasks-file` (recommended) or `--tasks` |
+| `read` | Query progress status | `--file`, `--summary`, `--checkpoints`, `--overview`, `--task-id`, `--status` |
+| `update-task` | Mark worker completion | `--file`, `--task-id`, `--status`, `--output`, `--error` |
+| `write-checkpoint` | Mark phase checkpoint | `--file`, `--stage`, `--checkpoint`, `--passed`, `--description` (optional) |
+| `update-workflow` | Update workflow stage | `--file`, `--stage`, `--status`, `--output` (optional) |
+| `update-counts` | Recalculate counts | `--file` |
+
+> **Note**: Use `--tasks-file` instead of `--tasks` on Windows PowerShell to avoid JSON parsing issues.
+
 # Workflow
 
 ## AgentFlow Definition
@@ -346,9 +359,12 @@ node {update_progress_script} write-checkpoint `
   --file {iterations_dir}/{iteration}/02.feature-design/.checkpoints.json `
   --stage 02_feature_design `
   --checkpoint function_decomposition `
-  --data '{"features": [...], "total_features": N, "total_modules": M}'
+  --passed true `
+  --description "Feature decomposition confirmed: N features across M modules"
 ```
 
+> **Note**: Use `--passed` and `--description` for write-checkpoint. The `--data` parameter is NOT supported by update-progress.js.
+
 **Feature status values:**
 - `pending`: Not started
 - `in_progress`: Worker dispatched
@@ -411,6 +427,67 @@ When involving related business domains, read `{workspace_path}/knowledges/bizs/
 > 6. **Intermediate artifacts are MANDATORY.** .feature-analysis.md must exist before Phase 3b.
 > 7. **Feature name is LOCKED after Phase 2 confirmation.** All Worker dispatch parameters MUST use the exact `feature_name` from `.checkpoints.json`. DO NOT derive, translate, or modify feature names at any point after the Feature List is confirmed.
 
+### Prepare Task List for Dispatch
+
+> ⚠️ **CRITICAL: Two Different File Formats**
+>
+> The `.prd-feature-list.json` and `init --tasks-file` expect DIFFERENT formats. Do NOT use one in place of the other.
+
+#### `.prd-feature-list.json` — Feature Metadata Registry
+
+This file is generated by PM Agent and contains the complete feature metadata with nested structure:
+
+```json
+{
+  "modules": [
+    {
+      "module_id": "M1-System",
+      "module_name": "System Management",
+      "features": [
+        {
+          "feature_id": "F-SYS-01",
+          "feature_name": "Account Login",
+          "feature_type": "Page+API",
+          "dependencies": []
+        }
+      ]
+    }
+  ]
+}
+```
+
+- **Purpose**: Source of truth for feature metadata (names, types, dependencies)
+- **Structure**: Nested `modules > features` array
+- **Used by**: Agent reads this to understand feature breakdown
+- **NOT for**: Direct use with `update-progress.js init` command
+
+#### `.tasks-temp.json` — Flat Task Array for init Command
+
+The `update-progress.js init --tasks-file` expects a **flat array** of task IDs:
+
+```json
+[
+  {"id": "F-SYS-01"},
+  {"id": "F-MEMBER-01"},
+  {"id": "F-CRM-01"}
+]
+```
+
+- **Purpose**: Initialize DISPATCH-PROGRESS.json task list
+- **Structure**: Flat array with `id` field only
+- **Used by**: `update-progress.js init --tasks-file <path>`
+- **Naming**: Recommend `.tasks-temp.json` (delete after init)
+
+#### Conversion Step
+
+Before initializing DISPATCH-PROGRESS.json, extract feature IDs from `.prd-feature-list.json`:
+
+1. Read `.prd-feature-list.json`
+2. Flatten `modules[].features[].feature_id` into array
+3. Write `[{"id": "F-XXX"}, ...]` to `.tasks-temp.json`
+4. Run `update-progress.js init --tasks-file .tasks-temp.json`
+5. Delete `.tasks-temp.json`
+
 ---
 
 ### Phase 3a: Analyze — Function Decomposition

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

@@ -94,7 +94,7 @@ PM continues to next orchestration block
 | Phase 3 | speccrew-pm-requirement-clarify | ✅ dispatch-to-worker |
 | Phase 4a | speccrew-pm-requirement-model | ✅ dispatch-to-worker |
 | Phase 4b | speccrew-pm-requirement-analysis | ✅ dispatch-to-worker |
-| Phase 5 | speccrew-pm-phase5-subprd-dispatch | ✅ dispatch-to-worker |
+| Phase 5 | speccrew-pm-phase5-subprd-dispatch | ⚡ PM direct execution |
 | Phase 6 | speccrew-pm-phase6-verify-confirm | ✅ dispatch-to-worker |
 
 ---
@@ -155,7 +155,7 @@ Phase 0 done. Moving to Phase 1...
 | **Phase 4a** | ISA-95 Modeling (complex) | `speccrew-pm-requirement-model` | Worker dispatch |
 | **Phase 4b** | PRD Generation (complex) | `speccrew-pm-requirement-analysis` | Worker dispatch |
 | **Phase 4** | Simple PRD Generation | `speccrew-pm-requirement-simple` | Worker dispatch |
-| **Phase 5** | Sub-PRD Dispatch (complex) | `speccrew-pm-phase5-subprd-dispatch` | Parallel Worker dispatch |
+| **Phase 5** | Sub-PRD Dispatch (complex) | `speccrew-pm-phase5-subprd-dispatch` | PM Direct Orchestration |
 | **Phase 6** | Verification & Confirmation | `speccrew-pm-phase6-verify-confirm` | Worker dispatch |
 
 ---
@@ -400,21 +400,62 @@ Step 4b: Dispatch Worker with speccrew-pm-requirement-analysis
 
 ---
 
-## Phase 5: Sub-PRD Worker Dispatch
+## Phase 5: Sub-PRD Worker Dispatch (PM Direct Orchestration)
 
-<!-- Phase 5 的详细步骤已提取到 AgentFlow Skill: speccrew-pm-phase5-subprd-dispatch -->
-<!-- 执行时由 orchestration 通过 dispatch-to-worker 调用 -->
+<!-- Phase 5 是 PM 直接执行的编排 Skill，PM 必须读取 workflow.agentflow.xml 并按步骤执行 -->
+<!-- ⚠️ 这里的 dispatch-to-worker 块由 PM Agent 直接执行，不能委派给 Worker -->
+
+**Purpose**: As the orchestration layer, PM Agent directly coordinates batch dispatch of Sub-PRD generation tasks to Worker Agents.
+
+> 🛑 **CRITICAL ARCHITECTURE RULE (Harness Principle 17: Orchestration Layer Separation)**
+>
+> Phase 5 is an **orchestration skill** containing internal `dispatch-to-worker` blocks.
+> - Workers CANNOT dispatch Workers (execution hierarchy)
+> - Therefore, Phase 5 MUST be executed directly by PM Agent
+> - PM Agent reads `workflow.agentflow.xml` and executes each block step-by-step
+
+### 5.1 PM Agent Execution Protocol
+
+**PM Agent MUST:**
+1. Read the skill's `workflow.agentflow.xml` to understand execution steps
+2. Execute each block in order: read plan → init progress → dispatch workers → verify
+3. Use Agent tool to create `speccrew-task-worker` for EACH module
+4. Pass `speccrew-pm-sub-prd-generate` skill name to each Worker
 
-**Purpose**: Dispatch parallel Workers to generate Sub-PRD documents for each module.
+**PM Agent MUST NOT:**
+- Dispatch Phase 5 to a Worker (Worker cannot dispatch sub-Workers)
+- Skip reading the workflow.agentflow.xml
+- Generate Sub-PRD content directly
 
-### 5.1 Prerequisites
+### 5.2 Prerequisites
 
 - Phase 4b completed with valid Dispatch Plan
 - Master PRD exists
 - Dispatch Plan contains module list (count ≥ 2)
+- `.sub-prd-dispatch-plan.json` exists in iteration directory
+
+### 5.3 Workflow Steps (from workflow.agentflow.xml)
 
-### 5.2 Dispatch Strategy
+**Step 5.1: Read Dispatch Plan**
+- Read `.sub-prd-dispatch-plan.json` from iteration directory
+- Parse module list and verify required fields
 
+**Step 5.2: Initialize Progress Tracking**
+
+> 🛑 **MANDATORY: Initialize DISPATCH-PROGRESS.json BEFORE any Worker dispatch**
+>
+> PM Agent MUST:
+> 1. Create temp task file: `.tasks-temp.json`
+> 2. Run: `node {update_progress_script} init --file DISPATCH-PROGRESS.json --stage sub_prd_dispatch --tasks-file .tasks-temp.json`
+> 3. Verify initialization (Total: N | Pending: N | Completed: 0)
+>
+> **FORBIDDEN:**
+> - DO NOT dispatch ANY Worker before DISPATCH-PROGRESS.json is initialized
+> - DO NOT create DISPATCH-PROGRESS.json manually via create_file
+
+**Step 5.3: Batch Dispatch Workers**
+
+Dispatch Strategy:
 | Module Count | Dispatch Strategy |
 |--------------|-------------------|
 | 1-5 modules | Single batch, all parallel |
@@ -424,24 +465,25 @@ Step 4b: Dispatch Worker with speccrew-pm-requirement-analysis
 
 **BATCH SIZE = 5 (maximum parallel Workers per batch)**
 
-### 5.3 Worker Dispatch Rules
-
-> 🛑 **CRITICAL: ONE Worker per Module — NO EXCEPTIONS**
+> 🛑 **MANDATORY: Update Progress After Each Worker Completes**
+>
+> After each Worker returns:
+> 1. Run: `node {update_progress_script} update-task --file DISPATCH-PROGRESS.json --task-id {module_id} --status {completed|failed}`
+> 2. Verify the update succeeded
+>
+> **FORBIDDEN:**
+> - DO NOT skip progress update
+> - DO NOT proceed to next batch until current batch is verified
 
-**PM Agent MUST:**
-1. Read the Dispatch Plan from generate skill output
-2. Initialize DISPATCH-PROGRESS.json via update-progress.js script
-3. For EACH module: invoke ONE `speccrew-task-worker` with `speccrew-pm-sub-prd-generate`
-4. Pass ALL required context parameters to each worker
-5. Dispatch in batches of 5, wait for each batch to complete
-6. After each Worker completes, update DISPATCH-PROGRESS.json via script
+**Step 5.4: Failure Retry**
+- Check for tasks with `failed` status
+- Retry once if failures exist
+- Log persistent failures and continue
 
-**PM Agent MUST NOT:**
-- Generate Sub-PRD files directly (via create_file, write, or any file creation)
-- Invoke speccrew-pm-sub-prd-generate skill directly
-- Dispatch ONE Worker to handle MULTIPLE modules
-- Create or edit any Sub-PRD content as fallback
-- Skip worker dispatch and generate Sub-PRDs inline
+**Step 5.5: Result Verification**
+- Read final DISPATCH-PROGRESS.json
+- Verify all Sub-PRD files exist and size > 3KB
+- Update checkpoint via script
 
 ### 5.4 Worker Context Parameters
 
@@ -458,21 +500,18 @@ Step 4b: Dispatch Worker with speccrew-pm-requirement-analysis
 | `output_path` | Computed | `{output_dir}/{feature_name}-sub-{module_key}.md` |
 | `language` | Detected | User's language |
 
-### 5.5 Progress Tracking
-
-- Track progress in `DISPATCH-PROGRESS.json` via `update-progress.js` script
-- After ALL workers complete, verify Sub-PRD files exist
-- Update checkpoint `sub_prd_dispatch` to `passed`
-
-### 5.6 Completion Verification
+### 5.5 Completion Verification
 
 Before proceeding to Phase 6, verify:
-- [ ] All workers were dispatched via speccrew-task-worker (one Worker per module)
+- [ ] PM Agent executed Phase 5 directly (NOT dispatched to Worker)
+- [ ] DISPATCH-PROGRESS.json was initialized BEFORE any dispatch
+- [ ] All workers were dispatched via Agent tool (one Worker per module)
+- [ ] Progress was updated after each Worker completed
 - [ ] No Sub-PRD was generated by PM Agent directly
 - [ ] All workers completed (DISPATCH-PROGRESS.json counts.pending == 0)
 - [ ] All Sub-PRD files exist and have valid size
 - [ ] `.prd-feature-list.json` contains complete feature data
-- [ ] Checkpoint updated
+- [ ] Checkpoint updated via script
 
 ---
 

package/.speccrew/skills/speccrew-pm-phase5-subprd-dispatch/SKILL.md

@@ -2,15 +2,32 @@
 
 ## Description
 
-PM Phase 5 Sub-PRD Batch Dispatch Skill. Core orchestration component for Master-Sub PRD workflow, executed directly by PM Agent (NOT dispatched to Worker).
+PM Phase 5 Sub-PRD Batch Dispatch Skill. **Orchestration-layer skill** executed directly by PM Agent (NOT dispatched to Worker).
 
-PM Agent loads and executes this skill directly to coordinate batch dispatch of Sub-PRD generation tasks to Worker Agents, implementing:
-- Reading Dispatch Plan from Master PRD
-- Initializing dispatch progress tracking
-- Dispatching Workers in parallel batches for Sub-PRD generation per module
-- Failure retry and result verification
+This is an **orchestration skill** that PM Agent must execute directly:
+- PM Agent reads `workflow.agentflow.xml` and executes each block step-by-step
+- PM Agent uses Agent tool to dispatch Workers for Sub-PRD generation
+- Workers generate Sub-PRD files; PM Agent only coordinates
 
-**CRITICAL**: This skill contains dispatch-to-worker logic internally. It MUST be executed by PM Agent (who has Agent tool access), NOT by a Worker Agent (who cannot create sub-Workers).
+**CRITICAL ARCHITECTURE RULE (Harness Principle 17: Orchestration Layer Separation)**:
+- This skill contains internal `dispatch-to-worker` blocks
+- Workers CANNOT dispatch Workers (execution hierarchy constraint)
+- Therefore, this skill MUST be executed by PM Agent directly
+- PM Agent MUST NOT dispatch this skill to a Worker
+
+**Execution Method**: PM Agent reads `workflow.agentflow.xml` and follows the workflow steps.
+
+## MANDATORY: PM Must Read workflow.agentflow.xml
+
+> 🛑 **BEFORE executing this skill, PM Agent MUST:**
+> 1. Read the `workflow.agentflow.xml` file in this skill directory
+> 2. Parse each block and execute in order
+> 3. Follow the exact workflow steps defined in the XML
+>
+> **FORBIDDEN:**
+> - DO NOT execute this skill without reading the XML workflow
+> - DO NOT skip blocks defined in the XML
+> - DO NOT dispatch this skill to a Worker Agent
 
 ## Input Parameters
 
@@ -69,27 +86,22 @@ PM Agent loads and executes this skill directly to coordinate batch dispatch of
 ### Step 5.6: User Confirmation
 - [ ] Wait for user confirmation of Sub-PRD generation results
 
-## Key Rules
-
-### MANDATORY - Worker Dispatch Rules
-- **ONE Worker per Module** - Dispatch one independent Worker per Sub-PRD module
-- **PM Must Not Generate Directly** - PM Agent must NOT directly generate Sub-PRD content
-- **Must Use dispatch-to-worker** - All Workers must be executed via `dispatch-to-worker` action
-- **Direct Skill Invocation Forbidden** - Must NOT directly invoke `speccrew-pm-sub-prd-generate` skill
-
-### MANDATORY - Batch Processing Rules
-- **Batch Size = 5** - Maximum 5 parallel Workers per batch
-- **Parallel Dispatch** - Workers in the same batch must be dispatched simultaneously
-- **Sequential Wait** - Wait for current batch to complete before dispatching next batch
-- **Progress Update** - Immediately update DISPATCH-PROGRESS.json after each Worker completes
-
-### MANDATORY - Progress Tracking Rules
-- **Script Initialization** - DISPATCH-PROGRESS.json must be created via update-progress.js
-- **Manual Creation Forbidden** - Must NOT create progress files directly via create_file or PowerShell
-- **Idempotent Update** - Use `update-task` command to update individual task status
-
-### FORBIDDEN - Prohibited Actions
-- PM Agent directly generating Sub-PRD files is forbidden
-- Dispatching one Worker to handle multiple modules is forbidden
-- Skipping Worker dispatch as a fallback after failure is forbidden
-- Marking checkpoint as passed before user confirmation is forbidden
+## Must Do
+
+- **READ workflow.agentflow.xml FIRST** — PM Agent must parse the XML workflow before any execution
+- **Initialize DISPATCH-PROGRESS.json BEFORE any Worker dispatch** — Use update-progress.js init command
+- **Dispatch one Worker per module** — Use Agent tool to create speccrew-task-worker with speccrew-pm-sub-prd-generate skill
+- **Update progress after each Worker completes** — Use update-progress.js update-task command
+- **Verify all Sub-PRD files exist** — Check file existence and size > 3KB
+- **Update checkpoint via script** — Use update-progress.js write-checkpoint command
+
+## Must Not Do
+
+- **DO NOT dispatch this skill to a Worker** — Phase 5 is PM direct execution
+- **DO NOT skip reading workflow.agentflow.xml** — XML workflow is the execution guide
+- **DO NOT dispatch Workers before DISPATCH-PROGRESS.json is initialized** — Progress tracking is mandatory
+- **DO NOT create DISPATCH-PROGRESS.json manually** — Must use update-progress.js script
+- **DO NOT generate Sub-PRD content directly** — Only Workers generate Sub-PRDs
+- **DO NOT skip progress update after Worker completes** — Must call update-task for each completed Worker
+- **DO NOT dispatch one Worker for multiple modules** — One Worker per module
+- **DO NOT proceed to Phase 6 without verifying all Sub-PRDs** — Completion verification is mandatory

package/package.json

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