🧠 OpenCode Bootstrap

Production-ready bootstrap for a stronger global OpenCode setup plus project-specific intelligence.

What it gives you

• stronger global OpenCode defaults for daily work, planning, verification, debugging, and review;
• project bootstrap via /ocb-project-init that turns repo evidence + a short interview into project-specific rules;
• explicit project artifacts under .opencode/project/ instead of “magic in chat history”;
• bounded workflow commands: explore, grounded analysis, plan, implement, verify, fix, evolve, and loop;
• a bundled bundle-maintenance skill for safely changing shipped artifacts, manifests, checksums, and smoke-test flows;
• GPT-first orchestration with explicit Anthropic routing for code generation and high-risk final review.

Supported platforms

• Linux
• macOS
• WSL2

Not supported:

• native Windows

Clipboard helpers:

• Linux X11: xclip
• Linux Wayland: wl-clipboard
• macOS: pngpaste when Homebrew is available

What gets installed

Global OpenCode bundle under ~/.config/opencode/:

• AGENTS.md
• opencode.json
• commands/*.md
• prompts/*.md
• agents/*.md
• skills/*/SKILL.md
• tools/*.ts

Core agents include:

• primary: fast, build, plan, deep
• workflow: project-bootstrapper, grounded-researcher, loop-orchestrator, project-evolver
• support: researcher, designer, planner, verifier, reviewer, docs-research, frontend-visual, implementer, final-reviewer

Global commands include:

• /ocb-start
• /ocb-project-init
• /ocb-explore
• /ocb-grounded
• /ocb-plan
• /ocb-implement
• /ocb-verify
• /ocb-fix
• /ocb-evolve
• /ocb-loop

Quick start

git clone git@github.com:tikhomirov/opencode-bootstrap.git
cd opencode-bootstrap
chmod +x bootstrap.sh scripts/verify.sh scripts/generate-checksums.sh
./bootstrap.sh

If you are new, start here

After installation, remember one command:

/ocb-start

What to do next:

1. Authenticate once with opencode auth login.
2. Open your repository with cd /path/to/project && opencode.
3. Type /ocb-start.
4. If the project is not yet initialized, it gives you one command to run. If it is already initialized, it shows a short numbered menu and then gives you one command to run.

The safe default path for most work is still:

/ocb-project-init
/ocb-plan <task>
/ocb-implement
/ocb-verify

The bootstrap flow is:

1. preflight
2. install dependencies
3. install OpenCode if missing
4. deploy bundle to staging
5. verify staging
6. backup and promote

Useful flags:

--dry-run
--verify-only
--skip-deps
--skip-opencode
--skip-backup
--target-dir PATH
--bundle-dir PATH
--opencode-version VERSION

Secrets and auth

The bootstrap does not copy:

• ~/.local/share/opencode/auth.json
• provider API keys
• MCP OAuth tokens
• shell profile secrets
• session history or cache files

Manual post-install steps:

opencode auth login
opencode auth list
opencode mcp list

How project rules are applied

Project-specific rules are never applied globally and never written to an arbitrary repository silently.

The target project is the current OpenCode session root.

Recommended usage:

cd /path/to/project
opencode

Then inside OpenCode:

/ocb-project-init

Flow:

1. OpenCode detects the current repository root
2. the command shows that path
3. it asks for explicit confirmation
4. only then does it write project-specific artifacts

If the detected path is wrong, stop and restart OpenCode from the correct repository root.

What /ocb-project-init creates

Inside the current repository:

.opencode/project/

Main artifacts:

• PROJECT_PROFILE.json
• PROJECT_RULES.generated.md
• LEARNED_RULES.generated.md
• PLAN.md
• RESEARCH.md
• VERIFY.md
• patches/
• evolutions/
• loops/

The local project opencode.json is updated so generated rule files are loaded through instructions.

What to do after /ocb-project-init

Short version: after /ocb-project-init, use the /ocb-* commands for normal work. They tell OpenCode what you want to do and which project files to use.

If you are not sure what to type next, run /ocb-start and let it route you to the right workflow command.

The simplest beginner flow is:

1. Run /ocb-project-init once in the repository.
2. For a new task, run /ocb-plan <what you want to change>.
3. When the plan looks right, run /ocb-implement.
4. When the work is done, run /ocb-verify.

If you remember only one pattern, remember this:

/ocb-project-init
/ocb-plan add X
/ocb-implement
/ocb-verify

If you remember only one command, remember this:

/ocb-start

Commands vs agents

If you are new to OpenCode, this part is important.

• The /ocb-* entries are ready-made commands. This is the main interface you should use in chat.
• fast, build, plan, and deep in the agent selector are base agents. Think of them as internal work modes.
• A command already picks the right mode and instructions for you. For example, /ocb-plan starts the planning flow, and /ocb-implement starts the implementation flow.
• In normal work, prefer /ocb-* commands. Switch base agents manually only if you already understand the difference.

Why this is useful:

• commands are easier for beginners because they say exactly what you want: explore, plan, implement, verify, fix
• commands reuse the project files created by /ocb-project-init
• commands keep work structured, so OpenCode is less likely to skip planning or verification
• commands write useful artifacts such as PLAN.md, RESEARCH.md, VERIFY.md, and patch history

Which command should I use?

Situation	Use this	What you get
You are not sure what to type next	/ocb-start	A simple next step for setup or the right workflow command
You want to build something new safely	/ocb-plan <task>	A step-by-step plan in .opencode/project/PLAN.md
The plan is ready and you want code changes	/ocb-implement	Code changes guided by the saved plan and project rules
You want to check whether the work is correct	/ocb-verify	A verification summary in .opencode/project/VERIFY.md
Something is broken	/ocb-fix <bug>	Debugging first, then a small fix and a patch note
You are not ready to choose a solution	/ocb-explore <topic>	Options, pros and cons, and research notes
You want a strict factual answer	/ocb-grounded <question>	An evidence-only answer with no guessing
The same mistakes keep happening	/ocb-evolve	Stronger learned project rules from past fixes
The task needs several controlled rounds	/ocb-loop new <task>	A bounded iterative workflow with saved state

Beginner examples

Unsure where to begin:

/ocb-start

New feature:

/ocb-project-init
/ocb-plan add a command to check bundle health
/ocb-implement
/ocb-verify

Bugfix:

/ocb-project-init
/ocb-fix the README says to run a command that does not exist
/ocb-verify

Research before coding:

/ocb-project-init
/ocb-explore what is the safest way to verify the bundle after install?
/ocb-plan improve bundle verification without breaking bootstrap

Need a strict factual answer:

/ocb-grounded which files define the shipped OpenCode bundle?

Daily workflow

• Main path for most work: /ocb-plan -> /ocb-implement -> /ocb-verify
• Use /ocb-explore before planning if you are still choosing between options
• Use /ocb-grounded when you need a strict evidence-only answer
• Use /ocb-fix instead of /ocb-plan when something is already broken and needs debugging first
• Use /ocb-evolve after several fixes to improve learned project rules
• Use /ocb-loop only for bigger tasks that may need several controlled rounds

Verification

Run at any time:

./scripts/verify.sh

It checks:

• bundle file presence
• OpenCode availability
• required agents
• MCP configuration (playwright, context7)
• enabled provider routing for openai and anthropic
• fast -> openai/gpt-5.4
• implementer -> Claude Sonnet
• final-reviewer -> Claude Opus

Routing policy

• fast and build use GPT-5.4 for orchestration, repo research, planning, and verification
• implementer uses Claude Sonnet for write-heavy code generation and substantial refactors
• final-reviewer uses Claude Opus only for large or risky final review passes
• if evidence is insufficient, agents should stop, name the missing evidence, and avoid guessing

Repository layout

.
├── bootstrap.sh
├── README.md
├── README.ru.md
├── PROJECT_INTELLIGENCE_PLAN.md
├── bundle/
│   ├── AGENTS.md
│   ├── MANIFEST.txt
│   ├── VERSION
│   ├── checksums.txt
│   ├── commands/
│   ├── opencode.json
│   ├── prompts/
│   ├── agents/
│   ├── skills/
│   └── tools/
└── scripts/
    ├── generate-checksums.sh
    └── verify.sh

Operational assumptions

• one write-heavy agent per project at a time
• no git worktree dependency
• logs, tests, diagnostics, and browser evidence are primary debugging inputs
• global config stays generic; project specifics are generated per repository

Maintenance

When updating the bundle:

1. update files under bundle/
2. update bundle/VERSION
3. run ./scripts/generate-checksums.sh
4. run ./scripts/verify.sh --target-dir "$HOME/.config/opencode" if needed
5. update CHANGELOG.md

Evaluation

• use EVALUATION.md for a repeatable golden-task checklist and A/B comparison method between baseline OpenCode and the bundled setup