speccrew 0.1.9 → 0.1.11

package/.speccrew/skills/speccrew-knowledge-techs-ui-analyze/SKILL.md

@@ -74,6 +74,16 @@ Generate the following documents in `{output_path}/`:
 
 ## Workflow
 
+### Absolute Constraints
+
+> **These rules apply to ALL document generation steps. Violation = task failure.**
+
+1. **FORBIDDEN: `create_file` for analysis documents** — NEVER use `create_file` to write any UI analysis document. Each document MUST be created by copying the appropriate template then filling sections with `search_replace`. `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** — For every output document, the corresponding template MUST be copied to the target path first, then sections filled with `search_replace`. Skipping copy and writing content directly is FORBIDDEN.
+
 ### Step 0: Read All Templates
 
 Before analysis, read all template files to understand document structures and required content:
@@ -187,6 +197,16 @@ For each identified page type, extract according to `PAGE-TYPE-INDIVIDUAL-TEMPLA
 
 **Generate**: `page-types/[type]-pages.md` for each discovered type
 
+#### Document Generation (per document)
+
+**For `page-types/page-type-summary.md`:**
+1. Copy template `templates/PAGE-TYPE-SUMMARY-TEMPLATE.md` → `{output_path}/page-types/page-type-summary.md`
+2. Fill each section using `search_replace` (FORBIDDEN: `create_file` rewrite)
+
+**For each `page-types/[type]-pages.md`:**
+1. Copy template `templates/PAGE-TYPE-INDIVIDUAL-TEMPLATE.md` → `{output_path}/page-types/[type]-pages.md`
+2. Fill each section using `search_replace` (FORBIDDEN: `create_file` rewrite)
+
 ### Step 3: Extract Component Usage
 
 **Purpose**: Generate component documentation in `components/` directory
@@ -243,6 +263,20 @@ Analyze component imports and usage:
 - Props and event definitions
 - Business logic integration patterns
 
+#### Document Generation (per document)
+
+**For `components/component-library.md`:**
+1. Copy template `templates/COMPONENT-LIBRARY-TEMPLATE.md` → `{output_path}/components/component-library.md`
+2. Fill each section using `search_replace` (FORBIDDEN: `create_file` rewrite)
+
+**For `components/common-components.md`:**
+1. Copy template `templates/COMMON-COMPONENTS-TEMPLATE.md` → `{output_path}/components/common-components.md`
+2. Fill each section using `search_replace` (FORBIDDEN: `create_file` rewrite)
+
+**For `components/business-components.md`:**
+1. Copy template `templates/BUSINESS-COMPONENTS-TEMPLATE.md` → `{output_path}/components/business-components.md`
+2. Fill each section using `search_replace` (FORBIDDEN: `create_file` rewrite)
+
 #### Generate Individual Component Documents
 
 For each component discovered during analysis:
@@ -328,6 +362,16 @@ Identify common layout patterns:
 - Route configuration conventions
 - Navigation state management
 
+#### Document Generation (per document)
+
+**For `layouts/page-layouts.md`:**
+1. Copy template `templates/LAYOUT-PATTERNS-TEMPLATE.md` → `{output_path}/layouts/page-layouts.md`
+2. Fill each section using `search_replace` (FORBIDDEN: `create_file` rewrite)
+
+**For `layouts/navigation-patterns.md`:**
+1. Copy template `templates/NAVIGATION-PATTERNS-TEMPLATE.md` → `{output_path}/layouts/navigation-patterns.md`
+2. Fill each section using `search_replace` (FORBIDDEN: `create_file` rewrite)
+
 #### Generate Individual Layout Documents
 
 For each distinct layout pattern discovered:
@@ -403,6 +447,20 @@ Analyze style files to extract:
 - Container and breakpoint definitions
 - Spacing application guidelines
 
+#### Document Generation (per document)
+
+**For `styles/color-system.md`:**
+1. Copy template `templates/STYLE-SYSTEM-TEMPLATE.md` → `{output_path}/styles/color-system.md`
+2. Fill each section using `search_replace` (FORBIDDEN: `create_file` rewrite)
+
+**For `styles/typography.md`:**
+1. Copy template `templates/TYPOGRAPHY-TEMPLATE.md` → `{output_path}/styles/typography.md`
+2. Fill each section using `search_replace` (FORBIDDEN: `create_file` rewrite)
+
+**For `styles/spacing-system.md`:**
+1. Copy template `templates/SPACING-TEMPLATE.md` → `{output_path}/styles/spacing-system.md`
+2. Fill each section using `search_replace` (FORBIDDEN: `create_file` rewrite)
+
 ### Step 6: Generate Documentation
 
 **Purpose**: Create all documentation files using extracted data and templates
@@ -411,11 +469,18 @@ Analyze style files to extract:
 
 For each document, follow this process:
 
-1. **Read the corresponding template** from `templates/` directory
+1. **Copy the corresponding template** from `templates/` directory to target path
 2. **Review extracted data** from Steps 1-5
-3. **Map data to template sections** - ensure all template placeholders are filled
-4. **Generate document** with actual values
-5. **Write output** to `{output_path}/`
+3. **Fill template sections** using `search_replace` - map data to template placeholders
+4. **Verify** all template placeholders are filled
+
+**Note**: NEVER use `create_file` to generate documents. Always copy template first, then use `search_replace` to fill sections.
+
+#### Document Generation (per document)
+
+**For `ui-style-guide.md`:**
+1. Copy template `templates/UI-STYLE-GUIDE-TEMPLATE.md` → `{output_path}/ui-style-guide.md`
+2. Fill each section using `search_replace` (FORBIDDEN: `create_file` rewrite)
 
 #### Document Generation Order and Dependencies
 

package/.speccrew/skills/speccrew-pm-requirement-analysis/SKILL.md

@@ -13,6 +13,16 @@ tools: Read, Write, Glob, Grep
 
 # Workflow
 
+## Absolute Constraints
+
+> **These rules apply to ALL document generation steps. Violation = task failure.**
+
+1. **FORBIDDEN: `create_file` for documents** — NEVER use `create_file` to write PRD or modeling documents. Documents MUST be created by copying the template then filling sections with `search_replace`.
+
+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 filling sections. Skipping copy and writing content directly is FORBIDDEN.
+
 ## Step 1: Requirements Clarification (Progressive Multi-Round)
 
 Use progressive questioning to clarify requirements. Do NOT ask all questions at once.
@@ -195,7 +205,16 @@ Ask: "Here are the core functions (Must have) and deferred functions. Is the MVP
   - No `direction` keyword
   - No `style` definitions
   - No special characters in node text
-- Save modeling document to: `iterations/{number}/01.product-requirement/{feature-name}-bizs-modeling.md`
+- **Write modeling document using template-fill workflow:**
+
+  **5.7a Copy Template to Document Path:**
+  1. Read `templates/BIZS-MODELING-TEMPLATE.md`
+  2. Replace top-level placeholders (feature name, domain name, etc.)
+  3. Create document using `create_file` at: `iterations/{number}-{type}-{name}/01.product-requirement/{feature-name}-bizs-modeling.md`
+
+  **5.7b Fill Each Section Using search_replace:**
+  Fill each modeling stage section with results from Stages 1-6 above, using `search_replace` per section.
+  > ⚠️ FORBIDDEN: `create_file` to rewrite entire document. MUST use `search_replace` per section.
 
 **ISA-95 Quick Reference:**
 
@@ -369,7 +388,29 @@ speccrew-workspace/iterations/{number}-{type}-{name}/01.product-requirement/
 
 If the iteration directory does not exist, refer to the `000-sample` directory structure to create it.
 
-## Step 12: Write File and Request Confirmation
+## Step 12: Write Files Using Template-Fill Workflow
+
+### 12a Copy Template to Document Path
+
+For each document to write (PRD, and optionally Sub-PRDs):
+
+1. **Read the template**: `templates/PRD-TEMPLATE.md` (already loaded in Step 7)
+2. **Replace top-level placeholders** (feature name, iteration, date)
+3. **Create the document** using `create_file` at the path determined in Step 11
+4. **Verify**: Document has complete section structure
+
+### 12b Fill Each Section Using search_replace
+
+Fill each section with content prepared in Step 9, using `search_replace` per section.
+
+> ⚠️ **CRITICAL CONSTRAINTS:**
+> - **FORBIDDEN: `create_file` to rewrite the entire document**
+> - **MUST use `search_replace` to fill each section individually**
+> - **All section titles MUST be preserved**
+
+For Master-Sub structure, repeat 12a + 12b for each Sub-PRD document.
+
+### 12c Request Confirmation
 
 After writing files, show summary and request user confirmation:
 

package/.speccrew/skills/speccrew-project-diagnosis/SKILL.md

@@ -31,6 +31,16 @@ tools: Read, Glob, Grep, List, ReadFile, Search
 - **Template**: [templates/DIAGNOSIS-REPORT-TEMPLATE.md](templates/DIAGNOSIS-REPORT-TEMPLATE.md)
 - **Naming Convention**: Date-time suffix using 24-hour format `HHmm` (e.g., `diagnosis-report-2026-03-15-1326.md` for 13:26), supports multiple diagnoses on the same day
 
+## Absolute Constraints
+
+> **These rules apply to ALL document generation steps. Violation = task failure.**
+
+1. **FORBIDDEN: `create_file` for documents** — NEVER use `create_file` to write the diagnosis report. It MUST be created by copying the template then filling sections with `search_replace`.
+
+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 filling sections. Skipping copy and writing content directly is FORBIDDEN.
+
 ## Get Current Timestamp
 
 To ensure consistent timestamp format, use the `speccrew-get-timestamp` skill:
@@ -141,9 +151,24 @@ diagnosis-report-{timestamp}.md
 
 Example: If script returns `2026-03-17-1326`, filename is `diagnosis-report-2026-03-17-1326.md`
 
-### 4.3 Fill Report Content
+### 4.3 Copy Template to Report Path
+
+1. **Read the template**: `templates/DIAGNOSIS-REPORT-TEMPLATE.md`
+2. **Replace top-level placeholders** (project name, timestamp from 4.2, etc.)
+3. **Create the document** using `create_file`:
+   - Target path: `speccrew-workspace/docs/diagnosis-reports/diagnosis-report-{timestamp}.md`
+   - Content: Template with top-level placeholders replaced
+4. **Verify**: Document has complete section structure ready for filling
+
+### 4.4 Fill Each Section Using search_replace
+
+Fill each section with diagnosis data using `search_replace`.
 
-Based on template `templates/DIAGNOSIS-REPORT-TEMPLATE.md`, generate the diagnosis report.
+> ⚠️ **CRITICAL CONSTRAINTS:**
+> - **FORBIDDEN: `create_file` to rewrite the entire document**
+> - **MUST use `search_replace` to fill each section individually**
+> - **All section titles MUST be preserved**
+> - If a section has no applicable data, keep title and fill with "To be confirmed"
 
 **Dynamic Content Filling Rules**:
 

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

@@ -12,6 +12,16 @@ tools: Read, Write, Glob, Grep
 
 # 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.
+
 ## Step 1: Read Inputs
 
 Read in order:
@@ -75,9 +85,25 @@ For each function (or logical group = one controller/module):
 
 Read the SD-BACKEND-TEMPLATE.md to understand document structure.
 
-### 4.2 Fill Template Sections
+### 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: `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
 
-Fill each section with technology-specific implementation details:
+### 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 |
 |---------|----------------|
@@ -93,9 +119,12 @@ Fill each section with technology-specific implementation details:
 - NestJS: `@Controller`, `@Post`, `@Body`, `@UseGuards`, etc.
 - Go: `gin.Context`, `echo.Context`, GORM annotations, etc.
 
-### 4.3 Write Output
+### 4.3 Verify Output
 
-Write to: `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/{module}-design.md`
+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
 
@@ -105,7 +134,20 @@ After all module designs are complete:
 
 Read INDEX-TEMPLATE.md to understand platform-level document structure.
 
-### 5.2 Fill Index Sections
+### 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 |
 |---------|---------|
@@ -115,9 +157,12 @@ Read INDEX-TEMPLATE.md to understand platform-level document structure.
 | **Cross-Module Interaction Notes** | Shared services, event-driven patterns, dependencies |
 | **Database Schema Overview** | New tables, modified tables, entity relationships |
 
-### 5.3 Write Output
+### 5.3 Verify Output
 
-Write to: `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/INDEX.md`
+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
 

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

@@ -12,6 +12,16 @@ tools: Read, Write, Glob, Grep
 
 # 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.
+
 ## Step 1: Read Inputs
 
 Read in order:
@@ -75,9 +85,25 @@ For each function (or logical group of closely related functions = one module):
 
 Read `SD-DESKTOP-TEMPLATE.md` for document structure.
 
-### 4.2 Fill Technology-Specific Details
+### 4.2a Copy Template to Document Path
+
+1. **Read the design template**: `templates/SD-DESKTOP-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.
 
-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 |
 |---------|----------------------------|
@@ -90,10 +116,6 @@ Fill each section with technology-specific implementation details:
 | Auto-update | electron-updater or tauri-updater patterns |
 | Pseudo-code | MUST use actual framework syntax from techs knowledge |
 
-### 4.3 Write Module Design
-
-Write to: `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/{module}-design.md`
-
 **Key Rules for Pseudo-code**:
 - MUST use actual framework API syntax from techs knowledge
 - NOT generic pseudo-code
@@ -102,6 +124,13 @@ Write to: `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design
 - For Electron: use `ipcMain.handle`, `ipcRenderer.invoke`, `BrowserWindow`
 - For Tauri: use `#[tauri::command]`, `invoke()`, `Window`
 
+### 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
 
 After all module designs are complete:
@@ -110,7 +139,20 @@ After all module designs are complete:
 
 Read `INDEX-TEMPLATE.md` for document structure.
 
-### 5.2 Fill Platform-Level Summary
+### 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 |
 |---------|---------------|
@@ -127,9 +169,12 @@ Read `INDEX-TEMPLATE.md` for document structure.
 
 Create table with links to each module design document.
 
-### 5.4 Write INDEX
+### 5.4 Verify Output
 
-Write to: `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/INDEX.md`
+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
 

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

@@ -12,6 +12,16 @@ tools: Read, Write, Glob, Grep
 
 # 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.
+
 ## Step 1: Read Inputs
 
 Read in order:
@@ -73,9 +83,25 @@ For each function (or logical group of closely related functions = one module):
 
 Read `SD-FRONTEND-TEMPLATE.md` for document structure.
 
-### 4.2 Fill Technology-Specific Details
+### 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: `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.
 
-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 |
 |---------|----------------------------|
@@ -86,16 +112,19 @@ Fill each section with technology-specific implementation details:
 | Routing | Actual router config format |
 | Pseudo-code | MUST use actual framework syntax from techs knowledge |
 
-### 4.3 Write Module Design
-
-Write to: `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/{module}-design.md`
-
 **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
 
 After all module designs are complete:
@@ -104,7 +133,20 @@ After all module designs are complete:
 
 Read `INDEX-TEMPLATE.md` for document structure.
 
-### 5.2 Fill Platform-Level Summary
+### 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 |
 |---------|---------------|
@@ -119,9 +161,12 @@ Read `INDEX-TEMPLATE.md` for document structure.
 
 Create table with links to each module design document.
 
-### 5.4 Write INDEX
+### 5.4 Verify Output
 
-Write to: `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/INDEX.md`
+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
 

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

@@ -12,6 +12,16 @@ tools: Read, Write, Glob, Grep
 
 # 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.
+
 ## Step 1: Read Inputs
 
 Read in order:
@@ -74,9 +84,25 @@ For each function (or logical group of closely related functions = one module):
 
 Read `SD-MOBILE-TEMPLATE.md` for document structure.
 
-### 4.2 Fill Technology-Specific Details
+### 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.
 
-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 |
 |---------|----------------------------|
@@ -89,16 +115,19 @@ Fill each section with technology-specific implementation details:
 | Platform features | Actual plugin APIs (camera, geolocator, local_notifications, etc.) |
 | Pseudo-code | MUST use actual framework syntax from techs knowledge |
 
-### 4.3 Write Module Design
-
-Write to: `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/{module}-design.md`
-
 **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
 
 After all module designs are complete:
@@ -107,7 +136,20 @@ After all module designs are complete:
 
 Read `INDEX-TEMPLATE.md` for document structure.
 
-### 5.2 Fill Platform-Level Summary
+### 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 |
 |---------|---------------|
@@ -124,9 +166,12 @@ Read `INDEX-TEMPLATE.md` for document structure.
 
 Create table with links to each module design document.
 
-### 5.4 Write INDEX
+### 5.4 Verify Output
 
-Write to: `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/INDEX.md`
+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