speccrew 0.7.61 → 0.7.62

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

@@ -6,383 +6,12 @@ tools: Read, Write, Glob, Grep
 
 # Trigger Scenarios
 
+- System Designer Agent dispatches this skill with platform context (platform_id, techs paths, Feature Spec paths)
 - Feature Spec has been confirmed, user requests backend system design
-- System Designer Agent receives task to create backend detailed design for a specific platform
-- User asks "Design backend implementation" or "Create backend design for {platform}"
+- User asks "Create backend design for this platform" or "Generate backend module design"
 
 ## 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., `backend-spring`, `backend-nestjs`.
-- `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. **Backend 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}/conventions-data.md` (critical for backend: ORM, data modeling, migration)
-4. **Design template**: `speccrew-sd-backend/templates/SD-BACKEND-TEMPLATE.md`
-5. **Index template**: `speccrew-sd-backend/templates/INDEX-TEMPLATE.md`
-
-## Step 2: Analyze Existing Code Structure
-
-Use Glob/Grep to understand current backend codebase:
-
-| Analysis Target | Purpose |
-|-----------------|---------|
-| 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 |
-
-## Step 3: Extract Functions from Feature Spec
-
-Parse Feature Spec to identify all backend-relevant functions.
-
-> **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 |
-|--------|---------|
-| **API Interfaces** | From Feature Spec Section 2.N backend part |
-| **Data Access Requirements** | What data needs to be read/written |
-| **Business Logic Flow** | Core processing steps |
-| **Cross-Module Dependencies** | Dependencies on other modules or services |
-
-Cross-reference with API Contract for exact endpoint specifications.
-
-Mark each function as:
-
-| Marker | Meaning |
-|--------|---------|
-| `[EXISTING]` | Reuse current implementation, no changes needed |
-| `[MODIFIED]` | Modify existing implementation |
-| `[NEW]` | Create brand new implementation |
-
-**Checkpoint A**:
-- If `skip_confirmation` = `true`: Log the function list with markers and **proceed automatically** without waiting for user confirmation.
-- If `skip_confirmation` is not set or `false`: Present function list with markers 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 = one controller/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 the SD-BACKEND-TEMPLATE.md to understand document structure.
-
-### 4.2a Copy Template to Document Path
-
-1. **Read the design template**: `templates/SD-BACKEND-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/backend-spring/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 | Content Source |
-|---------|----------------|
-| **Module Structure** | Use actual framework layering from techs knowledge |
-| **Interface Pseudo-code** | Use actual framework decorators/annotations |
-| **Database Design** | Use actual ORM entity definitions from conventions-data.md |
-| **Transaction Boundaries** | Use actual framework transaction mechanism |
-| **Exception Handling** | Use actual exception classes and error codes |
-
-**How to Reference Techs Knowledge for Pseudo-code:**
-
-1. **Read relevant techs knowledge file for the platform**:
-   - Core syntax: `tech-stack.md` for framework version and key libraries
-   - ORM patterns: `conventions-data.md` for entity definitions and transaction management
-   - Design patterns: `conventions-design.md` for layer structure and naming conventions
-2. **Extract framework-specific syntax patterns**:
-   - Controller annotations/decorators
-   - Service injection patterns
-   - Repository/DAO method signatures
-   - Transaction management annotations
-3. **Apply patterns in pseudo-code**:
-   - Use exact annotation/decorator syntax from techs knowledge
-   - Follow naming conventions from conventions-design.md
-   - Apply ORM patterns from conventions-data.md
-
-**Pseudo-code Requirements:**
-- MUST use actual framework syntax from techs knowledge
-- Spring Boot: `@RestController`, `@PostMapping`, `@Valid`, `@Transactional`, etc.
-- NestJS: `@Controller`, `@Post`, `@Body`, `@UseGuards`, etc.
-- Go: `gin.Context`, `echo.Context`, GORM annotations, etc.
-
-### 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 Index Template
-
-Read INDEX-TEMPLATE.md to understand platform-level 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 |
-|---------|---------|
-| **Tech Stack Summary** | Extract from techs knowledge |
-| **Shared Design Decisions** | Middleware stack, data source config, base service classes, common utilities |
-| **Module List Table** | Links to each module design document. Use `feature_id` as identifier if available (e.g., `F-CRM-01`), otherwise use module name. Example: `\| F-CRM-01 \| Customer List \| F-CRM-01-customer-list-design.md \| NEW \|` |
-| **Cross-Module Interaction Notes** | Shared services, event-driven patterns, dependencies |
-| **Database Schema Overview** | New tables, modified tables, entity relationships |
-
-### 5.3 Verify Output
-
-Verify the completed INDEX.md:
-- All sections filled with actual content (no remaining placeholders)
-- All module design documents are correctly linked
-- Database schema overview is complete
-
-## Step 6: Present Summary
-
-Present to user:
-
-```
-Backend System Design Summary for: {feature-name}
-Platform: {platform_id}
-
-Module Designs: {count}
-├── [NEW] {count} modules
-├── [MODIFIED] {count} modules
-└── [EXISTING] {count} modules (no design needed)
-
-Database Changes:
-├── New Tables: {count}
-├── Modified Tables: {count}
-└── Migration Files: {count}
-
-Key Design Decisions:
-- {decision 1}
-- {decision 2}
-- {decision 3}
-
-Files Generated:
-- {list all file paths}
-```
-
-## 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**: Backend 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
-
-## OUTPUT EFFICIENCY RULES
-
-When executing this skill:
-
-1. **Direct-to-File Output**: All design content (architecture diagrams, API mappings, component specifications, data models) MUST be written directly to the output file
-2. **Minimal Conversation Output**: Only output:
-   - Block execution announcements (1 line each): `"[Block XX] Designing..."`
-   - Error messages requiring attention
-   - Task Completion Report (final summary)
-3. **FORBIDDEN in conversation**:
-   - ❌ Full document sections or drafts
-   - ❌ Mermaid diagrams displayed in chat
-   - ❌ API endpoint listings
-   - ❌ Data model tables
-   - ❌ Architecture descriptions longer than 2 lines
-4. **Rationale**: Workers run in batch mode. Displaying design content in conversation wastes context window and provides no value since content goes to file anyway.
-
-# Key Rules
-
-| Rule | Description |
-|------|-------------|
-| **Actual Framework Syntax** | All pseudo-code MUST use actual framework/library syntax from techs knowledge |
-| **API Contract is READ-ONLY** | Do NOT modify API Contract, stop and report if issues found |
-| **Migration Strategy Required** | Database design must include migration strategy, not just final schema |
-| **Explicit Transaction Boundaries** | Transaction boundaries must be explicitly marked |
-| **Exception Code Mapping** | Exception handling must map to API Contract error codes |
-| **Follow Techs Conventions** | Naming, directory structure, patterns from techs knowledge |
-| **FORBIDDEN: TODO/FIXME Placeholders** | Design documents MUST contain complete implementation logic. Do NOT use TODO, FIXME, HACK, or any placeholder comments. Every method, validation rule, and business logic 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 for when that Feature is not yet implemented. |
-| **Output Filename Pattern** | Output filename MUST follow pattern: `{feature_id}-{feature_name}-design.md` |
-
-# Mermaid Diagram Requirements
-
-When generating Mermaid diagrams, follow compatibility guidelines:
-
-- Use only basic node definitions: `A[text content]`
-- No HTML tags (e.g., `<br/>`)
-- No nested subgraphs
-- No `direction` keyword
-- No `style` definitions
-- No special characters in node text
-- Use standard `graph TB/LR` or `flowchart TD/LR` or `erDiagram` syntax only
-
-# Checklist
-
-- [ ] All techs knowledge documents loaded before design
-- [ ] Feature Spec and API Contract read and understood
-- [ ] Existing codebase structure analyzed (Glob/Grep)
-- [ ] Function extraction completed with [EXISTING]/[MODIFIED]/[NEW] markers
-- [ ] Checkpoint A passed: function list confirmed (or skipped via skip_confirmation)
-- [ ] Every API in API Contract has a corresponding implementation design
-- [ ] Database entities cover all data requirements from Feature Spec
-- [ ] Transaction boundaries defined for multi-step operations
-- [ ] Exception types map to API Contract error codes
-- [ ] Pseudo-code uses actual framework syntax (not generic)
-- [ ] conventions-data.md ORM patterns followed
-- [ ] Migration requirements 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`
-- [ ] All Mermaid diagrams follow compatibility guidelines
-- [ ] **No TODO/FIXME placeholders** — all methods have complete pseudocode implementation
-- [ ] **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
+> **REQUIRED**: Read and execute the XML workflow above. The XML contains the complete workflow definition including all steps, rules, conditions, and checklist.