my-opencode 1.3.3 → 2.0.0

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 (46) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +299 -267
  3. package/agents/architect.md +30 -30
  4. package/agents/backend-dev.md +29 -0
  5. package/agents/business-analyst.md +30 -0
  6. package/agents/code-reviewer.md +29 -29
  7. package/agents/design-evidence.md +29 -0
  8. package/agents/frontend-dev.md +29 -0
  9. package/agents/system-designer.md +30 -0
  10. package/agents/team-lead.md +65 -60
  11. package/agents/tech-writer.md +30 -30
  12. package/agents/test-engineer.md +30 -30
  13. package/agents/verifier.md +38 -33
  14. package/bin/cli.js +366 -364
  15. package/bin/moc +198 -198
  16. package/opencode.json +218 -170
  17. package/package.json +53 -50
  18. package/plugins/README.md +67 -64
  19. package/plugins/provider-profile.mjs +203 -139
  20. package/scripts/postinstall.js +202 -202
  21. package/scripts/validate-role-flow.mjs +90 -0
  22. package/skills/adr/SKILL.md +91 -91
  23. package/skills/adr/references/templates.md +100 -100
  24. package/skills/adr/scripts/README.md +5 -5
  25. package/skills/design-evidence/SKILL.md +56 -0
  26. package/skills/dev-flow/SKILL.md +126 -188
  27. package/skills/dev-flow/references/code-phase.md +35 -72
  28. package/skills/dev-flow/references/contract-phase.md +66 -81
  29. package/skills/dev-flow/references/verify-phase.md +70 -129
  30. package/skills/dev-flow/scripts/README.md +3 -3
  31. package/skills/docs-gen/SKILL.md +162 -162
  32. package/skills/docs-gen/references/doc-styles.md +216 -216
  33. package/skills/docs-gen/scripts/README.md +5 -5
  34. package/skills/orchestrate/SKILL.md +63 -112
  35. package/skills/orchestrate/references/orchestration-patterns.md +49 -56
  36. package/skills/pr-review/SKILL.md +110 -110
  37. package/skills/pr-review/references/review-dimensions.md +117 -117
  38. package/skills/pr-review/references/security-checklist.md +122 -122
  39. package/skills/pr-review/scripts/README.md +5 -5
  40. package/skills/test-gen/SKILL.md +143 -143
  41. package/skills/test-gen/references/framework-detection.md +105 -105
  42. package/skills/test-gen/references/test-patterns.md +260 -260
  43. package/skills/test-gen/scripts/README.md +5 -5
  44. package/agents/executor.md +0 -30
  45. package/agents/fullstack-dev.md +0 -57
  46. package/agents/spec-writer.md +0 -37
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 my-opencode
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 my-opencode
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,281 +1,313 @@
1
- # my-opencode
2
-
3
- 為 [opencode](https://opencode.ai) 生態打造的高品質開發流程 skill 與 agents 集合。
4
-
5
- > 參考業界知名 agentic coding repo 的設計哲學,提煉出一套符合 opencode 架構的模組化、可組合的開發技能包。
6
-
7
- ---
8
-
9
- ## 快速安裝(npm)
10
-
11
- ```bash
1
+ # my-opencode
2
+
3
+ 為 [opencode](https://opencode.ai) 生態打造的高品質開發流程 skill 與 agents 集合。
4
+
5
+ > 參考業界知名 agentic coding repo 的設計哲學,提煉出一套符合 opencode 架構的模組化、可組合的開發技能包。
6
+
7
+ ---
8
+
9
+ ## 快速安裝(npm)
10
+
11
+ ```bash
12
12
  # 在專案中安裝(產生 .opencode/,並提供 moc launcher)
13
13
  npm install my-opencode
14
-
15
- # 或只初始化 .opencode/
16
- npx my-opencode init
17
-
18
- # 安裝到指定專案
19
- npx my-opencode init ./my-project
20
-
21
- # 覆寫既有檔案(升級用)
22
- npx my-opencode init --force
23
- ```
24
-
25
- 這會在你的專案下建立 `.opencode/`,包含 `skills/`、`agents/`、`plugins/`、`opencode.json`。
26
-
27
- opencode 會自動發現 `.opencode/opencode.json`,無需額外設定。
28
-
29
- ### 升級到最新版
30
-
31
- ```bash
32
- # 1. 更新 npm 套件
33
- npm install my-opencode@latest
34
-
35
- # 2. 覆寫既有 .opencode/ 檔案(預設會跳過已存在檔案)
36
- npx my-opencode init --force
37
- ```
38
-
39
- > ⚠️ `init` 預設「已存在就跳過」以保護你客製化的檔案。
40
- > `--force`(alias `-f` / `--overwrite`)才會覆寫 skills/agents/plugins/opencode.json。
41
- > 若只想保留自己改過的 `opencode.json`,可先備份再執行 `--force`。
42
-
43
- ---
44
-
45
- ### 本地開發(git clone)
46
-
47
- 如果直接 clone 本 repo 做開發或試用:
48
-
49
- ```bash
50
- git clone https://github.com/jjyung/my-opencode.git
51
- cd my-opencode
52
- npm link # 將 bin/moc 註冊到 PATH,讓 moc 指令全域可用
53
- ```
54
-
14
+
15
+ # 或只初始化 .opencode/
16
+ npx my-opencode init
17
+
18
+ # 安裝到指定專案
19
+ npx my-opencode init ./my-project
20
+
21
+ # 覆寫既有檔案(升級用)
22
+ npx my-opencode init --force
23
+ ```
24
+
25
+ 這會在你的專案下建立 `.opencode/`,包含 `skills/`、`agents/`、`plugins/`、`opencode.json`。
26
+
27
+ opencode 會自動發現 `.opencode/opencode.json`,無需額外設定。
28
+
29
+ ### 升級到最新版
30
+
31
+ ```bash
32
+ # 1. 更新 npm 套件
33
+ npm install my-opencode@latest
34
+
35
+ # 2. 覆寫既有 .opencode/ 檔案(預設會跳過已存在檔案)
36
+ npx my-opencode init --force
37
+ ```
38
+
39
+ > ⚠️ `init` 預設「已存在就跳過」以保護你客製化的檔案。
40
+ > `--force`(alias `-f` / `--overwrite`)才會覆寫 skills/agents/plugins/opencode.json。
41
+ > 若只想保留自己改過的 `opencode.json`,可先備份再執行 `--force`。
42
+
43
+ ---
44
+
45
+ ### 本地開發(git clone)
46
+
47
+ 如果直接 clone 本 repo 做開發或試用:
48
+
49
+ ```bash
50
+ git clone https://github.com/jjyung/my-opencode.git
51
+ cd my-opencode
52
+ npm link # 將 bin/moc 註冊到 PATH,讓 moc 指令全域可用
53
+ ```
54
+
55
55
  `npm link` 完成後,`moc` 即可在任何目錄使用。
56
56
  新的 npm bin 入口是跨平台的 `bin/moc.js`;repo 內仍保留 `bin/moc` 給直接 shell 執行情境使用。
57
-
58
- ---
59
-
57
+
58
+ ---
59
+
60
60
  安裝完成後,`moc` 會成為主要入口:
61
-
62
- ```bash
63
- moc # 預設 opencode profile
64
- moc openai # 切到 OpenAI profile
65
- moc google # 切到 Google profile
61
+
62
+ ```bash
63
+ moc # 預設 opencode profile
64
+ moc openai # 切到 OpenAI profile
65
+ moc google # 切到 Google profile
66
66
  moc copilot # 切到 Copilot profile
67
67
  moc --help # 透明轉發到 opencode --help
68
68
  ```
69
69
 
70
70
  Windows(cmd、PowerShell)現在也支援直接執行 `moc`;npm 會自動建立對應 shim,無需額外安裝 `.cmd` 或 `.ps1` 檔案。
71
-
72
- 其他指令:
73
-
74
- ```bash
75
- npx my-opencode list # 列出可用 skills 與 agents
76
- npx my-opencode help # 顯示說明
77
- ```
78
-
79
- ## Provider Profile 切換
80
-
81
- 內建 `provider-profile` plugin / resolver,主要透過 `moc` 切換整套模型配置。
82
-
83
- 支援值:`opencode`(預設)、`openai`、`google`、`copilot`
84
-
85
- | Profile | Primary / heavy | Small / verifier |
86
- |---------|------------------|------------------|
87
- | `opencode` | `opencode-go/deepseek-v4-pro` | `opencode-go/deepseek-v4-flash` |
88
- | `openai` | `openai/gpt-5.4` | `openai/gpt-5.4-mini` |
89
- | `google` | `google/gemini-3.1-pro-preview-customtools` | `google/gemini-3.5-flash` |
90
- | `copilot` | `copilot/gpt-5.4` | `copilot/gpt-5.4-mini` |
91
-
92
- ```bash
93
- # 預設 profile(opencode)
94
- moc
95
-
96
- # 切到 OpenAI
97
- moc openai
98
-
99
- # 切到 Google
100
- moc google
101
-
102
- # 轉發額外參數
103
- moc openai --list-agents
104
- ```
105
-
71
+
72
+ 其他指令:
73
+
74
+ ```bash
75
+ npx my-opencode list # 列出可用 skills 與 agents
76
+ npx my-opencode help # 顯示說明
77
+ ```
78
+
79
+ ## Provider Profile 切換
80
+
81
+ 內建 `provider-profile` plugin / resolver,主要透過 `moc` 切換整套模型配置。
82
+
83
+ 支援值:`opencode`(預設)、`openai`、`google`、`copilot`
84
+
85
+ | Profile | Primary / heavy | Small / verifier |
86
+ |---------|------------------|------------------|
87
+ | `opencode` | `opencode-go/deepseek-v4-pro` | `opencode-go/deepseek-v4-flash` |
88
+ | `openai` | `openai/gpt-5.6` | `openai/gpt-5.6-luna` |
89
+ | `google` | `google/gemini-3.1-pro-preview-customtools` | `google/gemini-3.5-flash` |
90
+ | `copilot` | `github-copilot/gpt-5.6-sol` | `github-copilot/gpt-5.6-luna` |
91
+
92
+ > 💡 `openai` 與 `copilot` profile 的 `gpt-5.6-luna`(verifier / 小型任務)支援 reasoning effort 切換:
93
+ > **high / medium / low** 三檔(預設 `low`)。在 opencode 內用 `variant_cycle` 快捷鍵循環切換。
94
+
95
+ ```bash
96
+ # 預設 profile(opencode)
97
+ moc
98
+
99
+ # 切到 OpenAI
100
+ moc openai
101
+
102
+ # 切到 Google
103
+ moc google
104
+
105
+ # 轉發額外參數
106
+ moc openai --list-agents
107
+ ```
108
+
106
109
  `moc` 會在目前工作目錄尋找 `.opencode/plugins/provider-profile.mjs` 與 `.opencode/opencode.json`。
107
110
  對 `opencode` / `openai` / `google` / `copilot` 這四個 profile,會把產生出的 `OPENCODE_CONFIG_CONTENT` 快取到 `.opencode/cache/provider-profile/`;只要 profile、plugin mtime、config mtime 都沒變,就直接重用快取,不再重新跑 Node。若 plugin 缺失,則會警告並回退為 plain `opencode`。
108
111
 
109
112
  若你直接用 repo 內的 `bin/moc`,仍會走既有 POSIX shell launcher;透過 npm 安裝、`npm link`、`npx` 取得的 `moc` 則會走跨平台的 `bin/moc.js`。
110
-
111
- 若要在 script 中直接使用環境變數,也可以:
112
-
113
- ```bash
114
- OPENCODE_PROVIDER_PROFILE=openai \
115
- OPENCODE_CONFIG_CONTENT="$(node .opencode/plugins/provider-profile.mjs)" \
116
- opencode
117
- ```
118
-
119
- 如果想固定專案 profile,可把 `.opencode/opencode.json` 的 plugin 設定改成 tuple:
120
-
121
- ```json
122
- {
123
- "plugin": [
124
- ["plugins/provider-profile.mjs", { "profile": "google" }]
125
- ]
126
- }
127
- ```
128
-
129
- 此 tuple 會覆寫 `OPENCODE_PROVIDER_PROFILE`。
130
-
131
- ### 發布(維護者專用)
132
-
133
- #### Token 設定
134
-
135
- 發布前需要建立一個 **Access Token**(繞過 2FA):
136
-
137
- 1. 到 https://www.npmjs.com/settings/~/tokens
138
- 2. Generate New Token → Granular Access Token
139
- 3. 勾選 bypass two-factor authentication
140
- 4. 設定 Read and Write 權限
141
- 5. 將產生的 token 寫入專案 `.npmrc`:
142
-
143
- ```bash
144
- echo "//registry.npmjs.org/:_authToken=npm_xxxxxxxxxxxx" > .npmrc
145
- ```
146
-
147
- > ⚠️ `.npmrc` 已加入 `.gitignore`,不會被 commit。
148
-
149
- #### 發布指令
150
-
151
- ```bash
152
- npm publish
153
- ```
154
-
155
- ---
156
-
157
- ## 靈感來源
158
-
159
- | 專案 | Stars | 核心啟發 |
160
- |------|-------|----------|
161
- | [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) | 170K+ | 超大型 skill 生態系統,40+ skill 模組,跨平台設計 |
162
- | [Yeachan-Heo/oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) | 31K+ | 多 agent 編排模式(Team / Autopilot / Pipeline),plan→prd→exec→verify→fix 流程 |
163
- | [wshobson/agents](https://github.com/wshobson/agents) | 35K+ | 185+ 專用 agent、153 skill、單一職責 plugin 架構 |
164
- | [alirezarezvani/claude-skills](https://github.com/alirezarezvani/claude-skills) | 15K+ | 313+ skill 跨 12 種 AI 編碼工具,零依賴 Python 工具 |
165
- | [coleam00/second-brain-skills](https://github.com/coleam00/second-brain-skills) | 700+ | 漸進式上下文揭露(progressive disclosure)哲學 |
166
- | [coleam00/your-claude-engineer](https://github.com/coleam00/your-claude-engineer) | 125+ | 多 agent 編排 + MCP 工具閘道整合 |
167
- | [cablate/claude-code-research](https://github.com/cablate/claude-code-research) | 130+ | Claude Code 內部機制逆向分析,75 份 deep-dive 報告 |
168
-
169
- ---
170
-
171
- ## 本地參考原始碼
172
-
173
- `ref/` 下以 `git submodule` 追蹤上述專案的原始碼,方便快速瀏覽、對照設計:
174
-
175
- ```
176
- ref/
177
- ├── everything-claude-code/ → affaan-m/everything-claude-code
178
- ├── oh-my-claudecode/ → Yeachan-Heo/oh-my-claudecode
179
- ├── wshobson-agents/ → wshobson/agents
180
- ├── claude-skills/ → alirezarezvani/claude-skills
181
- ├── second-brain-skills/ → coleam00/second-brain-skills
182
- └── claude-code-research/ → cablate/claude-code-research
183
- ```
184
-
185
- **同步到最新:**
186
- ```bash
187
- git submodule update --remote --merge
188
- ```
189
-
190
- **首次 clone 本專案:**
191
- ```bash
192
- git clone --recurse-submodules <repo-url>
193
- # 或事後初始化
194
- git submodule update --init --recursive
195
- ```
196
-
197
- ---
198
-
199
- ## 目標
200
-
201
- 1. **提煉通用流程** — 從上述專案中萃取「開發者真正需要的」工作流程模式,轉化為 opencode skill
202
- 2. **Contract-First** — 以合約文件(ADR + Spec)為源頭真相,取代一次性 handoff,支援前後端平行開發
203
- 3. **模組化設計** — 每個 skill 單一職責、可組合、可替換,避免大而全的 monolith
204
- 4. **opencode 原生** — 充分利用 opencode 的 skill/subagent/permission/MCP 機制,而非直接移植他廠格式
205
- 5. **團隊協作就緒** — 支援 adr → contract → code → review → verify → deploy 的完整開發生命週期
206
-
207
- ---
208
-
209
- ## 結構規劃
210
-
211
- ```
212
- my-opencode/
213
- ├── ref/ # 參考專案(git submodule)
214
- │ ├── everything-claude-code/
215
- │ ├── oh-my-claudecode/
216
- │ ├── wshobson-agents/
217
- │ ├── claude-skills/
218
- │ ├── second-brain-skills/
219
- │ └── claude-code-research/
220
- ├── docs/ # 探索記錄與設計文件
221
- │ ├── references/ # 各 repo 分析筆記(6 份)
222
- │ ├── patterns.md # 跨 repo 可複用模式
223
- │ └── design-decisions.md # opencode 生態取捨
224
- ├── skills/ # opencode skill(單一職責)
225
- │ ├── adr/ # [done] ADR:架構決策記錄
226
- │ ├── dev-flow/ # [done] 開發流程:contract → code → verify
227
- │ ├── pr-review/ # [done] PR 審查:5 維度分析
228
- │ ├── test-gen/ # [done] 測試生成:框架偵測 + 多語言模式
229
- │ ├── orchestrate/ # [done] 多 agent 編排:分解、平行派送、綜合
230
- │ └── docs-gen/ # [done] 文件生成:註解、API、README、ADR
231
- ├── agents/ # 組合多個 skill 的完整 agent
232
- │ ├── architect.md # [new] 架構師 agent(ADR 產生)
233
- │ ├── spec-writer.md # 規格 agent(合約文件 → docs/specs/)
234
- │ ├── executor.md # 實作 agent(讀寫)
235
- │ ├── verifier.md # 驗證 agent(唯讀+Bash)
236
- │ ├── code-reviewer.md # 程式碼審查 agent(唯讀)
237
- │ ├── test-engineer.md # 測試工程師 agent(讀寫)
238
- │ ├── tech-writer.md # 技術文件 agent(讀寫)
239
- │ ├── fullstack-dev.md # 全端開發 agent(編排三者)
240
- │ └── team-lead.md # 技術主管 agent(多 agent 交響樂指揮)
241
- ├── CONTRIBUTING.md # 貢獻指南
242
- ├── LICENSE # MIT License
243
- ├── opencode.json # opencode 整合設定:agent + command + skill 註冊
244
- ├── plugins/ # opencode plugin(保留)
245
- └── templates/ # skill / agent 建立範本
246
- ```
247
-
248
- ---
249
-
250
- ## 關鍵設計原則
251
-
252
- - **Progressive Disclosure** — 初期只載入必要 context,深入時才揭露細節
253
- - **Single Responsibility** — 每個 skill 只做一件事,做好
254
- - **Model Agnostic** — 不綁定特定模型,支援 opencode 支援的所有 LLM
255
- - **Zero Heavy Dependency** — 盡量使用 stdlib / 現有工具,避免非必要的 npm/pip 依賴
256
- - **可測試** — 每個 skill 附帶測試場景(eval set),可用 opencode eval 驗證
257
-
258
- ---
259
-
260
- ## 現狀
261
-
262
- - [x] 專案初始化
263
- - [x] ref/ 參考專案 submodule(6 個)
264
- - [x] docs/ 探索紀錄(6 份 notes + patterns.md + design-decisions.md)
265
- - [x] skill: adr(架構決策記錄,Michael Nygard 輕量格式)
266
- - [x] skill: dev-flow(開發流程,含 architecture → contract → code → verify)
267
- - [x] agents: spec-writer, executor, verifier, fullstack-dev, code-reviewer, test-engineer, team-lead, architect
268
- - [x] skill: pr-review(PR 審查,含 5 維度分析 + 安全檢查表)
269
- - [x] skill: test-gen(測試生成,含框架偵測 + 多語言測試模式)
270
- - [x] skill: orchestrate(多 agent 編排)
271
- - [x] skill: docs-gen(文件生成,含多語言註解風格 + ADR/CHANGELOG 範本)
272
- - [x] agent: tech-writer
273
- - [x] opencode.json 整合設定(含 9 個 agent + 7 個 command)
274
- - [x] CONTRIBUTING.md / LICENSE / plugins / templates
275
- - [ ] 自我驗證:用本工具跑自己的開發流程
276
-
277
- ---
278
-
279
- ## 授權
280
-
281
- MIT
113
+
114
+ 若要在 script 中直接使用環境變數,也可以:
115
+
116
+ ```bash
117
+ OPENCODE_PROVIDER_PROFILE=openai \
118
+ OPENCODE_CONFIG_CONTENT="$(node .opencode/plugins/provider-profile.mjs)" \
119
+ opencode
120
+ ```
121
+
122
+ 如果想固定專案 profile,可把 `.opencode/opencode.json` 的 plugin 設定改成 tuple:
123
+
124
+ ```json
125
+ {
126
+ "plugin": [
127
+ ["plugins/provider-profile.mjs", { "profile": "google" }]
128
+ ]
129
+ }
130
+ ```
131
+
132
+ 此 tuple 會覆寫 `OPENCODE_PROVIDER_PROFILE`。
133
+
134
+ ## Evidence-First Development
135
+
136
+ 新功能依序經過 Design Evidence、SA、SD、Frontend/Backend slices、Review 與 Verify:
137
+
138
+ ```text
139
+ Design Evidence → Business Requirements → Technical Design
140
+ ├→ Frontend slice
141
+ └→ Backend slice
142
+ ↓
143
+ Review → QA / Verify
144
+ ```
145
+
146
+ 可用的專用 commands:
147
+
148
+ ```text
149
+ /evidence # 建立 evidence-pack.md
150
+ /business-spec # 建立 SA business-requirements.md
151
+ /technical-design # 建立 SD technical/frontend/backend contracts
152
+ /frontend # 實作 frontend slice
153
+ /backend # 實作 backend slice
154
+ /verify # 執行四層 QA 與機械驗證
155
+ ```
156
+
157
+ 每個 feature 的持久文件位於 `docs/specs/<feature>/`,使用 `EVID-*`、`BR-*`、`API-*`、`DATA-*`、`AC-*`、`VER-*` 互相追蹤。Screenshot-only 或 wireframe-only 輸入必須標成 `prototype`,不可直接視為 implementation-ready。
158
+
159
+ ### 發布(維護者專用)
160
+
161
+ #### Token 設定
162
+
163
+ 發布前需要建立一個 **Access Token**(繞過 2FA):
164
+
165
+ 1. 到 https://www.npmjs.com/settings/~/tokens
166
+ 2. Generate New Token → Granular Access Token
167
+ 3. 勾選 bypass two-factor authentication
168
+ 4. 設定 Read and Write 權限
169
+ 5. 將產生的 token 寫入專案 `.npmrc`:
170
+
171
+ ```bash
172
+ echo "//registry.npmjs.org/:_authToken=npm_xxxxxxxxxxxx" > .npmrc
173
+ ```
174
+
175
+ > ⚠️ `.npmrc` 已加入 `.gitignore`,不會被 commit。
176
+
177
+ #### 發布指令
178
+
179
+ ```bash
180
+ npm publish
181
+ ```
182
+
183
+ ---
184
+
185
+ ## 靈感來源
186
+
187
+ | 專案 | Stars | 核心啟發 |
188
+ |------|-------|----------|
189
+ | [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) | 170K+ | 超大型 skill 生態系統,40+ skill 模組,跨平台設計 |
190
+ | [Yeachan-Heo/oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) | 31K+ | 多 agent 編排模式(Team / Autopilot / Pipeline),plan→prd→exec→verify→fix 流程 |
191
+ | [wshobson/agents](https://github.com/wshobson/agents) | 35K+ | 185+ 專用 agent、153 skill、單一職責 plugin 架構 |
192
+ | [alirezarezvani/claude-skills](https://github.com/alirezarezvani/claude-skills) | 15K+ | 313+ skill 跨 12 種 AI 編碼工具,零依賴 Python 工具 |
193
+ | [coleam00/second-brain-skills](https://github.com/coleam00/second-brain-skills) | 700+ | 漸進式上下文揭露(progressive disclosure)哲學 |
194
+ | [coleam00/your-claude-engineer](https://github.com/coleam00/your-claude-engineer) | 125+ | 多 agent 編排 + MCP 工具閘道整合 |
195
+ | [cablate/claude-code-research](https://github.com/cablate/claude-code-research) | 130+ | Claude Code 內部機制逆向分析,75 份 deep-dive 報告 |
196
+
197
+ ---
198
+
199
+ ## 本地參考原始碼
200
+
201
+ `ref/` 下以 `git submodule` 追蹤上述專案的原始碼,方便快速瀏覽、對照設計:
202
+
203
+ ```
204
+ ref/
205
+ ├── everything-claude-code/ → affaan-m/everything-claude-code
206
+ ├── oh-my-claudecode/ → Yeachan-Heo/oh-my-claudecode
207
+ ├── wshobson-agents/ → wshobson/agents
208
+ ├── claude-skills/ → alirezarezvani/claude-skills
209
+ ├── second-brain-skills/ → coleam00/second-brain-skills
210
+ └── claude-code-research/ → cablate/claude-code-research
211
+ ```
212
+
213
+ **同步到最新:**
214
+ ```bash
215
+ git submodule update --remote --merge
216
+ ```
217
+
218
+ **首次 clone 本專案:**
219
+ ```bash
220
+ git clone --recurse-submodules <repo-url>
221
+ # 或事後初始化
222
+ git submodule update --init --recursive
223
+ ```
224
+
225
+ ---
226
+
227
+ ## 目標
228
+
229
+ 1. **提煉通用流程** — 從上述專案中萃取「開發者真正需要的」工作流程模式,轉化為 opencode skill
230
+ 2. **Evidence-First** — 先將設計輸入整理為有來源的 Evidence Pack,再由 SA/SD 形成持久契約,支援前後端平行開發
231
+ 3. **模組化設計** — 每個 skill 單一職責、可組合、可替換,避免大而全的 monolith
232
+ 4. **opencode 原生** — 充分利用 opencode 的 skill/subagent/permission/MCP 機制,而非直接移植他廠格式
233
+ 5. **團隊協作就緒** — 支援 adr → contract → code → review → verify → deploy 的完整開發生命週期
234
+
235
+ ---
236
+
237
+ ## 結構規劃
238
+
239
+ ```
240
+ my-opencode/
241
+ ├── ref/ # 參考專案(git submodule)
242
+ │ ├── everything-claude-code/
243
+ │ ├── oh-my-claudecode/
244
+ │ ├── wshobson-agents/
245
+ │ ├── claude-skills/
246
+ │ ├── second-brain-skills/
247
+ │ └── claude-code-research/
248
+ ├── docs/ # 探索記錄與設計文件
249
+ │ ├── references/ # 各 repo 分析筆記(6 份)
250
+ │ ├── patterns.md # 跨 repo 可複用模式
251
+ │ └── design-decisions.md # opencode 生態取捨
252
+ ├── skills/ # opencode skill(單一職責)
253
+ │ ├── adr/ # [done] ADR:架構決策記錄
254
+ │ ├── dev-flow/ # [done] 開發流程:evidence → SA → SD → code → verify
255
+ │ ├── design-evidence/ # [new] Design Evidence Pack 規範
256
+ │ ├── pr-review/ # [done] PR 審查:5 維度分析
257
+ │ ├── test-gen/ # [done] 測試生成:框架偵測 + 多語言模式
258
+ │ ├── orchestrate/ # [done] 多 agent 編排:分解、平行派送、綜合
259
+ │ └── docs-gen/ # [done] 文件生成:註解、API、README、ADR
260
+ ├── agents/ # 組合多個 skill 的完整 agent
261
+ │ ├── architect.md # [new] 架構師 agent(ADR 產生)
262
+ │ ├── design-evidence.md # Design Evidence Pack 萃取
263
+ │ ├── business-analyst.md # SA 業務需求與 acceptance intent
264
+ │ ├── system-designer.md # SD 技術設計與角色契約
265
+ │ ├── frontend-dev.md # Frontend slice 實作
266
+ │ ├── backend-dev.md # Backend slice 實作
267
+ │ ├── verifier.md # 驗證 agent(唯讀+Bash)
268
+ │ ├── code-reviewer.md # 程式碼審查 agent(唯讀)
269
+ │ ├── test-engineer.md # 測試工程師 agent(讀寫)
270
+ │ ├── tech-writer.md # 技術文件 agent(讀寫)
271
+ │ └── team-lead.md # 技術主管 agent(多 agent 交響樂指揮)
272
+ ├── CONTRIBUTING.md # 貢獻指南
273
+ ├── LICENSE # MIT License
274
+ ├── opencode.json # opencode 整合設定:agent + command + skill 註冊
275
+ ├── plugins/ # opencode plugin(保留)
276
+ └── templates/ # skill / agent 建立範本
277
+ ```
278
+
279
+ ---
280
+
281
+ ## 關鍵設計原則
282
+
283
+ - **Progressive Disclosure** — 初期只載入必要 context,深入時才揭露細節
284
+ - **Single Responsibility** — 每個 skill 只做一件事,做好
285
+ - **Model Agnostic** — 不綁定特定模型,支援 opencode 支援的所有 LLM
286
+ - **Zero Heavy Dependency** — 盡量使用 stdlib / 現有工具,避免非必要的 npm/pip 依賴
287
+ - **可測試** — 每個 skill 附帶測試場景(eval set),可用 opencode eval 驗證
288
+
289
+ ---
290
+
291
+ ## 現狀
292
+
293
+ - [x] 專案初始化
294
+ - [x] ref/ 參考專案 submodule(6 個)
295
+ - [x] docs/ 探索紀錄(6 份 notes + patterns.md + design-decisions.md)
296
+ - [x] skill: adr(架構決策記錄,Michael Nygard 輕量格式)
297
+ - [x] skill: dev-flow(開發流程,含 evidence → SA → SD → role contracts → code → verify)
298
+ - [x] skill: design-evidence(設計輸入、信心與 traceability)
299
+ - [x] agents: design-evidence, business-analyst, system-designer, frontend-dev, backend-dev, verifier, code-reviewer, test-engineer, team-lead, architect
300
+ - [x] skill: pr-review(PR 審查,含 5 維度分析 + 安全檢查表)
301
+ - [x] skill: test-gen(測試生成,含框架偵測 + 多語言測試模式)
302
+ - [x] skill: orchestrate(多 agent 編排)
303
+ - [x] skill: docs-gen(文件生成,含多語言註解風格 + ADR/CHANGELOG 範本)
304
+ - [x] agent: tech-writer
305
+ - [x] opencode.json 整合設定(含 11 個 agent + 11 個 command)
306
+ - [x] CONTRIBUTING.md / LICENSE / plugins / templates
307
+ - [ ] 自我驗證:用本工具跑自己的開發流程
308
+
309
+ ---
310
+
311
+ ## 授權
312
+
313
+ MIT