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

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.