speccrew 0.7.32 → 0.7.34

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

@@ -54,6 +54,7 @@ Phase 4: API Contract Generation
 | ALL | ABORT ON FAILURE | If any skill invocation fails → STOP and report. Do NOT attempt to generate content manually as fallback |
 | ALL | SCRIPT ENFORCEMENT | All .checkpoints.json and WORKFLOW-PROGRESS.json updates via update-progress.js script. Manual JSON creation FORBIDDEN |
 | ALL | NAME LOCK | After Phase 2 Feature List is confirmed, feature_name is immutable. All Skills MUST use the exact parameter value for output filenames. Name translation or substitution is FORBIDDEN |
+| ALL | ANTI-SCRIPT | Agent MUST NOT create custom automation scripts. DO NOT generate helper scripts (.sh, .ps1, .js) for batch processing or progress checking. Use ONLY the standard update-progress.js commands in documented workflow order. |
 
 ## MANDATORY WORKER ENFORCEMENT
 
@@ -130,6 +131,9 @@ This agent MUST execute tasks continuously without unnecessary interruptions.
 4. DO NOT ask for confirmation before generating output files
 5. DO NOT warn about "large number of files" — proceed with generation
 6. DO NOT offer "Should I proceed with the remaining items?"
+7. DO NOT create custom scripts to automate batch processing — use ONLY update-progress.js
+8. DO NOT write helper scripts for progress checking or task management
+9. DO NOT suggest "Let me create a script to handle this more efficiently"
 
 ### When to Pause (ONLY these cases)
 
@@ -162,19 +166,36 @@ This agent MUST execute tasks continuously without unnecessary interruptions.
 > - If context window is exhausted, STOP and report progress — do NOT skip ahead
 > - When resuming, read DISPATCH-PROGRESS.json and continue from where you left off
 >
-> **Phase Transition Rule:**
-> Phase 4 CANNOT start until DISPATCH-PROGRESS.json shows counts.pending == 0 for Phase 3.
-> This is a programmatic check, not a suggestion.
+> **Phase 3→4 Transition Rule:**
+> Phase 4 CANNOT start until:
+> 1. DISPATCH-PROGRESS.json (02.feature-design/) shows counts.pending == 0
+> 2. All Feature Spec files exist in output directory
+> This is enforced by workflow XML validation gates — Agent MUST NOT skip or manually override.
+>
+> **Phase 4 Progress File:**
+> Phase 4 uses a SEPARATE progress file: `03.api-contract/DISPATCH-PROGRESS.json`
+> This ensures Phase 3 completion status is preserved.
 
 ## ABORT CONDITIONS
 
 > **If ANY of the following conditions occur, the Feature Designer Agent MUST immediately STOP the workflow and report to user.**
 
 1. **Skill Invocation Failure**: Any skill call returns error → STOP. Do NOT generate content manually.
-2. **Script Execution Failure**: `node ... update-progress.js` fails → STOP. Do NOT manually create/edit JSON files.
+2. **Script Execution Failure**: `node ... update-progress.js` exits with non-zero status or output contains "Error:" → STOP immediately.
+   - Do NOT attempt to continue batch processing
+   - Do NOT ask user for alternative options (A/B/C)
+   - Do NOT suggest "skip to next phase" or "process only some features"
+   - Report exact error message, failed task ID, and failed command
 3. **Missing Intermediate Artifacts**: Feature Spec output missing before Phase 4 → STOP.
 4. **User Rejection**: User rejects Feature List, batch design summary, or Joint Confirmation → STOP, ask for specific revision requirements.
 5. **Worker Batch Failure**: If >50% workers in a batch fail → STOP entire batch, report to user.
+6. **Progress File Read Failure**: Cannot read DISPATCH-PROGRESS.json → STOP.
+
+> 🛑 **FORBIDDEN ON SCRIPT FAILURE**:
+> - ❌ "Due to script errors, I suggest we..."
+> - ❌ "Let me offer you options: 1. Continue 2. Skip 3. ..."
+> - ❌ "进度更新脚本频繁失败，建议..."
+> - ✅ ONLY correct response: "STOP: update-progress.js failed with [error]. Task: [id]. Command: [cmd]."
 
 ## TIMESTAMP INTEGRITY
 
@@ -208,7 +229,7 @@ This agent MUST execute tasks continuously without unnecessary interruptions.
 ## Phase 0: Workflow Progress Management
 
 > **Path Variables** (provided by caller as absolute paths):
-> - `workspace_path`: Absolute path to speccrew-workspace directory
+> - `workspace_path`: **MANDATORY absolute path** — Worker MUST use this for ALL script calls. Example: `D:\dev\RuoYi-Vue3-FastAPI\speccrew-workspace`
 > - `update_progress_script`: `{workspace_path}/scripts/update-progress.js`
 > - `iterations_dir`: `{workspace_path}/iterations`
 
@@ -743,7 +764,7 @@ If **2+ Feature Specs** in registry:
    # Step 1: Write tasks JSON to temp file inside iteration directory
    # Create .tasks-temp.json with the task array content
    # Step 2: Initialize with --tasks-file
-   node {update_progress_script} init --file {iterations_dir}/{iteration}/02.feature-design/DISPATCH-PROGRESS.json --stage 02_feature_design_api_contract --tasks-file {iterations_dir}/{iteration}/02.feature-design/.tasks-temp.json
+   node {update_progress_script} init --file {iterations_dir}/{iteration}/03.api-contract/DISPATCH-PROGRESS.json --stage 02_feature_design_api_contract --tasks-file {iterations_dir}/{iteration}/02.feature-design/.tasks-temp.json
    # Step 3: Delete .tasks-temp.json after successful init
    ```
 
@@ -765,7 +786,7 @@ If **2+ Feature Specs** in registry:
 
 3. **Wait for batch completion**, update progress per worker:
    ```bash
-   node {update_progress_script} update-task --file {iterations_dir}/{iteration}/02.feature-design/DISPATCH-PROGRESS.json --task-id {feature_id} --status completed
+   node {update_progress_script} update-task --file {iterations_dir}/{iteration}/03.api-contract/DISPATCH-PROGRESS.json --task-id {feature_id} --status completed
    ```
 
 4. **Update `.checkpoints.json`** for each completed Feature:
@@ -783,7 +804,7 @@ When any API Contract worker reports failure:
 
 1. **Update status**:
    ```bash
-   node {update_progress_script} update-task --file {iterations_dir}/{iteration}/02.feature-design/DISPATCH-PROGRESS.json --task-id {feature_id} --status failed --error "[Phase 4] {error_message}"
+   node {update_progress_script} update-task --file {iterations_dir}/{iteration}/03.api-contract/DISPATCH-PROGRESS.json --task-id {feature_id} --status failed --error "[Phase 4] {error_message}"
    ```
 
 2. **Continue batch**: Do NOT stop entire batch for single failure. Complete remaining workers.

package/.speccrew/skills/speccrew-fd-feature-design/SKILL.md

@@ -52,6 +52,14 @@ This skill applies ISA-95 Stages 1-6 as an internal thinking framework:
 4. **FORBIDDEN: Skip Checkpoint B** — User confirmation required before generating documents (unless `skip_checkpoint=true`)
 5. **FORBIDDEN: Rename features** — Output filename MUST use the exact `feature_name` parameter value. DO NOT translate, abbreviate, paraphrase, or substitute with alternative names found in PRD content. The `feature_name` parameter is the SINGLE SOURCE OF TRUTH for file naming.
 
+> **CRITICAL: Script Path Rule**
+> ALL update-progress.js commands MUST use absolute paths with `{workspace_path}`:
+> ```
+> node "{workspace_path}/scripts/update-progress.js" update-task --file "{workspace_path}/iterations/..." ...
+> ```
+> NEVER use relative paths like `node scripts/update-progress.js` or `cd ... ; node scripts/...`
+> The Worker may execute from project root directory, NOT from speccrew-workspace directory.
+
 ⛔ **ABSOLUTE PROHIBITION — Phase B Content Filling:**
 - NEVER use `create_file` to rewrite or recreate the document after Step 5 skeleton creation
 - NEVER abandon `search_replace` mid-way and switch to `create_file`
@@ -178,8 +186,8 @@ If `skip_analysis_checkpoint=false` (default):
 After user confirms (or if skipped):
 
 ```bash
-node speccrew-workspace/scripts/update-progress.js write-checkpoint \
-  --file speccrew-workspace/iterations/{iteration_id}/02.feature-design/.checkpoints.json \
+node "{workspace_path}/scripts/update-progress.js" write-checkpoint \
+  --file "{workspace_path}/iterations/{iteration_id}/02.feature-design/.checkpoints.json" \
   --stage 02_feature_design \
   --checkpoint function_decomposition \
   --passed true
@@ -493,8 +501,8 @@ Document: `User Action → Frontend Response → Backend API Call`
 After user confirms (or if skipped):
 
 ```bash
-node speccrew-workspace/scripts/update-progress.js write-checkpoint \
-  --file speccrew-workspace/iterations/{iteration_id}/02.feature-design/.checkpoints.json \
+node "{workspace_path}/scripts/update-progress.js" write-checkpoint \
+  --file "{workspace_path}/iterations/{iteration_id}/02.feature-design/.checkpoints.json" \
   --stage 02_feature_design \
   --checkpoint feature_design_review \
   --passed true
@@ -654,8 +662,8 @@ Verify all Mermaid diagrams follow compliance rules:
 Set final checkpoint status:
 
 ```bash
-node speccrew-workspace/scripts/update-progress.js write-checkpoint \
-  --file speccrew-workspace/iterations/{iteration_id}/02.feature-design/.checkpoints.json \
+node "{workspace_path}/scripts/update-progress.js" write-checkpoint \
+  --file "{workspace_path}/iterations/{iteration_id}/02.feature-design/.checkpoints.json" \
   --stage 02_feature_design \
   --checkpoint feature_spec_review \
   --passed true

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

@@ -310,6 +310,25 @@
       <field name="message">📊 Phase 4: API Contract Generation</field>
     </block>
 
+    <!-- Read Phase 3 completion status -->
+    <block type="task" id="P4-V1" action="run-script" status="pending" desc="Read Feature Design completion status">
+      <field name="command">node ${workspace_root}/scripts/update-progress.js read --file ${iteration_path}/02.feature-design/DISPATCH-PROGRESS.json --overview</field>
+      <field name="output" var="phase3_progress"/>
+    </block>
+
+    <block type="gateway" id="P4-V2" mode="exclusive" desc="Verify Phase 3 completed before Phase 4">
+      <branch test="${phase3_progress.counts.pending} > 0" name="Phase 3 Incomplete">
+        <block type="event" id="P4-V3" action="abort" desc="Phase 3 not complete">
+          <field name="message">ABORT: Phase 3 (Feature Design) has ${phase3_progress.counts.pending} pending tasks. Cannot start Phase 4.</field>
+        </block>
+      </branch>
+      <branch default="true" name="Phase 3 Complete">
+        <block type="event" id="P4-V4" action="log" desc="Phase 3 verified">
+          <field name="message">✅ Phase 3 complete. Proceeding to Phase 4 (API Contract).</field>
+        </block>
+      </branch>
+    </block>
+
     <!-- Phase 4.1: Dispatch Mode Decision -->
     <block type="gateway" id="P4-G1" mode="exclusive" desc="Dispatch mode for API Contract">
       
@@ -338,7 +357,7 @@
 
         <!-- Initialize DISPATCH-PROGRESS.json for API Contract stage -->
         <block type="task" id="P4-B2" action="run-script" status="pending" desc="Initialize API contract dispatch">
-          <field name="command">node ${workspace_root}/scripts/update-progress.js init --file ${iteration_path}/02.feature-design/DISPATCH-PROGRESS.json --stage 02_feature_design_api_contract --tasks-file ${iteration_path}/02.feature-design/.tasks-temp.json</field>
+          <field name="command">node ${workspace_root}/scripts/update-progress.js init --file ${iteration_path}/03.api-contract/DISPATCH-PROGRESS.json --stage 02_feature_design_api_contract --tasks-file ${iteration_path}/02.feature-design/.tasks-temp.json</field>
         </block>
 
         <!-- MANDATORY: Dispatch prompt must contain ONLY skill path + context data parameters.
@@ -362,12 +381,27 @@
           </block>
 
           <block type="task" id="P4-B4" action="run-script" status="pending" desc="Update worker progress">
-            <field name="command">node ${workspace_root}/scripts/update-progress.js update-task --file ${iteration_path}/02.feature-design/DISPATCH-PROGRESS.json --task-id ${item.feature_id} --status ${worker_status}</field>
+            <field name="command">node ${workspace_root}/scripts/update-progress.js update-task --file ${iteration_path}/03.api-contract/DISPATCH-PROGRESS.json --task-id ${item.feature_id} --status ${worker_status}</field>
           </block>
         </block>
       </branch>
     </block>
 
+    <!-- Read Phase 4 completion summary -->
+    <block type="task" id="P4-B5a" action="run-script" status="pending" desc="Read API Contract completion summary">
+      <field name="command">node ${workspace_root}/scripts/update-progress.js read --file ${iteration_path}/03.api-contract/DISPATCH-PROGRESS.json --overview</field>
+      <field name="output" var="api_contract_progress"/>
+    </block>
+
+    <block type="gateway" id="P4-G2" mode="exclusive" desc="Check API Contract dispatch status">
+      <branch test="${api_contract_progress.counts.failed} > ${api_contract_progress.counts.total} / 2" name="Majority Failed">
+        <block type="event" id="P4-E-ABORT" action="abort" desc="API Contract batch failure threshold exceeded">
+          <field name="message">ABORT: More than 50% of API Contract tasks failed (${api_contract_progress.counts.failed}/${api_contract_progress.counts.total}).</field>
+        </block>
+      </branch>
+      <branch default="true" name="Acceptable"/>
+    </block>
+
     <!-- Phase 4.4: Joint Confirmation -->
     <block type="checkpoint" id="P4-CP1" name="api_contract_joint" desc="Joint confirmation gate">
       <field name="required" value="true"/>

package/package.json

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

package/workspace-template/scripts/update-progress.js

@@ -35,6 +35,7 @@
  *      --output <text>         Task output (used when completed)
  *      --error <text>          Error message (used when failed)
  *      --error-category <cat>  Error category (used when failed)
+ *      --metadata <json>       Metadata JSON string to merge into task
  *
  * 4. update-counts - Force recalculate counts
  *    node update-progress.js update-counts --file <path>
@@ -252,7 +253,8 @@ function parseArgs() {
         confirmedAt: null,
         featuresDir: null,
         platforms: null,
-        force: false
+        force: false,
+        metadata: null
     };
 
     // First argument is the command
@@ -357,6 +359,10 @@ function parseArgs() {
             case '-Matcher-Result':
                 result.matcherResult = args[++i];
                 break;
+            case '--metadata':
+            case '-Metadata':
+                result.metadata = args[++i];
+                break;
         }
     }
 
@@ -619,6 +625,16 @@ function cmdUpdateTask(args) {
             }
         }
 
+        // Handle metadata (merge into task)
+        if (args.metadata) {
+            try {
+                const metadataObj = JSON.parse(args.metadata);
+                task.metadata = { ...task.metadata, ...metadataObj };
+            } catch (e) {
+                outputError(`Failed to parse metadata JSON: ${e.message}`);
+            }
+        }
+
         // Update task
         data.tasks[taskIndex] = task;
         data.updated_at = now;