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

## D8 — 2026-10-14 — Final agent roster: pocock, pocock-worker, pocock-reviewer. No researcher.

Per-skill analysis (38 skills, `.opencode/state/classification.json`) confirms D5's core pair and
the reviewer candidate: `code-review`'s defining mechanic is two parallel isolated axis reviewers
with large self-contained prompts → `pocock-reviewer` (subagent, edit-deny, skill allow
`code-review` only) is the right primitive; the caller aggregates verbatim per the skill.
`pocock-researcher` is REJECTED: the 12-line `research` skill already is a background-agent brief;
OpenCode's built-in `general` subagent executes it as written — a branded agent adds drift risk and
zero capability. Per-phase agents (spec-writer, ticket-planner, debugger, ...) remain rejected:
Matt's phases share one conversation context by design (grilling facts feed to-spec; retro mines the
live session); isolating them would make the system worse. `triage` and `teach` agents rejected for
the same reason (continuous human dialogue belongs in the primary conversation).

## D9 — 2026-10-14 — Two 2.5 agent-improvement suggestions reviewed and rejected

The 2.5 orchestration run (PASS, commit `cc9a0dd`) suggested: (1) adding a line to `pocock.md`
about skill content looking truncated when a global `~/.agents/skills` install shadows the
plugin-injected id; (2) adding a reminder that a non-ff ticket merge is normal (resume the worker).
Both rejected: (1) is an artifact of one machine's pre-existing global install — on a clean machine
the package content is authoritative, and adding environment-quirk prose costs context load in
every session for zero general benefit (the model recovered unaided anyway); (2) is already the
documented path in `pocock.md` step 5, which the run followed correctly — duplicating it would
violate the no-duplicate-instructions validation criterion. Do not re-propose without evidence of
a run failing because of their absence.