opencode-starterkit

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:

npx opencode-starterkit

You can still call the explicit form if you want:

npx opencode-starterkit

This command installs the starterkit package source into:

• ~/.local/share/opencode/starterkit/

Then it syncs the active OpenCode runtime into:

• ~/.config/opencode/agents/
• ~/.config/opencode/skills/
• ~/.config/opencode/plugin/
• ~/.config/opencode/command/
• ~/.config/opencode/tool/
• ~/.config/opencode/opencode.json

Operational backups/manifests are stored under:

• ~/.local/state/opencode/

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

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:

• the installed package source lives at ~/.local/share/opencode/starterkit/
• active runtime config remains under ~/.config/opencode/
• reusable CLI shims are installed into ~/.local/bin/:
  • opencode-starterkit
  • opcs
• 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:

opcs install

This command creates a thin .opencode/ overlay for the current repo.

Project files created

.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

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

npx opencode-starterkit

You can still call the explicit form if you want:

npx opencode-starterkit

Project bootstrap

opcs install

Scriptable project bootstrap

opcs install --action "Initialize project" --preset recommended --yes

What is bundled in this repo

This package currently vendors a baseline derived from VAT under:

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/

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:

npx opencode-starterkit

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ư:

• opencode-agent-skills → dynamic skill discovery / selection / loading
• 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, đặc biệt là giúp agent discover và load skill phù hợp khi cần.

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:

opcs install

Lệnh này tạo .opencode/ mỏng cho repo hiện tại.

Những file được tạo

.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

npx opencode-starterkit

Cài tầng project

opcs install

Cài kiểu scriptable

opcs 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:

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/