speccrew 0.6.68 → 0.7.0

package/.speccrew/skills/speccrew-dev-review-mobile/workflow.agentflow.xml

@@ -0,0 +1,214 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<workflow id="dev-review-mobile" status="pending" version="1.0" desc="Mobile Code Review - Reviews mobile app implementation against design documents">
+
+  <!-- ============================================================
+       Input Parameters Definition
+       ============================================================ -->
+  <block type="input" id="I1" desc="Workflow input parameters">
+    <field name="design_doc_path" required="true" type="string" desc="Path to mobile module design document"/>
+    <field name="implementation_report_path" required="true" type="string" desc="Path to mobile development report"/>
+    <field name="source_root" required="true" type="string" desc="Root directory of mobile source code"/>
+    <field name="platform_id" required="true" type="string" desc="Mobile platform (mobile-uniapp, mobile-flutter, mobile-react-native)"/>
+    <field name="task_id" required="true" type="string" desc="Task identifier from dispatch context"/>
+    <field name="api_contract_path" required="false" type="string" desc="Path to API contract file"/>
+    <field name="previous_review_path" required="false" type="string" desc="Path to previous review report"/>
+  </block>
+
+  <!-- ============================================================
+       Global Constraints
+       ============================================================ -->
+  <block type="rule" id="R1" level="forbidden" desc="Review operation constraints">
+    <field name="text">NEVER modify source code files - read-only operation</field>
+    <field name="text">Do NOT attempt to fix issues - only document them</field>
+  </block>
+
+  <block type="rule" id="R2" level="mandatory" desc="Output requirements">
+    <field name="text">PARTIAL/FAIL results MUST include specific Re-dispatch Guidance</field>
+    <field name="text">Skip items already marked as passed in previous review</field>
+  </block>
+
+  <!-- ============================================================
+       Main Processing Sequence
+       ============================================================ -->
+  <sequence id="S1" name="Mobile Code Review" status="pending" desc="Execute mobile code review workflow">
+
+    <!-- Step 1: Load Documents -->
+    <block type="task" id="B1" action="validate" desc="Validate Inputs">
+      <field name="checks">Verify all required parameters provided</field>
+      <field name="on_fail">Report error and stop</field>
+      <field name="output" var="validation_result"/>
+    </block>
+
+    <block type="task" id="B2" action="read-file" desc="Read Design Document">
+      <field name="path" value="${design_doc_path}"/>
+      <field name="output" var="design_doc"/>
+    </block>
+
+    <block type="task" id="B3" action="analyze" desc="Extract from Design Document">
+      <field name="input" value="${design_doc}"/>
+      <field name="extraction">
+        - Module Overview
+        - Page/Component Structure
+        - Native Features
+        - Offline Support requirements
+      </field>
+      <field name="output" var="design_specs"/>
+    </block>
+
+    <block type="task" id="B4" action="read-file" desc="Read Implementation Report">
+      <field name="path" value="${implementation_report_path}"/>
+      <field name="output" var="impl_report"/>
+    </block>
+
+    <block type="task" id="B5" action="analyze" desc="Extract from Implementation Report">
+      <field name="input" value="${impl_report}"/>
+      <field name="extraction">Completed Files, Implementation Status, Known Issues</field>
+      <field name="output" var="impl_status"/>
+    </block>
+
+    <!-- Conditional: Read API Contract -->
+    <block type="gateway" id="G1" mode="exclusive" desc="Check if API contract provided">
+      <branch test="${api_contract_path} != null" name="Has API Contract">
+        <block type="task" id="B6" action="read-file" desc="Read API Contract">
+          <field name="path" value="${api_contract_path}"/>
+          <field name="output" var="api_contract"/>
+        </block>
+      </branch>
+      <branch default="true" name="No API Contract">
+        <block type="event" id="E1" action="log" level="info" desc="Skip API validation">
+          <field name="message">API contract not provided - skipping API validation</field>
+        </block>
+      </branch>
+    </block>
+
+    <!-- Step 2: File Completeness Check -->
+    <block type="task" id="B7" action="analyze" desc="Build Expected File List">
+      <field name="categories">
+        - Pages: pages/**/* or screens/**/* (e.g., pages/user/index.vue)
+        - Components: components/**/* (e.g., components/UserCard.vue)
+        - Store: store/**/* (e.g., store/user.js)
+        - API: api/**/* or services/**/* (e.g., api/user.js)
+        - Utils: utils/**/* (e.g., utils/permission.js)
+        - Native Modules: native/**/* or plugins/**/* (e.g., native/bridge.js)
+      </field>
+      <field name="output" var="expected_files"/>
+    </block>
+
+    <block type="task" id="B8" action="analyze" desc="Scan Actual Files">
+      <field name="source_root" value="${source_root}"/>
+      <field name="action">Use Glob to scan for implemented files</field>
+      <field name="output" var="actual_files"/>
+    </block>
+
+    <block type="task" id="B9" action="analyze" desc="Calculate Completeness">
+      <field name="formula">Generate completeness matrix and percentage</field>
+      <field name="output" var="completeness_result"/>
+    </block>
+
+    <!-- Step 3: Mobile-Specific Compliance Check -->
+    <block type="task" id="B10" action="analyze" desc="Mobile Component Check">
+      <field name="checks">
+        - Platform Components: Uses correct platform-specific components - Severity: ERROR
+        - Component Reuse: Components appropriately reusable - Severity: WARN
+        - Native Component Usage: Proper use of native UI components - Severity: WARN
+      </field>
+      <field name="output" var="component_check"/>
+    </block>
+
+    <block type="task" id="B11" action="analyze" desc="Platform Adaptation Validation">
+      <field name="checks">
+        - iOS/Android Differences: Platform-specific differences handled - Severity: ERROR
+        - Screen Adaptation: Different screen sizes handled - Severity: ERROR
+        - Safe Area: Safe area insets respected - Severity: ERROR
+        - Platform APIs: Platform-specific APIs correctly used - Severity: WARN
+      </field>
+      <field name="output" var="platform_check"/>
+    </block>
+
+    <block type="task" id="B12" action="analyze" desc="Permission Handling Check">
+      <field name="checks">
+        - Runtime Permissions: Runtime permission requests implemented - Severity: ERROR
+        - Permission Rationale: User-friendly permission explanations - Severity: WARN
+        - Denial Handling: Graceful handling of permission denial - Severity: ERROR
+      </field>
+      <field name="output" var="permission_check"/>
+    </block>
+
+    <block type="task" id="B13" action="analyze" desc="Offline Support Validation">
+      <field name="checks">
+        - Local Storage: Data caching implemented where required - Severity: ERROR
+        - Sync Mechanism: Offline data sync strategy implemented - Severity: ERROR
+        - Network State: Network connectivity handling - Severity: ERROR
+        - Queue Management: Pending request queue management - Severity: WARN
+      </field>
+      <field name="output" var="offline_check"/>
+    </block>
+
+    <block type="task" id="B14" action="analyze" desc="Performance Check">
+      <field name="checks">
+        - List Rendering: Virtual scrolling for long lists - Severity: ERROR
+        - Image Optimization: Image lazy loading and caching - Severity: WARN
+        - Memory Management: Proper cleanup of listeners/timers - Severity: ERROR
+        - Bundle Size: Code splitting where appropriate - Severity: WARN
+      </field>
+      <field name="output" var="performance_check"/>
+    </block>
+
+    <!-- Step 4: Generate Review Report -->
+    <block type="task" id="B15" action="analyze" desc="Determine Result">
+      <field name="criteria">
+        - PASS: 100% files created, 0 ERROR-level issues
+        - PARTIAL: 70-99% files created, or non-critical ERROR issues
+        - FAIL: &lt;70% files created, or critical blockers present
+      </field>
+      <field name="output" var="review_result"/>
+    </block>
+
+    <block type="task" id="B16" action="read-file" desc="Read Review Report Template">
+      <field name="path">templates/REVIEW-REPORT-TEMPLATE.md</field>
+      <field name="output" var="report_template"/>
+    </block>
+
+    <block type="task" id="B17" action="generate" desc="Write Review Report">
+      <field name="path">speccrew-workspace/iterations/{number}-{type}-{name}/04.development/{platform_id}/[module]-review-report.md</field>
+      <field name="template" value="${report_template}"/>
+      <field name="content">
+        - Completeness: ${completeness_result}
+        - Component Check: ${component_check}
+        - Platform Adaptation: ${platform_check}
+        - Permission Handling: ${permission_check}
+        - Offline Support: ${offline_check}
+        - Performance Check: ${performance_check}
+        - Final Result: ${review_result}
+      </field>
+      <field name="output" var="review_report_path"/>
+    </block>
+
+    <!-- Step 5: Task Completion Report -->
+    <block type="task" id="B18" action="report" desc="Generate Task Completion Report">
+      <field name="template">
+## Task Completion Report
+- **Status**: SUCCESS
+- **Task ID**: review-{original_task_id}
+- **Platform**: {platform_id}
+- **Module**: {module_name}
+- **Output Files**: {review_report_path}
+- **Summary**: Review {result}: {completed}/{total} files, {error_count} errors
+      </field>
+      <field name="output" var="completion_report"/>
+    </block>
+
+  </sequence>
+
+  <!-- ============================================================
+       Output Results
+       ============================================================ -->
+  <block type="output" id="O1" desc="Workflow output results">
+    <field name="review_report_path" value="${review_report_path}" type="string" desc="Path to review report"/>
+    <field name="review_result" value="${review_result}" type="string" desc="PASS/PARTIAL/FAIL verdict"/>
+    <field name="completeness_pct" type="number" desc="File completeness percentage"/>
+    <field name="error_count" type="number" desc="Number of ERROR-level issues"/>
+    <field name="completion_report" value="${completion_report}" type="string" desc="Task completion report"/>
+  </block>
+
+</workflow>

package/.speccrew/skills/speccrew-fd-api-contract/SKILL.md

@@ -9,7 +9,13 @@ tools: Read, Write, Glob, Grep
 - Automatically triggered by speccrew-fd-feature-design Skill after feature spec document completion
 - User requests "Generate API documentation" or "Define API contract"
 
-# Workflow
+## 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
 

package/.speccrew/skills/speccrew-fd-api-contract/workflow.agentflow.xml

@@ -0,0 +1,222 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<workflow id="api-contract-main" status="pending" version="1.0" desc="API Contract Generation 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"/>
+    <field name="feature_name" required="false" type="string" desc="Feature name, e.g., customer-list"/>
+    <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"/>
+  </block>
+
+  <!-- ============================================================
+       Global Constraints
+       ============================================================ -->
+  <block type="rule" id="R1" level="forbidden" desc="Document creation constraints">
+    <field name="text">NEVER use create_file to write the API contract document directly</field>
+    <field name="text">MUST create 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">Step 4a (copy template) MUST execute before Step 4b (fill sections)</field>
+    <field name="text">Skipping template copy is FORBIDDEN</field>
+  </block>
+
+  <!-- ============================================================
+       Main Processing Sequence
+       ============================================================ -->
+  <sequence id="S1" name="API Contract Generation" status="pending" desc="Generate API contract from feature spec">
+
+    <!-- Step 1: Read Feature Spec -->
+    <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>
+
+    <!-- Gateway: Validate Feature Spec exists -->
+    <block type="gateway" id="G1" mode="guard" desc="Verify Feature Spec exists"
+           test="${feature_spec} != null" fail-action="stop">
+      <field name="message">Feature Spec document not found. Check path: ${iteration_path}/02.feature-design/</field>
+    </block>
+
+    <!-- Step 2: Read API Contract Template -->
+    <block type="task" id="B2" action="read-file" desc="Read API Contract template">
+      <field name="path">speccrew-fd-api-contract/templates/API-CONTRACT-TEMPLATE.md</field>
+      <field name="output" var="template_content"/>
+    </block>
+
+    <!-- Gateway: Validate template exists -->
+    <block type="gateway" id="G2" mode="guard" desc="Verify template exists"
+           test="${template_content} != null" fail-action="stop">
+      <field name="message">API Contract template not found at speccrew-fd-api-contract/templates/API-CONTRACT-TEMPLATE.md</field>
+    </block>
+
+    <!-- Step 3: Extract and Organize API List -->
+    <block type="task" id="B3" action="analyze" desc="Extract API list from Feature Spec">
+      <field name="input" value="${feature_spec}"/>
+      <field name="extraction_rules">
+        - Extract all API endpoints from Section 2 (Function Details)
+        - Identify HTTP method (GET/POST/PUT/DELETE)
+        - Extract URL pattern following RESTful conventions
+        - Identify caller (Frontend/Backend/External)
+        - Build API list table
+      </field>
+      <field name="output" var="api_list"/>
+    </block>
+
+    <!-- Step 4a: Copy Template to Document Path -->
+    <block type="task" id="B4" action="generate" desc="Copy template and create document skeleton">
+      <field name="template" value="${template_content}"/>
+      <field name="placeholders">
+        - [Feature Name] → ${feature_name}
+        - {Feature ID} → ${feature_id}
+        - {Date} → current date
+      </field>
+      <field name="output_path">${iteration_path}/02.feature-design/${feature_id}-${feature_name}-api-contract.md</field>
+      <field name="fallback_path">${iteration_path}/02.feature-design/${feature_name}-api-contract.md</field>
+      <field name="output" var="document_created"/>
+    </block>
+
+    <!-- Checkpoint: Verify document created -->
+    <block type="checkpoint" id="CP1" name="document-created" desc="Verify API contract document created">
+      <field name="file" value="${iteration_path}/02.feature-design/${feature_id}-${feature_name}-api-contract.md"/>
+      <field name="verify" value="file_exists(${iteration_path}/02.feature-design/${feature_id}-${feature_name}-api-contract.md)"/>
+    </block>
+
+    <!-- Step 4b: Fill API List Overview Section -->
+    <block type="task" id="B5" action="edit-file" desc="Fill API List Overview section">
+      <field name="path">${iteration_path}/02.feature-design/${feature_id}-${feature_name}-api-contract.md</field>
+      <field name="fallback_path">${iteration_path}/02.feature-design/${feature_name}-api-contract.md</field>
+      <field name="operation">search_replace</field>
+      <field name="search">## API List Overview
+
+[TO BE FILLED]</field>
+      <field name="replace">## API List Overview
+
+| API Name | Method | URL | Description | Caller |
+|----------|--------|-----|-------------|--------|
+${api_list.table}</field>
+      <field name="output" var="section_1_filled"/>
+    </block>
+
+    <!-- Step 5: Define Contract for Each API -->
+    <block type="loop" id="L1" over="${api_list.apis}" as="api" desc="Define contract for each API">
+      <block type="task" id="B6" action="analyze" desc="Define API contract details">
+        <field name="input" value="${api}">${feature_spec}</field>
+        <field name="definition_rules">
+          - Request method, URL, authentication required
+          - Request parameters (type, required, example values)
+          - Response structure (type and description for each field)
+          - Success response example (JSON)
+          - Error code list
+        </field>
+        <field name="output" var="api_contract_details"/>
+      </block>
+
+      <block type="task" id="B7" action="edit-file" desc="Fill API contract section">
+        <field name="path">${iteration_path}/02.feature-design/${feature_id}-${feature_name}-api-contract.md</field>
+        <field name="fallback_path">${iteration_path}/02.feature-design/${feature_name}-api-contract.md</field>
+        <field name="operation">search_replace</field>
+        <field name="search">### ${api.name}
+
+[TO BE FILLED]</field>
+        <field name="replace">### ${api.name}
+
+${api_contract_details.content}</field>
+      </block>
+    </block>
+
+    <!-- Step 6: Fill Error Code Summary -->
+    <block type="task" id="B8" action="edit-file" desc="Fill Error Code Summary section">
+      <field name="path">${iteration_path}/02.feature-design/${feature_id}-${feature_name}-api-contract.md</field>
+      <field name="fallback_path">${iteration_path}/02.feature-design/${feature_name}-api-contract.md</field>
+      <field name="operation">search_replace</field>
+      <field name="search">## Error Code Summary
+
+[TO BE FILLED]</field>
+      <field name="replace">## Error Code Summary
+
+| Error Code | Description | HTTP Status |
+|------------|-------------|-------------|
+${api_list.error_codes}</field>
+    </block>
+
+    <!-- Step 7: Joint Confirmation -->
+    <block type="gateway" id="G3" mode="exclusive" desc="Select confirmation mode">
+      <branch test="${feature_id} != null" name="Feature-granular confirmation">
+        <block type="event" id="E1" action="confirm" title="Feature Design Confirmation" type="yesno" desc="Request user confirmation for feature">
+          <field name="preview">Feature design phase deliverables ready:
+
+Feature ID: ${feature_id}
+Feature Name: ${feature_name}
+
+Documents:
+- Feature Spec: ${iteration_path}/02.feature-design/${feature_id}-${feature_name}-feature-spec.md
+- API Contract: ${iteration_path}/02.feature-design/${feature_id}-${feature_name}-api-contract.md
+
+Please confirm:
+1. Is the technical solution feasible?
+2. Does the API definition meet frontend requirements?
+3. Is the data model reasonable?
+
+After confirmation, API Contract becomes the sole baseline for frontend-backend collaboration.</field>
+        </block>
+      </branch>
+      <branch default="true" name="Module-level confirmation">
+        <block type="event" id="E2" action="confirm" title="Feature Design Confirmation" type="yesno" desc="Request user confirmation">
+          <field name="preview">Feature design phase deliverables ready:
+- Feature Spec: ${iteration_path}/02.feature-design/${feature_name}-feature-spec.md
+- API Contract: ${iteration_path}/02.feature-design/${feature_name}-api-contract.md
+
+Please confirm:
+1. Is the overall technical solution feasible?
+2. Does the API definition meet frontend requirements?
+3. Is the data model reasonable?
+
+After confirmation, API Contract becomes the sole baseline for frontend-backend collaboration.</field>
+        </block>
+      </branch>
+    </block>
+
+    <!-- Step 8a: Update Checkpoints File -->
+    <block type="task" id="B9" action="run-script" desc="Update checkpoints via script">
+      <field name="command">node "${workspace_path}/scripts/update-progress.js" write-checkpoint --file "${iteration_path}/02.feature-design/.checkpoints.json" --stage 02_feature_design --checkpoint api_contract_joint --passed true</field>
+      <field name="output" var="checkpoint_result"/>
+    </block>
+
+    <!-- Step 8b: Update Workflow Progress -->
+    <block type="gateway" id="G4" mode="exclusive" desc="Update progress based on mode">
+      <branch test="${feature_id} != null" name="Feature mode">
+        <block type="task" id="B10" action="run-script" desc="Update workflow progress for feature">
+          <field name="command">node "${workspace_path}/scripts/update-progress.js" update-task --file "${iteration_path}/WORKFLOW-PROGRESS.json" --task-id "${feature_id}" --status confirmed --outputs '["02.feature-design/${feature_id}-${feature_name}-feature-spec.md","02.feature-design/${feature_id}-${feature_name}-api-contract.md"]'</field>
+        </block>
+      </branch>
+      <branch default="true" name="Module mode">
+        <block type="task" id="B11" action="run-script" desc="Update workflow progress for module">
+          <field name="command">node "${workspace_path}/scripts/update-progress.js" update-stage --file "${iteration_path}/WORKFLOW-PROGRESS.json" --stage 02_feature_design --status confirmed --outputs '["02.feature-design/${feature_name}-feature-spec.md","02.feature-design/${feature_name}-api-contract.md"]'</field>
+        </block>
+      </branch>
+    </block>
+
+  </sequence>
+
+  <!-- ============================================================
+       Output Results
+       ============================================================ -->
+  <block type="output" id="O1" desc="Workflow output results">
+    <field name="api_contract_path" value="${iteration_path}/02.feature-design/${feature_id}-${feature_name}-api-contract.md" type="string" desc="Path to generated API contract"/>
+    <field name="feature_spec_path" value="${iteration_path}/02.feature-design/${feature_id}-${feature_name}-feature-spec.md" type="string" desc="Path to Feature Spec"/>
+    <field name="api_count" from="${api_list.count}" type="number" desc="Number of APIs documented"/>
+    <field name="confirmation_status" value="confirmed" type="string" desc="User confirmation status"/>
+  </block>
+
+</workflow>

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

@@ -22,7 +22,13 @@ This skill applies ISA-95 Stages 1-3 as an internal thinking framework for analy
 - Feature Designer Agent needs to decompose PRD into functions before design
 - User asks "Analyze this feature" or "Break down this requirement"
 
-# Workflow
+## AgentFlow Definition
+
+<!-- @agentflow: workflow.agentflow.xml -->
+
+> **REQUIRED**: Before executing this workflow, read the XML workflow specification: `speccrew-workspace/docs/rules/agentflow-spec.md`
+
+## Workflow
 
 **MANDATORY:**
 - **Business Perspective Only** — Feature Analysis is a PURE BUSINESS document. It describes WHAT the system does from a business/user perspective, NOT HOW it's technically implemented.