speccrew 0.1.9 → 0.1.11

package/.speccrew/agents/speccrew-system-developer.md

@@ -1,9 +1,7 @@
-# speccrew-system-developer
-
-**Description**: SpecCrew System Developer. Reads system design blueprints and coordinates cross-platform development task dispatch. Loads techs knowledge, verifies environment readiness, dispatches per-platform dev skills, performs integration checks, and delivers development completion reports. Supports web, mobile, desktop, and backend platforms.
-
-**Tools**: Bash, Edit, Write, Glob, Grep, Read, WebFetch, WebSearch
-
+---
+name: speccrew-system-developer
+description: SpecCrew System Developer. Reads system design blueprints and coordinates cross-platform development task dispatch. Loads techs knowledge, verifies environment readiness, dispatches per-platform dev skills, performs integration checks, and delivers development completion reports. Supports web, mobile, desktop, and backend platforms.
+tools: Read, Write, Glob, Grep, Bash
 ---
 
 # Role Positioning

package/.speccrew/agents/speccrew-task-worker.md

@@ -1,7 +1,7 @@
 ---
 name: speccrew-task-worker
 description: Generic task execution Worker. Invoked in parallel by other Agents with multiple instances, receives context parameters and optional Skill path, executes tasks according to Skill definition if provided, or directly processes the task based on context. Specialized for batch document read/write operations, splitting large tasks into small, context-isolated subtasks for parallel execution.
-tools: Read, Grep, Glob, Write, Bash, Edit
+tools: Read, Grep, Glob, Write, Bash, Edit, WebFetch, WebSearch
 ---
 
 # Role Definition

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

@@ -12,6 +12,18 @@ tools: Bash, Edit, Write, Glob, Grep, Read
 
 # Workflow
 
+## Absolute Constraints
+
+> **These rules apply to Task Record document generation. Violation = task failure.**
+
+1. **FORBIDDEN: `create_file` for Task Record** — NEVER use `create_file` to write the Task Record document. It MUST be created by copying the template then filling sections with `search_replace`. `create_file` produces truncated output on large files.
+
+2. **FORBIDDEN: Full-file rewrite** — NEVER replace the entire Task Record 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. **CLARIFICATION: Source code is NOT template-filled** — Actual source code files are written directly based on design blueprints. The template-fill workflow applies ONLY to the Task Record document.
+
 ## Step 1: Read Design Documents
 
 Read in order:
@@ -29,11 +41,25 @@ Read in order:
 
 ## Step 2: Create Task Record File
 
-Before coding, create the task record:
+Before coding, create the task record using template-fill workflow:
+
+### 2a Copy Template to Task Record Path
+
+1. **Read the template file**: `templates/TASK-RECORD-TEMPLATE.md`
+2. **Replace top-level placeholders** (module name, feature name, platform ID, iteration info)
+3. **Create the document** using `create_file`:
+   - Target path: `speccrew-workspace/iterations/{number}-{type}-{name}/04.development/{platform_id}/[module]-task.md`
+   - Content: Template with top-level placeholders replaced
+4. **Verify**: Document has complete section structure ready for filling
+
+### 2b Fill Task Record Sections Using search_replace
 
-**Path**: `speccrew-workspace/iterations/{number}-{type}-{name}/04.development/{platform_id}/[module]-task.md`
+Fill each section with design metadata extracted from input documents.
 
-Initialize with design metadata and prepare task checklist structure.
+> ⚠️ **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**
 
 ## Step 3: Extract Task List
 

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

@@ -12,6 +12,18 @@ tools: Bash, Edit, Write, Glob, Grep, Read
 
 # Workflow
 
+## Absolute Constraints
+
+> **These rules apply to Task Record document generation. Violation = task failure.**
+
+1. **FORBIDDEN: `create_file` for Task Record** — NEVER use `create_file` to write the Task Record document. It MUST be created by copying the template then filling sections with `search_replace`. `create_file` produces truncated output on large files.
+
+2. **FORBIDDEN: Full-file rewrite** — NEVER replace the entire Task Record 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. **CLARIFICATION: Source code is NOT template-filled** — Actual source code files are written directly based on design blueprints. The template-fill workflow applies ONLY to the Task Record document.
+
 ## Step 1: Read Design Documents
 
 Read in order:
@@ -43,15 +55,31 @@ Use Glob/Grep to understand current codebase:
 
 Document findings for reference in later steps.
 
-## Step 3: Extract Task List
+## Step 3: Extract Task List and Create Task Record
 
-Create task record file:
+### 3.1 Create Task Record File Using Template-Fill Workflow
 
 **Path**: `speccrew-workspace/iterations/{number}-{type}-{name}/04.development/{platform_id}/[feature-name]-task.md`
 
-**Read Template**: `speccrew-dev-desktop/templates/TASK-RECORD-TEMPLATE.md`
+#### 3.1a Copy Template to Task Record Path
+
+1. **Read the template file**: `speccrew-dev-desktop/templates/TASK-RECORD-TEMPLATE.md`
+2. **Replace top-level placeholders** (feature name, platform ID, iteration info)
+3. **Create the document** using `create_file`:
+   - Target path: `speccrew-workspace/iterations/{number}-{type}-{name}/04.development/{platform_id}/[feature-name]-task.md`
+   - Content: Template with top-level placeholders replaced
+4. **Verify**: Document has complete section structure ready for filling
+
+#### 3.1b Fill Task Record Sections Using search_replace
+
+Fill each section with task checklist and design metadata extracted from input documents.
+
+> ⚠️ **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**
 
-### Desktop-Specific Task Types
+### 3.2 Desktop-Specific Task Types
 
 | Task Type | Description | Example |
 |-----------|-------------|---------|

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

@@ -12,6 +12,18 @@ tools: Bash, Edit, Write, Glob, Grep, Read
 
 # Workflow
 
+## Absolute Constraints
+
+> **These rules apply to Task Record document generation. Violation = task failure.**
+
+1. **FORBIDDEN: `create_file` for Task Record** — NEVER use `create_file` to write the Task Record document. It MUST be created by copying the template then filling sections with `search_replace`. `create_file` produces truncated output on large files.
+
+2. **FORBIDDEN: Full-file rewrite** — NEVER replace the entire Task Record 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. **CLARIFICATION: Source code is NOT template-filled** — Actual source code files are written directly based on design blueprints. The template-fill workflow applies ONLY to the Task Record document.
+
 ## Step 1: Read Design Documents
 
 Read in order:
@@ -66,9 +78,27 @@ Wait for user approval before writing any code.
 
 ### 3.4 Write Initial Task Record
 
-Write to: `speccrew-workspace/iterations/{number}-{type}-{name}/04.development/{platform_id}/{feature-name}-tasks.md`
+Create the task record using template-fill workflow:
+
+**Target Path**: `speccrew-workspace/iterations/{number}-{type}-{name}/04.development/{platform_id}/{feature-name}-tasks.md`
+
+#### 3.4a Copy Template to Task Record Path
+
+1. **Read the template file**: `speccrew-dev-frontend/templates/TASK-RECORD-TEMPLATE.md` (from Step 1)
+2. **Replace top-level placeholders** (feature name, platform ID, iteration info)
+3. **Create the document** using `create_file`:
+   - Target path: `speccrew-workspace/iterations/{number}-{type}-{name}/04.development/{platform_id}/{feature-name}-tasks.md`
+   - Content: Template with top-level placeholders replaced
+4. **Verify**: Document has complete section structure ready for filling
+
+#### 3.4b Fill Task Record Sections Using search_replace
+
+Fill each section with task checklist and design metadata.
 
-Use template from Step 1.
+> ⚠️ **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**
 
 ## Step 4: Execute Tasks
 

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

@@ -12,6 +12,18 @@ tools: Bash, Edit, Write, Glob, Grep, Read
 
 # Workflow
 
+## Absolute Constraints
+
+> **These rules apply to Task Record document generation. Violation = task failure.**
+
+1. **FORBIDDEN: `create_file` for Task Record** — NEVER use `create_file` to write the Task Record document. It MUST be created by copying the template then filling sections with `search_replace`. `create_file` produces truncated output on large files.
+
+2. **FORBIDDEN: Full-file rewrite** — NEVER replace the entire Task Record 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. **CLARIFICATION: Source code is NOT template-filled** — Actual source code files are written directly based on design blueprints. The template-fill workflow applies ONLY to the Task Record document.
+
 ## Step 1: Read Design Documents
 
 Read in order:
@@ -81,11 +93,27 @@ Use `MB-001`, `MB-002`, etc. for mobile tasks.
 
 ## Step 4: Create Task Record File
 
-Before writing code, create task record file:
+Before writing code, create task record file using template-fill workflow:
 
 **Path**: `speccrew-workspace/iterations/{iteration}/04.development/{platform_id}/{module}-task.md`
 
-Use `TASK-RECORD-TEMPLATE.md` for structure.
+### 4a Copy Template to Task Record Path
+
+1. **Read the template file**: `speccrew-dev-mobile/templates/TASK-RECORD-TEMPLATE.md`
+2. **Replace top-level placeholders** (module name, feature name, platform ID, iteration info)
+3. **Create the document** using `create_file`:
+   - Target path: `speccrew-workspace/iterations/{iteration}/04.development/{platform_id}/{module}-task.md`
+   - Content: Template with top-level placeholders replaced
+4. **Verify**: Document has complete section structure ready for filling
+
+### 4b Fill Task Record Sections Using search_replace
+
+Fill each section with task checklist and design metadata extracted from input documents.
+
+> ⚠️ **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**
 
 ## Step 5: Execute Task by Task
 

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

@@ -11,6 +11,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 the API contract document. It MUST be created by copying the template (Step 4a) then filling sections with `search_replace` (Step 4b). `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** — Step 4a (copy template) MUST execute before Step 4b (fill sections). Skipping Step 4a and writing content directly is FORBIDDEN.
+
 ## Step 1: Read Input
 
 1. Feature spec document: `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-feature-spec.md`
@@ -38,9 +48,35 @@ Complete definition for each API:
 - Success response example (JSON)
 - Error code list
 
-## Step 4: Write to File
+## Step 4: Write API Contract Document
+
+### 4a Copy Template to Document Path
+
+1. **Read the template file**: `templates/API-CONTRACT-TEMPLATE.md`
+2. **Replace top-level placeholders** (feature name, date, etc.)
+3. **Create the document** using `create_file`:
+   - Target path: `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-api-contract.md`
+   - Content: Template with top-level placeholders replaced
+4. **Verify**: Document has complete section structure ready for filling
+
+### 4b Fill Each Section Using search_replace
+
+Fill each section with API contract details from Step 2 and Step 3.
+
+> ⚠️ **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 MUST be preserved**
+
+**Section Filling Order:**
+
+| Section | Content Source |
+|---------|---------------|
+| **API List Overview** | API list table from Step 2 |
+| **API Contract Details** | Full contract definitions from Step 3 (per API) |
+| **Error Code Summary** | Aggregated error codes across all APIs |
 
-Write path: `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-api-contract.md`
+For each API, locate its section anchor in the template and use `search_replace` to fill request parameters, response structure, success example, and error codes.
 
 ## Step 5: Joint Confirmation
 

package/.speccrew/skills/speccrew-fd-feature-design/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 the feature spec document. Documents MUST be created by copying the template (Step 10.2a) then filling sections with `search_replace` (Step 10.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** — Step 10.2a (copy template) MUST execute before Step 10.2b (fill sections). Skipping Step 10.2a and writing content directly is FORBIDDEN.
+
 ## Step 1: Read PRD Input
 
 Read in order:
@@ -408,16 +418,42 @@ speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/
 
 If the iteration directory does not exist, refer to the `000-sample` directory structure to create it.
 
-### 10.2 Write Feature Spec Documents
+### 10.2a Copy Template to Document Path
+
+1. **Read the template file**: `templates/FEATURE-SPEC-TEMPLATE.md`
+2. **Replace top-level placeholders** in the template content:
+   - `{Feature Name}` → actual feature name
+   - Other top-level identifiers from PRD input
+3. **Create the document file** using `create_file`:
+   - Target path: determined in Step 10.1
+   - Content: Template with top-level placeholders replaced
+4. **Verify**: Document should have complete section structure ready for filling
+
+### 10.2b Fill Each Section Using search_replace
+
+Fill each section of the document with actual data from analysis steps.
+
+> ⚠️ **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** — do not delete or renumber
+> - If a section has no applicable content, keep the section title and replace placeholder with "N/A"
+
+**Section Filling Order:**
+
+Fill sections sequentially using `search_replace` for each content block:
+
+| Section | Content Source |
+|---------|---------------|
+| **Feature Overview** | One paragraph explaining what this feature does |
+| **Function Breakdown** | All functions with [EXISTING]/[MODIFIED]/[NEW] markers |
+| **Frontend Design** | ASCII wireframes, interaction flows, API mapping |
+| **Backend Design** | Interface list, logic flows, data access schemes |
+| **Data Model** | Entity definitions, relationships, modifications |
+| **Business Rules** | Permissions, validation, business logic rules |
+| **Cross-Module Interactions** | **[If applicable]** Interface contracts between modules |
 
-Fill in according to template structure, requirements:
-- **Feature Overview**: One paragraph explaining what this feature does
-- **Function Breakdown**: All functions with [EXISTING]/[MODIFIED]/[NEW] markers
-- **Frontend Design**: ASCII wireframes, interaction flows, API mapping
-- **Backend Design**: Interface list, logic flows, data access schemes
-- **Data Model**: Entity definitions, relationships, modifications
-- **Business Rules**: Permissions, validation, business logic rules
-- **Cross-Module Interactions**: **[If applicable]** Interface contracts between modules
+For Master-Sub specs, repeat Step 10.2a + 10.2b for each sub-spec document.
 
 ### 10.3 Mermaid Diagram Requirements
 

package/.speccrew/skills/speccrew-knowledge-bizs-ui-style-extract/SKILL.md

@@ -56,6 +56,16 @@ Extract and aggregate **UI design patterns** from bizs pipeline analyzed feature
     └── ...
 ```
 
+## Absolute Constraints
+
+> **These rules apply to ALL document generation steps. Violation = task failure.**
+
+1. **FORBIDDEN: `create_file` for pattern documents** — NEVER use `create_file` to write pattern documents. Each document MUST be created by copying the appropriate 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 for every pattern document.
+
 ## Workflow Overview
 
 ```mermaid
@@ -156,23 +166,34 @@ graph TB
 
 ## Step 5: Generate Pattern Documents
 
-**Goal**: Create pattern documents for each identified pattern.
+**Goal**: Create pattern documents for each identified pattern using template-fill workflow.
 
-**Action**:
-- For each identified pattern, generate a `.md` document using the appropriate template
-- Place documents in corresponding subdirectories:
-  - Page types → `{output_path}/page-types/`
-  - Component patterns → `{output_path}/components/`
-  - Layout patterns → `{output_path}/layouts/`
+### 5.1 Template Selection
+
+| Pattern Category | Template File | Output Directory |
+|-----------------|---------------|------------------|
+| Page types | `templates/PAGE-TYPE-TEMPLATE.md` | `{output_path}/page-types/` |
+| Component patterns | `templates/COMPONENT-PATTERN-TEMPLATE.md` | `{output_path}/components/` |
+| Layout patterns | `templates/LAYOUT-PATTERN-TEMPLATE.md` | `{output_path}/layouts/` |
 
 **File Naming Convention**:
 - Use `kebab-case` for pattern names
 - Examples: `list-page.md`, `search-filter-bar.md`, `sidebar-content.md`
 
-**Template Application**:
-- Use `PAGE-TYPE-TEMPLATE.md` for page type patterns
-- Use `COMPONENT-PATTERN-TEMPLATE.md` for component patterns
-- Use `LAYOUT-PATTERN-TEMPLATE.md` for layout patterns
+### 5.2 For Each Pattern: Copy Template to Document Path
+
+For each identified pattern:
+1. **Select the appropriate template** based on pattern category
+2. **Replace top-level placeholders** (pattern name, category, etc.)
+3. **Create the document** using `create_file` at the corresponding output path
+4. **Verify**: Document has complete section structure ready for filling
+
+### 5.3 For Each Pattern: Fill Sections Using search_replace
+
+> ⚠️ **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**
 
 **Content Requirements**:
 1. **ASCII wireframes**: Must be generalized versions (not direct copies from specific features)

package/.speccrew/skills/speccrew-knowledge-module-summarize/SKILL.md

@@ -49,6 +49,16 @@ flowchart TD
     Step6 --> End([End])
 ```
 
+### Absolute Constraints
+
+> **These rules apply to ALL steps. Violation = task failure.**
+
+1. **FORBIDDEN: `create_file` for overview document** — NEVER use `create_file` to write the module overview document. If the initial skeleton exists, use `search_replace` to fill sections. If no skeleton exists, copy the template first then fill 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** — Template (or existing skeleton) MUST be in place before filling sections. Writing content without a template base is FORBIDDEN.
+
 ### Step 1: Read Prerequisites
 
 Before processing, read all required files:
@@ -129,16 +139,35 @@ Collect all business rules from feature details:
 1. **Read Configuration**:
    - Read `speccrew-workspace/docs/rules/mermaid-rule.md` - Get Mermaid diagram compatibility guidelines
 
-2. **Use template `templates/MODULE-OVERVIEW-TEMPLATE.md`, fill all sections**:
-   - Follow [Mermaid Diagram Guide](#mermaid-diagram-guide) for diagram generation
+2. **Prepare document file (if not already exists)**:
+   - If the initial skeleton from Step 1 exists at `module_path/module_name-overview.md`:
+     - Use the existing file as the base (sections 1-2 already populated)
+   - If no skeleton exists:
+     - **Read template**: `templates/MODULE-OVERVIEW-TEMPLATE.md`
+     - **Replace top-level placeholders** (module name, language, etc.)
+     - **Create document** using `create_file` at `module_path/module_name-overview.md`
+
+3. **Fill each section using search_replace**:
+
+> ⚠️ **CRITICAL CONSTRAINTS:**
+> - **FORBIDDEN: `create_file` to rewrite the entire document** — it destroys template/skeleton 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"
+
+**Locate and fill via `search_replace`:**
 
 **Section 1: Module Basic Info** (from initial version)
 - Keep existing information
 
+**Locate and fill via `search_replace`:**
+
 **Section 2: Feature List** (from initial version)
 - Keep feature list table
 - Ensure all links to {{feature_name}}.md are correct
 
+**Locate and fill via `search_replace`:**
+
 **Section 3: Business Entities** (NEW)
 
 **Backend example:**
@@ -154,6 +183,8 @@ Collect all business rules from feature details:
 
 Include ER diagram based on entity relationships.
 
+**Locate and fill via `search_replace`:**
+
 **Section 4: Dependencies** (NEW)
 
 **Backend example:**
@@ -167,6 +198,8 @@ Include ER diagram based on entity relationships.
 | Imports | UserStore | Get user state | Store injection |
 | Imports | UserCard | Display user info | Component import |
 
+**Locate and fill via `search_replace`:**
+
 **Section 5: Core Business Flows** (NEW)
 
 Based on feature interactions, identify core flows:
@@ -177,6 +210,8 @@ Create Order: Validate params → Calculate amount → Save to DB → Notify dow
 **Frontend example:**
 Order List: Load data → Display list → User selects → Load detail → Display detail → Edit → Submit → Update state
 
+**Locate and fill via `search_replace`:**
+
 **Section 6: Business Rules** (NEW)
 
 | Rule ID | Rule Name | Description | Related Features |

package/.speccrew/skills/speccrew-knowledge-system-summarize/SKILL.md

@@ -40,6 +40,16 @@ Worker Agent (speccrew-task-worker)
 
 ## Workflow
 
+### Absolute Constraints
+
+> **These rules apply to ALL steps. Violation = task failure.**
+
+1. **FORBIDDEN: `create_file` for documents** — NEVER use `create_file` to write the system overview document. It MUST be created by copying the template (Step 7a) then filling sections with `search_replace` (Step 7b). `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** — Step 7a (copy template) MUST execute before Step 7b (fill sections). Skipping Step 7a and writing content directly is FORBIDDEN.
+
 ### Prerequisites
 
 Before starting, verify:
@@ -219,8 +229,21 @@ Create flow-module mapping matrix:
    - **CRITICAL**: Use the Skill tool to invoke `speccrew-get-timestamp` (no parameters needed, uses default format `YYYY-MM-DD-HHmmss`, returns timestamp string e.g. `2026-03-17-132645`)
    - Use the returned timestamp as generation timestamp in document
 
-3. **Use template `templates/SYSTEM-OVERVIEW-TEMPLATE.md`, fill all sections**:
-   - Follow [Mermaid Diagram Guide](#mermaid-diagram-guide) for diagram generation
+4. **Copy template to document path (Step 7a)**:
+   - Read template: `templates/SYSTEM-OVERVIEW-TEMPLATE.md` (already loaded in Step 0)
+   - Replace top-level placeholders (system name, generation timestamp, tech stack info)
+   - Create document using `create_file` at: `output_path/system-overview.md`
+   - Verify: Document has complete section structure ready for filling
+
+5. **Fill each section using search_replace (Step 7b)**:
+
+> ⚠️ **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 MUST be preserved**
+> - If a section has no applicable content, keep the section title and replace placeholder with "N/A"
+
+**Fill via `search_replace`:**
 
 **Section: Index and Overview** (NEW)
 - Generation timestamp (from get-timestamp skill)
@@ -228,27 +251,37 @@ Create flow-module mapping matrix:
 - Statistics: module count, entity count, API count, flow count
 - Module quick index table
 
+**Fill via `search_replace`:**
+
 **Section 1: System Overview**
 - System name from project config
 - Core positioning
 - Target users
 - Deployment type
 
+**Fill via `search_replace`:**
+
 **Section 2: Module Topology**
 - Business domain diagram
 - Module hierarchy diagram
 - Module dependency diagram
 - Module index table (from Step 3)
 
+**Fill via `search_replace`:**
+
 **Section 3: End-to-End Business Flows**
 - Core business process list
 - Flow-module mapping matrix (from Step 6)
 - Typical flow diagrams
 
+**Fill via `search_replace`:**
+
 **Section 4: System Boundaries and Integration**
 - External system integration diagram
 - Integration interface list
 
+**Fill via `search_replace`:**
+
 **Section 5: Requirement Assessment Guide**
 - Reference to `speccrew-pm-requirement-assess` skill
 - Quick location guide (which section to reference)