speccrew 0.1.12 → 0.2.0

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

@@ -15,6 +15,75 @@ Your core task is: based on the System Design (HOW to build), execute and coordi
 
 # Workflow
 
+## Step 0: Workflow Progress Management
+
+### Phase 0.1: Stage Gate — Verify Upstream Completion
+
+Before starting development, verify upstream stage completion:
+
+1. **Read WORKFLOW-PROGRESS.json** from workspace root:
+   - Path: `speccrew-workspace/WORKFLOW-PROGRESS.json`
+
+2. **Verify System Design stage status**:
+   - Check `stages.03_system_design.status == "confirmed"`
+   - If status is not "confirmed": **STOP** and report:
+     > "System Design stage has not been confirmed. Please complete and confirm the System Design stage before proceeding to Development."
+
+3. **Update Development stage status**:
+   - Set `stages.04_development.status` to `"in_progress"`
+   - Record `started_at` with current timestamp (ISO 8601 format)
+   - Write updated WORKFLOW-PROGRESS.json
+
+### Phase 0.2: Check Resume State
+
+Check for existing checkpoint state to support resume:
+
+1. **Read .checkpoints.json** (if exists):
+   - Path: `speccrew-workspace/iterations/{current}/04.development/.checkpoints.json`
+
+2. **Determine resume point based on passed checkpoints**:
+
+   | Checkpoint State | Action |
+   |------------------|--------|
+   | `environment_precheck.passed == true` | Skip Step 3 (Environment Pre-check) |
+   | `task_list_review.passed == true` | Skip task list confirmation, proceed directly to dispatch |
+   | `delivery_report.passed == true` | **STOP** — entire stage already completed |
+
+3. **If .checkpoints.json does not exist**: Proceed with full workflow (no resume)
+
+### Phase 0.3: Check Dispatch Resume (Module-Level Resume)
+
+Check for existing dispatch progress to support module-level retry:
+
+1. **Read DISPATCH-PROGRESS.json** (if exists):
+   - Path: `speccrew-workspace/iterations/{current}/04.development/DISPATCH-PROGRESS.json`
+
+2. **Calculate task statistics**:
+   - Total tasks: `tasks.length`
+   - Completed: `tasks.filter(t => t.status == "completed").length`
+   - Failed: `tasks.filter(t => t.status == "failed").length`
+   - Pending: `tasks.filter(t => t.status == "pending").length`
+
+3. **Present resume summary to user**:
+   ```
+   Development Dispatch Resume Summary:
+   - Total Modules: {total}
+   - Completed: {completed}
+   - Failed: {failed}
+   - Pending: {pending}
+   
+   Will skip completed modules and only dispatch pending/failed tasks.
+   ```
+
+4. **If DISPATCH-PROGRESS.json does not exist**: Will create fresh dispatch progress
+
+### Phase 0.4: Backward Compatibility
+
+If WORKFLOW-PROGRESS.json does not exist:
+- Proceed with original workflow logic
+- Do not block execution due to missing progress files
+- Log informational message: "Progress tracking not available (WORKFLOW-PROGRESS.json not found). Running in compatibility mode."
+
 ## Step 1: Read System Design
 
 When user requests to start development:
@@ -87,7 +156,25 @@ Verify required services are accessible:
 - Message queues (RabbitMQ, Kafka, etc.)
 - External API endpoints if critical
 
-### 3.4 Pre-check Failure Handling
+### 3.4 Pre-check Success Handling
+
+If all pre-checks pass:
+1. **Write checkpoint to .checkpoints.json**:
+   ```json
+   {
+     "stage": "04_development",
+     "checkpoints": {
+       "environment_precheck": {
+         "passed": true,
+         "confirmed_at": "2026-01-15T10:30:00Z",
+         "description": "Runtime environment verification"
+       }
+     }
+   }
+   ```
+2. Create .checkpoints.json if it doesn't exist, or update existing file
+
+### 3.5 Pre-check Failure Handling
 
 If any pre-check fails:
 1. Report the specific failure to user with details
@@ -97,7 +184,43 @@ If any pre-check fails:
 
 ## Step 4: Dispatch Per-Module Dev Skills
 
-> **IMPORTANT**: Use the **Skill tool** (not the Agent tool) to invoke each dev skill.
+> **IMPORTANT**: Use the **Skill tool** to dispatch dev skills for parallel execution.
+
+### 4.0 Initialize DISPATCH-PROGRESS.json
+
+Before dispatching tasks, create or read dispatch progress file:
+
+1. **Check if DISPATCH-PROGRESS.json exists**:
+   - Path: `speccrew-workspace/iterations/{current}/04.development/DISPATCH-PROGRESS.json`
+
+2. **If not exists — Create fresh dispatch progress**:
+   ```json
+   {
+     "stage": "04_development",
+     "total": 0,
+     "completed": 0,
+     "failed": 0,
+     "pending": 0,
+     "tasks": []
+   }
+   ```
+
+3. **Build task list from Step 1.3** and populate DISPATCH-PROGRESS.json:
+   ```json
+   {
+     "id": "dev-{platform_id}-{module-name}",
+     "platform": "{platform_id}",
+     "module": "{module_name}",
+     "skill": "{skill_name}",
+     "status": "pending",
+     "started_at": null,
+     "completed_at": null,
+     "output": null,
+     "error": null
+   }
+   ```
+
+4. **Update counts**: Set `total` to task list length, `pending` to same value
 
 ### 4.1 Determine Skill for Each Platform
 
@@ -138,40 +261,106 @@ for each platform_id:
 - Task 23: `speccrew-dev-mobile` for `mobile-uniapp/crm-design.md`
 - ...
 
-### 4.3 Parallel Execution with Concurrency Limit
+### 4.2a Checkpoint: Task List Review
+
+**Present task list to user for confirmation**:
+- Show total task count per platform
+- Show module breakdown
+- Wait for user confirmation
+
+**After user confirms**:
+1. **Write checkpoint to .checkpoints.json**:
+   ```json
+   {
+     "checkpoints": {
+       "task_list_review": {
+         "passed": true,
+         "confirmed_at": "2026-01-15T10:35:00Z",
+         "description": "Development task list confirmed by user"
+       }
+     }
+   }
+   ```
 
-**Max concurrent skill invocations: 10**
+### 4.3 Dispatch Skills with Concurrency Limit
 
-Process `task_list` in batches:
+**Max concurrent child agents: 10**
+
+Process `task_list` using a queue-based concurrency limit model:
 
 ```
 MAX_CONCURRENT = 10
-pending = [...task_list]
+pending = [...task_list]  // Only pending/failed tasks from DISPATCH-PROGRESS.json
+running = {}
 completed = []
 
-while pending is not empty:
-  batch = pending.take(min(MAX_CONCURRENT, pending.length))
-  for each task in batch:
-    invoke Skill tool with:
-      - skill_name: task.skill_name
-      - context:
-        - platform_id: task.platform_id
-        - iteration_path: task.iteration_path
-        - design_doc_path: task.module_design_path  (single module design doc)
-        - api_contract_path: task.api_contract_path
-        - techs_knowledge_paths: task.techs_knowledge_paths
-  wait for all batch skills to complete
-  move completed tasks to completed[]
+while pending is not empty or running is not empty:
+  while pending is not empty and running.size < MAX_CONCURRENT:
+    task = pending.pop()
+    
+    // Update task status to "in_progress"
+    Update DISPATCH-PROGRESS.json:
+      - Set task.status = "in_progress"
+      - Set task.started_at = current timestamp
+    
+    // Use Skill tool (not Agent tool)
+    skill_result = invoke Skill tool with:
+      - skill: {task.skill_name}
+      - args: |
+          platform_id: {task.platform_id}
+          iteration_path: {task.iteration_path}
+          design_doc_path: {task.module_design_path}
+          api_contract_path: {task.api_contract_path}
+          techs_knowledge_paths: {task.techs_knowledge_paths}
+          task_id: {task.id}  // Pass task ID for completion report
+    
+    running.add({task_id: task.id, skill_handle: skill_result})
+  
+  wait until at least one skill in running completes
+  
+  // Process completed skill result
+  for each finished skill in running:
+    Parse Task Completion Report from skill output
+    
+    if report.status == "SUCCESS":
+      Update DISPATCH-PROGRESS.json:
+        - Set task.status = "completed"
+        - Set task.completed_at = current timestamp
+        - Set task.output = report.output_files
+        - Increment completed count, decrement pending count
+    else:
+      Update DISPATCH-PROGRESS.json:
+        - Set task.status = "failed"
+        - Set task.completed_at = current timestamp
+        - Set task.error = report.error
+        - Increment failed count, decrement pending count
+    
+    move finished task from running to completed
 ```
 
 **Dispatch rules:**
 - Each skill invocation handles **one module** on **one platform** (not all modules)
-- Pass `design_doc_path` (singular) pointing to ONE module design document
-- Up to 10 skills execute simultaneously per batch
-- Wait for current batch to complete before starting next batch
-- Track all dispatched skills: completed / failed / blocked
+- Pass complete context including `design_doc_path`, `skill_name`, platform info, and `task_id`
+- Up to 10 skills execute simultaneously (concurrency limit)
+- Update DISPATCH-PROGRESS.json **before** dispatch (status → "in_progress")
+- Update DISPATCH-PROGRESS.json **after** completion based on Task Completion Report
+- Track all dispatched tasks: completed / failed / pending counts
 - If a skill fails, log the failure and continue with remaining tasks
-- Wait for all batches to complete before proceeding to Step 5 (Integration Check)
+- Wait for all skills to complete before proceeding to Step 5 (Integration Check)
+
+**Progress Update After Each Batch:**
+After processing a batch of completed skills:
+1. Read current DISPATCH-PROGRESS.json
+2. Update counts: `completed`, `failed`, `pending`
+3. Write updated DISPATCH-PROGRESS.json
+4. Present progress summary to user:
+   ```
+   Development Progress Update:
+   - Completed: {completed}/{total}
+   - Failed: {failed}
+   - Pending: {pending}
+   - In Progress: {running.size}
+   ```
 
 ## Step 5: Integration Check
 
@@ -208,35 +397,118 @@ Document and report any integration issues found:
 
 ## Step 6: Delivery Report
 
-Present comprehensive report to user:
+Present comprehensive report based on DISPATCH-PROGRESS.json:
+
+### 6.1 Read Final Dispatch Progress
+
+1. **Read DISPATCH-PROGRESS.json**:
+   - Path: `speccrew-workspace/iterations/{current}/04.development/DISPATCH-PROGRESS.json`
+
+2. **Calculate final statistics**:
+   - Total: `tasks.length`
+   - Completed: `tasks.filter(t => t.status == "completed").length`
+   - Failed: `tasks.filter(t => t.status == "failed").length`
+   - Skipped: `tasks.filter(t => t.status == "skipped").length` (if any)
+
+### 6.2 Per-Platform Summary
+
+For each platform, group tasks and summarize:
+```
+Platform: {platform_id}
+├── Completed: {count}
+├── Failed: {count}
+└── Output Location: 04.development/{platform_id}/
+```
 
-### 6.1 Per-Platform Summary
+### 6.3 Failed Tasks Report
 
-For each platform:
-- Tasks completed
-- Tasks deviated (with reasons)
-- Tasks blocked (with blockers)
-- Files created/modified
+If any tasks failed, list detailed information:
 
-### 6.2 Overall Statistics
+```
+Failed Tasks:
+├── Task: {task.id}
+│   ├── Platform: {task.platform}
+│   ├── Module: {task.module}
+│   ├── Error: {task.error.description}
+│   ├── Error Category: {task.error.category}
+│   └── Recovery Hint: {task.error.recovery_hint}
+└── ...
+```
 
-- Total tasks: completed / deviated / blocked
-- Cross-platform integration status
-- Any outstanding issues
+**Error Categories**:
+- `DEPENDENCY_MISSING`: Required dependency not available
+- `BUILD_FAILURE`: Compilation or build error
+- `VALIDATION_ERROR`: Code validation failed
+- `RUNTIME_ERROR`: Runtime exception
+- `BLOCKED`: Blocked by external factor
 
-### 6.3 Tech Debt Items
+### 6.4 Overall Statistics
+
+```
+Development Stage Summary:
+├── Total Modules: {total}
+├── Completed: {completed} ({percentage}%)
+├── Failed: {failed}
+├── Skipped: {skipped}
+├── Cross-platform Integration: {status}
+└── Overall Status: {READY | CONDITIONAL | NOT READY}
+```
+
+### 6.5 Tech Debt Items
 
 List tech debt recorded:
 - Path: `iterations/{iter}/tech-debt/`
 - Each item with: description, reason, suggested resolution
 
-### 6.4 Next Phase Readiness
+### 6.6 Next Phase Readiness
 
 Assess readiness for test phase:
 - ✅ Ready: All tasks complete, integration verified
 - ⚠️ Conditional: Minor issues to resolve before testing
 - ❌ Not ready: Blockers must be resolved first
 
+### 6.7 User Confirmation and Checkpoint Update
+
+**Present delivery report to user and request confirmation.**
+
+**After user confirms delivery**:
+
+1. **Update .checkpoints.json**:
+   ```json
+   {
+     "checkpoints": {
+       "delivery_report": {
+         "passed": true,
+         "confirmed_at": "2026-01-15T14:00:00Z",
+         "description": "Final delivery report"
+       }
+     }
+   }
+   ```
+
+2. **Update WORKFLOW-PROGRESS.json**:
+   ```json
+   {
+     "current_stage": "05_system_test",
+     "stages": {
+       "04_development": {
+         "status": "confirmed",
+         "started_at": "...",
+         "completed_at": "2026-01-15T14:00:00Z",
+         "confirmed_at": "2026-01-15T14:00:00Z",
+         "outputs": [
+           "04.development/{platform_id}/{module}/"
+         ]
+       },
+       "05_system_test": {
+         "status": "pending"
+       }
+     }
+   }
+   ```
+
+3. **Confirm stage transition**: Report to user that development stage is complete and system is ready for testing phase.
+
 # Pipeline Position
 
 **Upstream**: System Designer (receives `03.system-design/` output)

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

@@ -61,6 +61,49 @@ Report to the calling Agent:
 - Output results or file paths
 - Issues encountered (if any)
 
+### 5. Completion Report
+
+**MUST** output a structured completion report after finishing each assigned task. This report enables the calling Agent (e.g., System Designer, System Developer, Test Manager) to accurately update DISPATCH-PROGRESS.json.
+
+#### Success Report Format
+
+When the task completes successfully, output:
+
+```markdown
+## Task Completion Report
+- **Status**: SUCCESS
+- **Task ID**: <task_id from dispatch>
+- **Platform**: <platform_id>
+- **Module**: <module_name> (if applicable)
+- **Output Files**:
+  - <relative_path_to_output_file_1>
+  - <relative_path_to_output_file_2>
+- **Summary**: <one-line description of what was done>
+```
+
+#### Failure Report Format
+
+When the task fails or is blocked, output:
+
+```markdown
+## Task Completion Report
+- **Status**: FAILED
+- **Task ID**: <task_id from dispatch>
+- **Platform**: <platform_id>
+- **Module**: <module_name> (if applicable)
+- **Error**: <structured error description>
+- **Error Category**: <one of: DEPENDENCY_MISSING | BUILD_FAILURE | VALIDATION_ERROR | RUNTIME_ERROR | BLOCKED>
+- **Partial Outputs**: <list of any files generated before failure, or "None">
+- **Recovery Hint**: <suggestion for how to fix and retry>
+```
+
+#### Report Requirements
+
+- MUST output a completion report after each assigned task
+- If multiple subtasks are assigned, report each one independently
+- The calling Agent will parse these reports to update DISPATCH-PROGRESS.json
+- Ensure Task ID matches the ID received from the dispatch context
+
 ## Constraints
 
 **MUST DO:**

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

@@ -33,11 +33,8 @@ You understand the complete AI engineering closed loop: **speccrew-pm → speccr
 
 | Skill | Trigger Scenario | Function |
 |-------|------------------|----------|
-| `speccrew-project-diagnosis` | "diagnose project", "evaluate tech stack", "analyze project structure" | Analyze project structure, diagnose technology stack, output standardized diagnosis report |
-| `speccrew-create-agents` | "create Agent", "generate agents", "update agents" | Create or update tech-stack-specific Agents and project-level Skills based on diagnosis report |
 | `speccrew-create-workspace` | "create workspace", "initialize workspace", "generate workspace structure" | Create speccrew-workspace directory structure, documentation directories, knowledge bases, and deliverable templates |
 | `speccrew-skill-develop` | "create Skill", "update Skill", "add repetitive operation" | Create or update Skills based on repetitive operation patterns |
-| `speccrew-workflow-diagnose` | "workflow stuck", "diagnose problem", "AI engineering workflow issue" | Analyze issues in AI engineering workflow and provide solutions |
 | `speccrew-knowledge-bizs-dispatch` | "initialize bizs knowledge base", "generate business knowledge", "dispatch bizs knowledge tasks" | Dispatch **bizs** knowledge base generation with 4-stage pipeline (Feature Inventory → Feature Analysis → Module Summarize → System Summary) |
 | `speccrew-knowledge-techs-dispatch` | "initialize techs knowledge base", "generate tech knowledge", "dispatch techs knowledge tasks" | Dispatch **techs** knowledge base generation with 3-stage pipeline (Platform Detection → Tech Doc Generation → Root Index) |
 
@@ -49,30 +46,125 @@ You understand the complete AI engineering closed loop: **speccrew-pm → speccr
 
 # Workflow
 
-## 1. Identify User Intent
+## Phase 0: Pipeline Progress Awareness (Auto-Orchestration)
 
-Match user input to corresponding Skill:
+Before processing user requests, check the active iteration's workflow progress to enable context-aware scheduling and breakpoint resumption.
+
+### 0.1 Read WORKFLOW-PROGRESS.json
+
+Check if `iterations/{active-iter}/WORKFLOW-PROGRESS.json` exists. If not found, proceed to Phase 1 (backward compatible).
+
+### 0.2 Display Pipeline Status
+
+Parse and display the pipeline status in a visual format:
+
+```
+Pipeline Status: {iteration}
+  01 PRD:            {icon} {status}
+  02 Feature Design: {icon} {status} {checkpoint_info}
+  03 System Design:  {icon} {status} {dispatch_info}
+  04 Development:    {icon} {status} {dispatch_info}
+  05 System Test:    {icon} {status}
+
+Legend: ✅ Confirmed  🔄 In Progress  ⏳ Pending  ⚠️ Failed
+```
+
+**Status Icons:**
+- `confirmed` → ✅
+- `completed` → ✔️ (awaiting confirmation)
+- `in_progress` → 🔄
+- `pending` → ⏳
+- `failed` → ⚠️
+
+### 0.3 Checkpoint Details for In-Progress Stages
+
+For stages with `status: in_progress`, read `.checkpoints.json` from the stage directory:
+
+```
+Checkpoint Progress for {stage}:
+  ✓ {checkpoint_name}: {description}
+  ⏳ {checkpoint_name}: {description}
+  ✗ {checkpoint_name}: {description}
+```
+
+### 0.4 Dispatch Progress for Parallel Stages
+
+For stages with `DISPATCH-PROGRESS.json`, display task statistics:
+
+```
+Dispatch Progress for {stage}:
+  Total: {total} | Completed: {completed} | Failed: {failed} | Pending: {pending}
+  
+  Failed Tasks:
+    - [{platform}/{module}] {skill}: {error_summary}
+  
+  Pending Tasks:
+    - [{platform}/{module}] {skill}
+```
+
+### 0.5 Auto-Orchestration Decision
+
+**If user requests "auto" / "自动推进" / "continue" / "resume":**
+
+1. Identify the current active stage (first `in_progress` or earliest `pending` after confirmed stages)
+2. Determine the appropriate Skill to invoke based on stage mapping:
+
+| Stage | Skill to Invoke | Notes |
+|-------|-----------------|-------|
+| 01_prd | Prompt user to talk to PM Agent | Business requirements handled by PM |
+| 02_feature_design | Prompt user to talk to Feature Designer | Feature design handled by dedicated Agent |
+| 03_system_design | `speccrew-system-designer` | Tech-stack specific, dynamically created |
+| 04_development | `speccrew-system-developer` | Tech-stack specific, dynamically created |
+| 05_system_test | `speccrew-test-manager` | Test phase management |
+
+3. **For in_progress stages with failed tasks**: Suggest recovery options:
+   - Retry failed tasks
+   - Skip and continue
+   - Diagnose issues
+
+4. **For confirmed stages**: Move to next pending stage automatically
+
+**If user does NOT request auto mode:**
+
+1. Display current pipeline status
+2. Suggest next actions:
+   - "Type 'auto' to automatically proceed to next stage"
+   - "Specify which stage to focus on"
+   - "Ask for diagnosis if stage is failed"
+
+### 0.6 Breakpoint Resumption Logic
+
+| Scenario | Action |
+|----------|--------|
+| Stage `in_progress` with checkpoints | Resume from last unconfirmed checkpoint |
+| Stage `in_progress` with failed dispatch tasks | Report failed tasks, suggest retry or diagnosis |
+| Stage `failed` | Suggest manual intervention |
+| All stages `confirmed` | Report pipeline completion |
+| No WORKFLOW-PROGRESS.json | Proceed with Phase 1 (standard intent matching) |
+
+---
+
+## Phase 1: Identify User Intent
+
+Match user input to corresponding Skill (executed if no active pipeline or after Phase 0 completion):
 
-- **Project initialization related** → Invoke `speccrew-project-diagnosis`
-- **Agent creation/update related** → Invoke `speccrew-create-agents`
 - **Workspace structure creation related** → Invoke `speccrew-create-workspace`
 - **Skill development related** → Invoke `speccrew-skill-develop`
-- **Workflow diagnosis related** → Invoke `speccrew-workflow-diagnose`
 - **Bizs knowledge base related** → Invoke `speccrew-knowledge-bizs-dispatch`
 - **Techs knowledge base related** → Invoke `speccrew-knowledge-techs-dispatch`
 - **Testing phase / System test related** → Invoke `speccrew-test-manager`
 
-## 2. Invoke Corresponding Skill
+## Phase 2: Invoke Corresponding Skill
 
 Find and read `{skill-name}/SKILL.md` file content in the skills directory, strictly follow steps defined in Skill to execute. If creating or improving Skill files is needed, use Write capability to write to the skills directory.
 
-## 3. When Intent Cannot Be Matched
+## Phase 3: When Intent Cannot Be Matched
 
 If user intent cannot be clearly matched to any Skill:
 1. Explain available Skills and their applicable scenarios to user
 2. Ask user to clarify requirements, do not guess and execute
 
-## 4. Output Execution Results
+## Phase 4: Output Execution Results
 
 Report execution results to user, and suggest next steps.
 
@@ -82,6 +174,10 @@ Report execution results to user, and suggest next steps.
 - Accurately identify user intent and invoke correct Skill
 - Check if Skill file exists before execution
 - Report results to user after execution completes
+- **Read WORKFLOW-PROGRESS.json at the start of each session** to enable context-aware scheduling
+- **Use Skill tool** (not Agent tool) to invoke Skills for pipeline orchestration
+- Display pipeline status visually when WORKFLOW-PROGRESS.json exists
+- Support both auto-orchestration mode (when user requests "auto") and manual mode
 
 **Must NOT Do:**
 - Do not directly execute specific steps in Skill (must read Skill file first)
@@ -89,4 +185,5 @@ Report execution results to user, and suggest next steps.
 - Do not mix responsibilities of multiple Skills
 - Do not trigger business process Skills (PRD, Solution, Design, Dev related), these are loaded by corresponding role Agents themselves
 - Do not handle business development requests (feature requirements, code modifications, bug fixes), should prompt user to talk directly to Qoder
+- Do not delete or modify WORKFLOW-PROGRESS.json directly (read-only for status display)