opencode-starterkit 1.0.1 → 1.0.3

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 CHANGED
@@ -1,26 +1,140 @@
1
1
  # opencode-starterkit
2
2
 
3
- Bootstrap package for a two-layer OpenCode setup.
3
+ <p align="center">
4
+ Install a shared OpenCode baseline globally, then create a thin per-project `.opencode/` overlay with project-local memory.
5
+ </p>
4
6
 
5
- ## Install model
7
+ <p align="center">
8
+ <a href="#english">English</a> | <a href="#tiếng-việt">Tiếng Việt</a>
9
+ </p>
6
10
 
7
- ### 1. Global baseline
11
+ ---
12
+
13
+ ## English
14
+
15
+ ### What this package actually installs
16
+
17
+ `opencode-starterkit` is a **bootstrap package for OpenCode**.
18
+
19
+ It installs OpenCode in **two layers**:
20
+
21
+ 1. **Global baseline** — installed once into your real OpenCode global surface
22
+ 2. **Project overlay** — installed into each repo you want to work on
23
+
24
+ This package exists so you do **not** need to copy a huge `.opencode/` directory into every repository.
25
+
26
+ ---
27
+
28
+ ### Global install: what it adds and why
29
+
30
+ Run:
8
31
 
9
32
  ```bash
10
33
  npx opencode-starterkit install
11
34
  ```
12
35
 
13
- This installs shared baseline directly into the real OpenCode global surface under `~/.config/opencode` and exposes the `ocp` project command.
36
+ This command is intended to install or sync the shared baseline into:
37
+
38
+ - `~/.config/opencode/agents/`
39
+ - `~/.config/opencode/skills/`
40
+ - `~/.config/opencode/plugin/`
41
+ - `~/.config/opencode/command/`
42
+ - `~/.config/opencode/tool/`
43
+ - `~/.config/opencode/opencode.json`
44
+
45
+ #### What the global install actually puts into OpenCode
46
+
47
+ ##### 1) Shared agents
48
+ Installed into `~/.config/opencode/agents/`.
49
+
50
+ Current baseline agents include:
51
+ - `build`
52
+ - `review`
53
+ - `plan`
54
+ - `explore`
55
+ - `general`
56
+ - `scout`
57
+ - `vision`
58
+ - `painter`
59
+ - `runner`
60
+
61
+ **Purpose:** provide reusable agent roles and default model behavior across repositories.
62
+
63
+ ##### 2) Shared commands
64
+ Installed into `~/.config/opencode/command/`.
65
+
66
+ Current baseline commands include:
67
+ - `init`, `init-user`, `init-context`
68
+ - `plan`, `start`, `ship`, `verify`
69
+ - `research`, `review-codebase`, `handoff`, `resume`, `status`
70
+ - `ui-review`, `ui-slop-check`, `pr`, `design`, `create`
71
+
72
+ **Purpose:** give every repo the same workflow/runbook command surface instead of re-copying command markdown into each project.
73
+
74
+ ##### 3) Shared plugins
75
+ Installed into `~/.config/opencode/plugin/` and activated through global config resolution.
76
+
77
+ Current baseline plugins include:
78
+ - `memory.ts` → project memory runtime and prompt injection pipeline
79
+ - `sessions.ts` → session search/read tooling
80
+ - `copilot-auth.ts` → provider/auth integration helpers
81
+ - `skill-mcp.ts` → skill-scoped MCP bridge
82
+
83
+ **Purpose:** extend OpenCode globally with memory, session, auth, and MCP capabilities.
84
+
85
+ ##### 4) Shared skills
86
+ Installed into `~/.config/opencode/skills/`.
87
+
88
+ The baseline currently ships grouped skill families such as:
89
+ - **planning & execution**: `writing-plans`, `executing-plans`, `development-lifecycle`, `index-knowledge`
90
+ - **verification & quality**: `verification-before-completion`, `test-driven-development`, `testing-anti-patterns`, `requesting-code-review`, `receiving-code-review`
91
+ - **debugging & investigation**: `systematic-debugging`, `root-cause-tracing`, `deep-research`, `code-navigation`
92
+ - **UI / frontend**: `frontend-design`, `mockup-to-code`, `design-system-audit`, `visual-analysis`, `ui-ux-research`
93
+ - **orchestration & coordination**: `beads`, `beads-bridge`, `swarm-coordination`, `subagent-driven-development`
94
+ - **platform / infra / provider skills**: `cloudflare`, `supabase`, `jira`, `playwright`, `playwriter`, `tilth-cli`
14
95
 
15
- ### 2. Thin project overlay
96
+ **Purpose:** give every repo the same shared operating skills without duplicating them per-project.
97
+
98
+ ##### 5) Shared tools
99
+ Installed into `~/.config/opencode/tool/`.
100
+
101
+ Current baseline tools include:
102
+ - `context7.ts`
103
+ - `grepsearch.ts`
104
+
105
+ **Purpose:** bundle shared helper tools used by the baseline workflows.
106
+
107
+ ##### 6) Global config merge
108
+ Merged additively into `~/.config/opencode/opencode.json`.
109
+
110
+ This merge is intended to add:
111
+ - agent definitions and model defaults
112
+ - plugin entries
113
+ - MCP entries
114
+ - other baseline config blocks
115
+
116
+ **Purpose:** extend the user's global OpenCode config without blindly overwriting existing config.
117
+
118
+ #### Why this matters
119
+
120
+ After the global install, OpenCode should already know about the shared baseline:
121
+ - skills become available globally
122
+ - shared plugins are active
123
+ - default agent/model behavior is available without re-copying files into every repo
124
+
125
+ ---
126
+
127
+ ### Project install: what it creates and why
128
+
129
+ Inside a project repo, run:
16
130
 
17
131
  ```bash
18
132
  ocp install
19
133
  ```
20
134
 
21
- This creates a thin `.opencode/` overlay for the current repo and bootstraps a per-project `memory.db*` runtime state.
135
+ This command creates a **thin `.opencode/` overlay** for the current repo.
22
136
 
23
- ## Project target shape
137
+ #### Project files created
24
138
 
25
139
  ```text
26
140
  .opencode/
@@ -38,10 +152,370 @@ This creates a thin `.opencode/` overlay for the current repo and bootstraps a p
38
152
  gotchas.md
39
153
  ```
40
154
 
41
- ## Current status
155
+ #### What each project-local piece does
156
+
157
+ - **`.opencode/opencode.json`**
158
+ - thin repo-specific config
159
+ - points OpenCode at the repo's local project memory files
160
+ - may carry project-specific model/MCP overrides later
161
+
162
+ - **`.opencode/memory/project/*.md`**
163
+ - human-readable project context that gets injected via `instructions[]`
164
+ - typical roles:
165
+ - `project.md` → project purpose and goals
166
+ - `state.md` → current working state
167
+ - `roadmap.md` → milestones / phases
168
+ - `tech-stack.md` → stack and technical constraints
169
+ - `user.md` → project/user preferences
170
+ - `gotchas.md` → repo-specific footguns and warnings
171
+
172
+ - **`.opencode/memory.db*`**
173
+ - **per-project runtime memory database**
174
+ - stores operational memory for the OpenCode memory plugin
175
+ - this is intentionally project-local, not global
176
+ - examples of stored data include temporal messages, distillations, observations, and pipeline state
177
+
178
+ #### Why this matters
179
+
180
+ Each project keeps its own:
181
+ - project context
182
+ - runtime memory
183
+ - repo-specific behavior
184
+
185
+ while still reusing the heavy shared baseline from the global layer.
186
+
187
+ ---
188
+
189
+ ### Architecture summary
190
+
191
+ - **Global baseline** = shared OpenCode operating system
192
+ - **Project overlay** = thin repo-specific wrapper
193
+ - **Project memory DB** = local runtime state per repo
194
+
195
+ That means:
196
+ - shared skills/plugins/agents/commands/tools are installed once
197
+ - each repo still has its own memory and context
198
+
199
+ ---
200
+
201
+ ### Commands
202
+
203
+ #### Global bootstrap
204
+
205
+ ```bash
206
+ npx opencode-starterkit install
207
+ ```
208
+
209
+ #### Project bootstrap
210
+
211
+ ```bash
212
+ ocp install
213
+ ```
214
+
215
+ #### Scriptable project bootstrap
216
+
217
+ ```bash
218
+ ocp install --action "Initialize project" --preset recommended --yes
219
+ ```
220
+
221
+ ---
222
+
223
+ ### What is bundled in this repo
224
+
225
+ This package currently vendors a baseline derived from VAT under:
226
+
227
+ ```text
228
+ baseline/
229
+ agent/
230
+ command/
231
+ plugin/
232
+ skill/
233
+ tool/
234
+ opencode.json
235
+ ...
236
+ ```
237
+
238
+ It also ships:
239
+ - CLI entrypoints in `bin/`
240
+ - installer logic in `src/`
241
+ - migration/audit notes in `docs/reports/`
242
+
243
+ ---
244
+
245
+ ### Current status
246
+
247
+ Working now:
248
+ - baseline vendored into the package
249
+ - global sync into real OpenCode paths
250
+ - thin project overlay creation
251
+ - per-project `memory.db*` bootstrap
252
+ - VAT canary migration path validated locally
253
+
254
+ Still being improved:
255
+ - richer interactive wizard UX
256
+ - more menu actions beyond `Initialize project`
257
+ - stronger config merge policy/hardening
258
+ - broader canary coverage across more repos
259
+
260
+ ---
261
+
262
+ ### Who should use this
263
+
264
+ Use this if you want:
265
+ - one shared OpenCode baseline across many repositories
266
+ - smaller `.opencode/` folders in each repo
267
+ - project-local memory and context preserved per repo
268
+
269
+ ---
270
+
271
+ ## Tiếng Việt
272
+
273
+ ### Package này thực sự cài cái gì
274
+
275
+ `opencode-starterkit` là package bootstrap cho OpenCode theo mô hình **2 tầng**:
276
+
277
+ 1. **Tầng global** — cài một lần vào đúng bề mặt global của OpenCode
278
+ 2. **Tầng project** — cài lớp mỏng cho từng repo cụ thể
279
+
280
+ Mục tiêu là không phải copy nguyên một thư mục `.opencode/` nặng vào mọi project nữa.
281
+
282
+ ---
283
+
284
+ ### Global install: nó thêm những gì và để làm gì
285
+
286
+ Chạy:
287
+
288
+ ```bash
289
+ npx opencode-starterkit install
290
+ ```
291
+
292
+ Lệnh này nhằm sync baseline dùng chung vào:
293
+
294
+ - `~/.config/opencode/agents/`
295
+ - `~/.config/opencode/skills/`
296
+ - `~/.config/opencode/plugin/`
297
+ - `~/.config/opencode/command/`
298
+ - `~/.config/opencode/tool/`
299
+ - `~/.config/opencode/opencode.json`
300
+
301
+ #### Những gì tầng global thực sự cài vào OpenCode
302
+
303
+ ##### 1) Agents dùng chung
304
+ Cài vào `~/.config/opencode/agents/`.
305
+
306
+ Baseline hiện có các agent như:
307
+ - `build`
308
+ - `review`
309
+ - `plan`
310
+ - `explore`
311
+ - `general`
312
+ - `scout`
313
+ - `vision`
314
+ - `painter`
315
+ - `runner`
316
+
317
+ **Tác dụng:** cung cấp role/model mặc định dùng chung cho nhiều repo.
318
+
319
+ ##### 2) Commands dùng chung
320
+ Cài vào `~/.config/opencode/command/`.
321
+
322
+ Baseline hiện có các command như:
323
+ - `init`, `init-user`, `init-context`
324
+ - `plan`, `start`, `ship`, `verify`
325
+ - `research`, `review-codebase`, `handoff`, `resume`, `status`
326
+ - `ui-review`, `ui-slop-check`, `pr`, `design`, `create`
327
+
328
+ **Tác dụng:** đưa các command workflow/runbook dùng chung lên global để repo nào cũng gọi được.
329
+
330
+ ##### 3) Plugins dùng chung
331
+ Cài vào `~/.config/opencode/plugin/` và được runtime activate qua global config resolution.
332
+
333
+ Baseline hiện có các plugin như:
334
+ - `opencode-agent-skills` → dynamic skill discovery / selection / loading
335
+ - `memory.ts` → memory runtime và prompt injection
336
+ - `sessions.ts` → đọc/tìm session
337
+ - `copilot-auth.ts` → auth/provider integration
338
+ - `skill-mcp.ts` → MCP bridge cho skill
339
+
340
+ **Tác dụng:** mở rộng capability chung cho OpenCode ở tầng global, đặc biệt là giúp agent discover và load skill phù hợp khi cần.
341
+
342
+ ##### 4) Skills dùng chung
343
+ Cài vào `~/.config/opencode/skills/`.
344
+
345
+ Baseline hiện có các nhóm skill lớn như:
346
+ - **planning & execution**: `writing-plans`, `executing-plans`, `development-lifecycle`, `index-knowledge`
347
+ - **verification & quality**: `verification-before-completion`, `test-driven-development`, `testing-anti-patterns`, `requesting-code-review`, `receiving-code-review`
348
+ - **debugging & investigation**: `systematic-debugging`, `root-cause-tracing`, `deep-research`, `code-navigation`
349
+ - **UI / frontend**: `frontend-design`, `mockup-to-code`, `design-system-audit`, `visual-analysis`, `ui-ux-research`
350
+ - **orchestration & coordination**: `beads`, `beads-bridge`, `swarm-coordination`, `subagent-driven-development`
351
+ - **platform / provider skills**: `cloudflare`, `supabase`, `jira`, `playwright`, `playwriter`, `tilth-cli`
352
+
353
+ **Tác dụng:** mọi repo dùng chung cùng một bộ operating skills, không phải copy vào từng project.
354
+
355
+ ##### 5) Tools dùng chung
356
+ Cài vào `~/.config/opencode/tool/`.
357
+
358
+ Baseline hiện có:
359
+ - `context7.ts`
360
+ - `grepsearch.ts`
361
+
362
+ **Tác dụng:** helper tool chung cho các workflow/search/context surface.
363
+
364
+ ##### 6) Global config merge
365
+ Merge-additive vào `~/.config/opencode/opencode.json`.
366
+
367
+ Phần merge này nhằm bổ sung:
368
+ - agent definitions và model defaults
369
+ - plugin entries
370
+ - MCP entries
371
+ - config block nền tảng khác
372
+
373
+ **Tác dụng:** thêm baseline vào global config hiện có mà không đè bừa config người dùng.
374
+
375
+ #### Tác dụng của tầng global
376
+
377
+ Sau khi cài global, OpenCode sẽ dùng được baseline chung:
378
+ - skill xuất hiện ở global
379
+ - plugin chung được activate
380
+ - agent/model baseline có sẵn cho nhiều repo khác nhau
381
+
382
+ ---
383
+
384
+ ### Local project install: nó tạo gì và để làm gì
385
+
386
+ Trong repo cần dùng, chạy:
387
+
388
+ ```bash
389
+ ocp install
390
+ ```
391
+
392
+ Lệnh này tạo `.opencode/` mỏng cho repo hiện tại.
393
+
394
+ #### Những file được tạo
395
+
396
+ ```text
397
+ .opencode/
398
+ opencode.json
399
+ memory.db
400
+ memory.db-shm
401
+ memory.db-wal
402
+ memory/
403
+ project/
404
+ project.md
405
+ state.md
406
+ roadmap.md
407
+ tech-stack.md
408
+ user.md
409
+ gotchas.md
410
+ ```
411
+
412
+ #### Từng phần có tác dụng gì
413
+
414
+ - **`.opencode/opencode.json`**
415
+ - config mỏng riêng cho repo
416
+ - trỏ OpenCode vào project memory của repo này
417
+ - sau này có thể chứa override riêng của project
418
+
419
+ - **`.opencode/memory/project/*.md`**
420
+ - là project context file để inject vào prompt
421
+ - ví dụ:
422
+ - `project.md` → project này làm gì
423
+ - `state.md` → trạng thái hiện tại
424
+ - `roadmap.md` → roadmap/phase
425
+ - `tech-stack.md` → stack và constraint kỹ thuật
426
+ - `user.md` → preference/quy ước riêng
427
+ - `gotchas.md` → footguns của repo
428
+
429
+ - **`.opencode/memory.db*`**
430
+ - là **memory runtime riêng của từng project**
431
+ - OpenCode memory plugin dùng DB này để lưu:
432
+ - temporal messages
433
+ - distillations
434
+ - observations
435
+ - pipeline state
436
+ - phần này cố ý để theo từng repo, không global hóa
437
+
438
+ #### Tác dụng của tầng project
439
+
440
+ Mỗi repo giữ được:
441
+ - context riêng
442
+ - memory runtime riêng
443
+ - override riêng nếu cần
444
+
445
+ trong khi vẫn dùng lại baseline nặng từ tầng global.
446
+
447
+ ---
448
+
449
+ ### Tóm tắt kiến trúc
450
+
451
+ - **Global baseline** = OpenCode operating system dùng chung
452
+ - **Project overlay** = lớp mỏng riêng từng repo
453
+ - **Project memory DB** = runtime memory riêng theo repo
454
+
455
+ Tức là:
456
+ - phần nặng cài một lần
457
+ - phần riêng của project vẫn tách riêng và giữ đúng ranh giới
458
+
459
+ ---
460
+
461
+ ### Lệnh hiện tại
462
+
463
+ #### Cài tầng global
464
+
465
+ ```bash
466
+ npx opencode-starterkit install
467
+ ```
468
+
469
+ #### Cài tầng project
470
+
471
+ ```bash
472
+ ocp install
473
+ ```
474
+
475
+ #### Cài kiểu scriptable
476
+
477
+ ```bash
478
+ ocp install --action "Initialize project" --preset recommended --yes
479
+ ```
480
+
481
+ ---
482
+
483
+ ### Repo này hiện chứa gì
484
+
485
+ Repo package hiện đang vendor baseline từ VAT tại:
486
+
487
+ ```text
488
+ baseline/
489
+ agent/
490
+ command/
491
+ plugin/
492
+ skill/
493
+ tool/
494
+ opencode.json
495
+ ...
496
+ ```
497
+
498
+ Ngoài ra còn có:
499
+ - CLI trong `bin/`
500
+ - installer logic trong `src/`
501
+ - tài liệu audit/migration trong `docs/reports/`
502
+
503
+ ---
504
+
505
+ ### Trạng thái hiện tại
506
+
507
+ Đã chạy được:
508
+ - sync baseline global vào path OpenCode thật
509
+ - tạo thin overlay cho project
510
+ - bootstrap `memory.db*` per-project
511
+ - canary local với VAT
42
512
 
43
- Functional bootstrap in progress:
44
- - package includes a vendored baseline from VAT in `baseline/`
45
- - `opencode-starterkit install` syncs baseline into global OpenCode paths
46
- - `ocp install` creates thin project overlay and bootstraps `memory.db*`
47
- - remaining work: safer global config merge + wizard polish + canary on more repos
513
+ Đang tiếp tục hoàn thiện:
514
+ - wizard đẹp hơn
515
+ - thêm action ngoài `Initialize project`
516
+ - harden merge config global
517
+ - mở rộng canary sang nhiều repo hơn
518
+ hơn
519
+ - thêm action ngoài `Initialize project`
520
+ - harden merge config global
521
+ - mở rộng canary sang nhiều repo hơn
@@ -151,6 +151,7 @@
151
151
  }
152
152
  },
153
153
  "plugin": [
154
+ "opencode-agent-skills",
154
155
  "@tarquinen/opencode-dcp@latest",
155
156
  "@franlol/opencode-md-table-formatter@0.0.3",
156
157
  "openslimedit@latest"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-starterkit",
3
- "version": "1.0.1",
3
+ "version": "1.0.3",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Global baseline + thin project overlay installer for OpenCode.",