Skip to content

setup.md

Latest commit

 

History

History
92 lines (68 loc) · 3.52 KB

setup.md

File metadata and controls

92 lines (68 loc) · 3.52 KB

OpenCode-First Setup

What this repository captures now

This playbook now captures a converged OpenCode setup with:

  • native primary agents for low-cost and deep work
  • command-driven planning, TDD anchoring, implementation, review, and verification
  • a persisted PLAN.md contract for non-trivial work
  • lightweight local plugins for compaction and verification discipline
  • Sentry MCP for runtime evidence
  • optional skills and optional OpenSpec, not mandatory baseline dependencies

Two adoption paths

Minimal path

Use this if you mainly want the planning and execution model without copying every detail:

  1. Install and configure OpenCode.
  2. Copy config/opencode.template.json, config/AGENTS.template.md, and config/agents/reviewer.template.md into your environment.
  3. Add the command templates for /plan, /spec, /implement, /review, and /verify.
  4. Add Sentry MCP later if you actually need runtime evidence.

Full path

Use this if you want the full implementation documented by this repo:

  1. Install and configure OpenCode.
  2. Configure both openai and github-copilot providers.
  3. Copy the full template set from config/.
  4. Configure Sentry MCP in local-command mode and authenticate it. Run sentry-mcp auth login, or provide SENTRY_ACCESS_TOKEN in the environment when you start OpenCode.
  5. Add optional skills only when a framework-specific domain clearly justifies them.
  6. Add OpenSpec only if you want a larger change lifecycle than PLAN.md provides.

Before finalizing the setup, verify that the model IDs in your config actually exist for your providers. This repository documents one working April 2026 baseline, not a universal set of provider slugs.

Suggested directory layout

~/.config/opencode/
├── opencode.json
├── package.json
└── node_modules/

~/.opencode/
├── agents/
│   └── reviewer.md
├── commands/
│   ├── plan.md
│   ├── spec.md
│   ├── implement.md
│   ├── review.md
│   ├── verify.md
│   └── release.md
└── plugins/
    ├── smart-compaction.ts
    └── verify-gate.ts

~/projects/my-repo/
├── AGENTS.md
└── PLAN.md

PLAN.md is task-local and repo-local. It should be created during planning, not stored as a global default file.

Recommended installation order

  1. Install OpenCode and authenticate your providers.
  2. Copy opencode.template.json and the agent/command/plugin templates.
  3. Configure mcp.sentry in opencode.json to call your local sentry-mcp binary, then complete authentication with sentry-mcp auth login or SENTRY_ACCESS_TOKEN.
  4. Run a small smoke test: switch agents, use /plan, and verify that PLAN.md can be created.
  5. Add optional skills later, after you see repeated domain-specific needs.

Convergence rules

  • Keep one active planning-and-execution baseline.
  • Do not let optional skills silently redefine your routing rules.
  • If you add OpenSpec, treat it as an explicit extension for persistent artifacts, not as a hidden duplicate of /plan and /spec.

Template files in this repository

Use the config/ directory as the shareable baseline:

  • opencode.template.json
  • AGENTS.template.md
  • agents/reviewer.template.md
  • commands/*.template.md
  • plugins/*.template.ts

The legacy routing and environment-check templates are still included as historical references in config/ROUTING_POLICY.template.md and config/ENV_SELF_CHECK_POLICY.template.md, but they are no longer required for the baseline stack.