feat: skill generator with manifest, frontmatter parser and mapping-doc matrix

docs/skill-mapping.md

@@ -40,48 +40,55 @@ not roles; splitting them shreds the grilling→spec context the methodology dep
 ## 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.
+(D1); "Artifacts" lists everything generated for the skill. Status `analyzed` = classification
+reviewed by a human; `needs-review` = new upstream skill, drift test fails until reviewed. Runtime
+validation of every artifact is tracked in `.opencode/state/status.md` (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 |
+<!-- matrix:start -->
+
+| Upstream skill | Bucket | DMI | Classification | Artifacts | Depends on | Status | Rationale |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| ask-matt | eng | ✓ | skill | skill:verbatim |  | analyzed | Pure router prose over all skills; no execution or isolation. Its routing logic also informs the pocock agent's system prompt. |
+| code-review | eng |  | agent+skill | skill:verbatim, agent:pocock-reviewer |  | analyzed | 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. |
+| codebase-design | eng |  | skill | skill:verbatim |  | analyzed | 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. |
+| diagnosing-bugs | eng |  | skill | skill:verbatim |  | analyzed | Six-phase procedural discipline run inline; no isolation or special permissions needed. |
+| domain-modeling | eng |  | skill | skill:verbatim |  | analyzed | Interactive writing discipline + bundled format files (GLOSSARY/ADR); must run in the main conversation to challenge user wording - an isolated agent would break it. |
+| grill-with-docs | eng | ✓ | skill | skill:verbatim | grilling, domain-modeling | analyzed | 7-line composition wrapper; OpenCode skill tool loads the two named skills. Preserve verbatim; orchestrator verifies both load (known upstream wrapper failure mode). |
+| implement | eng | ✓ | skill | skill:verbatim | tdd, code-review | analyzed | Thin single-context per-ticket procedure composing tdd + code-review; the pocock-worker agent embodies its discipline for parallel builds. |
+| implement-spec | eng | ✓ | orchestrator | skill:verbatim, agent:pocock, agent:pocock-worker | tdd, code-review | analyzed | 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. |
+| improve-codebase-architecture | eng | ✓ | skill | skill:verbatim | codebase-design, grilling, domain-modeling | analyzed | Interactive survey-and-grill; its exploration/design-it-twice subagents are internal delegation via task tool, not its identity. |
+| pr | eng |  | skill | skill:verbatim |  | analyzed | Pure PR-body template/reference. Verbatim vendoring preserves required attribution (metadata.credits + CREDITS.md, Dex Horthy's show-me). |
+| prototype | eng |  | skill | skill:verbatim |  | analyzed | Generation procedure with two branch docs (LOGIC/UI); user reacts to artifacts in main conversation. |
+| research | eng |  | skill | skill:verbatim |  | analyzed | 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. |
+| retro | eng | ✓ | skill | skill:verbatim | writing-for-agents | analyzed | Analysis over the current session's history - isolating it in a subagent would starve it of the session context it mines. |
+| setup-matt-pocock-skills | eng | ✓ | skill | skill:verbatim |  | analyzed | 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. |
+| tdd | eng |  | skill | skill:verbatim | codebase-design | analyzed | The reusable build discipline; consumed by implement and every pocock-worker via skill allow-list. |
+| to-spec | eng | ✓ | skill | skill:verbatim |  | analyzed | Synthesis + template + publish procedure; explicitly no interview, needs main-conversation context (grilling output). |
+| to-tickets | eng | ✓ | skill | skill:verbatim |  | analyzed | Decomposition with human approval loop; needs the spec conversation in context. |
+| triage | eng | ✓ | skill | skill:verbatim | grilling, domain-modeling | analyzed | 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. |
+| wayfinder | eng | ✓ | skill | skill:verbatim | grilling, domain-modeling, research, prototype | analyzed | Stateful planning protocol over the tracker (map/fog/frontier); its research dispatches use the research skill + built-in subagents. |
+| wizard | eng |  | skill | skill:verbatim |  | analyzed | Code generator with bundled template.sh asset; the generated artifact is a human-run script, no harness integration needed. |
+| grill-me | prod | ✓ | skill | skill:verbatim | grilling | analyzed | 7-line stateless wrapper around grilling. |
+| grilling | prod |  | skill | skill:verbatim |  | analyzed | 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. |
+| handoff | prod | ✓ | skill | skill:verbatim |  | analyzed | Document-generation instructions writing to OS temp dir. |
+| teach | prod | ✓ | skill | skill:verbatim |  | analyzed | 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. |
+| to-questionnaire | prod | ✓ | skill | skill:verbatim |  | analyzed | Two structured interviews + document template. |
+| wait-what | prod | ✓ | skill | skill:verbatim |  | analyzed | 7-line corrective re-pitch instruction, usable mid-any-skill. |
+| writing-for-agents | prod |  | skill | skill:verbatim |  | analyzed | Pure theory reference; the most instructions-only skill in the repo. |
+| git-guardrails-claude-code | misc |  | plugin | skill:verbatim, plugin:guardrails |  | analyzed | 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. |
+| migrate-to-shoehorn | misc |  | skill | skill:verbatim |  | analyzed | Mechanical codemod recipe. Frozen misc bucket - vendored as-is. |
+| scaffold-exercises | misc |  | skill | skill:verbatim |  | analyzed | 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. |
+| setup-pre-commit | misc |  | skill | skill:verbatim |  | analyzed | Setup recipe, npm ecosystem only. Frozen misc bucket - vendored as-is. |
+| chief-of-staff | in-prog | ✓ | orchestrator | excluded |  | analyzed | EXCLUDED per D6 (in-progress beta). Would map to a coordinator persona over background subagents; revisit only if upstream promotes it. |
+| claude-handoff | in-prog | ✓ | not-convertible | excluded | handoff | analyzed | 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. |
+| loop-me | in-prog | ✓ | skill | excluded | grilling | analyzed | EXCLUDED per D6 (in-progress). Grilling + workflows/*.md workspace convention; converts trivially if promoted. |
+| setup-ts-deep-modules | in-prog | ✓ | skill | excluded | codebase-design | analyzed | EXCLUDED per D6 (in-progress). Dependency-cruiser setup with bundled config + prove-it-bites self-check; converts cleanly if promoted. |
+| writing-beats | in-prog | ✓ | skill | excluded | writing-fragments | analyzed | EXCLUDED per D6 (in-progress). |
+| writing-fragments | in-prog | ✓ | skill | excluded | grilling | analyzed | EXCLUDED per D6 (in-progress). |
+| writing-shape | in-prog | ✓ | skill | excluded | writing-fragments | analyzed | EXCLUDED per D6 (in-progress). |
+
+<!-- matrix:end -->
 
 ## Cross-cutting notes for the conversion