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.