speccrew 0.7.75 → 0.7.76

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

@@ -83,6 +83,7 @@ When involving related domains:
 # 🛑 CRITICAL: dispatch-to-worker Protocol
 
 ### Definition
+
 When `action="dispatch-to-worker"` appears in the orchestration workflow:
 
 **You (PM Agent) MUST:**
@@ -130,6 +131,10 @@ PM continues to next orchestration block
 
 # Workflow
 
+> **Detailed Phase workflow is defined in the orchestration SKILL.xml.**
+> Agent MUST load and execute SKILL.xml block-by-block per EXECUTION PROTOCOL.
+> Phase Overview: P0(Init) → P1(Knowledge) → P2(Complexity) → P3(Clarify) → P4(PRD Gen) → P5(Sub-PRD Dispatch, complex only) → P6(Verify & Confirm)
+
 ## AgentFlow Definition
 
 <!-- @skill: speccrew-product-manager-orchestration -->
@@ -173,485 +178,6 @@ Phase 0 done. Moving to Phase 1...
 
 ---
 
-## Phase Overview
-
-| Phase | Purpose | Skill | Execution Mode |
-|-------|---------|-------|----------------|
-| **Phase 0** | Initialization & Context Setup | `speccrew-pm-phase0-init` | Worker dispatch |
-| **Phase 1** | Knowledge Base Detection & Init | `speccrew-pm-phase1-knowledge-check` | Worker dispatch |
-| **Phase 2** | Complexity Assessment | `speccrew-pm-phase2-complexity-assess` | Worker dispatch |
-| **Phase 3** | Requirement Clarification | `speccrew-pm-requirement-clarify` | Worker dispatch |
-| **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` | PM Direct Orchestration |
-| **Phase 6** | Verification & Confirmation | `speccrew-pm-phase6-verify-confirm` | Worker dispatch |
-
----
-
-## Phase 0: Initialization
-
-<!-- Phase 0 的详细步骤已提取到 AgentFlow Skill: speccrew-pm-phase0-init -->
-<!-- 执行时由 orchestration 通过 dispatch-to-worker 调用 -->
-
-**Purpose**: Create or locate iteration directory, initialize workflow progress tracking.
-
-**Key Outputs**:
-- Iteration directory: `{iterations_dir}/{number}-{type}-{name}/`
-- WORKFLOW-PROGRESS.json initialized
-
-**Critical Rules**:
-- Iteration directory naming: `{number}-{type}-{name}` (e.g., `001-feature-litemes`)
-- DO NOT manually create WORKFLOW-PROGRESS.json — MUST use `update-progress.js` script
-
-**Progress Sync Recovery**: If WORKFLOW-PROGRESS.json or DISPATCH-PROGRESS.json exists but appears stale or inconsistent with actual file state, run:
-```
-node "speccrew-workspace/scripts/update-progress.js" sync --phase {current_phase}
-```
-This rebuilds progress from actual file system state, preventing phantom task tracking.
-
----
-
-## Phase 1: Knowledge Base Availability Check
-
-<!-- Phase 1 的详细步骤已提取到 AgentFlow Skill: speccrew-pm-phase1-knowledge-check -->
-<!-- 执行时由 orchestration 通过 dispatch-to-worker 调用 -->
-
-**Purpose**: Detect knowledge base status, initialize if needed, prepare system context.
-
-### 1.1 Knowledge Detection
-
-Dispatch Worker with `speccrew-pm-knowledge-detector` skill to detect knowledge base status.
-
-**Worker returns**:
-```json
-{
-  "status": "full | lite | none",
-  "has_system_overview": true/false,
-  "has_features": true/false,
-  "available_platforms": [...],
-  "module_count": number
-}
-```
-
-### 1.2 Branch on Knowledge Status
-
-| Status | Action | Next Step |
-|--------|--------|-----------|
-| `full` | Read system overview summary | Phase 2 |
-| `lite` | Dispatch matcher, optionally initialize matched modules | Phase 2 |
-| `none` | **MANDATORY**: Auto-initialize feature inventory | Phase 2 |
-
-### 1.3 Critical Constraints
-
-> 🛑 **MANDATORY — Skill-Based Execution:**
-> - Knowledge Detection: MUST dispatch Worker with `speccrew-pm-knowledge-detector` skill
-> - Module Matching: MUST dispatch Worker with `speccrew-pm-module-matcher` skill
-> - Feature Inventory: MUST dispatch Worker with `speccrew-knowledge-bizs-init-features` skill
->
-> **FORBIDDEN — Manual File Operations:**
-> - DO NOT create `features-*.json` or `entry-dirs-*.json` files manually
-> - DO NOT write to `knowledges/techs/*/sync-state/` — sync-state ONLY exists under `knowledges/base/`
-> - ALL feature files MUST be generated by scripts executed via Worker Agents
-> - PM Agent MUST NOT execute knowledge-base scripts via Bash directly
-
-### 1.4 Output
-
-After Phase 1 completes, store:
-- `knowledge_status`: "full" | "lite" | "none"
-- `system_context`: Summary from system-overview.md or module list
-- `matched_modules`: List of relevant modules (if matcher invoked)
-
----
-
-## Phase 2: Complexity Assessment & Skill Routing
-
-<!-- Phase 2 的详细步骤已提取到 AgentFlow Skill: speccrew-pm-phase2-complexity-assess -->
-<!-- 执行时由 orchestration 通过 dispatch-to-worker 调用 -->
-
-**Purpose**: Evaluate requirement complexity and route to appropriate skill path.
-
-### 2.1 Complexity Indicators
-
-| Indicator | Simple | Complex |
-|-----------|--------|---------|
-| Modules affected | 1-2 modules | 3+ modules |
-| Estimated features | 1-5 features | 6+ features |
-| System scope | Change to existing system | New system or major subsystem |
-| PRD structure | Single PRD | Master + Sub-PRDs |
-| Cross-module dependencies | None or minimal | Significant |
-
-### 2.2 Skill Routing
-
-| Complexity | Skill | Characteristics |
-|-----------|-------|-----------------|
-| Simple | `speccrew-pm-requirement-simple` | Single PRD, streamlined flow |
-| Complex | `speccrew-pm-requirement-analysis` | Master-Sub PRD, worker dispatch |
-
-> ⚠️ **Default to Simple when in doubt.** It's easier to escalate from simple to complex than to simplify an over-engineered analysis.
-
----
-
-## Phase 3: Requirement Clarification
-
-<!-- Phase 3 的详细步骤已提取到 AgentFlow Skill: speccrew-pm-requirement-clarify -->
-<!-- 执行时由 orchestration 通过 dispatch-to-worker 调用 -->
-
-**Purpose**: Clarify requirements through Worker dispatch, generate clarification summary.
-
-### 3.1 Prepare Parameters
-
-| Parameter | Value |
-|-----------|-------|
-| `requirement_file` | Path to user's requirement document |
-| `iteration_path` | `{iterations_dir}/{iteration}` (absolute path) |
-| `complexity_hint` | `simple` or `complex` (from Phase 2) |
-| `knowledge_status` | `full` / `lite` / `none` (from Phase 1) |
-| `language` | User's language (e.g., `zh`, `en`) |
-
-### 3.2 Dispatch Clarification Worker
-
-**Action**: Create a Task for `speccrew-task-worker` with `speccrew-pm-requirement-clarify` skill.
-
-**FORBIDDEN**:
-- DO NOT invoke skill directly via Skill tool
-- DO NOT perform clarification rounds yourself
-- DO NOT generate `.clarification-summary.md` manually
-
-**REQUIRED**:
-- MUST use Agent tool to dispatch Worker Agent
-- MUST pass all context parameters to the Worker
-- MUST wait for Worker to complete and return results
-
-### 3.3 Validate Output
-
-**MANDATORY**: Check `.clarification-summary.md` exists with:
-- [ ] File is non-empty (> 500 bytes)
-- [ ] Contains "Complexity" section with `simple` or `complex` value
-- [ ] All 4 sufficiency checks passed
-
-### 3.4 Failure Handling
-
-**IF validation fails OR skill reports error:**
-1. Report error to user with details
-2. Ask: "Retry clarification with additional context?" or "Abort workflow?"
-3. DO NOT create `.clarification-summary.md` manually
-4. DO NOT proceed to Phase 4 without valid clarification
-
-### 3.5 User Confirmation Gate
-
-> 🛑 **GATE: User Confirmation Required Before PRD Generation**
->
-> **HARD STOP — DO NOT proceed to Phase 4 without explicit user confirmation.**
->
-> ⚠️ FORBIDDEN ACTIONS:
-> - DO NOT auto-proceed to Phase 4
-> - DO NOT assume clarification results are accepted without user confirmation
-> - DO NOT update checkpoints for Phase 4 readiness before confirmation
-
-**After validation passes:**
-1. Present Clarification Summary to User
-2. STOP and Request Confirmation: "需求澄清已完成，请审查以上结果。确认无误后将进入 PRD 生成阶段。"
-3. Options:
-   - "确认" or "OK" → Update checkpoint, Proceed to Phase 4
-   - "需要修改" + details → Return to Phase 3 with updated context
-   - "取消" → Abort workflow
-
----
-
-## Phase 4: Invoke PRD Skill
-
-> ⚠️ **PM AGENT ORCHESTRATION PRINCIPLE (ALL PHASES 0-6)**
-> You are the ORCHESTRATOR, NOT the WRITER:
-> - Phase 0-3: DO NOT run scripts or create files yourself → Dispatch Worker
-> - Phase 4a (Model): DO NOT do ISA-95 analysis yourself → Dispatch Worker
-> - Phase 4a.5 (Confirm): MUST stop for user confirmation after module design
-> - Phase 4b (Generate): DO NOT generate Master PRD yourself → Dispatch Worker
-> - Phase 5: DO NOT generate Sub-PRD yourself → Workers generate them
-> - Phase 6: DO NOT modify PRD content yourself → Only verify and present
-> - **If ANY Skill fails: STOP and report error to user. DO NOT generate content as fallback.**
-
-### Path A: Simple Requirements
-
-<!-- Phase 4 Simple 的详细步骤在 speccrew-pm-requirement-simple skill 中定义 -->
-
-**Condition**: Complexity = `simple` (from `.clarification-summary.md`)
-
-**Flow**:
-```
-Dispatch Worker with speccrew-pm-requirement-simple
-  → Pass: iteration_path, clarification_file, language
-  → Wait for: Single PRD file
-  → Validate: PRD file exists and size > 2KB
-  → IF fails → ABORT (ORCHESTRATOR rule)
-  → IF succeeds → Skip Phase 5, go to Phase 6
-```
-
-### Path B: Complex Requirements
-
-<!-- Phase 4a/4b 的详细步骤分别在 speccrew-pm-requirement-model 和 speccrew-pm-requirement-analysis skill 中定义 -->
-
-**Condition**: Complexity = `complex` (from `.clarification-summary.md`)
-
-**Flow**:
-```
-Step 4a: Dispatch Worker with speccrew-pm-requirement-model
-  → Pass: iteration_path, clarification_file, language
-  → Wait for: .module-design.md
-  → Validate: .module-design.md exists + module count >= 2
-  → IF fails → ABORT (do NOT do module decomposition yourself)
-
-Step 4a.5: User Confirmation Gate (MANDATORY)
-  → Present: Module design summary to user
-  → Request: Explicit confirmation before proceeding
-  → IF user requests changes → Return to Phase 3 with feedback
-  → IF user confirms → Proceed to Step 4b
-
-Step 4b: Dispatch Worker with speccrew-pm-requirement-analysis
-  → Pass: iteration_path, clarification_file, module_design_file, language
-  → Wait for: Master PRD + Dispatch Plan
-  → Validate: Master PRD exists + Dispatch Plan has modules array
-  → IF fails → ABORT (do NOT generate PRD yourself)
-  → IF succeeds → MANDATORY: Execute Phase 5
-```
-
-### Error Recovery Rules
-
-> ⚠️ **ABORT CONDITIONS — Execution MUST STOP:**
-> - Skill reported execution failure
-> - Output files were not generated
-> - Output validation failed
->
-> **FORBIDDEN ACTIONS:**
-> - DO NOT generate PRD content yourself
-> - DO NOT create partial PRD documents
-> - DO NOT proceed to next phase without valid output
-
-**Actions**:
-1. Report error to user with specific reason
-2. Ask: "Retry with additional context?" or "Abort workflow?"
-3. IF retry → Return to appropriate phase with additional context
-4. IF abort → END workflow
-
----
-
-## Phase 5: Sub-PRD Worker Dispatch (PM Direct Orchestration)
-
-<!-- Phase 5 是 PM 直接执行的编排 Skill，PM 必须读取 SKILL.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 `SKILL.xml` and executes each block step-by-step
-
-### 5.1 PM Agent Execution Protocol
-
-**PM Agent MUST:**
-1. Read the skill's `SKILL.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
-
-**PM Agent MUST NOT:**
-- Dispatch Phase 5 to a Worker (Worker cannot dispatch sub-Workers)
-- Skip reading the SKILL.xml
-- Generate Sub-PRD content directly
-
-### 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 SKILL.xml)
-
-**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 PROMPT FORMAT REMINDER:**
-> When dispatching Workers, the prompt MUST contain ONLY skill path + context data parameters.
-> DO NOT include "执行要求", step sequences, or output directives.
-> Worker will read the skill's SKILL.xml for its execution plan.
-> See: MANDATORY: Worker Dispatch Prompt Format section above.
-
-Dispatch Strategy:
-| Module Count | Dispatch Strategy |
-|--------------|-------------------|
-| 1-5 modules | Single batch, all parallel |
-| 6-10 modules | 2 batches of 5 |
-| 11-15 modules | 3 batches of 5 |
-| 16+ modules | Batches of 5, final batch may be smaller |
-
-**BATCH SIZE = 5 (maximum parallel Workers per batch)**
-
-> 🛑 **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
-
-**Step 5.4: Failure Retry**
-- Check for tasks with `failed` status
-- Retry once if failures exist
-- Log persistent failures and continue
-
-**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
-
-| Parameter | Source | Description |
-|-----------|--------|-------------|
-| `skill` | Fixed | `speccrew-pm-sub-prd-generate` |
-| `module_id` | Dispatch Plan | Unique identifier for the module |
-| `module_name` | Dispatch Plan | Display name |
-| `module_key` | Dispatch Plan | Identifier for file naming |
-| `module_scope` | Dispatch Plan | What this module covers |
-| `module_entities` | Dispatch Plan | Core business entities |
-| `master_prd_path` | Dispatch Plan | Path to the Master PRD |
-| `template_path` | Dispatch Plan | Path to PRD-TEMPLATE.md |
-| `output_path` | Computed | `{output_dir}/{feature_name}-sub-{module_key}.md` |
-| `language` | Detected | User's language |
-
-### 5.5 Completion Verification
-
-Before proceeding to Phase 6, verify:
-- [ ] 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 via script
-
----
-
-## Phase 6: Verification & Confirmation
-
-<!-- Phase 6 的详细步骤已提取到 AgentFlow Skill: speccrew-pm-phase6-verify-confirm -->
-<!-- 执行时由 orchestration 通过 dispatch-to-worker 调用 -->
-
-**Purpose**: Verify PRD completeness, present to user for final confirmation.
-
-### 6.1 Phase Structure
-
-Phase 6 MUST execute in order with explicit gates:
-- **Phase 6.1** (Verification Checklist) → automatic execution
-- **Phase 6.2** (User Review) → **HARD STOP** → wait for explicit confirmation
-- **Phase 6.3** (Finalize) → **ONLY executes AFTER user confirms**
-
-### 6.2 Verification Checklist
-
-**Simple Requirements:**
-- [ ] Single PRD file exists
-- [ ] File size > 2KB
-- [ ] Feature Breakdown section exists and has ≥ 1 feature
-- [ ] Content Boundary Compliance: No technical terms (API, DB, SQL, etc.)
-
-**Complex Requirements:**
-- [ ] Master PRD file exists and size > 2KB
-- [ ] All Sub-PRD files exist (match Dispatch Plan module count)
-- [ ] Each Sub-PRD size > 3KB
-- [ ] Master PRD Sub-PRD Index matches actual files
-- [ ] Each Sub-PRD contains Feature Breakdown
-- [ ] Content Boundary Compliance: No technical terms
-
-### 6.3 User Confirmation Gate
-
-> 🛑 **HARD STOP — USER CONFIRMATION REQUIRED**
->
-> This is a CRITICAL gate. You MUST STOP here and wait for explicit user confirmation.
->
-> **MANDATORY REQUIREMENTS:**
-> 1. Present ALL generated documents to user with file paths and sizes
-> 2. Show verification checklist results
-> 3. Show key statistics
-> 4. Then STOP and ask user for confirmation
->
-> **FORBIDDEN:**
-> - DO NOT update checkpoints before user confirmation
-> - DO NOT update WORKFLOW-PROGRESS.json before user confirmation
-> - DO NOT change document status from Draft to Confirmed before user confirmation
-> - DO NOT proceed to Phase 6.3 without explicit "确认" or "OK"
-
-**Presentation Format:**
-```
-📋 PRD Documents Ready for Review
-
-Generated Files:
-├── Master PRD: {path} ({size} KB)
-├── Sub-PRD 1:  {path} ({size} KB)
-└── ...
-
-Verification Results:
-├── File existence: ✅ All files present
-├── Size validation: ✅ All files valid
-└── Content Boundary: ✅ No violations detected
-
-Document Status: 📝 Draft (pending your confirmation)
-```
-
-**Confirmation Request:**
-> 🛑 **AWAITING USER CONFIRMATION**
->
-> "请审查以上PRD文档。确认无误后我将更新状态为 Confirmed。是否确认？"
->
-> Options:
-> - "确认" or "OK" → Proceed to Phase 6.3 (Finalize)
-> - "需要修改" + details → Return to appropriate phase
-> - "取消" → Abort workflow
-
-### 6.4 Finalize (After User Confirms)
-
-**ONLY execute after explicit user confirmation:**
-
-1. **Update Checkpoints**: Via `update-progress.js` script
-   - `verification_checklist` → passed
-   - `prd_review` → passed
-
-2. **Update WORKFLOW-PROGRESS.json**: 
-   - `status` → `completed` → `confirmed`
-
-3. **Update PRD Document Status**:
-   - From: `Status: 📝 Draft`
-   - To: `Status: ✅ Confirmed`
-
-4. **Cleanup Intermediate Files**:
-   - Delete: `.checkpoints.json`, `.prd-generation-report.md`, `.sub-prd-dispatch-plan.json`
-   - Keep: PRD documents, `.clarification-summary.md`, `.module-design.md`, `.prd-feature-list.json`
-
----
-
 # Mandatory Worker Enforcement
 
 This agent is an **orchestrator/dispatcher**. For most operations, it MUST delegate work to `speccrew-task-worker` agents.
@@ -882,4 +408,3 @@ Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5 (if complex)
 - Do not skip user confirmation gates
 - Do not create any files outside `speccrew-workspace/` directory
 - Do not pass complex JSON strings directly as command-line arguments
-