Opencode Repo Setup Skill

---
name: opencode-repo-setup-skill
description: >-
  Interactive per-repo setup — opt-in MCP servers (project opencode.json wins),
  optional CodeGraph init, AGENTS.md rule blocks, token-cost report. Triggers:
  set up mcp for this repo, repo setup, per-project enable, configure project
  opencode.
license: Apache-2.0
compatibility: opencode
category: OpenCode Meta
---

## What I do

I am the **interactive frontend for per-project MCP enablement**. The global deploy ships most MCP servers disabled (zero always-on schema cost); this skill is how a specific repo opts in. I run in the primary session of the TARGET project (not the configurator repo):

1. **Detect** — scan the repo for setup signals
2. **Ask** — present a question-tool menu of opt-in servers + extras
3. **Write** — merge-write ONLY the delta into `<repo>/opencode.json`
4. **Init** — optionally run `codegraph init -i`
5. **Report** — enabled set, estimated token cost, revert instructions

I never edit the global `~/.config/opencode/config.json`. Opencode merges project config over global with **project wins** semantics, so a one-key delta is all that's needed.

## When to use me

- User says "set up MCP for this repo", "enable Jira/Atlassian here", "project-level opencode setup"
- A marker rule fired (user AGENTS.md may say: if a repo's AGENTS.md mentions Jira/MCP needs, offer this skill)
- First session in a repo that carries its own `.opencode/` — offer to review/extend it

## Step 1 — Detect

Cheap, read-only scans (no network):

| Signal | Check | Suggests |
|--------|-------|----------|
| Existing project config | `<repo>/opencode.json` exists | Idempotent mode: show current overrides, offer to extend |
| CodeGraph index | `<repo>/.codegraph/` exists | codegraph already enabled locally; no action |
| Jira usage | AGENTS.md/README mentions Jira keys (`PROJ-123`), JIRA env vars, `atlassian` refs | offer `atlassian` enable |
| GitHub-centric | `.github/`, `gh` in scripts | gh CLI usually suffices; no MCP needed |
| Docs-heavy | `.docx`/`.pptx`/`.pdf` in repo | offer markitdown/docling packs |
| Frontend | `package.json` with next/react | offer next-devtools |
| Python | `pyproject.toml` | nothing MCP-specific by default |
| GitHub repo | `.github/` or GitHub remote present AND `.github/ISSUE_TEMPLATE/` absent | offer issue-template scaffold (Step 2 extras) |

Report findings in one table, then go to Step 2.

## Step 2 — Ask (question tool)

One multi-select question + one yes/no per extra. Options are built from the detection table — only show servers with a detected signal plus the general opt-in list:

**MCP enables** (any of):
- `atlassian` — Jira/Confluence tools (~5–6.5k tok/session when enabled; see caveats below)
- markitdown / docling / chrome-devtools / next-devtools — via global `--enable-pack` if not already enabled

**Extras**:
- "Initialize CodeGraph index? (`codegraph init -i`)" — only if `.codegraph/` absent and repo is code-heavy; on accept, also append the CodeGraph rule block (below) to `<repo>/AGENTS.md`
- "Append the LSP rule block to AGENTS.md?" — offer when a built-in LSP server matches the repo language (TS/JS → `typescript`+`eslint`; Python → `pyright`)
- "Scaffold a minimal project AGENTS.md?" — repo rules only; NO MCP prose (that belongs to config + this skill)
- "Scaffold GitHub issue templates? (bug report + feature request forms + chooser config)" — offer when the detection table signals a GitHub repo without `.github/ISSUE_TEMPLATE/`; copies `bug_report.yml`, `feature_request.yml`, `config.yml` from the installed `ticket-creation-skill/templates/` dir into `<repo>/.github/ISSUE_TEMPLATE/`. Create-if-absent ONLY — an existing file is skipped and reported, never overwritten. Source templates dir absent (per-skill install without `ticket-creation-skill`) → skip the offer with a note (mirrors the CodeGraph soft-skip). These are git-tracked repo files — they never touch `opencode.json`.

## Step 3 — Write (merge-write, delta-only)

Target: `<repo>/opencode.json`. Create if absent; **never clobber existing keys** — deep-merge at the top level manually (read file, add only the chosen `mcp.servers.<server>` entries). Keep the file comment-free JSON.

Typical delta (FULL entry — mandatory):

```json
{
  "mcp": {
    "servers": {
      "atlassian": {
        "type": "local",
        "command": ["npx", "-y", "mcp-remote", "https://mcp.atlassian.com/v1/mcp"],
        "disabled": false
      }
    }
  }
}
```

Rules:
- **Full entries only**: v2 replaces `mcp.servers.<name>` **atomically** across config layers — a bare `{"disabled": false}` stub erases the global transport and yields an inert server. Copy `type`/`command`/`environment` from the global `~/.config/opencode/opencode.json` definition and set `disabled: false` (Atlassian OAuth flows via `mcp-remote`; see caveats)
- If the file exists, preserve every other key verbatim (byte-stable elsewhere; pretty-print 2-space)
- Never write `disabled: true` to disable something globally enabled — the project layer is for opting IN

Merge procedure (MANDATORY when `<repo>/opencode.json` already exists — never Write-overwrite):

1. Read + validate the existing file: `jq . opencode.json` (if invalid JSON, STOP and show the user; do not guess)
2. Merge the delta with jq `*` deep-merge, existing file as base:

   ```bash
   jq -s '.[0] * .[1]' opencode.json delta.json > opencode.json.new && mv opencode.json.new opencode.json
   ```

   (`delta.json` = the chosen `{"mcp":{...}}` blob; `*` merges recursively, existing non-conflicting keys survive, delta wins on conflicts — which is exactly the chosen-enable set)
3. Diff-check: `git diff opencode.json` (or plain diff vs a pre-made backup) must show ONLY the added `mcp.*` keys
4. No jq available? Read the file, hand-merge the `mcp` key into the parsed object, and Write the full merged result — never emit a file missing previously-present keys

Also in Step 1 detection: ALWAYS `cat <repo>/opencode.json` when present and show its current keys to the user before Step 2, so the menu reflects what is already enabled.

## Step 4 — Init (CodeGraph only)

If accepted and `.codegraph/` absent: run `codegraph init -i` in the repo root. If `codegraph` is not installed or the repo is non-code/very large, soft-skip with a note. In headless/CI: skip silently unless explicitly requested.

CodeGraph setup reference (merged from the former `codegraph-setup-skill`):

```bash
npx @colbymchenry/codegraph init -i          # init + index (5-60s; creates .codegraph/)
echo ".codegraph/" >> .gitignore             # index is local-only — never commit it
npx @colbymchenry/codegraph status           # verify: backend native (preferred) or wasm
npx @colbymchenry/codegraph sync             # incremental sync (watcher auto-syncs, 2s debounce)
npx @colbymchenry/codegraph index --force    # full re-index after major structural changes
npx @colbymchenry/codegraph uninit --force   # remove CodeGraph from the project
```

- **Prereqs:** Node.js v18+, no API keys (100% local). 19+ languages (TS/JS/Python/Go/Rust/Java/C#/…).
- **Post-setup:** the file watcher auto-syncs; MCP tools (`codegraph_search`, `codegraph_callers`/`callees`, `codegraph_impact`, `codegraph_files`, …) are available to all agents whenever `.codegraph/` exists. `codegraph_explore`/`codegraph_context` are for explore agents (flood primary context otherwise).

Troubleshooting:

- **"Backend: wasm" (5–10x slower)** — install native build tools (`sudo apt install build-essential python3 make`; macOS: `xcode-select --install`), then `npm rebuild better-sqlite3`. Also fixes **"database is locked"**.
- **Missing symbols after edits** — wait 2–3s for the watcher, or run `sync` manually.
- **Large repos slow to index** — add `exclude` globs (`node_modules/**`, `dist/**`, `build/**`, `vendor/**`, `*.min.js`, `*.generated.*`) to `.codegraph/config.json`.

## Rule blocks (project AGENTS.md)

Per-tool routing rules live at PROJECT level, not user level — this skill appends them on acceptance. Append = add the block verbatim under an `## OpenCode Rule Blocks` heading (create file/heading if absent); skip if the block's marker comment already exists anywhere in the file.

**CodeGraph** (marker `<!-- opencode:codegraph -->`) — append on init accept:

> The `codegraph_*` tools are the interface (`status` → `search`/`callers`/`callees`/`impact`/`node`/`files`). Never call `read_mcp_resource`/`list_mcp_resources` — runtime-denied (upstream tool-list bug). Main session: lightweight lookups only — never `codegraph_explore`/`codegraph_context` (flood context; spawn an explore agent).

**LSP** (marker `<!-- opencode:lsp -->`) — append on offer accept:

> On reviews with >10-file or shared-module changes where `opencode.json` has no `lsp` key and a built-in server matches: append a one-line LSP-enable recommendation (TS/JS/Next.js → `typescript`+`eslint`; Python → `pyright`). Recommend only — never auto-edit `opencode.json`.

**Jira templates** (marker `<!-- opencode:jira-templates -->`) — offer appended when the repo is Jira-centric (detection table's Jira signal) and accepted:

> Jira ticket descriptions follow the type templates — Bug: Problem description / Steps to reproduce / Expected vs Actual / Environment / Logs / References (mirrors the canonical GitHub bug body). Story: "As a… I want… so that…" + acceptance-criteria checklist. Task: Context / Acceptance Criteria / Scope. Run the intake from `ticket-creation-skill` first (classify → collect required fields → validate → preview); never leave a Jira description empty.

> GitHub repos get real form files via the issue-template scaffold above; Jira has no repo-file equivalent, so this rule block is the agent-side application path.

## Step 5 — Report

State exactly:

- **Enabled here**: list (e.g. `atlassian`) — takes effect on NEXT session start (opencode reads config at startup; no lazy-start mid-session)
- **Estimated per-session cost**: atlassian ~5–6.5k tok; codegraph ~1.2k + zai-web-search ~0.35k (both already default-on, GIT-336)
- **Rule blocks appended**: CodeGraph / LSP / Jira templates / none
- **Files written**: `.github/ISSUE_TEMPLATE/{bug_report.yml,feature_request.yml,config.yml}` (per file actually written; none if all already existed) + appended AGENTS.md blocks
- **Revert**: delete the added `mcp.<server>` keys (or the whole file if we created it); remove appended AGENTS.md blocks
- **Global untouched**: `~/.config/opencode/config.json` unchanged; other repos unaffected

## Atlassian caveats (read before enabling)

- **First use opens a browser OAuth flow** (mcp-remote → mcp.atlassian.com). Fine on desktop; **fails headless/CI**.
- Headless fallback = skip MCP, use REST: token at id.atlassian.com/manage-profile/security/api-tokens; REST pattern + cloudId discovery per `jira-git-integration-skill` §MCP Availability Guard.
- Delegation pattern: even when enabled, route bulk Jira calls through a subagent to keep tool output out of the primary context (schemas are paid regardless of who calls).

## Governance

| Aspect | Source of truth |
|--------|----------------|
| Server inventory + default enable states | `opencode_app/opencode.json` `mcp` block of the configurator repo |
| Config layering (project wins) | opencode docs — config merge semantics |
| CodeGraph init | CodeGraph server's own MCP instructions + this skill's Step 4 / Rule blocks |

This skill deliberately contains no server versions, URLs beyond Atlassian REST constants, or token costs beyond the estimates above — refresh from the configurator repo's README MCP table when drifting.