# Decision log

Binding decisions. Re-litigate only with new evidence; append, never rewrite history.

## D1 — 2026-10-14 — Skills ship verbatim, agents carry the OpenCode wiring

Upstream SKILL.md files are served as faithfully as possible (OpenCode v2 natively honors `name`,
`description`, `disable-model-invocation`, supporting files via path resolution). OpenCode-specific
behavior (worktrees, subagent dispatch, permission enforcement, phase gating) lives in generated
**agent** files, not in patched skill text. This matches the proven `mcdays94/pocock-agents` design
and the mission's "upstream = methodology truth" principle.

## D2 — 2026-10-14 — Distribution: plugin injects skills; `init` bin copies agents

V2 `SkillEditor` supports `add()`; `AgentEditor` does **not** (verified against
`anomalyco/opencode@dev` docs/source 2026-10-14). Therefore:

- `setup(ctx)` injects every vendored skill via `ctx.skill.transform` reading bundled files
  (zero-config once the package is in `plugins`).
- `bin/opencode-pocock init [-g]` copies generated `agents/*.md` into `.opencode/agents/`
  (or `~/.config/opencode/agents/`). Plugin setup warns (one line) when the agents are missing or
  their stamped version != package version. No silent writes to user repos.

## D3 — 2026-10-14 — Release flow copied from fastcrw-opencode-websearch

CHANGELOG.md `## [x.y.z]` heading = release source of truth. `scripts/release.ts` publishes to the
Gitea npm registry via HTTP API (packument PUT + base64 tarball, no `npm publish`, no `.npmrc`),
ensures tag `v<version>`, links package to repo. Idempotent. Credentials only from
`secrets.PACKAGE_TOKEN`. package.json keeps `0.0.0-dev`; version is stamped in the staged copy only.

## D4 — 2026-10-14 — Nightly sync stops on no-change, minor-bumps on upstream change

Nightly workflow: sync → if upstream commit unchanged, exit 0 immediately. On change: update
snapshot, regenerate, format/typecheck/test/build, auto-prepend changelog entry with new minor
version + upstream short-SHA, release, commit generated changes back to main. Major bumps are never
automatic. Generated commit-back can't retrigger nightly (schedule/dispatch only).

## D5 — 2026-10-14 — Agent hierarchy stays minimal: orchestrator + worker (+ candidates)

No "giant Matt Pocock agent" and no 12-agent hierarchy for its own sake. Matt's phases
(grill → spec → tickets → build → review → retro) run in one primary conversation; only the build
phase fans out. Core agents: `pocock` (primary orchestrator), `pocock-worker` (subagent, worktree-
isolated, TDD). Candidates evaluated in Phase 2: `pocock-reviewer` (read-only review fanout —
likely yes), `pocock-researcher` (likely reject: built-in explore/general suffice). Every extra
agent must prove value against the classification matrix or be documented as rejected.

## D6 — 2026-10-14 — in-progress and deprecated upstream skills are excluded

`skills/in-progress/*` and `skills/deprecated/*` are not vendored into the package (unstable,
upstream itself gates them). `claude-handoff` is Claude-specific → not-convertible. Exclusions are
recorded in `.opencode/state/classification.json` so re-inclusion is a data change, not a redesign.

## D7 — 2026-10-14 — git-guardrails-claude-code becomes a real plugin feature

The only skill needing executable integration: dangerous-git blocking. Implemented as an opt-in
plugin hook (`ctx.tool.hook("execute.before")` on shell, options `{ guardrails: true }`, default
off) inside our plugin; the skill itself stays vendored verbatim for reference.