@webpresso/claude-plugin 3.1.3

package/.claude-plugin/marketplace.json

@@ -0,0 +1,30 @@
+{
+  "name": "webpresso",
+  "owner": {
+    "name": "Webpresso",
+    "url": "https://github.com/webpresso"
+  },
+  "metadata": {
+    "description": "Webpresso agent-kit Claude Code plugin: blueprints, skills, hooks, MCP server",
+    "version": "3.1.3"
+  },
+  "plugins": [
+    {
+      "name": "agent-kit",
+      "source": "./",
+      "description": "Webpresso agent-kit: blueprints, skills, lore commit protocol, tech-debt lifecycle",
+      "category": "development",
+      "keywords": ["agent", "blueprint", "claude-code", "skills", "mcp"],
+      "mcpServers": {
+        "webpresso": {
+          "command": "${CLAUDE_PLUGIN_ROOT}/bin/wp",
+          "args": ["mcp"],
+          "env": {
+            "WP_SKIP_UPDATE_CHECK": "1"
+          }
+        }
+      }
+    }
+  ],
+  "version": "3.1.3"
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "agent-kit",
+  "version": "3.1.3",
+  "description": "Webpresso agent-kit: blueprints, skills, lore commit protocol, tech-debt lifecycle",
+  "author": {
+    "name": "Webpresso",
+    "url": "https://github.com/webpresso"
+  },
+  "skills": "./skills",
+  "commands": "./commands",
+  "mcpServers": {
+    "webpresso": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/bin/wp",
+      "args": [
+        "mcp"
+      ],
+      "env": {
+        "WP_SKIP_UPDATE_CHECK": "1"
+      }
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,104 @@
+Elastic License 2.0
+===================
+
+Copyright (c) 2026 Webpresso, Inc.
+
+Acceptance
+----------
+
+By using the software, you agree to all of the terms and conditions below.
+
+Copyright License
+-----------------
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+Limitations
+-----------
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key
+functionality in the software, and you may not remove or obscure any
+functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+Patents
+-------
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software.
+
+If you or your company make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license for the software
+granted under these terms ends immediately. If your company makes such a claim,
+your patent license ends immediately for work on behalf of your company.
+
+Notices
+-------
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+No Other Rights
+---------------
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+Termination
+-----------
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+No Liability
+------------
+
+As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.
+
+Definitions
+-----------
+
+The licensor is the entity offering these terms, and the software is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+you refers to the individual or entity agreeing to these terms.
+
+your company is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+control means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+your licenses are all the licenses granted to you for the software under these
+terms.
+
+use means anything you do with the software requiring one of your licenses.
+
+trademark means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,25 @@
+# @webpresso/claude-plugin
+
+`@webpresso/claude-plugin` is the Claude Code host adapter package for Agent
+Kit. It ships the Claude plugin manifest, marketplace metadata, packaged
+skills, command docs, and a package-local `bin/wp` shim that forwards to an
+Agent Kit `wp` CLI resolved at runtime.
+
+This adapter does not declare `@webpresso/agent-kit` as a package dependency.
+Its package-local `bin/wp` shim resolves the CLI in this order:
+
+1. `WEBPRESSO_WP_BIN`, when set to an executable file.
+2. The source-checkout root `../../bin/wp`, for local adapter development.
+3. `@webpresso/agent-kit/bin/wp`, when an integrator installed the root package
+   alongside this adapter.
+4. `wp` on `PATH`.
+
+If none of those candidates is available, install or update the root package
+through `wp setup`, `wp update`, or your package manager, or set
+`WEBPRESSO_WP_BIN` to the desired executable. The shim preserves
+`WP_SKIP_UPDATE_CHECK=1` by default for host MCP invocations.
+
+The root `@webpresso/agent-kit` package is CLI/core only: it ships `wp`, MCP
+tools, audits, blueprints, session memory, docs, and catalog sources, but it
+does not ship this Claude payload from the root package. Use this adapter when
+you need the Claude-native plugin delivery surface.

package/bin/wp

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, delimiter, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const shimPath = fileURLToPath(import.meta.url);
+const shimDir = dirname(shimPath);
+const adapterRoot = dirname(shimDir);
+
+function isExecutableFile(candidate) {
+  try {
+    const stat = statSync(candidate);
+    if (!stat.isFile()) return false;
+    accessSync(candidate, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function sameFile(a, b) {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return false;
+  }
+}
+
+function pathWpCandidates() {
+  return (process.env.PATH ?? "")
+    .split(delimiter)
+    .filter(Boolean)
+    .map((entry) => join(entry, process.platform === "win32" ? "wp.cmd" : "wp"));
+}
+
+function resolveAgentKitPackageWp() {
+  try {
+    const packageJsonPath = require.resolve("@webpresso/agent-kit/package.json");
+    return join(dirname(packageJsonPath), "bin", "wp");
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveAgentKitWp() {
+  const explicitPath = process.env.WEBPRESSO_WP_BIN;
+  if (explicitPath) {
+    if (isExecutableFile(explicitPath)) return explicitPath;
+    throw new Error(
+      `WEBPRESSO_WP_BIN points to ${explicitPath}, but that file is not executable. ` +
+        "Set WEBPRESSO_WP_BIN to a valid wp executable, install/update @webpresso/agent-kit, or run wp setup.",
+    );
+  }
+
+  const candidates = [
+    join(adapterRoot, "..", "..", "bin", "wp"),
+    resolveAgentKitPackageWp(),
+    ...pathWpCandidates(),
+  ].filter(Boolean);
+
+  for (const candidate of candidates) {
+    if (isExecutableFile(candidate) && !sameFile(candidate, shimPath)) {
+      return candidate;
+    }
+  }
+
+  throw new Error(
+    "Unable to locate the Webpresso wp CLI. Install or update @webpresso/agent-kit, run wp setup, " +
+      "set WEBPRESSO_WP_BIN to the wp executable, or ensure wp is available on PATH.",
+  );
+}
+
+const result = spawnSync(resolveAgentKitWp(), process.argv.slice(2), {
+  stdio: "inherit",
+  env: {
+    ...process.env,
+    WP_SKIP_UPDATE_CHECK: process.env.WP_SKIP_UPDATE_CHECK ?? "1",
+  },
+});
+
+if (result.error) {
+  throw result.error;
+}
+
+process.exit(result.status ?? (result.signal ? 1 : 0));

package/commands/audit.md

@@ -0,0 +1,29 @@
+---
+description: Run a webpresso audit
+---
+
+Use the `mcp__webpresso__wp_audit` tool when the requested audit is available
+through MCP, or `./bin/wp audit <kind>` from this source repo for the full CLI
+registry. Common `kind` values include `guardrails`, `quality`,
+`catalog-drift`, `package-surface`, `docs-frontmatter`, `blueprint-lifecycle`,
+`blueprint-readme-drift`, `cloudflare-deploy-contract`, `harness-surfaces`,
+`weakness-mining`, `harness-overlay-evidence`, `bundle-budget`,
+`commit-message`, `tech-debt`, and `architecture-drift`.
+
+`architecture-drift` verifies a repo-local `docs/architecture.contract.json`
+contract against:
+
+- required architecture docs
+- required architecture text/rules
+- active blueprint links to architecture docs/contracts
+- required `Architecture before` / `Architecture after` sections for
+  architecture-changing blueprints
+
+Harness-specific audits:
+
+- `harness-surfaces` validates `catalog/agent/harness-surfaces.yaml` against
+  the repo layout.
+- `weakness-mining` clusters available hook evidence and can draft tech-debt
+  when invoked with the matching CLI option.
+- `harness-overlay-evidence` validates `agent-overlays/<cli>/manifest.yaml`
+  evidence and target-safety rules; an empty overlay set is valid.

package/commands/blueprint.md

@@ -0,0 +1,27 @@
+---
+description: Manage blueprints via focused MCP tools
+---
+
+Use the focused blueprint MCP tools.
+
+- `wp_blueprint_projects` — discover visible projects and worktrees
+- `wp_blueprint_list` — list blueprints
+- `wp_blueprint_get` — fetch one blueprint with freshness metadata
+- `wp_blueprint_context` — assemble bounded task context
+- `wp_blueprint_create` — create a draft blueprint; requires `project_id` and accepts optional `request_id` and `head_at_ingest` for retry-safe, stale-write-safe creation
+- `wp_blueprint_put` — whole-document structured authoring; writes the canonical blueprint markdown from typed input and returns revision metadata
+- `wp_blueprint_transition` — optimistic-concurrency lifecycle transition; requires `expected_version` and returns updated revision metadata
+- `wp_blueprint_task_next` — return the next ready task; accepts optional `project_id` when the current cwd is a multi-repo workspace container
+- `wp_blueprint_task_advance` — change task status (non-`done`); requires `project_id` and accepts optional `request_id` and `head_at_ingest` for retry-safe mutation
+- `wp_blueprint_task_verify` — mark a task `done` with evidence; accepts optional `request_id` and `head_at_ingest` for retry-safe verification
+- `wp_blueprint_promote` / `wp_blueprint_finalize` — accept optional `project_id` for nested-workspace disambiguation
+
+Guidance:
+
+- Prefer `project_id` from `wp_blueprint_projects` when multiple repos are visible.
+- Use `request_id` for retry-safe mutations and reuse it only with the same payload.
+- Carry `head_at_ingest` from read/context tools into stale-write-sensitive mutations.
+- Author documents through `wp_blueprint_put`, then lifecycle with `wp_blueprint_transition`.
+- Deferred `wp_blueprint_patch` semantic ops (`add_task`, `update_task`, `set_summary`, `replace_decision`) are future layers; patch is **not** part of the v1 canonical surface.
+- MCP Apps editor support is a follow-on enhancement over `wp_blueprint_put` / `wp_blueprint_transition`.
+- Hosts without MCP Apps support keep using the structured tools above.

package/commands/qa.md

@@ -0,0 +1,5 @@
+---
+description: Run lint + typecheck + tests in parallel via webpresso MCP
+---
+
+Use the `mcp__webpresso__wp_qa` tool to run lint, typecheck, and tests in parallel. No arguments required; the tool aggregates structured results from each sub-tool.

package/commands/test.md

@@ -0,0 +1,5 @@
+---
+description: Run tests via the webpresso MCP server
+---
+
+Use the `mcp__webpresso__wp_test` tool to run tests. Pass `packages` or `files` as arguments based on what the user asks for.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@webpresso/claude-plugin",
+  "version": "3.1.3",
+  "private": false,
+  "description": "Claude Code plugin adapter for Webpresso agent-kit skills, commands, and MCP runtime.",
+  "homepage": "https://github.com/webpresso/agent-kit#readme",
+  "bugs": {
+    "url": "https://github.com/webpresso/agent-kit/issues"
+  },
+  "license": "Elastic-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/webpresso/agent-kit.git",
+    "directory": "packages/claude-plugin"
+  },
+  "files": [
+    ".claude-plugin",
+    "skills",
+    "commands",
+    "bin/wp",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

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 `researcher`.
+
+## 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`, `$deep-interview`, `$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; use `dependency-expert`.
+- The user only needs implementation against already-grounded requirements; use `executor`, `$ralph`, or `$team` 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. Use `researcher` for official/upstream docs, release notes, standards, migration guides, source-backed examples, and current best-practice evidence for an already chosen technology.
+3. Use `dependency-expert` only for adoption/upgrade/replacement/comparison decisions.
+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 `researcher` 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.