speccrew 0.7.61 → 0.7.62

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

@@ -14,339 +14,4 @@ tools: Read, Write, Glob, Grep
 
 <!-- @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. **FORBIDDEN: `create_file` for documents** — NEVER use `create_file` to write design documents or INDEX. Documents MUST be created by copying the template (Step 4.2a / Step 5.2a) then filling sections with `search_replace` (Step 4.2b / Step 5.2b). `create_file` produces truncated output on large files.
-
-2. **FORBIDDEN: Full-file rewrite** — NEVER replace the entire document content in a single operation. Always use targeted `search_replace` on specific sections.
-
-3. **MANDATORY: Template-first workflow** — Copy template MUST execute before fill sections. Skipping copy and writing content directly is FORBIDDEN.
-
-4. **MANDATORY: Output filename pattern** — Output filename MUST follow pattern: `{feature_id}-{feature_name}-design.md`. Omitting feature_id or using alternative naming is FORBIDDEN.
-
-## Step 1: Read Inputs
-
-> **Conditional Execution**: If `index_only` = `true`, **skip Steps 1-4** and jump directly to Step 5 to generate INDEX.md.
-
-**Input Parameters** (from agent context):
-- `feature_id` (optional): Feature identifier, e.g., `F-CRM-01`.
-- `feature_name`: Feature name, e.g., `customer-list`.
-- `platform_id`: Target platform, e.g., `mobile-uniapp`, `mobile-flutter`.
-- `skip_confirmation` (optional, boolean): When `true`, skip Checkpoint A user confirmation (used in batch dispatch mode)
-- `skip_index_generation` (optional, boolean): When `true`, skip Step 5 INDEX.md generation (INDEX.md will be generated by orchestrator after all workers complete)
-- `index_only` (optional, boolean): When `true`, skip Steps 1-4 and ONLY execute Step 5 (INDEX.md generation). Used after all platform workers complete.
-- `task_id` (optional, string): Task identifier in DISPATCH-PROGRESS.json. Used for status tracking.
-- `dispatch_progress_file` (optional, string): Path to DISPATCH-PROGRESS.json. If provided, worker updates its own task status on completion.
-- `update_progress_script` (optional, string): Path to update-progress.js script.
-
-Read in order:
-
-1. **Feature Spec document(s)**: `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-feature-spec.md`
-2. **API Contract**: `speccrew-workspace/iterations/{number}-{type}-{name}/03.api-contract/[feature-name]-api-contract.md`
-3. **Mobile techs knowledge** (paths from agent context):
-   - `speccrew-workspace/knowledges/techs/{platform_id}/tech-stack.md`
-   - `speccrew-workspace/knowledges/techs/{platform_id}/architecture.md`
-   - `speccrew-workspace/knowledges/techs/{platform_id}/conventions-design.md`
-   - `speccrew-workspace/knowledges/techs/{platform_id}/conventions-dev.md`
-4. **Design template**: `speccrew-sd-mobile/templates/SD-MOBILE-TEMPLATE.md`
-5. **Index template**: `speccrew-sd-mobile/templates/INDEX-TEMPLATE.md`
-
-## Step 2: Analyze Existing Code Structure
-
-Use Glob/Grep to understand current codebase:
-
-| Target | Glob Pattern | Purpose |
-|--------|-------------|---------|
-| Screen/Page directory | `lib/screens/**/*.dart` or `src/screens/**/*.tsx` | Understand screen organization |
-| Widget/Component directory | `lib/widgets/**/*.dart` or `src/components/**/*` | Understand widget organization |
-| State management | `lib/providers/**/*.dart` or `src/stores/**/*` | Understand state pattern |
-| Navigation configuration | `lib/router/**/*.dart` or `src/navigation/**/*` | Understand routing structure |
-| API layer | `lib/api/**/*.dart` or `src/api/**/*` | Understand API encapsulation pattern |
-| Local storage | `lib/storage/**/*.dart` or `src/storage/**/*` | Understand persistence patterns |
-| Naming conventions | Various | Identify actual naming patterns in use |
-
-Document findings for reference in later steps.
-
-## Step 3: Extract Functions from Feature Spec
-
-Parse Feature Spec to identify all functions (Section 2.N pattern).
-
-For each function, extract:
-
-| Aspect | Content to Extract |
-|--------|-------------------|
-| Mobile prototype | UI flow description from Feature Spec |
-| Interaction flow | User actions and system responses |
-| Backend API calls | Required API endpoints from API Contract |
-| Data requirements | Fields and structures needed |
-| Platform features | Camera, GPS, push notifications, biometrics, etc. |
-
-Mark each function's screens/widgets as:
-
-| Marker | Meaning | Example |
-|--------|---------|---------|
-| `[EXISTING]` | Reuse current screen/widget | `[EXISTING] UserProfileScreen` |
-| `[MODIFIED]` | Enhance/change existing | `[MODIFIED] OrderList - add pull-to-refresh` |
-| `[NEW]` | Create brand new | `[NEW] ProductDetailPage` |
-
-**Checkpoint A**:
-- If `skip_confirmation` = `true`: Log the function extraction summary and **proceed automatically** without waiting for user confirmation.
-- If `skip_confirmation` is not set or `false`: Present function extraction summary to user and **wait for explicit confirmation** before proceeding.
-
-> ⚠️ **FORBIDDEN**: Worker MUST NOT self-decide to skip confirmation. Only the `skip_confirmation` parameter from dispatch context controls this behavior.
-
-## Step 4: Generate Module Design Documents
-
-For each function (or logical group of closely related functions = one module):
-
-### Output File Naming Convention
-
-**MANDATORY**: The design document file MUST be named using this exact pattern:
-
-```
-{feature_id}-{feature_name}-design.md
-```
-
-Examples:
-- `F-M01-05-操作日志-design.md` ✅
-- `F-M02-01-顾客档案管理-design.md` ✅
-- `member-level-change-history-design.md` ❌ (missing feature_id prefix)
-- `customer-profile-design.md` ❌ (missing feature_id prefix)
-
-Where:
-- `feature_id`: The exact feature ID from dispatch context (e.g., `F-M01-05`, `F-M02-01`)
-- `feature_name`: The exact feature name from dispatch context (e.g., `操作日志`, `顾客档案管理`)
-
-> ⚠️ **FORBIDDEN**: 
-> - Using any filename format other than `{feature_id}-{feature_name}-design.md`
-> - Omitting the feature_id prefix
-> - Translating or paraphrasing the feature_name (must use the exact name from context)
-> - Using function/sub-feature names instead of the main feature_name
-
-### 4.1 Read Template
-
-Read `SD-MOBILE-TEMPLATE.md` for document structure.
-
-### 4.2a Copy Template to Document Path
-
-1. **Read the design template**: `templates/SD-MOBILE-TEMPLATE.md`
-2. **Replace top-level placeholders** with known variables:
-   - Module name, feature name, platform ID, etc.
-3. **Create the document file** using `create_file`:
-   - Target path: `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/{module}-design.md`
-   - Content: Template with top-level placeholders replaced
-4. **Verify**: Document should have complete section structure ready for filling
-
-### 4.2b Fill Each Section Using search_replace
-
-Fill each section with technology-specific implementation details.
-
-> ⚠️ **CRITICAL CONSTRAINTS:**
-> - **FORBIDDEN: `create_file` to rewrite the entire document** — it destroys template structure
-> - **MUST use `search_replace` to fill each section individually**
-> - **All section titles and numbering MUST be preserved**
-> - If a section has no applicable content, keep the section title and replace placeholder with "N/A"
-
-| Section | Technology-Specific Content |
-|---------|----------------------------|
-| Screen/widget tree | Use actual framework patterns (Flutter Widgets / React Native Components) |
-| Props/Parameters | Type definitions from conventions-dev.md |
-| State management | Actual pattern (Provider/Bloc/Riverpod for Flutter, Redux/MobX for React Native) |
-| API layer | Actual HTTP client (Dio for Flutter, Axios/fetch for React Native) |
-| Navigation | Actual router config (GoRouter for Flutter, React Navigation for React Native) |
-| Local storage | Actual storage solution (SharedPreferences/Hive/SQLite/MMKV) |
-| Platform features | Actual plugin APIs (camera, geolocator, local_notifications, etc.) |
-| Pseudo-code | MUST use actual framework syntax from techs knowledge |
-
-**Key Rules for Pseudo-code**:
-- MUST use actual framework API syntax from techs knowledge
-- NOT generic pseudo-code
-- Include actual import statements
-- Use actual state management/API patterns from conventions
-
-### 4.3 Verify Output
-
-Verify the completed design document:
-- All sections filled with actual content (no remaining placeholders)
-- Mermaid diagrams render correctly
-- Pseudo-code uses actual framework syntax from techs knowledge
-
-## Step 5: Generate Platform INDEX.md
-
-> **Conditional Execution**:
-> - If `skip_index_generation` = `true`, **skip this entire Step 5**.
-> - If `index_only` = `true`, this step is the ONLY step to execute (Steps 1-4 are skipped).
-
-After all module designs are complete:
-
-### 5.1 Read Template
-
-Read `INDEX-TEMPLATE.md` for document structure.
-
-### 5.2a Copy Index Template to Document Path
-
-1. **Read the index template**: `templates/INDEX-TEMPLATE.md`
-2. **Replace top-level placeholders** (platform name, feature name, etc.)
-3. **Create the document file** using `create_file`:
-   - Target path: `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/INDEX.md`
-   - Content: Template with top-level placeholders replaced
-
-### 5.2b Fill Index Sections Using search_replace
-
-> ⚠️ **CRITICAL CONSTRAINTS:**
-> - **FORBIDDEN: `create_file` to rewrite the entire document** — it destroys template structure
-> - **MUST use `search_replace` to fill each section individually**
-> - **All section titles and numbering MUST be preserved**
-
-| Section | Content Source |
-|---------|---------------|
-| Tech stack summary | tech-stack.md |
-| Target platforms | tech-stack.md (iOS/Android min versions) |
-| Shared design decisions | architecture.md, conventions-design.md |
-| State management strategy | architecture.md state management section |
-| Base widgets/components | conventions-design.md shared components |
-| API client configuration | conventions-dev.md HTTP client section |
-| Authentication pattern | architecture.md authentication section |
-| Third-party SDKs | tech-stack.md dependencies |
-
-### 5.3 Build Module List
-
-Create table with links to each module design document.
-
-### 5.4 Verify Output
-
-Verify the completed INDEX.md:
-- All sections filled with actual content (no remaining placeholders)
-- All module design documents are correctly linked
-- Platform-level summary is complete
-
-## Step 6: Present Summary
-
-Present to user:
-
-```
-Mobile System Design Summary for: {feature-name}
-Platform: {platform_id}
-
-Module Design Documents: {count}
-├── {module1}-design.md
-├── {module2}-design.md
-└── ...
-
-Key Design Decisions:
-- State Management: {approach}
-- Navigation Strategy: {approach}
-- API Layer: {approach}
-- Local Storage: {approach}
-- Platform Features: {list}
-
-Concerns/Trade-offs:
-- {list any concerns}
-```
-
-**Ask user to confirm:**
-1. Are the screen architectures appropriate?
-2. Is the state management strategy correct?
-3. Do the pseudo-code patterns match project conventions?
-4. Are all API calls from API Contract covered?
-5. Are platform-specific features (permissions, native integration) properly handled?
-
-## Step 7: Update Task Status (if dispatch_progress_file provided)
-
-> **Conditional Execution**: Only execute this step if `dispatch_progress_file` and `task_id` parameters are provided in the dispatch context.
-
-Update the task status in DISPATCH-PROGRESS.json to mark this task as completed:
-
-```
-node "${update_progress_script}" update-task --file "${dispatch_progress_file}" --task-id "${task_id}" --status completed
-```
-
-If the design document generation failed at any step, update with status `failed` instead:
-```
-node "${update_progress_script}" update-task --file "${dispatch_progress_file}" --task-id "${task_id}" --status failed
-```
-
-> ⚠️ **IMPORTANT**: This step MUST be the last action before returning the completion report. Do NOT skip this step in batch dispatch mode.
-
-## Step 8: Task Completion Report
-
-After completing all steps, output a structured completion report for the System Designer Agent to parse and update DISPATCH-PROGRESS.json:
-
-### On Success
-
-```
-## Task Completion Report
-- **Status**: SUCCESS
-- **Task ID**: {task_id from context}
-- **Platform**: {platform_id}
-- **Feature**: {feature_name}
-- **Output Files**:
-  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/INDEX.md
-  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/{module1}-design.md
-  - speccrew-workspace/iterations/{iter}/03.system-design/{platform_id}/{module2}-design.md
-- **Summary**: Mobile system design completed for {feature_name} on {platform_id} with {count} module designs
-```
-
-### On Failure
-
-```
-## Task Completion Report
-- **Status**: FAILED
-- **Task ID**: {task_id from context}
-- **Platform**: {platform_id}
-- **Feature**: {feature_name}
-- **Output Files**: []
-- **Error**: {description of what went wrong}
-- **Error Category**: DEPENDENCY_MISSING | VALIDATION_ERROR | BLOCKED
-- **Recovery Hint**: {suggestion for how to resolve or retry}
-```
-
-**Error Categories:**
-- `DEPENDENCY_MISSING`: Required input file or knowledge document not found
-- `VALIDATION_ERROR`: Input validation failed (e.g., invalid Feature Spec format)
-- `BLOCKED`: Blocked by external dependency or prerequisite not met
-
-# Key Rules
-
-| Rule | Description |
-|------|-------------|
-| **Actual Framework Syntax** | All pseudo-code MUST use actual framework/library syntax from techs knowledge, NOT generic code |
-| **API Contract READ-ONLY** | API Contract is reference only - do not modify |
-| **One Module Per Function Group** | Each module design document maps to one or more related Feature Spec functions |
-| **Status Markers Required** | Use [EXISTING], [MODIFIED], [NEW] markers for all screens, widgets, and store modules |
-| **Follow Techs Conventions** | Naming, directory structure, patterns must follow techs knowledge |
-| **Platform-Specific Handling** | Properly handle iOS/Android differences, permissions, and native integrations |
-| **Offline Support** | Consider offline-first patterns where applicable |
-| **FORBIDDEN: TODO/FIXME Placeholders** | Design documents MUST contain complete implementation logic. Do NOT use TODO, FIXME, HACK, or any placeholder comments. Every screen, component, and method MUST be fully specified with actual pseudocode. |
-| **API Route Consistency** | All API routes in the design document MUST exactly match the routes defined in the API Contract document. Before writing any route, READ the API Contract and copy routes verbatim. Do NOT invent or modify routes. |
-| **Cross-Feature Dependency Marking** | When referencing functionality from another Feature (e.g., conflict detection from F-APPT-002), MUST explicitly mark it as `[DEPENDENCY: F-XXX-NNN]` and define a degradation strategy (e.g., hide button, show placeholder) for when that Feature is not yet implemented. |
-| **Mermaid for All Diagrams** | ALL screen trees, navigation flows, interaction sequences, and state diagrams MUST use Mermaid syntax (`graph TB`, `sequenceDiagram`, `flowchart`). Plain text ASCII diagrams are FORBIDDEN for these sections. |
-| **Output Filename Pattern** | Output filename MUST follow pattern: `{feature_id}-{feature_name}-design.md` |
-
-# Checklist
-
-- [ ] All techs knowledge documents loaded before design
-- [ ] Existing code structure analyzed via Glob/Grep
-- [ ] Every Feature Spec function covered in a module design
-- [ ] All API calls from API Contract referenced correctly
-- [ ] Pseudo-code uses actual framework syntax (not generic)
-- [ ] Screen/widget naming follows conventions-dev.md
-- [ ] State management follows architecture.md patterns
-- [ ] Navigation follows conventions-design.md
-- [ ] Local storage strategy documented
-- [ ] Platform permissions and native integrations documented
-- [ ] App lifecycle handling documented
-- [ ] INDEX.md generated with complete module list
-- [ ] All files written to correct paths under 03.system-design/{platform_id}/
-- [ ] Output file named as `{feature_id}-{feature_name}-design.md`
-- [ ] **Checkpoint A passed**: function extraction confirmed (or skipped via skip_confirmation)
-- [ ] **No TODO/FIXME placeholders** — all screens and methods have complete pseudocode
-- [ ] **API routes match API Contract exactly** — verified route-by-route
-- [ ] **Cross-Feature dependencies explicitly marked** — all `[DEPENDENCY: F-XXX-NNN]` tags present with degradation strategy
-- [ ] **Mermaid diagrams used** — no ASCII text diagrams for flows or screen trees
+> **REQUIRED**: Read and execute the XML workflow above. The XML contains the complete workflow definition including all steps, rules, conditions, and checklist.