opencode-starterkit 1.0.1 → 1.0.2

package/README.md

@@ -1,26 +1,140 @@
 # opencode-starterkit
 
-Bootstrap package for a two-layer OpenCode setup.
+<p align="center">
+  Install a shared OpenCode baseline globally, then create a thin per-project `.opencode/` overlay with project-local memory.
+</p>
 
-## Install model
+<p align="center">
+  <a href="#english">English</a> | <a href="#tiếng-việt">Tiếng Việt</a>
+</p>
 
-### 1. Global baseline
+---
+
+## English
+
+### What this package actually installs
+
+`opencode-starterkit` is a **bootstrap package for OpenCode**.
+
+It installs OpenCode in **two layers**:
+
+1. **Global baseline** — installed once into your real OpenCode global surface
+2. **Project overlay** — installed into each repo you want to work on
+
+This package exists so you do **not** need to copy a huge `.opencode/` directory into every repository.
+
+---
+
+### Global install: what it adds and why
+
+Run:
 
 ```bash
 npx opencode-starterkit install
 ```
 
-This installs shared baseline directly into the real OpenCode global surface under `~/.config/opencode` and exposes the `ocp` project command.
+This command is intended to install or sync the shared baseline into:
+
+- `~/.config/opencode/agents/`
+- `~/.config/opencode/skills/`
+- `~/.config/opencode/plugin/`
+- `~/.config/opencode/command/`
+- `~/.config/opencode/tool/`
+- `~/.config/opencode/opencode.json`
+
+#### What the global install actually puts into OpenCode
+
+##### 1) Shared agents
+Installed into `~/.config/opencode/agents/`.
+
+Current baseline agents include:
+- `build`
+- `review`
+- `plan`
+- `explore`
+- `general`
+- `scout`
+- `vision`
+- `painter`
+- `runner`
+
+**Purpose:** provide reusable agent roles and default model behavior across repositories.
+
+##### 2) Shared commands
+Installed into `~/.config/opencode/command/`.
+
+Current baseline commands include:
+- `init`, `init-user`, `init-context`
+- `plan`, `start`, `ship`, `verify`
+- `research`, `review-codebase`, `handoff`, `resume`, `status`
+- `ui-review`, `ui-slop-check`, `pr`, `design`, `create`
+
+**Purpose:** give every repo the same workflow/runbook command surface instead of re-copying command markdown into each project.
+
+##### 3) Shared plugins
+Installed into `~/.config/opencode/plugin/` and activated through global config resolution.
+
+Current baseline plugins include:
+- `memory.ts` → project memory runtime and prompt injection pipeline
+- `sessions.ts` → session search/read tooling
+- `copilot-auth.ts` → provider/auth integration helpers
+- `skill-mcp.ts` → skill-scoped MCP bridge
+
+**Purpose:** extend OpenCode globally with memory, session, auth, and MCP capabilities.
+
+##### 4) Shared skills
+Installed into `~/.config/opencode/skills/`.
+
+The baseline currently ships grouped skill families such as:
+- **planning & execution**: `writing-plans`, `executing-plans`, `development-lifecycle`, `index-knowledge`
+- **verification & quality**: `verification-before-completion`, `test-driven-development`, `testing-anti-patterns`, `requesting-code-review`, `receiving-code-review`
+- **debugging & investigation**: `systematic-debugging`, `root-cause-tracing`, `deep-research`, `code-navigation`
+- **UI / frontend**: `frontend-design`, `mockup-to-code`, `design-system-audit`, `visual-analysis`, `ui-ux-research`
+- **orchestration & coordination**: `beads`, `beads-bridge`, `swarm-coordination`, `subagent-driven-development`
+- **platform / infra / provider skills**: `cloudflare`, `supabase`, `jira`, `playwright`, `playwriter`, `tilth-cli`
 
-### 2. Thin project overlay
+**Purpose:** give every repo the same shared operating skills without duplicating them per-project.
+
+##### 5) Shared tools
+Installed into `~/.config/opencode/tool/`.
+
+Current baseline tools include:
+- `context7.ts`
+- `grepsearch.ts`
+
+**Purpose:** bundle shared helper tools used by the baseline workflows.
+
+##### 6) Global config merge
+Merged additively into `~/.config/opencode/opencode.json`.
+
+This merge is intended to add:
+- agent definitions and model defaults
+- plugin entries
+- MCP entries
+- other baseline config blocks
+
+**Purpose:** extend the user's global OpenCode config without blindly overwriting existing config.
+
+#### Why this matters
+
+After the global install, OpenCode should already know about the shared baseline:
+- skills become available globally
+- shared plugins are active
+- default agent/model behavior is available without re-copying files into every repo
+
+---
+
+### Project install: what it creates and why
+
+Inside a project repo, run:
 
 ```bash
 ocp install
 ```
 
-This creates a thin `.opencode/` overlay for the current repo and bootstraps a per-project `memory.db*` runtime state.
+This command creates a **thin `.opencode/` overlay** for the current repo.
 
-## Project target shape
+#### Project files created
 
 ```text
 .opencode/
@@ -38,10 +152,365 @@ This creates a thin `.opencode/` overlay for the current repo and bootstraps a p
       gotchas.md
 ```
 
-## Current status
+#### What each project-local piece does
+
+- **`.opencode/opencode.json`**
+  - thin repo-specific config
+  - points OpenCode at the repo's local project memory files
+  - may carry project-specific model/MCP overrides later
+
+- **`.opencode/memory/project/*.md`**
+  - human-readable project context that gets injected via `instructions[]`
+  - typical roles:
+    - `project.md` → project purpose and goals
+    - `state.md` → current working state
+    - `roadmap.md` → milestones / phases
+    - `tech-stack.md` → stack and technical constraints
+    - `user.md` → project/user preferences
+    - `gotchas.md` → repo-specific footguns and warnings
+
+- **`.opencode/memory.db*`**
+  - **per-project runtime memory database**
+  - stores operational memory for the OpenCode memory plugin
+  - this is intentionally project-local, not global
+  - examples of stored data include temporal messages, distillations, observations, and pipeline state
+
+#### Why this matters
+
+Each project keeps its own:
+- project context
+- runtime memory
+- repo-specific behavior
+
+while still reusing the heavy shared baseline from the global layer.
+
+---
+
+### Architecture summary
+
+- **Global baseline** = shared OpenCode operating system
+- **Project overlay** = thin repo-specific wrapper
+- **Project memory DB** = local runtime state per repo
+
+That means:
+- shared skills/plugins/agents/commands/tools are installed once
+- each repo still has its own memory and context
+
+---
+
+### Commands
+
+#### Global bootstrap
+
+```bash
+npx opencode-starterkit install
+```
+
+#### Project bootstrap
+
+```bash
+ocp install
+```
+
+#### Scriptable project bootstrap
+
+```bash
+ocp install --action "Initialize project" --preset recommended --yes
+```
+
+---
+
+### What is bundled in this repo
+
+This package currently vendors a baseline derived from VAT under:
+
+```text
+baseline/
+  agent/
+  command/
+  plugin/
+  skill/
+  tool/
+  opencode.json
+  ...
+```
+
+It also ships:
+- CLI entrypoints in `bin/`
+- installer logic in `src/`
+- migration/audit notes in `docs/reports/`
+
+---
+
+### Current status
+
+Working now:
+- baseline vendored into the package
+- global sync into real OpenCode paths
+- thin project overlay creation
+- per-project `memory.db*` bootstrap
+- VAT canary migration path validated locally
+
+Still being improved:
+- richer interactive wizard UX
+- more menu actions beyond `Initialize project`
+- stronger config merge policy/hardening
+- broader canary coverage across more repos
+
+---
+
+### Who should use this
+
+Use this if you want:
+- one shared OpenCode baseline across many repositories
+- smaller `.opencode/` folders in each repo
+- project-local memory and context preserved per repo
+
+---
+
+## Tiếng Việt
+
+### Package này thực sự cài cái gì
+
+`opencode-starterkit` là package bootstrap cho OpenCode theo mô hình **2 tầng**:
+
+1. **Tầng global** — cài một lần vào đúng bề mặt global của OpenCode
+2. **Tầng project** — cài lớp mỏng cho từng repo cụ thể
+
+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.
+
+---
+
+### Global install: nó thêm những gì và để làm gì
+
+Chạy:
+
+```bash
+npx opencode-starterkit install
+```
+
+Lệnh này nhằm sync baseline dùng chung vào:
+
+- `~/.config/opencode/agents/`
+- `~/.config/opencode/skills/`
+- `~/.config/opencode/plugin/`
+- `~/.config/opencode/command/`
+- `~/.config/opencode/tool/`
+- `~/.config/opencode/opencode.json`
+
+#### Những gì tầng global thực sự cài vào OpenCode
+
+##### 1) Agents dùng chung
+Cài vào `~/.config/opencode/agents/`.
+
+Baseline hiện có các agent như:
+- `build`
+- `review`
+- `plan`
+- `explore`
+- `general`
+- `scout`
+- `vision`
+- `painter`
+- `runner`
+
+**Tác dụng:** cung cấp role/model mặc định dùng chung cho nhiều repo.
+
+##### 2) Commands dùng chung
+Cài vào `~/.config/opencode/command/`.
+
+Baseline hiện có các command như:
+- `init`, `init-user`, `init-context`
+- `plan`, `start`, `ship`, `verify`
+- `research`, `review-codebase`, `handoff`, `resume`, `status`
+- `ui-review`, `ui-slop-check`, `pr`, `design`, `create`
+
+**Tác dụng:** đưa các command workflow/runbook dùng chung lên global để repo nào cũng gọi được.
+
+##### 3) Plugins dùng chung
+Cài vào `~/.config/opencode/plugin/` và được runtime activate qua global config resolution.
+
+Baseline hiện có các plugin như:
+- `memory.ts` → memory runtime và prompt injection
+- `sessions.ts` → đọc/tìm session
+- `copilot-auth.ts` → auth/provider integration
+- `skill-mcp.ts` → MCP bridge cho skill
+
+**Tác dụng:** mở rộng capability chung cho OpenCode ở tầng global.
+
+##### 4) Skills dùng chung
+Cài vào `~/.config/opencode/skills/`.
+
+Baseline hiện có các nhóm skill lớn như:
+- **planning & execution**: `writing-plans`, `executing-plans`, `development-lifecycle`, `index-knowledge`
+- **verification & quality**: `verification-before-completion`, `test-driven-development`, `testing-anti-patterns`, `requesting-code-review`, `receiving-code-review`
+- **debugging & investigation**: `systematic-debugging`, `root-cause-tracing`, `deep-research`, `code-navigation`
+- **UI / frontend**: `frontend-design`, `mockup-to-code`, `design-system-audit`, `visual-analysis`, `ui-ux-research`
+- **orchestration & coordination**: `beads`, `beads-bridge`, `swarm-coordination`, `subagent-driven-development`
+- **platform / provider skills**: `cloudflare`, `supabase`, `jira`, `playwright`, `playwriter`, `tilth-cli`
+
+**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.
+
+##### 5) Tools dùng chung
+Cài vào `~/.config/opencode/tool/`.
+
+Baseline hiện có:
+- `context7.ts`
+- `grepsearch.ts`
+
+**Tác dụng:** helper tool chung cho các workflow/search/context surface.
+
+##### 6) Global config merge
+Merge-additive vào `~/.config/opencode/opencode.json`.
+
+Phần merge này nhằm bổ sung:
+- agent definitions và model defaults
+- plugin entries
+- MCP entries
+- config block nền tảng khác
+
+**Tác dụng:** thêm baseline vào global config hiện có mà không đè bừa config người dùng.
+
+#### Tác dụng của tầng global
+
+Sau khi cài global, OpenCode sẽ dùng được baseline chung:
+- skill xuất hiện ở global
+- plugin chung được activate
+- agent/model baseline có sẵn cho nhiều repo khác nhau
+
+---
+
+### Local project install: nó tạo gì và để làm gì
+
+Trong repo cần dùng, chạy:
+
+```bash
+ocp install
+```
+
+Lệnh này tạo `.opencode/` mỏng cho repo hiện tại.
+
+#### Những file được tạo
+
+```text
+.opencode/
+  opencode.json
+  memory.db
+  memory.db-shm
+  memory.db-wal
+  memory/
+    project/
+      project.md
+      state.md
+      roadmap.md
+      tech-stack.md
+      user.md
+      gotchas.md
+```
+
+#### Từng phần có tác dụng gì
+
+- **`.opencode/opencode.json`**
+  - config mỏng riêng cho repo
+  - trỏ OpenCode vào project memory của repo này
+  - sau này có thể chứa override riêng của project
+
+- **`.opencode/memory/project/*.md`**
+  - là project context file để inject vào prompt
+  - ví dụ:
+    - `project.md` → project này làm gì
+    - `state.md` → trạng thái hiện tại
+    - `roadmap.md` → roadmap/phase
+    - `tech-stack.md` → stack và constraint kỹ thuật
+    - `user.md` → preference/quy ước riêng
+    - `gotchas.md` → footguns của repo
+
+- **`.opencode/memory.db*`**
+  - là **memory runtime riêng của từng project**
+  - OpenCode memory plugin dùng DB này để lưu:
+    - temporal messages
+    - distillations
+    - observations
+    - pipeline state
+  - phần này cố ý để theo từng repo, không global hóa
+
+#### Tác dụng của tầng project
+
+Mỗi repo giữ được:
+- context riêng
+- memory runtime riêng
+- override riêng nếu cần
+
+trong khi vẫn dùng lại baseline nặng từ tầng global.
+
+---
+
+### Tóm tắt kiến trúc
+
+- **Global baseline** = OpenCode operating system dùng chung
+- **Project overlay** = lớp mỏng riêng từng repo
+- **Project memory DB** = runtime memory riêng theo repo
+
+Tức là:
+- phần nặng cài một lần
+- phần riêng của project vẫn tách riêng và giữ đúng ranh giới
+
+---
+
+### Lệnh hiện tại
+
+#### Cài tầng global
+
+```bash
+npx opencode-starterkit install
+```
+
+#### Cài tầng project
+
+```bash
+ocp install
+```
+
+#### Cài kiểu scriptable
+
+```bash
+ocp install --action "Initialize project" --preset recommended --yes
+```
+
+---
+
+### Repo này hiện chứa gì
+
+Repo package hiện đang vendor baseline từ VAT tại:
+
+```text
+baseline/
+  agent/
+  command/
+  plugin/
+  skill/
+  tool/
+  opencode.json
+  ...
+```
+
+Ngoài ra còn có:
+- CLI trong `bin/`
+- installer logic trong `src/`
+- tài liệu audit/migration trong `docs/reports/`
+
+---
+
+### Trạng thái hiện tại
+
+Đã chạy được:
+- sync baseline global vào path OpenCode thật
+- tạo thin overlay cho project
+- bootstrap `memory.db*` per-project
+- canary local với VAT
 
-Functional bootstrap in progress:
-- package includes a vendored baseline from VAT in `baseline/`
-- `opencode-starterkit install` syncs baseline into global OpenCode paths
-- `ocp install` creates thin project overlay and bootstraps `memory.db*`
-- remaining work: safer global config merge + wizard polish + canary on more repos
+Đang tiếp tục hoàn thiện:
+- wizard đẹp hơn
+- thêm action ngoài `Initialize project`
+- harden merge config global
+- mở rộng canary sang nhiều repo hơn

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-starterkit",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "private": false,
   "type": "module",
   "description": "Global baseline + thin project overlay installer for OpenCode.",