@webpresso/claude-plugin 3.1.3

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/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
+```

package/skills/opencode-go/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: opencode-go
+description: "OpenCode Go aggregate outside-voice reviewer for read-only plan, code, or implementation critique."
+license: MIT
+---
+
+# OpenCode Go aggregate reviewer via OpenCode Go
+
+Use when the user asks for an OpenCode Go aggregate reviewer / OpenCode Go review. Treat output as external advice until independently verified.
+
+## Model routing
+
+Rendered from the committed OpenCode reviewer policy. It does not hardcode model IDs; it resolves the live `opencode models opencode-go` catalog.
+Use the aggregate reviewer when the user wants an OpenCode Go review but did not specify a family. The default outside-voice lane is Kimi K2.7 Code first for coding quality, then DeepSeek V4 Pro for deeper review depth, then DeepSeek V4 Flash for cheap/high-availability follow-up passes; only after that should it fall back to the remaining families.
+Use the aggregate reviewer for general outside-voice plan critique, implementation review, or when the user wants the current best OpenCode Go lane without naming a family.
+
+## Auth and availability check
+
+```bash
+opencode providers list >/dev/null
+opencode models opencode-go >/dev/null
+```
+
+## Portable prompt file
+
+```bash
+PROMPT_FILE=$(mktemp -t wp-opencode-go-review.XXXXXX)
+trap 'rm -f "$PROMPT_FILE"' EXIT
+```
+
+## Review command
+
+Use read-only prompts. Run from the repo directory; do NOT pass `--dir "$PWD"` because opencode already uses the current directory and the extra index can stall reviews.
+
+```bash
+# Aggregate reviewer: honor the canonical reviewer policy (Kimi K2.7 Code → DeepSeek V4 Pro → DeepSeek V4 Flash first, then cross-family fallbacks).
+CATALOG=$(opencode models opencode-go)
+MODEL=$(echo "$CATALOG" | grep '^opencode-go/kimi' | grep -- '-code$' | sort -V | tail -1)
+[ -z "$MODEL" ] && MODEL=$(echo "$CATALOG" | grep '^opencode-go/deepseek' | grep -- '-pro$' | sort -V | tail -1)
+[ -z "$MODEL" ] && MODEL=$(echo "$CATALOG" | grep '^opencode-go/deepseek' | grep -- '-flash$' | sort -V | tail -1)
+[ -z "$MODEL" ] && MODEL=$(echo "$CATALOG" | grep '^opencode-go/qwen' | grep -- '-max$' | sort -V | tail -1)
+[ -z "$MODEL" ] && MODEL=$(echo "$CATALOG" | grep '^opencode-go/glm' | sort -V | tail -1)
+[ -z "$MODEL" ] && MODEL=$(echo "$CATALOG" | grep '^opencode-go/minimax' | sort -V | tail -1)
+[ -z "$MODEL" ] && MODEL=$(echo "$CATALOG" | grep '^opencode-go/mimo' | grep -- '-pro$' | sort -V | tail -1)
+[ -z "$MODEL" ] && MODEL=$(echo "$CATALOG" | sort -V | tail -1)
+
+# Fail fast on blocked quota before launching a long review.
+[ -n "$MODEL" ] || { echo "No OpenCode Go model resolved for this reviewer." >&2; exit 2; }
+OPENCODE_GO_REVIEW_EFFORT=${OPENCODE_GO_REVIEW_EFFORT:-medium}
+[ "$OPENCODE_GO_REVIEW_EFFORT" = medium ] || [ "$OPENCODE_GO_REVIEW_EFFORT" = high ] || { echo "OPENCODE_GO_REVIEW_EFFORT must be one of: medium, high" >&2; exit 2; }
+OPENCODE_GO_PROBE_TIMEOUT=${OPENCODE_GO_PROBE_TIMEOUT:-20}
+PROBE_LOG=$(mktemp -t wp-opencode-go-probe.XXXXXX)
+PROBE_RC=0
+node - "$MODEL" "$OPENCODE_GO_PROBE_TIMEOUT" "$PROBE_LOG" "$OPENCODE_GO_REVIEW_EFFORT" <<'JS' || PROBE_RC=$?
+const { spawnSync } = require('node:child_process')
+const { writeFileSync } = require('node:fs')
+
+const [model, timeoutSecondsRaw, logPath, reviewEffort] = process.argv.slice(2)
+const timeoutSeconds = Number(timeoutSecondsRaw)
+if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) {
+  console.error('OPENCODE_GO_PROBE_TIMEOUT must be a positive number of seconds')
+  process.exit(2)
+}
+
+const result = spawnSync(
+  'opencode',
+  ['run', '--format', 'json', '--variant', reviewEffort, '--model', model, '--title', 'opencode-go-credit-probe', 'Reply exactly OPENCODE_GO_OK.'],
+  { encoding: 'utf8', timeout: timeoutSeconds * 1000, maxBuffer: 1024 * 1024 },
+)
+
+let output = ''
+if (result.stdout) output += result.stdout
+if (result.stderr) output += result.stderr
+if (result.error?.code === 'ETIMEDOUT') {
+  output += `\nOPENCODE_GO_PROBE_TIMEOUT after ${timeoutSeconds}s\n`
+  writeFileSync(logPath, output)
+  process.exit(124)
+}
+if (result.error) {
+  output += `${result.error.message}\n`
+  writeFileSync(logPath, output)
+  process.exit(1)
+}
+writeFileSync(logPath, output)
+process.exit(typeof result.status === 'number' ? result.status : 1)
+JS
+if [ "$PROBE_RC" -ne 0 ]; then
+  echo "OpenCode Go probe failed or timed out for $MODEL after ${OPENCODE_GO_PROBE_TIMEOUT}s; skipping this reviewer instead of starting the full review." >&2
+  sed -n '1,80p' "$PROBE_LOG" >&2
+  rm -f "$PROBE_LOG"
+  exit "$PROBE_RC"
+fi
+rm -f "$PROBE_LOG"
+opencode run --variant "$OPENCODE_GO_REVIEW_EFFORT" --model "$MODEL" "$(cat "$PROMPT_FILE")"
+```
+
+If `$MODEL` is empty, run `opencode models opencode-go` and choose a present reviewer.

package/skills/plan-ceo-review/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: plan-ceo-review
+description: "CEO/founder plan review for scope, ambition, customer value, sequencing, and whether the plan is the right bet."
+license: MIT
+---
+
+# CEO plan review
+
+Review the plan as a founder accountable for product leverage and customer value.
+
+## Modes
+
+Choose one mode explicitly:
+
+- **Scope expansion:** the plan is too timid; propose a bigger wedge.
+- **Selective expansion:** keep the core but add one or two high-leverage improvements.
+- **Hold scope:** ambition is right; demand sharper execution and proof.
+- **Scope reduction:** remove distracting work and ship the smallest valuable slice.
+
+## Review checklist
+
+1. Who urgently wants this outcome and why now?
+2. What is the 10-star version, and what is the smallest credible slice of it?
+3. What should be deleted because it does not advance the wedge?
+4. What proof will convince us the work mattered?
+
+Return a verdict, the recommended mode, and specific plan edits.

package/skills/plan-design-review/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: plan-design-review
+description: "Designer plan review for UI/UX clarity, hierarchy, interaction quality, accessibility, and visual coherence."
+license: MIT
+---
+
+# Design plan review
+
+Review the plan as a product designer before code is written.
+
+## Scorecard
+
+Rate each dimension from 0-10 and explain what would make it a 10:
+
+- User intent and primary task clarity
+- Information hierarchy and content structure
+- Interaction states and error recovery
+- Accessibility and keyboard/screen-reader paths
+- Visual coherence, spacing, and affordances
+- Responsiveness and empty/loading states
+
+## Output
+
+- Overall score and verdict
+- Top three design risks
+- Minimal plan edits that improve the score
+- Acceptance criteria for visual and accessibility verification

package/skills/plan-devex-review/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: plan-devex-review
+description: "Developer-experience plan review for onboarding, docs, CLI/API ergonomics, migration risk, and time-to-hello-world."
+license: MIT
+---
+
+# Developer-experience plan review
+
+Use before implementing developer-facing features, setup flows, CLIs, docs, SDKs, or migrations.
+
+## Review checklist
+
+- Who is the developer and what are they trying to do?
+- Is the first successful path obvious and short?
+- Are errors actionable and copy-pastable?
+- Does the plan preserve existing workflows and migration safety?
+- What docs, examples, and smoke tests prove the experience?
+
+Return DX score, blockers, simplifications, and acceptance tests.

package/skills/plan-eng-review/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: plan-eng-review
+description: "Engineering-manager plan review for architecture, data flow, sequencing, edge cases, tests, and rollout risk."
+license: MIT
+---
+
+# Engineering plan review
+
+Review the plan as an engineering manager who must make it safe to execute.
+
+## Process
+
+1. Identify the target outcome, non-goals, constraints, owners, and stop condition.
+2. Map the implementation path: changed files, data flow, public interfaces, migrations, and backward-compatibility concerns.
+3. List edge cases and failure modes by severity.
+4. Check test shape: unit, integration, e2e, fixtures, regression coverage, and verification commands.
+5. Recommend the smallest plan repair that materially reduces risk.
+
+## Output
+
+- **Verdict:** ready / ready with edits / not ready
+- **Blocking issues:** concrete fixes required before coding
+- **Recommended edits:** concise patch-level plan changes
+- **Verification contract:** commands and evidence required before completion

package/skills/plan-refine/SKILL.md

@@ -0,0 +1,49 @@
+---
+type: skill
+slug: plan-refine
+title: Plan Refinement Methodology
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: "2026-05-07"
+last_reviewed: "2026-07-03"
+name: plan-refine
+description: "Blueprint hardening: fact-check assumptions, run plan reviews, split parallel tasks, and lock verification."
+---
+
+# Plan Refinement Methodology
+
+Use when a blueprint or implementation plan needs fact-checking, architecture hardening, parallel task shaping, or review consolidation before execution.
+
+## Core principle
+
+A plan is only as strong as its weakest unchecked assumption and only as fast as its coarsest task granularity.
+
+## Required workflow
+
+1. **Technology fact-check.** Verify API, version, runtime, platform, and package claims against official/upstream sources when external behavior matters.
+2. **Codebase verification.** Confirm file paths, exports, existing patterns, dependency availability, and local command surfaces in the repo.
+3. **Architecture review.** Challenge race conditions, error cascades, ownership boundaries, concurrency, auth/session edges, public-package leakage, and unnecessary abstractions.
+4. **Plan-review lenses.** Folded `/autoplan`: run the relevant CEO/founder, design, engineering, and DevEx review lenses; consolidate keep/change/drop decisions, unresolved taste calls, tests, and go/no-go.
+5. **Blueprint enforcement.** Split tasks for independent execution, declare dependencies, identify file conflicts, require TDD/proof steps, and preserve acceptance criteria.
+6. **Apply and record.** Update edge cases, risks, technology choices, cross-plan references, and verification gates. Do not edit implementation code during plan refinement.
+
+## Mandatory gates
+
+- Apply DRY, SOLID, YAGNI, and KISS; reject speculative abstractions.
+- For package, catalog, generated-surface, or release changes, require package-surface and public-content checks.
+- Prefer deletion/reuse over new layers or dependencies.
+- Stop on unverified external claims, unresolved shared-file conflicts, or missing authority for destructive work.
+
+## Output
+
+Return a concise plan review with:
+
+- verdict: ready / ready with edits / blocked
+- material corrections with evidence
+- task/dependency changes needed for parallel execution
+- required tests and audits
+- residual risks or explicit blockers
+
+For the full historical checklist and examples, read `references/full-methodology.md` only when deeper plan surgery is needed.