speccrew 0.7.54 → 0.7.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,240 @@
1
+ ---
2
+ name: speccrew-sd-design-overview-generate
3
+ version: 1.0.0
4
+ description: Design Overview Generation Skill for System Designer. Reads Feature Registry, techs-manifest platforms, and framework evaluation results to generate a comprehensive DESIGN-OVERVIEW.md with Feature×Platform matrix index. Invoked by System Designer Agent during Phase 4 via worker dispatch.
5
+ tools: Read, Write, Glob, Grep
6
+ ---
7
+
8
+ # Trigger Scenarios
9
+
10
+ - System Designer Agent dispatches this skill during Phase 4 to generate DESIGN-OVERVIEW.md
11
+ - User requests a design overview document for the current iteration
12
+ - Need to establish a Feature×Platform matrix index before per-platform system design begins
13
+
14
+ ## AgentFlow Definition
15
+
16
+ <!-- @agentflow: workflow.agentflow.xml -->
17
+
18
+ > **REQUIRED**: Before executing this workflow, read the XML workflow specification: `speccrew-workspace/docs/rules/agentflow-spec.md`
19
+
20
+ ## Workflow
21
+
22
+ ## Absolute Constraints
23
+
24
+ > **These rules apply to ALL steps. Violation = task failure.**
25
+
26
+ 1. **READ-ONLY on Feature Spec and API Contract** — NEVER modify Feature Spec or API Contract documents. Only read for reference.
27
+ 2. **READ-ONLY on techs-manifest.json** — NEVER modify the techs manifest. Only read for platform information.
28
+ 3. **READ-ONLY on framework-evaluation.md** — NEVER modify the framework evaluation report. Only read for technology decisions.
29
+ 4. **Single Output Only** — Only create DESIGN-OVERVIEW.md at the specified output_path. No other files.
30
+ 5. **Direct-to-File Output** — Write all content directly to DESIGN-OVERVIEW.md. DO NOT display document content in conversation.
31
+
32
+ ## Step 1: Read Inputs
33
+
34
+ **Input Parameters** (from agent context):
35
+
36
+ | Parameter | Type | Required | Description |
37
+ |-----------|------|----------|-------------|
38
+ | `workspace_path` | string | Yes | speccrew-workspace root directory path |
39
+ | `iteration_path` | string | Yes | Current iteration directory path |
40
+ | `feature_registry_path` | string | Yes | Path to .prd-feature-list.json |
41
+ | `techs_manifest_path` | string | Yes | Path to techs-manifest.json |
42
+ | `framework_evaluation_path` | string | Yes | Path to framework-evaluation.md |
43
+ | `output_path` | string | No | Output file path (default: iteration_path/03.system-design/DESIGN-OVERVIEW.md) |
44
+
45
+ Read in order:
46
+
47
+ 1. **Read .prd-feature-list.json** — Extract features array:
48
+ - `feature_id` (e.g., F-CRM-01) or `module_name` for legacy format
49
+ - `feature_name` or `module_name`
50
+ - `feature_spec` path
51
+ - `api_contract` path
52
+ - `module`
53
+ - `type`
54
+
55
+ 2. **Read techs-manifest.json** — Extract platforms array:
56
+ - `platform_id` (e.g., web-react, backend-nodejs)
57
+ - `friendly_name`
58
+ - `tech_stack`
59
+
60
+ 3. **Read framework-evaluation.md** — Extract Technology Decisions:
61
+ - Framework evaluation results
62
+ - New dependencies introduced (if any)
63
+ - Version constraints
64
+
65
+ ## Step 2: Build Feature×Platform Matrix
66
+
67
+ For each feature × platform combination, generate one matrix row:
68
+
69
+ | Field | Source |
70
+ |-------|--------|
71
+ | `feature_id` | feature.feature_id (or "-" for legacy format) |
72
+ | `feature_name` | feature.feature_name (or feature.module_name for legacy) |
73
+ | `platform` | platform.friendly_name |
74
+ | `platform_id` | platform.platform_id |
75
+ | `skill` | Map platform_id prefix → speccrew-sd-{type} (see below) |
76
+ | `design_directory` | {platform_id}/{feature_id}-{feature_name}-design.md (new) or {platform_id}/{module}-design.md (legacy) |
77
+ | `status` | Always "pending" |
78
+
79
+ ### Platform ID Prefix → Skill Mapping
80
+
81
+ | Platform ID Prefix | Target Skill |
82
+ |-------------------|--------------|
83
+ | web-* | speccrew-sd-frontend |
84
+ | backend-* | speccrew-sd-backend |
85
+ | mobile-* | speccrew-sd-mobile |
86
+ | desktop-* | speccrew-sd-desktop |
87
+
88
+ ### Legacy Format Compatibility
89
+
90
+ If a feature does NOT have a Feature ID (no "F-" prefix):
91
+ - Feature ID column displays `-`
92
+ - Use `module_name` as Feature Name
93
+ - Design Directory uses `{platform_id}/{module_name}-design.md` (legacy format)
94
+
95
+ ## Step 3: Generate DESIGN-OVERVIEW.md
96
+
97
+ Write the design overview document to `output_path`.
98
+
99
+ ### Document Structure
100
+
101
+ ```markdown
102
+ # System Design Overview - {Iteration Name}
103
+
104
+ ## 1. Design Scope
105
+
106
+ - **Iteration**: {iteration_identifier}
107
+ - **Platforms**: {platform_list}
108
+ - **Features**: {count} features discovered
109
+
110
+ ### 1.1 Feature List
111
+
112
+ | Feature ID | Feature Name | Feature Spec | API Contract |
113
+ |------------|--------------|--------------|--------------|
114
+ | (from feature registry, one row per feature) |
115
+
116
+ > **Legacy Format Compatibility**: If file uses legacy format (no Feature ID), Feature ID column shows `-`, using module name as Feature Name
117
+
118
+ ## 2. Technology Decisions
119
+
120
+ (from framework-evaluation.md - Phase 3 results)
121
+
122
+ - Framework evaluation results
123
+ - New dependencies introduced (if any)
124
+ - Version constraints
125
+
126
+ ## 3. Platform Design Index
127
+
128
+ | Feature ID | Feature Name | Platform | Platform ID | Skill | Design Directory | Status |
129
+ |------------|--------------|----------|-------------|-------|------------------|--------|
130
+ | (Feature × Platform matrix from Step 2) |
131
+
132
+ > **Notes**:
133
+ > - New Format: Design Directory contains `{feature-id}-{feature-name}` (e.g., `F-CRM-01-customer-list-design.md`)
134
+ > - Legacy Format: Design Directory uses `{module}-design.md`
135
+
136
+ ## 4. Feature Summary (Optional - when Feature count > 5)
137
+
138
+ ### 4.1 Feature by Module
139
+
140
+ | Module | Feature Count | Feature IDs |
141
+ |--------|---------------|-------------|
142
+ | (group features by module) |
143
+
144
+ ### 4.2 Feature Type Distribution
145
+
146
+ | Type | Count | Features |
147
+ |------|-------|----------|
148
+ | (group features by type) |
149
+
150
+ ## 5. Cross-Platform Concerns
151
+
152
+ - Shared data structures
153
+ - Cross-platform API contracts
154
+ - Authentication/authorization strategy
155
+ - Error handling conventions
156
+
157
+ ## 6. Design Constraints
158
+
159
+ - API Contract is READ-ONLY — do not modify
160
+ - All pseudo-code must use actual framework syntax from techs knowledge
161
+ - Each module design document maps 1:1 to a Feature Spec function
162
+ ```
163
+
164
+ ## Step 4: Validate Output
165
+
166
+ After writing DESIGN-OVERVIEW.md, verify:
167
+
168
+ - [ ] File exists at output_path
169
+ - [ ] Contains "## 1. Design Scope" section
170
+ - [ ] Contains "## 2. Technology Decisions" section
171
+ - [ ] Contains "## 3. Platform Design Index" table
172
+ - [ ] Platform Design Index covers all Feature × Platform combinations
173
+ - [ ] Feature count matches feature registry
174
+ - [ ] Platform count matches techs-manifest
175
+ - [ ] All index entries have status "pending"
176
+
177
+ ## Step 5: Output Task Completion Report
178
+
179
+ After validation, output:
180
+
181
+ ```
182
+ --- TASK COMPLETION REPORT ---
183
+ Task: Design Overview Generation
184
+ Status: SUCCESS
185
+ Output: {output_path}
186
+ Features: {feature_count}
187
+ Platforms: {platform_count}
188
+ Matrix Entries: {feature_count × platform_count}
189
+ --- END REPORT ---
190
+ ```
191
+
192
+ If any step fails:
193
+
194
+ ```
195
+ --- TASK COMPLETION REPORT ---
196
+ Task: Design Overview Generation
197
+ Status: FAILED
198
+ Error: {specific error description}
199
+ Failed At: Step {N}
200
+ --- END REPORT ---
201
+ ```
202
+
203
+ ## OUTPUT EFFICIENCY RULES
204
+
205
+ When executing this skill:
206
+
207
+ 1. **Direct-to-File Output**: All design overview content MUST be written directly to DESIGN-OVERVIEW.md
208
+ 2. **Minimal Conversation Output**: Only output:
209
+ - Block execution announcements (1 line each): `[Block XX] Building matrix...`
210
+ - Error messages requiring attention
211
+ - Task Completion Report (final summary)
212
+ 3. **FORBIDDEN in conversation**:
213
+ - Full document sections or drafts
214
+ - Feature × Platform matrix tables
215
+ - Feature list tables
216
+ - Technology decision excerpts longer than 2 lines
217
+ 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.
218
+
219
+ # Key Rules
220
+
221
+ | Rule | Description |
222
+ |------|-------------|
223
+ | **FORBIDDEN: Input Modification** | Do NOT modify feature specs, API contracts, techs-manifest, or framework-evaluation |
224
+ | **FORBIDDEN: Extra Files** | Do NOT create any files other than DESIGN-OVERVIEW.md |
225
+ | **FORBIDDEN: Conversation Output** | Do NOT display DESIGN-OVERVIEW content in conversation — write directly to file |
226
+ | **MANDATORY: Complete Matrix** | Platform Design Index MUST cover ALL Feature × Platform combinations |
227
+ | **MANDATORY: Pending Status** | ALL Platform Design Index entries MUST have status "pending" |
228
+
229
+ # Checklist
230
+
231
+ - [ ] .prd-feature-list.json read and features array extracted
232
+ - [ ] techs-manifest.json read and platforms array extracted
233
+ - [ ] framework-evaluation.md read and technology decisions extracted
234
+ - [ ] Feature format detected (new or legacy)
235
+ - [ ] Feature × Platform matrix built with all combinations
236
+ - [ ] Platform ID prefix correctly mapped to target skills
237
+ - [ ] DESIGN-OVERVIEW.md generated with all required sections
238
+ - [ ] Feature Summary section included only when feature count > 5
239
+ - [ ] Output validated against checklist
240
+ - [ ] Task Completion Report output
@@ -0,0 +1,161 @@
1
+ <?xml version="1.0" encoding="UTF-8"?>
2
+ <workflow id="sd-design-overview-generate-main" status="pending" version="1.0.0" desc="Design Overview Generation workflow">
3
+
4
+ <!-- ============================================================
5
+ Input Parameters Definition
6
+ ============================================================ -->
7
+ <block type="input" id="I1" desc="Workflow input parameters">
8
+ <field name="workspace_path" required="true" type="string" desc="speccrew-workspace root directory path"/>
9
+ <field name="iteration_path" required="true" type="string" desc="Current iteration directory path"/>
10
+ <field name="feature_registry_path" required="true" type="string" desc="Path to .prd-feature-list.json"/>
11
+ <field name="techs_manifest_path" required="true" type="string" desc="Path to techs-manifest.json"/>
12
+ <field name="framework_evaluation_path" required="true" type="string" desc="Path to framework-evaluation.md"/>
13
+ <field name="output_path" required="false" type="string" desc="Output file path (default: iteration_path/03.system-design/DESIGN-OVERVIEW.md)"/>
14
+ </block>
15
+
16
+ <!-- ============================================================
17
+ Global Rules
18
+ ============================================================ -->
19
+ <block type="rule" id="R1" level="forbidden" desc="Input File Protection">
20
+ <field name="text">DO NOT modify any input files (feature specs, API contracts, techs-manifest.json, framework-evaluation.md)</field>
21
+ </block>
22
+
23
+ <block type="rule" id="R2" level="forbidden" desc="Single Output Only">
24
+ <field name="text">DO NOT create any files other than DESIGN-OVERVIEW.md at the specified output_path</field>
25
+ </block>
26
+
27
+ <block type="rule" id="R3" level="mandatory" desc="Direct-to-File Output">
28
+ <field name="text">Write all design content directly to DESIGN-OVERVIEW.md. DO NOT display document content in conversation.</field>
29
+ </block>
30
+
31
+ <block type="rule" id="R4" level="mandatory" desc="Complete Matrix Coverage">
32
+ <field name="text">Platform Design Index MUST cover ALL Feature × Platform combinations. No feature or platform may be omitted.</field>
33
+ </block>
34
+
35
+ <!-- ============================================================
36
+ Main Processing Sequence
37
+ ============================================================ -->
38
+ <sequence id="S1" name="Design Overview Generation" status="pending" desc="Generate DESIGN-OVERVIEW.md with Feature×Platform matrix">
39
+
40
+ <!-- Step 1: Read Feature Registry -->
41
+ <block type="task" id="B1" action="read-file" status="pending" desc="Read Feature Registry (.prd-feature-list.json)">
42
+ <field name="path" value="${feature_registry_path}"/>
43
+ <field name="output" var="feature_registry"/>
44
+ </block>
45
+
46
+ <!-- Step 2: Read Techs Manifest -->
47
+ <block type="task" id="B2" action="read-file" status="pending" desc="Read Techs Manifest (techs-manifest.json)">
48
+ <field name="path" value="${techs_manifest_path}"/>
49
+ <field name="output" var="techs_manifest"/>
50
+ </block>
51
+
52
+ <!-- Step 3: Read Framework Evaluation -->
53
+ <block type="task" id="B3" action="read-file" status="pending" desc="Read Framework Evaluation Report">
54
+ <field name="path" value="${framework_evaluation_path}"/>
55
+ <field name="output" var="framework_evaluation"/>
56
+ </block>
57
+
58
+ <!-- Step 4: Determine Feature Format -->
59
+ <block type="gateway" id="G1" mode="exclusive" desc="Check Feature ID format">
60
+ <branch test="${feature_registry.features[0].feature_id} exists and starts with 'F-'" name="New Format">
61
+ <block type="event" id="E1" action="log" level="info" desc="New format detected">
62
+ <field name="message">Feature registry uses new format with F- prefixed Feature IDs</field>
63
+ </block>
64
+ <field name="format" var="feature_format" value="new"/>
65
+ </branch>
66
+ <branch default="true" name="Legacy Format">
67
+ <block type="event" id="E2" action="log" level="info" desc="Legacy format detected">
68
+ <field name="message">Feature registry uses legacy format (no Feature IDs)</field>
69
+ </block>
70
+ <field name="format" var="feature_format" value="legacy"/>
71
+ </branch>
72
+ </block>
73
+
74
+ <!-- Step 5: Build Feature × Platform Matrix -->
75
+ <block type="task" id="B4" action="compute" status="pending" desc="Build Feature×Platform matrix index">
76
+ <field name="input" value="${feature_registry.features}">${techs_manifest.platforms}</field>
77
+ <field name="logic">
78
+ For each feature in feature_registry.features:
79
+ For each platform in techs_manifest.platforms:
80
+ - feature_id: feature.feature_id (or "-" for legacy)
81
+ - feature_name: feature.feature_name (or feature.module_name for legacy)
82
+ - platform: platform.friendly_name
83
+ - platform_id: platform.platform_id
84
+ - skill: map platform_id prefix → speccrew-sd-{type}
85
+ (web-* → frontend, backend-* → backend, mobile-* → mobile, desktop-* → desktop)
86
+ - design_directory: {platform_id}/{feature_id}-{feature_name}-design.md (new)
87
+ or {platform_id}/{module_name}-design.md (legacy)
88
+ - status: "pending"
89
+ </field>
90
+ <field name="output" var="platform_design_index"/>
91
+ </block>
92
+
93
+ <!-- Step 6: Check if Feature Summary needed -->
94
+ <block type="gateway" id="G2" mode="exclusive" desc="Feature count check for optional summary">
95
+ <branch test="${feature_registry.features.length} > 5" name="Large Feature Set">
96
+ <block type="event" id="E3" action="log" level="info" desc="Large feature set">
97
+ <field name="message">Feature count > 5, including Feature Summary section</field>
98
+ </block>
99
+ <field name="include_summary" var="include_feature_summary" value="true"/>
100
+ </branch>
101
+ <branch default="true" name="Small Feature Set">
102
+ <block type="event" id="E4" action="log" level="info" desc="Small feature set">
103
+ <field name="message">Feature count <= 5, skipping Feature Summary section</field>
104
+ </block>
105
+ <field name="include_summary" var="include_feature_summary" value="false"/>
106
+ </branch>
107
+ </block>
108
+
109
+ <!-- Step 7: Generate DESIGN-OVERVIEW.md -->
110
+ <block type="task" id="B5" action="write-file" status="pending" desc="Generate DESIGN-OVERVIEW.md with all sections">
111
+ <field name="path">${output_path}</field>
112
+ <field name="encoding">utf8</field>
113
+ <field name="content">
114
+ Section 1: Design Scope (iteration, platforms, features count, Feature List table)
115
+ Section 2: Technology Decisions (from framework_evaluation)
116
+ Section 3: Platform Design Index (from platform_design_index matrix)
117
+ Section 4: Feature Summary (ONLY if include_feature_summary == true)
118
+ - 4.1 Feature by Module
119
+ - 4.2 Feature Type Distribution
120
+ Section 5: Cross-Platform Concerns
121
+ Section 6: Design Constraints
122
+ </field>
123
+ </block>
124
+
125
+ <!-- Step 8: Validate Output -->
126
+ <block type="checkpoint" id="CP1" name="design_overview_validation" desc="Validate DESIGN-OVERVIEW.md completeness">
127
+ <field name="conditions">
128
+ file_exists: ${output_path} exists,
129
+ has_design_scope: contains "## 1. Design Scope",
130
+ has_tech_decisions: contains "## 2. Technology Decisions",
131
+ has_platform_index: contains "## 3. Platform Design Index",
132
+ matrix_complete: index row count == feature_count × platform_count,
133
+ all_pending: all status entries are "pending"
134
+ </field>
135
+ </block>
136
+
137
+ <!-- Step 9: Output Task Completion Report -->
138
+ <block type="event" id="E5" action="log" level="info" desc="Output completion report">
139
+ <field name="message">--- TASK COMPLETION REPORT ---
140
+ Task: Design Overview Generation
141
+ Status: SUCCESS
142
+ Output: ${output_path}
143
+ Features: ${feature_registry.features.length}
144
+ Platforms: ${techs_manifest.platforms.length}
145
+ Matrix Entries: ${feature_registry.features.length * techs_manifest.platforms.length}
146
+ --- END REPORT ---</field>
147
+ </block>
148
+
149
+ </sequence>
150
+
151
+ <!-- ============================================================
152
+ Output Results
153
+ ============================================================ -->
154
+ <block type="output" id="O1" desc="Workflow output results">
155
+ <field name="design_overview_path" value="${output_path}" type="string" desc="Path to generated DESIGN-OVERVIEW.md"/>
156
+ <field name="feature_count" from="${feature_registry.features.length}" type="number" desc="Number of features in the matrix"/>
157
+ <field name="platform_count" from="${techs_manifest.platforms.length}" type="number" desc="Number of platforms in the matrix"/>
158
+ <field name="matrix_entries" from="${feature_registry.features.length * techs_manifest.platforms.length}" type="number" desc="Total Feature×Platform combinations"/>
159
+ </block>
160
+
161
+ </workflow>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "speccrew",
3
- "version": "0.7.54",
3
+ "version": "0.7.55",
4
4
  "description": "Spec-Driven Development toolkit for AI-powered IDEs",
5
5
  "author": "charlesmu99",
6
6
  "repository": {