speccrew 0.7.33 → 0.7.35

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. If a required temp file (.tasks-temp.json) is missing, this indicates a workflow orchestration gap — follow the XML workflow's regeneration step, do NOT implement workarounds with ad-hoc commands. |
 
 ## 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,9 +166,15 @@ 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
 
@@ -746,15 +756,33 @@ If **2+ Feature Specs** in registry:
 > Worker will read the skill's workflow.agentflow.xml for its execution plan.
 > See: MANDATORY: Worker Dispatch Prompt Format section above.
 
+### Phase 4: API Contract — Task File Management
+
+⚠️ **CRITICAL: .tasks-temp.json Regeneration**
+
+Phase 3 deletes `.tasks-temp.json` after init. Phase 4 MUST regenerate it before init:
+
+1. Read `{iteration_path}/02.feature-design/DISPATCH-PROGRESS.json` (Phase 3 results)
+2. Extract ALL task IDs from the tasks array
+3. Build flat JSON array: `[{"id":"F-M01-01"},{"id":"F-M01-02"},...]`
+4. Write to `{iteration_path}/03.api-contract/.tasks-temp.json`
+5. Run init: `node {workspace_path}/scripts/update-progress.js init --file {iteration_path}/03.api-contract/DISPATCH-PROGRESS.json --stage 02_feature_design_api_contract --tasks-file {iteration_path}/03.api-contract/.tasks-temp.json`
+6. Delete `.tasks-temp.json` after successful init
+
+**DO NOT**:
+- Run ad-hoc PowerShell/Bash commands to parse `.prd-feature-list.json`
+- Create custom scripts to build task lists
+- Skip the init step and manually edit DISPATCH-PROGRESS.json
+
 1. **Initialize DISPATCH-PROGRESS.json for API Contract stage**:
 
    > ⚠️ Use `--tasks-file` instead of `--tasks` to avoid PowerShell JSON parsing issues.
 
    ```bash
-   # Step 1: Write tasks JSON to temp file inside iteration directory
-   # Create .tasks-temp.json with the task array content
+   # Step 1: Read Phase 3 DISPATCH-PROGRESS.json and extract all task IDs
+   # Build flat JSON array: [{"id":"F-XXX"},...] and write to .tasks-temp.json
    # 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}/03.api-contract/.tasks-temp.json
    # Step 3: Delete .tasks-temp.json after successful init
    ```
 
@@ -776,7 +804,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:
@@ -794,7 +822,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/agents/speccrew-task-worker.md

@@ -65,6 +65,13 @@ When executing design or document generation skills:
 - Only output brief block execution announcements
 - This is especially critical in batch mode where multiple Workers run simultaneously
 
+### FILE ENCODING
+
+ALL file operations MUST use UTF-8 encoding explicitly:
+- When creating files via tools: ensure UTF-8 (most IDE tools default to UTF-8)
+- When writing via Node.js: always pass `'utf8'` as encoding parameter
+- NEVER rely on system default encoding — Chinese Windows defaults to GBK which corrupts Unicode characters
+
 **FORBIDDEN output in conversation during design tasks:**
 - ASCII wireframes / UI prototypes
 - Mermaid diagrams (these go in the file only)

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">
       
@@ -336,9 +355,15 @@
           <field name="text">DO NOT invoke speccrew-fd-api-contract directly</field>
         </block>
 
+        <!-- Phase 4.1a: Regenerate tasks file from Phase 3 completed features -->
+        <block type="task" id="P4-B1c" action="analyze" status="pending" desc="Build API Contract task list from Phase 3 DISPATCH-PROGRESS.json">
+          <field name="text">Read ${iteration_path}/02.feature-design/DISPATCH-PROGRESS.json. Extract all task IDs (regardless of status). Build a flat JSON array: [{"id":"F-M01-01"},{"id":"F-M01-02"},...]. Write this array to ${iteration_path}/03.api-contract/.tasks-temp.json</field>
+          <field name="output" var="api_contract_tasks_file"/>
+        </block>
+
         <!-- 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}/03.api-contract/.tasks-temp.json</field>
         </block>
 
         <!-- MANDATORY: Dispatch prompt must contain ONLY skill path + context data parameters.
@@ -362,12 +387,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/.speccrew/skills/speccrew-pm-sub-prd-generate/SKILL.md

@@ -201,6 +201,14 @@ IF verification fails:
 > **Purpose:** Separate feature data from dispatch plan into dedicated `.prd-feature-list.json` file.
 > Each Sub-PRD Worker writes its module's features upon completion.
 
+> **CRITICAL: UTF-8 Encoding**
+> 
+> When writing ANY file (JSON, Markdown, or other text files), you MUST ensure UTF-8 encoding:
+> - Use `create_file` tool (which defaults to UTF-8) for file creation
+> - If using Node.js scripts: `fs.writeFileSync(path, content, 'utf8')`
+> - NEVER rely on system default encoding (may be GBK on Chinese Windows)
+> - This applies to ALL output files including `.prd-feature-list.json`
+
 ### 5.1 Determine Feature List File Path
 
 ```

package/.speccrew/skills/speccrew-pm-sub-prd-generate/workflow.agentflow.xml

@@ -190,6 +190,7 @@
 
     <block type="task" id="B17" action="write-file" desc="Update feature list file">
       <field name="path" value="${feature_list_path}"/>
+      <field name="encoding">utf8</field>
       <field name="merge">true</field>
       <field name="entry" value="${feature_list_entry}"/>
       <field name="output" var="feature_list_updated"/>

package/package.json

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