speccrew 0.7.61 → 0.7.63

package/.speccrew/skills/speccrew-sd-backend/SKILL.xml

@@ -0,0 +1,542 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<workflow id="sd-backend-main" status="pending" version="1.0" desc="Backend System Design workflow">
+
+  <!-- ============================================================
+       Input Parameters Definition
+       ============================================================ -->
+  <block type="input" id="I1" desc="Workflow input parameters">
+    <field name="feature_id" required="false" type="string" desc="Feature identifier, e.g., F-CRM-01. If provided, use new naming format"/>
+    <field name="feature_name" required="true" type="string" desc="Feature name, e.g., customer-list"/>
+    <field name="platform_id" required="true" type="string" desc="Target platform, e.g., backend-spring, backend-nestjs"/>
+    <field name="iteration_path" required="true" type="string" desc="Absolute path to iteration directory"/>
+    <field name="workspace_path" required="true" type="string" desc="Absolute path to speccrew-workspace"/>
+    <field name="task_id" required="false" type="string" desc="Task identifier in DISPATCH-PROGRESS.json. Used for status tracking"/>
+    <field name="skip_confirmation" required="false" type="boolean" default="false" desc="When true, skip Checkpoint A user confirmation (used in batch dispatch mode)"/>
+    <field name="skip_index_generation" required="false" type="boolean" default="false" desc="When true, skip Step 5 INDEX.md generation (INDEX.md will be generated by orchestrator after all workers complete)"/>
+    <field name="index_only" required="false" type="boolean" default="false" desc="When true, skip Steps 1-4 and ONLY execute Step 5 (INDEX.md generation). Used after all platform workers complete"/>
+    <field name="dispatch_progress_file" required="false" type="string" desc="Path to DISPATCH-PROGRESS.json. If provided, worker updates its own task status on completion"/>
+    <field name="update_progress_script" required="false" type="string" desc="Path to update-progress.js script"/>
+  </block>
+
+  <!-- ============================================================
+       Global Constraints
+       ============================================================ -->
+  <block type="rule" id="R1" level="forbidden" desc="Document creation constraints">
+    <field name="text">NEVER use create_file to write design documents or INDEX directly</field>
+    <field name="text">Documents MUST be created by copying template then filling with search_replace</field>
+    <field name="text">create_file produces truncated output on large files</field>
+  </block>
+
+  <block type="rule" id="R2" level="forbidden" desc="Full-file rewrite prohibition">
+    <field name="text">NEVER replace entire document content in single operation</field>
+    <field name="text">ALWAYS use targeted search_replace on specific sections</field>
+  </block>
+
+  <block type="rule" id="R3" level="mandatory" desc="Template-first workflow">
+    <field name="text">Copy template MUST execute before fill sections</field>
+    <field name="text">Skipping copy and writing content directly is FORBIDDEN</field>
+  </block>
+
+  <block type="rule" id="R4" level="mandatory" desc="Actual framework syntax">
+    <field name="text">All pseudo-code MUST use actual framework/library syntax from techs knowledge</field>
+    <field name="text">NOT generic pseudo-code</field>
+    <field name="text">Include actual import statements</field>
+    <field name="text">Use actual ORM and transaction patterns from conventions</field>
+  </block>
+
+  <block type="rule" id="R5" level="forbidden" desc="TODO/FIXME placeholders">
+    <field name="text">Design documents MUST contain complete implementation logic</field>
+    <field name="text">Do NOT use TODO, FIXME, HACK, or any placeholder comments</field>
+    <field name="text">Every method, validation rule, and business logic MUST be fully specified with actual pseudocode</field>
+  </block>
+
+  <block type="rule" id="R6" level="mandatory" desc="Output filename pattern">
+    <field name="text">Output filename MUST follow pattern: {feature_id}-{feature_name}-design.md</field>
+    <field name="text">Omitting feature_id or using alternative naming is FORBIDDEN</field>
+  </block>
+
+  <block type="rule" id="R7" level="mandatory" desc="Mermaid for all diagrams">
+    <field name="text">ALL module structures, interaction flows, and entity relationship diagrams MUST use Mermaid syntax</field>
+    <field name="text">Use graph TB, sequenceDiagram, flowchart, erDiagram</field>
+    <field name="text">Plain text ASCII diagrams are FORBIDDEN for these sections</field>
+  </block>
+
+  <block type="rule" id="R8" level="mandatory" desc="API route consistency">
+    <field name="text">All API routes in design document MUST exactly match routes defined in API Contract</field>
+    <field name="text">Before writing any route, READ the API Contract and copy routes verbatim</field>
+    <field name="text">Do NOT invent or modify routes</field>
+  </block>
+
+  <block type="rule" id="R9" level="mandatory" desc="Cross-feature dependency marking">
+    <field name="text">When referencing functionality from another Feature, MUST explicitly mark as [DEPENDENCY: F-XXX-NNN]</field>
+    <field name="text">Define a degradation strategy for when that Feature is not yet implemented</field>
+  </block>
+
+  <block type="rule" id="R10" level="mandatory" desc="Status markers required">
+    <field name="text">Use [EXISTING], [MODIFIED], [NEW] markers for all modules, services, and entities</field>
+  </block>
+
+  <block type="rule" id="R11" level="mandatory" desc="Follow techs conventions">
+    <field name="text">Naming, directory structure, patterns must follow techs knowledge</field>
+    <field name="text">Layer structure follows conventions-design.md</field>
+    <field name="text">ORM patterns follow conventions-data.md</field>
+  </block>
+
+  <block type="rule" id="R12" level="mandatory" desc="API Contract is READ-ONLY">
+    <field name="text">Do NOT modify API Contract</field>
+    <field name="text">Stop and report if issues found in API Contract</field>
+  </block>
+
+  <block type="rule" id="R13" level="mandatory" desc="Migration strategy required">
+    <field name="text">Database design must include migration strategy, not just final schema</field>
+    <field name="text">Document migration files and rollback plans</field>
+  </block>
+
+  <block type="rule" id="R14" level="mandatory" desc="Explicit transaction boundaries">
+    <field name="text">Transaction boundaries must be explicitly marked in design</field>
+    <field name="text">Use actual framework transaction annotations from conventions-data.md</field>
+  </block>
+
+  <block type="rule" id="R15" level="mandatory" desc="Exception code mapping">
+    <field name="text">Exception handling must map to API Contract error codes</field>
+    <field name="text">Use actual exception classes from techs knowledge</field>
+  </block>
+
+  <block type="rule" id="R16" level="mandatory" desc="Mermaid compatibility">
+    <field name="text">Use only basic node definitions: A[text content]</field>
+    <field name="text">No HTML tags, no nested subgraphs, no direction keyword, no style definitions</field>
+    <field name="text">Use standard graph TB/LR, flowchart TD/LR, or erDiagram syntax only</field>
+  </block>
+
+  <!-- ============================================================
+       Main Processing Sequence
+       ============================================================ -->
+  <sequence id="S1" name="Backend System Design" status="pending" desc="Generate backend detailed design documents">
+
+    <!-- Gateway: index_only conditional -->
+    <block type="gateway" id="G0" mode="exclusive" desc="Check if index_only mode">
+      <branch test="${index_only} == true" name="Index only - skip to Step 5">
+        <block type="event" id="E0" action="log" level="info" desc="index_only mode active">
+          <field name="message">index_only=true, skipping Steps 1-4 and jumping directly to Step 5 (INDEX.md generation)</field>
+        </block>
+      </branch>
+      <branch default="true" name="Full workflow">
+
+    <!-- Step 1: Read Inputs -->
+    <block type="task" id="B1" action="read-file" desc="Read Feature Spec document">
+      <field name="path">${iteration_path}/02.feature-design/${feature_id}-${feature_name}-feature-spec.md</field>
+      <field name="fallback_path">${iteration_path}/02.feature-design/${feature_name}-feature-spec.md</field>
+      <field name="output" var="feature_spec"/>
+    </block>
+
+    <block type="task" id="B2" action="read-file" desc="Read API Contract">
+      <field name="path">${iteration_path}/03.api-contract/${feature_id}-${feature_name}-api-contract.md</field>
+      <field name="fallback_path">${iteration_path}/03.api-contract/${feature_name}-api-contract.md</field>
+      <field name="output" var="api_contract"/>
+    </block>
+
+    <!-- Read Techs Knowledge -->
+    <block type="task" id="B3" action="read-file" desc="Read tech-stack.md">
+      <field name="path">${workspace_path}/knowledges/techs/${platform_id}/tech-stack.md</field>
+      <field name="output" var="tech_stack"/>
+    </block>
+
+    <block type="task" id="B4" action="read-file" desc="Read architecture.md">
+      <field name="path">${workspace_path}/knowledges/techs/${platform_id}/architecture.md</field>
+      <field name="output" var="architecture"/>
+    </block>
+
+    <block type="task" id="B5" action="read-file" desc="Read conventions-design.md">
+      <field name="path">${workspace_path}/knowledges/techs/${platform_id}/conventions-design.md</field>
+      <field name="output" var="conventions_design"/>
+    </block>
+
+    <block type="task" id="B6" action="read-file" desc="Read conventions-dev.md">
+      <field name="path">${workspace_path}/knowledges/techs/${platform_id}/conventions-dev.md</field>
+      <field name="output" var="conventions_dev"/>
+    </block>
+
+    <block type="task" id="B7" action="read-file" desc="Read conventions-data.md">
+      <field name="path">${workspace_path}/knowledges/techs/${platform_id}/conventions-data.md</field>
+      <field name="output" var="conventions_data"/>
+    </block>
+
+    <!-- Step 2: Analyze Existing Code Structure -->
+    <block type="task" id="B8" action="analyze" desc="Analyze backend codebase structure">
+      <field name="analysis_targets">
+        - Controller/Router layer structure — Understand routing patterns and naming conventions
+        - Service layer organization — Identify service boundaries and reuse opportunities
+        - Repository/DAO layer patterns — Review data access patterns
+        - Entity/Model definitions — Understand existing data models
+        - Middleware stack — Identify cross-cutting concerns
+        - Exception handling patterns — Review error handling approach
+        - Database migration structure — Understand migration naming and structure
+        - Naming conventions — Ensure consistency with existing code
+      </field>
+      <field name="output" var="codebase_analysis"/>
+    </block>
+
+    <!-- Step 3: Extract Functions from Feature Spec -->
+    <block type="task" id="B9" action="analyze" desc="Extract backend functions from Feature Spec">
+      <field name="input" value="${feature_spec}">${api_contract}</field>
+      <field name="extraction_rules">
+        - Parse Feature Spec Section 2.N pattern
+        - Each Feature Spec typically contains 3-8 functions (fine-grained format)
+        - Extract API interfaces from backend part
+        - Extract data access requirements
+        - Extract business logic flow
+        - Extract cross-module dependencies
+        - Mark each function as [EXISTING], [MODIFIED], or [NEW]
+      </field>
+      <field name="output" var="extracted_functions"/>
+    </block>
+
+    <!-- Checkpoint A: Function Extraction Confirmation -->
+    <block type="gateway" id="G1" mode="exclusive" desc="Handle Checkpoint A - skip_confirmation gateway">
+      <branch test="${skip_confirmation} == true" name="Skip confirmation - auto proceed">
+        <block type="event" id="E1_skip" action="log" level="info" desc="Skipping Checkpoint A">
+          <field name="message">skip_confirmation=true, logging function extraction summary and proceeding automatically</field>
+        </block>
+      </branch>
+      <branch default="true" name="Request user confirmation">
+        <block type="event" id="E1" action="confirm" title="Function Extraction Confirmation - Checkpoint A" type="yesno" desc="Present function extraction summary">
+          <field name="preview">Backend Functions Extracted for: ${feature_name}
+Platform: ${platform_id}
+
+Function Extraction Summary:
+${extracted_functions.summary}
+
+Component Markers:
+- [NEW]: ${extracted_functions.new_count} modules
+- [MODIFIED]: ${extracted_functions.modified_count} modules
+- [EXISTING]: ${extracted_functions.existing_count} modules
+
+Confirm function extraction before proceeding?</field>
+        </block>
+      </branch>
+    </block>
+
+    <!-- Step 4: Generate Module Design Documents -->
+    <block type="task" id="B10" action="read-file" desc="Read design template">
+      <field name="path">speccrew-sd-backend/templates/SD-BACKEND-TEMPLATE.md</field>
+      <field name="output" var="design_template"/>
+    </block>
+
+    <!-- Loop: Generate design for each function -->
+    <block type="loop" id="L1" over="${extracted_functions.functions}" as="function" desc="Generate module design documents">
+      <!-- Gateway: Determine output path based on feature_id -->
+      <block type="gateway" id="G2" mode="exclusive" desc="Determine output path">
+        <branch test="${feature_id} != null" name="With feature_id">
+          <block type="task" id="B11" action="generate" desc="Copy template and create document with feature_id">
+            <field name="template" value="${design_template}"/>
+            <field name="placeholders">
+              - {Module Name} → ${function.module_name}
+              - {Feature Name} → ${feature_name}
+              - {Platform ID} → ${platform_id}
+            </field>
+            <field name="output_path">${iteration_path}/03.system-design/${platform_id}/${feature_id}-${feature_name}-design.md</field>
+            <field name="output" var="module_doc_created"/>
+          </block>
+        </branch>
+        <branch default="true" name="Without feature_id (backward compatibility)">
+          <block type="task" id="B12" action="generate" desc="Copy template and create document without feature_id">
+            <field name="template" value="${design_template}"/>
+            <field name="placeholders">
+              - {Module Name} → ${function.module_name}
+              - {Feature Name} → ${feature_name}
+              - {Platform ID} → ${platform_id}
+            </field>
+            <field name="output_path">${iteration_path}/03.system-design/${platform_id}/${function.module_name}-design.md</field>
+            <field name="output" var="module_doc_created"/>
+          </block>
+        </branch>
+      </block>
+
+      <!-- Fill each section using search_replace -->
+      <block type="task" id="B13" action="edit-file" desc="Fill Module Structure section">
+        <field name="path">${module_doc_created.path}</field>
+        <field name="operation">search_replace</field>
+        <field name="content_source">${tech_stack}${conventions_design}</field>
+        <field name="section">Module Structure</field>
+        <field name="rules">
+          - Use actual framework layering from techs knowledge
+          - ALL module structure diagrams MUST use Mermaid syntax
+          - Mark each module as [EXISTING], [MODIFIED], or [NEW]
+        </field>
+      </block>
+
+      <block type="task" id="B14" action="edit-file" desc="Fill Interface Pseudo-code section">
+        <field name="path">${module_doc_created.path}</field>
+        <field name="operation">search_replace</field>
+        <field name="content_source">${api_contract}${conventions_dev}</field>
+        <field name="section">Interface Pseudo-code</field>
+        <field name="rules">
+          - Use actual framework decorators/annotations
+          - Spring Boot: @RestController, @PostMapping, @Valid, etc.
+          - NestJS: @Controller, @Post, @Body, @UseGuards, etc.
+          - Go: gin.Context, echo.Context, etc.
+        </field>
+      </block>
+
+      <block type="task" id="B15" action="edit-file" desc="Fill Database Design section">
+        <field name="path">${module_doc_created.path}</field>
+        <field name="operation">search_replace</field>
+        <field name="content_source">${feature_spec}${conventions_data}</field>
+        <field name="section">Database Design</field>
+        <field name="rules">
+          - Use actual ORM entity definitions from conventions-data.md
+          - Include migration strategy, not just final schema
+          - Document new tables, modified tables, entity relationships
+        </field>
+      </block>
+
+      <block type="task" id="B16" action="edit-file" desc="Fill Transaction Boundaries section">
+        <field name="path">${module_doc_created.path}</field>
+        <field name="operation">search_replace</field>
+        <field name="content_source">${conventions_data}</field>
+        <field name="section">Transaction Boundaries</field>
+        <field name="rules">
+          - Use actual framework transaction mechanism
+          - Explicitly mark transaction boundaries for multi-step operations
+          - Use actual transaction annotations from conventions-data.md
+        </field>
+      </block>
+
+      <block type="task" id="B17" action="edit-file" desc="Fill Exception Handling section">
+        <field name="path">${module_doc_created.path}</field>
+        <field name="operation">search_replace</field>
+        <field name="content_source">${api_contract}${conventions_dev}</field>
+        <field name="section">Exception Handling</field>
+        <field name="rules">
+          - Use actual exception classes and error codes
+          - Exception handling must map to API Contract error codes
+          - Use actual framework exception patterns from techs knowledge
+        </field>
+      </block>
+
+      <!-- Step 4.3: Verify Output -->
+      <block type="task" id="B18" action="verify" desc="Verify completed design document">
+        <field name="verification_rules">
+          - All sections filled with actual content (no remaining placeholders)
+          - Mermaid diagrams render correctly
+          - Pseudo-code uses actual framework syntax from techs knowledge
+          - Transaction boundaries explicitly marked
+          - Exception types map to API Contract error codes
+          - If a section has no applicable content, section title kept with "N/A"
+          - All section titles and numbering preserved
+        </field>
+        <field name="output" var="design_doc_verified"/>
+      </block>
+    </block>
+
+      </branch>
+    </block>
+
+    <!-- Gateway: skip_index_generation conditional -->
+    <block type="gateway" id="G3" mode="exclusive" desc="Check if skip_index_generation">
+      <branch test="${skip_index_generation} == true" name="Skip INDEX.md generation">
+        <block type="event" id="E2_skip" action="log" level="info" desc="Skipping INDEX.md generation">
+          <field name="message">skip_index_generation=true, skipping Step 5 (INDEX.md will be generated by orchestrator after all workers complete)</field>
+        </block>
+      </branch>
+      <branch default="true" name="Generate INDEX.md">
+
+    <!-- Step 5: Generate Platform INDEX.md -->
+    <block type="task" id="B19" action="read-file" desc="Read index template">
+      <field name="path">speccrew-sd-backend/templates/INDEX-TEMPLATE.md</field>
+      <field name="output" var="index_template"/>
+    </block>
+
+    <block type="task" id="B20" action="generate" desc="Create INDEX.md from template">
+      <field name="template" value="${index_template}"/>
+      <field name="placeholders">
+        - {Platform Name} → ${platform_id}
+        - {Feature Name} → ${feature_name}
+      </field>
+      <field name="output_path">${iteration_path}/03.system-design/${platform_id}/INDEX.md</field>
+      <field name="output" var="index_doc_created"/>
+    </block>
+
+    <block type="task" id="B21" action="edit-file" desc="Fill Tech Stack Summary">
+      <field name="path">${iteration_path}/03.system-design/${platform_id}/INDEX.md</field>
+      <field name="operation">search_replace</field>
+      <field name="content_source">${tech_stack}</field>
+      <field name="section">Tech Stack Summary</field>
+    </block>
+
+    <block type="task" id="B22" action="edit-file" desc="Fill Shared Design Decisions">
+      <field name="path">${iteration_path}/03.system-design/${platform_id}/INDEX.md</field>
+      <field name="operation">search_replace</field>
+      <field name="content_source">${architecture}${conventions_design}</field>
+      <field name="section">Shared Design Decisions</field>
+    </block>
+
+    <block type="task" id="B23" action="edit-file" desc="Fill Module List Table">
+      <field name="path">${iteration_path}/03.system-design/${platform_id}/INDEX.md</field>
+      <field name="operation">search_replace</field>
+      <field name="content_source">${extracted_functions}</field>
+      <field name="section">Module List Table</field>
+      <field name="module_list_rules">
+        - Column ID: Use feature_id if available (e.g., F-CRM-01), otherwise use module name
+        - Column Name: Feature or module name
+        - Column Document: Link to design file (e.g., F-CRM-01-customer-list-design.md)
+        - Column Status: [NEW], [MODIFIED], or [EXISTING]
+        - Example row: | F-CRM-01 | Customer List | F-CRM-01-customer-list-design.md | NEW |
+      </field>
+    </block>
+
+    <block type="task" id="B24" action="edit-file" desc="Fill Cross-Module Interaction Notes">
+      <field name="path">${iteration_path}/03.system-design/${platform_id}/INDEX.md</field>
+      <field name="operation">search_replace</field>
+      <field name="content_source">${architecture}${extracted_functions}</field>
+      <field name="section">Cross-Module Interaction Notes</field>
+      <field name="rules">
+        - Shared services, event-driven patterns, dependencies
+        - Cross-Feature dependencies explicitly marked as [DEPENDENCY: F-XXX-NNN]
+      </field>
+    </block>
+
+    <block type="task" id="B25" action="edit-file" desc="Fill Database Schema Overview">
+      <field name="path">${iteration_path}/03.system-design/${platform_id}/INDEX.md</field>
+      <field name="operation">search_replace</field>
+      <field name="content_source">${conventions_data}${extracted_functions}</field>
+      <field name="section">Database Schema Overview</field>
+      <field name="rules">
+        - New tables, modified tables, entity relationships
+        - Migration files and rollback plans
+      </field>
+    </block>
+
+    <!-- Step 5.4: Verify INDEX.md Output -->
+    <block type="task" id="B26" action="verify" desc="Verify completed INDEX.md">
+      <field name="verification_rules">
+        - All sections filled with actual content (no remaining placeholders)
+        - All module design documents are correctly linked
+        - Database schema overview is complete
+        - Platform-level summary is complete
+      </field>
+      <field name="output" var="index_doc_verified"/>
+    </block>
+
+      </branch>
+    </block>
+
+    <!-- Step 6: Present Summary -->
+    <block type="event" id="E3" action="log" level="info" desc="Present design summary">
+      <field name="message">Backend System Design Summary for: ${feature_name}
+Platform: ${platform_id}
+
+Module Design Documents: ${extracted_functions.design_count}
+├── [NEW] ${extracted_functions.new_count} modules
+├── [MODIFIED] ${extracted_functions.modified_count} modules
+└── [EXISTING] ${extracted_functions.existing_count} modules (no design needed)
+
+Database Changes:
+├── New Tables: ${extracted_functions.new_tables_count}
+├── Modified Tables: ${extracted_functions.modified_tables_count}
+└── Migration Files: ${extracted_functions.migration_count}
+
+Key Design Decisions:
+- Data Access: ${conventions_data.orm_pattern}
+- Layer Structure: ${conventions_design.layer_structure}
+- Transaction Strategy: ${conventions_data.transaction_strategy}
+
+Files Generated:
+- ${iteration_path}/03.system-design/${platform_id}/INDEX.md
+${extracted_functions.file_list}
+
+Please confirm:
+1. Are the module architectures appropriate?
+2. Is the database design complete with migrations?
+3. Do the pseudo-code patterns match project conventions?
+4. Are all API routes from API Contract covered?</field>
+    </block>
+
+    <!-- Step 7: Update Task Status (conditional) -->
+    <block type="gateway" id="G4" mode="exclusive" desc="Check if dispatch_progress_file provided">
+      <branch test="${dispatch_progress_file} != null AND ${task_id} != null" name="Update task status">
+        <block type="gateway" id="G4a" mode="exclusive" desc="Determine success or failure">
+          <branch test="${workflow_status} == 'SUCCESS'" name="Mark completed">
+            <block type="task" id="B27" action="run-script" desc="Update task status to completed">
+              <field name="command">node "${update_progress_script}" update-task --file "${dispatch_progress_file}" --task-id "${task_id}" --status completed</field>
+              <field name="output" var="status_update_result"/>
+            </block>
+          </branch>
+          <branch default="true" name="Mark failed">
+            <block type="task" id="B28" action="run-script" desc="Update task status to failed">
+              <field name="command">node "${update_progress_script}" update-task --file "${dispatch_progress_file}" --task-id "${task_id}" --status failed</field>
+              <field name="output" var="status_update_result"/>
+            </block>
+          </branch>
+        </block>
+      </branch>
+      <branch default="true" name="No status update needed">
+        <block type="event" id="E4" action="log" level="info" desc="No dispatch_progress_file provided">
+          <field name="message">dispatch_progress_file or task_id not provided, skipping status update</field>
+        </block>
+      </branch>
+    </block>
+
+  </sequence>
+
+  <!-- ============================================================
+       Output Results
+       ============================================================ -->
+  <block type="output" id="O1" desc="Workflow output results - SUCCESS scenario">
+    <field name="status" value="SUCCESS" type="string" desc="Task completion status"/>
+    <field name="task_id" from="${task_id}" type="string" desc="Task ID from context"/>
+    <field name="platform" value="${platform_id}" type="string" desc="Target platform"/>
+    <field name="feature_id" from="${feature_id}" type="string" desc="Feature ID"/>
+    <field name="feature" value="${feature_name}" type="string" desc="Feature name"/>
+    <field name="output_files" type="array" desc="List of generated files">
+      <field name="file">${iteration_path}/03.system-design/${platform_id}/INDEX.md</field>
+      <field name="files" from="${extracted_functions.output_files}"/>
+    </field>
+    <field name="database_changes" type="object" desc="Database change summary">
+      <field name="new_tables" from="${extracted_functions.new_tables_count}" type="number"/>
+      <field name="modified_tables" from="${extracted_functions.modified_tables_count}" type="number"/>
+      <field name="migration_files" from="${extracted_functions.migration_count}" type="number"/>
+    </field>
+    <field name="summary" value="Backend system design completed for ${feature_name} on ${platform_id} with ${extracted_functions.design_count} module designs" type="string" desc="Completion summary"/>
+  </block>
+
+  <block type="output" id="O2" desc="Workflow output results - FAILED scenario">
+    <field name="status" value="FAILED" type="string" desc="Task completion status"/>
+    <field name="task_id" from="${task_id}" type="string" desc="Task ID from context"/>
+    <field name="platform" value="${platform_id}" type="string" desc="Target platform"/>
+    <field name="feature_id" from="${feature_id}" type="string" desc="Feature ID"/>
+    <field name="feature" value="${feature_name}" type="string" desc="Feature name"/>
+    <field name="output_files" value="[]" type="array" desc="No output files generated"/>
+    <field name="error" type="string" desc="Description of what went wrong"/>
+    <field name="error_category" type="string" desc="DEPENDENCY_MISSING | VALIDATION_ERROR | BLOCKED"/>
+    <field name="recovery_hint" type="string" desc="Suggestion for how to resolve or retry"/>
+  </block>
+
+  <!-- ============================================================
+       Quality Verification Checklist
+       ============================================================ -->
+  <block type="checklist" id="CK1" desc="Quality verification checklist">
+    <field name="item">All techs knowledge documents loaded before design</field>
+    <field name="item">Feature Spec and API Contract read and understood</field>
+    <field name="item">Existing codebase structure analyzed (Glob/Grep)</field>
+    <field name="item">Every Feature Spec function covered in a module design</field>
+    <field name="item">All API routes from API Contract referenced correctly</field>
+    <field name="item">Pseudo-code uses actual framework syntax (not generic)</field>
+    <field name="item">Module naming follows conventions-design.md</field>
+    <field name="item">Layer structure follows conventions-design.md</field>
+    <field name="item">ORM patterns follow conventions-data.md</field>
+    <field name="item">Database entities cover all data requirements from Feature Spec</field>
+    <field name="item">Transaction boundaries defined for multi-step operations</field>
+    <field name="item">Exception types map to API Contract error codes</field>
+    <field name="item">Migration requirements documented</field>
+    <field name="item">INDEX.md generated with complete module list</field>
+    <field name="item">All files written to correct paths under 03.system-design/{platform_id}/</field>
+    <field name="item">Output file named as {feature_id}-{feature_name}-design.md</field>
+    <field name="item">Checkpoint A passed (or skipped via skip_confirmation)</field>
+    <field name="item">No TODO/FIXME placeholders - all methods have complete pseudocode</field>
+    <field name="item">API routes match API Contract exactly</field>
+    <field name="item">Cross-Feature dependencies explicitly marked</field>
+    <field name="item">All Mermaid diagrams follow compatibility guidelines</field>
+  </block>
+
+</workflow>

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

@@ -1,4 +1,4 @@
----
+---
 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.
@@ -13,7 +13,7 @@ tools: Read, Write, Glob, Grep
 
 ## AgentFlow Definition
 
-<!-- @agentflow: workflow.agentflow.xml -->
+<!-- @agentflow: SKILL.xml -->
 
 > **REQUIRED**: Before executing this workflow, read the XML workflow specification: `speccrew-workspace/docs/rules/agentflow-spec.md`
 

package/.speccrew/skills/speccrew-sd-desktop/SKILL.md

@@ -1,4 +1,4 @@
----
+---
 name: speccrew-sd-desktop
 description: Desktop System Design SOP. Guide System Designer Agent to generate platform-specific desktop detailed design documents by filling technology implementation details into the Feature Spec skeleton. Reads techs knowledge to determine actual framework syntax (Electron/Tauri/Qt) and conventions.
 tools: Read, Write, Glob, Grep
@@ -12,7 +12,7 @@ tools: Read, Write, Glob, Grep
 
 ## AgentFlow Definition
 
-<!-- @agentflow: workflow.agentflow.xml -->
+<!-- @agentflow: SKILL.xml -->
 
 > **REQUIRED**: Before executing this workflow, read the XML workflow specification: `speccrew-workspace/docs/rules/agentflow-spec.md`
 

package/.speccrew/skills/speccrew-sd-framework-evaluate/SKILL.md

@@ -1,4 +1,4 @@
----
+---
 name: speccrew-sd-framework-evaluate
 description: Framework Evaluation Skill for System Designer. Analyzes Feature Spec requirements against current technology stack capabilities, identifies capability gaps, evaluates potential open-source frameworks/libraries, and generates a framework-evaluation.md report. Invoked by System Designer Agent during Phase 3.
 tools: Read, Write, Glob, Grep
@@ -12,7 +12,7 @@ tools: Read, Write, Glob, Grep
 
 ## AgentFlow Definition
 
-<!-- @agentflow: workflow.agentflow.xml -->
+<!-- @agentflow: SKILL.xml -->
 
 > **REQUIRED**: Before executing this workflow, read the XML workflow specification: `speccrew-workspace/docs/rules/agentflow-spec.md`