@webpresso/agent-kit 0.21.0

package/catalog/AGENTS.md.tpl

@@ -0,0 +1,202 @@
+<!--
+  AGENTS.md template.
+
+  Current-state agent-kit scaffolding (`wp setup`) renders this file with:
+  - Repository map: bulleted list of workspace packages inferred from
+    pnpm-workspace.yaml / package.json workspaces.
+  - Tech stack: short description generated from package.json + detected
+    frameworks (React, Hono, Drizzle, etc.).
+  - Escalation map: user-edited section. Left as a TODO placeholder if
+    not specified.
+  - Durable planning root: defaults to `.agent/planning/`. Override via
+    .webpressorc.json.
+  - Blueprints directory: defaults to `blueprints`. Override via
+    .webpressorc.json#blueprintsDir.
+
+  Managed sections in this file are refreshed by agent-kit. Sync uses `wp sync`.
+  Repo-specific edits belong only inside `user-owned` blocks; agent-kit preserves
+  those blocks verbatim when it rewrites managed content.
+-->
+
+<!-- >>> managed by webpresso (operating-contract) -->
+# Operating Contract
+
+This is the shared working agreement for contributors and coding agents in this
+repo. Prefer repo-local instructions when they are more specific than this
+starter template, and keep changes small, reviewable, and verified.
+
+## Setup after clone
+
+No agent surfaces are tracked in git — everything is regenerated. After cloning:
+
+```bash
+vp install && vp run setup:agent  # setup:agent runs wp setup, which scaffolds .agent/, AGENTS.md, hooks, and runs wp sync
+```
+
+agent-kit's catalog is the single source of truth for generated agent surfaces.
+`wp` is the canonical public CLI surface for setup, sync, and repo automation.
+To customize skills, commands, or workflows, edit them in agent-kit's catalog
+and publish — not in individual repos. The default `omx` preset chains
+`omx setup --yes --scope user` and installs missing OMX through
+`vp install -g oh-my-codex`. The default `omc` preset ensures OMC through
+Claude Code's plugin marketplace in user scope when `claude` is on `PATH`.
+`wp setup` also repairs the managed `.gitignore` block for regenerated agent
+surfaces so repo-local `.codex/`,
+`.omx/`, `.agent/`, and generated IDE projection outputs stay out of Git.
+Tracked vs ignored rule of thumb:
+
+- **Track** deliberate repo-owned instruction surfaces (for example
+  `AGENTS.md`, committed `.claude/commands/*.md` symlinks when the repo uses
+  them, and canonical sources such as `agent-rules/` / `agent-skills/`).
+- **Ignore** regenerated or local-only surfaces (for example `.agent/`,
+  `.agents/`, generated `.claude/rules/`, `.claude/skills/`,
+  `.claude/worktrees/`, editor-local state, and other runtime projections).
+
+`wp setup` / `wp sync` are the canonical bootstrap commands.
+
+## Plan
+
+Use blueprints for non-trivial work. Blueprint specs live in
+[`{{BLUEPRINTS_DIR}}/`](./{{BLUEPRINTS_DIR}}/) with lifecycle directories such
+as `planned/`, `in-progress/`, and `completed/`. Keep each blueprint's tasks,
+dependencies, verification commands, and acceptance criteria current before
+execution.
+
+Slash-commands and skills are loaded from agent-kit's catalog at setup time:
+
+- `.agent/commands/` — slash-command sources (from catalog).
+- `.agent/skills/` — skills (from catalog); edit in agent-kit, not here.
+
+## Implement
+
+Use this repo's task runner or package scripts instead of guessing commands from
+memory. If a wrapped command exists, prefer it over direct tool invocation so the
+repo can apply its environment, caching, and policy consistently.
+
+Before large edits, inspect nearby patterns and reuse existing utilities. Apply
+DRY, SOLID, YAGNI, and KISS as design filters; avoid new abstractions or
+dependencies unless the task explicitly requires them. Full details:
+`.agent/rules/engineering-principles.md`.
+
+Never use hardcoded relative filesystem paths in executable code or config.
+Derive absolute paths from an explicit absolute anchor instead (for example a
+repo-root helper, package-root helper, or runtime-provided absolute base
+path).
+
+## Verify
+
+Before claiming completion, run the narrowest checks that prove the changed
+behavior and any broader checks this repo requires. Typical gates are:
+
+- agent-kit MCP tools first when available; otherwise the repo-owned wrapper
+  command
+- typecheck
+- lint / format check
+- affected tests
+- repo policy checks such as `verify:paths` / `verify:secrets` when setup
+  scaffolded them
+- docs or blueprint validation when docs/plans changed
+- `wp sync --check` after `wp setup` to verify surfaces are in sync
+
+If a gate fails, fix the root cause or record the blocker with evidence.
+
+## Communicate
+
+Commit messages, PR descriptions, and decision records should explain why the
+change exists, what tradeoffs were made, and what was verified. Record durable
+architecture decisions in this repo's ADR or planning location if one exists.
+<!-- <<< managed by webpresso (operating-contract) -->
+
+<!-- >>> user-owned (repo-customizations) -->
+## Repo-specific customizations
+
+Add repo-local instructions, preferences, and exceptions here. Content inside
+this block is preserved verbatim across `wp sync` runs.
+<!-- <<< user-owned (repo-customizations) -->
+
+<!-- >>> managed by webpresso (planning-and-release) -->
+## Safety boundaries
+
+- Do not commit secrets or credentials.
+- Do not create or persist secret-bearing files like `.env`, `.env.local`, `.env.*.local`,
+  `.dev.vars`, or `.dev.vars.example` in the repository.
+- Route secret-scoped commands through the repo contract (`wp config secrets` +
+  `with-secrets -- <cmd>`); do not hardwire provider-specific wrappers in repo
+  scripts/docs.
+- Keep secret/path checks on shared audit surfaces when available: pre-commit
+  and repo scripts should route through `wp audit absolute-path-policy`,
+  local secret policy verification, and `audit-secret-provider-quarantine`.
+- Do not commit agent surfaces (`.agent/`, `.agents/`, `.gemini/`, `.cursor/`,
+  `.windsurf/`, `.omx/`, `.omc/`, `.codex/`, `.opencode/`) — they are gitignored and
+  regenerated by `wp setup` / `omx setup`.
+- Do not hand-edit generated or derived surfaces; edit the catalog in agent-kit.
+- Do not bypass hooks or verification gates to force a change through.
+- Do not use hardcoded relative filesystem paths in executable code or config;
+  derive absolute paths from an explicit anchor.
+- Treat publishable package tarballs as public disclosure surfaces even when a
+  registry is currently restricted; verify packed contents before changing
+  `files`, `bin`, `exports`, release workflows, or catalog assets. Full
+  details: `.agent/rules/public-package-safety.md`.
+- Do not assume Webpresso-specific paths, tools, or runtimes exist unless this
+  repo documents them.
+- Surface conflicts between this file and deeper repo instructions instead of
+  silently ignoring either.
+
+## Durable planning surface
+
+- Materialized by setup: blueprint lifecycle directories under
+  `{{BLUEPRINTS_DIR}}/` (`planned/`, `in-progress/`, `completed/`) and durable
+  plan files under `{{DURABLE_PLANNING_ROOT}}plans/` when PRDs or test specs
+  are generated.
+- Generated on demand (not created by setup): boundary contracts at
+  `{{DURABLE_PLANNING_ROOT}}contracts/`, lifecycle state at
+  `{{DURABLE_PLANNING_ROOT}}state/`, session notes at
+  `{{DURABLE_PLANNING_ROOT}}notepad.md`, and project memory at
+  `{{DURABLE_PLANNING_ROOT}}project-memory.json`.
+
+If work changes workspace ownership, build boundaries, or cross-package
+consumption mode, update the relevant boundary contract before claiming the plan
+is ready.
+
+## Releases
+
+All packages in the webpresso public umbrella use **Changesets**. Never push
+`v*` tags or manually bump `package.json#version`.
+
+To ship a change:
+1. `vp run changeset` — describe the change and select the bump type.
+2. Commit the generated `.changeset/<name>.md` alongside your code.
+3. Merge to `main`. The release workflow versions the package and publishes it
+   to the public npm registry.
+
+```bash
+vp run changeset:status   # see pending changesets
+```
+
+Full protocol: `.agent/rules/changeset-release.md`
+
+## Package conventions
+
+- No `../` parent-relative imports — use workspace deps + subpath exports.
+- No `.mjs` source files — write `.ts` (with Bun/Node shebang if needed).
+- Use `vp` as the command facade (`vp install`, `vp run <script>`) so Vite+ selects the repo-declared package-manager substrate. Do not call `npm`, `npx`, or raw package-manager globals for repo workflows unless a deeper repo instruction explicitly requires it.
+- All packages: `"type": "module"`, `publishConfig` → public npm registry.
+- Auth: use npm trusted publishing where available, or scope `NPM_TOKEN` to
+  publish-only flows. Never hardcode tokens.
+
+Full details: `.agent/rules/package-conventions.md`
+
+## Repository map
+
+{{REPOSITORY_MAP}}
+
+## Tech stack
+
+{{TECH_STACK}}
+<!-- <<< managed by webpresso (planning-and-release) -->
+
+<!-- >>> user-owned (escalation-map) -->
+## Escalation map
+
+{{ESCALATION_MAP}}
+<!-- <<< user-owned (escalation-map) -->

package/catalog/agent/.audit-budgets.yaml

@@ -0,0 +1,12 @@
+# Agent-kit audit budgets — override defaults here
+# Generated by wp setup; safe to modify and commit
+budgets:
+  codex-skill-listing-total:
+    max_bytes: 7000          # Codex 8000-char hard cap with 1KB headroom
+  claude-skill-description-each:
+    max_bytes: 800
+  agents-md-section-each:
+    max_bytes: 4096
+    suggest_compact_at: 0.75
+  skill-md-total-each:
+    max_bytes: 16384         # warn beyond 16KB; 22-33KB files trigger oversize

package/catalog/agent/agents/README.md

@@ -0,0 +1,22 @@
+---
+type: core
+last_updated: 2026-05-05
+---
+
+# Canonical Subagents
+
+These markdown files are the canonical Claude subagent definitions shipped by
+webpresso. `wp setup` distributes them to `.claude/agents/`.
+
+## Included Agents
+
+- `code-reviewer.md` — review changed code for regressions, missing tests, and maintainability risks
+- `security-auditor.md` — inspect trust boundaries, secrets handling, and auth-sensitive changes
+- `doc-writer.md` — update public docs, migration notes, and operational guidance
+- `explorer.md` — map the repo quickly before implementation or deeper review
+
+## Usage
+
+- Run `wp setup` to sync the canonical agents into `.claude/agents/`.
+- Keep custom consumer agents under `.claude/agents/*.md`; the scaffolder preserves them.
+- If a canonical agent drifts, re-run `wp setup` or `wp audit agents`.

package/catalog/agent/agents/code-reviewer.md

@@ -0,0 +1,34 @@
+---
+name: code-reviewer
+description: Review changed code for bugs, regressions, missing tests, and maintainability risks before merge.
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+model: sonnet
+---
+
+# Code Reviewer
+
+You are a focused review lane for code that already exists.
+
+## Primary responsibilities
+
+- Look for correctness bugs and behavioral regressions first.
+- Check whether tests cover the changed behavior and obvious failure paths.
+- Flag awkward or fragile changes when they raise maintenance cost.
+- Prefer concrete file/line evidence over broad style commentary.
+
+## Review stance
+
+- Findings first, highest severity first.
+- Treat missing tests as a product risk when behavior changed.
+- Avoid speculative nits unless they would likely become real defects.
+- Preserve existing architecture unless a local inconsistency creates risk.
+
+## Expected output
+
+- Short summary of overall risk.
+- Ranked findings with file references.
+- Any notable test gaps or assumptions.

package/catalog/agent/agents/doc-writer.md

@@ -0,0 +1,35 @@
+---
+name: doc-writer
+description: Update README, migration notes, operator docs, and examples to match shipped behavior.
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Edit
+  - Write
+model: sonnet
+---
+
+# Doc Writer
+
+You own documentation accuracy after code changes land.
+
+## Primary responsibilities
+
+- Update user-facing and operator-facing docs that describe changed behavior.
+- Keep examples, command snippets, and config references aligned with the code.
+- Prefer concise, direct prose over marketing or internal jargon.
+- Preserve the repo's tone and structure while tightening clarity.
+
+## Writing stance
+
+- Fact-check claims against the code and tests.
+- Do not invent features or guarantees that are not implemented.
+- Keep migration notes actionable and brief.
+- Surface any docs gaps that should block claiming the feature is done.
+
+## Expected output
+
+- High-signal doc edits.
+- Short note on which docs were updated and why.
+- Any remaining documentation gaps that still need follow-up.

package/catalog/agent/agents/explorer.md

@@ -0,0 +1,33 @@
+---
+name: explorer
+description: Map files, symbols, dependencies, and local patterns quickly before deeper work starts.
+tools:
+  - Read
+  - Grep
+  - Glob
+model: haiku
+---
+
+# Explorer
+
+You are the fast repo-mapping lane.
+
+## Primary responsibilities
+
+- Locate relevant files, symbols, and entrypoints quickly.
+- Summarize how the repo currently models a feature or dependency.
+- Highlight likely touch points, ownership boundaries, and test locations.
+- Stop short of redesigning or implementing unless explicitly asked.
+
+## Exploration stance
+
+- Prefer precise file references and short factual summaries.
+- Distinguish evidence from inference.
+- Avoid broad theory when the repo already answers the question.
+- Surface ambiguities or conflicts early so the main lane can choose cleanly.
+
+## Expected output
+
+- Tight map of the relevant files and patterns.
+- Clear answer to the specific lookup question.
+- Pointers to likely next files for implementation or review.

package/catalog/agent/agents/security-auditor.md

@@ -0,0 +1,34 @@
+---
+name: security-auditor
+description: Audit changes for trust-boundary, secret-handling, auth, and injection risks.
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+model: sonnet
+---
+
+# Security Auditor
+
+You review code through a security lens.
+
+## Primary responsibilities
+
+- Trace trust boundaries and identify where untrusted input crosses them.
+- Check authn/authz behavior, secrets handling, and privilege assumptions.
+- Look for injection, path traversal, SSRF, unsafe shelling, and config bypasses.
+- Flag insecure defaults or silent failure modes that weaken safety guarantees.
+
+## Review stance
+
+- Focus on practical exploit paths, not theoretical noise.
+- Cite the exact code path that creates the risk.
+- Distinguish hard vulnerabilities from defense-in-depth improvements.
+- Recommend the smallest fix that closes the risk cleanly.
+
+## Expected output
+
+- Severity-ranked findings with clear exploit or abuse path.
+- Concrete remediation guidance.
+- Residual risk notes when a change is only partially hardened.

package/catalog/agent/commands/audit-duplication.md

@@ -0,0 +1,34 @@
+---
+description: Run duplication analysis using jscpd and provide remediation guidance.
+---
+
+# /audit-duplication
+
+Run duplication analysis using jscpd and provide recommendations.
+
+## Steps
+
+1. Execute `just analysis-duplication` (or your repo's equivalent runner) to run jscpd
+2. Parse the console output or JSON report
+3. Identify top duplication clusters
+4. Provide specific recommendations for each cluster
+
+## Output Format
+
+- Summary of total duplication percentage
+- Top 5 duplication clusters with file locations
+- Specific recommendations for remediation
+- Suggested canonical packages for shared code
+
+## Example Usage
+
+```bash
+/audit-duplication
+```
+
+## Implementation Notes
+
+- Uses jscpd (JavaScript Code Plagiarism Detector)
+- Minimum 10 lines and 50 tokens for detection
+- Reports both syntactic and semantic duplicates
+- Suggests extraction to your repo's shared utility or types packages

package/catalog/agent/commands/audit.md

@@ -0,0 +1,219 @@
+---
+description: 'Unified audit command for code quality, test quality, duplication, and UX audits'
+argument-hint: '<type> [target] where type is: code|test|dup|ux|all'
+allowed-tools: Bash, Read, Glob, Grep, Task
+---
+
+# Audit Command
+
+Unified audit command that consolidates code quality, test quality, duplication, and UX audits.
+
+**Arguments**: $ARGUMENTS
+
+---
+
+## Usage
+
+```bash
+/audit <type> [target]
+```
+
+Repo CLI equivalent (with a just-based runner, for example webpresso's just recipes):
+
+```bash
+just audit <type> [target]
+```
+
+Substitute your own task runner (make, npm run, etc.) where needed.
+
+**Types:**
+
+| Type   | Description                                 | Output                                                    |
+| ------ | ------------------------------------------- | --------------------------------------------------------- |
+| `code` | SOLID, security, complexity, documentation  | `docs/research/quality-audits/code-quality-YYYY-MM-DD.md` |
+| `test` | Useless tests, gaps, brittleness, flakiness | `docs/research/quality-audits/test-quality-YYYY-MM-DD.md` |
+| `dup`  | Code duplication, extraction candidates     | `docs/research/quality-audits/duplication-YYYY-MM-DD.md`  |
+| `ux`   | Error states, loading, a11y, responsiveness | `docs/research/quality-audits/ux-quality-YYYY-MM-DD.md`   |
+| `all`  | Run all audits                              | All of the above                                          |
+
+**Examples:**
+
+```bash
+/audit code cli               # Audit code quality for cli package
+/audit test api               # Audit test quality for api package
+/audit dup                    # Find duplication across codebase
+/audit ux admin               # UX audit for admin package
+/audit all                    # Run all audits
+```
+
+---
+
+## Audit Type: `code`
+
+Comprehensive SOLID, security, complexity, and documentation audit.
+
+### Checks
+
+- SOLID principle violations
+- Security vulnerabilities (injection, auth, secrets)
+- Cognitive complexity > 8
+- Missing/outdated documentation
+- Dead code (`just analysis-dead-code` or your repo's equivalent)
+
+### Commands
+
+```bash
+just lint --package <target>
+just analysis-dead-code
+```
+
+---
+
+## Audit Type: `test`
+
+Find useless tests, coverage gaps, brittleness, and flakiness.
+
+### Checks
+
+- Tautological assertions (`expect(true).toBe(true)`)
+- Mock-heavy tests that don't test real behavior
+- Missing edge case coverage
+- Flaky tests (timing, order-dependent)
+- Low mutation score areas
+
+### Commands
+
+```bash
+just test --package <target>
+just test --mutation --package <package>
+```
+
+### Output Format
+
+Include confidence matrix and `file:line` evidence for each finding.
+
+---
+
+## Audit Type: `dup`
+
+Identify code duplication and extraction candidates.
+
+### Commands
+
+```bash
+just audit dup [target]           # Repo CLI equivalent
+just analysis-duplication         # Raw jscpd run — console + JSON report
+```
+
+### How It Works
+
+- Uses **jscpd** with a minimum of 10 lines / 50 tokens for detection
+- Reports both syntactic and semantic duplicates
+- Suggests extraction to shared utility or types packages in your repo
+
+### Checks
+
+- Interfaces/types duplicated across packages
+- Similar utilities (dates, validation, fetch wrappers)
+- Service clients/patterns repeated
+- Config duplication (tsconfig/biome/env patterns)
+
+### Output Format
+
+For each extraction candidate:
+
+- **Score**: Duplication severity (1-10)
+- **Files**: List of files with duplication
+- **Proposed API**: Suggested shared interface
+- **Migration Plan**: Steps to consolidate
+- **Canonical package**: Recommended shared target when applicable
+
+---
+
+## Audit Type: `ux`
+
+Audit UX quality across error states, loading states, accessibility, responsiveness.
+
+### Checks
+
+- Error state handling (empty, error, loading)
+- Accessibility (WCAG 2.1 AA compliance)
+- Responsive design breakpoints
+- Performance (LCP, FID, CLS)
+- Form validation UX
+
+### Output Format
+
+Include severity, location, and user impact for each finding.
+
+---
+
+## Report Template
+
+All audit reports should follow this structure:
+
+```markdown
+# [Audit Type] Audit Report
+
+**Date:** YYYY-MM-DD
+**Target:** [package/file/scope]
+**Auditor:** Claude
+
+## Executive Summary
+
+- Total findings: X
+- P0 (Critical): X
+- P1 (High): X
+- P2 (Medium): X
+
+## Findings
+
+### P0: Critical
+
+#### [Finding Title]
+
+- **Location:** `file:line`
+- **Description:** What's wrong
+- **Impact:** Why it matters
+- **Recommendation:** How to fix
+
+### P1: High
+
+...
+
+## Follow-up Actions
+
+- [ ] Action item 1
+- [ ] Action item 2
+```
+
+---
+
+## Execution Protocol
+
+1. Parse `$ARGUMENTS` to determine audit type and target
+2. Run appropriate checks for the audit type
+3. Generate report in the specified output location
+4. Summarize findings with P0/P1 highlights
+
+---
+
+## Dead Code Analysis Notes
+
+Use `just analysis-dead-code` (or your repo's equivalent knip runner) carefully before deleting files.
+
+Known false-positive areas:
+
+- Dynamic imports such as `lazy(() => import('./file'))`
+- Barrel files (`index.ts`) where consumers import subpaths directly
+- React Router generated `+types/*`
+- Storybook stories and test utilities
+- Pulumi or other infra files loaded indirectly
+
+Verification steps before deleting:
+
+1. Run `just analysis-dead-code` and read the knip log it emits
+2. Grep for imports/usages across the relevant package
+3. Check for `import()` or `lazy()` usage
+4. Confirm the file is not a barrel-only or infra-only entrypoint
+5. Never delete a file that might be dynamically loaded without proof