@webpresso/claude-plugin 3.1.3

package/skills/claude/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: claude
+description: "Claude CLI outside-voice wrapper for review, adversarial challenge, or consultation from non-Claude hosts."
+license: MIT
+---
+
+# Claude outside voice
+
+Use when a non-Claude host needs Claude to review a diff, challenge a plan, or answer a focused repo question. Keep it bounded/read-only unless asked otherwise, and report Claude output as advice, not verified fact.
+
+## Auth check
+
+Use local Claude CLI login directly; do not route through Anthropic API-key env vars.
+
+```bash
+AUTH_STATUS_FILE=$(mktemp -t wp-claude-auth.XXXXXX)
+trap 'rm -f "$AUTH_STATUS_FILE"' EXIT
+if ! claude auth status --json >"$AUTH_STATUS_FILE" 2>/dev/null; then
+  if ! claude auth status >"$AUTH_STATUS_FILE" 2>/dev/null; then
+    echo "CLAUDE_AUTH=missing: run claude auth login with the intended Claude Max account"
+    exit 1
+  fi
+fi
+if grep -E '"(authenticated|loggedIn|success)"[[:space:]]*:[[:space:]]*true' "$AUTH_STATUS_FILE" >/dev/null; then
+  echo "CLAUDE_AUTH=cli-login"
+else
+  echo "CLAUDE_AUTH=missing: claude auth status did not report a recognized Claude CLI login"
+  exit 1
+fi
+```
+
+## Portable prompt file
+
+Use a suffix-free `mktemp -t` pattern so macOS and Linux both work:
+
+```bash
+PROMPT_FILE=$(mktemp -t wp-claude-review.XXXXXX)
+trap 'rm -f "$PROMPT_FILE"' EXIT
+```
+
+## Modes
+
+### Review
+
+Use single-file / single-question first for any non-trivial diff. Do not send a whole PR unless it already fits within the bounded payload below.
+
+**Model policy:** default to `sonnet` via `CLAUDE_REVIEW_MODEL=${CLAUDE_REVIEW_MODEL:-sonnet}`. Override to `opus` only when the review is approval evidence or the user explicitly asks for Opus. Never use `fable` for Claude outside-voice review. Any review used as blueprint approval evidence MUST run with Claude Opus and record `"model": "opus"`.
+
+#### Bounded prompt payload
+
+Always include:
+
+- current branch and base branch
+- `git diff --stat`
+- changed file list
+- one targeted file diff or one narrow snippet/hunk only, capped to a fixed size
+
+Prefer ~12 KB or ~200 lines per call. Split large reviews instead of raising the cap.
+
+```bash
+BASE_BRANCH=${BASE_BRANCH:-origin/main}
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+TARGET_FILE=${TARGET_FILE:?set TARGET_FILE to one changed file}
+
+{
+  printf 'Outside review mode: focused diff review\n'
+  printf 'Base branch: %s\nCurrent branch: %s\n\n' "$BASE_BRANCH" "$CURRENT_BRANCH"
+  printf 'git diff --stat %s...HEAD\n' "$BASE_BRANCH"
+  git diff --stat "$BASE_BRANCH"...HEAD
+  printf '\nChanged files:\n'
+  git diff --name-only "$BASE_BRANCH"...HEAD
+  printf '\nTarget file: %s\n' "$TARGET_FILE"
+  printf 'Bounded target diff (max 12000 bytes):\n'
+  git diff --unified=3 "$BASE_BRANCH"...HEAD -- "$TARGET_FILE" | \
+    head -c 12000
+  printf '\n\nQuestion: Identify the highest-signal correctness, security, data-loss, or maintainability risk in %s. Quote only the smallest relevant excerpt. If context is insufficient, answer INSUFFICIENT_CONTEXT.\n' "$TARGET_FILE"
+} >"$PROMPT_FILE"
+```
+
+#### Timed Claude artifact wrapper
+
+Run Claude through the bounded Python wrapper. Use `claude --print --model "$CLAUDE_REVIEW_MODEL"`; do not recommend `--bare` for this path. Do not add artificial budget caps unless the user requested one. The wrapper is deterministic:
+
+- it defaults to `CLAUDE_REVIEW_MODEL=sonnet` and allows only `opus` or `sonnet`
+- it never passes `--tools ""`, because Claude's variadic `--tools` option can swallow the prompt
+- it captures stdout and stderr for preflight and the full review
+- it writes the artifact on success, non-zero exit, or timeout
+- it runs one full review attempt only; retry only if you change the command shape for a specific diagnosed reason
+
+Preflight must be only the tiny `claude-ok` prompt with the selected model. Do not use the real review prompt for preflight.
+
+```bash
+CLAUDE_REVIEW_MODEL=${CLAUDE_REVIEW_MODEL:-sonnet}
+CLAUDE_REVIEW_EFFORT=${CLAUDE_REVIEW_EFFORT:-medium}
+CLAUDE_REVIEW_PREFLIGHT_TIMEOUT_SECONDS=${CLAUDE_REVIEW_PREFLIGHT_TIMEOUT_SECONDS:-30}
+CLAUDE_REVIEW_IDLE_TIMEOUT_SECONDS=${CLAUDE_REVIEW_IDLE_TIMEOUT_SECONDS:-180}
+CLAUDE_REVIEW_ARTIFACT=${CLAUDE_REVIEW_ARTIFACT:-"$(pwd)/.webpresso/claude-review-$(date +%Y%m%dT%H%M%S).json"}
+export CLAUDE_REVIEW_MODEL CLAUDE_REVIEW_EFFORT CLAUDE_REVIEW_PREFLIGHT_TIMEOUT_SECONDS CLAUDE_REVIEW_IDLE_TIMEOUT_SECONDS CLAUDE_REVIEW_ARTIFACT
+mkdir -p "$(dirname "$CLAUDE_REVIEW_ARTIFACT")"
+
+python3 - "$PROMPT_FILE" "$CLAUDE_REVIEW_ARTIFACT" <<'PY'
+from __future__ import annotations
+
+import json, os, subprocess, sys, time
+from pathlib import Path
+
+prompt_path = Path(sys.argv[1])
+artifact_path = Path(sys.argv[2])
+model = os.environ.get("CLAUDE_REVIEW_MODEL", "sonnet")
+effort = os.environ.get("CLAUDE_REVIEW_EFFORT", "medium")
+preflight_timeout = float(os.environ.get("CLAUDE_REVIEW_PREFLIGHT_TIMEOUT_SECONDS", "30"))
+review_idle_timeout = float(os.environ.get("CLAUDE_REVIEW_IDLE_TIMEOUT_SECONDS", "180"))
+if model not in {"opus", "sonnet"}: raise SystemExit("CLAUDE_REVIEW_MODEL must be one of: opus, sonnet")
+if effort not in {"medium", "high"}: raise SystemExit("CLAUDE_REVIEW_EFFORT must be one of: medium, high")
+if preflight_timeout <= 0 or review_idle_timeout <= 0: raise SystemExit("Claude timeout values must be positive numbers")
+
+
+def utc_now() -> str: return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+artifact: dict[str, object] = {"tool": "claude-outside-voice", "model": model, "effort": effort, "startedAt": utc_now(), "artifactPath": str(artifact_path), "runs": []}
+
+
+def write_artifact(status: str, exit_code: int) -> None:
+    artifact.update({"finishedAt": utc_now(), "status": status, "exitCode": exit_code})
+    artifact_path.parent.mkdir(parents=True, exist_ok=True)
+    artifact_path.write_text(json.dumps(artifact, indent=2) + "\n", encoding="utf-8")
+
+
+def as_text(value: str | bytes | None) -> str:
+    return value.decode(errors="replace") if isinstance(value, bytes) else (value or "")
+
+
+def run_claude(stage: str, prompt: str, timeout_seconds: float, timeout_kind: str) -> int:
+    command = ["claude", "--print", "--model", model, "--effort", effort, prompt]
+    started = last_progress = time.monotonic()
+    last_progress_at = utc_now()
+    out = err = ""
+    record: dict[str, object] = {"stage": stage, "command": [*command[:-1], "<prompt>"], "timeoutKind": timeout_kind, "timeoutSeconds": timeout_seconds, "idleTimeoutSeconds": timeout_seconds if timeout_kind == "idle" else None, "startedAt": last_progress_at}
+    try:
+        process = subprocess.Popen(command, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+        while True:
+            try:
+                new_out, new_err = process.communicate(timeout=0.5)
+                out, err = as_text(new_out), as_text(new_err)
+                code = int(process.returncode)
+                timed_out = False
+                break
+            except subprocess.TimeoutExpired as exc:
+                new_out, new_err = as_text(exc.stdout), as_text(exc.stderr)
+                if new_out != out or new_err != err:
+                    out, err, last_progress, last_progress_at = new_out, new_err, time.monotonic(), utc_now()
+                reference = last_progress if timeout_kind == "idle" else started
+                if time.monotonic() - reference > timeout_seconds:
+                    process.kill()
+                    final_out, final_err = process.communicate()
+                    out += as_text(final_out)[len(out):]
+                    err += as_text(final_err)[len(err):]
+                    code, timed_out = 124, True
+                    break
+    except OSError as exc:
+        out, err, code, timed_out = "", str(exc), 1, False
+    record.update({"exitCode": code, "timedOut": timed_out, "stdout": out, "stderr": err, "finishedAt": utc_now(), "lastProgressAt": last_progress_at, "elapsedSeconds": round(time.monotonic() - started, 3)})
+    artifact["runs"].append(record)
+    return code
+
+preflight_code = run_claude("preflight", "claude-ok", preflight_timeout, "wall-clock")
+if preflight_code != 0:
+    write_artifact("preflight-timeout" if preflight_code == 124 else "preflight-failed", preflight_code)
+    print(f"CLAUDE_REVIEW_PREFLIGHT_EXIT={preflight_code}", file=sys.stderr)
+    print(f"CLAUDE_REVIEW_ARTIFACT={artifact_path}", file=sys.stderr)
+    raise SystemExit(preflight_code)
+review_code = run_claude("review", prompt_path.read_text(encoding="utf-8"), review_idle_timeout, "idle")
+write_artifact("idle-timeout" if review_code == 124 else ("success" if review_code == 0 else "failed"), review_code)
+print(f"CLAUDE_REVIEW_EXIT={review_code}", file=sys.stderr)
+print(f"CLAUDE_REVIEW_ARTIFACT={artifact_path}", file=sys.stderr)
+raise SystemExit(review_code)
+PY
+```
+
+After the wrapper exits, verify both the exit code and artifact path before summarizing Claude's raw output:
+
+```bash
+test -f "$CLAUDE_REVIEW_ARTIFACT" || {
+  echo "CLAUDE_REVIEW_ARTIFACT=missing: $CLAUDE_REVIEW_ARTIFACT" >&2
+  exit 1
+}
+echo "CLAUDE_REVIEW_ARTIFACT=$CLAUDE_REVIEW_ARTIFACT"
+```
+
+#### Retry policy
+
+Do not perform blind retries. Run the full review once. Retry only after diagnosing and changing a command-shape problem; record the reason and artifact path. Do not fall back to an unbounded whole-PR prompt.
+
+Summarize findings with severity, evidence, model, artifact path, and whether you independently verified them.
+
+### Challenge
+
+Ask Claude to argue against the current plan: hidden assumptions, failure modes, missing tests, and simpler alternatives.
+
+### Consult
+
+Ask a focused repo question. Include only the necessary file paths and snippets; do not send secrets.

package/skills/codex/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: codex
+description: "Codex CLI outside-voice wrapper for code review, plan challenge, or consultation from non-Codex hosts."
+license: MIT
+---
+
+# Codex outside voice
+
+Use this skill from Claude or another non-Codex host when the user wants Codex to independently review a diff, challenge a plan, or answer a repo question. Keep Codex read-only by default and treat its answer as external advice until independently verified.
+
+## Auth check
+
+```bash
+if ! codex login status >/dev/null 2>&1; then
+  echo "CODEX_AUTH=missing: run codex login before using the codex outside-voice skill"
+  exit 1
+fi
+echo "CODEX_AUTH=ok"
+```
+
+## Portable prompt file
+
+```bash
+PROMPT_FILE=$(mktemp -t wp-codex-review.XXXXXX)
+trap 'rm -f "$PROMPT_FILE"' EXIT
+```
+
+## Modes
+
+### Review
+
+1. Capture the current branch, base branch, and `git diff --stat`.
+2. Write a concise prompt asking Codex to find correctness, security, data-loss, and maintainability risks.
+3. Run Codex non-interactively in read-only mode:
+
+```bash
+CODEX_REVIEW_EFFORT=${CODEX_REVIEW_EFFORT:-medium}
+case "$CODEX_REVIEW_EFFORT" in
+  medium|high) ;;
+  *) echo "CODEX_REVIEW_EFFORT must be one of: medium, high" >&2; exit 2 ;;
+esac
+codex exec -c model_reasoning_effort="\"$CODEX_REVIEW_EFFORT\"" --sandbox read-only --cd "$PWD" - <"$PROMPT_FILE"
+```
+
+4. Summarize findings with severity, evidence, and whether you independently verified them.
+
+### Challenge
+
+Ask Codex to argue against the current plan: hidden assumptions, failure modes, missing tests, and simpler alternatives.
+
+### Consult
+
+Ask a focused repo question. Include only the necessary file paths and snippets; do not send secrets.

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.