architext 0.0.3 → 0.0.5

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 (118) hide show
  1. package/CHANGELOG.md +56 -1
  2. package/README.md +94 -12
  3. package/README.zh-CN.md +94 -12
  4. package/dist/index.js +43 -39
  5. package/dist/templates/en/briefs/_base.md +44 -11
  6. package/dist/templates/en/briefs/_modules.md +31 -4
  7. package/dist/templates/en/docs/global/api_snapshot.json +24 -0
  8. package/dist/templates/en/docs/global/command_api.json +26 -0
  9. package/dist/templates/en/docs/global/env_registry.json +12 -0
  10. package/dist/templates/en/docs/global/map.json +5 -0
  11. package/dist/templates/en/docs/global/public_api.json +12 -0
  12. package/dist/templates/en/docs/prompts/audit.md +80 -94
  13. package/dist/templates/en/docs/prompts/code.md +100 -109
  14. package/dist/templates/en/docs/prompts/edit.md +52 -47
  15. package/dist/templates/en/docs/prompts/fix.md +49 -42
  16. package/dist/templates/en/docs/prompts/help.md +23 -31
  17. package/dist/templates/en/docs/prompts/inherit.md +110 -116
  18. package/dist/templates/en/docs/prompts/map.md +47 -69
  19. package/dist/templates/en/docs/prompts/plan.md +160 -171
  20. package/dist/templates/en/docs/prompts/recover.md +48 -0
  21. package/dist/templates/en/docs/prompts/ref.md +163 -0
  22. package/dist/templates/en/docs/prompts/remove.md +55 -107
  23. package/dist/templates/en/docs/prompts/revise.md +63 -106
  24. package/dist/templates/en/docs/prompts/scope.md +77 -117
  25. package/dist/templates/en/docs/prompts/start.md +93 -139
  26. package/dist/templates/en/docs/shared/verify-result-handling.md +6 -0
  27. package/dist/templates/en/docs/templates/design.template.md +77 -0
  28. package/dist/templates/en/docs/templates/spec.template.md +60 -25
  29. package/dist/templates/en/rules/00_system.md +36 -79
  30. package/dist/templates/en/rules/01_workflow.md +59 -57
  31. package/dist/templates/en/rules/03_data_governance.md +46 -42
  32. package/dist/templates/en/skills/archi-data-sync/SKILL.md +83 -0
  33. package/dist/templates/en/skills/archi-decompose-roadmap/SKILL.md +166 -151
  34. package/dist/templates/en/skills/archi-design-patterns/SKILL.md +140 -0
  35. package/dist/templates/en/skills/archi-feature-relations/SKILL.md +118 -0
  36. package/dist/templates/en/skills/archi-interview-protocol/SKILL.md +2 -1
  37. package/dist/templates/en/skills/archi-plan-options/SKILL.md +4 -3
  38. package/dist/templates/en/skills/archi-silent-audit/SKILL.md +118 -0
  39. package/dist/templates/en/skills/archi-ui-wireframe/SKILL.md +315 -270
  40. package/dist/templates/zh/briefs/_base.md +46 -14
  41. package/dist/templates/zh/briefs/_modules.md +29 -2
  42. package/dist/templates/zh/docs/global/api_snapshot.json +24 -0
  43. package/dist/templates/zh/docs/global/command_api.json +26 -0
  44. package/dist/templates/zh/docs/global/data_snapshot.json +0 -1
  45. package/dist/templates/zh/docs/global/design_tokens.json +0 -1
  46. package/dist/templates/zh/docs/global/dictionary.json +1 -1
  47. package/dist/templates/zh/docs/global/env_registry.json +12 -0
  48. package/dist/templates/zh/docs/global/error_codes.json +0 -8
  49. package/dist/templates/zh/docs/global/map.json +28 -3
  50. package/dist/templates/zh/docs/global/public_api.json +12 -0
  51. package/dist/templates/zh/docs/global/vision.md +1 -1
  52. package/dist/templates/zh/docs/prompts/audit.md +43 -57
  53. package/dist/templates/zh/docs/prompts/code.md +68 -77
  54. package/dist/templates/zh/docs/prompts/edit.md +44 -39
  55. package/dist/templates/zh/docs/prompts/fix.md +33 -26
  56. package/dist/templates/zh/docs/prompts/help.md +13 -21
  57. package/dist/templates/zh/docs/prompts/inherit.md +81 -87
  58. package/dist/templates/zh/docs/prompts/map.md +23 -45
  59. package/dist/templates/zh/docs/prompts/plan.md +134 -146
  60. package/dist/templates/zh/docs/prompts/recover.md +48 -0
  61. package/dist/templates/zh/docs/prompts/ref.md +163 -0
  62. package/dist/templates/zh/docs/prompts/remove.md +31 -83
  63. package/dist/templates/zh/docs/prompts/revise.md +43 -84
  64. package/dist/templates/zh/docs/prompts/scope.md +53 -93
  65. package/dist/templates/zh/docs/prompts/start.md +75 -121
  66. package/dist/templates/zh/docs/shared/verify-result-handling.md +6 -0
  67. package/dist/templates/zh/docs/templates/design.template.md +77 -0
  68. package/dist/templates/zh/docs/templates/spec.template.md +60 -25
  69. package/dist/templates/zh/rules/00_system.md +37 -80
  70. package/dist/templates/zh/rules/01_workflow.md +60 -58
  71. package/dist/templates/zh/rules/02_tech_stack.md +7 -6
  72. package/dist/templates/zh/rules/03_data_governance.md +43 -39
  73. package/dist/templates/zh/rules/99_context_glue.md +2 -2
  74. package/dist/templates/zh/skills/archi-data-sync/SKILL.md +83 -0
  75. package/dist/templates/zh/skills/archi-decompose-roadmap/SKILL.md +70 -56
  76. package/dist/templates/zh/skills/archi-design-patterns/SKILL.md +140 -0
  77. package/dist/templates/zh/skills/archi-feature-relations/SKILL.md +118 -0
  78. package/dist/templates/zh/skills/archi-interview-protocol/SKILL.md +2 -1
  79. package/dist/templates/zh/skills/archi-plan-options/SKILL.md +26 -25
  80. package/dist/templates/zh/skills/archi-silent-audit/SKILL.md +118 -0
  81. package/dist/templates/zh/skills/archi-ui-wireframe/SKILL.md +317 -269
  82. package/package.json +1 -1
  83. package/dist/templates/zh-Hant/briefs/_base.md +0 -115
  84. package/dist/templates/zh-Hant/briefs/_modules.md +0 -173
  85. package/dist/templates/zh-Hant/docs/global/data_snapshot.json +0 -31
  86. package/dist/templates/zh-Hant/docs/global/design_tokens.json +0 -135
  87. package/dist/templates/zh-Hant/docs/global/dictionary.json +0 -35
  88. package/dist/templates/zh-Hant/docs/global/error_codes.json +0 -19
  89. package/dist/templates/zh-Hant/docs/global/map.json +0 -94
  90. package/dist/templates/zh-Hant/docs/global/roadmap.json +0 -39
  91. package/dist/templates/zh-Hant/docs/global/vision.md +0 -82
  92. package/dist/templates/zh-Hant/docs/prompts/audit.md +0 -150
  93. package/dist/templates/zh-Hant/docs/prompts/code.md +0 -160
  94. package/dist/templates/zh-Hant/docs/prompts/edit.md +0 -87
  95. package/dist/templates/zh-Hant/docs/prompts/fix.md +0 -86
  96. package/dist/templates/zh-Hant/docs/prompts/help.md +0 -69
  97. package/dist/templates/zh-Hant/docs/prompts/inherit.md +0 -270
  98. package/dist/templates/zh-Hant/docs/prompts/map.md +0 -131
  99. package/dist/templates/zh-Hant/docs/prompts/plan.md +0 -252
  100. package/dist/templates/zh-Hant/docs/prompts/remove.md +0 -162
  101. package/dist/templates/zh-Hant/docs/prompts/revise.md +0 -160
  102. package/dist/templates/zh-Hant/docs/prompts/scope.md +0 -198
  103. package/dist/templates/zh-Hant/docs/prompts/start.md +0 -258
  104. package/dist/templates/zh-Hant/docs/templates/plan.template.json +0 -88
  105. package/dist/templates/zh-Hant/docs/templates/scope-brief.template.md +0 -58
  106. package/dist/templates/zh-Hant/docs/templates/spec.template.md +0 -51
  107. package/dist/templates/zh-Hant/docs/templates/ui.template.md +0 -51
  108. package/dist/templates/zh-Hant/rules/00_system.md +0 -123
  109. package/dist/templates/zh-Hant/rules/01_workflow.md +0 -93
  110. package/dist/templates/zh-Hant/rules/02_tech_stack.md +0 -192
  111. package/dist/templates/zh-Hant/rules/03_data_governance.md +0 -102
  112. package/dist/templates/zh-Hant/rules/04_cli_tools.md +0 -50
  113. package/dist/templates/zh-Hant/rules/90_custom_rules.md +0 -21
  114. package/dist/templates/zh-Hant/rules/99_context_glue.md +0 -53
  115. package/dist/templates/zh-Hant/skills/archi-decompose-roadmap/SKILL.md +0 -293
  116. package/dist/templates/zh-Hant/skills/archi-interview-protocol/SKILL.md +0 -86
  117. package/dist/templates/zh-Hant/skills/archi-plan-options/SKILL.md +0 -364
  118. package/dist/templates/zh-Hant/skills/archi-ui-wireframe/SKILL.md +0 -337
@@ -1,162 +0,0 @@
1
- <protocol_remove>
2
- **Trigger**: `/archi.remove <id>`
3
- **Goal**: 將指定 Task 從專案中徹底下線——刪除檔案、程式碼、全域引用,確保零殘留。
4
-
5
- <meta>
6
- <style>Surgical, Cautious, Thorough</style>
7
- <language>繁體中文</language>
8
- <principles>
9
- 1. **Dependency Safety**: 有其他任務依賴此 Task 時,須先解除依賴才能繼續。
10
- 2. **Confirmation Gate**: 刪除操作不可逆,須向使用者展示完整影響並取得明確確認。
11
- 3. **Zero Residue**: 清理須覆蓋全部關聯層面(檔案/程式碼/全域資料/尋址條目)。
12
- 4. **No Side Effects**: 僅刪除目標 Task 相關內容,禁觸碰無關檔案。
13
- </principles>
14
- </meta>
15
-
16
- <step_1_resolve>
17
- **Role**: 系統分析師
18
- **Action**:
19
- 1. **Resolve ID**: 從 `[[__DOCS_DIR__]]/global/roadmap.json` 解析 `<id>` → Task Name、Slug、狀態。
20
- 2. **ID Not Found** → 報錯並列出可用任務 ID。
21
- 3. **Load Context**:
22
- - `[[__DOCS_DIR__]]/tasks/<id>_<Slug>/` — 全部檔案(spec.md, ui.md, plan.json 等)
23
- - `[[__DOCS_DIR__]]/global/roadmap.json` — 任務依賴關係
24
- - `[[__DOCS_DIR__]]/global/map.json` — 架構註冊
25
- - `99_context_glue.md` — 程式碼↔檔案關聯
26
-
27
- **Output**: 目標 Task 基本資訊(ID、名稱、狀態、關聯檔案數)。
28
- </step_1_resolve>
29
-
30
- <step_2_impact>
31
- **Role**: 影響評估官
32
- **Action**: 逐層掃描,產生影響清單。
33
-
34
- ### 2.1 依賴檢查(阻塞級)
35
-
36
- 掃描 `roadmap.json` 中所有任務的 `deps` 欄位,找出依賴 `<id>` 的任務。
37
-
38
- | 情況 | 處理 |
39
- |:---|:---|
40
- | 無下游依賴 | 通過,繼續 |
41
- | 有下游依賴且狀態為 `pending`/`blocked` | 列出受影響任務,詢問使用者:移除依賴關係後繼續,還是中止 |
42
- | 有下游依賴且狀態為 `active`/`done` | **阻塞** — 這些任務可能已使用該 Task 的介面/元件。須先用 `/archi.edit` 解耦後再移除 |
43
-
44
- ### 2.2 程式碼檔案識別
45
-
46
- 透過以下方式定位該 Task 的程式碼檔案:
47
- 1. `99_context_glue.md` 中與 `<id>` 關聯的程式碼路徑。
48
- 2. `map.json` 中該 Task 註冊的模組/目錄。
49
- 3. `plan.json` 中任務提及的檔案路徑。
50
- 4. 掃描程式碼目錄,查找以 Slug 命名或在目錄結構中明確歸屬的檔案。
51
-
52
- ### 2.3 全域引用掃描
53
-
54
- | 檔案 | 掃描內容 |
55
- |:---|:---|
56
- | `roadmap.json` | 任務條目 + 其他任務 `deps` 中的引用 |
57
- | `map.json` | 模組註冊條目 + `featureRelations` 中以被刪 Task 為 aggregator 的條目 |
58
- | `99_context_glue.md` | 關聯條目 |
59
- | `dictionary.json` | 該 Task 獨佔的術語(僅標記,不自動刪) |
60
- | `error_codes.json` | 該 Task 獨佔的錯誤碼(僅標記,不自動刪) |
61
-
62
- ### 2.4 聚合聯動檢查
63
-
64
- 讀取 `map.json.featureRelations`,判斷被刪 Task 是否屬於某聚合方的 `sources` 覆蓋範圍。
65
-
66
- | 情況 | 處理 |
67
- |:---|:---|
68
- | 不在任何聚合方的 sources 範圍內 | 無需特殊處理 |
69
- | 在聚合方 sources 範圍內 | 在影響報告中列出,提示刪除後須檢查聚合方內容是否需要同步移除 |
70
- | 被刪 Task 本身是 aggregator | 同時移除 `featureRelations` 中該條記錄 |
71
-
72
- ### 2.5 跨 Task 引用
73
-
74
- 掃描其他 Task 的 `spec.md`,檢查是否引用了被刪 Task 的介面、元件或資料。發現引用則標註為 `[Breaking]`。
75
-
76
- **Output**: 向使用者輸出影響報告:
77
- ```
78
- ### 下線影響報告: <ID> <Name>
79
-
80
- **Task 狀態**: [status]
81
-
82
- **將刪除的檔案**:
83
- - [[__DOCS_DIR__]]/tasks/<id>_<slug>/ (N 個檔案)
84
-
85
- **將刪除的程式碼**:
86
- | 檔案/目錄 | 來源 |
87
- |:---|:---|
88
- | src/xxx/xxx.ts | context_glue |
89
- | src/xxx/ | map.json |
90
-
91
- **全域引用清理**:
92
- - roadmap.json: 移除任務 <id>,清理 N 處 deps 引用
93
- - map.json: 移除 N 個模組條目
94
- - context_glue: 移除 N 條關聯
95
-
96
- **[?有]術語/錯誤碼殘留** (須人工確認):
97
- - dictionary.json: [term1], [term2]
98
- - error_codes.json: [ERR_XXX]
99
-
100
- **[?有]聚合聯動** (須檢查):
101
- | 聚合方 | checkNote |
102
- |:---|:---|
103
- | [aggregator ID/路徑] | [checkNote 內容] |
104
-
105
- **[?有]跨 Task 引用 [Breaking]**:
106
- | 引用方 | 引用內容 | 建議 |
107
- |:---|:---|:---|
108
- | FEAT-005 spec.md | 呼叫了 <id> 的 UserAPI | 先 /archi.edit FEAT-005 解耦 |
109
-
110
- ---
111
- > 回覆 **OK** 確認執行;回覆 **中止** 取消操作。
112
- ```
113
-
114
- **Gate**: 使用者回覆 OK 後進入 step_3。有 `[Breaking]` 跨 Task 引用時須再次警告。
115
- </step_2_impact>
116
-
117
- <step_3_execute>
118
- **Role**: 外科醫生
119
- **Action**: 按以下順序執行(順序不可調整)。
120
-
121
- | # | 操作 | 對象 |
122
- |:---|:---|:---|
123
- | 1 | 刪除程式碼檔案/目錄 | step_2 識別的程式碼路徑 |
124
- | 2 | 刪除 Task 檔案目錄 | `[[__DOCS_DIR__]]/tasks/<id>_<slug>/` |
125
- | 3 | 更新 `roadmap.json` | 移除任務條目;清理其他任務 `deps` 中對 `<id>` 的引用 |
126
- | 4 | 更新 `map.json` | 移除模組條目;若該 Task 本身是 aggregator,同時移除其 `featureRelations` 條目 |
127
- | 5 | 更新 `99_context_glue.md` | 移除該 Task 的關聯條目 |
128
- | 6 | [?有獨佔術語] 更新 `dictionary.json` | 移除或標註廢棄 |
129
- | 7 | [?有獨佔錯誤碼] 更新 `error_codes.json` | 移除或標註廢棄 |
130
- | 8 | [?有聚合聯動] 檢查聚合方程式碼 | 確認聚合方中對被刪 Task 的引用已清理 |
131
-
132
- 每步完成後記錄操作日誌(檔案路徑 + 操作型別)。
133
- </step_3_execute>
134
-
135
- <step_4_verify>
136
- **Role**: 驗證工程師
137
- **Terminal Gate** (禁止跳過,須在 step_5 輸出前全部完成):
138
- | 步驟 | 命令 | 通過條件 |
139
- |:---|:---|:---|
140
- | 1 | `npx archi task --check` | 無 ERROR 級問題,無懸空依賴 |
141
- | 2 | `npx archi render` | `.md` 視圖生成完成 |
142
- | 3 | 運行專案建置命令 | 零編譯錯誤 |
143
-
144
- | 檢查項 | 通過標準 |
145
- |:---|:---|
146
- | Roadmap 一致性 | `--check` 通過,無懸空依賴 |
147
- | 建置 | 零編譯錯誤 |
148
- | 殘留引用 | 程式碼中無對已刪模組的 import/require |
149
-
150
- 建置失敗或發現殘留引用 → 定位並修復後重檢。
151
- </step_4_verify>
152
-
153
- <step_5_summary>
154
- **Output**: 下線完成摘要:
155
- - **已刪除**: 檔案 N 個、程式碼 N 個
156
- - **已清理**: roadmap / map / context_glue 中的引用
157
- - **建置狀態**: 通過/失敗
158
- - **[?有]須人工跟進**: 術語/錯誤碼/跨 Task 引用殘留
159
- - **Git Commit Suggestion**: `feat(remove): decommission <ID> <Name>`
160
- </step_5_summary>
161
-
162
- </protocol_remove>
@@ -1,160 +0,0 @@
1
- <protocol_revise>
2
- **Trigger**: `/archi.revise [context]`
3
- **Goal**: 執行專案級全域變更(技術堆疊、架構、願景等),分析影響範圍,經使用者確認後修改全域資產並級聯更新受影響的 Task 檔案。
4
-
5
- <constraints_cursor>
6
- **Mode Lock**: 本協議須在 **Agent Mode (Normal Mode)** 下執行。禁切換到 Plan Mode 或其他唯讀模式。
7
- </constraints_cursor>
8
-
9
- <meta>
10
- <style>Strategic, Analytical, Cautious, Traceable</style>
11
- <language>繁體中文</language>
12
- <principles>
13
- 1. **User Gate**: 全域變更須經使用者逐項確認後才執行。禁擅自修改。
14
- 2. **Impact First**: 先輸出完整影響分析,後執行修改。
15
- 3. **Doc Cascade**: 全域資產變更後,須按 edit 標準同步更新受影響的 Task 檔案。
16
- 4. **Traceability**: 每項變更須可追溯 — 說明變更理由和影響範圍。
17
- </principles>
18
- </meta>
19
-
20
- <step_1_load>
21
- **Role**: 系統分析師
22
- **Action**:
23
- 1. **Read Global Assets**:
24
- - `[[__DOCS_DIR__]]/global/vision.md`
25
- - `[[__DOCS_DIR__]]/global/roadmap.json`
26
- - `[[__DOCS_DIR__]]/global/map.json`
27
- - `[[__DOCS_DIR__]]/global/dictionary.json`
28
- - `[[__DOCS_DIR__]]/global/error_codes.json`
29
- - `02_tech_stack.md`
30
- - [?UI] `[[__DOCS_DIR__]]/global/design_tokens.json`
31
- - [?Data] `[[__DOCS_DIR__]]/global/data_snapshot.json`
32
- 2. **Scan Task Index**: 掃描 `[[__DOCS_DIR__]]/tasks/` 目錄,建立 Task 索引(ID、名稱、狀態)。
33
- 3. **Intent Analysis**: 根據使用者 `[context]`,初步定位受影響的全域資產類別。
34
-
35
- **Output**: 變更意圖摘要 — 列出初步判斷涉及的全域檔案,進入 step_2。
36
- </step_1_load>
37
-
38
- <step_2_interview>
39
- **Role**: 首席架構師
40
- **Action**:
41
- 根據使用者描述和已載入上下文,釐清變更邊界:
42
-
43
- | 釐清維度 | 說明 |
44
- |:---|:---|
45
- | 變更範圍 | 精確定位哪些全域檔案、哪些規則受影響 |
46
- | 變更動機 | 為什麼要做此變更,期望達到什麼結果 |
47
- | 排除清單 | 是否有不應被影響的 Task |
48
-
49
- - 上下文足夠清晰時 → 合併到 step_3 直接輸出影響分析。
50
- - 存在歧義或多種可行方向時 → 向使用者提問確認(A/B/C/D 選項)。
51
- </step_2_interview>
52
-
53
- <step_3_impact>
54
- **Role**: 影響分析師
55
- **Constraint**: **純輸出,禁修改任何檔案**。此步驟為「變更影響評估書」。
56
-
57
- **Output Format**:
58
- ```
59
- ## 變更影響評估: [變更主題]
60
-
61
- ### 1. 全域資產變更清單
62
- | 檔案 | 變更內容 | 類型 |
63
- |:---|:---|:---|
64
- | vision.md | [具體改什麼,或"無需變更"] | 修改/無變更 |
65
- | 02_tech_stack.md | [...] | ... |
66
- | roadmap.json | [...] | ... |
67
- | map.json | [...] | ... |
68
- | dictionary.json | [...] | ... |
69
- | data_snapshot.json | [...] | ... |
70
- | design_tokens.json | [...] | ... |
71
- | error_codes.json | [...] | ... |
72
-
73
- ### 2. 受影響 Task 清單
74
- | Task ID | 名稱 | 影響點 | 程度 |
75
- |:---|:---|:---|:---|
76
- | INF-001 | [名稱] | [spec/ui/plan 的哪些部分受影響] | 高/中/低 |
77
-
78
- ### 3. 需使用者決策的項目(如有)
79
- - [?] [不確定項描述 + 選項]
80
- - [?] ...
81
-
82
- ---
83
- > 回覆 **OK** 確認全部;或標注需調整的部分。
84
- ```
85
-
86
- **Gate**: 等待使用者確認。未確認禁進入 step_4。
87
- </step_3_impact>
88
-
89
- <step_3_5_refinement>
90
- **Role**: 諮詢顧問
91
- **Trigger**: 使用者回覆非 OK,含修正、否決或追加意見。
92
- **Action**: 不執行修改。融入使用者回饋,重新整理影響評估書輸出,等待再次確認。
93
- </step_3_5_refinement>
94
-
95
- <step_4_execute>
96
- **Role**: 執行工程師
97
- **Action**:
98
-
99
- **Safety Checkpoint** (執行前須完成):
100
- 1. 檢查 Git 工作區狀態(建議執行 `git status`)。
101
- 2. 如有未提交變更 → 提示使用者先 commit 或 stash,再繼續執行。
102
- 3. 工作區乾淨後,告知使用者:如需回滾,可執行 `git checkout -- .` 恢復至變更前狀態。
103
-
104
- **Phase 1 — 修改全域資產**:
105
- 按使用者確認的清單修改全域檔案。每個檔案修改後輸出變更摘要。
106
-
107
- **[?UI] Phase 1.5 — 設計系統變更檢查**:
108
- 若 `design_tokens.json` 有以下變更,須在 Phase 2 完成後執行對應操作:
109
-
110
- | 變更範圍 | 影響 | 處理方式 |
111
- |:---|:---|:---|
112
- | `primitivePalette.brand` / `semanticTokens.colors` | 品牌色/語義色變化 | 通知使用者:需重跑 `archi-ui-wireframe` Phase 2(全量重著色) |
113
- | `semanticTokens.typography` | 字體變化 | 通知使用者:需重跑 Phase 2 |
114
- | `motion.preference` / `motion.patterns` | 動效變化 | 通知使用者:需重跑 Phase 2 |
115
- | `illustration.iconLibrary` | 圖示庫變化 | 通知使用者:需重跑 Phase 2 |
116
- | `layout` (radius/spacing/shadow) | 元件尺寸/圓角變化 | 通知使用者:需重跑 Phase 2 |
117
-
118
- > 如上述欄位未變動(如僅改 `mode.default`),無需重跑 Phase 2。
119
-
120
- **Phase 2 — 級聯更新 Task 檔案**:
121
- 對每個受影響的 Task,按 `/archi.edit` 標準執行:
122
- 1. 更新 `spec.md`(邏輯/規則因全域變更而需調整的部分)。
123
- 2. [?UI] 更新 `ui.md`(範圍/互動因全域變更而需調整的部分);如畫面結構受影響,執行 `archi-ui-wireframe` Skill(局部更新模式)同步更新 `ui_concept.html` + `ui_context.md`。
124
- 3. 在 `plan.json` 的 `phases` 中追加新 Phase: `Phase X: Global Revision — [變更主題] (<Date>)`,列出落地任務。
125
-
126
- **Output**: 每個檔案的變更摘要(全域 + Task)。
127
- </step_4_execute>
128
-
129
- <step_5_summary>
130
- **Role**: 審計官
131
- **Checklist**:
132
- 1. 全域資產間一致性(vision ↔ tech_stack ↔ roadmap ↔ map)。
133
- 2. Task 檔案與更新後的全域資產對齊。
134
- 3. 無孤立引用(dictionary/map 中舊術語/路徑是否已清理)。
135
-
136
- **Terminal Gate** (禁止跳過,須在輸出總結前全部完成):
137
- | 步驟 | 命令 | 通過條件 |
138
- |:---|:---|:---|
139
- | 1 | `npx archi task --check` | 無 ERROR 級問題 |
140
- | 2 | `npx archi render` | `.md` 視圖生成完成 |
141
-
142
- **Action** (Gate 通過後):
143
- 1. 輸出變更總結。
144
-
145
- **Output**:
146
- ```
147
- ## Global Revision Summary: [變更主題]
148
-
149
- **全域資產變更**: [已修改檔案列表]
150
- **Task 更新**: [已更新 Task 列表 + 各自影響摘要]
151
- **審計結果**: [通過/有風險項]
152
-
153
- ### Next Steps
154
- | 優先級 | 動作 | 說明 |
155
- |:---|:---|:---|
156
- | ... | ... | ... |
157
- ```
158
- </step_5_summary>
159
-
160
- </protocol_revise>
@@ -1,198 +0,0 @@
1
- <protocol_scope>
2
- **Trigger**: `/archi.scope [file_path]`
3
- **Phase**: Requirement Decomposition
4
- **Goal**: 讀取 Scope Brief,將大需求分解為多個 Roadmap 任務並建立依賴關係。
5
-
6
- <meta>
7
- <style>Strategic, Analytical, Structured</style>
8
- <language>繁體中文</language>
9
- <principles>
10
- 1. **Brief-Driven**: 以使用者提供的 Scope Brief 為核心輸入源,禁憑空腦暴功能。
11
- 2. **Incremental**: 在已有 Roadmap 上追加,禁重寫已有任務。
12
- 3. **User Agency First**: Brief 中使用者已填寫的選擇須直接採納,禁質疑或替換。
13
- 4. **Minimal Questions**: 僅針對資訊缺口提問,Brief 充分時可跳過提問直接分解。
14
- 5. **Option Z Everywhere**: 補充提問須包含 `[Z] 自訂`。
15
- </principles>
16
- </meta>
17
-
18
- <step_0_ingest>
19
- **Role**: 情報分析官
20
- **Action**:
21
- 1. 解析觸發命令中的 `[file_path]`:
22
- - 如提供了路徑 → 讀取該檔案
23
- - 如未提供路徑 → 依次查找 `scope-brief.md`(專案根)、`[[__DOCS_DIR__]]/scope-brief.md`
24
- - 如均不存在或為空 → 跳轉 `<fallback_interview>`
25
-
26
- 2. 解析 Brief 各 Section,提取:
27
- - 需求名稱和描述
28
- - 功能清單
29
- - 已有設計決策
30
- - 邊界與約束(不做的事、時間、依賴、技術限制)
31
- - 受影響的已有功能
32
- - 參考資料
33
-
34
- > Brief 是一次性輸入檔案,處理完成後使用者可自行刪除。
35
-
36
- **Output**: 內部摘要(不輸出給使用者),進入 `<step_1_load>`。
37
- </step_0_ingest>
38
-
39
- <step_1_load>
40
- **Role**: 系統分析師
41
- **Action**:
42
- 1. **Read Vision**: `[[__DOCS_DIR__]]/global/vision.md` — 僅讀北極星指標和 Boundaries 段落;其餘章節跳過。
43
- 2. **Read Roadmap**: `[[__DOCS_DIR__]]/global/roadmap.json` — 僅提取每個 task 的 `id/title/status/deps/tag` 欄位(跳過 `goal/notes`,需求分解不需要這些詳情);讀取當前最大 ID 水位用於新任務編號。
44
- 3. **Read Tech Stack**: `02_tech_stack.md` — 技術約束。
45
- 4. **Read Map**: `[[__DOCS_DIR__]]/global/map.json` — 僅讀 `directoryMapping` 和 `featureRelations`;`logicalTopology` 和 `criticalUserJourneys` 跳過。
46
- 5. **Scan Tasks**: 掃描 `[[__DOCS_DIR__]]/tasks/` 目錄 — 了解已有 task 概要(標題 + 關鍵流程,無需全文)。
47
-
48
- **Output**: 內部上下文摘要,進入 `<step_2_analysis>`。
49
- </step_1_load>
50
-
51
- <step_2_analysis>
52
- **Role**: 首席產品戰略官 (CPO)
53
- **Input**: Step 0 Brief 解析結果 + Step 1 專案上下文。
54
-
55
- **Action**:
56
-
57
- 1. **Vision 對齊檢查**: Brief 需求是否與 vision.md 的北極星指標一致?如有偏離 → 在輸出中標註 `[Vision 偏離警告]`。
58
- 2. **功能清單完整性**: Brief 功能清單是否足以支撐需求目標?
59
- 3. **影響評估**: Brief 中「受影響的已有功能」→ 對照 roadmap/tasks 驗證是否存在、狀態如何。
60
- 4. **缺口識別**: 檢查 Brief 是否有關鍵資訊缺失。
61
- 5. **聯動檢查**: 讀取 `map.json.featureRelations`,將新任務的描述與各條 `sources` 欄位做語義對比,判斷新任務是否屬於某聚合方的覆蓋範圍。命中時在摘要中輸出聯動提示。
62
-
63
- **缺口分級**:
64
- - **必須**: 缺失則無法合理分解(如功能清單為空)
65
- - **可補**: AI 可推導但建議確認(如依賴關係不明確)
66
- - **建議**: AI 可自行決定(如功能分組方式)
67
-
68
- **Decision**:
69
- - 無「必須」級缺口 + 無「可補」級缺口 → 跳過 Step 2.5,直接進入 Step 3
70
- - 有缺口 → 進入 Step 2.5
71
-
72
- **Output**: 向使用者輸出 Brief 分析摘要:
73
- ```
74
- ### SCOPE BRIEF 分析報告
75
- > **需求**: [名稱] | **規模**: 預估 [N] 個任務
76
-
77
- **Vision 對齊**: [一致 / ⚠️ 偏離 — 原因]
78
-
79
- **已確認資訊**:
80
- - [列表]
81
-
82
- **受影響的已有功能**:
83
- | 功能 | 狀態 | 預估影響 |
84
- |:---|:---|:---|
85
- | [ID: 名稱] | [done/active/stub] | [需修改/需擴展/無影響] |
86
-
87
- **[?有命中] 聯動提示**:
88
- | 聚合方 | checkNote |
89
- |:---|:---|
90
- | [aggregator ID/路徑] | [checkNote 內容] |
91
-
92
- **資訊缺口** (須補充):
93
- - [缺口列表]
94
-
95
- **AI 將自動決定** (無需操作):
96
- - [列表]
97
- ```
98
- </step_2_analysis>
99
-
100
- <step_2_5_supplementary>
101
- **Role**: 產品顧問
102
- **Trigger**: 僅當 Step 2 發現「必須」或「可補」級缺口時執行。
103
- **Input**: Step 2 的缺口列表。問題數上限 3 題。
104
-
105
- [[SKILL: 按 `archi-interview-protocol` Skill 的核心規則和標準輸出格式提問。]][[NO-SKILL: (Skill 未安裝:請閱讀 `[[__DOCS_DIR__]]/skills/archi-interview-protocol/SKILL.md` 並遵循其規則)]]
106
- </step_2_5_supplementary>
107
-
108
- <step_3_decompose>
109
- **Role**: 首席架構師
110
- **Input**: Brief 全文 + 專案上下文 + 補充回答(如有)。
111
-
112
- **Action**: [[SKILL: 按 `archi-decompose-roadmap` Skill 的協議,基於 Scope Brief 功能清單生成增量任務資料]][[NO-SKILL: (Skill 未安裝:請閱讀 `[[__DOCS_DIR__]]/skills/archi-decompose-roadmap/SKILL.md` 並遵循其協議執行)]]
113
-
114
- **展示格式**(將 Skill 產出的任務資料轉換為以下格式,向使用者呈現後等待確認):
115
-
116
- ```
117
- #### Phase 1: Infrastructure
118
- | ID | 標題 | 描述摘要 | 標籤 |
119
-
120
- #### Phase 2: Core Features
121
- | ID | 標題 | 描述摘要 | 依賴 | 標籤 |
122
-
123
- #### Execution Batches(並行執行批次)
124
- (從 deps 拓樸排序推導,列出每批可同時開工的任務)
125
- Batch 1(立即可開工): ...
126
- Batch 2(等 Batch 1 全完): ...
127
-
128
- #### NFR 橫切關注點(已歸併,不入 Roadmap)
129
- (來自 Skill 的 NFR 歸併清單)
130
- - [NFR 名稱] → 注入 [任務 ID] | 影響:[其他任務 ID]
131
- ```
132
-
133
- **Gate**: 使用者回覆 **OK** 後進入 step_4;未確認禁寫入 Roadmap。使用者可在確認前修正方案(合併/拆分/調整依賴)。
134
- </step_3_decompose>
135
-
136
- <step_3_5_refinement>
137
- **Role**: 諮詢顧問
138
- **Trigger**: 使用者回覆非 OK,含合併/拆分/增刪/依賴調整等修正。
139
- **Action**: 融入使用者回饋,刷新分解方案重新輸出,等待再次確認。
140
- </step_3_5_refinement>
141
-
142
- <step_4_roadmap_update>
143
- **Role**: 系統管理員
144
- **Input**: 使用者確認的分解方案。
145
-
146
- **Action**:
147
- 1. 將新任務追加到 `[[__DOCS_DIR__]]/global/roadmap.json` 對應 Phase 的 `tasks` 陣列中。
148
- 2. 如需新增 Phase → 追加到 `phases` 陣列。
149
- 3. 更新 `lastUpdated` 欄位。
150
- 4. [?新模組] 更新 `[[__DOCS_DIR__]]/global/map.json` 的 `directoryMapping`:為新增任務預注冊推斷的模組路徑(基於 tech_stack 架構模式和任務描述推斷,僅目錄級別;詳細內容在 `/archi.plan` 時完善)。
151
-
152
- **Terminal Gate** (禁止跳過,須在輸出總結前全部完成):
153
- | 步驟 | 命令 | 通過條件 |
154
- |:---|:---|:---|
155
- | 1 | `npx archi task --check` | 無 ERROR 級問題 |
156
- | 2 | `npx archi render` | `.md` 視圖生成完成 |
157
-
158
- **Output**: 寫入確認。
159
- </step_4_roadmap_update>
160
-
161
- <step_5_signoff>
162
- **Action** (Gate 須在 step_4 完成):
163
- 1. 執行 `npx archi task` 輸出任務進度概覽。
164
- 2. 輸出總結。
165
-
166
- **Output**: 需求分解摘要,含:
167
- - **Brief 來源確認**: 需求名稱和核心目標
168
- - **新增任務**: 數量和 Phase 分佈
169
- - **對已有功能的影響**: 影響列表(如有)
170
- - **Next Steps**:
171
-
172
- | 優先級 | 動作 | 說明 |
173
- |:---|:---|:---|
174
- | [?UI] 推薦 | 執行 `archi-ui-wireframe` Skill(追加模式) | 為新增功能追加畫面到 `ui_concept.html`,同步更新 `ui_context.md` |
175
- | 1 | `/archi.plan <第一個 pending 任務 ID>` | 對首個可執行任務做深度規劃 |
176
- | 2 | 審查 roadmap | 確認依賴關係和優先級 |
177
- </step_5_signoff>
178
-
179
- <fallback_interview>
180
- **Trigger**: Brief 檔案不存在或為空。
181
- **Role**: 產品顧問
182
-
183
- **Action**:
184
- 1. 告知使用者 `scope-brief.md` 未找到。建議:
185
- - 執行 `npx archi template scope-brief` 取得範本到專案根目錄
186
- - 填寫後重新執行 `/archi.scope scope-brief.md`
187
- - 或繼續對話,透過訪談方式提供資訊
188
- 2. 如使用者選擇繼續對話,按以下順序引導:
189
- a. 這次要做什麼?(需求名稱、一句話描述、動機)
190
- b. 包含哪些功能?(具體功能清單)
191
- c. 有什麼約束?(不做的事、依賴、技術限制)
192
- d. 會影響哪些已有功能?
193
- 3. 收集完畢後,將資訊寫入 `scope-brief.md`(專案根目錄),然後跳轉 `<step_1_load>`。
194
-
195
- > 此模式為向後相容,核心流程仍以 Brief 為準。
196
- </fallback_interview>
197
-
198
- </protocol_scope>