🧠 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;
• GPT-first orchestration with selective Anthropic usage for implementation-heavy and final-review tasks only.

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

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.

Daily workflow

/ocb-explore
/ocb-grounded
/ocb-plan
/ocb-implement
/ocb-verify
/ocb-fix
/ocb-evolve
/ocb-loop

Verification

Run at any time:

./scripts/verify.sh

It checks:

• bundle file presence
• OpenCode availability
• required agents
• MCP configuration (playwright, context7)
• fast -> openai/gpt-5.3-codex
• implementer -> Claude Sonnet
• final-reviewer -> Claude Opus

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