107 lines
9.3 KiB
Markdown
107 lines
9.3 KiB
Markdown
# 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.
|