sdtk-kit 0.3.5 → 0.3.7
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.
- package/README.md +7 -0
- package/assets/manifest/toolkit-bundle.manifest.json +46 -26
- package/assets/manifest/toolkit-bundle.sha256.txt +15 -11
- package/assets/toolkit/toolkit/AGENTS.md +23 -9
- package/assets/toolkit/toolkit/skills/sdtk-arch/SKILL.md +44 -11
- package/assets/toolkit/toolkit/skills/sdtk-arch/references/FLOW_ACTION_SPEC_CREATION_RULES.md +34 -6
- package/assets/toolkit/toolkit/skills/sdtk-design-layout/SKILL.md +16 -0
- package/assets/toolkit/toolkit/skills/sdtk-design-layout/scripts/render_design_layout_images.py +213 -0
- package/assets/toolkit/toolkit/skills/sdtk-dev/SKILL.md +71 -5
- package/assets/toolkit/toolkit/skills/sdtk-dev/prompts/code-quality-reviewer.md +35 -0
- package/assets/toolkit/toolkit/skills/sdtk-dev/prompts/implementer.md +61 -0
- package/assets/toolkit/toolkit/skills/sdtk-dev/prompts/spec-reviewer.md +42 -0
- package/assets/toolkit/toolkit/skills/sdtk-orchestrator/SKILL.md +34 -2
- package/assets/toolkit/toolkit/skills/sdtk-qa/SKILL.md +20 -3
- package/assets/toolkit/toolkit/skills/sdtk-screen-design-spec/SKILL.md +21 -11
- package/assets/toolkit/toolkit/skills/sdtk-screen-design-spec/references/FLOW_ACTION_SPEC_CREATION_RULES.md +34 -6
- package/assets/toolkit/toolkit/templates/docs/specs/FLOW_ACTION_SPEC_CREATION_RULES.md +34 -6
- package/assets/toolkit/toolkit/templates/docs/specs/FLOW_ACTION_SPEC_TEMPLATE.md +22 -16
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,6 +4,10 @@ SDTK CLI -- deterministic documentation toolkit for software teams.
|
|
|
4
4
|
|
|
5
5
|
Wraps the SDTK PowerShell toolkit for portable, reproducible feature documentation scaffolding.
|
|
6
6
|
|
|
7
|
+
Canonical install/runtime source in the source repo: `governance/ai/cli/SDTK_RUNTIME_AND_FEATURE_STATUS.md`
|
|
8
|
+
|
|
9
|
+
Generated skills include verification gates and two-stage review hard gates. See `toolkit/SDTK_TOOLKIT.md` for workflow quality contracts.
|
|
10
|
+
|
|
7
11
|
## Install
|
|
8
12
|
|
|
9
13
|
```bash
|
|
@@ -166,3 +170,6 @@ npm run verify:payload
|
|
|
166
170
|
# Smoke test npm pack
|
|
167
171
|
npm run pack:smoke
|
|
168
172
|
```
|
|
173
|
+
|
|
174
|
+
Run `tests/skill_triggering/` to validate skill routing behavior.
|
|
175
|
+
|
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
{
|
|
2
|
-
"version": "0.3.
|
|
3
|
-
"sourceCommit": "
|
|
4
|
-
"buildTimestamp": "2026-03-
|
|
5
|
-
"fileCount":
|
|
2
|
+
"version": "0.3.7",
|
|
3
|
+
"sourceCommit": "65389f67329cb7379a816963ccdc039dfca74b86",
|
|
4
|
+
"buildTimestamp": "2026-03-17T07:28:34Z",
|
|
5
|
+
"fileCount": 85,
|
|
6
6
|
"files": [
|
|
7
7
|
{
|
|
8
8
|
"path": "toolkit/AGENTS.md",
|
|
9
|
-
"sha256": "
|
|
10
|
-
"size":
|
|
9
|
+
"sha256": "6abad956dae1c20f14d78319282141963e544c24da7ad4d3c22250ff9ebdb783",
|
|
10
|
+
"size": 5887
|
|
11
11
|
},
|
|
12
12
|
{
|
|
13
13
|
"path": "toolkit/install.ps1",
|
|
@@ -116,8 +116,8 @@
|
|
|
116
116
|
},
|
|
117
117
|
{
|
|
118
118
|
"path": "toolkit/skills/sdtk-arch/references/FLOW_ACTION_SPEC_CREATION_RULES.md",
|
|
119
|
-
"sha256": "
|
|
120
|
-
"size":
|
|
119
|
+
"sha256": "a9b8a776ec57a29363924f3f1aef324567292ae17b3bb2ba9d43c83760d926bc",
|
|
120
|
+
"size": 7546
|
|
121
121
|
},
|
|
122
122
|
{
|
|
123
123
|
"path": "toolkit/skills/sdtk-arch/references/FLOWCHART_CREATION_RULES.md",
|
|
@@ -131,23 +131,43 @@
|
|
|
131
131
|
},
|
|
132
132
|
{
|
|
133
133
|
"path": "toolkit/skills/sdtk-arch/SKILL.md",
|
|
134
|
-
"sha256": "
|
|
135
|
-
"size":
|
|
134
|
+
"sha256": "bd7c67ed7d4caf130939fb2dd373fa7e4823b9d85bd45dffbb90761b0510c33a",
|
|
135
|
+
"size": 4876
|
|
136
136
|
},
|
|
137
137
|
{
|
|
138
138
|
"path": "toolkit/skills/sdtk-ba/SKILL.md",
|
|
139
139
|
"sha256": "0a7c6aa20be2e29aa2124355264ee45847df76f635437c2d05ddd26f7121f12e",
|
|
140
140
|
"size": 1177
|
|
141
141
|
},
|
|
142
|
+
{
|
|
143
|
+
"path": "toolkit/skills/sdtk-design-layout/scripts/render_design_layout_images.py",
|
|
144
|
+
"sha256": "ee01a3daeeb4822429f4dcf530c11f15ac65df6700615beefd6c04c3fb41bbbc",
|
|
145
|
+
"size": 6832
|
|
146
|
+
},
|
|
142
147
|
{
|
|
143
148
|
"path": "toolkit/skills/sdtk-design-layout/SKILL.md",
|
|
144
|
-
"sha256": "
|
|
145
|
-
"size":
|
|
149
|
+
"sha256": "24f24cc3561342b4e19ca076ad557dd09a5da380ef979dad68664ab671dd8452",
|
|
150
|
+
"size": 1733
|
|
151
|
+
},
|
|
152
|
+
{
|
|
153
|
+
"path": "toolkit/skills/sdtk-dev/prompts/code-quality-reviewer.md",
|
|
154
|
+
"sha256": "3d44bc436dab6201beeb4fed52ab3aa94791c51baca7b7b8e2e8a5ecd6c08baf",
|
|
155
|
+
"size": 1125
|
|
156
|
+
},
|
|
157
|
+
{
|
|
158
|
+
"path": "toolkit/skills/sdtk-dev/prompts/implementer.md",
|
|
159
|
+
"sha256": "9bed2859fbeee84257199e63eb471874975d26d57f5a19dcedab0c06980e24ad",
|
|
160
|
+
"size": 1844
|
|
161
|
+
},
|
|
162
|
+
{
|
|
163
|
+
"path": "toolkit/skills/sdtk-dev/prompts/spec-reviewer.md",
|
|
164
|
+
"sha256": "1dc33dd59afe48c4c78564bdb32999b9a4f34958361ad8f5580cef0e77c953ef",
|
|
165
|
+
"size": 1222
|
|
146
166
|
},
|
|
147
167
|
{
|
|
148
168
|
"path": "toolkit/skills/sdtk-dev/SKILL.md",
|
|
149
|
-
"sha256": "
|
|
150
|
-
"size":
|
|
169
|
+
"sha256": "785bdb7e35d6b1c58eee35cda1bd9c7f16f543c302c65287a1484b32fc9e8717",
|
|
170
|
+
"size": 5426
|
|
151
171
|
},
|
|
152
172
|
{
|
|
153
173
|
"path": "toolkit/skills/sdtk-dev-backend/SKILL.md",
|
|
@@ -161,8 +181,8 @@
|
|
|
161
181
|
},
|
|
162
182
|
{
|
|
163
183
|
"path": "toolkit/skills/sdtk-orchestrator/SKILL.md",
|
|
164
|
-
"sha256": "
|
|
165
|
-
"size":
|
|
184
|
+
"sha256": "5dbd257f32f0b72ac8968f392bb20789a7e488a612a0f01e8debed80999d0ffa",
|
|
185
|
+
"size": 4352
|
|
166
186
|
},
|
|
167
187
|
{
|
|
168
188
|
"path": "toolkit/skills/sdtk-pm/SKILL.md",
|
|
@@ -171,8 +191,8 @@
|
|
|
171
191
|
},
|
|
172
192
|
{
|
|
173
193
|
"path": "toolkit/skills/sdtk-qa/SKILL.md",
|
|
174
|
-
"sha256": "
|
|
175
|
-
"size":
|
|
194
|
+
"sha256": "4330fcec7b9dcb59ff4a10fb9f39a5c056a0e24ae66655a509e7f79fef6936c0",
|
|
195
|
+
"size": 2568
|
|
176
196
|
},
|
|
177
197
|
{
|
|
178
198
|
"path": "toolkit/skills/sdtk-screen-design-spec/references/excel-image-export.md",
|
|
@@ -186,8 +206,8 @@
|
|
|
186
206
|
},
|
|
187
207
|
{
|
|
188
208
|
"path": "toolkit/skills/sdtk-screen-design-spec/references/FLOW_ACTION_SPEC_CREATION_RULES.md",
|
|
189
|
-
"sha256": "
|
|
190
|
-
"size":
|
|
209
|
+
"sha256": "a9b8a776ec57a29363924f3f1aef324567292ae17b3bb2ba9d43c83760d926bc",
|
|
210
|
+
"size": 7546
|
|
191
211
|
},
|
|
192
212
|
{
|
|
193
213
|
"path": "toolkit/skills/sdtk-screen-design-spec/references/numbering-rules.md",
|
|
@@ -206,8 +226,8 @@
|
|
|
206
226
|
},
|
|
207
227
|
{
|
|
208
228
|
"path": "toolkit/skills/sdtk-screen-design-spec/SKILL.md",
|
|
209
|
-
"sha256": "
|
|
210
|
-
"size":
|
|
229
|
+
"sha256": "6a7149d761ca3e76353a9b78f7ad8195360e8d43dae6e4fa5d1035ef27f0462e",
|
|
230
|
+
"size": 4242
|
|
211
231
|
},
|
|
212
232
|
{
|
|
213
233
|
"path": "toolkit/skills/sdtk-test-case-spec/references/TEST_CASE_CREATION_RULES.md",
|
|
@@ -386,13 +406,13 @@
|
|
|
386
406
|
},
|
|
387
407
|
{
|
|
388
408
|
"path": "toolkit/templates/docs/specs/FLOW_ACTION_SPEC_CREATION_RULES.md",
|
|
389
|
-
"sha256": "
|
|
390
|
-
"size":
|
|
409
|
+
"sha256": "a9b8a776ec57a29363924f3f1aef324567292ae17b3bb2ba9d43c83760d926bc",
|
|
410
|
+
"size": 7546
|
|
391
411
|
},
|
|
392
412
|
{
|
|
393
413
|
"path": "toolkit/templates/docs/specs/FLOW_ACTION_SPEC_TEMPLATE.md",
|
|
394
|
-
"sha256": "
|
|
395
|
-
"size":
|
|
414
|
+
"sha256": "b045989fb4eb6b4a0f62341019c4388f498d18027ec09a0d8da91f3fe310fd51",
|
|
415
|
+
"size": 4760
|
|
396
416
|
},
|
|
397
417
|
{
|
|
398
418
|
"path": "toolkit/templates/QUALITY_CHECKLIST.md",
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
|
|
1
|
+
6abad956dae1c20f14d78319282141963e544c24da7ad4d3c22250ff9ebdb783 toolkit/AGENTS.md
|
|
2
2
|
e717a2791fb597d7a21f57f4c4790dbc545e954f0af3ca0c47f160f78c8a2474 toolkit/install.ps1
|
|
3
3
|
0f3e0bfe1b5165250f0da4da5790a9e6220023752713088a0076eb7f17fd6397 toolkit/runtimes/claude/CLAUDE_TEMPLATE.md
|
|
4
4
|
4154c15c71f44d2f2caf07fb41722fa65d4f9ec7e78f798ee084effd12345c62 toolkit/runtimes/codex/CODEX_TEMPLATE.md
|
|
@@ -20,25 +20,29 @@ f29c6774019ef0789dfb88678e1ab31d4d8eb7b3ab69b2115368ef5d879e5276 toolkit/skills
|
|
|
20
20
|
2c4bc8edda84f20bf05130fdf19b9abd562dd87b03508301dff9ccd877b52a2f toolkit/skills/sdtk-api-doc/SKILL.md
|
|
21
21
|
9adf1e46833411a861fb7426c37baac69689b9e3120a8ed1e4a3224de44a8dd2 toolkit/skills/sdtk-arch/references/API_DESIGN_CREATION_RULES.md
|
|
22
22
|
13f26a3307894b9bfb570d75f6db4ccb61104064d19661ec2a26a1b9984f4c97 toolkit/skills/sdtk-arch/references/API_DESIGN_FLOWCHART_CREATION_RULES.md
|
|
23
|
-
|
|
23
|
+
a9b8a776ec57a29363924f3f1aef324567292ae17b3bb2ba9d43c83760d926bc toolkit/skills/sdtk-arch/references/FLOW_ACTION_SPEC_CREATION_RULES.md
|
|
24
24
|
decffe52425e22b3dd82e9c8f3768aefbb209ec58237107d84f583fee876ea8f toolkit/skills/sdtk-arch/references/FLOWCHART_CREATION_RULES.md
|
|
25
25
|
f29c6774019ef0789dfb88678e1ab31d4d8eb7b3ab69b2115368ef5d879e5276 toolkit/skills/sdtk-arch/references/YAML_CREATION_RULES.md
|
|
26
|
-
|
|
26
|
+
bd7c67ed7d4caf130939fb2dd373fa7e4823b9d85bd45dffbb90761b0510c33a toolkit/skills/sdtk-arch/SKILL.md
|
|
27
27
|
0a7c6aa20be2e29aa2124355264ee45847df76f635437c2d05ddd26f7121f12e toolkit/skills/sdtk-ba/SKILL.md
|
|
28
|
-
|
|
29
|
-
|
|
28
|
+
ee01a3daeeb4822429f4dcf530c11f15ac65df6700615beefd6c04c3fb41bbbc toolkit/skills/sdtk-design-layout/scripts/render_design_layout_images.py
|
|
29
|
+
24f24cc3561342b4e19ca076ad557dd09a5da380ef979dad68664ab671dd8452 toolkit/skills/sdtk-design-layout/SKILL.md
|
|
30
|
+
3d44bc436dab6201beeb4fed52ab3aa94791c51baca7b7b8e2e8a5ecd6c08baf toolkit/skills/sdtk-dev/prompts/code-quality-reviewer.md
|
|
31
|
+
9bed2859fbeee84257199e63eb471874975d26d57f5a19dcedab0c06980e24ad toolkit/skills/sdtk-dev/prompts/implementer.md
|
|
32
|
+
1dc33dd59afe48c4c78564bdb32999b9a4f34958361ad8f5580cef0e77c953ef toolkit/skills/sdtk-dev/prompts/spec-reviewer.md
|
|
33
|
+
785bdb7e35d6b1c58eee35cda1bd9c7f16f543c302c65287a1484b32fc9e8717 toolkit/skills/sdtk-dev/SKILL.md
|
|
30
34
|
4b242b5f86d0074538e14721cc66c0fbaac5757e984796145f5e4477c89c6729 toolkit/skills/sdtk-dev-backend/SKILL.md
|
|
31
35
|
390d895ab5da1fd214efecdbbd13c81e92815d4db157a7e9e8f32c79e09439dd toolkit/skills/sdtk-dev-frontend/SKILL.md
|
|
32
|
-
|
|
36
|
+
5dbd257f32f0b72ac8968f392bb20789a7e488a612a0f01e8debed80999d0ffa toolkit/skills/sdtk-orchestrator/SKILL.md
|
|
33
37
|
7dd81943172b1d7a96093424b0ba76519db3d713272374d5c4aedb15f37adbe2 toolkit/skills/sdtk-pm/SKILL.md
|
|
34
|
-
|
|
38
|
+
4330fcec7b9dcb59ff4a10fb9f39a5c056a0e24ae66655a509e7f79fef6936c0 toolkit/skills/sdtk-qa/SKILL.md
|
|
35
39
|
97f65fd84c80e4836c9bbb82d8b7fc81527336c55dbbd82ea5e69672e21b22e4 toolkit/skills/sdtk-screen-design-spec/references/excel-image-export.md
|
|
36
40
|
a9b414a07d76e63331ffc832dea2381357f9a99e2cd82ea74f713b3a9d7acee7 toolkit/skills/sdtk-screen-design-spec/references/figma-mcp.md
|
|
37
|
-
|
|
41
|
+
a9b8a776ec57a29363924f3f1aef324567292ae17b3bb2ba9d43c83760d926bc toolkit/skills/sdtk-screen-design-spec/references/FLOW_ACTION_SPEC_CREATION_RULES.md
|
|
38
42
|
4edd3318634fbc142f1ce3161fc3ac93d901a6bb7f0add1d1bed7fc25293c4d9 toolkit/skills/sdtk-screen-design-spec/references/numbering-rules.md
|
|
39
43
|
b54b14cc75c02c3fe9f89547b3f09baf1d7d036ef5f3d9f40487516e22351c45 toolkit/skills/sdtk-screen-design-spec/scripts/renumber_flow_action_spec_global.py
|
|
40
44
|
ae0bc9b120c19a142f10cc79168a8f7d6bf8a37e48341fc16cbc74bbdc2e692c toolkit/skills/sdtk-screen-design-spec/scripts/validate_flow_action_spec_numbering.py
|
|
41
|
-
|
|
45
|
+
6a7149d761ca3e76353a9b78f7ad8195360e8d43dae6e4fa5d1035ef27f0462e toolkit/skills/sdtk-screen-design-spec/SKILL.md
|
|
42
46
|
7c21e74f5eee712c6b65665b4f10483ed008113186a92dc0a4673ce1fcd3ef5c toolkit/skills/sdtk-test-case-spec/references/TEST_CASE_CREATION_RULES.md
|
|
43
47
|
4d1e813908114f2be68007fb7373973e2c6e0aebc5a6305b8b19443d5ae477d0 toolkit/skills/sdtk-test-case-spec/scripts/validate_test_case_spec.py
|
|
44
48
|
727a9870a455e9c455b2c405cb52c6b9867f229fa56d8ce9408e66b6f6cae4a5 toolkit/skills/sdtk-test-case-spec/SKILL.md
|
|
@@ -74,8 +78,8 @@ e8d3554fc4893a8a57fbf006e58f37f21347de5f31ce02f0717e97d29b387eea toolkit/templa
|
|
|
74
78
|
7c21e74f5eee712c6b65665b4f10483ed008113186a92dc0a4673ce1fcd3ef5c toolkit/templates/docs/qa/TEST_CASE_CREATION_RULES.md
|
|
75
79
|
4b64a123d6e22edefa17a23a1eff766cf612ec5fa2f78b34bf50eecb39abf06a toolkit/templates/docs/qa/TEST_CASE_TEMPLATE.md
|
|
76
80
|
3b5f911d5e0eb042efc388ef3a441285a57d2dc02ae032d080934495e2d06f4d toolkit/templates/docs/specs/BA_SPEC_TEMPLATE.md
|
|
77
|
-
|
|
78
|
-
|
|
81
|
+
a9b8a776ec57a29363924f3f1aef324567292ae17b3bb2ba9d43c83760d926bc toolkit/templates/docs/specs/FLOW_ACTION_SPEC_CREATION_RULES.md
|
|
82
|
+
b045989fb4eb6b4a0f62341019c4388f498d18027ec09a0d8da91f3fe310fd51 toolkit/templates/docs/specs/FLOW_ACTION_SPEC_TEMPLATE.md
|
|
79
83
|
f9dc0d49ceeeb8814d77670e43f09b5221f46d406fb1e89eb575c1ab39bc022a toolkit/templates/QUALITY_CHECKLIST.md
|
|
80
84
|
0ccb7a0509cf92aa91ebea95996dfffd5b52edd6ab4bbefbb827e4ed495abc31 toolkit/templates/README.md
|
|
81
85
|
2b5d4d10019e3c9b3219d92b8123acc85872d9c76230107206e7a270a5ece5a2 toolkit/templates/SHARED_PLANNING.md
|
|
@@ -12,6 +12,7 @@ Goal: use SDTK as a virtual PM/BA/ARCH/DEV/QA operating model to deliver one fea
|
|
|
12
12
|
- Read stack and command configuration from `sdtk.config.json` in the project root.
|
|
13
13
|
- For VI/JP source requirements, keep original text in an appendix and add literal English translation for traceability.
|
|
14
14
|
- Code review must be complete before QA starts.
|
|
15
|
+
- Verification-before-completion: no phase may declare done, pass, or handoff-ready without fresh command evidence per `governance/ai/core/SDTK_VERIFICATION_BEFORE_COMPLETION_POLICY.md`.
|
|
15
16
|
|
|
16
17
|
## 0.1) Clarification Protocol
|
|
17
18
|
Apply for all roles (`/pm`, `/ba`, `/arch`, `/dev`, `/qa`):
|
|
@@ -44,6 +45,13 @@ Notes:
|
|
|
44
45
|
5. DEV Implementation + Code Review -> `docs/dev/FEATURE_IMPL_PLAN_[FEATURE_KEY].md` + code + tests
|
|
45
46
|
6. QA Testing -> `docs/qa/[FEATURE_KEY]_TEST_CASE.md` + `docs/qa/QA_RELEASE_REPORT_[FEATURE_KEY].md`
|
|
46
47
|
|
|
48
|
+
## 2.1) DEV Review Gates
|
|
49
|
+
DEV Review Gates (mandatory, in order):
|
|
50
|
+
1. Artifact/spec compliance review -- verify code matches BA spec, API YAML, FLOW_ACTION_SPEC, and DB spec line by line.
|
|
51
|
+
2. Code quality review -- verify structure, naming, test coverage, and maintainability. Runs ONLY after Stage 1 PASS.
|
|
52
|
+
|
|
53
|
+
QA handoff is blocked until both gates PASS.
|
|
54
|
+
|
|
47
55
|
## 3) Shared State And Quality Gates
|
|
48
56
|
- `SHARED_PLANNING.md`: phase status, owners, artifacts, blockers, handoff notes.
|
|
49
57
|
- `QUALITY_CHECKLIST.md`: gate checklist by phase.
|
|
@@ -94,16 +102,22 @@ Rule files are installed locally by the runtime. Skills resolve these at:
|
|
|
94
102
|
- Claude Code: `.claude/skills/references/`
|
|
95
103
|
- Codex: `$CODEX_HOME/skills/<skill>/references/`
|
|
96
104
|
|
|
105
|
+
Workflow governance docs:
|
|
106
|
+
- `governance/ai/core/SDTK_VERIFICATION_BEFORE_COMPLETION_POLICY.md` -- verification-before-completion gate
|
|
107
|
+
- `governance/ai/core/SDTK_SKILL_AUTHORING_AND_TESTING.md` -- maintainer authoring/test guide
|
|
108
|
+
|
|
97
109
|
Available rule files:
|
|
98
|
-
- `YAML_CREATION_RULES.md`
|
|
99
|
-
- `API_DESIGN_FLOWCHART_CREATION_RULES.md`
|
|
100
|
-
- `FLOWCHART_CREATION_RULES.md`
|
|
101
|
-
- `API_DESIGN_CREATION_RULES.md`
|
|
102
|
-
- `FLOW_ACTION_SPEC_CREATION_RULES.md`
|
|
103
|
-
- `TEST_CASE_CREATION_RULES.md`
|
|
104
|
-
- `numbering-rules.md`
|
|
105
|
-
- `figma-mcp.md`
|
|
106
|
-
- `excel-image-export.md`
|
|
110
|
+
- `YAML_CREATION_RULES.md` -- API YAML docs
|
|
111
|
+
- `API_DESIGN_FLOWCHART_CREATION_RULES.md` -- API design detail + flow docs
|
|
112
|
+
- `FLOWCHART_CREATION_RULES.md` -- Flowchart (legacy compat)
|
|
113
|
+
- `API_DESIGN_CREATION_RULES.md` -- API design (legacy compat)
|
|
114
|
+
- `FLOW_ACTION_SPEC_CREATION_RULES.md` -- Screen flow-action specs
|
|
115
|
+
- `TEST_CASE_CREATION_RULES.md` -- QA test-case specs
|
|
116
|
+
- `numbering-rules.md` -- Flow-action numbering policy
|
|
117
|
+
- `figma-mcp.md` -- Figma MCP integration
|
|
118
|
+
- `excel-image-export.md` -- Excel image export
|
|
107
119
|
|
|
108
120
|
Flow-action numbering policy:
|
|
109
121
|
- Use one global numbering mode for the whole document (no per-screen reset).
|
|
122
|
+
|
|
123
|
+
|
|
@@ -16,6 +16,19 @@ description: Solution Architect workflow for SDTK. Use when you need to convert
|
|
|
16
16
|
- `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md`
|
|
17
17
|
- `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md`
|
|
18
18
|
|
|
19
|
+
## Flow Overview
|
|
20
|
+
|
|
21
|
+
```dot
|
|
22
|
+
digraph sdtk_arch_flow {
|
|
23
|
+
rankdir=TB;
|
|
24
|
+
BA_SPEC -> ARCH_DESIGN;
|
|
25
|
+
ARCH_DESIGN -> DESIGN_LAYOUT;
|
|
26
|
+
DESIGN_LAYOUT -> FLOW_ACTION_SPEC;
|
|
27
|
+
ARCH_DESIGN -> API_YAML;
|
|
28
|
+
API_YAML -> API_DETAIL;
|
|
29
|
+
}
|
|
30
|
+
```
|
|
31
|
+
|
|
19
32
|
## Process
|
|
20
33
|
1. Read BA spec and PRD/backlog.
|
|
21
34
|
2. Read `sdtk.config.json` for project stack assumptions (backend/frontend/db/auth).
|
|
@@ -25,22 +38,42 @@ description: Solution Architect workflow for SDTK. Use when you need to convert
|
|
|
25
38
|
- `governance/ai/core/SDTK_API_PATH_STYLE_POLICY.md` for canonical resource naming and multi-word path style
|
|
26
39
|
4. If architecture output includes screen flow-action specs, read and apply `./references/FLOW_ACTION_SPEC_CREATION_RULES.md`.
|
|
27
40
|
5. If API detail spec is required, use `sdtk-api-design-spec` to build/update `docs/api/[FEATURE_KEY]_API_DESIGN_DETAIL.md` using YAML + flow list.
|
|
28
|
-
6. For
|
|
29
|
-
|
|
41
|
+
6. For UI-scope features, enforce this generation sequence:
|
|
42
|
+
a. Generate/update `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md` first (using `sdtk-design-layout`).
|
|
43
|
+
b. Attempt to render screen preview images from the layout using `render_design_layout_images.py`. Output: `docs/specs/assets/<feature_snake>/screens/<screen_id>.svg`. If rendering fails (no Java/plantuml.jar), fall back to the render-skipped note -- do not silently skip.
|
|
44
|
+
c. Then generate/update `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md` (using `sdtk-screen-design-spec`).
|
|
45
|
+
d. The flow-action spec must reference the design-layout doc as its design source when no Figma/screenshot is available (Design Source Type: `generated-draft`). Use rendered `.svg` files as the screen image. If render failed, use the render-skipped note instead of a broken image reference.
|
|
46
|
+
7. For complex UI flow-action specs, use `sdtk-screen-design-spec` to build/update `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md`.
|
|
47
|
+
8. Define:
|
|
30
48
|
- System components + data model
|
|
31
49
|
- API endpoints and flows
|
|
32
50
|
- Screen layouts
|
|
33
51
|
- Security/authz decisions
|
|
34
|
-
|
|
52
|
+
9. Create/update:
|
|
35
53
|
- OpenAPI YAML + API endpoint markdown
|
|
36
54
|
- API flow list
|
|
37
55
|
- API design detail spec (when `orchestration.apiDesignDetailMode` is `auto/on`)
|
|
38
56
|
- Database spec (if DB impact exists)
|
|
39
|
-
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
11.
|
|
45
|
-
12.
|
|
46
|
-
13.
|
|
57
|
+
- Design layout (if UI impact exists) - must be created before flow-action spec
|
|
58
|
+
- Flow-action spec (if UI impact exists) - must reference design layout as fallback source
|
|
59
|
+
10. Ensure mapping UC/BR -> DB/API/screens and run output hygiene checks:
|
|
60
|
+
- EN artifacts use English narrative text (except clearly marked original-language appendix blocks)
|
|
61
|
+
- No mojibake/encoding corruption in markdown/yaml/txt outputs
|
|
62
|
+
11. For benchmark runs, apply `governance/ai/core/SDTK_BENCHMARK_OQ_POLICY.md`: keep benchmark-expected open questions explicitly OPEN unless the requirement source resolves them.
|
|
63
|
+
12. If anything is unclear, record OQ-xx in ARCH_DESIGN "Open Questions" and escalate to `@pm` for a decision.
|
|
64
|
+
13. Update shared state + Phase 3 checklist.
|
|
65
|
+
14. Handoff: `@dev please implement ...`.
|
|
66
|
+
|
|
67
|
+
## Order-Critical Hard Gate
|
|
68
|
+
For UI-scope features, do not generate or update `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md` until `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md` already exists and is current enough to serve as the design source for the same scope.
|
|
69
|
+
|
|
70
|
+
If the layout is missing, stale, or cannot support the flow-action spec, stop and fix the layout first. Do not reverse the order and repair it later.
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
## Common Mistakes
|
|
74
|
+
|
|
75
|
+
| Mistake | Why it is wrong | Do instead |
|
|
76
|
+
|---|---|---|
|
|
77
|
+
| Generate `FLOW_ACTION_SPEC` before `DESIGN_LAYOUT` for UI scope | Forces the spec to invent screen behavior without a design source | Create or refresh the layout first, then derive the flow-action spec |
|
|
78
|
+
| Treat API YAML, API detail, and flow-action outputs as independent documents | Causes naming and traceability drift across artifacts | Keep ARCH outputs linked through shared requirements and path policy |
|
|
79
|
+
| Close open questions silently during ARCH | Hides unresolved design decisions from downstream roles | Record `OQ-xx` explicitly and escalate through `@pm` |
|
package/assets/toolkit/toolkit/skills/sdtk-arch/references/FLOW_ACTION_SPEC_CREATION_RULES.md
CHANGED
|
@@ -32,9 +32,9 @@ If a section is not in scope, keep the section and mark explicitly as `N/A` with
|
|
|
32
32
|
|
|
33
33
|
- Every table must include a `No` column (sequential numbering).
|
|
34
34
|
- Use stable headers for action tables:
|
|
35
|
-
- `No |
|
|
35
|
+
- `No | Item Name | Item Type | Attribute | DB Column | Size | Default Value | Action | Description | Note`
|
|
36
36
|
- Use stable headers for API mapping tables:
|
|
37
|
-
- `No | Trigger/When | UI item (No /
|
|
37
|
+
- `No | Trigger/When | UI item (No / Item Name) | API to call | Data usage / Notes`
|
|
38
38
|
- Use stable headers for screen mapping:
|
|
39
39
|
- `No | Screen (section) | Screen ID | Read/Search APIs | Write APIs | Notes / Q&A refs`
|
|
40
40
|
- Table rows must keep column count consistent with the header (no broken or merged rows).
|
|
@@ -43,7 +43,7 @@ If a section is not in scope, keep the section and mark explicitly as `N/A` with
|
|
|
43
43
|
### 3.1 Language and Encoding Standards (EN Artifacts)
|
|
44
44
|
|
|
45
45
|
- For EN artifacts (`docs/en/**` or explicitly requested EN version), narrative text must be English.
|
|
46
|
-
- JP labels
|
|
46
|
+
- JP labels, if provided by the input, should be kept in a clearly marked appendix or note column, not in the default item table columns.
|
|
47
47
|
- Do not leave mixed-language fragments in one sentence/cell (for example VI+EN mixed text).
|
|
48
48
|
- If original VI/JP text is required for traceability, keep it in a clearly marked appendix block (`Original Text`), then provide EN translation.
|
|
49
49
|
- Save files as UTF-8 and avoid mojibake/broken glyphs (`�`, `ↁE`, garbled sequences).
|
|
@@ -69,12 +69,29 @@ For each screen section:
|
|
|
69
69
|
- Provide metadata:
|
|
70
70
|
- official screen name
|
|
71
71
|
- Screen ID
|
|
72
|
-
-
|
|
73
|
-
-
|
|
72
|
+
- Design Source Type
|
|
73
|
+
- Design Source Reference
|
|
74
|
+
- Embed one representative image per screen (from Figma, screenshot, or generated layout).
|
|
74
75
|
- Provide one action table.
|
|
75
76
|
- Provide one API mapping table.
|
|
76
77
|
- If a screen has dialogs, create explicit dialog sub-sections with their own tables and API mapping.
|
|
77
78
|
|
|
79
|
+
## 5.1 Design Source Modes
|
|
80
|
+
|
|
81
|
+
Each screen section must declare a design source using one of these modes:
|
|
82
|
+
|
|
83
|
+
| Mode | When | Design Source Reference |
|
|
84
|
+
|------|------|----------------------|
|
|
85
|
+
| `source-backed` | Figma URL or screenshot is available | Figma URL or screenshot path |
|
|
86
|
+
| `generated-draft` | No Figma/screenshot, but feature has UI scope | Section reference in `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md` |
|
|
87
|
+
| `none` | Feature has no UI scope for this screen | State `N/A - no UI scope` |
|
|
88
|
+
|
|
89
|
+
Rules:
|
|
90
|
+
- For UI-scope features, `none` is only valid when the specific screen truly has no visual layout.
|
|
91
|
+
- When using `generated-draft`, the `DESIGN_LAYOUT_[FEATURE_KEY].md` must exist before the flow-action spec is finalized.
|
|
92
|
+
- The flow-action spec and the design-layout doc must remain separate documents.
|
|
93
|
+
- When Figma becomes available later, update the source mode from `generated-draft` to `source-backed`.
|
|
94
|
+
|
|
78
95
|
## 6. API Traceability Rules
|
|
79
96
|
|
|
80
97
|
- Every actionable UI event that changes state must map to a write API.
|
|
@@ -98,6 +115,17 @@ For each screen section:
|
|
|
98
115
|
- Store images in repository-relative paths.
|
|
99
116
|
- Do not keep temporary local absolute paths in markdown.
|
|
100
117
|
|
|
118
|
+
### 8.1 Rendered Screen Images for Generated-Draft Screens
|
|
119
|
+
|
|
120
|
+
When `Design Source Type` is `generated-draft`:
|
|
121
|
+
- Screen preview images may be rendered from `DESIGN_LAYOUT_[FEATURE_KEY].md` PlantUML SALT wireframes.
|
|
122
|
+
- Renderer: `toolkit/skills/sdtk-design-layout/scripts/render_design_layout_images.py`
|
|
123
|
+
- Expected output path: `docs/specs/assets/<feature_snake>/screens/<screen_id>.svg`
|
|
124
|
+
- If the rendered `.svg` file exists, use it as the `Screen image:` reference.
|
|
125
|
+
- If rendering is unavailable or the `.svg` does not exist, replace the image line with:
|
|
126
|
+
`> Screen image not rendered in this environment. See Design Source Reference for layout.`
|
|
127
|
+
- Do not leave a broken image reference pointing to a non-existent file.
|
|
128
|
+
|
|
101
129
|
## 9. Consistency with Other Specs
|
|
102
130
|
|
|
103
131
|
- Align terms with:
|
|
@@ -128,7 +156,7 @@ For each screen section:
|
|
|
128
156
|
- All mandatory sections exist.
|
|
129
157
|
- All tables include `No`.
|
|
130
158
|
- Numbering is global across the document (no resets).
|
|
131
|
-
- No broken image links.
|
|
159
|
+
- No broken image links (for `generated-draft` screens: `.svg` exists or render-skipped note is present).
|
|
132
160
|
- Screen/API mappings are consistent with `*_ENDPOINTS.md`.
|
|
133
161
|
- Open questions are explicit and traceable.
|
|
134
162
|
- For EN artifact: no leftover VI text outside allowed `Original Text` appendix blocks.
|
|
@@ -15,6 +15,22 @@ description: Generate UI screen layout documentation for a feature, including Pl
|
|
|
15
15
|
- API list table
|
|
16
16
|
- Item table with numbering that matches the wireframe
|
|
17
17
|
3. Keep screen IDs consistent (A-*, B-*, C-*).
|
|
18
|
+
4. After writing `DESIGN_LAYOUT`, attempt to render screen preview images by default:
|
|
19
|
+
- Run `render_design_layout_images.py` to extract `@startsalt` blocks and render `.svg` files.
|
|
20
|
+
- Output path: `docs/specs/assets/<feature_snake>/screens/<screen_id>.svg`
|
|
21
|
+
- If PlantUML is unavailable, rendering is skipped with a warning and the render-skipped note is used in `FLOW_ACTION_SPEC`. The layout doc remains valid.
|
|
22
|
+
|
|
23
|
+
## Screen Image Renderer
|
|
24
|
+
- Script: `toolkit/skills/sdtk-design-layout/scripts/render_design_layout_images.py`
|
|
25
|
+
- Usage:
|
|
26
|
+
```
|
|
27
|
+
python "toolkit/skills/sdtk-design-layout/scripts/render_design_layout_images.py" \
|
|
28
|
+
--design-layout "docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md" \
|
|
29
|
+
--feature-key [FEATURE_KEY]
|
|
30
|
+
```
|
|
31
|
+
- Requires: Java + `plantuml.jar` (auto-detected from VSCode PlantUML extension, or pass `--plantuml-jar`)
|
|
32
|
+
- Output: `.svg` files under `docs/specs/assets/<feature_snake>/screens/`
|
|
33
|
+
- Failure policy: non-blocking. Warns and continues if rendering is unavailable.
|
|
18
34
|
|
|
19
35
|
## Template
|
|
20
36
|
- Use `toolkit/templates/docs/design/DESIGN_LAYOUT_TEMPLATE.md` as starting structure.
|
package/assets/toolkit/toolkit/skills/sdtk-design-layout/scripts/render_design_layout_images.py
ADDED
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""
|
|
3
|
+
Render screen preview SVGs from DESIGN_LAYOUT PlantUML SALT wireframes.
|
|
4
|
+
|
|
5
|
+
Extracts @startsalt blocks from a DESIGN_LAYOUT_[FEATURE_KEY].md file,
|
|
6
|
+
renders each to .svg using a local plantuml.jar, and writes the images
|
|
7
|
+
to docs/specs/assets/<feature_snake>/screens/.
|
|
8
|
+
|
|
9
|
+
Graceful failure: if PlantUML is unavailable or a block fails to render,
|
|
10
|
+
the script warns but does not exit with an error code.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
import argparse
|
|
16
|
+
import re
|
|
17
|
+
import shutil
|
|
18
|
+
import subprocess
|
|
19
|
+
import sys
|
|
20
|
+
from pathlib import Path
|
|
21
|
+
from typing import List, Optional, Tuple
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def parse_args() -> argparse.Namespace:
|
|
25
|
+
parser = argparse.ArgumentParser(
|
|
26
|
+
description="Render screen images from DESIGN_LAYOUT PlantUML SALT blocks."
|
|
27
|
+
)
|
|
28
|
+
parser.add_argument(
|
|
29
|
+
"--design-layout",
|
|
30
|
+
required=True,
|
|
31
|
+
help="Path to DESIGN_LAYOUT_[FEATURE_KEY].md",
|
|
32
|
+
)
|
|
33
|
+
parser.add_argument(
|
|
34
|
+
"--feature-key",
|
|
35
|
+
required=True,
|
|
36
|
+
help="Feature key, e.g. CRM_LITE",
|
|
37
|
+
)
|
|
38
|
+
parser.add_argument(
|
|
39
|
+
"--output-dir",
|
|
40
|
+
default="",
|
|
41
|
+
help="Output directory for SVGs. Default: docs/specs/assets/<feature_snake>/screens/",
|
|
42
|
+
)
|
|
43
|
+
parser.add_argument(
|
|
44
|
+
"--plantuml-jar",
|
|
45
|
+
default="",
|
|
46
|
+
help="Explicit path to plantuml.jar. Auto-detected if omitted.",
|
|
47
|
+
)
|
|
48
|
+
parser.add_argument(
|
|
49
|
+
"--skip-render",
|
|
50
|
+
action="store_true",
|
|
51
|
+
help="Extract .puml files only, skip SVG rendering.",
|
|
52
|
+
)
|
|
53
|
+
return parser.parse_args()
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def normalize_feature_snake(feature_key: str) -> str:
|
|
57
|
+
return re.sub(r"[^a-z0-9]+", "_", feature_key.lower()).strip("_")
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def find_plantuml_jar(explicit: str) -> Optional[Path]:
|
|
61
|
+
if explicit:
|
|
62
|
+
p = Path(explicit).expanduser().resolve()
|
|
63
|
+
return p if p.exists() else None
|
|
64
|
+
user_home = Path.home()
|
|
65
|
+
candidates = sorted(
|
|
66
|
+
(user_home / ".vscode" / "extensions").glob("jebbs.plantuml-*/plantuml.jar")
|
|
67
|
+
)
|
|
68
|
+
if candidates:
|
|
69
|
+
return candidates[-1]
|
|
70
|
+
return None
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def extract_screens(text: str) -> List[Tuple[str, str]]:
|
|
74
|
+
"""Extract (screen_id, plantuml_block) pairs from DESIGN_LAYOUT markdown.
|
|
75
|
+
|
|
76
|
+
Looks for heading patterns like '## A-1. Screen Name' or '## SCR-01 Screen Name'
|
|
77
|
+
followed by a fenced plantuml block containing @startsalt.
|
|
78
|
+
"""
|
|
79
|
+
screens: List[Tuple[str, str]] = []
|
|
80
|
+
heading_pattern = re.compile(
|
|
81
|
+
r"^##\s+([A-Z]+-?\d+|SCR-?\d+)[.\s]",
|
|
82
|
+
re.MULTILINE,
|
|
83
|
+
)
|
|
84
|
+
salt_pattern = re.compile(
|
|
85
|
+
r"```plantuml\s*\n(@startsalt[\s\S]*?@endsalt)\s*\n```",
|
|
86
|
+
re.MULTILINE,
|
|
87
|
+
)
|
|
88
|
+
|
|
89
|
+
headings = list(heading_pattern.finditer(text))
|
|
90
|
+
for i, match in enumerate(headings):
|
|
91
|
+
screen_id = match.group(1).strip().lower().replace("-", "_")
|
|
92
|
+
start = match.start()
|
|
93
|
+
end = headings[i + 1].start() if i + 1 < len(headings) else len(text)
|
|
94
|
+
section = text[start:end]
|
|
95
|
+
|
|
96
|
+
salt_match = salt_pattern.search(section)
|
|
97
|
+
if salt_match:
|
|
98
|
+
screens.append((screen_id, salt_match.group(1)))
|
|
99
|
+
|
|
100
|
+
return screens
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def render_svg(
|
|
104
|
+
plantuml_jar: Path, puml_path: Path, output_dir: Path
|
|
105
|
+
) -> Optional[str]:
|
|
106
|
+
"""Render a single .puml to .svg. Returns error string or None on success."""
|
|
107
|
+
proc = subprocess.run(
|
|
108
|
+
["java", "-jar", str(plantuml_jar), "-tsvg", str(puml_path)],
|
|
109
|
+
stdout=subprocess.PIPE,
|
|
110
|
+
stderr=subprocess.STDOUT,
|
|
111
|
+
text=True,
|
|
112
|
+
check=False,
|
|
113
|
+
)
|
|
114
|
+
# PlantUML writes .svg next to the .puml file.
|
|
115
|
+
svg_path = puml_path.with_suffix(".svg")
|
|
116
|
+
if not svg_path.exists():
|
|
117
|
+
return f"Render failed (no svg produced): {puml_path.name}"
|
|
118
|
+
|
|
119
|
+
# If .puml is already in the output dir, no copy needed.
|
|
120
|
+
# Otherwise move the svg to the output dir.
|
|
121
|
+
svg_dst = output_dir / svg_path.name
|
|
122
|
+
if svg_path.resolve() != svg_dst.resolve():
|
|
123
|
+
shutil.copy2(svg_path, svg_dst)
|
|
124
|
+
svg_path.unlink(missing_ok=True)
|
|
125
|
+
svg_path = svg_dst
|
|
126
|
+
|
|
127
|
+
svg_text = svg_path.read_text(encoding="utf-8", errors="ignore")
|
|
128
|
+
if any(
|
|
129
|
+
x in svg_text
|
|
130
|
+
for x in ("Cannot find group", "Syntax Error", "contains errors")
|
|
131
|
+
):
|
|
132
|
+
return f"Rendered with error content: {svg_path.name}"
|
|
133
|
+
if proc.returncode != 0:
|
|
134
|
+
return f"PlantUML exit={proc.returncode} for {puml_path.name}"
|
|
135
|
+
return None
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
def main() -> int:
|
|
139
|
+
args = parse_args()
|
|
140
|
+
|
|
141
|
+
feature_key = args.feature_key.strip()
|
|
142
|
+
if not feature_key:
|
|
143
|
+
print("[ERROR] --feature-key is empty", file=sys.stderr)
|
|
144
|
+
return 1
|
|
145
|
+
|
|
146
|
+
feature_snake = normalize_feature_snake(feature_key)
|
|
147
|
+
layout_path = Path(args.design_layout)
|
|
148
|
+
if not layout_path.exists():
|
|
149
|
+
print(f"[ERROR] Design layout not found: {layout_path}", file=sys.stderr)
|
|
150
|
+
return 1
|
|
151
|
+
|
|
152
|
+
if args.output_dir:
|
|
153
|
+
output_dir = Path(args.output_dir)
|
|
154
|
+
else:
|
|
155
|
+
output_dir = Path(f"docs/specs/assets/{feature_snake}/screens")
|
|
156
|
+
|
|
157
|
+
output_dir.mkdir(parents=True, exist_ok=True)
|
|
158
|
+
|
|
159
|
+
text = layout_path.read_text(encoding="utf-8")
|
|
160
|
+
screens = extract_screens(text)
|
|
161
|
+
|
|
162
|
+
if not screens:
|
|
163
|
+
print("[WARN] No screen sections with @startsalt blocks found.")
|
|
164
|
+
print("[OK] Nothing to render.")
|
|
165
|
+
return 0
|
|
166
|
+
|
|
167
|
+
print(f"[OK] Found {len(screens)} screen(s) with SALT wireframes.")
|
|
168
|
+
|
|
169
|
+
# Write .puml files
|
|
170
|
+
puml_files: List[Path] = []
|
|
171
|
+
for screen_id, salt_block in screens:
|
|
172
|
+
puml_name = f"{screen_id}.puml"
|
|
173
|
+
puml_path = output_dir / puml_name
|
|
174
|
+
puml_path.write_text(salt_block + "\n", encoding="utf-8")
|
|
175
|
+
puml_files.append(puml_path)
|
|
176
|
+
|
|
177
|
+
if args.skip_render:
|
|
178
|
+
print(f"[OK] Wrote {len(puml_files)} .puml file(s). Render skipped (--skip-render).")
|
|
179
|
+
return 0
|
|
180
|
+
|
|
181
|
+
# Find PlantUML
|
|
182
|
+
jar = find_plantuml_jar(args.plantuml_jar)
|
|
183
|
+
if not jar:
|
|
184
|
+
print("[WARN] PlantUML jar not found. SVG rendering skipped.")
|
|
185
|
+
print(" Use --plantuml-jar or install VSCode PlantUML extension.")
|
|
186
|
+
print(f"[OK] Wrote {len(puml_files)} .puml file(s) without SVG rendering.")
|
|
187
|
+
return 0
|
|
188
|
+
|
|
189
|
+
# Render SVGs
|
|
190
|
+
errors: List[str] = []
|
|
191
|
+
rendered = 0
|
|
192
|
+
for puml_path in puml_files:
|
|
193
|
+
err = render_svg(jar, puml_path, output_dir)
|
|
194
|
+
if err:
|
|
195
|
+
errors.append(err)
|
|
196
|
+
else:
|
|
197
|
+
rendered += 1
|
|
198
|
+
|
|
199
|
+
print(f"[OK] Rendered {rendered}/{len(puml_files)} screen image(s) to: {output_dir}")
|
|
200
|
+
if errors:
|
|
201
|
+
print("[WARN] Render issues:")
|
|
202
|
+
for item in errors:
|
|
203
|
+
print(f" - {item}")
|
|
204
|
+
|
|
205
|
+
return 0
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
if __name__ == "__main__":
|
|
209
|
+
try:
|
|
210
|
+
raise SystemExit(main())
|
|
211
|
+
except Exception as exc:
|
|
212
|
+
print(f"[ERROR] {exc}", file=sys.stderr)
|
|
213
|
+
raise
|
|
@@ -9,12 +9,78 @@ description: Developer workflow for SDTK. Use when you need to implement a featu
|
|
|
9
9
|
- `docs/dev/FEATURE_IMPL_PLAN_[FEATURE_KEY].md`
|
|
10
10
|
- Code + tests (follow repo conventions)
|
|
11
11
|
|
|
12
|
+
## Prompt Templates
|
|
13
|
+
- `./prompts/implementer.md`
|
|
14
|
+
- `./prompts/spec-reviewer.md`
|
|
15
|
+
- `./prompts/code-quality-reviewer.md`
|
|
16
|
+
|
|
17
|
+
Use these templates when you need a controller -> subagent execution loop for implementation and review. The controller owns context selection and pastes the task text into the template placeholders.
|
|
18
|
+
|
|
12
19
|
## Process
|
|
13
20
|
1. Read `ARCH_DESIGN_*` + backlog.
|
|
14
21
|
2. Read `sdtk.config.json` for project stack + test/lint commands.
|
|
15
22
|
3. Write `FEATURE_IMPL_PLAN_*` (scope, file list, test plan).
|
|
16
|
-
4. If anything is unclear: record OQ-xx in FEATURE_IMPL_PLAN
|
|
17
|
-
5.
|
|
18
|
-
6.
|
|
19
|
-
7.
|
|
20
|
-
8.
|
|
23
|
+
4. If anything is unclear: record OQ-xx in FEATURE_IMPL_PLAN "Open Questions" and escalate to `@pm` for a decision (PM asks the user if still missing info).
|
|
24
|
+
5. Dispatch implementation work with `./prompts/implementer.md` when task slicing or delegated execution is needed. The controller must paste the full task text and relevant constraints into the template; do not make the implementer subagent discover missing context on its own.
|
|
25
|
+
6. Implement incrementally with tests.
|
|
26
|
+
7. Run the verification commands that prove the current claim (unit tests, lint, typecheck, build, or targeted smoke checks as applicable) and read the full output before saying the work is done.
|
|
27
|
+
8. If delegated review is needed, run the review loop in this order:
|
|
28
|
+
- `./prompts/spec-reviewer.md` first for artifact/spec compliance
|
|
29
|
+
- `./prompts/code-quality-reviewer.md` only after spec reviewer PASS is documented
|
|
30
|
+
9. Complete mandatory code review gate (self + peer checklist; AI peer review allowed).
|
|
31
|
+
10. Update `SHARED_PLANNING.md` + `QUALITY_CHECKLIST.md` Phase 4.
|
|
32
|
+
11. Handoff: `@qa please test ...` (only after code review PASS and fresh verification evidence is recorded).
|
|
33
|
+
|
|
34
|
+
## Delegated Execution Contract
|
|
35
|
+
- The implementer subagent receives the full task text directly in the prompt.
|
|
36
|
+
- Required implementer status values:
|
|
37
|
+
- `DONE`
|
|
38
|
+
- `DONE_WITH_CONCERNS`
|
|
39
|
+
- `NEEDS_CONTEXT`
|
|
40
|
+
- `BLOCKED`
|
|
41
|
+
- `DONE_WITH_CONCERNS` means the task is complete but the controller must read the concerns before review.
|
|
42
|
+
- `NEEDS_CONTEXT` means the controller must supply missing information and re-dispatch.
|
|
43
|
+
- `BLOCKED` means do not retry the same task unchanged; resolve the blocker first.
|
|
44
|
+
- The spec reviewer must verify real artifacts, not trust implementer claims.
|
|
45
|
+
- The code-quality reviewer is a second-stage review and must not run before spec compliance passes.
|
|
46
|
+
|
|
47
|
+
## Model Selection Guidance
|
|
48
|
+
Choose the cheapest model that can safely complete the task without creating avoidable rework.
|
|
49
|
+
|
|
50
|
+
| Task type | Recommended model tier | Why |
|
|
51
|
+
|---|---|---|
|
|
52
|
+
| Single-file mechanical change with a clear spec | Fast model | Speed matters more than deep judgment |
|
|
53
|
+
| Multi-file integration that follows an approved plan | Standard model | Needs pattern matching across several files |
|
|
54
|
+
| Architecture or design tradeoff for the current implementation slice | Most capable model | Requires judgment and ambiguity handling |
|
|
55
|
+
| Stage 1 artifact/spec review | Standard model | Needs careful comparison against requirements |
|
|
56
|
+
| Stage 2 code-quality review | Standard or most capable model | Choose most capable when boundaries or refactors are non-trivial |
|
|
57
|
+
| Cross-artifact consistency investigation | Most capable model | Requires broader synthesis across docs and code |
|
|
58
|
+
|
|
59
|
+
Blocked-task rule:
|
|
60
|
+
- If an implementer returns `BLOCKED`, do not force the same model to retry the same task unchanged.
|
|
61
|
+
- First resolve missing context or reduce task scope.
|
|
62
|
+
- Escalate to a stronger model only when the blocker is judgment or synthesis bound, not because the prompt was incomplete.
|
|
63
|
+
|
|
64
|
+
## Verification Before Completion
|
|
65
|
+
Apply `governance/ai/core/SDTK_VERIFICATION_BEFORE_COMPLETION_POLICY.md`.
|
|
66
|
+
|
|
67
|
+
Do not:
|
|
68
|
+
- say implementation is done, passing, or QA-ready without fresh verification evidence
|
|
69
|
+
- use `should`, `probably`, or `seems` in place of executed checks
|
|
70
|
+
- rely on partial output, stale command runs, or unchecked agent reports
|
|
71
|
+
|
|
72
|
+
If verification fails or cannot be run, report the status as not verified and explain the blocker.
|
|
73
|
+
|
|
74
|
+
## Order-Critical Hard Gate
|
|
75
|
+
Do not start implementation work until `docs/dev/FEATURE_IMPL_PLAN_[FEATURE_KEY].md` exists and the current execution scope is explicitly approved in that plan for implementation.
|
|
76
|
+
|
|
77
|
+
If the plan is missing, incomplete, or still awaiting approval for the current task slice, stop and update the plan first. Do not implement first and backfill the plan later.
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
## Common Mistakes
|
|
81
|
+
|
|
82
|
+
| Mistake | Why it is wrong | Do instead |
|
|
83
|
+
|---|---|---|
|
|
84
|
+
| Start coding before the implementation plan is approved | Causes scope drift and invalidates review order | Finish and approve `FEATURE_IMPL_PLAN` first |
|
|
85
|
+
| Run Stage 2 code-quality review before Stage 1 spec review passes | Hides requirement mismatches behind style feedback | Keep the review order strict: spec first, quality second |
|
|
86
|
+
| Retry a `BLOCKED` implementer with the same prompt and same model | Repeats the same failure mode | Add missing context, split the task, or change model tier intentionally |
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# SDTK DEV Code Quality Reviewer Prompt Template
|
|
2
|
+
|
|
3
|
+
You are the Stage 2 code-quality reviewer for a completed SDTK development task.
|
|
4
|
+
|
|
5
|
+
## Gate Position
|
|
6
|
+
Run this prompt only after the spec reviewer has passed Stage 1 artifact/spec compliance.
|
|
7
|
+
|
|
8
|
+
## Inputs From Controller
|
|
9
|
+
- Task ID: `{{TASK_ID}}`
|
|
10
|
+
- Feature key: `{{FEATURE_KEY}}`
|
|
11
|
+
- Stage 1 PASS evidence: `{{SPEC_REVIEW_PASS_EVIDENCE}}`
|
|
12
|
+
- Files to review:
|
|
13
|
+
|
|
14
|
+
```text
|
|
15
|
+
{{FILES_TO_REVIEW}}
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
- Relevant coding standards or repo conventions:
|
|
19
|
+
|
|
20
|
+
```text
|
|
21
|
+
{{CODE_QUALITY_RULES}}
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Review Rules
|
|
25
|
+
- Confirm Stage 1 PASS before reviewing code quality.
|
|
26
|
+
- Review structure, naming, maintainability, boundary clarity, and test quality.
|
|
27
|
+
- Flag issues that make the implementation fragile even if it is spec-compliant.
|
|
28
|
+
- Do not reopen Stage 1 scope unless you find a direct contradiction in the shipped code.
|
|
29
|
+
|
|
30
|
+
## Response Format
|
|
31
|
+
- Gate result: `{{GATE_RESULT}}`
|
|
32
|
+
- Code quality findings: `{{QUALITY_FINDINGS}}`
|
|
33
|
+
- Test quality findings: `{{TEST_FINDINGS}}`
|
|
34
|
+
- Required improvements: `{{REQUIRED_IMPROVEMENTS}}`
|
|
35
|
+
- Final recommendation: `{{FINAL_RECOMMENDATION}}`
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# SDTK DEV Implementer Prompt Template
|
|
2
|
+
|
|
3
|
+
You are the implementation subagent for a single SDTK development task.
|
|
4
|
+
|
|
5
|
+
## Mission
|
|
6
|
+
Implement exactly the task provided by the controller, then report one of the required status values.
|
|
7
|
+
|
|
8
|
+
## Inputs From Controller
|
|
9
|
+
- Task ID: `{{TASK_ID}}`
|
|
10
|
+
- Feature key: `{{FEATURE_KEY}}`
|
|
11
|
+
- Scene-setting context: `{{SCENE_CONTEXT}}`
|
|
12
|
+
- Full task text:
|
|
13
|
+
|
|
14
|
+
```text
|
|
15
|
+
{{FULL_TASK_TEXT}}
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
- Relevant requirements or constraints:
|
|
19
|
+
|
|
20
|
+
```text
|
|
21
|
+
{{RELEVANT_CONSTRAINTS}}
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
- Files already identified by the controller:
|
|
25
|
+
|
|
26
|
+
```text
|
|
27
|
+
{{KNOWN_FILE_PATHS}}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
- Verification commands to run before claiming completion:
|
|
31
|
+
|
|
32
|
+
```text
|
|
33
|
+
{{VERIFICATION_COMMANDS}}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Before You Begin
|
|
37
|
+
1. Read the full task text carefully.
|
|
38
|
+
2. If required information is missing, ask focused questions immediately instead of guessing.
|
|
39
|
+
3. Do not ask the controller to make you read unrelated planning files. The controller is responsible for pasting the task context you need.
|
|
40
|
+
|
|
41
|
+
## Working Rules
|
|
42
|
+
- Stay within the provided task scope.
|
|
43
|
+
- Follow repo conventions and existing patterns in the touched files.
|
|
44
|
+
- Update or add tests when the task requires it.
|
|
45
|
+
- Run the provided verification commands before reporting `DONE` or `DONE_WITH_CONCERNS`.
|
|
46
|
+
- Perform a short self-review against the task requirements and obvious code quality issues before you report back.
|
|
47
|
+
|
|
48
|
+
## Required Status Taxonomy
|
|
49
|
+
Return exactly one of these statuses:
|
|
50
|
+
- `DONE`
|
|
51
|
+
- `DONE_WITH_CONCERNS`
|
|
52
|
+
- `NEEDS_CONTEXT`
|
|
53
|
+
- `BLOCKED`
|
|
54
|
+
|
|
55
|
+
## Response Format
|
|
56
|
+
- Status: `{{STATUS}}`
|
|
57
|
+
- Files changed: `{{FILES_CHANGED}}`
|
|
58
|
+
- What was implemented: `{{IMPLEMENTATION_SUMMARY}}`
|
|
59
|
+
- Verification evidence: `{{VERIFICATION_RESULTS}}`
|
|
60
|
+
- Open concerns or blocker details: `{{CONCERNS_OR_BLOCKERS}}`
|
|
61
|
+
- Questions for the controller (if any): `{{FOLLOW_UP_QUESTIONS}}`
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# SDTK DEV Spec Reviewer Prompt Template
|
|
2
|
+
|
|
3
|
+
You are the artifact/spec compliance reviewer for a completed SDTK development task.
|
|
4
|
+
|
|
5
|
+
## Gate Position
|
|
6
|
+
This is Stage 1 review. It runs before the code-quality reviewer.
|
|
7
|
+
|
|
8
|
+
## Inputs From Controller
|
|
9
|
+
- Task ID: `{{TASK_ID}}`
|
|
10
|
+
- Feature key: `{{FEATURE_KEY}}`
|
|
11
|
+
- Scope summary: `{{SCOPE_SUMMARY}}`
|
|
12
|
+
- Implementer report:
|
|
13
|
+
|
|
14
|
+
```text
|
|
15
|
+
{{IMPLEMENTER_REPORT}}
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
- Requirements to validate against:
|
|
19
|
+
|
|
20
|
+
```text
|
|
21
|
+
{{SPEC_REQUIREMENTS}}
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
- Files to review:
|
|
25
|
+
|
|
26
|
+
```text
|
|
27
|
+
{{FILES_TO_REVIEW}}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Review Rules
|
|
31
|
+
- Do NOT trust implementer report, verify code.
|
|
32
|
+
- Read the actual files listed by the controller.
|
|
33
|
+
- Compare the changed artifacts against the provided BA/API/FLOW_ACTION/DB/plan requirements line by line.
|
|
34
|
+
- Identify missing behavior, incorrect mappings, requirement drift, and unverified assumptions.
|
|
35
|
+
- If artifact compliance fails, do not allow the code-quality review to proceed.
|
|
36
|
+
|
|
37
|
+
## Response Format
|
|
38
|
+
- Gate result: `{{GATE_RESULT}}`
|
|
39
|
+
- Requirement-by-requirement findings: `{{SPEC_FINDINGS}}`
|
|
40
|
+
- Missing or incorrect artifacts: `{{ARTIFACT_GAPS}}`
|
|
41
|
+
- Required fixes before Stage 2: `{{REQUIRED_FIXES}}`
|
|
42
|
+
- Verification notes: `{{VERIFICATION_NOTES}}`
|
|
@@ -21,7 +21,7 @@ description: Orchestrate a full 6-phase SDLC multi-agent workflow (PM/BA/ARCH/DE
|
|
|
21
21
|
- If phase is QA and test-case specification is in scope, invoke `sdtk-test-case-spec` to produce/update `docs/qa/[FEATURE_KEY]_TEST_CASE.md`.
|
|
22
22
|
- Update `SHARED_PLANNING.md` (phase row + activity log).
|
|
23
23
|
- Update `QUALITY_CHECKLIST.md` (mark items PASS/Pending).
|
|
24
|
-
- Produce one clear handoff message to the next role.
|
|
24
|
+
- Produce one clear handoff message to the next role only after the current phase evidence supports that handoff.
|
|
25
25
|
|
|
26
26
|
## API design detail mode (Hybrid)
|
|
27
27
|
- Read `sdtk.config.json` key: `orchestration.apiDesignDetailMode`.
|
|
@@ -37,8 +37,40 @@ description: Orchestrate a full 6-phase SDLC multi-agent workflow (PM/BA/ARCH/DE
|
|
|
37
37
|
- `on`: always run `sdtk-test-case-spec` for QA phase (fail fast if required inputs are missing).
|
|
38
38
|
- `off`: skip test-case spec generation unless user explicitly requests it.
|
|
39
39
|
|
|
40
|
+
## Flow Overview
|
|
41
|
+
|
|
42
|
+
```dot
|
|
43
|
+
digraph sdtk_orchestrator_flow {
|
|
44
|
+
rankdir=LR;
|
|
45
|
+
PM -> BA;
|
|
46
|
+
BA -> ARCH;
|
|
47
|
+
ARCH -> DEV;
|
|
48
|
+
DEV -> QA;
|
|
49
|
+
QA -> PM;
|
|
50
|
+
}
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Verification Before Completion
|
|
54
|
+
Apply `governance/ai/core/SDTK_VERIFICATION_BEFORE_COMPLETION_POLICY.md` whenever you mark a phase complete, mark a gate PASS, or hand off to the next role. Require fresh verification evidence before you state that the phase is done.
|
|
55
|
+
|
|
56
|
+
Do not:
|
|
57
|
+
- say a phase is done or PASS without citing the evidence that proves it
|
|
58
|
+
- treat a planned command as equivalent to an executed command
|
|
59
|
+
- hand off DEV or QA work with overstated verification status
|
|
60
|
+
|
|
61
|
+
If the evidence is incomplete, keep the phase open or mark it blocked instead of overstating completion.
|
|
62
|
+
|
|
40
63
|
## Guardrails
|
|
41
64
|
- Do not skip phases; if prerequisites are missing, ask focused questions.
|
|
42
65
|
- Keep traceability: REQ -> BR/UC/AC -> design -> backlog -> code/tests -> QA report.
|
|
43
66
|
- Require code review completion before QA handoff.
|
|
44
|
-
- If input requirements are VI/JP: preserve original text + add EN translation in appendix for traceability (at least in Project Initiation and BA spec).
|
|
67
|
+
- If input requirements are VI/JP: preserve original text + add EN translation in appendix for traceability (at least in Project Initiation and BA spec).
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
## Common Mistakes
|
|
71
|
+
|
|
72
|
+
| Mistake | Why it is wrong | Do instead |
|
|
73
|
+
|---|---|---|
|
|
74
|
+
| Skip directly from PM to DEV because the request seems small | Breaks traceability and removes BA and ARCH controls | Keep phase order unless the user explicitly narrows scope with acceptable evidence |
|
|
75
|
+
| Hand off a phase based on planned checks instead of executed evidence | Creates false PASS status and weakens downstream gates | Require fresh evidence before marking the phase complete |
|
|
76
|
+
| Mix generation, review, and release decisions in one uncontrolled turn | Makes status tracking ambiguous | Complete one phase handoff at a time and update shared state before moving on |
|
|
@@ -11,13 +11,30 @@ description: QA workflow for SDTK. Use when you need to validate an implemented
|
|
|
11
11
|
- `docs/qa/[FEATURE_KEY]_TEST_CASE.md` via `sdtk-test-case-spec`
|
|
12
12
|
|
|
13
13
|
## Process
|
|
14
|
-
1. Validate prerequisites: DEV phase completed + code review PASS.
|
|
14
|
+
1. Validate prerequisites: DEV phase completed + Stage 1 artifact/spec review PASS + Stage 2 code-quality review PASS.
|
|
15
15
|
2. Create test strategy mapped to UC/AC.
|
|
16
16
|
3. If test-case specification artifact is required, invoke `sdtk-test-case-spec` and align counts/coverage with release testing scope. Keep the structured TEST_CASE total consistent with the release-report baseline; track E2E separately if needed.
|
|
17
17
|
4. Apply `governance/ai/core/SDTK_BENCHMARK_QA_MODE_POLICY.md` for benchmark-mode verdict rules when no executable build exists.
|
|
18
18
|
5. If acceptance criteria / expected behavior is unclear, record OQ-xx in QA report and preserve benchmark-expected ambiguity per `governance/ai/core/SDTK_BENCHMARK_OQ_POLICY.md`; escalate to `@pm` if still missing info.
|
|
19
|
-
6. Execute
|
|
19
|
+
6. Execute the required checks, record the commands used, and capture the actual results (unit/integration/e2e or document review evidence as applicable).
|
|
20
20
|
7. Record defects with severity and status.
|
|
21
|
-
8. Decide: APPROVED vs REJECTED
|
|
21
|
+
8. Decide: APPROVED vs REJECTED only after fresh verification evidence supports the verdict.
|
|
22
22
|
9. Update shared state + Phase 5 checklist.
|
|
23
23
|
10. Handoff: `@pm please finalize release status ...` if approved.
|
|
24
|
+
|
|
25
|
+
## Verification Before Completion
|
|
26
|
+
Apply `governance/ai/core/SDTK_VERIFICATION_BEFORE_COMPLETION_POLICY.md` and require fresh verification evidence before any QA verdict or handoff.
|
|
27
|
+
|
|
28
|
+
Do not:
|
|
29
|
+
- issue an APPROVED verdict without fresh verification evidence
|
|
30
|
+
- infer PASS from expected behavior, partial logs, or missing runtime access
|
|
31
|
+
- overstate benchmark-mode results as if they were live execution results
|
|
32
|
+
|
|
33
|
+
If the environment cannot run the proving checks, follow the benchmark QA mode policy explicitly and state that the result is not fully verified at runtime.
|
|
34
|
+
|
|
35
|
+
## Order-Critical Hard Gate
|
|
36
|
+
Do not start QA handoff, release testing, or release decision work until both DEV review gates are documented as PASS:
|
|
37
|
+
- Stage 1 artifact/spec compliance review
|
|
38
|
+
- Stage 2 code-quality review
|
|
39
|
+
|
|
40
|
+
If either review gate is missing or not PASS, keep the work in DEV and block QA handoff until both gates are complete.
|
|
@@ -15,29 +15,39 @@ description: Create/update screen flow-action specifications from requirement so
|
|
|
15
15
|
## Required Inputs
|
|
16
16
|
- Feature key/name
|
|
17
17
|
- Primary requirement sources (BA spec, architecture, customer design docs)
|
|
18
|
-
- Screen source references
|
|
18
|
+
- Screen source references, using one of these design source modes:
|
|
19
|
+
- `source-backed`: Figma URLs and/or requirement screenshots
|
|
20
|
+
- `generated-draft`: generated layout from `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md` (used when no Figma/screenshot is available for a UI-scope feature)
|
|
19
21
|
- API endpoint source (`docs/api/[FEATURE_KEY]_ENDPOINTS.md`) when available
|
|
20
22
|
|
|
21
23
|
## Process
|
|
22
24
|
1. Read requirement sources and identify in-scope screens, dialogs, and transitions.
|
|
23
25
|
2. Read and apply rules from `./references/FLOW_ACTION_SPEC_CREATION_RULES.md`.
|
|
24
|
-
3.
|
|
25
|
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
26
|
+
3. Determine design source mode per screen:
|
|
27
|
+
- If Figma URL or screenshot exists: use `source-backed`.
|
|
28
|
+
- If no Figma/screenshot but feature has UI scope: use `generated-draft` and reference the corresponding section in `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md`. That file must exist before finalizing the flow-action spec.
|
|
29
|
+
- If screen has no UI scope: use `none`.
|
|
30
|
+
4. Build/update section `Feature overview` and `Screen flow action` (PlantUML).
|
|
31
|
+
5. For each screen/dialog:
|
|
32
|
+
- Add metadata (screen ID, Design Source Type, Design Source Reference)
|
|
33
|
+
- Add screen image reference (from Figma, screenshot, or rendered `.svg` from generated layout)
|
|
28
34
|
- Add UI item/action table with `No` column
|
|
29
35
|
- Add API mapping table (trigger -> API -> data usage)
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
36
|
+
6. Build/update `System processing flow` from use-case and process sources.
|
|
37
|
+
7. Build/update `Open questions` for unresolved behavior/API/data points.
|
|
38
|
+
8. Build/update `Screen - API Mapping` summary section.
|
|
39
|
+
9. Validate:
|
|
34
40
|
- global numbering consistency (no screen-level reset)
|
|
35
|
-
- no broken image paths
|
|
41
|
+
- no broken image paths (for `generated-draft` screens, verify `.svg` exists or use render-skipped note)
|
|
36
42
|
- PlantUML renderability
|
|
37
43
|
- consistency with API endpoints spec
|
|
38
44
|
- EN artifact hygiene (no VI leftovers, no mojibake, no merged heading lines)
|
|
39
45
|
- for legacy specs with per-screen reset numbering: run renumber migration first
|
|
40
|
-
|
|
46
|
+
- every UI-scope screen declares a Design Source Type (`source-backed` or `generated-draft`)
|
|
47
|
+
10. For `generated-draft` screens, set `Screen image:` to the rendered `.svg` path if the file exists:
|
|
48
|
+
- Expected path: `docs/specs/assets/<feature_snake>/screens/<screen_id>.svg`
|
|
49
|
+
- If the `.svg` does not exist (render unavailable), replace the image reference with: `> Screen image not rendered in this environment. See Design Source Reference for layout.`
|
|
50
|
+
11. Update document history and handoff to ARCH/DEV.
|
|
41
51
|
|
|
42
52
|
## Rule References
|
|
43
53
|
- Core rules: `./references/FLOW_ACTION_SPEC_CREATION_RULES.md`
|
|
@@ -32,9 +32,9 @@ If a section is not in scope, keep the section and mark explicitly as `N/A` with
|
|
|
32
32
|
|
|
33
33
|
- Every table must include a `No` column (sequential numbering).
|
|
34
34
|
- Use stable headers for action tables:
|
|
35
|
-
- `No |
|
|
35
|
+
- `No | Item Name | Item Type | Attribute | DB Column | Size | Default Value | Action | Description | Note`
|
|
36
36
|
- Use stable headers for API mapping tables:
|
|
37
|
-
- `No | Trigger/When | UI item (No /
|
|
37
|
+
- `No | Trigger/When | UI item (No / Item Name) | API to call | Data usage / Notes`
|
|
38
38
|
- Use stable headers for screen mapping:
|
|
39
39
|
- `No | Screen (section) | Screen ID | Read/Search APIs | Write APIs | Notes / Q&A refs`
|
|
40
40
|
- Table rows must keep column count consistent with the header (no broken or merged rows).
|
|
@@ -43,7 +43,7 @@ If a section is not in scope, keep the section and mark explicitly as `N/A` with
|
|
|
43
43
|
### 3.1 Language and Encoding Standards (EN Artifacts)
|
|
44
44
|
|
|
45
45
|
- For EN artifacts (`docs/en/**` or explicitly requested EN version), narrative text must be English.
|
|
46
|
-
- JP labels
|
|
46
|
+
- JP labels, if provided by the input, should be kept in a clearly marked appendix or note column, not in the default item table columns.
|
|
47
47
|
- Do not leave mixed-language fragments in one sentence/cell (for example VI+EN mixed text).
|
|
48
48
|
- If original VI/JP text is required for traceability, keep it in a clearly marked appendix block (`Original Text`), then provide EN translation.
|
|
49
49
|
- Save files as UTF-8 and avoid mojibake/broken glyphs (`�`, `ↁE`, garbled sequences).
|
|
@@ -69,12 +69,29 @@ For each screen section:
|
|
|
69
69
|
- Provide metadata:
|
|
70
70
|
- official screen name
|
|
71
71
|
- Screen ID
|
|
72
|
-
-
|
|
73
|
-
-
|
|
72
|
+
- Design Source Type
|
|
73
|
+
- Design Source Reference
|
|
74
|
+
- Embed one representative image per screen (from Figma, screenshot, or generated layout).
|
|
74
75
|
- Provide one action table.
|
|
75
76
|
- Provide one API mapping table.
|
|
76
77
|
- If a screen has dialogs, create explicit dialog sub-sections with their own tables and API mapping.
|
|
77
78
|
|
|
79
|
+
## 5.1 Design Source Modes
|
|
80
|
+
|
|
81
|
+
Each screen section must declare a design source using one of these modes:
|
|
82
|
+
|
|
83
|
+
| Mode | When | Design Source Reference |
|
|
84
|
+
|------|------|----------------------|
|
|
85
|
+
| `source-backed` | Figma URL or screenshot is available | Figma URL or screenshot path |
|
|
86
|
+
| `generated-draft` | No Figma/screenshot, but feature has UI scope | Section reference in `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md` |
|
|
87
|
+
| `none` | Feature has no UI scope for this screen | State `N/A - no UI scope` |
|
|
88
|
+
|
|
89
|
+
Rules:
|
|
90
|
+
- For UI-scope features, `none` is only valid when the specific screen truly has no visual layout.
|
|
91
|
+
- When using `generated-draft`, the `DESIGN_LAYOUT_[FEATURE_KEY].md` must exist before the flow-action spec is finalized.
|
|
92
|
+
- The flow-action spec and the design-layout doc must remain separate documents.
|
|
93
|
+
- When Figma becomes available later, update the source mode from `generated-draft` to `source-backed`.
|
|
94
|
+
|
|
78
95
|
## 6. API Traceability Rules
|
|
79
96
|
|
|
80
97
|
- Every actionable UI event that changes state must map to a write API.
|
|
@@ -98,6 +115,17 @@ For each screen section:
|
|
|
98
115
|
- Store images in repository-relative paths.
|
|
99
116
|
- Do not keep temporary local absolute paths in markdown.
|
|
100
117
|
|
|
118
|
+
### 8.1 Rendered Screen Images for Generated-Draft Screens
|
|
119
|
+
|
|
120
|
+
When `Design Source Type` is `generated-draft`:
|
|
121
|
+
- Screen preview images may be rendered from `DESIGN_LAYOUT_[FEATURE_KEY].md` PlantUML SALT wireframes.
|
|
122
|
+
- Renderer: `toolkit/skills/sdtk-design-layout/scripts/render_design_layout_images.py`
|
|
123
|
+
- Expected output path: `docs/specs/assets/<feature_snake>/screens/<screen_id>.svg`
|
|
124
|
+
- If the rendered `.svg` file exists, use it as the `Screen image:` reference.
|
|
125
|
+
- If rendering is unavailable or the `.svg` does not exist, replace the image line with:
|
|
126
|
+
`> Screen image not rendered in this environment. See Design Source Reference for layout.`
|
|
127
|
+
- Do not leave a broken image reference pointing to a non-existent file.
|
|
128
|
+
|
|
101
129
|
## 9. Consistency with Other Specs
|
|
102
130
|
|
|
103
131
|
- Align terms with:
|
|
@@ -128,7 +156,7 @@ For each screen section:
|
|
|
128
156
|
- All mandatory sections exist.
|
|
129
157
|
- All tables include `No`.
|
|
130
158
|
- Numbering is global across the document (no resets).
|
|
131
|
-
- No broken image links.
|
|
159
|
+
- No broken image links (for `generated-draft` screens: `.svg` exists or render-skipped note is present).
|
|
132
160
|
- Screen/API mappings are consistent with `*_ENDPOINTS.md`.
|
|
133
161
|
- Open questions are explicit and traceable.
|
|
134
162
|
- For EN artifact: no leftover VI text outside allowed `Original Text` appendix blocks.
|
|
@@ -32,9 +32,9 @@ If a section is not in scope, keep the section and mark explicitly as `N/A` with
|
|
|
32
32
|
|
|
33
33
|
- Every table must include a `No` column (sequential numbering).
|
|
34
34
|
- Use stable headers for action tables:
|
|
35
|
-
- `No |
|
|
35
|
+
- `No | Item Name | Item Type | Attribute | DB Column | Size | Default Value | Action | Description | Note`
|
|
36
36
|
- Use stable headers for API mapping tables:
|
|
37
|
-
- `No | Trigger/When | UI item (No /
|
|
37
|
+
- `No | Trigger/When | UI item (No / Item Name) | API to call | Data usage / Notes`
|
|
38
38
|
- Use stable headers for screen mapping:
|
|
39
39
|
- `No | Screen (section) | Screen ID | Read/Search APIs | Write APIs | Notes / Q&A refs`
|
|
40
40
|
- Table rows must keep column count consistent with the header (no broken or merged rows).
|
|
@@ -43,7 +43,7 @@ If a section is not in scope, keep the section and mark explicitly as `N/A` with
|
|
|
43
43
|
### 3.1 Language and Encoding Standards (EN Artifacts)
|
|
44
44
|
|
|
45
45
|
- For EN artifacts (`docs/en/**` or explicitly requested EN version), narrative text must be English.
|
|
46
|
-
- JP labels
|
|
46
|
+
- JP labels, if provided by the input, should be kept in a clearly marked appendix or note column, not in the default item table columns.
|
|
47
47
|
- Do not leave mixed-language fragments in one sentence/cell (for example VI+EN mixed text).
|
|
48
48
|
- If original VI/JP text is required for traceability, keep it in a clearly marked appendix block (`Original Text`), then provide EN translation.
|
|
49
49
|
- Save files as UTF-8 and avoid mojibake/broken glyphs (`�`, `ↁE`, garbled sequences).
|
|
@@ -69,12 +69,29 @@ For each screen section:
|
|
|
69
69
|
- Provide metadata:
|
|
70
70
|
- official screen name
|
|
71
71
|
- Screen ID
|
|
72
|
-
-
|
|
73
|
-
-
|
|
72
|
+
- Design Source Type
|
|
73
|
+
- Design Source Reference
|
|
74
|
+
- Embed one representative image per screen (from Figma, screenshot, or generated layout).
|
|
74
75
|
- Provide one action table.
|
|
75
76
|
- Provide one API mapping table.
|
|
76
77
|
- If a screen has dialogs, create explicit dialog sub-sections with their own tables and API mapping.
|
|
77
78
|
|
|
79
|
+
## 5.1 Design Source Modes
|
|
80
|
+
|
|
81
|
+
Each screen section must declare a design source using one of these modes:
|
|
82
|
+
|
|
83
|
+
| Mode | When | Design Source Reference |
|
|
84
|
+
|------|------|----------------------|
|
|
85
|
+
| `source-backed` | Figma URL or screenshot is available | Figma URL or screenshot path |
|
|
86
|
+
| `generated-draft` | No Figma/screenshot, but feature has UI scope | Section reference in `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md` |
|
|
87
|
+
| `none` | Feature has no UI scope for this screen | State `N/A - no UI scope` |
|
|
88
|
+
|
|
89
|
+
Rules:
|
|
90
|
+
- For UI-scope features, `none` is only valid when the specific screen truly has no visual layout.
|
|
91
|
+
- When using `generated-draft`, the `DESIGN_LAYOUT_[FEATURE_KEY].md` must exist before the flow-action spec is finalized.
|
|
92
|
+
- The flow-action spec and the design-layout doc must remain separate documents.
|
|
93
|
+
- When Figma becomes available later, update the source mode from `generated-draft` to `source-backed`.
|
|
94
|
+
|
|
78
95
|
## 6. API Traceability Rules
|
|
79
96
|
|
|
80
97
|
- Every actionable UI event that changes state must map to a write API.
|
|
@@ -98,6 +115,17 @@ For each screen section:
|
|
|
98
115
|
- Store images in repository-relative paths.
|
|
99
116
|
- Do not keep temporary local absolute paths in markdown.
|
|
100
117
|
|
|
118
|
+
### 8.1 Rendered Screen Images for Generated-Draft Screens
|
|
119
|
+
|
|
120
|
+
When `Design Source Type` is `generated-draft`:
|
|
121
|
+
- Screen preview images may be rendered from `DESIGN_LAYOUT_[FEATURE_KEY].md` PlantUML SALT wireframes.
|
|
122
|
+
- Renderer: `toolkit/skills/sdtk-design-layout/scripts/render_design_layout_images.py`
|
|
123
|
+
- Expected output path: `docs/specs/assets/<feature_snake>/screens/<screen_id>.svg`
|
|
124
|
+
- If the rendered `.svg` file exists, use it as the `Screen image:` reference.
|
|
125
|
+
- If rendering is unavailable or the `.svg` does not exist, replace the image line with:
|
|
126
|
+
`> Screen image not rendered in this environment. See Design Source Reference for layout.`
|
|
127
|
+
- Do not leave a broken image reference pointing to a non-existent file.
|
|
128
|
+
|
|
101
129
|
## 9. Consistency with Other Specs
|
|
102
130
|
|
|
103
131
|
- Align terms with:
|
|
@@ -128,7 +156,7 @@ For each screen section:
|
|
|
128
156
|
- All mandatory sections exist.
|
|
129
157
|
- All tables include `No`.
|
|
130
158
|
- Numbering is global across the document (no resets).
|
|
131
|
-
- No broken image links.
|
|
159
|
+
- No broken image links (for `generated-draft` screens: `.svg` exists or render-skipped note is present).
|
|
132
160
|
- Screen/API mappings are consistent with `*_ENDPOINTS.md`.
|
|
133
161
|
- Open questions are explicit and traceable.
|
|
134
162
|
- For EN artifact: no leftover VI text outside allowed `Original Text` appendix blocks.
|
|
@@ -66,26 +66,29 @@ B --> C : open dialog
|
|
|
66
66
|
## 3) Screen layout spec by flow action
|
|
67
67
|
|
|
68
68
|
> Standard item table format:
|
|
69
|
-
> `No |
|
|
69
|
+
> `No | Item Name | Item Type | Attribute | DB Column | Size | Default Value | Action | Description | Note`
|
|
70
70
|
|
|
71
71
|
### 3.1 Screen A
|
|
72
72
|
|
|
73
73
|
Information:
|
|
74
|
-
- JP: TBD
|
|
75
74
|
- Screen ID: SCR-01
|
|
76
|
-
-
|
|
75
|
+
- Design Source Type: source-backed | generated-draft | none
|
|
76
|
+
- Design Source Reference: Figma URL | screenshot path | `docs/design/DESIGN_LAYOUT_{{FEATURE_KEY}}.md` section reference | `N/A - no UI scope`
|
|
77
77
|
|
|
78
78
|
Screen image:
|
|
79
|
-

|
|
80
80
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
|
81
|
+
<!-- If the .svg file does not exist (render unavailable), replace the image line above with: -->
|
|
82
|
+
<!-- > Screen image not rendered in this environment. See Design Source Reference for layout. -->
|
|
83
|
+
|
|
84
|
+
| No | Item Name | Item Type | Attribute | DB Column | Size | Default Value | Action | Description | Note |
|
|
85
|
+
| ---: | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
|
86
|
+
| 1 | Item A | Button | - | - | - | - | Click | TBD | TBD |
|
|
87
|
+
| 2 | Item B | Input | string | column_a | 100 | empty | Input | TBD | TBD |
|
|
85
88
|
|
|
86
89
|
#### API Mapping (Draft)
|
|
87
90
|
|
|
88
|
-
| No | Trigger/When | UI item (No /
|
|
91
|
+
| No | Trigger/When | UI item (No / Item Name) | API to call | Data usage / Notes |
|
|
89
92
|
| ---: | --- | --- | --- | --- |
|
|
90
93
|
| 1 | Initial load | Main area | `GET /api/...` | Load initial dataset |
|
|
91
94
|
| 2 | Click search | No 1 | `POST /api/.../search` | Refresh grid |
|
|
@@ -95,20 +98,23 @@ Screen image:
|
|
|
95
98
|
### 3.2 Screen B
|
|
96
99
|
|
|
97
100
|
Information:
|
|
98
|
-
- JP: TBD
|
|
99
101
|
- Screen ID: SCR-02
|
|
100
|
-
-
|
|
102
|
+
- Design Source Type: source-backed | generated-draft | none
|
|
103
|
+
- Design Source Reference: Figma URL | screenshot path | `docs/design/DESIGN_LAYOUT_{{FEATURE_KEY}}.md` section reference | `N/A - no UI scope`
|
|
101
104
|
|
|
102
105
|
Screen image:
|
|
103
|
-

|
|
107
|
+
|
|
108
|
+
<!-- If the .svg file does not exist (render unavailable), replace the image line above with: -->
|
|
109
|
+
<!-- > Screen image not rendered in this environment. See Design Source Reference for layout. -->
|
|
104
110
|
|
|
105
|
-
| No |
|
|
106
|
-
| ---: | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
|
107
|
-
| 3 | Item C
|
|
111
|
+
| No | Item Name | Item Type | Attribute | DB Column | Size | Default Value | Action | Description | Note |
|
|
112
|
+
| ---: | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
|
113
|
+
| 3 | Item C | Toggle | boolean | flag_a | - | false | Toggle | TBD | TBD |
|
|
108
114
|
|
|
109
115
|
#### API Mapping (Draft)
|
|
110
116
|
|
|
111
|
-
| No | Trigger/When | UI item (No /
|
|
117
|
+
| No | Trigger/When | UI item (No / Item Name) | API to call | Data usage / Notes |
|
|
112
118
|
| ---: | --- | --- | --- | --- |
|
|
113
119
|
| 1 | Change mode | No 3 | `POST /api/.../edit/{uuid}` | Persist mode |
|
|
114
120
|
|