@webpresso/plugin-claude 0.0.4

package/skills/best-practice-research/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: best-practice-research
+description: "Official/upstream best-practice research wrapper with bounded evidence and dated citations."
+argument-hint: "<technology|decision|practice question>"
+---
+
+# Best-Practice Research
+
+Use this skill when a task depends on current external best practices, version-aware guidance, standards, official recommendations, or upstream behavior. This is a workflow wrapper: it routes evidence gathering and synthesis; it is not a new research authority and it does not replace the `deep-research` skill.
+
+## Purpose
+
+Produce a cited, reusable best-practice answer or handoff that separates current external evidence from repo-local facts and dependency-selection decisions.
+
+## Activate When
+
+- The user asks for best practices, recommended approach, current guidance, official recommendations, standards, or version-aware external behavior.
+- `$ralplan`, `$team`, or another workflow needs current external evidence before planning or execution can be correct.
+- The task involves an already chosen technology and needs authoritative usage guidance, migration notes, API behavior, lifecycle rules, or current safety guidance.
+
+## Do Not Activate When
+
+- The answer is fully repo-local; use `explore` for codebase facts.
+- The main question is whether to adopt, replace, upgrade, or compare dependencies — that decision is out of scope; inform it with evidence but return the choice to the caller.
+- The user only needs implementation against already-grounded requirements; hand off to the caller's execution workflow (`$team` or `$ralplan`) as appropriate.
+- The task can be answered from stable local project conventions without current external lookup.
+
+## Specialist Routing
+
+1. Use `explore` first for brownfield facts: current code usage, local constraints, versions, config, and integration points.
+2. Gather official/upstream docs, release notes, standards, migration guides, and source-backed evidence yourself with web search and doc fetches; escalate to the `deep-research` skill for exhaustive multi-source research on an already chosen technology.
+3. Adoption / upgrade / replacement / comparison decisions are out of scope: surface the evidence, but return the decision to the caller.
+4. Return to the caller with explicit evidence, uncertainty, and any implementation handoff constraints.
+
+## Source-Quality Rules
+
+- Prefer official documentation, upstream source, release notes, changelogs, standards, and maintainer guidance.
+- Include source URLs for material claims.
+- State date/version context for current best-practice claims.
+- Label third-party summaries as supplemental; do not use them before official/upstream sources.
+- Flag stale, conflicting, undocumented, or version-mismatched evidence.
+- Do not over-fetch: gather the smallest evidence set that can support the decision.
+
+## Workflow
+
+1. Classify the question: conceptual best practice, implementation guidance, migration/version guidance, standards/compliance guidance, or mixed local + external guidance.
+2. Gather repo-local facts with `explore` when local usage or constraints affect the answer.
+3. Gather external evidence with web search and official-doc fetches (escalate to the `deep-research` skill for depth) when current or version-aware practice affects correctness.
+4. Synthesize a concise answer with source quality, version/date context, caveats, and an implementation or planning handoff.
+5. Stop when the answer is grounded enough for the caller; otherwise report the exact blocker or specialist handoff needed.
+
+## Output Contract
+
+```md
+## Best-Practice Research: <question>
+
+### Direct Recommendation
+
+<actionable guidance or decision support>
+
+### Evidence Used
+
+- Official/upstream: <source URL> — <what it establishes>
+- Supplemental, if any: <source URL> — <why it is secondary>
+
+### Version / Date Context
+
+<versions, dates, release channels, or unknowns>
+
+### Repo-Local Context
+
+<facts from explore, or "not needed">
+
+### Boundaries / Non-goals
+
+<what this research does not decide>
+
+### Handoff
+
+<planning/execution/test implications>
+```
+
+## Stop Rules
+
+- Stop after a source-backed recommendation is reusable by the caller.
+- Stop and route upward if the task becomes dependency comparison, broad architecture, or implementation.
+- Do not continue researching when remaining work would only polish wording rather than change the recommendation.
+
+Task: {{ARGUMENTS}}

package/skills/browse/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: browse
+description: "Browser/page inspection via Webpresso Playwright: inspect DOM, console, network basics, screenshots, and findings."
+license: MIT
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+---
+
+# Browse
+
+Use `wp browser doctor` first if browser availability is unknown; if it reports a missing browser, run `wp browser ensure chromium`. Prefer repo-local preview or dev-server URLs; if none are discoverable, ask for a URL.
+
+## Read-only inspection
+
+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.
+
+1. Identify the URL and whether headed or headless mode is needed.
+2. Use `wp browser open <url> --json` for a lightweight smoke snapshot, or a project Playwright test for deeper flows.
+3. Report URL, title, status evidence, console/page errors when available, and any screenshots/artifacts.
+4. Do not mutate app data unless the user explicitly asks for a mutating browser flow.

package/skills/claude/SKILL.md

@@ -0,0 +1,186 @@
+---
+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.
+
+## Single-shot budget (anti-stampede)
+
+- Default: **one** review invocation per request.
+- Do **not** spawn parallel Claude + Codex + Grok + OpenCode reviews unless the user set `review_budget`/`N` > 1.
+- Prefer MCP `wp_review_run`, then the `wp review run` CLI fallback, over hand-rolled multi-agent loops.
+- Bounded payload only (see below). Split large diffs across sequential calls, never unbounded whole-PR dumps.
+
+## Primary path: the `wp_review_run` MCP tool
+
+When the webpresso MCP server is available, call `wp_review_run` exactly once
+instead of any bash block below. It is the same `wp review run` typed runtime,
+called in-process, and takes a `prompt` string without `--prompt-file` bookkeeping.
+Use the default review stage.
+
+```jsonc
+// wp_review_run MCP tool call
+{
+  "prompt": "<diff summary + what to look for>",
+  "provider": "claude",
+  // model, effort, artifactRoot, idleSeconds, and stage are optional and
+  // default the same way the `wp review run` CLI does. The default stage is
+  // review.
+}
+```
+
+Use the requested provider for this invocation. Do not retry, use provider
+fallback, or rotate accounts within the invocation. Never shell into a
+provider CLI when MCP is available; that bypasses typed artifact capture under
+`.webpresso/reviews`.
+
+For long-running reviews, prefer the async MCP path: call `wp_review_run` with
+`"provider": "claude"` and `"background": true`, then poll `wp_review_wait`
+with the returned `runId`. Do not solve MCP transport limits by inflating
+synchronous review timeouts.
+
+The bash blocks in this skill (below) are the **MCP-unavailable fallback only**
+— use them when the webpresso MCP server itself is not reachable in the current
+host, not as a provider-fallback mechanism.
+
+## MCP-unavailable fallback: 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
+```
+
+## MCP-unavailable fallback: 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
+```
+
+## Dashboard helper relation
+
+When this skill runs under `wp dash`, record the outside-voice lifecycle with
+`wp dash-helper-start --provider claude --role reviewer` and
+`wp dash-helper-complete --provider claude --role reviewer --outcome <completed|failed>`
+using the actual terminal outcome and artifact path.
+Outside the dashboard, skip helper emission. Claude's managed native subagent
+lifecycle is not parent-linked; this unsupported coverage must stay explicit,
+and completion must never be inferred from transcript text or timing.
+
+## 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:** leave `CLAUDE_REVIEW_MODEL` unset unless the user requested a
+specific Claude model (for example `fable` for a lighter advisory pass). When it
+is unset, `wp review run` lets the Claude CLI choose its own default by omitting
+`--model`. The blueprint promotion/completion approval gate
+(`catalog/agent/rules/pre-implementation.md`) validates reviewer identity
+(`claude`/`codex`/`grok`/an OpenCode-Go model), not the reviewed model string, so do not
+claim the gate rejects a different Claude model.
+
+#### 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"
+```
+
+#### Progress-aware review runtime
+
+Run one review through the typed `wp review run` owner. Skills must not embed
+subprocess supervision. The runtime consumes Claude's streaming JSON events,
+advances its idle clock only on monotonic semantic progress, and has no total
+wall-clock cutoff.
+
+The artifact root contains private runtime diagnostics, not a recorded
+transcript or committable approval evidence. Direct `wp review run` output is
+advisory. `wp_review_gate` is plan-only exact-version draft approval/auto-promotion;
+implementation/phase reviews use advisory `wp_review_run` and never mutate
+blueprint approval state. CLI delivery gates are MCP-unavailable compatibility only.
+
+```bash
+CLAUDE_REVIEW_MODEL=${CLAUDE_REVIEW_MODEL:-}
+CLAUDE_MODEL_ARGS=()
+if [ -n "$CLAUDE_REVIEW_MODEL" ]; then
+  CLAUDE_MODEL_ARGS=(--model "$CLAUDE_REVIEW_MODEL")
+fi
+CLAUDE_REVIEW_EFFORT=${CLAUDE_REVIEW_EFFORT:-medium}
+CLAUDE_REVIEW_IDLE_SECONDS=${CLAUDE_REVIEW_IDLE_SECONDS:-180}
+CLAUDE_REVIEW_ARTIFACT_ROOT=${CLAUDE_REVIEW_ARTIFACT_ROOT:-"$(pwd)/.webpresso/reviews"}
+CLAUDE_REVIEW_CODE=0
+wp review run \
+  --provider claude \
+  --prompt-file "$PROMPT_FILE" \
+  "${CLAUDE_MODEL_ARGS[@]}" \
+  --effort "$CLAUDE_REVIEW_EFFORT" \
+  --stage review \
+  --artifact-root "$CLAUDE_REVIEW_ARTIFACT_ROOT" \
+  --idle-seconds "$CLAUDE_REVIEW_IDLE_SECONDS"
+CLAUDE_REVIEW_CODE=$?
+```
+
+Treat `true-idle`, `protocol-unsupported`, provider failure, abort, spawn failure, or artifact failure as an unavailable advisory result. Never replace them with a static timeout, arbitrary byte-growth heartbeat, or buffered-output fallback.
+
+#### Invocation policy
+
+Run one provider review per invocation. Do not retry, fall back to another
+provider, or rotate accounts within the invocation. A new invocation requires
+an explicit diagnosis and caller decision. 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,142 @@
+---
+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.
+
+## Primary path: the `wp_review_run` MCP tool
+
+When the webpresso MCP server is available, call `wp_review_run` exactly once instead of any bash block below. It is the same `wp review run` typed runtime, called in-process, and takes a `prompt` string without `--prompt-file` bookkeeping. Use the default review stage.
+
+```jsonc
+// wp_review_run MCP tool call
+{
+  "prompt": "<diff summary + what to look for>",
+  "provider": "codex",
+  // model, effort, artifactRoot, idleSeconds, and stage are optional and
+  // default the same way the `wp review run` CLI does. The default stage is
+  // review.
+}
+```
+
+Use the requested provider for this invocation. Do not retry, use provider fallback, or rotate accounts within the invocation. Never shell into a provider CLI when MCP is available; that bypasses typed artifact capture under `.webpresso/reviews`. The pretool guard hook redirects provider review launches to MCP.
+
+For long-running reviews, prefer the async MCP path: call `wp_review_run` with
+`"provider": "codex"` and `"background": true`, then poll `wp_review_wait`
+with the returned `runId`. Do not solve MCP transport limits by inflating
+synchronous review timeouts.
+
+The bash blocks in this skill (below) are the **MCP-unavailable fallback only** — use them when the webpresso MCP server itself is not reachable in the current host, not as a provider-fallback mechanism.
+
+## Single-shot budget (anti-stampede)
+
+- Default: **one** review invocation per request.
+- Do **not** fan out parallel multi-host review matrices unless the user set `review_budget`/`N` > 1.
+- Prefer `wp_review_run` (MCP) or `wp review run` (CLI fallback) over spawn/wait agent loops for review.
+- Keep prompts bounded; no whole-repo paste.
+
+## MCP-unavailable fallback (raw CLI)
+
+Everything from here down is the manual `wp review run` CLI path documented for hosts or sessions where the webpresso MCP server is not reachable. Prefer `wp_review_run` above whenever MCP is available.
+
+## MCP-unavailable fallback: 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"
+```
+
+## MCP-unavailable fallback: portable prompt file
+
+```bash
+PROMPT_FILE=$(mktemp -t wp-codex-review.XXXXXX)
+trap 'rm -f "$PROMPT_FILE"' EXIT
+```
+
+## Dashboard helper relation
+
+When called by `wp dash`, record the outside-voice lifecycle with
+`wp dash-helper-start --provider codex --role reviewer` and
+`wp dash-helper-complete --provider codex --role reviewer --outcome <completed|failed>`
+using the actual terminal outcome and artifact path.
+Standalone calls skip helper emission. Codex native subagent events are not
+parent-linked in the managed lifecycle; this unsupported coverage must stay
+explicit, and completion must never be inferred from text, PIDs, or
+timestamps.
+
+## Options
+
+Every mode runs through the `wp review run` runtime and honors these environment
+overrides. Set them inline, e.g.
+`CODEX_REVIEW_MODEL=gpt-5.6-sol CODEX_REVIEW_EFFORT=high /codex`.
+
+- `CODEX_REVIEW_MODEL` — the Codex model. Defaults to the `model = "..."` in the
+  active Codex config (`${CODEX_HOME:-~/.codex}/config.toml`); if neither the
+  environment nor config names a model, `wp review run` lets the Codex CLI choose
+  its own default. It MUST be a model the current login is provisioned for: ChatGPT-account
+  logins use the config's codenamed ids (e.g. `gpt-5.6-sol`) and reject a bare
+  `gpt-5.6`. When the user names a model ("review with 5.6-sol"), pass it here.
+- `CODEX_REVIEW_EFFORT` — reasoning effort, default `medium`. The review stage
+  accepts only `medium` or `high`; any other value is rejected.
+- `CODEX_REVIEW_IDLE_SECONDS` — idle timeout in seconds for the review stage,
+  default `180`.
+- `CODEX_REVIEW_ARTIFACT_ROOT` — directory for private runtime diagnostics,
+  default `<cwd>/.webpresso/reviews`. Never commit files from this directory or
+  cite them as approval evidence.
+
+Direct `wp review run` output is advisory. `wp_review_gate` is plan-only
+exact-version draft approval/auto-promotion; implementation/phase reviews use
+advisory `wp_review_run` and never mutate blueprint approval state. CLI delivery
+gates are MCP-unavailable compatibility only.
+
+## 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 through the typed review runtime in read-only mode:
+
+```bash
+# CODEX_REVIEW_MODEL / CODEX_REVIEW_EFFORT are overridable — see ## Options for
+# the full option list, valid values, and how to pick a login-supported model.
+CODEX_REVIEW_MODEL=${CODEX_REVIEW_MODEL:-}
+CODEX_MODEL_ARGS=()
+if [ -n "$CODEX_REVIEW_MODEL" ]; then
+  CODEX_MODEL_ARGS=(--model "$CODEX_REVIEW_MODEL")
+fi
+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_REVIEW_IDLE_SECONDS=${CODEX_REVIEW_IDLE_SECONDS:-180}
+CODEX_REVIEW_ARTIFACT_ROOT=${CODEX_REVIEW_ARTIFACT_ROOT:-"$(pwd)/.webpresso/reviews"}
+CODEX_REVIEW_CODE=0
+wp review run \
+  --provider codex \
+  --prompt-file "$PROMPT_FILE" \
+  "${CODEX_MODEL_ARGS[@]}" \
+  --effort "$CODEX_REVIEW_EFFORT" \
+  --stage review \
+  --artifact-root "$CODEX_REVIEW_ARTIFACT_ROOT" \
+  --idle-seconds "$CODEX_REVIEW_IDLE_SECONDS"
+CODEX_REVIEW_CODE=$?
+```
+
+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-interview/LICENSE.txt

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 Yeachan Heo
+
+Applies to the upstream deep-interview skill vendored from
+https://github.com/Yeachan-Heo/oh-my-codex at commit
+0e00a6ebdd12a6674f5a4735942940b9bdcdb8c0. The upstream repository declares
+the MIT license in its package.json and Cargo.toml at that commit without
+shipping a standalone LICENSE file; this file preserves the standard MIT
+copyright and permission notice for the vendored material.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.