speccrew 0.7.53 → 0.7.55

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

@@ -122,7 +122,7 @@ This agent MUST execute tasks continuously without unnecessary interruptions.
 | Phase 1 | REGISTRY ONLY | Agent reads .prd-feature-list.json + WORKFLOW-PROGRESS.json only. DO NOT use Glob to discover files |
 | Phase 2 | VERIFY ONLY | Agent verifies file existence only. DO NOT read Feature Spec, API Contract, or techs knowledge content |
 | Phase 2 | KNOWLEDGE-FIRST | MUST load ALL techs knowledge before Phase 3. DO NOT assume technology stack |
-| Phase 3 | SKILL-ONLY | Framework evaluation MUST use speccrew-sd-framework-evaluate skill. Agent MUST NOT evaluate frameworks itself |
+| Phase 3 | WORKER-DISPATCH | Framework evaluation MUST be dispatched to speccrew-task-worker via **Agent tool**. Agent MUST NOT invoke speccrew-sd-framework-evaluate via Skill tool. |
 | Phase 3 | HARD STOP | User must confirm framework decisions before proceeding to Phase 4 |
 | Phase 4 | AGENT-OWNED | DESIGN-OVERVIEW.md generation is Agent responsibility (not skill-dispatched) |
 | Phase 5 | SKILL-ONLY | Platform design workers MUST use platform-specific design skills. Agent MUST NOT write design documents itself |
@@ -429,7 +429,20 @@ Build the parameter template for Phase 3 and Phase 5 Skills:
 
 ## Phase 3: Framework Evaluation (🛑 HARD STOP — User Confirmation Required)
 
-> ⚠️ **SKILL-ONLY RULE**: Framework evaluation MUST be performed by `speccrew-sd-framework-evaluate` skill. Agent MUST NOT perform capability gap analysis or framework recommendations itself.
+> 🛑 **WORKER-DISPATCH RULE**: Framework evaluation MUST be dispatched to `speccrew-task-worker` via **Agent tool**. Agent MUST NOT perform capability gap analysis or framework recommendations itself, and MUST NOT invoke `speccrew-sd-framework-evaluate` via Skill tool.
+
+> 🛑 **CRITICAL: Phase 3 dispatch-to-worker Protocol**
+>
+> When executing Phase 3 (Framework Evaluation):
+> 1. Use **Agent tool** to create a new sub-Agent
+> 2. Specify sub-Agent role as **speccrew-task-worker**
+> 3. Pass skill_path and all context parameters in Task description
+> 4. **Wait for Worker completion** before proceeding
+>
+> **FORBIDDEN**:
+> - ❌ DO NOT use Skill tool to invoke speccrew-sd-framework-evaluate
+> - ❌ DO NOT read feature spec files yourself for framework evaluation
+> - ❌ DO NOT generate framework-evaluation.md yourself
 
 ### 3.1 Invoke Framework Evaluation Skill
 
@@ -444,7 +457,7 @@ Build the parameter template for Phase 3 and Phase 5 Skills:
 | `iteration_path` | `{iterations_dir}/{current}` | Current iteration directory |
 | `output_path` | `{iterations_dir}/{current}/03.system-design/framework-evaluation.md` | Output report path |
 
-**Invocation**: Call the skill directly (not via speccrew-task-worker — framework evaluation is a single coordinated task, not per-Feature).
+**Invocation**: Use **Agent tool** to dispatch `speccrew-task-worker` agent. Pass `skill_path: ${workspace_path}/.speccrew/skills/speccrew-sd-framework-evaluate/SKILL.md` and all context parameters. Even though framework evaluation is a single coordinated task (not per-Feature), it MUST be delegated to a Worker Agent — NOT invoked inline via Skill tool. See workflow.agentflow.xml block P3-B1 for dispatch parameters.
 
 ### 3.2 Validate Skill Output
 
@@ -464,7 +477,7 @@ After skill completes, validate the output:
    - Read error details from Task Completion Report
    - **DO NOT attempt to perform framework evaluation yourself**
    - Report error to user and ask: "Retry?" or "Abort?"
-   - If retry → Re-invoke skill with same or adjusted parameters
+   - If retry → Re-dispatch speccrew-task-worker with same or adjusted parameters
    - If abort → END workflow
 
 ### 3.3 User Confirmation (🛑 HARD STOP)
@@ -509,9 +522,9 @@ Proceed to Phase 4? (Confirm/Cancel)
 - DO NOT proceed to Phase 4 without valid evaluation output
 
 **Recovery Actions**:
-1. Report error to user: "Framework evaluation skill failed: {specific reason}"
+1. Report error to user: "Framework evaluation worker failed: {specific reason}"
 2. Ask user: "Retry with additional context?" or "Abort workflow?"
-3. IF retry → Re-invoke speccrew-sd-framework-evaluate with adjusted parameters
+3. IF retry → Re-dispatch speccrew-task-worker with adjusted parameters
 4. IF abort → END workflow
 
 ## Phase 4: Generate DESIGN-OVERVIEW.md (L1)
@@ -1010,7 +1023,7 @@ Otherwise
 - Phase 0.1: ALWAYS verify Feature Design stage is confirmed before proceeding
 - Phase 0.5: ALWAYS detect IDE directory and verify skills exist before dispatching
 - Phase 2: MUST verify ALL techs knowledge files exist (manifest + platform-specific stacks) before Phase 3
-- Phase 3: MUST use speccrew-sd-framework-evaluate skill for framework evaluation — DO NOT evaluate yourself
+- Phase 3: MUST dispatch speccrew-sd-framework-evaluate via speccrew-task-worker (Agent tool) — DO NOT evaluate yourself and DO NOT invoke via Skill tool
 - Phase 3: User MUST confirm framework decisions (🛑 HARD STOP) before proceeding to Phase 4
 - Phase 4: MUST generate DESIGN-OVERVIEW.md with complete Feature×Platform index BEFORE dispatching platform workers
 - Phase 5: MUST use speccrew-task-worker to dispatch platform-specific design skills for parallel execution (never direct skill invocation for batch)

package/.speccrew/skills/speccrew-sd-design-overview-generate/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: speccrew-sd-design-overview-generate
+version: 1.0.0
+description: Design Overview Generation Skill for System Designer. Reads Feature Registry, techs-manifest platforms, and framework evaluation results to generate a comprehensive DESIGN-OVERVIEW.md with Feature×Platform matrix index. Invoked by System Designer Agent during Phase 4 via worker dispatch.
+tools: Read, Write, Glob, Grep
+---
+
+# Trigger Scenarios
+
+- System Designer Agent dispatches this skill during Phase 4 to generate DESIGN-OVERVIEW.md
+- User requests a design overview document for the current iteration
+- Need to establish a Feature×Platform matrix index before per-platform system design begins
+
+## AgentFlow Definition
+
+<!-- @agentflow: workflow.agentflow.xml -->
+
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `speccrew-workspace/docs/rules/agentflow-spec.md`
+
+## Workflow
+
+## Absolute Constraints
+
+> **These rules apply to ALL steps. Violation = task failure.**
+
+1. **READ-ONLY on Feature Spec and API Contract** — NEVER modify Feature Spec or API Contract documents. Only read for reference.
+2. **READ-ONLY on techs-manifest.json** — NEVER modify the techs manifest. Only read for platform information.
+3. **READ-ONLY on framework-evaluation.md** — NEVER modify the framework evaluation report. Only read for technology decisions.
+4. **Single Output Only** — Only create DESIGN-OVERVIEW.md at the specified output_path. No other files.
+5. **Direct-to-File Output** — Write all content directly to DESIGN-OVERVIEW.md. DO NOT display document content in conversation.
+
+## Step 1: Read Inputs
+
+**Input Parameters** (from agent context):
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `workspace_path` | string | Yes | speccrew-workspace root directory path |
+| `iteration_path` | string | Yes | Current iteration directory path |
+| `feature_registry_path` | string | Yes | Path to .prd-feature-list.json |
+| `techs_manifest_path` | string | Yes | Path to techs-manifest.json |
+| `framework_evaluation_path` | string | Yes | Path to framework-evaluation.md |
+| `output_path` | string | No | Output file path (default: iteration_path/03.system-design/DESIGN-OVERVIEW.md) |
+
+Read in order:
+
+1. **Read .prd-feature-list.json** — Extract features array:
+   - `feature_id` (e.g., F-CRM-01) or `module_name` for legacy format
+   - `feature_name` or `module_name`
+   - `feature_spec` path
+   - `api_contract` path
+   - `module`
+   - `type`
+
+2. **Read techs-manifest.json** — Extract platforms array:
+   - `platform_id` (e.g., web-react, backend-nodejs)
+   - `friendly_name`
+   - `tech_stack`
+
+3. **Read framework-evaluation.md** — Extract Technology Decisions:
+   - Framework evaluation results
+   - New dependencies introduced (if any)
+   - Version constraints
+
+## Step 2: Build Feature×Platform Matrix
+
+For each feature × platform combination, generate one matrix row:
+
+| Field | Source |
+|-------|--------|
+| `feature_id` | feature.feature_id (or "-" for legacy format) |
+| `feature_name` | feature.feature_name (or feature.module_name for legacy) |
+| `platform` | platform.friendly_name |
+| `platform_id` | platform.platform_id |
+| `skill` | Map platform_id prefix → speccrew-sd-{type} (see below) |
+| `design_directory` | {platform_id}/{feature_id}-{feature_name}-design.md (new) or {platform_id}/{module}-design.md (legacy) |
+| `status` | Always "pending" |
+
+### Platform ID Prefix → Skill Mapping
+
+| Platform ID Prefix | Target Skill |
+|-------------------|--------------|
+| web-* | speccrew-sd-frontend |
+| backend-* | speccrew-sd-backend |
+| mobile-* | speccrew-sd-mobile |
+| desktop-* | speccrew-sd-desktop |
+
+### Legacy Format Compatibility
+
+If a feature does NOT have a Feature ID (no "F-" prefix):
+- Feature ID column displays `-`
+- Use `module_name` as Feature Name
+- Design Directory uses `{platform_id}/{module_name}-design.md` (legacy format)
+
+## Step 3: Generate DESIGN-OVERVIEW.md
+
+Write the design overview document to `output_path`.
+
+### Document Structure
+
+```markdown
+# System Design Overview - {Iteration Name}
+
+## 1. Design Scope
+
+- **Iteration**: {iteration_identifier}
+- **Platforms**: {platform_list}
+- **Features**: {count} features discovered
+
+### 1.1 Feature List
+
+| Feature ID | Feature Name | Feature Spec | API Contract |
+|------------|--------------|--------------|--------------|
+| (from feature registry, one row per feature) |
+
+> **Legacy Format Compatibility**: If file uses legacy format (no Feature ID), Feature ID column shows `-`, using module name as Feature Name
+
+## 2. Technology Decisions
+
+(from framework-evaluation.md - Phase 3 results)
+
+- Framework evaluation results
+- New dependencies introduced (if any)
+- Version constraints
+
+## 3. Platform Design Index
+
+| Feature ID | Feature Name | Platform | Platform ID | Skill | Design Directory | Status |
+|------------|--------------|----------|-------------|-------|------------------|--------|
+| (Feature × Platform matrix from Step 2) |
+
+> **Notes**:
+> - New Format: Design Directory contains `{feature-id}-{feature-name}` (e.g., `F-CRM-01-customer-list-design.md`)
+> - Legacy Format: Design Directory uses `{module}-design.md`
+
+## 4. Feature Summary (Optional - when Feature count > 5)
+
+### 4.1 Feature by Module
+
+| Module | Feature Count | Feature IDs |
+|--------|---------------|-------------|
+| (group features by module) |
+
+### 4.2 Feature Type Distribution
+
+| Type | Count | Features |
+|------|-------|----------|
+| (group features by type) |
+
+## 5. Cross-Platform Concerns
+
+- Shared data structures
+- Cross-platform API contracts
+- Authentication/authorization strategy
+- Error handling conventions
+
+## 6. Design Constraints
+
+- API Contract is READ-ONLY — do not modify
+- All pseudo-code must use actual framework syntax from techs knowledge
+- Each module design document maps 1:1 to a Feature Spec function
+```
+
+## Step 4: Validate Output
+
+After writing DESIGN-OVERVIEW.md, verify:
+
+- [ ] File exists at output_path
+- [ ] Contains "## 1. Design Scope" section
+- [ ] Contains "## 2. Technology Decisions" section
+- [ ] Contains "## 3. Platform Design Index" table
+- [ ] Platform Design Index covers all Feature × Platform combinations
+- [ ] Feature count matches feature registry
+- [ ] Platform count matches techs-manifest
+- [ ] All index entries have status "pending"
+
+## Step 5: Output Task Completion Report
+
+After validation, output:
+
+```
+--- TASK COMPLETION REPORT ---
+Task: Design Overview Generation
+Status: SUCCESS
+Output: {output_path}
+Features: {feature_count}
+Platforms: {platform_count}
+Matrix Entries: {feature_count × platform_count}
+--- END REPORT ---
+```
+
+If any step fails:
+
+```
+--- TASK COMPLETION REPORT ---
+Task: Design Overview Generation
+Status: FAILED
+Error: {specific error description}
+Failed At: Step {N}
+--- END REPORT ---
+```
+
+## OUTPUT EFFICIENCY RULES
+
+When executing this skill:
+
+1. **Direct-to-File Output**: All design overview content MUST be written directly to DESIGN-OVERVIEW.md
+2. **Minimal Conversation Output**: Only output:
+   - Block execution announcements (1 line each): `[Block XX] Building matrix...`
+   - Error messages requiring attention
+   - Task Completion Report (final summary)
+3. **FORBIDDEN in conversation**:
+   - Full document sections or drafts
+   - Feature × Platform matrix tables
+   - Feature list tables
+   - Technology decision excerpts longer than 2 lines
+4. **Rationale**: Workers run in batch mode. Displaying design content in conversation wastes context window and provides no value since content goes to file anyway.
+
+# Key Rules
+
+| Rule | Description |
+|------|-------------|
+| **FORBIDDEN: Input Modification** | Do NOT modify feature specs, API contracts, techs-manifest, or framework-evaluation |
+| **FORBIDDEN: Extra Files** | Do NOT create any files other than DESIGN-OVERVIEW.md |
+| **FORBIDDEN: Conversation Output** | Do NOT display DESIGN-OVERVIEW content in conversation — write directly to file |
+| **MANDATORY: Complete Matrix** | Platform Design Index MUST cover ALL Feature × Platform combinations |
+| **MANDATORY: Pending Status** | ALL Platform Design Index entries MUST have status "pending" |
+
+# Checklist
+
+- [ ] .prd-feature-list.json read and features array extracted
+- [ ] techs-manifest.json read and platforms array extracted
+- [ ] framework-evaluation.md read and technology decisions extracted
+- [ ] Feature format detected (new or legacy)
+- [ ] Feature × Platform matrix built with all combinations
+- [ ] Platform ID prefix correctly mapped to target skills
+- [ ] DESIGN-OVERVIEW.md generated with all required sections
+- [ ] Feature Summary section included only when feature count > 5
+- [ ] Output validated against checklist
+- [ ] Task Completion Report output

package/.speccrew/skills/speccrew-sd-design-overview-generate/workflow.agentflow.xml

@@ -0,0 +1,161 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<workflow id="sd-design-overview-generate-main" status="pending" version="1.0.0" desc="Design Overview Generation workflow">
+
+  <!-- ============================================================
+       Input Parameters Definition
+       ============================================================ -->
+  <block type="input" id="I1" desc="Workflow input parameters">
+    <field name="workspace_path" required="true" type="string" desc="speccrew-workspace root directory path"/>
+    <field name="iteration_path" required="true" type="string" desc="Current iteration directory path"/>
+    <field name="feature_registry_path" required="true" type="string" desc="Path to .prd-feature-list.json"/>
+    <field name="techs_manifest_path" required="true" type="string" desc="Path to techs-manifest.json"/>
+    <field name="framework_evaluation_path" required="true" type="string" desc="Path to framework-evaluation.md"/>
+    <field name="output_path" required="false" type="string" desc="Output file path (default: iteration_path/03.system-design/DESIGN-OVERVIEW.md)"/>
+  </block>
+
+  <!-- ============================================================
+       Global Rules
+       ============================================================ -->
+  <block type="rule" id="R1" level="forbidden" desc="Input File Protection">
+    <field name="text">DO NOT modify any input files (feature specs, API contracts, techs-manifest.json, framework-evaluation.md)</field>
+  </block>
+
+  <block type="rule" id="R2" level="forbidden" desc="Single Output Only">
+    <field name="text">DO NOT create any files other than DESIGN-OVERVIEW.md at the specified output_path</field>
+  </block>
+
+  <block type="rule" id="R3" level="mandatory" desc="Direct-to-File Output">
+    <field name="text">Write all design content directly to DESIGN-OVERVIEW.md. DO NOT display document content in conversation.</field>
+  </block>
+
+  <block type="rule" id="R4" level="mandatory" desc="Complete Matrix Coverage">
+    <field name="text">Platform Design Index MUST cover ALL Feature × Platform combinations. No feature or platform may be omitted.</field>
+  </block>
+
+  <!-- ============================================================
+       Main Processing Sequence
+       ============================================================ -->
+  <sequence id="S1" name="Design Overview Generation" status="pending" desc="Generate DESIGN-OVERVIEW.md with Feature×Platform matrix">
+
+    <!-- Step 1: Read Feature Registry -->
+    <block type="task" id="B1" action="read-file" status="pending" desc="Read Feature Registry (.prd-feature-list.json)">
+      <field name="path" value="${feature_registry_path}"/>
+      <field name="output" var="feature_registry"/>
+    </block>
+
+    <!-- Step 2: Read Techs Manifest -->
+    <block type="task" id="B2" action="read-file" status="pending" desc="Read Techs Manifest (techs-manifest.json)">
+      <field name="path" value="${techs_manifest_path}"/>
+      <field name="output" var="techs_manifest"/>
+    </block>
+
+    <!-- Step 3: Read Framework Evaluation -->
+    <block type="task" id="B3" action="read-file" status="pending" desc="Read Framework Evaluation Report">
+      <field name="path" value="${framework_evaluation_path}"/>
+      <field name="output" var="framework_evaluation"/>
+    </block>
+
+    <!-- Step 4: Determine Feature Format -->
+    <block type="gateway" id="G1" mode="exclusive" desc="Check Feature ID format">
+      <branch test="${feature_registry.features[0].feature_id} exists and starts with 'F-'" name="New Format">
+        <block type="event" id="E1" action="log" level="info" desc="New format detected">
+          <field name="message">Feature registry uses new format with F- prefixed Feature IDs</field>
+        </block>
+        <field name="format" var="feature_format" value="new"/>
+      </branch>
+      <branch default="true" name="Legacy Format">
+        <block type="event" id="E2" action="log" level="info" desc="Legacy format detected">
+          <field name="message">Feature registry uses legacy format (no Feature IDs)</field>
+        </block>
+        <field name="format" var="feature_format" value="legacy"/>
+      </branch>
+    </block>
+
+    <!-- Step 5: Build Feature × Platform Matrix -->
+    <block type="task" id="B4" action="compute" status="pending" desc="Build Feature×Platform matrix index">
+      <field name="input" value="${feature_registry.features}">${techs_manifest.platforms}</field>
+      <field name="logic">
+        For each feature in feature_registry.features:
+          For each platform in techs_manifest.platforms:
+            - feature_id: feature.feature_id (or "-" for legacy)
+            - feature_name: feature.feature_name (or feature.module_name for legacy)
+            - platform: platform.friendly_name
+            - platform_id: platform.platform_id
+            - skill: map platform_id prefix → speccrew-sd-{type}
+              (web-* → frontend, backend-* → backend, mobile-* → mobile, desktop-* → desktop)
+            - design_directory: {platform_id}/{feature_id}-{feature_name}-design.md (new)
+              or {platform_id}/{module_name}-design.md (legacy)
+            - status: "pending"
+      </field>
+      <field name="output" var="platform_design_index"/>
+    </block>
+
+    <!-- Step 6: Check if Feature Summary needed -->
+    <block type="gateway" id="G2" mode="exclusive" desc="Feature count check for optional summary">
+      <branch test="${feature_registry.features.length} > 5" name="Large Feature Set">
+        <block type="event" id="E3" action="log" level="info" desc="Large feature set">
+          <field name="message">Feature count > 5, including Feature Summary section</field>
+        </block>
+        <field name="include_summary" var="include_feature_summary" value="true"/>
+      </branch>
+      <branch default="true" name="Small Feature Set">
+        <block type="event" id="E4" action="log" level="info" desc="Small feature set">
+          <field name="message">Feature count <= 5, skipping Feature Summary section</field>
+        </block>
+        <field name="include_summary" var="include_feature_summary" value="false"/>
+      </branch>
+    </block>
+
+    <!-- Step 7: Generate DESIGN-OVERVIEW.md -->
+    <block type="task" id="B5" action="write-file" status="pending" desc="Generate DESIGN-OVERVIEW.md with all sections">
+      <field name="path">${output_path}</field>
+      <field name="encoding">utf8</field>
+      <field name="content">
+        Section 1: Design Scope (iteration, platforms, features count, Feature List table)
+        Section 2: Technology Decisions (from framework_evaluation)
+        Section 3: Platform Design Index (from platform_design_index matrix)
+        Section 4: Feature Summary (ONLY if include_feature_summary == true)
+          - 4.1 Feature by Module
+          - 4.2 Feature Type Distribution
+        Section 5: Cross-Platform Concerns
+        Section 6: Design Constraints
+      </field>
+    </block>
+
+    <!-- Step 8: Validate Output -->
+    <block type="checkpoint" id="CP1" name="design_overview_validation" desc="Validate DESIGN-OVERVIEW.md completeness">
+      <field name="conditions">
+        file_exists: ${output_path} exists,
+        has_design_scope: contains "## 1. Design Scope",
+        has_tech_decisions: contains "## 2. Technology Decisions",
+        has_platform_index: contains "## 3. Platform Design Index",
+        matrix_complete: index row count == feature_count × platform_count,
+        all_pending: all status entries are "pending"
+      </field>
+    </block>
+
+    <!-- Step 9: Output Task Completion Report -->
+    <block type="event" id="E5" action="log" level="info" desc="Output completion report">
+      <field name="message">--- TASK COMPLETION REPORT ---
+Task: Design Overview Generation
+Status: SUCCESS
+Output: ${output_path}
+Features: ${feature_registry.features.length}
+Platforms: ${techs_manifest.platforms.length}
+Matrix Entries: ${feature_registry.features.length * techs_manifest.platforms.length}
+--- END REPORT ---</field>
+    </block>
+
+  </sequence>
+
+  <!-- ============================================================
+       Output Results
+       ============================================================ -->
+  <block type="output" id="O1" desc="Workflow output results">
+    <field name="design_overview_path" value="${output_path}" type="string" desc="Path to generated DESIGN-OVERVIEW.md"/>
+    <field name="feature_count" from="${feature_registry.features.length}" type="number" desc="Number of features in the matrix"/>
+    <field name="platform_count" from="${techs_manifest.platforms.length}" type="number" desc="Number of platforms in the matrix"/>
+    <field name="matrix_entries" from="${feature_registry.features.length * techs_manifest.platforms.length}" type="number" desc="Total Feature×Platform combinations"/>
+  </block>
+
+</workflow>

package/package.json

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