@webpresso/agent-kit 0.21.0

package/catalog/agent/skills/web-design-guidelines/SKILL.md

@@ -0,0 +1,53 @@
+---
+type: skill
+slug: web-design-guidelines
+title: Web Interface Guidelines
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: '2026-05-07'
+last_reviewed: '2026-05-07'
+name: web-design-guidelines
+description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
+metadata: 
+  author: vercel
+  version: '1.0.0'
+  argument-hint: <file-or-pattern>
+license: MIT
+upstream: 
+  source: https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
+  last_synced: "2026-05-28"
+---
+
+# Web Interface Guidelines
+
+Review files for compliance with Web Interface Guidelines.
+
+## How It Works
+
+1. Fetch the latest guidelines from the source URL below
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the fetched guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```
+https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+
+## Usage
+
+When a user provides a file or pattern argument:
+
+1. Fetch guidelines from the source URL above
+2. Read the specified files
+3. Apply all rules from the fetched guidelines
+4. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.

package/catalog/agent/workflows/README.md

@@ -0,0 +1,20 @@
+---
+type: core
+last_updated: 2026-04-22
+---
+
+# Workflow Index
+
+Workflow docs in this directory are short operator playbooks for common agent tasks.
+
+## Available Workflows
+
+- `conf.md` — confidence / verification workflow
+- `debug.md` — debugging workflow
+- `docs.md` — documentation update workflow
+- `execute-plan.md` — implementation execution workflow
+- `write-plan.md` — implementation planning workflow
+- `test.md` — test execution workflow
+- `fix-all-md-warnings.md` — markdown lint remediation workflow
+
+Open the specific workflow file you need instead of assuming a generic process.

package/catalog/agent/workflows/conf.md

@@ -0,0 +1,18 @@
+---
+description: Confidence Protocol - A rigorous, state-of-the-art interview process for gathering requirements and configuration with 100% confidence.
+---
+
+# /conf: The Confidence Protocol
+
+Goal: gather requirements with zero ambiguity and low cognitive load.
+
+## Steps
+
+1. **Prep (silent)**: read AGENTS.md + relevant files; infer defaults from existing patterns.
+2. **Gap analysis**: identify unknowns vs. safe assumptions.
+3. **Interview loop** (one question at a time):
+   - Context → Question → Default → Optional alternatives.
+4. **Validate**: confirm answers are precise, secure, and schema-aligned.
+5. **Contract**: present final summary and request explicit approval.
+
+Checklist: one question at a time, sensible defaults, no secrets in chat, remind about docs updates.

package/catalog/agent/workflows/debug.md

@@ -0,0 +1,20 @@
+---
+description: Systematic debugging - find root cause before attempting fixes
+---
+
+## Systematic Debugging
+
+Random fixes waste time. Find root cause first.
+
+## Checklist
+
+1. Read the full error/stack trace.
+2. Reproduce reliably; note exact steps.
+3. Inspect recent changes (diffs, configs).
+4. Gather evidence across components (log inputs/outputs).
+5. Compare with a working example; list differences.
+6. Form one hypothesis and test the smallest change.
+7. Write a failing test, fix once, re-run.
+8. After 3 failed fixes: stop and question architecture.
+
+Red flags: "quick fix", guessing, multiple fixes at once, or no reproduction.

package/catalog/agent/workflows/docs.md

@@ -0,0 +1,9 @@
+---
+description: Update documentation and agent instructions based on recent context.
+---
+
+1. Review recent context (task files + recent changes).
+2. Identify targets (AGENTS.md, docs/\*, tool entry points).
+3. Edit with apply_patch; follow templates in `docs/`.
+4. Validate with the repo's documentation check (e.g. `just docs`, `pnpm docs:check`, or equivalent) and apply fixes if needed.
+5. Summarize updates and locations.

package/catalog/agent/workflows/execute-plan.md

@@ -0,0 +1,15 @@
+---
+description: Execute a plan from a blueprint or plan file.
+---
+
+# Execute Plan
+
+Runs the steps defined in a plan or blueprint.
+
+## Steps
+
+1. Parse the plan file for tasks and dependencies
+2. Execute tasks in dependency order
+3. Report progress and results
+
+See the plan command for creating and managing plans.

package/catalog/agent/workflows/fix-all-md-warnings.md

@@ -0,0 +1,13 @@
+---
+description: Fix all markdown warnings across the repository.
+---
+
+# Fix All MD Warnings
+
+Automatically fixes markdown lint warnings across all documentation.
+
+## Steps
+
+1. Run markdown lint to identify warnings
+2. Apply automatic fixes where possible
+3. Report remaining issues that need manual attention

package/catalog/agent/workflows/test.md

@@ -0,0 +1,14 @@
+---
+description: Test execution workflow for running and verifying tests.
+---
+
+# Test Workflow
+
+Run and verify tests across the repository.
+
+## Steps
+
+1. Identify the target scope (package, file, or all)
+2. Run tests with appropriate configuration
+3. Review results and fix failures
+4. Re-run to verify fixes

package/catalog/agent/workflows/write-plan.md

@@ -0,0 +1,16 @@
+---
+description: Create detailed implementation plan with bite-sized tasks, dependencies, and rollback steps
+---
+
+## Writing Implementation Plans
+
+1. Review design and clarify unknowns.
+2. Create the draft with `wp blueprint new "<goal>" --complexity <XS|S|M|L|XL>`, then refine the generated file in `blueprints/draft/{slug}/`.
+3. Tasks are bite-sized with exact files, tests, commands, and expected output.
+4. Include dependencies and rollback per task.
+5. Offer execution via `/pll`.
+
+**Important:**
+
+- Use t-shirt sizing (XS/S/M/L/XL) for estimates, NEVER day/week estimates
+- Remember: exact paths, complete code, DRY/YAGNI/TDD, frequent commits

package/catalog/base-kit/.actrc.tmpl

@@ -0,0 +1,2 @@
+-P ubicloud-standard-2=ghcr.io/catthehacker/ubuntu:js-latest
+--container-architecture linux/amd64

package/catalog/base-kit/.editorconfig.tmpl

@@ -0,0 +1,23 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+max_line_length = 100
+trim_trailing_whitespace = true
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab
+
+[*.{yaml,yml}]
+indent_size = 2
+
+[*.json]
+insert_final_newline = false

package/catalog/base-kit/.github/workflows/ci.webpresso.yml.tmpl

@@ -0,0 +1,66 @@
+name: CI (webpresso baseline)
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+env:
+  # Opt the workflow's JavaScript actions into Node.js 24 ahead of the
+  # 2026-06-02 GitHub default switch (replaces the deprecation warning
+  # surfaced by actions/checkout@v4, actions/setup-node@v4, and
+  # pnpm/action-setup@v4 internally running on Node 20).
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '24.16.0'
+          cache: pnpm
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run verify:secrets
+      - run: pnpm run audit:secret-provider-quarantine
+      - run: pnpm run typecheck
+      - run: pnpm run lint
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '24.16.0'
+          cache: pnpm
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run test
+
+  wp-audits:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '24.16.0'
+          cache: pnpm
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: pnpm install --frozen-lockfile
+      - name: Run wp audit guardrails
+        run: |
+          WP="$(pwd)/node_modules/.bin/wp"
+          [ -x "$WP" ] || WP=wp
+          "$WP" audit guardrails

package/catalog/base-kit/.gitignore.tmpl

@@ -0,0 +1,82 @@
+# Dependencies
+node_modules/
+.pnpm-store/
+
+# Build outputs
+dist/
+build/
+.next/
+out/
+.output/
+.vercel/
+.netlify/
+
+# TypeScript
+*.tsbuildinfo
+tsconfig.tsbuildinfo
+
+# Testing
+coverage/
+.nyc_output/
+
+# E2E Testing
+playwright-report/
+test-results/
+*.auth.json
+
+# Environment files
+.env
+*.env.*
+!.env.example
+.dev.vars
+.dev.vars.*
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# IDE — JetBrains
+.idea/
+*.iml
+*.iws
+
+# IDE — VS Code (keep settings, ignore personal)
+.vscode/*.log
+
+# Misc
+*.backup
+*.bak
+.cache/
+tmp/
+.tmp/
+
+# Agent surfaces — regenerated by `wp setup` and `wp symlink sync`.
+# Edit the catalog in webpresso, then run `wp setup --overwrite`.
+.agent/
+.agents/
+.gemini/
+.cursor/
+.windsurf/
+.omx/
+.omc/
+.codex/
+.opencode/
+# .claude/ is partially tracked:
+#   settings.json, hooks/, rules/ — committed so worktrees inherit them
+#   worktrees/ and skills/ — gitignored (runtime / user-global)
+.claude/worktrees/
+.claude/skills/
+.claude/scheduled_tasks.lock

package/catalog/base-kit/.husky/commit-msg.tmpl

@@ -0,0 +1,7 @@
+#!/usr/bin/env sh
+set -eu
+# Prefer local node_modules/.bin/wp; fall back to global wp for repos
+# that rely on the global install (no local webpresso devDep).
+WP="$(git rev-parse --show-toplevel)/node_modules/.bin/wp"
+[ -x "$WP" ] || WP=wp
+"$WP" audit commit-message --message-file "$1"

package/catalog/base-kit/.husky/pre-commit.tmpl

@@ -0,0 +1,10 @@
+#!/usr/bin/env sh
+set -eu
+# Prefer local node_modules/.bin/wp; fall back to global wp for repos
+# that rely on the global install (no local webpresso devDep).
+WP="$(git rev-parse --show-toplevel)/node_modules/.bin/wp"
+[ -x "$WP" ] || WP=wp
+bun scripts/check-no-dev-vars.ts
+"$WP" audit absolute-path-policy --root .
+bun scripts/audit-secret-provider-quarantine.ts
+"$WP" audit guardrails

package/catalog/base-kit/.secretlintrc.json.tmpl

@@ -0,0 +1,5 @@
+{
+  "rules": [
+    { "id": "@secretlint/secretlint-rule-preset-recommend" }
+  ]
+}

package/catalog/base-kit/commitlint.config.ts.tmpl

@@ -0,0 +1,7 @@
+import type { UserConfig } from '@commitlint/types'
+
+const config: UserConfig = {
+  extends: ['@commitlint/config-conventional'],
+}
+
+export default config

package/catalog/base-kit/pnpm-workspace.yaml.tmpl

@@ -0,0 +1,49 @@
+packages:
+  - packages/*
+  - apps/*
+
+catalog:
+  # TypeScript compiler and type infrastructure
+  typescript: ^5.9.3
+
+  # Testing
+  vitest: ^4.1.4
+  '@vitest/coverage-v8': ^4.1.4
+
+  # Linting and formatting
+  eslint: ^9.0.0
+  prettier: ^3.0.0
+
+  # Build tooling
+  vite: ^8.0.0
+  tsup: ^8.0.0
+
+  # Node types
+  '@types/node': ^22.0.0
+
+  # Commit tooling
+  husky: ^9.0.0
+  '@commitlint/cli': ^19.0.0
+  '@commitlint/config-conventional': ^19.0.0
+
+  # Secret linting
+  secretlint: ^9.0.0
+  '@secretlint/secretlint-rule-preset-recommend': ^9.0.0
+
+  # AI SDK
+  '@anthropic-ai/sdk': ^0.71.2
+
+  # HTTP
+  zod: ^4.3.6
+
+  # Utilities
+  yaml: ^2.8.1
+  dotenv: ^16.0.0
+
+  # React (if applicable)
+  react: ^19.0.0
+  react-dom: ^19.0.0
+  '@types/react': ^19.0.0
+  '@types/react-dom': ^19.0.0
+
+cleanupUnusedCatalogs: true

package/catalog/base-kit/scripts/audit-secret-provider-quarantine.ts.tmpl

@@ -0,0 +1,91 @@
+#!/usr/bin/env bun
+
+import { readdirSync, readFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+const ROOT = process.cwd()
+const IGNORED_DIRS = new Set([
+  '.git',
+  'node_modules',
+  '.agent',
+  '.claude',
+  '.codex',
+  '.omx',
+  '.omc',
+  'blueprints',
+  'dist',
+  'coverage',
+])
+
+const TEXT_FILE_PATTERN = /\.(md|ts|tsx|js|json|ya?ml|toml|txt)$/i
+
+const BANNED_PATTERNS: Array<{ pattern: RegExp; message: string }> = [
+  { pattern: /\bdoppler run\b/, message: 'use `with-secrets -- <cmd>` instead of `doppler run`' },
+  {
+    pattern: /\bwith-secrets\s+--doppler\b/,
+    message: 'use selected-manager `with-secrets -- <cmd>` instead of provider flags',
+  },
+  {
+    pattern: /\bwith-secrets\s+--infisical\b/,
+    message: 'use selected-manager `with-secrets -- <cmd>` instead of provider flags',
+  },
+  {
+    pattern: /\bdoppler secrets download\b/,
+    message: 'load secrets through runtime/env, not direct provider downloads',
+  },
+  {
+    pattern: /runtime\/process\/secret-runner/,
+    message: 'use `@webpresso/webpresso/runtime/env` instead of secret-runner',
+  },
+]
+
+const violations: string[] = []
+const SELF_RELATIVE_PATH = 'scripts/audit-secret-provider-quarantine.ts'
+const ALLOWED_RELATIVE_PATHS = new Set([
+  'src/hooks/pretool-guard/dev-routing.ts',
+  'src/hooks/pretool-guard/dev-routing.test.ts',
+  'src/hooks/pretool-guard/validators/forbidden-commands.ts',
+  'src/hooks/pretool-guard/validators/forbidden-commands.test.ts',
+])
+
+walk(ROOT)
+
+if (violations.length > 0) {
+  console.error('Secret-provider quarantine violations detected:\n')
+  for (const violation of violations) {
+    console.error(`- ${violation}`)
+  }
+  process.exit(1)
+}
+
+console.log('Secret-provider quarantine: clean.')
+
+function walk(directory: string) {
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (IGNORED_DIRS.has(entry.name)) {
+      continue
+    }
+
+    const fullPath = join(directory, entry.name)
+    if (entry.isDirectory()) {
+      walk(fullPath)
+      continue
+    }
+
+    if (!entry.isFile() || !TEXT_FILE_PATTERN.test(entry.name)) {
+      continue
+    }
+
+    const content = readFileSync(fullPath, 'utf8')
+    const relPath = relative(ROOT, fullPath)
+    if (relPath === SELF_RELATIVE_PATH || ALLOWED_RELATIVE_PATHS.has(relPath)) {
+      continue
+    }
+
+    for (const { pattern, message } of BANNED_PATTERNS) {
+      if (pattern.test(content)) {
+        violations.push(`${relPath}: ${message}`)
+      }
+    }
+  }
+}

package/catalog/base-kit/scripts/check-no-dev-vars.ts.tmpl

@@ -0,0 +1,56 @@
+import { readdirSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+const root = process.cwd()
+const forbidden: string[] = []
+
+function walk(dir: string): void {
+  let entries: string[] = []
+  try {
+    entries = readdirSync(dir, { withFileTypes: true }).map((entry) => entry.name)
+  } catch {
+    return
+  }
+
+  for (const name of entries) {
+    if (name === '.git' || name === 'node_modules') {
+      continue
+    }
+
+    const fullPath = join(dir, name)
+    let stat: ReturnType<typeof statSync>
+    try {
+      stat = statSync(fullPath)
+    } catch {
+      continue
+    }
+
+    if (stat.isDirectory()) {
+      walk(fullPath)
+      continue
+    }
+
+    if (!stat.isFile()) {
+      continue
+    }
+
+    const isEnvFile = (name === '.env' || /^\.env(?:\..+)?$/.test(name)) && name !== '.env.example'
+    if (name === '.dev.vars' || /^\.dev\.vars(?:\..+)?$/.test(name) || isEnvFile) {
+      forbidden.push(relative(root, fullPath))
+    }
+  }
+}
+
+walk(root)
+
+if (forbidden.length > 0) {
+  console.error(
+    'ERROR: forbidden .dev.vars or .env files detected. Secrets must be managed by secret providers, not written to disk:',
+  )
+  for (const file of forbidden) {
+    console.log(file)
+  }
+  process.exit(1)
+}
+
+console.log('OK: no forbidden .dev.vars or .env files present in repo working tree')

package/catalog/docs/templates/adr.md

@@ -0,0 +1,38 @@
+---
+type: adr
+last_updated: "YYYY-MM-DD"
+---
+
+# ADR NNNN: {{Title}}
+
+- **Status:** proposed | accepted | superseded by ADR-MMMM | rejected
+- **Date:** YYYY-MM-DD
+- **Decider(s):** names
+
+## Context
+
+What forces are at play? What constraints apply? Cite concrete repo files,
+incident reports, or external constraints — not generic industry trends.
+
+## Decision
+
+We will …
+
+## Consequences
+
+### Positive
+
+- …
+
+### Negative
+
+- …
+
+### Neutral / follow-ups
+
+- …
+
+## Alternatives considered
+
+- **Alternative A** — rejected because …
+- **Alternative B** — rejected because …