@webpresso/opencode-plugin 3.1.11 → 3.1.13

package/skills/deep-research/SKILL.md

@@ -0,0 +1,258 @@
+---
+type: skill
+slug: deep-research
+title: Deep Research
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: "2026-05-07"
+last_reviewed: "2026-05-07"
+name: deep-research
+description: "Deep web research with dated credible sources, pro/con synthesis, and project-alignment notes."
+argument-hint: "<subject or question to research>"
+---
+
+<Purpose>
+Deep Research is a multi-phase web research workflow that produces a balanced, citation-backed analysis of a subject. It collects both positive and negative sentiments from credible sources, evaluates alignment with the project's vision and tech stack, identifies 2026 state-of-the-art best practices, and logs the result to `docs/research/` with a date-prefixed filename.
+</Purpose>
+
+<Use_When>
+
+- Evaluating a technology, library, pattern, or product direction
+- Comparing alternatives before making an architectural or product decision
+- The user says "research", "deep research", "investigate", or "what does the community think about"
+- You need a balanced view of trade-offs before recommending something
+  </Use_When>
+
+<Do_Not_Use_When>
+
+- The user wants a quick factual lookup (use WebSearch directly)
+- The user wants codebase exploration (use explore)
+- The user wants a requirements interview (use deep-interview)
+- The answer is already well-established and non-controversial
+  </Do_Not_Use_When>
+
+<Output_Contract>
+A single markdown file written to:
+
+```
+docs/research/{YYYY-MM-DD}-{slug}.md
+```
+
+Where `{YYYY-MM-DD}` is today's date and `{slug}` is a kebab-case summary of the subject.
+
+The file MUST have this frontmatter and structure (see Phase 5 for full template).
+</Output_Contract>
+
+<Steps>
+
+## Phase 0: Scope and Context Load
+
+1. Parse `{{ARGUMENTS}}` into a research subject and any qualifiers (e.g., "for our use case", "vs X").
+2. Derive a short kebab-case slug for the filename.
+3. Read `docs/research/product/VISION.md` (or the project's equivalent — check `docs/` for a vision doc) to load the current vision context. Skip if not present.
+4. Identify the relevant tech stack context by reading project config files (e.g., `package.json` workspaces, `tsconfig.json`, key dependencies) — keep this lightweight, just enough to judge alignment.
+5. Announce the research plan to the user:
+   - Subject
+   - Key questions to investigate
+   - Output path
+
+## Phase 1: Broad Discovery (parallel)
+
+Run **5-8 parallel WebSearch queries** covering different angles:
+
+1. **Overview**: `"{subject} 2026 overview best practices"`
+2. **Positive sentiment**: `"{subject} benefits advantages why use 2026"`
+3. **Negative sentiment / criticism**: `"{subject} problems criticism drawbacks 2026"`
+4. **Community opinion**: `"{subject} reddit hacker news experience production 2026"`
+5. **Comparison / alternatives**: `"{subject} vs alternatives comparison 2026"`
+6. **State of the art**: `"{subject} state of the art latest 2026"`
+7. **(If applicable)** Stack-specific: `"{subject} TypeScript Cloudflare Workers React 2026"`
+8. **(If applicable)** Domain-specific query based on the project's problem space
+
+For each search, record:
+
+- Source URL
+- Source type (docs, blog, forum, official, academic)
+- Key claims or data points
+- Sentiment direction (positive / negative / neutral)
+
+## Phase 2: Deep Dive (sequential, selective)
+
+From Phase 1 results, identify the **5-10 most credible and information-dense sources**.
+
+Use `WebFetch` on each to extract deeper detail. Prioritize:
+
+- Official documentation or announcements
+- Production experience reports (postmortems, migration stories)
+- Benchmark data or technical comparisons
+- Strong critical takes with specific evidence
+
+For each fetched source, extract:
+
+- Specific claims with evidence
+- Sentiment and strength (strong positive, mild positive, neutral, mild negative, strong negative)
+- Credibility assessment (official docs > production experience > blog opinion > forum anecdote)
+
+## Phase 3: Triangulate and Score
+
+1. **Cluster findings** into themes (e.g., "developer experience", "performance", "ecosystem maturity", "production readiness").
+2. **Cross-reference claims**: if only one source makes a claim, flag it as unverified. Claims supported by 2+ independent sources get higher weight.
+3. **Score source credibility** using:
+   - Official docs / specs: high
+   - Production postmortems with data: high
+   - Respected engineering blogs: medium-high
+   - Community forums (HN, Reddit) with detail: medium
+   - Marketing material / vendor blogs: low (note bias)
+   - Undated or anonymous content: very low
+4. **Identify gaps**: what questions remain unanswered? If critical gaps exist, run 1-2 additional targeted searches.
+
+## Phase 4: Vision and Stack Alignment Analysis
+
+Using the project's vision from Phase 0 and the research findings:
+
+1. **Vision alignment**: How does this subject relate to the project's stated mission? Does it help or hinder current priorities?
+2. **Tech stack fit**: How well does this integrate with the existing stack (read `package.json`, key deps, framework choices)? What's the integration cost?
+3. **Trade-off assessment**: Given the project's current stage, what are the most relevant trade-offs?
+4. **Recommendation**: Based on the evidence, what's the suggested path? Be explicit about confidence level.
+
+## Phase 5: Write Report
+
+Write the report to `docs/research/{YYYY-MM-DD}-{slug}.md` using this template:
+
+```markdown
+---
+type: research
+title: "{Title}"
+subject: "{subject}"
+date: { YYYY-MM-DD }
+confidence: { high|medium|low }
+verdict: { adopt|trial|assess|hold|reject }
+---
+
+# {Title}
+
+> One-line summary of the finding.
+
+## TL;DR
+
+3-5 bullet executive summary covering: what it is, key finding, recommendation.
+
+## What This Is
+
+Brief neutral description of the subject being researched.
+
+## State of the Art (2026)
+
+Current best practices, latest developments, where the ecosystem stands today.
+Cite sources inline as [Source Name](url).
+
+## Positive Signals
+
+Evidence-backed reasons in favor. Group by theme.
+Each point should cite its source and note credibility level.
+
+### {Theme 1}
+
+- ...
+
+### {Theme 2}
+
+- ...
+
+## Negative Signals
+
+Evidence-backed criticism and risks. Group by theme.
+Each point should cite its source and note credibility level.
+
+### {Theme 1}
+
+- ...
+
+### {Theme 2}
+
+- ...
+
+## Community Sentiment
+
+What practitioners actually say. Include direct quotes where available.
+Note the balance: if sentiment skews one way, say so explicitly.
+
+## Project Alignment
+
+### Vision Fit
+
+How this relates to the project's current goals.
+
+### Tech Stack Fit
+
+Integration with the project's stack (from `package.json`, framework configs).
+
+### Trade-offs for Current Stage
+
+What matters most given where the project is now.
+
+## Recommendation
+
+Clear recommendation with confidence level and reasoning.
+Include conditions under which the recommendation would change.
+
+## Sources
+
+Numbered list of all sources used, with:
+
+- [N] [Title](url) — type, credibility, sentiment direction
+```
+
+## Phase 6: Present Summary
+
+After writing the file, present to the user:
+
+1. The output file path
+2. The verdict and confidence
+3. A 3-line summary of the key finding
+4. Any critical gaps or caveats
+
+</Steps>
+
+<Quality_Gates>
+
+- Minimum 8 distinct sources cited
+- At least 2 sources per major claim
+- Both positive AND negative signals sections must be substantive (not token)
+- Sources section must include credibility and sentiment annotations
+- Vision alignment section must reference specific project goals (not generic)
+- All inline citations must be clickable links
+- Frontmatter must include confidence and verdict fields
+  </Quality_Gates>
+
+<Verdict_Scale>
+
+- **adopt**: Strong evidence, clear fit, community consensus positive. Use it.
+- **trial**: Promising evidence, worth a bounded experiment. Try it in a limited scope.
+- **assess**: Mixed signals or insufficient evidence. Research more before committing.
+- **hold**: Significant concerns or poor fit. Don't invest now, revisit later.
+- **reject**: Clear evidence against. Don't use this.
+  </Verdict_Scale>
+
+<Tool_Usage>
+
+- `WebSearch` for broad discovery (Phase 1) and gap-filling (Phase 3)
+- `WebFetch` for deep source extraction (Phase 2)
+- `Read` for loading vision and tech stack context (Phase 0)
+- `Write` for the final report (Phase 5)
+- `Agent` with `subagent_type=Explore` if codebase context is needed for alignment analysis
+- Use parallel tool calls wherever searches are independent
+  </Tool_Usage>
+
+<Common_Mistakes>
+
+- Writing a report that's all positive or all negative — always find both sides
+- Citing marketing material as if it were neutral evidence — flag vendor bias
+- Making alignment claims without reading the actual vision doc
+- Using stale search results — always include "2026" in queries
+- Writing the report before triangulating — don't just concatenate search results
+  </Common_Mistakes>
+
+Task: {{ARGUMENTS}}

package/skills/design-review/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: design-review
+description: "Report-first visual/browser design audit for hierarchy, spacing, consistency, responsive, a11y, and interactions."
+license: MIT
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+---
+
+# Design review
+
+Use for live visual QA or design polish requests. For pre-implementation plan critique, use `/plan-design-review`.
+
+## Default behavior
+
+- The `allowed-tools` frontmatter is an audited disclosure for supported hosts;
+  pretool-guard remains the enforced mutation backstop when a host does not prove
+  skill-frontmatter enforcement.
+- Report first; do not edit source unless the user explicitly asks for fixes.
+- Inspect key viewports and states.
+- Capture evidence with browser screenshots or precise observations.
+- Rank findings by user impact and implementation effort.
+
+If fixes are authorized, make small visual changes and verify before/after.

package/skills/devex-review/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: devex-review
+description: "Report-first developer-experience audit for onboarding, docs, examples, CLI help, and time-to-hello-world."
+license: MIT
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+---
+
+# Live DX review
+
+Use after or during developer-facing work to test the real user journey.
+
+This is report-only by default. The `allowed-tools` frontmatter is an audited
+disclosure for supported hosts; pretool-guard remains the enforced mutation
+backstop when a host does not prove skill-frontmatter enforcement.
+
+## Evidence to gather
+
+- Docs route or README entrypoint.
+- Install/setup command path.
+- CLI help and error messages.
+- Time-to-hello-world estimate.
+- Browser evidence for docs or local app flows when relevant.
+
+Return a scorecard with blockers, papercuts, screenshots/artifacts when available, and concrete next fixes.

package/skills/fix/SKILL.md

@@ -0,0 +1,129 @@
+---
+type: skill
+slug: fix
+title: Fix
+status: active
+scope: repo
+applies_to: [agents]
+related: [verify, testing-philosophy]
+created: "2026-05-13"
+last_reviewed: "2026-05-22"
+name: fix
+description: "Root-cause fix workflow for bugs, failures, regressions, and errors; reproduce, repair owner, test, verify."
+argument-hint: '<target> where target is: file|symptom|error|test|"free-text description"'
+---
+
+# Fix Command
+
+Fix the issue at its root, future-proof, aligned with repo philosophy.
+
+**Arguments**: $ARGUMENTS
+
+This command turns "please fix it well" into an enforceable workflow: reproduce, identify the broken invariant, repair it at the owner, prove the repair, and escalate to `/verify` when the blast radius is broader than a local fix.
+
+## Merged debugging discipline
+
+`/investigate` and `systematic-debugging` are folded into this workflow. Keep the
+old iron law: no fixes before evidence. Reproduce or capture the failure, read
+the complete error/stack, trace the bad value or broken invariant to its owner,
+compare with a working local pattern, and disconfirm cheap hypotheses before
+editing. If the issue crosses component boundaries, add temporary diagnostics at
+each boundary, run once, then remove or convert them to durable tests.
+
+## Non-negotiable invariants
+
+1. **Root cause, not symptom.** Trace the failure to the invariant that actually broke. Do not patch callers when the owner is fixable.
+2. **Loud failures, no silent fallbacks.** No default shims, sentinel returns, or catch-and-continue behavior that hides missing config, bad state, or broken boundaries.
+3. **Use the repo's real execution surface.** Prefer repo-owned wrappers and injected routing guidance over host-specific tool assumptions. If the repo exposes quality wrappers, use them. Use bounded inspection paths for large-output investigation.
+4. **Regression proof is mandatory.** Add or strengthen a test or other reliable proof that would fail against the old behavior.
+5. **Raising timeouts is not a fix.** If a timeout fires, investigate the bottleneck. Only raise a bound when the repo already documents that workload and you can cite measurement.
+6. **Zero suppressions, zero papering over.** No lint disables, ts-ignore, compat aliases, or "temporary" branches to sneak the fix through.
+7. **Minimal correct diff.** Update every consumer of a changed contract in the same change, but do not bundle unrelated cleanup.
+
+## Protocol
+
+### Step 1 — Reproduce and name the broken invariant
+
+- Run the exact command, test, or user flow that surfaces the failure.
+- Capture the evidence that matters: error text, file:line, exit code, failing assertion, or log path.
+- Read enough surrounding code to say the broken invariant in one sentence.
+- If the issue is nondeterministic, gather evidence until you can describe the slow/flaky/failing case without guessing.
+
+If the "issue" is actually several unrelated failures, stop and ask which one to fix first.
+
+### Step 2 — Decide where the fix belongs
+
+State briefly:
+
+- the broken invariant
+- the owner that should enforce it
+- whether the fix changes a public contract
+- which direct consumers must change in the same diff
+
+If the blast radius is broader than the owner + direct consumers, keep going with `/fix` only if the change is still one coherent repair. If the work becomes a broader hardening pass, plan a `/verify` handoff before claiming done.
+
+### Step 3 — Write failing proof first when feasible
+
+- For a reproducible bug, write or strengthen the smallest regression test that fails on the old behavior.
+- Verify that it fails for the right reason before changing production code.
+- If test-first is genuinely infeasible at that boundary, record why and create the nearest reliable proof instead (for example a deterministic integration reproduction, fixture, or logged command).
+
+Do not keep production code written before the test as "reference". If you wrote code first, throw it away and restart from the failing proof.
+
+### Step 4 — Implement the minimal correct fix
+
+- Edit the file or module that owns the invariant.
+- Update every changed consumer in the same diff. No half-migrations.
+- Delete compat shims, dead aliases, and TODO branches made obsolete by the repair.
+- Keep complexity down by extracting helpers instead of nesting conditionals.
+
+### Step 5 — Run scoped verification
+
+Run the narrowest checks that prove the repaired behavior on the real repo surface:
+
+- targeted test(s) for the repaired path
+- targeted lint/typecheck/build checks for changed files or packages
+- any boundary-specific verification the repo requires for the touched surface
+
+Rules:
+
+- Prefer repo-owned wrappers or routed quality tools over raw host-specific commands.
+- Reuse fresh logs if the repo auto-saves them; do not re-run long commands just to re-read output.
+- Read the exit code and summary before making a claim.
+
+Escalate to `/verify <target>` when any of these are true:
+
+- the fix crosses packages
+- the fix changes a public or shared contract
+- the fix touched docs, plans, blueprints, or repo SSOT
+- the fix needs dead-code / compat / broad regression review before claiming done
+
+### Step 6 — Report with evidence
+
+Keep it short:
+
+- what invariant broke
+- how the change restores it
+- what proof ran (tests, commands, log paths, exit codes)
+- adjacent issues noticed but intentionally not fixed
+
+## Done looks like
+
+- [ ] Root cause named in one sentence
+- [ ] Fix applied at the owning boundary
+- [ ] Regression proof fails against the old behavior
+- [ ] Minimal code change restores the invariant
+- [ ] Scoped verification passed on the changed surface
+- [ ] `/verify` handoff used when blast radius exceeded a local fix
+- [ ] Report cites evidence, not intent
+
+## Anti-patterns this command refuses
+
+- Fixing the nearest symptom while leaving the real invariant broken
+- Catching an error and returning a sentinel to "keep things moving"
+- Raising a timeout, retry count, or polling interval instead of finding the bottleneck
+- Adding a deprecated alias instead of updating consumers
+- Introducing `any`, suppressions, or lint disables to unblock the fix
+- Bundling unrelated refactors with the repair
+- Claiming done from intuition, partial output, or another agent's success message
+- Writing a planning/doc artifact when the user asked for a fix

package/skills/goal/SKILL.md

@@ -0,0 +1,27 @@
+---
+type: skill
+slug: goal
+title: Goal
+status: active
+scope: repo
+applies_to: [agents]
+related: [autopilot, plan-refine, verify]
+created: "2026-07-10"
+last_reviewed: "2026-07-10"
+name: goal
+description: "Run durable multi-blueprint goals through evidence-gated handoffs."
+argument-hint: "<new|status|handoff|run|cancel> [brief]"
+---
+
+# Goal
+
+Use `wp goal` as the durable controller for work spanning one or more blueprints.
+
+## Protocol
+
+1. Create or resume the goal in a managed blueprint owner worktree.
+2. Read `wp goal status`, execute only the current phase handoff, then call `wp goal run` again.
+3. Complete blueprint tasks only through `wp_blueprint_task_verify` with passing evidence.
+4. Stop when the controller reports `complete`, `cancelled`, blocked guard exhaustion, or `WP_GOAL_DISABLE=1`.
+
+The blueprint engine owns task status and approval gates. The goal controller must never self-approve, directly mark a task done, bypass review provenance, or mutate the primary checkout. Keep every loop bounded and never increase timeouts.

package/skills/hooks-doctor/SKILL.md

@@ -0,0 +1,78 @@
+---
+type: skill
+slug: hooks-doctor
+title: Hooks Doctor
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: "2026-05-07"
+last_reviewed: "2026-05-07"
+name: hooks-doctor
+description: "Webpresso hook/plugin doctor: verify install health and debug broken hooks or plugin integration."
+argument-hint: "[--skip-mcp]"
+allowed-tools:
+  - Bash
+---
+
+# Hooks Doctor
+
+Verify the webpresso plugin hooks installation is healthy. Run this first when:
+
+- A hook seems not to be firing
+- The plugin was just installed or updated
+- Claude Code can't find expected tools
+- Any plugin integration issue arises
+
+## Running the Check
+
+Run the doctor command directly:
+
+```
+wp hooks doctor
+```
+
+Or skip the MCP server check (for CI environments):
+
+```
+wp hooks doctor --skip-mcp
+```
+
+## Interpreting Results
+
+Each check prints `[x]` (pass) or `[ ]` (fail) with a detail line:
+
+```
+[x] pretool-guard
+[x] post-tool (lint-after-edit)
+[x] stop (qa-changed-files)
+[x] guard-switch
+[x] sessionstart
+[x] test-quality-check
+[x] plugin.json integrity
+[x] MCP server liveness: MCP server already running (sentinel found)
+```
+
+## Failure Remediation
+
+| Check                                            | Likely Cause                                                   | Fix                                                            |
+| ------------------------------------------------ | -------------------------------------------------------------- | -------------------------------------------------------------- |
+| `pretool-guard` / `post-tool` / etc. — not found | `pnpm build` not run after install                             | `pnpm build`                                                   |
+| `pretool-guard` / etc. — not executable          | `chmod +x` not persisted                                       | Re-run `pnpm prepare` or `pnpm build` which runs `chmod-bins`  |
+| `plugin.json integrity` — missing                | Claude adapter manifest absent from `@webpresso/claude-plugin` | Re-run `wp setup --host claude` or reinstall the Claude plugin |
+| `MCP server liveness` — timeout                  | MCP server cold-start too slow                                 | Wait and retry, or run `wp hooks doctor --skip-mcp`            |
+| Any check — not found at `dist/esm/...`          | Build artifacts missing                                        | Run `pnpm build` in the webpresso repo                         |
+
+After fixing, re-run `wp hooks doctor` to confirm.
+
+## How It Works
+
+The doctor runs five categories of checks:
+
+1. **Bin existence** — each hook binary exists at the expected `dist/esm/hooks/...` path
+2. **Executable bit** — bins have execute permission (skipped on Windows)
+3. **stdin response** — interactive hooks (`pretool-guard`, `guard-switch`, `sessionstart`) respond to `{}` input with valid JSON and exit 0; fire-and-forget hooks (`lint-after-edit`, `qa-changed-files`) exit 0
+4. **plugin.json integrity** — adapter manifest exists, has required fields, and all referenced bins exist on disk
+5. **MCP server liveness** — spawns the MCP server and sends a `tools/list` JSON-RPC request; times out at 5s (soft-fail — warning only, does not fail the overall check)
+
+If `isMcpReady()` detects a live MCP sentinel, the MCP check fast-passes without spawning.

package/skills/lore-protocol/SKILL.md

@@ -0,0 +1,84 @@
+---
+type: skill
+slug: lore-protocol
+title: lore-protocol
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: "2026-05-07"
+last_reviewed: "2026-05-07"
+name: lore-protocol
+description: "Manual Lore commit-message trailers with wp audit commit-message; no hook enforcement because PRs squash."
+---
+
+# lore-protocol
+
+Use Lore commit-message trailers manually with `wp audit commit-message`. Hook enforcement is intentionally not installed because this repo uses squash commits.
+
+Lore is a lightweight protocol for embedding decision context directly into
+commit messages — constraints, rejected alternatives, confidence, and
+forward-looking directives — so future engineers understand _why_ a change
+was made, not just _what_ changed.
+
+## Quick start
+
+```bash
+# Validate a commit message file (hard-fail mode — exits non-zero on violations)
+wp audit commit-message --message-file .git/COMMIT_EDITMSG --require-lore
+
+# Soft-warn mode — emits warnings but always exits 0 (adoption ramp)
+wp audit commit-message --message-file .git/COMMIT_EDITMSG --lore-warn
+
+# Opt in per-commit by adding [lore] to the subject line:
+# feat(auth): prevent silent session drops [lore]
+```
+
+## Hook policy
+
+Lore trailers are advisory/manual. Do not install commit-msg or pre-push hooks for Lore enforcement; squash commits are the durable review boundary.
+
+## Trailer format
+
+```
+<intent line: why the change was made, not what changed>
+
+<body: narrative context — constraints, approach rationale>
+
+Constraint: <external constraint that shaped the decision>
+Rejected: <alternative considered> | <reason for rejection>
+Confidence: <low|medium|high>
+Scope-risk: <narrow|moderate|broad>
+Directive: <forward-looking warning for future modifiers>
+Tested: <what was verified>
+Not-tested: <known gaps in verification>
+```
+
+## Required trailers (for `--require-lore` or `[lore]` subject tag)
+
+| Trailer                                      | Required     | Allowed values                   |
+| -------------------------------------------- | ------------ | -------------------------------- |
+| `Confidence:`                                | yes          | `low`, `medium`, `high`          |
+| `Constraint:` or `Rejected:` or `Directive:` | at least one | free text                        |
+| `Scope-risk:`                                | optional     | `narrow`, `moderate`, `broad`    |
+| `Reversibility:`                             | optional     | `clean`, `messy`, `irreversible` |
+| `Tested:`                                    | optional     | free text                        |
+| `Not-tested:`                                | optional     | free text                        |
+| `Related:`                                   | optional     | free text                        |
+
+## Example commit
+
+```
+Prevent silent session drops during long-running operations
+
+The auth service returns inconsistent status codes on token
+expiry, so the interceptor catches all 4xx responses.
+
+Constraint: Auth service does not support token introspection
+Rejected: Extend token TTL to 24h | security policy violation
+Confidence: high
+Scope-risk: narrow
+Directive: Error handling is broad — do not narrow without verifying upstream behavior
+Tested: Single expired token refresh (unit)
+Not-tested: Auth service cold-start > 500ms behavior
+```