@webpresso/agent-kit 0.21.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,27 @@
+{
+  "name": "webpresso",
+  "owner": {
+    "name": "Webpresso",
+    "url": "https://github.com/webpresso"
+  },
+  "metadata": {
+    "description": "Webpresso agent-kit Claude Code plugin: blueprints, skills, hooks, MCP server",
+    "version": "0.21.0"
+  },
+  "plugins": [
+    {
+      "name": "webpresso",
+      "source": "./",
+      "description": "Webpresso agent-kit: blueprints, skills, lore commit protocol, tech-debt lifecycle",
+      "category": "development",
+      "keywords": [
+        "agent",
+        "blueprint",
+        "claude-code",
+        "skills",
+        "mcp"
+      ]
+    }
+  ],
+  "version": "0.21.0"
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,73 @@
+{
+  "name": "webpresso",
+  "version": "0.21.0",
+  "description": "Webpresso agent-kit: blueprints, skills, lore commit protocol, tech-debt lifecycle",
+  "skills": "./skills",
+  "commands": "./commands",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Edit|Write|MultiEdit|WebFetch|Read|Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/bin/wp-pretool-guard.js"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/bin/wp-post-tool.js",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/bin/wp-stop-qa.js"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/bin/wp-guard-switch.js",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/bin/wp-sessionstart-routing.js"
+          }
+        ]
+      }
+    ]
+  },
+  "mcpServers": {
+    "webpresso": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/bin/wp.js",
+        "mcp"
+      ]
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Webpresso
+
+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.

package/README.md

@@ -0,0 +1,106 @@
+# @webpresso/agent-kit
+
+> Plug-and-play setup for AI coding agents. Run one command and every agent in
+> the repo gets the same instructions, skills, hooks, planning files, and quality
+> gates. MIT. Experimental v0.x.
+
+## Install
+
+Requires Node.js 24 or newer.
+
+Install from the public npm registry:
+
+```bash
+npm install -g @webpresso/agent-kit
+wp setup
+```
+
+That's the product.
+
+No private registry setup is required.
+
+If you do not want a global install, run it one-shot instead:
+
+```bash
+npm exec --yes --package @webpresso/agent-kit@latest -- wp setup
+```
+
+`wp setup` is safe to run again. It refreshes the webpresso-owned pieces and
+preserves consumer-owned files.
+
+## What it gives you
+
+- **One repo brain** — major coding agents read the same operating contract.
+- **Skills that travel** — repo skills show up across supported agent surfaces.
+- **Hooks that help** — generated hooks steer common work through repo quality gates.
+- **Blueprints by default** — planning files and templates are ready when the task needs them, and Blueprint markdown stays the canonical plan while OMX handoff files remain derived metadata.
+- **Agent-friendly checks** — tests, lint, typecheck, E2E, and audits are easy to run and cite.
+- **Context-efficient evidence by default** — `wp_*` MCP wrappers return
+  compact test/lint/typecheck/audit summaries, and `wp setup` includes `rtk`
+  in its default workstation preset set.
+
+## Why it exists
+
+AI-agent repos usually grow six copies of the same thing:
+
+- one instruction file for Claude,
+- another for Codex,
+- another for Cursor,
+- separate hooks,
+- separate skills,
+- separate planning conventions.
+
+Those copies drift. webpresso makes the repo feel like one product again:
+
+```bash
+wp setup
+```
+
+## Why agents keep more useful context
+
+Coding agents waste context in two predictable ways: duplicated repo guidance and
+verbose tool output. Agent Kit attacks both:
+
+- **Default compact quality evidence:** `wp_test`, `wp_lint`, `wp_typecheck`, `wp_qa`,
+  `wp_e2e`, and `wp_audit` are MCP-first wrappers that return summary-first
+  JSON, clipped raw output, and budget metadata such as `bytes` and
+  `tokensSaved`. See [`docs/qa-output.md`](docs/qa-output.md).
+- **Default RTK shell filtering lane:** `wp setup` includes `rtk` in its
+  default preset set. The setup command skips RTK in CI and when
+  `WP_SKIP_RTK=1` is set. See [`docs/add-ons.md`](docs/add-ons.md).
+- **Default context-mode lane:** `wp setup` includes `context-mode` in its
+  default preset set. The setup command skips context-mode in CI and when
+  `WP_SKIP_CONTEXT_MODE=1` is set, and the published package still does not
+  bundle the external tool. See
+  [`docs/migration/context-mode-default.md`](docs/migration/context-mode-default.md).
+
+The result: agents spend more of the window on code, plans, decisions, and
+errors that matter, and less on repeated instructions or thousand-line command
+logs.
+
+## Add-ons
+
+Most repos should start with the default setup. Extra integrations and their
+default/opt-in behavior are documented in [`docs/add-ons.md`](docs/add-ons.md).
+
+## Package references
+
+If you need config subpaths or dependency references, use the appendix:
+[`docs/markdown-fact-check.md`](docs/markdown-fact-check.md).
+
+## Docs
+
+- [Getting started](docs/getting-started.md)
+- [Is webpresso for me?](docs/is-agent-kit-for-me.md)
+- [Add-ons](docs/add-ons.md)
+- [Blueprint format](docs/blueprint-format.md)
+- [Skills catalog](docs/skills-catalog.md)
+
+## Status
+
+Experimental v0.x. Public APIs may change before v1.
+
+## License
+
+MIT — see [LICENSE](./LICENSE). Vendored catalog skills and runtime integration
+licenses are documented in [THIRD-PARTY-NOTICES.md](./THIRD-PARTY-NOTICES.md).

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,60 @@
+# Third-Party Notices
+
+`@webpresso/agent-kit` is licensed under the [MIT License](./LICENSE).
+
+The catalog includes skills copied or adapted from upstream open-source projects.
+Machine-readable provenance lives in
+[`catalog/agent/skills/third-party-manifest.json`](./catalog/agent/skills/third-party-manifest.json).
+CI validates that manifest with `wp audit open-source-licenses`.
+
+## Vendored catalog skills
+
+| Skill | Upstream | License | Notes |
+| --- | --- | --- | --- |
+| `frontend-design` | [anthropics/skills](https://github.com/anthropics/skills/tree/main/skills/frontend-design) | Apache-2.0 | `LICENSE.txt` vendored alongside the skill |
+| `vercel-react-best-practices` | [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices) | MIT | Substantial rule corpus vendored under `catalog/agent/skills/vercel-react-best-practices/` |
+| `logging-best-practices` | [boristane/agent-skills](https://github.com/boristane/agent-skills/tree/main/skills/logging-best-practices) | MIT | Wide-events logging guidance |
+| `web-design-guidelines` | [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines) | MIT | Skill wrapper; live guidelines fetched from upstream at runtime |
+
+## Webpresso-authored catalog skills
+
+Skills such as `tanstack-query`, `lore-protocol`, `pll`, `verify`, `fix`, and
+`better-auth-best-practices` are maintained in this repository and are covered by
+the project MIT license unless noted otherwise in their frontmatter.
+
+## Integration-only skills (not vendored)
+
+| Skill | Upstream tool | License |
+| --- | --- | --- |
+| `react-doctor` | [millionco/react-doctor](https://github.com/millionco/react-doctor) | MIT |
+
+These skills document how to invoke external CLIs or packages. Their upstream
+binaries are **not** bundled in `@webpresso/agent-kit`.
+
+## Runtime integrations (not bundled)
+
+These integrations invoke or install external tools separately; their upstream
+binaries are **not** bundled in `@webpresso/agent-kit`. The table below records
+whether each integration is part of the current default `wp setup` preset set or
+requires explicit `wp setup --with <name>` opt-in. Consumers accept the upstream
+license separately when an integration is installed.
+
+| Integration | Default behavior | Upstream | License |
+| --- | --- | --- | --- |
+| `context-mode` | In the default preset set; skipped in CI or when `WP_SKIP_CONTEXT_MODE=1`. | [mksglu/context-mode](https://github.com/mksglu/context-mode) | Elastic-2.0 (source-available) |
+| `playwright-mcp` | Opt-in. | [microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp) | Apache-2.0 |
+| `gstack` | In the default preset set; skipped in CI or when `WP_SKIP_GSTACK=1`. | [garrytan/gstack](https://github.com/garrytan/gstack) | MIT |
+| `omx` / `oh-my-codex` | In the default preset set; skipped in CI. | [oh-my-codex](https://oh-my-codex.dev/) | MIT |
+| `omc` / `oh-my-claudecode` | In the default preset set; skipped when `WP_SKIP_OMC=1` or the `claude` CLI is unavailable. | [Yeachan-Heo/oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) | MIT |
+| `rtk` | In the default preset set; skipped in CI or when `WP_SKIP_RTK=1`. | [rtk-ai/rtk](https://github.com/rtk-ai/rtk) | Apache-2.0 |
+
+`scripts/verify-no-context-mode.sh` and `wp audit open-source-licenses` ensure
+`context-mode` never appears in the default published npm dependency graph.
+
+## Runtime npm dependencies
+
+Production dependencies ship under their own licenses (MIT, Apache-2.0, ISC, and
+similar permissive terms). Run `pnpm licenses list --prod` in a fully installed
+checkout for the current dependency license report.
+
+This file is an engineering attribution inventory, not legal advice.

package/bin/_run.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const BIN_ENTRYPOINTS = {
+  wp: 'src/cli/cli.ts',
+  'wp-pretool-guard': 'src/hooks/pretool-guard/index.ts',
+  'wp-post-tool': 'src/hooks/post-tool/lint-after-edit.ts',
+  'wp-stop-qa': 'src/hooks/stop/qa-changed-files.ts',
+  'wp-guard-switch': 'src/hooks/guard-switch/index.ts',
+  'wp-test-quality-check': 'src/hooks/test-quality-check.ts',
+  'wp-sessionstart-routing': 'src/hooks/sessionstart/index.ts',
+  'wp-check-dev-link': 'src/hooks/check-dev-link/index.ts',
+  'wp-restore-dev-links': 'src/dev/restore-dev-links/index.ts',
+  'docs-check-internal-links': 'src/config/docs-lint/cli/check-internal-links.ts',
+  'docs-check-refs': 'src/config/docs-lint/cli/check-refs.ts',
+  'docs-check-stale': 'src/config/docs-lint/cli/check-stale.ts',
+  'docs-lint': 'src/config/docs-lint/cli/validate.ts',
+  'docs-migrate': 'src/config/docs-lint/cli/migrate.ts',
+}
+
+function resolvePackageRoot() {
+  return join(dirname(fileURLToPath(import.meta.url)), '..')
+}
+
+function normalizeNodeVersion(version) {
+  return version.replace(/^v/u, '')
+}
+
+function isExactNodeVersion(version) {
+  return /^\d+\.\d+\.\d+$/u.test(version)
+}
+
+function readTextIfExists(path) {
+  return existsSync(path) ? readFileSync(path, 'utf8').trim() : null
+}
+
+export function resolvePinnedNodeVersion(repoRoot = resolvePackageRoot()) {
+  const nodeVersionFile = readTextIfExists(join(repoRoot, '.node-version'))
+  if (nodeVersionFile && isExactNodeVersion(nodeVersionFile)) return nodeVersionFile
+
+  const nvmrc = readTextIfExists(join(repoRoot, '.nvmrc'))
+  if (nvmrc && isExactNodeVersion(nvmrc)) return nvmrc
+
+  const packageJsonPath = join(repoRoot, 'package.json')
+  if (!existsSync(packageJsonPath)) return null
+
+  try {
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'))
+    const engineNode = packageJson?.engines?.node
+    return typeof engineNode === 'string' && isExactNodeVersion(engineNode) ? engineNode : null
+  } catch {
+    return null
+  }
+}
+
+export function resolveNodeRuntimeManager() {
+  const result = spawnSync('mise', ['--version'], { encoding: 'utf8' })
+  if (!result.error && (result.status === 0 || result.status === null)) {
+    return { kind: 'mise', command: 'mise' }
+  }
+
+  return null
+}
+
+function sourceToBuiltRelativePath(sourceRelativePath) {
+  if (!sourceRelativePath.startsWith('src/')) {
+    throw new Error(`Unsupported bin source path: ${sourceRelativePath}`)
+  }
+  return `dist/esm/${sourceRelativePath.slice(4).replace(/\.ts$/u, '.js')}`
+}
+
+function buildSourceLaunchPlan(sourceEntrypoint, forwardedArgs) {
+  return {
+    mode: 'source',
+    runtime: process.env.BUN ?? 'bun',
+    entrypoint: sourceEntrypoint,
+    args: [sourceEntrypoint, ...forwardedArgs],
+  }
+}
+
+export function resolveInvokedBinName(argv = process.argv.slice(1)) {
+  const invoked = argv[0]
+  if (typeof invoked !== 'string' || invoked.length === 0) {
+    throw new Error('Unable to determine which webpresso bin was invoked.')
+  }
+  return basename(invoked).replace(/\.js$/u, '')
+}
+
+export function buildLaunchPlan({
+  binName,
+  repoRoot = resolvePackageRoot(),
+  forwardedArgs = process.argv.slice(2),
+  builtExists,
+  sourceExists,
+  nodeExecPath = process.execPath,
+  currentNodeVersion = process.version,
+  pinnedNodeVersion = resolvePinnedNodeVersion(repoRoot),
+  runtimeManager = resolveNodeRuntimeManager(),
+  builtMtimeMs,
+  sourceMtimeMs,
+}) {
+  const sourceRelativePath = BIN_ENTRYPOINTS[binName]
+  if (!sourceRelativePath) {
+    throw new Error(`Unknown webpresso bin: ${binName}`)
+  }
+
+  const builtRelativePath = sourceToBuiltRelativePath(sourceRelativePath)
+  const builtEntrypoint = join(repoRoot, builtRelativePath)
+  const sourceEntrypoint = join(repoRoot, sourceRelativePath)
+
+  const hasBuilt = builtExists ?? existsSync(builtEntrypoint)
+  const hasSource = sourceExists ?? existsSync(sourceEntrypoint)
+  const resolvedBuiltMtimeMs =
+    builtMtimeMs ?? (builtExists === undefined && hasBuilt ? statSync(builtEntrypoint).mtimeMs : null)
+  const resolvedSourceMtimeMs =
+    sourceMtimeMs ??
+    (sourceExists === undefined && hasSource ? statSync(sourceEntrypoint).mtimeMs : null)
+  const shouldPreferSource =
+    hasSource &&
+    typeof resolvedBuiltMtimeMs === 'number' &&
+    typeof resolvedSourceMtimeMs === 'number' &&
+    resolvedSourceMtimeMs > resolvedBuiltMtimeMs
+
+  if (shouldPreferSource) {
+    return buildSourceLaunchPlan(sourceEntrypoint, forwardedArgs)
+  }
+
+  if (hasBuilt) {
+    const normalizedCurrent = normalizeNodeVersion(currentNodeVersion)
+    if (
+      pinnedNodeVersion &&
+      isExactNodeVersion(pinnedNodeVersion) &&
+      normalizedCurrent !== pinnedNodeVersion
+    ) {
+      if (runtimeManager?.kind === 'mise') {
+        return {
+          mode: 'built',
+          runtime: runtimeManager.command,
+          entrypoint: builtEntrypoint,
+          args: [
+            'exec',
+            `node@${pinnedNodeVersion}`,
+            '--',
+            nodeExecPath,
+            builtEntrypoint,
+            ...forwardedArgs,
+          ],
+        }
+      }
+
+      throw new Error(
+        [
+          `Unable to launch ${binName}: current Node is ${normalizedCurrent}, but this package pins Node ${pinnedNodeVersion}.`,
+          'Install `mise` or switch to the pinned Node version before retrying.',
+        ].join(' '),
+      )
+    }
+
+    return {
+      mode: 'built',
+      runtime: nodeExecPath,
+      entrypoint: builtEntrypoint,
+      args: [builtEntrypoint, ...forwardedArgs],
+    }
+  }
+
+  if (hasSource) {
+    return buildSourceLaunchPlan(sourceEntrypoint, forwardedArgs)
+  }
+
+  throw new Error(
+    [
+      `Unable to launch ${binName}: neither ${builtRelativePath} nor ${sourceRelativePath} exists.`,
+      'Run `wp hooks doctor` to diagnose the install, or rebuild/reinstall the package before retrying.',
+    ].join(' '),
+  )
+}
+
+export function runNamedBin(binName, argv = process.argv.slice(2)) {
+  const plan = buildLaunchPlan({ binName, forwardedArgs: argv })
+  const child = spawnSync(plan.runtime, plan.args, { stdio: 'inherit' })
+
+  if (child.error) {
+    const detail =
+      plan.mode === 'source'
+        ? `Bun is required for source-checkout fallback (${plan.entrypoint}). Install bun or rebuild so dist/esm exists.`
+        : child.error.message
+    throw new Error(detail)
+  }
+
+  if (child.signal) {
+    process.kill(process.pid, child.signal)
+    return
+  }
+
+  process.exit(child.status ?? 1)
+}

package/bin/docs-check-internal-links.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runNamedBin } from './_run.js'
+
+runNamedBin('docs-check-internal-links')

package/bin/docs-check-refs.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runNamedBin } from './_run.js'
+
+runNamedBin('docs-check-refs')

package/bin/docs-check-stale.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runNamedBin } from './_run.js'
+
+runNamedBin('docs-check-stale')

package/bin/docs-lint.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runNamedBin } from './_run.js'
+
+runNamedBin('docs-lint')

package/bin/docs-migrate.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runNamedBin } from './_run.js'
+
+runNamedBin('docs-migrate')

package/bin/wp-check-dev-link.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runNamedBin } from './_run.js'
+
+runNamedBin('wp-check-dev-link')

package/bin/wp-guard-switch.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runNamedBin } from './_run.js'
+
+runNamedBin('wp-guard-switch')

package/bin/wp-post-tool.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runNamedBin } from './_run.js'
+
+runNamedBin('wp-post-tool')

package/bin/wp-pretool-guard.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runNamedBin } from './_run.js'
+
+runNamedBin('wp-pretool-guard')

package/bin/wp-restore-dev-links.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runNamedBin } from './_run.js'
+
+runNamedBin('wp-restore-dev-links')

package/bin/wp-sessionstart-routing.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runNamedBin } from './_run.js'
+
+runNamedBin('wp-sessionstart-routing')

package/bin/wp-stop-qa.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runNamedBin } from './_run.js'
+
+runNamedBin('wp-stop-qa')

package/bin/wp-test-quality-check.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runNamedBin } from './_run.js'
+
+runNamedBin('wp-test-quality-check')

package/bin/wp.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runNamedBin } from './_run.js'
+
+runNamedBin('wp')