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

AGENTS.md

@@ -0,0 +1,58 @@
+# mattpocock-skills-opencode
+
+OpenCode v2 integration for the [Matt Pocock skills](https://github.com/mattpocock/skills) ecosystem.
+Upstream is the source of truth for the methodology; OpenCode v2 is the source of truth for execution
+architecture. We translate, never copy Claude Code's plugin architecture.
+
+## Session start protocol (long-running project)
+
+1. `git status` + current branch — never destroy uncommitted work.
+2. Read `TODO.md` — the persistent task list.
+3. Read `.opencode/state/status.md` — current phase and last completed work.
+4. Read `.opencode/state/decisions.md` — binding decisions; don't re-litigate them without new evidence.
+5. Read `.opencode/state/upstream.json` — last synchronized upstream revision.
+6. Pick the highest-value unfinished task from `TODO.md` and continue.
+
+Before context runs low: update `status.md` + `TODO.md`, record failures and exact next steps, commit
+safe intermediate work.
+
+## Layout
+
+- `upstream/` — pristine vendored snapshot of mattpocock/skills (`skills/` subtree). **Never hand-edit.**
+  Updated only by `scripts/sync-upstream.ts`.
+- `skills/` — generated OpenCode skill tree + `manifest.json` (output of `scripts/generate.ts`). Hand-edit
+  only the overlay inputs under `overlay/`, never the output.
+- `agents/` — generated OpenCode v2 agent markdown files. Edit templates in `agent-templates/`, then regenerate.
+- `.opencode/state/` — machine- and human-readable project state (upstream revision, classification, status).
+- `docs/architecture.md` — the design. `docs/skill-mapping.md` — per-skill classification record (generated
+  from `.opencode/state/classification.json`).
+- `scripts/` — sync, generate, release (Gitea npm registry publish without `npm publish`), smoke.
+- `test/` — `node --test` on TypeScript sources directly (Node ≥ 22.18 type stripping, like the reference repo).
+
+## Conventions
+
+- TypeScript ESM, `type: module`, prettier (`semi: false`, `printWidth: 100`), `tsc --noEmit` gate.
+- Generated agent frontmatter uses **V2-native fields only**: `mode`, `description`, `model`
+  (`provider/model#variant`), `permissions` (array of `{action, resource, effect}`), `steps`, `hidden`,
+  `request` (sparingly — body overlays are not sent by the runner yet). Never `prompt`, `permission`,
+  `tools`, `disable`, `maxSteps`, `temperature` at top level.
+- Commits: `sync:`, `feat:`, `fix:`, `test:`, `chore:`, `docs:` — logically separated, conventional style.
+- Versioning: semver; `CHANGELOG.md` `## [x.y.z]` headings are the release source of truth
+  (fastcrw pattern). Upstream revision tracked separately in state + changelog entries.
+- Registry credentials only from Gitea Action secrets (`PACKAGE_TOKEN`). Never commit them.
+
+## Key V2 facts this repo relies on (verified 2026-10-14 against opencode docs/source)
+
+- Plugins: `Plugin.define({ id, setup(ctx) })` from `@opencode/plugin`; config key `plugins`;
+  npm package needs `type: module` + `exports["."]`.
+- `ctx.skill.transform(editor)` **can add** skills programmatically (id, name, description, path,
+  content, autoinvoke, slash). `ctx.agent.transform(editor)` **cannot add** agents — only
+  list/get/update/remove/default. Hence: skills ship via plugin injection, agents via `init` copy.
+- Skills frontmatter honored: `name`, `description`, `slash`, `disable-model-invocation` /
+  `metadata.opencode/autoinvoke` (hidden from model, still loadable by id/slash).
+- Agent files: `.opencode/agents/<name>.md` (project), `~/.config/opencode/agents/` (global);
+  frontmatter = agent config, body = system prompt.
+- Permission rules are ordered, last match wins; per-agent skill restrictions via
+  `{action: "skill", resource: "<pattern>", effect: ...}`. Shell action is `shell` in V2.
+- Agent `steps` replaces `maxSteps`; `temperature`/`top_p` go under `request.body` (not yet sent by
+  the runner — avoid).