speccrew 0.6.43 → 0.6.44

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.
Files changed (13) hide show
  1. package/.speccrew/skills/speccrew-knowledge-bizs-api-analyze-xml/SKILL.md +495 -477
  2. package/.speccrew/skills/speccrew-knowledge-bizs-api-graph-xml/SKILL.md +281 -197
  3. package/.speccrew/skills/speccrew-knowledge-bizs-identify-entries-xml/SKILL.md +134 -144
  4. package/.speccrew/skills/speccrew-knowledge-bizs-ui-analyze-xml/SKILL.md +316 -377
  5. package/.speccrew/skills/speccrew-knowledge-bizs-ui-graph-xml/SKILL.md +233 -131
  6. package/.speccrew/skills/speccrew-knowledge-bizs-ui-style-extract-xml/SKILL.md +221 -209
  7. package/.speccrew/skills/speccrew-knowledge-module-summarize-xml/SKILL.md +291 -255
  8. package/.speccrew/skills/speccrew-knowledge-system-summarize-xml/SKILL.md +355 -281
  9. package/.speccrew/skills/speccrew-knowledge-techs-generate-conventions-xml/SKILL.md +722 -627
  10. package/.speccrew/skills/speccrew-knowledge-techs-generate-xml/SKILL.md +195 -117
  11. package/.speccrew/skills/speccrew-knowledge-techs-index-xml/SKILL.md +151 -99
  12. package/.speccrew/skills/speccrew-knowledge-techs-init-xml/SKILL.md +201 -99
  13. package/package.json +1 -1
package/.speccrew/skills/speccrew-knowledge-bizs-api-analyze-xml/SKILL.md CHANGED
@@ -21,25 +21,25 @@ Analyze one specific API controller from source code, extract all business featu
21
21
 
22
22
  | Variable | Type | Description | Example |
23
23
  |----------|------|-------------|---------|
24
- | `{{feature}}` | object | Complete feature object from features.json | - |
25
- | `{{fileName}}` | string | Controller file name | `"UserController"`, `"OrderController"` |
26
- | `{{sourcePath}}` | string | Relative path to source file | `"yudao-module-system/yudao-module-system-biz/src/main/java/cn/iocoder/yudao/module/system/controller/admin/user/UserController.java"` |
27
- | `{{documentPath}}` | string | Target path for generated document | `"speccrew-workspace/knowledges/bizs/admin-api/system/user/UserController.md"` |
28
- | `{{module}}` | string | Business module name (from feature.module) | `"system"`, `"trade"`, `"_root"` |
29
- | `{{analyzed}}` | boolean | Analysis status flag | `true` / `false` |
30
- | `{{platform_type}}` | string | Platform type | `"admin-api"`, `"app-api"` |
31
- | `{{platform_subtype}}` | string | Platform subtype | `"spring-boot"`, `"java"` |
32
- | `{{tech_stack}}` | array | Platform tech stack | `["java", "spring-boot", "mybatis-plus"]` |
33
- | `{{completed_dir}}` | string | Marker files output directory | `"speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed"` |
34
- | `{{sourceFile}}` | string | Source features JSON file name | `"features-admin-api.json"` |
35
- | `{{language}}` | string | Target language for content | `"zh"`, `"en"` |
24
+ | `${feature}` | object | Complete feature object from features.json | - |
25
+ | `${fileName}` | string | Controller file name | `"UserController"`, `"OrderController"` |
26
+ | `${sourcePath}` | string | Relative path to source file | `"yudao-module-system/yudao-module-system-biz/src/main/java/cn/iocoder/yudao/module/system/controller/admin/user/UserController.java"` |
27
+ | `${documentPath}` | string | Target path for generated document | `"speccrew-workspace/knowledges/bizs/admin-api/system/user/UserController.md"` |
28
+ | `${module}` | string | Business module name (from feature.module) | `"system"`, `"trade"`, `"_root"` |
29
+ | `${analyzed}` | boolean | Analysis status flag | `true` / `false` |
30
+ | `${platform_type}` | string | Platform type | `"admin-api"`, `"app-api"` |
31
+ | `${platform_subtype}` | string | Platform subtype | `"spring-boot"`, `"java"` |
32
+ | `${tech_stack}` | array | Platform tech stack | `["java", "spring-boot", "mybatis-plus"]` |
33
+ | `${completed_dir}` | string | Marker files output directory | `"speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/completed"` |
34
+ | `${sourceFile}` | string | Source features JSON file name | `"features-admin-api.json"` |
35
+ | `${language}` | string | Target language for content | `"zh"`, `"en"` |
36
36
 
37
37
  ## Language Adaptation
38
38
 
39
- **CRITICAL**: Generate all content in the language specified by the `{{language}}` parameter.
39
+ **CRITICAL**: Generate all content in the language specified by the `${language}` parameter.
40
40
 
41
- - `{{language}} == "zh"` → Generate all content in 中文
42
- - `{{language}} == "en"` → Generate all content in English
41
+ - `${language} == "zh"` → Generate all content in 中文
42
+ - `${language} == "en"` → Generate all content in English
43
43
  - Other languages → Use the specified language
44
44
 
45
45
  **All output content (feature names, descriptions, business rules) must be in the target language only.**
@@ -48,10 +48,10 @@ Analyze one specific API controller from source code, extract all business featu
48
48
 
49
49
  | Variable | Type | Description |
50
50
  |----------|------|-------------|
51
- | `{{status}}` | string | Analysis status: `"success"`, `"partial"`, or `"failed"` |
52
- | `{{feature_name}}` | string | Name of the analyzed controller |
53
- | `{{generated_file}}` | string | Path to the generated documentation file |
54
- | `{{message}}` | string | Summary message for status update |
51
+ | `${status}` | string | Analysis status: `"success"`, `"partial"`, or `"failed"` |
52
+ | `${feature_name}` | string | Name of the analyzed controller |
53
+ | `${generated_file}` | string | Path to the generated documentation file |
54
+ | `${message}` | string | Summary message for status update |
55
55
 
56
56
  ## Execution Requirements
57
57
 
@@ -63,8 +63,8 @@ This skill operates in **strict sequential execution mode**:
63
63
  ## Output
64
64
 
65
65
  **Generated Files:**
66
- 1. `{{documentPath}}` - Controller documentation file
67
- 2. `{{completed_dir}}/{module}-{subpath}-{fileName}.done.json` - Completion status marker
66
+ 1. `${documentPath}` - Controller documentation file
67
+ 2. `${completed_dir}/{module}-{subpath}-{fileName}.done.json` - Completion status marker
68
68
 
69
69
  **Graph Data Generation:**
70
70
  Graph data (nodes, edges) construction is handled by `speccrew-knowledge-bizs-api-graph-xml` Skill.
@@ -95,63 +95,64 @@ The return value is used by dispatch to update the feature status in `features-{
95
95
 
96
96
  Before executing the workflow, verify the following inputs:
97
97
 
98
- - Controller: `{{fileName}}` (`{{sourcePath}}`)
99
- - Target: `{{documentPath}}`
100
- - Language: `{{language}}`
101
- - Module: `{{module}}`
102
- - Platform: `{{platform_type}}`/`{{platform_subtype}}`
103
- - Completed Dir: `{{completed_dir}}`
104
- - Source File: `{{sourceFile}}`
98
+ - Controller: `${fileName}` (`${sourcePath}`)
99
+ - Target: `${documentPath}`
100
+ - Language: `${language}`
101
+ - Module: `${module}`
102
+ - Platform: `${platform_type}`/`${platform_subtype}`
103
+ - Completed Dir: `${completed_dir}`
104
+ - Source File: `${sourceFile}`
105
105
 
106
106
  ## Workflow
107
107
 
108
108
  > **REQUIRED**: Before executing this workflow, read the XML workflow specification: `docs/rules/xml-workflow-spec.md`
109
109
 
110
- ```xml
111
- <workflow name="api-controller-analysis" version="1.0">
110
+ <workflow id="api-controller-analysis" status="pending" version="1.0" desc="API controller analysis workflow">
112
111
 
113
112
  <!-- ==================== INPUT PARAMETERS ==================== -->
114
- <input name="feature" type="object" required="true" description="Complete feature object from features.json"/>
115
- <input name="fileName" type="string" required="true" description="Controller file name"/>
116
- <input name="sourcePath" type="string" required="true" description="Relative path to source file"/>
117
- <input name="documentPath" type="string" required="true" description="Target path for generated document"/>
118
- <input name="module" type="string" required="true" description="Business module name"/>
119
- <input name="analyzed" type="boolean" required="true" description="Analysis status flag"/>
120
- <input name="platform_type" type="string" required="true" description="Platform type: admin-api, app-api"/>
121
- <input name="platform_subtype" type="string" required="true" description="Platform subtype: spring-boot, java"/>
122
- <input name="tech_stack" type="array" required="true" description="Platform tech stack"/>
123
- <input name="completed_dir" type="string" required="true" description="Marker files output directory"/>
124
- <input name="sourceFile" type="string" required="true" description="Source features JSON file name"/>
125
- <input name="language" type="string" required="true" description="Target language for content"/>
113
+ <block type="input" id="I1" desc="API controller analysis input parameters">
114
+ <field name="feature" required="true" type="object" desc="Complete feature object from features.json"/>
115
+ <field name="fileName" required="true" type="string" desc="Controller file name"/>
116
+ <field name="sourcePath" required="true" type="string" desc="Relative path to source file"/>
117
+ <field name="documentPath" required="true" type="string" desc="Target path for generated document"/>
118
+ <field name="module" required="true" type="string" desc="Business module name"/>
119
+ <field name="analyzed" required="true" type="boolean" desc="Analysis status flag"/>
120
+ <field name="platform_type" required="true" type="string" desc="Platform type: admin-api, app-api"/>
121
+ <field name="platform_subtype" required="true" type="string" desc="Platform subtype: spring-boot, java"/>
122
+ <field name="tech_stack" required="true" type="array" desc="Platform tech stack"/>
123
+ <field name="completed_dir" required="true" type="string" desc="Marker files output directory"/>
124
+ <field name="sourceFile" required="true" type="string" desc="Source features JSON file name"/>
125
+ <field name="language" required="true" type="string" desc="Target language for content"/>
126
+ </block>
126
127
 
127
128
  <!-- ==================== CONSTRAINT RULES ==================== -->
128
- <rule level="forbidden" id="no-create-file-for-docs">
129
- NEVER use create_file to rewrite entire document. Documents MUST be created by copying template then filling with search_replace.
130
- </rule>
131
- <rule level="forbidden" id="no-file-deletion">
132
- NEVER delete generated files. If a file is malformed, fix it with search_replace.
133
- </rule>
134
- <rule level="forbidden" id="no-full-rewrite">
135
- NEVER rewrite entire document. Always use targeted search_replace on specific sections.
136
- </rule>
137
- <rule level="mandatory" id="template-first">
138
- Template copying (Step 5a) MUST execute before section filling (Step 5b).
139
- </rule>
140
- <rule level="mandatory" id="write-both-markers">
141
- MUST write both .done.json and .graph.json marker files in Step 7.
142
- </rule>
143
- <rule level="mandatory" id="marker-naming">
144
- Marker file names MUST follow pattern: {module}-{subpath}-{fileName}.done.json
145
- </rule>
146
- <rule level="mandatory" id="no-extension-in-filename">
147
- fileName in .done.json MUST NOT include file extension.
148
- </rule>
149
- <rule level="mandatory" id="relative-paths-only">
150
- ALL paths in JSON content MUST be relative, NEVER absolute paths.
151
- </rule>
152
- <rule level="mandatory" id="language-compliance">
153
- ALL content MUST be generated in the language specified by {{language}} parameter.
154
- </rule>
129
+ <block type="rule" id="R-FORB1" level="forbidden" desc="Document creation constraint">
130
+ <field name="text">NEVER use create_file to rewrite entire document. Documents MUST be created by copying template then filling with search_replace.</field>
131
+ </block>
132
+ <block type="rule" id="R-FORB2" level="forbidden" desc="File deletion constraint">
133
+ <field name="text">NEVER delete generated files. If a file is malformed, fix it with search_replace.</field>
134
+ </block>
135
+ <block type="rule" id="R-FORB3" level="forbidden" desc="Full rewrite constraint">
136
+ <field name="text">NEVER rewrite entire document. Always use targeted search_replace on specific sections.</field>
137
+ </block>
138
+ <block type="rule" id="R-MAND1" level="mandatory" desc="Template-first constraint">
139
+ <field name="text">Template copying (Step 5a) MUST execute before section filling (Step 5b).</field>
140
+ </block>
141
+ <block type="rule" id="R-MAND2" level="mandatory" desc="Marker files constraint">
142
+ <field name="text">MUST write both .done.json and .graph.json marker files in Step 7.</field>
143
+ </block>
144
+ <block type="rule" id="R-MAND3" level="mandatory" desc="Marker naming constraint">
145
+ <field name="text">Marker file names MUST follow pattern: {module}-{subpath}-{fileName}.done.json</field>
146
+ </block>
147
+ <block type="rule" id="R-MAND4" level="mandatory" desc="No extension in filename">
148
+ <field name="text">fileName in .done.json MUST NOT include file extension.</field>
149
+ </block>
150
+ <block type="rule" id="R-MAND5" level="mandatory" desc="Relative paths constraint">
151
+ <field name="text">ALL paths in JSON content MUST be relative, NEVER absolute paths.</field>
152
+ </block>
153
+ <block type="rule" id="R-MAND6" level="mandatory" desc="Language compliance">
154
+ <field name="text">ALL content MUST be generated in the language specified by ${language} parameter.</field>
155
+ </block>
155
156
 
156
157
  <!-- ==================== GLOBAL CONTINUOUS EXECUTION RULES ==================== -->
157
158
  <block type="rule" id="GLOBAL-R1" level="forbidden" desc="Continuous execution constraints — NEVER violate">
@@ -164,440 +165,457 @@ Before executing the workflow, verify the following inputs:
164
165
  </block>
165
166
 
166
167
  <!-- ==================== STEP 0: CHECK ANALYSIS STATUS ==================== -->
167
- <gateway name="check-analyzed-status" mode="exclusive">
168
- <branch condition="{{analyzed}} == true">
169
- <event action="log" level="info" message="Step 0 Status: SKIPPED (already analyzed)"/>
170
- <output name="status" value="skipped"/>
171
- <output name="message" value="Controller already analyzed, skipping"/>
172
- <checkpoint name="skip-complete" verify="true"/>
168
+ <block type="gateway" id="G0" mode="exclusive" desc="Check if already analyzed">
169
+ <branch test="${analyzed} == true" name="Already analyzed">
170
+ <block type="event" id="E1" action="log" level="info" desc="Log skip status">
171
+ <field name="message" value="Step 0 Status: SKIPPED (already analyzed)"/>
172
+ </block>
173
+ <block type="output" id="O-skip" desc="Skip output">
174
+ <field name="status" value="skipped"/>
175
+ <field name="message" value="Controller already analyzed, skipping"/>
176
+ </block>
177
+ <block type="checkpoint" id="CP-skip" name="skip-complete" desc="Skip checkpoint">
178
+ <field name="verify" value="true"/>
179
+ </block>
173
180
  </branch>
174
- <branch condition="{{analyzed}} == false">
175
- <event action="log" level="info" message="Step 0 Status: PROCEEDING (analysis required)"/>
181
+ <branch test="${analyzed} == false" name="Analysis required">
182
+ <block type="event" id="E2" action="log" level="info" desc="Log proceed status">
183
+ <field name="message" value="Step 0 Status: PROCEEDING (analysis required)"/>
184
+ </block>
176
185
  </branch>
177
- </gateway>
186
+ </block>
178
187
 
179
188
  <!-- ==================== STEP 1: READ ANALYSIS TEMPLATE ==================== -->
180
- <task name="step1-read-template" action="run-skill">
181
- <description>Read the appropriate template based on tech stack</description>
182
- <parameter name="tech_stack">{{tech_stack}}</parameter>
183
- <script>
184
- <!-- Template Selection Logic -->
185
- <gateway name="template-selection" mode="exclusive">
186
- <branch condition="{{tech_stack}} contains 'fastapi' OR {{tech_stack}} contains 'python'">
187
- <output name="templateFile" value="../speccrew-knowledge-bizs-api-analyze/templates/FEATURE-DETAIL-TEMPLATE-FASTAPI.md"/>
188
- </branch>
189
- <branch condition="{{tech_stack}} contains 'dotnet' OR {{tech_stack}} contains '.net'">
190
- <output name="templateFile" value="../speccrew-knowledge-bizs-api-analyze/templates/FEATURE-DETAIL-TEMPLATE-NET.md"/>
191
- </branch>
192
- <branch condition="default">
193
- <output name="templateFile" value="../speccrew-knowledge-bizs-api-analyze/templates/FEATURE-DETAIL-TEMPLATE.md"/>
194
- </branch>
195
- </gateway>
196
-
197
- <!-- Read Template Content -->
198
- <task action="read-file" target="{{templateFile}}">
199
- <output name="templateContent" from="file.content"/>
200
- <output name="sectionCount" from="template.sections.count"/>
201
- </task>
202
-
203
- <!-- Validate Template Structure -->
204
- <checkpoint name="template-loaded" verify="{{templateContent}} != null AND {{templateContent}} != ''"/>
205
- <event action="log" level="info" message="Step 1 Status: COMPLETED - Template loaded, {{sectionCount}} sections identified for analysis"/>
206
- </script>
207
- </task>
189
+ <!-- Template Selection Logic -->
190
+ <block type="gateway" id="G1" mode="exclusive" desc="Select template based on tech stack">
191
+ <branch test="${tech_stack} contains 'fastapi' OR ${tech_stack} contains 'python'" name="FastAPI template">
192
+ <block type="output" id="O-tpl1" desc="Set FastAPI template path">
193
+ <field name="templateFile" value="../speccrew-knowledge-bizs-api-analyze/templates/FEATURE-DETAIL-TEMPLATE-FASTAPI.md"/>
194
+ </block>
195
+ </branch>
196
+ <branch test="${tech_stack} contains 'dotnet' OR ${tech_stack} contains '.net'" name=".NET template">
197
+ <block type="output" id="O-tpl2" desc="Set .NET template path">
198
+ <field name="templateFile" value="../speccrew-knowledge-bizs-api-analyze/templates/FEATURE-DETAIL-TEMPLATE-NET.md"/>
199
+ </block>
200
+ </branch>
201
+ <branch default="true" name="Default template">
202
+ <block type="output" id="O-tpl3" desc="Set default template path">
203
+ <field name="templateFile" value="../speccrew-knowledge-bizs-api-analyze/templates/FEATURE-DETAIL-TEMPLATE.md"/>
204
+ </block>
205
+ </branch>
206
+ </block>
207
+
208
+ <!-- Read Template Content -->
209
+ <block type="task" id="B1" action="read-file" desc="Read selected template">
210
+ <field name="target" value="${templateFile}"/>
211
+ <field name="output" var="templateContent" from="file.content"/>
212
+ <field name="output" var="sectionCount" from="template.sections.count"/>
213
+ </block>
214
+
215
+ <!-- Validate Template Structure -->
216
+ <block type="checkpoint" id="CP1" name="template-loaded" desc="Template loaded successfully">
217
+ <field name="verify" value="${templateContent} != null AND ${templateContent} != ''"/>
218
+ </block>
219
+ <block type="event" id="E3" action="log" level="info" desc="Log template status">
220
+ <field name="message" value="Step 1 Status: COMPLETED - Template loaded, ${sectionCount} sections identified for analysis"/>
221
+ </block>
208
222
 
209
223
  <!-- ==================== STEP 2: READ CONTROLLER AND ANALYZE API STRUCTURE ==================== -->
210
- <task name="step2-read-controller" action="run-skill">
211
- <description>Read controller file and analyze API handler structure</description>
212
- <parameter name="sourcePath">{{sourcePath}}</parameter>
213
- <parameter name="tech_stack">{{tech_stack}}</parameter>
214
- <script>
215
- <!-- Read Source File -->
216
- <task action="read-file" target="{{sourcePath}}">
217
- <output name="sourceContent" from="file.content"/>
218
- <output name="lineCount" from="file.lineCount"/>
219
- </task>
220
-
221
- <!-- Analyze API Structure Based on Tech Stack -->
222
- <gateway name="tech-specific-analysis" mode="exclusive">
223
- <branch condition="{{tech_stack}} contains 'java' OR {{tech_stack}} contains 'spring'">
224
- <task action="parse-spring-controller">
225
- <input name="content">{{sourceContent}}</input>
226
- <output name="endpoints" from="parser.endpoints"/>
227
- <output name="endpointCount" from="parser.endpointCount"/>
228
- <output name="services" from="parser.services"/>
229
- <output name="serviceCount" from="parser.serviceCount"/>
230
- </task>
231
- </branch>
232
- <branch condition="{{tech_stack}} contains 'fastapi' OR {{tech_stack}} contains 'python'">
233
- <task action="parse-fastapi-router">
234
- <input name="content">{{sourceContent}}</input>
235
- <output name="endpoints" from="parser.endpoints"/>
236
- <output name="endpointCount" from="parser.endpointCount"/>
237
- <output name="services" from="parser.services"/>
238
- <output name="serviceCount" from="parser.serviceCount"/>
239
- </task>
240
- </branch>
241
- <branch condition="{{tech_stack}} contains 'dotnet' OR {{tech_stack}} contains '.net'">
242
- <task action="parse-dotnet-controller">
243
- <input name="content">{{sourceContent}}</input>
244
- <output name="endpoints" from="parser.endpoints"/>
245
- <output name="endpointCount" from="parser.endpointCount"/>
246
- <output name="services" from="parser.services"/>
247
- <output name="serviceCount" from="parser.serviceCount"/>
248
- </task>
249
- </branch>
250
- <branch condition="default">
251
- <task action="parse-generic-controller">
252
- <input name="content">{{sourceContent}}</input>
253
- <output name="endpoints" from="parser.endpoints"/>
254
- <output name="endpointCount" from="parser.endpointCount"/>
255
- <output name="services" from="parser.services"/>
256
- <output name="serviceCount" from="parser.serviceCount"/>
257
- </task>
258
- </branch>
259
- </gateway>
260
-
261
- <checkpoint name="controller-analyzed" verify="{{sourceContent}} != null"/>
262
- <event action="log" level="info" message="Step 2 Status: COMPLETED - Read {{sourcePath}} ({{lineCount}} lines), Analyzed {{endpointCount}} endpoints, {{serviceCount}} services"/>
263
- </script>
264
- </task>
224
+ <!-- Read Source File -->
225
+ <block type="task" id="B2" action="read-file" desc="Read controller source file">
226
+ <field name="target" value="${sourcePath}"/>
227
+ <field name="output" var="sourceContent" from="file.content"/>
228
+ <field name="output" var="lineCount" from="file.lineCount"/>
229
+ </block>
230
+
231
+ <!-- Analyze API Structure Based on Tech Stack -->
232
+ <block type="gateway" id="G2" mode="exclusive" desc="Tech-specific API analysis">
233
+ <branch test="${tech_stack} contains 'java' OR ${tech_stack} contains 'spring'" name="Spring/Java analysis">
234
+ <block type="task" id="B3" action="parse-spring-controller" desc="Parse Spring controller">
235
+ <field name="content" value="${sourceContent}"/>
236
+ <field name="output" var="endpoints" from="parser.endpoints"/>
237
+ <field name="output" var="endpointCount" from="parser.endpointCount"/>
238
+ <field name="output" var="services" from="parser.services"/>
239
+ <field name="output" var="serviceCount" from="parser.serviceCount"/>
240
+ </block>
241
+ </branch>
242
+ <branch test="${tech_stack} contains 'fastapi' OR ${tech_stack} contains 'python'" name="FastAPI/Python analysis">
243
+ <block type="task" id="B4" action="parse-fastapi-router" desc="Parse FastAPI router">
244
+ <field name="content" value="${sourceContent}"/>
245
+ <field name="output" var="endpoints" from="parser.endpoints"/>
246
+ <field name="output" var="endpointCount" from="parser.endpointCount"/>
247
+ <field name="output" var="services" from="parser.services"/>
248
+ <field name="output" var="serviceCount" from="parser.serviceCount"/>
249
+ </block>
250
+ </branch>
251
+ <branch test="${tech_stack} contains 'dotnet' OR ${tech_stack} contains '.net'" name=".NET analysis">
252
+ <block type="task" id="B5" action="parse-dotnet-controller" desc="Parse .NET controller">
253
+ <field name="content" value="${sourceContent}"/>
254
+ <field name="output" var="endpoints" from="parser.endpoints"/>
255
+ <field name="output" var="endpointCount" from="parser.endpointCount"/>
256
+ <field name="output" var="services" from="parser.services"/>
257
+ <field name="output" var="serviceCount" from="parser.serviceCount"/>
258
+ </block>
259
+ </branch>
260
+ <branch default="true" name="Generic analysis">
261
+ <block type="task" id="B6" action="parse-generic-controller" desc="Parse generic controller">
262
+ <field name="content" value="${sourceContent}"/>
263
+ <field name="output" var="endpoints" from="parser.endpoints"/>
264
+ <field name="output" var="endpointCount" from="parser.endpointCount"/>
265
+ <field name="output" var="services" from="parser.services"/>
266
+ <field name="output" var="serviceCount" from="parser.serviceCount"/>
267
+ </block>
268
+ </branch>
269
+ </block>
270
+
271
+ <block type="checkpoint" id="CP2" name="controller-analyzed" desc="Controller analyzed successfully">
272
+ <field name="verify" value="${sourceContent} != null"/>
273
+ </block>
274
+ <block type="event" id="E4" action="log" level="info" desc="Log controller status">
275
+ <field name="message" value="Step 2 Status: COMPLETED - Read ${sourcePath} (${lineCount} lines), Analyzed ${endpointCount} endpoints, ${serviceCount} services"/>
276
+ </block>
265
277
 
266
278
  <!-- ==================== STEP 3: EXTRACT API FEATURES ==================== -->
267
- <task name="step3-extract-features" action="run-skill">
268
- <description>Extract API features, business flows, and data structures from controller analysis</description>
269
- <parameter name="endpoints">{{endpoints}}</parameter>
270
- <parameter name="sourcePath">{{sourcePath}}</parameter>
271
- <parameter name="language">{{language}}</parameter>
272
- <script>
273
- <!-- Read Mermaid Rules -->
274
- <task action="read-file" target="speccrew-workspace/docs/rules/mermaid-rule.md">
275
- <output name="mermaidRules" from="file.content"/>
276
- </task>
277
-
278
- <!-- Extract Each API Endpoint Details -->
279
- <loop name="extract-endpoint-details" over="{{endpoints}}" as="endpoint">
280
- <task action="analyze-endpoint">
281
- <input name="endpoint">{{endpoint}}</input>
282
- <input name="tech_stack">{{tech_stack}}</input>
283
- <output name="requestDTO" from="analysis.requestDTO"/>
284
- <output name="responseDTO" from="analysis.responseDTO"/>
285
- <output name="businessFlow" from="analysis.flow"/>
286
- <output name="validationRules" from="analysis.validations"/>
287
- </task>
288
- </loop>
289
-
290
- <!-- Trace Backend Call Chain -->
291
- <task action="trace-call-chain">
292
- <input name="endpoints">{{endpoints}}</input>
293
- <input name="services">{{services}}</input>
294
- <input name="tech_stack">{{tech_stack}}</input>
295
- <output name="callChains" from="trace.chains"/>
296
- <output name="databaseTables" from="trace.tables"/>
297
- <output name="transactionBoundaries" from="trace.transactions"/>
298
- <output name="crossModuleCalls" from="trace.crossModules"/>
299
- </task>
300
-
301
- <!-- Generate Mermaid Flowcharts -->
302
- <task action="generate-flowcharts">
303
- <input name="endpoints">{{endpoints}}</input>
304
- <input name="callChains">{{callChains}}</input>
305
- <input name="mermaidRules">{{mermaidRules}}</input>
306
- <output name="flowcharts" from="generation.flowcharts"/>
307
- <output name="flowCount" from="generation.count"/>
308
- </task>
309
-
310
- <checkpoint name="features-extracted" verify="{{endpointCount}} &gt; 0"/>
311
- <event action="log" level="info" message="Step 3 Status: COMPLETED - Extracted {{endpointCount}} API endpoints, {{flowCount}} business flows"/>
312
- </script>
313
- </task>
279
+ <!-- Read Mermaid Rules -->
280
+ <block type="task" id="B7" action="read-file" desc="Read Mermaid rules">
281
+ <field name="target" value="speccrew-workspace/docs/rules/mermaid-rule.md"/>
282
+ <field name="output" var="mermaidRules" from="file.content"/>
283
+ </block>
284
+
285
+ <!-- Extract Each API Endpoint Details -->
286
+ <block type="loop" id="L1" over="${endpoints}" as="endpoint" desc="Extract endpoint details">
287
+ <block type="task" id="B8" action="analyze-endpoint" desc="Analyze single endpoint">
288
+ <field name="endpoint" value="${endpoint}"/>
289
+ <field name="tech_stack" value="${tech_stack}"/>
290
+ <field name="output" var="requestDTO" from="analysis.requestDTO"/>
291
+ <field name="output" var="responseDTO" from="analysis.responseDTO"/>
292
+ <field name="output" var="businessFlow" from="analysis.flow"/>
293
+ <field name="output" var="validationRules" from="analysis.validations"/>
294
+ </block>
295
+ </block>
296
+
297
+ <!-- Trace Backend Call Chain -->
298
+ <block type="task" id="B9" action="trace-call-chain" desc="Trace call chains">
299
+ <field name="endpoints" value="${endpoints}"/>
300
+ <field name="services" value="${services}"/>
301
+ <field name="tech_stack" value="${tech_stack}"/>
302
+ <field name="output" var="callChains" from="trace.chains"/>
303
+ <field name="output" var="databaseTables" from="trace.tables"/>
304
+ <field name="output" var="transactionBoundaries" from="trace.transactions"/>
305
+ <field name="output" var="crossModuleCalls" from="trace.crossModules"/>
306
+ </block>
307
+
308
+ <!-- Generate Mermaid Flowcharts -->
309
+ <block type="task" id="B10" action="generate-flowcharts" desc="Generate Mermaid diagrams">
310
+ <field name="endpoints" value="${endpoints}"/>
311
+ <field name="callChains" value="${callChains}"/>
312
+ <field name="mermaidRules" value="${mermaidRules}"/>
313
+ <field name="output" var="flowcharts" from="generation.flowcharts"/>
314
+ <field name="output" var="flowCount" from="generation.count"/>
315
+ </block>
316
+
317
+ <block type="checkpoint" id="CP3" name="features-extracted" desc="Features extracted successfully">
318
+ <field name="verify" value="${endpointCount} > 0"/>
319
+ </block>
320
+ <block type="event" id="E5" action="log" level="info" desc="Log extraction status">
321
+ <field name="message" value="Step 3 Status: COMPLETED - Extracted ${endpointCount} API endpoints, ${flowCount} business flows"/>
322
+ </block>
314
323
 
315
324
  <!-- ==================== STEP 4: FIND API CONSUMERS ==================== -->
316
- <task name="step4-find-consumers" action="run-skill">
317
- <description>Search frontend page files to find which pages call the APIs in this controller</description>
318
- <parameter name="endpoints">{{endpoints}}</parameter>
319
- <parameter name="fileName">{{fileName}}</parameter>
320
- <script>
321
- <!-- Search for API Client Calls -->
322
- <task action="grep-search">
323
- <input name="pattern">{{fileName}}</input>
324
- <input name="glob">*.{vue,tsx,jsx,ts,js}</input>
325
- <output name="clientMatches" from="search.results"/>
326
- </task>
327
-
328
- <!-- Search for HTTP Requests to Controller Path -->
329
- <loop name="search-endpoint-paths" over="{{endpoints}}" as="endpoint">
330
- <task action="grep-search">
331
- <input name="pattern">{{endpoint.path}}</input>
332
- <input name="glob">*.{vue,tsx,jsx,ts,js}</input>
333
- <output name="pathMatches" from="search.results" accumulate="true"/>
334
- </task>
335
- </loop>
336
-
337
- <!-- Compile Consumer Pages -->
338
- <task action="compile-consumers">
339
- <input name="clientMatches">{{clientMatches}}</input>
340
- <input name="pathMatches">{{pathMatches}}</input>
341
- <output name="consumerPages" from="compilation.pages"/>
342
- <output name="consumerCount" from="compilation.count"/>
343
- </task>
344
-
345
- <event action="log" level="info" message="Step 4 Status: COMPLETED - Found {{consumerCount}} API consumers"/>
346
- </script>
347
- </task>
325
+ <!-- Search for API Client Calls -->
326
+ <block type="task" id="B11" action="grep-search" desc="Search for API client calls">
327
+ <field name="pattern" value="${fileName}"/>
328
+ <field name="glob" value="*.{vue,tsx,jsx,ts,js}"/>
329
+ <field name="output" var="clientMatches" from="search.results"/>
330
+ </block>
331
+
332
+ <!-- Search for HTTP Requests to Controller Path -->
333
+ <block type="loop" id="L2" over="${endpoints}" as="endpoint" desc="Search endpoint paths">
334
+ <block type="task" id="B12" action="grep-search" desc="Search for endpoint path">
335
+ <field name="pattern" value="${endpoint.path}"/>
336
+ <field name="glob" value="*.{vue,tsx,jsx,ts,js}"/>
337
+ <field name="output" var="pathMatches" from="search.results" accumulate="true"/>
338
+ </block>
339
+ </block>
340
+
341
+ <!-- Compile Consumer Pages -->
342
+ <block type="task" id="B13" action="compile-consumers" desc="Compile consumer pages">
343
+ <field name="clientMatches" value="${clientMatches}"/>
344
+ <field name="pathMatches" value="${pathMatches}"/>
345
+ <field name="output" var="consumerPages" from="compilation.pages"/>
346
+ <field name="output" var="consumerCount" from="compilation.count"/>
347
+ </block>
348
+
349
+ <block type="event" id="E6" action="log" level="info" desc="Log consumer status">
350
+ <field name="message" value="Step 4 Status: COMPLETED - Found ${consumerCount} API consumers"/>
351
+ </block>
348
352
 
349
353
  <!-- ==================== STEP 5A: COPY TEMPLATE TO DOCUMENT PATH ==================== -->
350
- <task name="step5a-copy-template" action="run-skill">
351
- <description>Copy the appropriate template to the target document path and replace top-level placeholders</description>
352
- <parameter name="templateContent">{{templateContent}}</parameter>
353
- <parameter name="documentPath">{{documentPath}}</parameter>
354
- <parameter name="fileName">{{fileName}}</parameter>
355
- <parameter name="sourcePath">{{sourcePath}}</parameter>
356
- <parameter name="module">{{module}}</parameter>
357
- <script>
358
- <!-- Replace Top-Level Placeholders -->
359
- <task action="replace-placeholders">
360
- <input name="template">{{templateContent}}</input>
361
- <replacements>
362
- <replacement from="{Controller}" to="{{fileName}}"/>
363
- <replacement from="{sourcePath}" to="{{sourcePath}}"/>
364
- <replacement from="{documentPath}" to="{{documentPath}}"/>
365
- <replacement from="{module}" to="{{module}}"/>
366
- <replacement from="[Feature Name]" to="{{fileName}}"/>
367
- </replacements>
368
- <output name="documentSkeleton" from="result.content"/>
369
- </task>
370
-
371
- <!-- Create Document File -->
372
- <task action="create-file" target="{{documentPath}}">
373
- <content>{{documentSkeleton}}</content>
374
- </task>
375
-
376
- <!-- Verify Document Skeleton -->
377
- <task action="verify-structure">
378
- <input name="documentPath">{{documentPath}}</input>
379
- <output name="structureValid" from="verification.valid"/>
380
- </task>
381
-
382
- <checkpoint name="template-copied" verify="file.exists({{documentPath}}) AND {{structureValid}}"/>
383
- <event action="log" level="info" message="Step 5a Status: COMPLETED - Template copied to {{documentPath}}, ready for section filling"/>
384
- </script>
385
- </task>
354
+ <!-- Replace Top-Level Placeholders -->
355
+ <block type="task" id="B14" action="replace-placeholders" desc="Replace template placeholders">
356
+ <field name="template" value="${templateContent}"/>
357
+ <field name="replacements">
358
+ <replacement from="{Controller}" to="${fileName}"/>
359
+ <replacement from="{sourcePath}" to="${sourcePath}"/>
360
+ <replacement from="{documentPath}" to="${documentPath}"/>
361
+ <replacement from="{module}" to="${module}"/>
362
+ <replacement from="[Feature Name]" to="${fileName}"/>
363
+ </field>
364
+ <field name="output" var="documentSkeleton" from="result.content"/>
365
+ </block>
366
+
367
+ <!-- Create Document File -->
368
+ <block type="task" id="B15" action="create-file" desc="Create document file">
369
+ <field name="target" value="${documentPath}"/>
370
+ <field name="content" value="${documentSkeleton}"/>
371
+ </block>
372
+
373
+ <!-- Verify Document Skeleton -->
374
+ <block type="task" id="B16" action="verify-structure" desc="Verify document structure">
375
+ <field name="documentPath" value="${documentPath}"/>
376
+ <field name="output" var="structureValid" from="verification.valid"/>
377
+ </block>
378
+
379
+ <block type="checkpoint" id="CP4" name="template-copied" desc="Template copied successfully">
380
+ <field name="verify" value="file.exists(${documentPath}) AND ${structureValid}"/>
381
+ </block>
382
+ <block type="event" id="E7" action="log" level="info" desc="Log template copy status">
383
+ <field name="message" value="Step 5a Status: COMPLETED - Template copied to ${documentPath}, ready for section filling"/>
384
+ </block>
386
385
 
387
386
  <!-- ==================== STEP 5B: FILL EACH SECTION USING SEARCH_REPLACE ==================== -->
388
- <task name="step5b-fill-sections" action="run-skill">
389
- <description>Fill each section of the document with actual data extracted from source code analysis</description>
390
- <parameter name="documentPath">{{documentPath}}</parameter>
391
- <parameter name="endpoints">{{endpoints}}</parameter>
392
- <parameter name="consumerPages">{{consumerPages}}</parameter>
393
- <parameter name="callChains">{{callChains}}</parameter>
394
- <parameter name="flowcharts">{{flowcharts}}</parameter>
395
- <parameter name="databaseTables">{{databaseTables}}</parameter>
396
- <parameter name="language">{{language}}</parameter>
397
- <script>
398
- <!-- Calculate Dynamic Path Prefix -->
399
- <task action="calculate-path-prefix">
400
- <input name="documentPath">{{documentPath}}</input>
401
- <output name="pathPrefix" from="calculation.prefix"/>
402
- </task>
403
-
404
- <!-- Section 1: Content Overview -->
405
- <task action="search_replace" target="{{documentPath}}">
406
- <anchor><!-- AI-TAG: OVERVIEW --></anchor>
407
- <replace>{{overviewContent}}</replace>
408
- </task>
409
-
410
- <!-- Section 2: API Endpoints -->
411
- <task action="search_replace" target="{{documentPath}}">
412
- <anchor><!-- AI-TAG: API_ENDPOINTS --></anchor>
413
- <replace>{{endpointDefinitions}}</replace>
414
- </task>
415
-
416
- <!-- Section 3: Data Fields -->
417
- <task action="search_replace" target="{{documentPath}}">
418
- <anchor><!-- AI-TAG: DATA_DEFINITION --></anchor>
419
- <replace>{{dataFieldDefinitions}}</replace>
420
- </task>
421
-
422
- <!-- Section 4: References -->
423
- <task action="search_replace" target="{{documentPath}}">
424
- <anchor><!-- AI-TAG: REFERENCES --></anchor>
425
- <replace>{{referencesContent}}</replace>
426
- </task>
427
-
428
- <!-- Section 5: Business Rules -->
429
- <task action="search_replace" target="{{documentPath}}">
430
- <anchor><!-- AI-TAG: BUSINESS_RULES --></anchor>
431
- <replace>{{businessRulesContent}}</replace>
432
- </task>
433
-
434
- <!-- Section 6: Dependencies -->
435
- <task action="search_replace" target="{{documentPath}}">
436
- <anchor><!-- AI-TAG: DEPENDENCIES --></anchor>
437
- <replace>{{dependenciesContent}}</replace>
438
- </task>
439
-
440
- <!-- Section 7: Performance -->
441
- <task action="search_replace" target="{{documentPath}}">
442
- <anchor><!-- AI-TAG: PERFORMANCE --></anchor>
443
- <replace>{{performanceContent}}</replace>
444
- </task>
445
-
446
- <!-- Section 8: Troubleshooting -->
447
- <task action="search_replace" target="{{documentPath}}">
448
- <anchor><!-- AI-TAG: TROUBLESHOOTING --></anchor>
449
- <replace>{{troubleshootingContent}}</replace>
450
- </task>
451
-
452
- <!-- Section 9: Notes -->
453
- <task action="search_replace" target="{{documentPath}}">
454
- <anchor><!-- AI-TAG: ADDITIONAL_NOTES --></anchor>
455
- <replace>{{additionalNotes}}</replace>
456
- </task>
457
-
458
- <!-- Section 10: Appendix -->
459
- <task action="search_replace" target="{{documentPath}}">
460
- <search>## 10. Appendix.*</search>
461
- <replace>## 10. Appendix
462
-
463
- {{appendixContent}}</replace>
464
- </task>
465
-
466
- <!-- Get File Size -->
467
- <task action="get-file-size" target="{{documentPath}}">
468
- <output name="fileSize" from="file.size"/>
469
- </task>
470
-
471
- <checkpoint name="all-sections-filled" verify="all.sections.filled"/>
472
- <event action="log" level="info" message="Step 5b Status: COMPLETED - All sections filled at {{documentPath}} ({{fileSize}} bytes)"/>
473
- </script>
474
- </task>
387
+ <!-- Calculate Dynamic Path Prefix -->
388
+ <block type="task" id="B17" action="calculate-path-prefix" desc="Calculate path prefix">
389
+ <field name="documentPath" value="${documentPath}"/>
390
+ <field name="output" var="pathPrefix" from="calculation.prefix"/>
391
+ </block>
392
+
393
+ <!-- Section 1: Content Overview -->
394
+ <block type="task" id="B18" action="search_replace" desc="Fill overview section">
395
+ <field name="target" value="${documentPath}"/>
396
+ <field name="anchor" value="<!-- AI-TAG: OVERVIEW -->"/>
397
+ <field name="replace" value="${overviewContent}"/>
398
+ </block>
399
+
400
+ <!-- Section 2: API Endpoints -->
401
+ <block type="task" id="B19" action="search_replace" desc="Fill API endpoints section">
402
+ <field name="target" value="${documentPath}"/>
403
+ <field name="anchor" value="<!-- AI-TAG: API_ENDPOINTS -->"/>
404
+ <field name="replace" value="${endpointDefinitions}"/>
405
+ </block>
406
+
407
+ <!-- Section 3: Data Fields -->
408
+ <block type="task" id="B20" action="search_replace" desc="Fill data definition section">
409
+ <field name="target" value="${documentPath}"/>
410
+ <field name="anchor" value="<!-- AI-TAG: DATA_DEFINITION -->"/>
411
+ <field name="replace" value="${dataFieldDefinitions}"/>
412
+ </block>
413
+
414
+ <!-- Section 4: References -->
415
+ <block type="task" id="B21" action="search_replace" desc="Fill references section">
416
+ <field name="target" value="${documentPath}"/>
417
+ <field name="anchor" value="<!-- AI-TAG: REFERENCES -->"/>
418
+ <field name="replace" value="${referencesContent}"/>
419
+ </block>
420
+
421
+ <!-- Section 5: Business Rules -->
422
+ <block type="task" id="B22" action="search_replace" desc="Fill business rules section">
423
+ <field name="target" value="${documentPath}"/>
424
+ <field name="anchor" value="<!-- AI-TAG: BUSINESS_RULES -->"/>
425
+ <field name="replace" value="${businessRulesContent}"/>
426
+ </block>
427
+
428
+ <!-- Section 6: Dependencies -->
429
+ <block type="task" id="B23" action="search_replace" desc="Fill dependencies section">
430
+ <field name="target" value="${documentPath}"/>
431
+ <field name="anchor" value="<!-- AI-TAG: DEPENDENCIES -->"/>
432
+ <field name="replace" value="${dependenciesContent}"/>
433
+ </block>
434
+
435
+ <!-- Section 7: Performance -->
436
+ <block type="task" id="B24" action="search_replace" desc="Fill performance section">
437
+ <field name="target" value="${documentPath}"/>
438
+ <field name="anchor" value="<!-- AI-TAG: PERFORMANCE -->"/>
439
+ <field name="replace" value="${performanceContent}"/>
440
+ </block>
441
+
442
+ <!-- Section 8: Troubleshooting -->
443
+ <block type="task" id="B25" action="search_replace" desc="Fill troubleshooting section">
444
+ <field name="target" value="${documentPath}"/>
445
+ <field name="anchor" value="<!-- AI-TAG: TROUBLESHOOTING -->"/>
446
+ <field name="replace" value="${troubleshootingContent}"/>
447
+ </block>
448
+
449
+ <!-- Section 9: Notes -->
450
+ <block type="task" id="B26" action="search_replace" desc="Fill additional notes section">
451
+ <field name="target" value="${documentPath}"/>
452
+ <field name="anchor" value="<!-- AI-TAG: ADDITIONAL_NOTES -->"/>
453
+ <field name="replace" value="${additionalNotes}"/>
454
+ </block>
455
+
456
+ <!-- Section 10: Appendix -->
457
+ <block type="task" id="B27" action="search_replace" desc="Fill appendix section">
458
+ <field name="target" value="${documentPath}"/>
459
+ <field name="search" value="## 10. Appendix.*"/>
460
+ <field name="replace" value="## 10. Appendix&#10;&#10;${appendixContent}"/>
461
+ </block>
462
+
463
+ <!-- Get File Size -->
464
+ <block type="task" id="B28" action="get-file-size" desc="Get generated file size">
465
+ <field name="target" value="${documentPath}"/>
466
+ <field name="output" var="fileSize" from="file.size"/>
467
+ </block>
468
+
469
+ <block type="checkpoint" id="CP5" name="all-sections-filled" desc="All sections filled">
470
+ <field name="verify" value="all.sections.filled"/>
471
+ </block>
472
+ <block type="event" id="E8" action="log" level="info" desc="Log sections filled status">
473
+ <field name="message" value="Step 5b Status: COMPLETED - All sections filled at ${documentPath} (${fileSize} bytes)"/>
474
+ </block>
475
475
 
476
476
  <!-- ==================== STEP 6: REPORT RESULTS ==================== -->
477
- <task name="step6-report" action="run-skill">
478
- <description>Return analysis result summary to dispatch</description>
479
- <script>
480
- <gateway name="determine-status" mode="exclusive">
481
- <branch condition="{{endpointCount}} == 0">
482
- <output name="status" value="failed"/>
483
- <output name="message" value="No API endpoints found in controller"/>
484
- </branch>
485
- <branch condition="{{errors}} != null AND {{errors.length}} &gt; 0">
486
- <output name="status" value="partial"/>
487
- <output name="message" value="Analysis completed with {{errors.length}} warnings"/>
488
- </branch>
489
- <branch condition="default">
490
- <output name="status" value="success"/>
491
- <output name="message" value="Successfully analyzed {{fileName}} with {{endpointCount}} API endpoints"/>
492
- </branch>
493
- </gateway>
494
-
495
- <output name="feature_name" value="{{fileName}}"/>
496
- <output name="generated_file" value="{{documentPath}}"/>
497
-
498
- <event action="log" level="info" message="Step 6 Status: COMPLETED - Analysis {{status}}: {{message}}"/>
499
- </script>
500
- </task>
477
+ <block type="gateway" id="G3" mode="exclusive" desc="Determine analysis status">
478
+ <branch test="${endpointCount} == 0" name="No endpoints">
479
+ <block type="output" id="O-fail" desc="Failed output">
480
+ <field name="status" value="failed"/>
481
+ <field name="message" value="No API endpoints found in controller"/>
482
+ </block>
483
+ </branch>
484
+ <branch test="${errors} != null AND ${errors.length} > 0" name="Partial success">
485
+ <block type="output" id="O-partial" desc="Partial output">
486
+ <field name="status" value="partial"/>
487
+ <field name="message" value="Analysis completed with ${errors.length} warnings"/>
488
+ </block>
489
+ </branch>
490
+ <branch default="true" name="Success">
491
+ <block type="output" id="O-success" desc="Success output">
492
+ <field name="status" value="success"/>
493
+ <field name="message" value="Successfully analyzed ${fileName} with ${endpointCount} API endpoints"/>
494
+ </block>
495
+ </branch>
496
+ </block>
497
+
498
+ <block type="output" id="O-vals" desc="Feature outputs">
499
+ <field name="feature_name" value="${fileName}"/>
500
+ <field name="generated_file" value="${documentPath}"/>
501
+ </block>
502
+
503
+ <block type="event" id="E9" action="log" level="info" desc="Log report status">
504
+ <field name="message" value="Step 6 Status: COMPLETED - Analysis ${status}: ${message}"/>
505
+ </block>
501
506
 
502
507
  <!-- ==================== STEP 7: WRITE COMPLETION MARKERS ==================== -->
503
- <task name="step7-write-markers" action="run-skill">
504
- <description>Write analysis results to marker files for dispatch batch processing</description>
505
- <parameter name="completed_dir">{{completed_dir}}</parameter>
506
- <parameter name="module">{{module}}</parameter>
507
- <parameter name="sourcePath">{{sourcePath}}</parameter>
508
- <parameter name="fileName">{{fileName}}</parameter>
509
- <parameter name="sourceFile">{{sourceFile}}</parameter>
510
- <parameter name="documentPath">{{documentPath}}</parameter>
511
- <parameter name="status">{{status}}</parameter>
512
- <parameter name="message">{{message}}</parameter>
513
- <script>
514
- <!-- Calculate Subpath from Source Path -->
515
- <task action="calculate-subpath">
516
- <input name="sourcePath">{{sourcePath}}</input>
517
- <output name="subpath" from="calculation.subpath"/>
518
- </task>
519
-
520
- <!-- Generate Marker File Name -->
521
- <task action="generate-marker-name">
522
- <input name="module">{{module}}</input>
523
- <input name="subpath">{{subpath}}</input>
524
- <input name="fileName">{{fileName}}</input>
525
- <output name="markerName" from="generation.name"/>
526
- </task>
527
-
528
- <!-- Pre-write Verification -->
529
- <checkpoint name="pre-write-check" verify="{{fileName}} does-not-contain '.' AND {{sourceFile}} matches 'features-*.json'"/>
530
-
531
- <!-- Write .done.json File -->
532
- <task action="create-file" target="{{completed_dir}}/{{markerName}}.done.json">
533
- <content>{
534
- "fileName": "{{fileName}}",
535
- "sourcePath": "{{sourcePath}}",
536
- "sourceFile": "{{sourceFile}}",
537
- "module": "{{module}}",
538
- "documentPath": "{{documentPath}}",
539
- "status": "{{status}}",
540
- "analysisNotes": "{{message}}"
541
- }</content>
542
- </task>
543
-
544
- <!-- Verify Marker File Written -->
545
- <checkpoint name="marker-written" verify="file.exists({{completed_dir}}/{{markerName}}.done.json)"/>
546
-
547
- <!-- Dispatch to Graph Skill for .graph.json -->
548
- <task name="dispatch-graph-generation" action="dispatch-to-worker">
549
- <skill>speccrew-knowledge-bizs-api-graph-xml</skill>
550
- <parameters>
551
- <parameter name="controllerFile">{{fileName}}</parameter>
552
- <parameter name="sourcePath">{{sourcePath}}</parameter>
553
- <parameter name="endpoints">{{endpoints}}</parameter>
554
- <parameter name="completed_dir">{{completed_dir}}</parameter>
555
- <parameter name="markerName">{{markerName}}</parameter>
556
- </parameters>
557
- </task>
558
-
559
- <event action="log" level="info" message="Step 7 Status: COMPLETED - Marker file written to {{completed_dir}}"/>
560
- </script>
561
- </task>
508
+ <!-- Calculate Subpath from Source Path -->
509
+ <block type="task" id="B29" action="calculate-subpath" desc="Calculate subpath">
510
+ <field name="sourcePath" value="${sourcePath}"/>
511
+ <field name="output" var="subpath" from="calculation.subpath"/>
512
+ </block>
513
+
514
+ <!-- Generate Marker File Name -->
515
+ <block type="task" id="B30" action="generate-marker-name" desc="Generate marker name">
516
+ <field name="module" value="${module}"/>
517
+ <field name="subpath" value="${subpath}"/>
518
+ <field name="fileName" value="${fileName}"/>
519
+ <field name="output" var="markerName" from="generation.name"/>
520
+ </block>
521
+
522
+ <!-- Pre-write Verification -->
523
+ <block type="checkpoint" id="CP6" name="pre-write-check" desc="Pre-write verification">
524
+ <field name="verify" value="${fileName} does-not-contain '.' AND ${sourceFile} matches 'features-*.json'"/>
525
+ </block>
526
+
527
+ <!-- Write .done.json File -->
528
+ <block type="task" id="B31" action="create-file" desc="Write done marker file">
529
+ <field name="target" value="${completed_dir}/${markerName}.done.json"/>
530
+ <field name="content" value="{
531
+ &quot;fileName&quot;: &quot;${fileName}&quot;,
532
+ &quot;sourcePath&quot;: &quot;${sourcePath}&quot;,
533
+ &quot;sourceFile&quot;: &quot;${sourceFile}&quot;,
534
+ &quot;module&quot;: &quot;${module}&quot;,
535
+ &quot;documentPath&quot;: &quot;${documentPath}&quot;,
536
+ &quot;status&quot;: &quot;${status}&quot;,
537
+ &quot;analysisNotes&quot;: &quot;${message}&quot;
538
+ }"/>
539
+ </block>
540
+
541
+ <!-- Verify Marker File Written -->
542
+ <block type="checkpoint" id="CP7" name="marker-written" desc="Marker file written">
543
+ <field name="verify" value="file.exists(${completed_dir}/${markerName}.done.json)"/>
544
+ </block>
545
+
546
+ <!-- Dispatch to Graph Skill for .graph.json -->
547
+ <block type="task" id="B32" action="dispatch-to-worker" desc="Dispatch graph generation">
548
+ <field name="skill">speccrew-knowledge-bizs-api-graph-xml</field>
549
+ <field name="parameters">
550
+ <field name="controllerFile">${fileName}</field>
551
+ <field name="sourcePath">${sourcePath}</field>
552
+ <field name="endpoints">${endpoints}</field>
553
+ <field name="completed_dir">${completed_dir}</field>
554
+ <field name="markerName">${markerName}</field>
555
+ </field>
556
+ </block>
557
+
558
+ <block type="event" id="E10" action="log" level="info" desc="Log marker status">
559
+ <field name="message" value="Step 7 Status: COMPLETED - Marker file written to ${completed_dir}"/>
560
+ </block>
562
561
 
563
562
  <!-- ==================== FINAL OUTPUT ==================== -->
564
- <output name="status" from="step6-report.status"/>
565
- <output name="feature" from="step6-report.feature"/>
566
- <output name="platformType" from="input.platform_type"/>
567
- <output name="module" from="input.module"/>
568
- <output name="featureName" from="step6-report.feature_name"/>
569
- <output name="generatedFile" from="step6-report.generated_file"/>
570
- <output name="message" from="step6-report.message"/>
563
+ <block type="output" id="O1" desc="Final workflow outputs">
564
+ <field name="status" from="step6-report.status"/>
565
+ <field name="feature" from="step6-report.feature"/>
566
+ <field name="platformType" from="input.platform_type"/>
567
+ <field name="module" from="input.module"/>
568
+ <field name="featureName" from="step6-report.feature_name"/>
569
+ <field name="generatedFile" from="step6-report.generated_file"/>
570
+ <field name="message" from="step6-report.message"/>
571
+ </block>
571
572
 
572
573
  <!-- ==================== ERROR HANDLING ==================== -->
573
- <error-handler>
574
- <catch type="file-not-found">
575
- <event action="log" level="error" message="Source file not found: {{sourcePath}}"/>
576
- <output name="status" value="failed"/>
577
- <output name="message" value="Source file not found: {{sourcePath}}"/>
574
+ <block type="error-handler" id="EH1" desc="Global error handling">
575
+ <catch error-type="file-not-found">
576
+ <block type="event" id="E-err1" action="log" level="error" desc="Log file not found">
577
+ <field name="message" value="Source file not found: ${sourcePath}"/>
578
+ </block>
579
+ <block type="output" id="O-err1" desc="Error output">
580
+ <field name="status" value="failed"/>
581
+ <field name="message" value="Source file not found: ${sourcePath}"/>
582
+ </block>
578
583
  </catch>
579
- <catch type="template-error">
580
- <event action="log" level="error" message="Template processing error"/>
581
- <output name="status" value="failed"/>
582
- <output name="message" value="Failed to process template"/>
584
+ <catch error-type="template-error">
585
+ <block type="event" id="E-err2" action="log" level="error" desc="Log template error">
586
+ <field name="message" value="Template processing error"/>
587
+ </block>
588
+ <block type="output" id="O-err2" desc="Error output">
589
+ <field name="status" value="failed"/>
590
+ <field name="message" value="Failed to process template"/>
591
+ </block>
583
592
  </catch>
584
- <catch type="marker-write-error">
585
- <event action="log" level="error" message="Failed to write marker file: {{error.message}}"/>
586
- <output name="status" value="failed"/>
587
- <output name="message" value="Failed to write completion marker"/>
593
+ <catch error-type="marker-write-error">
594
+ <block type="event" id="E-err3" action="log" level="error" desc="Log marker write error">
595
+ <field name="message" value="Failed to write marker file: ${error.message}"/>
596
+ </block>
597
+ <block type="output" id="O-err3" desc="Error output">
598
+ <field name="status" value="failed"/>
599
+ <field name="message" value="Failed to write completion marker"/>
600
+ </block>
588
601
  </catch>
589
- <catch type="validation-error">
590
- <event action="log" level="error" message="Validation failed: {{error.message}}"/>
591
- <output name="status" value="partial"/>
592
- <output name="message" value="Analysis completed with validation errors"/>
602
+ <catch error-type="validation-error">
603
+ <block type="event" id="E-err4" action="log" level="error" desc="Log validation error">
604
+ <field name="message" value="Validation failed: ${error.message}"/>
605
+ </block>
606
+ <block type="output" id="O-err4" desc="Partial output">
607
+ <field name="status" value="partial"/>
608
+ <field name="message" value="Analysis completed with validation errors"/>
609
+ </block>
593
610
  </catch>
594
611
  <finally>
595
- <event action="log" level="info" message="Workflow execution completed"/>
612
+ <block type="event" id="E-finally" action="log" level="info" desc="Log workflow complete">
613
+ <field name="message" value="Workflow execution completed"/>
614
+ </block>
596
615
  </finally>
597
- </error-handler>
616
+ </block>
598
617
 
599
618
  </workflow>
600
- ```
601
619
 
602
620
  ## Reference Guides
603
621
 
@@ -617,9 +635,9 @@ When generating Mermaid diagrams, follow compatibility guidelines:
617
635
 
618
636
  ## Constraints
619
637
 
620
- 1. **DO NOT analyze files outside the specified `{{sourcePath}}`**
638
+ 1. **DO NOT analyze files outside the specified `${sourcePath}`**
621
639
  2. **DO NOT generate separate documents for internal/private methods**
622
- 3. **All content MUST be in the language specified by `{{language}}`**
640
+ 3. **All content MUST be in the language specified by `${language}`**
623
641
  4. **Use `search_replace` for section filling, NEVER rewrite entire document**
624
642
  5. **Mermaid diagrams MUST follow the rules in `mermaid-rule.md`**
625
643
  6. **All links MUST use relative paths, NEVER `file://` protocol**
@@ -629,14 +647,14 @@ When generating Mermaid diagrams, follow compatibility guidelines:
629
647
 
630
648
  ## Checklist
631
649
 
632
- - [ ] Template file selected based on `{{tech_stack}}`
650
+ - [ ] Template file selected based on `${tech_stack}`
633
651
  - [ ] Template content read successfully
634
652
  - [ ] Controller file read and analyzed
635
653
  - [ ] API endpoints extracted with business flows
636
654
  - [ ] API consumers found
637
655
  - [ ] Template copied to document path
638
656
  - [ ] All sections filled using search_replace
639
- - [ ] All content in target language (`{{language}}`)
657
+ - [ ] All content in target language (`${language}`)
640
658
  - [ ] Results reported in JSON format
641
659
  - [ ] .done.json marker file written successfully
642
660
  - [ ] .graph.json generation dispatched to graph skill