docs: phase 0 analysis - architecture, plugin api requirements, sync and release design

.opencode/state/decisions.md

@@ -0,0 +1,57 @@
+# 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.

.opencode/state/status.md

@@ -0,0 +1,40 @@
+# Project status
+
+Updated: 2026-10-14 (phase 0 — analysis)
+
+## Current phase
+
+Phase 0 (analysis) — nearly complete. Phase 1 (plugin package) not started.
+
+## Done
+
+- Repo bootstrapped (was empty; Gitea remote `haylan/mattpocock-skills-opencode` configured, no commits yet).
+- Studied reference repos (cloned to temp, not vendored):
+  - `fastcrw-opencode-websearch` — V2 plugin shape, Gitea release script/workflows, test style
+    (`node --test` on .ts), prettier/tsconfig conventions.
+  - `mcdays94/pocock-agents` — proven orchestrator/worker agent pair (V1-era, tracks upstream v1.3
+    `d81f3a1`), drift-check script, Docker smoke test.
+  - `mattpocock/skills` @ `49dd158` (2026-10-09, v1.3.1) — full inventory: engineering 20,
+    productivity 7, misc 4, in-progress 7 (excluded), deprecated 0.
+- Verified OpenCode V2 API surface against docs + `anomalyco/opencode@dev` source (see AGENTS.md
+  "Key V2 facts").
+- Wrote: AGENTS.md, state files, TODO.md, docs/architecture.md, docs/skill-mapping.md.
+
+## Known gaps / risks
+
+- Unverified at runtime: exact `Skill.Info` field set accepted by `editor.add` (docs show
+  id/name/description/path/content + autoinvoke; confirm against installed `@opencode/plugin`
+  typings in Phase 1). Same for `permissions` array frontmatter in agent .md — verify with a real
+  `opencode serve` smoke.
+- Background subagents: V1 needed `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true`; V2 status
+  unknown — orchestrator must work in batch mode either way.
+- `request.body` overlays are accepted but not sent by the V2 runner yet — don't rely on
+  temperature tuning.
+- Nightly commit-back to main needs a Gitea token with repo write scope (same `PACKAGE_TOKEN`
+  pattern as fastcrw, which used it for tags + package link).
+
+## Next steps (exact)
+
+1. Finish docs/skill-mapping.md classification matrix (subagent analysis of every SKILL.md).
+2. Commit phase-0 docs: `docs: phase 0 analysis and migration plan`.
+3. Start TODO.md Phase 1.1: scaffold package (package.json, tsconfig, prettier, src/index.ts stub).

.opencode/state/upstream.json

@@ -0,0 +1,8 @@
+{
+  "repo": "https://github.com/mattpocock/skills",
+  "commit": "49dd158d1076134a641b33efb035946536778336",
+  "commit_date": "2026-10-09T11:56:49+01:00",
+  "upstream_version": "1.3.1",
+  "synced_at": null,
+  "note": "HEAD observed during phase-0 analysis; upstream/ snapshot not vendored yet"
+}