speccrew 0.7.61 → 0.7.63

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

@@ -1,4 +1,4 @@
----
+---
 name: speccrew-sd-frontend
 description: Frontend System Design SOP. Guide System Designer Agent to generate platform-specific frontend detailed design documents by filling technology implementation details into the Feature Spec skeleton. Reads techs knowledge to determine actual framework syntax and conventions.
 tools: Read, Write, Glob, Grep
@@ -12,343 +12,6 @@ tools: Read, Write, Glob, Grep
 
 ## 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. **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`. If provided, use new naming format.
-- `feature_name`: Feature name, e.g., `customer-list`.
-- `platform_id`: Target platform, e.g., `frontend-vue`, `frontend-react`.
-- `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-id}-{feature-name}-feature-spec.md`
-2. **API Contract**: `speccrew-workspace/iterations/{number}-{type}-{name}/03.api-contract/{feature-id}-{feature-name}-api-contract.md`
-3. **Frontend 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`
-   - `speccrew-workspace/knowledges/techs/{platform_id}/ui-style/ui-style-guide.md` (if exists)
-4. **Design template**: `speccrew-sd-frontend/templates/SD-FRONTEND-TEMPLATE.md`
-5. **Index template**: `speccrew-sd-frontend/templates/INDEX-TEMPLATE.md`
-
-## Step 2: Analyze Existing Code Structure
-
-Use Glob/Grep to understand current codebase:
-
-| Target | Glob Pattern | Purpose |
-|--------|-------------|---------|
-| Component directory | `src/components/**/*.vue` or `src/components/**/*.tsx` | Understand component organization |
-| Shared/base components | `src/components/base/**/*` | Identify reusable components |
-| State management | `src/stores/**/*.ts` or `src/store/**/*.ts` | Understand store pattern |
-| Router configuration | `src/router/**/*.ts` | Understand routing structure |
-| API layer | `src/apis/**/*.ts` or `src/api/**/*.ts` | Understand API encapsulation pattern |
-| 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).
-
-> **Note**: With the new fine-grained Feature Spec format, each Feature Spec typically contains **3-8 functions** (previously 10-20). The extraction logic remains the same, but the scope is more focused.
-
-For each function, extract:
-
-| Aspect | Content to Extract |
-|--------|-------------------|
-| Frontend prototype | ASCII wireframe 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 |
-
-Mark each function's components as:
-
-| Marker | Meaning | Example |
-|--------|---------|---------|
-| `[EXISTING]` | Reuse current component/store | `[EXISTING] UserSelect component` |
-| `[MODIFIED]` | Enhance/change existing | `[MODIFIED] OrderTable - add new column` |
-| `[NEW]` | Create brand new | `[NEW] ProductDetailDrawer` |
-
-**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-FRONTEND-TEMPLATE.md` for document structure.
-
-### 4.2a Copy Template to Document Path
-
-1. **Read the design template**: `templates/SD-FRONTEND-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 pattern**:
-     - With `feature_id`: `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/{feature-id}-{feature-name}-design.md`
-       - Example: `03.system-design/frontend-vue/F-CRM-01-customer-list-design.md`
-     - Without `feature_id` (backward compatibility): `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 |
-|---------|----------------------------|
-| Component tree | Use actual framework patterns (Vue 3 Composition API / React Hooks / etc.) |
-| Props/Emits | TypeScript types from conventions-dev.md |
-| State management | Actual store pattern (Pinia/Vuex/Redux/Zustand) |
-| API layer | Actual request library and interceptor patterns |
-| Routing | Actual router config format |
-| 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 store/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 |
-| Shared design decisions | architecture.md, conventions-design.md |
-| Global state strategy | architecture.md state management section |
-| Base components | conventions-design.md shared components |
-| API interceptor config | conventions-dev.md HTTP client section |
-| Auth pattern | architecture.md authentication section |
-
-### 5.3 Build Module List
-
-Create table with links to each module design document.
-
-| Column | Content |
-|--------|---------|
-| **ID** | Use `feature_id` if available (e.g., `F-CRM-01`), otherwise use module name |
-| **Name** | Feature or module name |
-| **Document** | Link to design file (e.g., `F-CRM-01-customer-list-design.md`) |
-| **Status** | `[NEW]`, `[MODIFIED]`, or `[EXISTING]` |
-
-Example row with `feature_id`: `| F-CRM-01 | Customer List | F-CRM-01-customer-list-design.md | NEW |`
-
-### 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:
-
-```
-Frontend 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}
-- Component Strategy: {approach}
-- API Layer: {approach}
-
-Concerns/Trade-offs:
-- {list any concerns}
-```
-
-**Ask user to confirm:**
-1. Are the component 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?
-
-## 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 ID**: {feature_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}/{feature-id}-{feature-name}-design.md (or {module}-design.md if no feature_id)
-- **Summary**: Frontend 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 ID**: {feature_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 components and store modules |
-| **Follow Techs Conventions** | Naming, directory structure, patterns must follow techs knowledge |
-| **FORBIDDEN: TODO/FIXME Placeholders** | Design documents MUST contain complete implementation logic. Do NOT use TODO, FIXME, HACK, or any placeholder comments. Every component, method, and interaction 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 component trees, interaction flows, and state management 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
+<!-- @agentflow: SKILL.xml -->
 
-- [ ] 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)
-- [ ] Component naming follows conventions-dev.md
-- [ ] State management follows architecture.md patterns
-- [ ] Directory structure follows conventions-design.md
-- [ ] 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 components 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 component trees
+> **REQUIRED**: Read and execute the XML workflow above. The XML contains the complete workflow definition including all steps, rules, conditions, and checklist.