docs: skill inventory and classification matrix for all 38 upstream skills

.opencode/state/classification.json

@@ -0,0 +1,50 @@
+{
+  "$comment": "Per-skill classification driving scripts/generate.ts. Source of truth for docs/skill-mapping.md. Classification enum: skill | agent | agent+skill | orchestrator | plugin | not-convertible. Artifacts: skill:verbatim (vendored + plugin-injected), agent:<name> (generated .md), plugin:<feature>, excluded. status: analyzed | needs-review (new upstream skills land as skill/needs-review).",
+  "upstream_commit": "49dd158d1076134a641b33efb035946536778336",
+  "analyzed_at": "2026-10-14",
+  "agents": {
+    "pocock": "primary orchestrator: ask-matt routing + implement-spec dispatch loop (worktrees, frontier, merges) + user-invoked gating",
+    "pocock-worker": "subagent: one ticket, TDD at spec seams, worktree-locked, never pushes, skill allow-list",
+    "pocock-reviewer": "subagent: read-only code-review axis executor (Standards/Spec), findings returned to caller"
+  },
+  "skills": [
+    { "name": "ask-matt", "bucket": "engineering", "classification": "skill", "user_invoked": true, "artifacts": ["skill:verbatim"], "depends_on": [], "status": "analyzed", "rationale": "Pure router prose over all skills; no execution or isolation. Its routing logic also informs the pocock agent's system prompt." },
+    { "name": "code-review", "bucket": "engineering", "classification": "agent+skill", "user_invoked": false, "artifacts": ["skill:verbatim", "agent:pocock-reviewer"], "depends_on": [], "status": "analyzed", "rationale": "Skill stays verbatim (aggregation protocol), but its core mechanic is two parallel isolated axis reviewers with large self-contained prompts -> dedicated read-only pocock-reviewer subagent hosts each axis. Caller (pocock or user) aggregates per the skill." },
+    { "name": "codebase-design", "bucket": "engineering", "classification": "skill", "user_invoked": false, "artifacts": ["skill:verbatim"], "depends_on": [], "status": "analyzed", "rationale": "Canonical shared-vocabulary reference consumed by tdd/improve-arch/setup-ts-deep-modules; DESIGN-IT-TWICE parallel subagents run via task tool from the loading agent." },
+    { "name": "diagnosing-bugs", "bucket": "engineering", "classification": "skill", "user_invoked": false, "artifacts": ["skill:verbatim"], "depends_on": [], "status": "analyzed", "rationale": "Six-phase procedural discipline run inline; no isolation or special permissions needed." },
+    { "name": "domain-modeling", "bucket": "engineering", "classification": "skill", "user_invoked": false, "artifacts": ["skill:verbatim"], "depends_on": [], "status": "analyzed", "rationale": "Interactive writing discipline + bundled format files (GLOSSARY/ADR); must run in the main conversation to challenge user wording - an isolated agent would break it." },
+    { "name": "grill-with-docs", "bucket": "engineering", "classification": "skill", "user_invoked": true, "artifacts": ["skill:verbatim"], "depends_on": ["grilling", "domain-modeling"], "status": "analyzed", "rationale": "7-line composition wrapper; OpenCode skill tool loads the two named skills. Preserve verbatim; orchestrator verifies both load (known upstream wrapper failure mode)." },
+    { "name": "implement", "bucket": "engineering", "classification": "skill", "user_invoked": true, "artifacts": ["skill:verbatim"], "depends_on": ["tdd", "code-review"], "status": "analyzed", "rationale": "Thin single-context per-ticket procedure composing tdd + code-review; the pocock-worker agent embodies its discipline for parallel builds." },
+    { "name": "implement-spec", "bucket": "engineering", "classification": "orchestrator", "user_invoked": true, "artifacts": ["skill:verbatim", "agent:pocock", "agent:pocock-worker"], "depends_on": ["tdd", "code-review"], "status": "analyzed", "rationale": "The repo's clearest orchestrator: task-graph frontier, background implementers in git worktrees, merger, fixer. OpenCode's task tool provides no worktrees, so the pocock agent supplies worktree creation, frontier scheduling from its own merge record, and merges; skill text stays verbatim." },
+    { "name": "improve-codebase-architecture", "bucket": "engineering", "classification": "skill", "user_invoked": true, "artifacts": ["skill:verbatim"], "depends_on": ["codebase-design", "grilling", "domain-modeling"], "status": "analyzed", "rationale": "Interactive survey-and-grill; its exploration/design-it-twice subagents are internal delegation via task tool, not its identity." },
+    { "name": "pr", "bucket": "engineering", "classification": "skill", "user_invoked": false, "artifacts": ["skill:verbatim"], "depends_on": [], "status": "analyzed", "rationale": "Pure PR-body template/reference. Verbatim vendoring preserves required attribution (metadata.credits + CREDITS.md, Dex Horthy's show-me)." },
+    { "name": "prototype", "bucket": "engineering", "classification": "skill", "user_invoked": false, "artifacts": ["skill:verbatim"], "depends_on": [], "status": "analyzed", "rationale": "Generation procedure with two branch docs (LOGIC/UI); user reacts to artifacts in main conversation." },
+    { "name": "research", "bucket": "engineering", "classification": "skill", "user_invoked": false, "artifacts": ["skill:verbatim"], "depends_on": [], "status": "analyzed", "rationale": "The 12-line skill IS a background-agent brief; OpenCode's built-in general subagent + background:true executes it as written. Dedicated pocock-researcher agent evaluated and REJECTED (D8): the brief is self-contained, a branded agent adds drift risk and no capability." },
+    { "name": "retro", "bucket": "engineering", "classification": "skill", "user_invoked": true, "artifacts": ["skill:verbatim"], "depends_on": ["writing-for-agents"], "status": "analyzed", "rationale": "Analysis over the current session's history - isolating it in a subagent would starve it of the session context it mines." },
+    { "name": "setup-matt-pocock-skills", "bucket": "engineering", "classification": "skill", "user_invoked": true, "artifacts": ["skill:verbatim"], "depends_on": [], "status": "analyzed", "rationale": "Interactive per-repo scaffolding + seed assets; it creates the docs/agents/* state that to-spec/to-tickets/triage/implement/implement-spec/code-review/wayfinder hard-depend on. Keep verbatim; README flags it as required first run." },
+    { "name": "tdd", "bucket": "engineering", "classification": "skill", "user_invoked": false, "artifacts": ["skill:verbatim"], "depends_on": ["codebase-design"], "status": "analyzed", "rationale": "The reusable build discipline; consumed by implement and every pocock-worker via skill allow-list." },
+    { "name": "to-spec", "bucket": "engineering", "classification": "skill", "user_invoked": true, "artifacts": ["skill:verbatim"], "depends_on": [], "status": "analyzed", "rationale": "Synthesis + template + publish procedure; explicitly no interview, needs main-conversation context (grilling output)." },
+    { "name": "to-tickets", "bucket": "engineering", "classification": "skill", "user_invoked": true, "artifacts": ["skill:verbatim"], "depends_on": [], "status": "analyzed", "rationale": "Decomposition with human approval loop; needs the spec conversation in context." },
+    { "name": "triage", "bucket": "engineering", "classification": "skill", "user_invoked": true, "artifacts": ["skill:verbatim"], "depends_on": ["grilling", "domain-modeling"], "status": "analyzed", "rationale": "Maintainer-driven interactive state machine; heavy human-in-the-loop design fits a skill. A dedicated triage agent was considered and rejected: every step waits on the maintainer." },
+    { "name": "wayfinder", "bucket": "engineering", "classification": "skill", "user_invoked": true, "artifacts": ["skill:verbatim"], "depends_on": ["grilling", "domain-modeling", "research", "prototype"], "status": "analyzed", "rationale": "Stateful planning protocol over the tracker (map/fog/frontier); its research dispatches use the research skill + built-in subagents." },
+    { "name": "wizard", "bucket": "engineering", "classification": "skill", "user_invoked": false, "artifacts": ["skill:verbatim"], "depends_on": [], "status": "analyzed", "rationale": "Code generator with bundled template.sh asset; the generated artifact is a human-run script, no harness integration needed." },
+    { "name": "grill-me", "bucket": "productivity", "classification": "skill", "user_invoked": true, "artifacts": ["skill:verbatim"], "depends_on": ["grilling"], "status": "analyzed", "rationale": "7-line stateless wrapper around grilling." },
+    { "name": "grilling", "bucket": "productivity", "classification": "skill", "user_invoked": false, "artifacts": ["skill:verbatim"], "depends_on": [], "status": "analyzed", "rationale": "The interview primitive the whole methodology builds on; 100% human interaction in the main conversation - converting to an agent would make it worse (isolated context can't grill the user). Fact-finding subagents dispatch via task tool." },
+    { "name": "handoff", "bucket": "productivity", "classification": "skill", "user_invoked": true, "artifacts": ["skill:verbatim"], "depends_on": [], "status": "analyzed", "rationale": "Document-generation instructions writing to OS temp dir." },
+    { "name": "teach", "bucket": "productivity", "classification": "skill", "user_invoked": true, "artifacts": ["skill:verbatim"], "depends_on": [], "status": "analyzed", "rationale": "Stateful multi-session tutor with bundled format files; workspace state lives in files, so no agent isolation needed. A tutor agent was considered and rejected: continuous human dialogue belongs in the primary conversation." },
+    { "name": "to-questionnaire", "bucket": "productivity", "classification": "skill", "user_invoked": true, "artifacts": ["skill:verbatim"], "depends_on": [], "status": "analyzed", "rationale": "Two structured interviews + document template." },
+    { "name": "wait-what", "bucket": "productivity", "classification": "skill", "user_invoked": true, "artifacts": ["skill:verbatim"], "depends_on": [], "status": "analyzed", "rationale": "7-line corrective re-pitch instruction, usable mid-any-skill." },
+    { "name": "writing-for-agents", "bucket": "productivity", "classification": "skill", "user_invoked": false, "artifacts": ["skill:verbatim"], "depends_on": [], "status": "analyzed", "rationale": "Pure theory reference; the most instructions-only skill in the repo." },
+    { "name": "git-guardrails-claude-code", "bucket": "misc", "classification": "plugin", "user_invoked": false, "artifacts": ["skill:verbatim", "plugin:guardrails"], "depends_on": [], "status": "analyzed", "rationale": "Only skill needing executable integration: a Claude Code PreToolUse hook. OpenCode equivalent = opt-in ctx.tool.hook('execute.before') on shell inside our plugin (D7), default off, porting the bundled block-dangerous-git.sh pattern list. Skill text stays vendored verbatim for reference/fidelity." },
+    { "name": "migrate-to-shoehorn", "bucket": "misc", "classification": "skill", "user_invoked": false, "artifacts": ["skill:verbatim"], "depends_on": [], "status": "analyzed", "rationale": "Mechanical codemod recipe. Frozen misc bucket - vendored as-is." },
+    { "name": "scaffold-exercises", "bucket": "misc", "classification": "skill", "user_invoked": false, "artifacts": ["skill:verbatim"], "depends_on": [], "status": "analyzed", "rationale": "Environment-bound: hard-depends on Matt's private ai-hero-cli, only works in his course repos. Vendored verbatim with caveat noted in mapping doc; no OpenCode artifact can fix an external private tool." },
+    { "name": "setup-pre-commit", "bucket": "misc", "classification": "skill", "user_invoked": false, "artifacts": ["skill:verbatim"], "depends_on": [], "status": "analyzed", "rationale": "Setup recipe, npm ecosystem only. Frozen misc bucket - vendored as-is." },
+    { "name": "chief-of-staff", "bucket": "in-progress", "classification": "orchestrator", "user_invoked": true, "artifacts": ["excluded"], "depends_on": [], "status": "analyzed", "rationale": "EXCLUDED per D6 (in-progress beta). Would map to a coordinator persona over background subagents; revisit only if upstream promotes it." },
+    { "name": "claude-handoff", "bucket": "in-progress", "classification": "not-convertible", "user_invoked": true, "artifacts": ["excluded"], "depends_on": ["handoff"], "status": "analyzed", "rationale": "EXCLUDED per D6 + harness-bound: hard-depends on Claude CLI --bg/agents launcher. OpenCode analogue would need its own background-session mechanism; handoff skill covers the portable half." },
+    { "name": "loop-me", "bucket": "in-progress", "classification": "skill", "user_invoked": true, "artifacts": ["excluded"], "depends_on": ["grilling"], "status": "analyzed", "rationale": "EXCLUDED per D6 (in-progress). Grilling + workflows/*.md workspace convention; converts trivially if promoted." },
+    { "name": "setup-ts-deep-modules", "bucket": "in-progress", "classification": "skill", "user_invoked": true, "artifacts": ["excluded"], "depends_on": ["codebase-design"], "status": "analyzed", "rationale": "EXCLUDED per D6 (in-progress). Dependency-cruiser setup with bundled config + prove-it-bites self-check; converts cleanly if promoted." },
+    { "name": "writing-beats", "bucket": "in-progress", "classification": "skill", "user_invoked": true, "artifacts": ["excluded"], "depends_on": ["writing-fragments"], "status": "analyzed", "rationale": "EXCLUDED per D6 (in-progress)." },
+    { "name": "writing-fragments", "bucket": "in-progress", "classification": "skill", "user_invoked": true, "artifacts": ["excluded"], "depends_on": ["grilling"], "status": "analyzed", "rationale": "EXCLUDED per D6 (in-progress)." },
+    { "name": "writing-shape", "bucket": "in-progress", "classification": "skill", "user_invoked": true, "artifacts": ["excluded"], "depends_on": ["writing-fragments"], "status": "analyzed", "rationale": "EXCLUDED per D6 (in-progress)." }
+  ]
+}

.opencode/state/decisions.md

@@ -55,3 +55,16 @@ recorded in `.opencode/state/classification.json` so re-inclusion is a data chan
 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).

.opencode/state/status.md

@@ -4,21 +4,23 @@ Updated: 2026-10-14 (phase 0 — analysis)
 
 ## Current phase
 
-Phase 0 (analysis) — nearly complete. Phase 1 (plugin package) not started.
+Phase 0 (analysis) — COMPLETE. Phase 1 (plugin package) ready to start at TODO 1.1.
 
 ## Done
 
-- Repo bootstrapped (was empty; Gitea remote `haylan/mattpocock-skills-opencode` configured, no commits yet).
+- Repo bootstrapped (was empty; Gitea remote `haylan/mattpocock-skills-opencode` configured).
 - 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.
+  - `mattpocock/skills` @ `49dd158` (2026-10-09, v1.3.1) — all 38 SKILL.md files read in full by a
+    subagent: frontmatter census (only name/description/disable-model-invocation×23/argument-hint×4/
+    metadata.credits×1), dependency graph, subagent census, 17 pending patch changesets.
+- Verified OpenCode V2 API surface against docs + `anomalyco/opencode@dev` source + installed
+  `@opencode/plugin@2.0.29` typings (see AGENTS.md "Key V2 facts").
+- Wrote: AGENTS.md, state files (upstream/decisions D1–D8/classification.json), TODO.md,
+  docs/architecture.md, docs/skill-mapping.md (31 vendored + 7 excluded skills classified).
 
 ## Known gaps / risks
 
@@ -35,6 +37,10 @@ Phase 0 (analysis) — nearly complete. Phase 1 (plugin package) not started.
 
 ## 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).
+1. Phase 1.1: scaffold package (package.json `@haylan/opencode-pocock` — confirm scope with owner,
+   tsconfig, prettier, .gitignore, MIT LICENSE + upstream attribution, README stub).
+2. Phase 1.2: scripts/sync-upstream.ts + vendor upstream/ @49dd158 (strip non-skill files: keep
+   skills/{engineering,productivity,misc}/** minus agents/openai.yaml; write UPSTREAM.json).
+3. Phase 1.6 note: agent templates = port pocock.md/pocock-worker.md from mcdays94/pocock-agents
+   (temp clone path in status history) to V2-native frontmatter + add pocock-reviewer; update
+   stack-skills table to be user-editable; worker skill allow-list from classification.json.

TODO.md

@@ -13,8 +13,9 @@ State: `.opencode/state/status.md`. Design: `docs/architecture.md`.
 - [x] Gitea Actions design (§6)
 - [x] Testing strategy (§7)
 - [x] Phased plan (§9)
-- [ ] Skill inventory + classification matrix → docs/skill-mapping.md (subagent analysis in flight)
-- [ ] Commit phase-0 docs (`docs: phase 0 analysis and migration plan`)
+- [x] Skill inventory + classification matrix → docs/skill-mapping.md +
+      .opencode/state/classification.json (38 skills analyzed from SKILL.md sources)
+- [x] Commit phase-0 docs
 
 ## Phase 1 — plugin package
 
@@ -36,10 +37,10 @@ State: `.opencode/state/status.md`. Design: `docs/architecture.md`.
 
 ## Phase 2 — conversion
 
-- [ ] 2.1 deep per-skill analysis → .opencode/state/classification.json + docs/skill-mapping.md
-      (classification.json becomes generator input; mapping doc generated from it)
+- [x] 2.1 deep per-skill analysis → .opencode/state/classification.json + docs/skill-mapping.md
+      (done in phase 0; generator must regenerate mapping doc from classification.json — keep in 1.3 scope)
 - [ ] 2.2 guardrails plugin hook (opt-in, tool.hook execute.before on shell) + tests
-- [ ] 2.3 pocock-reviewer: implement or document rejection in decisions.md
+- [ ] 2.3 pocock-reviewer: CONFIRMED by analysis (D8) — implement template + skill-permission scoping
 - [ ] 2.4 orchestrator V2 flow wiring (background-subagent status in V2? batch fallback; worktree
       permission guidance; slash UX for user-invoked skills)
 - [ ] 2.5 per-skill regression checks + manual orchestration smoke (token-spending, documented)

docs/skill-mapping.md

@@ -0,0 +1,106 @@
+# Skill mapping — mattpocock/skills → OpenCode v2
+
+Upstream: `mattpocock/skills@49dd158` (v1.3.1, 2026-10-09). Analyzed 2026-10-14.
+Machine-readable source of truth: `.opencode/state/classification.json` (this doc will be generated
+from it once `scripts/generate.ts` exists — until then keep both in sync by hand).
+
+Validation status legend: `pending` = not yet runtime-verified (Phase 1.9); `validated` = loads and
+behaves correctly in a real OpenCode v2 session.
+
+## Summary
+
+| Classification | Count | Skills |
+| --- | --- | --- |
+| skill | 27 | all vendored verbatim; see matrix |
+| agent+skill | 1 | code-review (+ `pocock-reviewer` subagent) |
+| orchestrator | 2 | implement-spec (→ `pocock` + `pocock-worker`), chief-of-staff (excluded, in-progress) |
+| plugin | 1 | git-guardrails-claude-code (→ opt-in guardrails hook) |
+| not-convertible | 1 | claude-handoff (Claude-CLI-bound, excluded) |
+| agent (dedicated, no skill) | 0 | research evaluated → rejected as dedicated agent (D8) |
+
+Vendored: 31 skills (engineering 20, productivity 7, misc 4). Excluded: 7 in-progress + deprecated
+bucket (empty upstream). 23 of 31 vendored skills are user-invoked upstream
+(`disable-model-invocation: true`) → manifest sets `autoinvoke: false`; OpenCode v2 honors this
+natively (hidden from model auto-selection, still loadable via `/name` or explicit id).
+
+## Generated agents
+
+| Agent | Mode | Purpose | Key permissions |
+| --- | --- | --- | --- |
+| `pocock` | primary | Orchestrator: routes via ask-matt, walks grill→spec→tickets→build→review→retro, gates user-invoked skills behind explicit proposals, runs the implement-spec dispatch loop (integration branch, one worktree per ticket, frontier from own merge record, merges, cleanup) | edit/shell allow; destructive-git denies on main checkout; skill `*` allow; task allow |
+| `pocock-worker` | subagent | Builds one ticket test-first (tdd at the spec's seams) inside its prepared worktree; merges integration tip; reports; never pushes/PRs/stashes/worktrees; asks nothing | skill deny `*` + allow-list (tdd, codebase-design, diagnosing-bugs + stack skills); shell denies push/stash/reset --hard/clean/worktree/switch, gh pr/issue-close; edit allow |
+| `pocock-reviewer` | subagent | Read-only executor of one code-review axis (Standards or Spec) with the skill's fully-specified prompt; findings returned to the caller for verbatim aggregation | edit deny; shell allow git-read only; skill allow code-review only |
+
+Rejected agents (recorded so they are not re-proposed without new evidence): `pocock-researcher`
+(D8 — built-in `general` + the 12-line research brief is equivalent), per-phase agents
+(spec-writer/ticket-planner/debugger/... — Matt's phases are conversation steps sharing one context,
+not roles; splitting them shreds the grilling→spec context the methodology depends on), triage agent
+(every step waits on the maintainer), teach/tutor agent (continuous human dialogue).
+
+## Matrix
+
+DMI = `disable-model-invocation: true` upstream (user-invoked). All vendored skills ship verbatim
+(D1); "extra artifact" lists anything generated on top. Validation: all `pending` until Phase 1.9.
+
+| Upstream skill | Bucket | DMI | Classification | Extra artifact | Depends on (skill-tool) | Rationale (abridged; full text in classification.json) |
+| --- | --- | --- | --- | --- | --- | --- |
+| ask-matt | eng | ✓ | skill | informs `pocock` system | — | pure router prose; must stay in sync upstream, vendored as-is |
+| code-review | eng | | agent+skill | `pocock-reviewer` | — | two parallel isolated axis reviewers = dedicated read-only subagent; aggregation stays in caller |
+| codebase-design | eng | | skill | — | — | shared-vocabulary reference consumed by tdd et al. |
+| diagnosing-bugs | eng | | skill | — | — | six-phase inline discipline, no isolation needed |
+| domain-modeling | eng | | skill | — | — | dialogue discipline writing GLOSSARY/ADRs; isolation would break it |
+| grill-with-docs | eng | ✓ | skill | — | grilling, domain-modeling | 7-line wrapper; orchestrator verifies both loads (known upstream failure mode) |
+| implement | eng | ✓ | skill | embodied by `pocock-worker` | tdd, code-review | thin single-context per-ticket procedure |
+| implement-spec | eng | ✓ | orchestrator | `pocock`, `pocock-worker` | tdd, code-review | frontier + worktree fleet; OpenCode task tool lacks worktrees → agents supply them |
+| improve-codebase-architecture | eng | ✓ | skill | — | codebase-design, grilling, domain-modeling | interactive survey-and-grill; subagents are internal delegation |
+| pr | eng | | skill | — | — | PR-body template; verbatim vendoring preserves Dex Horthy attribution (metadata.credits, CREDITS.md) |
+| prototype | eng | | skill | — | — | throwaway-artifact generation procedure |
+| research | eng | | skill | — | — | the skill IS a background-agent brief; built-in `general` executes it (dedicated agent rejected, D8) |
+| retro | eng | ✓ | skill | — | writing-for-agents | mines the current session — must not be isolated |
+| setup-matt-pocock-skills | eng | ✓ | skill | — | — | creates `docs/agents/*` state that 7 skills hard-depend on; required first run per repo |
+| tdd | eng | | skill | — | codebase-design | the build discipline; worker allow-list core |
+| to-spec | eng | ✓ | skill | — | — | synthesis from conversation, no interview |
+| to-tickets | eng | ✓ | skill | — | — | decomposition + human approval loop |
+| triage | eng | ✓ | skill | — | grilling, domain-modeling | maintainer-driven state machine; agent rejected (HITL at every step) |
+| wayfinder | eng | ✓ | skill | — | grilling, domain-modeling, research, prototype | tracker-based map/fog/frontier protocol |
+| wizard | eng | | skill | — | — | bash-wizard generator; bundled template.sh ships with the skill dir |
+| grill-me | prod | ✓ | skill | — | grilling | 7-line stateless wrapper |
+| grilling | prod | | skill | — | — | the interview primitive; isolation would make it worse |
+| handoff | prod | ✓ | skill | — | — | handoff doc to OS temp dir |
+| teach | prod | ✓ | skill | — | — | stateful tutor; state lives in workspace files |
+| to-questionnaire | prod | ✓ | skill | — | — | interviews + questionnaire template |
+| wait-what | prod | ✓ | skill | — | — | 7-line re-pitch corrective |
+| writing-for-agents | prod | | skill | — | — | pure theory reference |
+| git-guardrails-claude-code | misc | | plugin | guardrails hook (opt-in) | — | Claude PreToolUse hook → OpenCode `ctx.tool.hook` on shell; skill text kept verbatim for reference |
+| migrate-to-shoehorn | misc | | skill | — | — | codemod recipe (frozen bucket) |
+| scaffold-exercises | misc | | skill | — | — | environment-bound: needs Matt's private `ai-hero-cli`; caveat documented, no fix possible |
+| setup-pre-commit | misc | | skill | — | — | husky/lint-staged recipe (frozen bucket) |
+| chief-of-staff | in-prog | ✓ | orchestrator | excluded (D6) | — | coordinator persona; revisit if upstream promotes |
+| claude-handoff | in-prog | ✓ | not-convertible | excluded (D6) | handoff | Claude-CLI `--bg` launcher; harness-bound |
+| loop-me | in-prog | ✓ | skill | excluded (D6) | grilling | workflow-spec grilling workspace |
+| setup-ts-deep-modules | in-prog | ✓ | skill | excluded (D6) | codebase-design | dependency-cruiser enforcement setup |
+| writing-beats | in-prog | ✓ | skill | excluded (D6) | writing-fragments | beat-by-beat exploit writing |
+| writing-fragments | in-prog | ✓ | skill | excluded (D6) | grilling | explore-phase fragment mining |
+| writing-shape | in-prog | ✓ | skill | excluded (D6) | writing-fragments | paragraph-level shaping |
+
+## Cross-cutting notes for the conversion
+
+- **Hard dependency chain**: `setup-matt-pocock-skills` writes `docs/agents/{issue-tracker,domain,
+  triage-labels}.md` + the `## Agent skills` block; to-spec, to-tickets, triage, implement,
+  implement-spec, code-review, wayfinder all break without it. README + pocock agent must flag it.
+- **Wrapper semantics**: grill-me/grill-with-docs/wait-what are 7-line compositions relying on
+  cross-skill invocation ("Call the Skill tool with X"). OpenCode's skill tool loads by name — the
+  loading agent must load both named skills itself (upstream docs report wrappers failing to chain;
+  pocock agent verifies).
+- **Invariant**: user-invoked skills are never callable from other skills upstream; V2's
+  `autoinvoke: false` reproduces exactly this (hidden from model, loadable by human via slash).
+- **Frontmatter census**: only `name`, `description`, `disable-model-invocation`, `argument-hint`
+  (4 skills), `metadata.credits` (pr) exist upstream — no allowed-tools/model/context fields, so all
+  permission/isolation design is ours (authored fresh in agent templates, not translated).
+- **`agents/openai.yaml`** in every skill dir is Codex UI metadata (display_name, short_description,
+  policy mirroring DMI) — stripped from the generated OpenCode tree by the generator.
+- **17 pending upstream changesets** (patch) target code-review, to-tickets, wayfinder, wizard, tdd,
+  teach, implement, grilling, handoff, diagnosing-bugs, ask-matt, setup — the next upstream release
+  will touch ~1/3 of the vendored skills; the nightly sync + drift tests are the safety net.
+- **scaffold-exercises** only works in Matt's course repos (private `ai-hero-cli`); vendored for
+  fidelity, documented as environment-bound.