@webpresso/agent-kit 0.21.0

package/skills/pll/SKILL.md

@@ -0,0 +1,85 @@
+---
+type: skill
+slug: pll
+title: PLL Skill — Blueprint-Aware Parallel Execution
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: '2026-05-07'
+last_reviewed: '2026-05-07'
+name: pll
+description: Blueprint-aware parallel execution adapter over ultrawork/subagents. If OMX isn't installed, the skill uses the `local-worktree` backend (default for repos without OMX).
+---
+
+# PLL Skill — Blueprint-Aware Parallel Execution
+
+Use this skill when the user invokes `/pll` or asks for Blueprint-aware parallel execution.
+
+`/pll` is not a standalone runner. It is the operator-facing adapter over the same shared execution model used by `wp blueprint exec`: both surfaces consume the same Blueprint-backed launch spec, backend vocabulary, and runtime-state bridge, but `/pll` stays manual and operator-facing.
+
+`/pll`:
+
+1. understands Blueprint/task dependencies
+2. updates `wp blueprint` lifecycle state honestly
+3. delegates generic parallel fan-out to the engine layer such as `$ultrawork` or host-native subagents
+
+> **Backends**: `/pll` can delegate to `omx-team` or `omx-pll-interactive` when OMX is installed. If OMX isn't installed, the skill uses the `local-worktree` backend (default for repos without OMX).
+
+## Responsibilities
+
+1. **Input parsing**
+   - Accept inline task lists, comma-separated strings, or file paths.
+   - Treat blueprint paths under `blueprints/` as lifecycle-backed execution.
+2. **Blueprint lifecycle**
+   - Use `wp blueprint start`, `wp blueprint task ...`, and `wp blueprint finalize` for durable state.
+   - Never use `wp blueprint move` as the normal execution primitive.
+   - Keep the lifecycle semantics aligned with `wp blueprint exec`; do not invent a separate `/pll`-only plan model.
+3. **Dependency-aware batching**
+   - Compute ready work from explicit dependencies and obvious blocking relationships.
+   - Prioritize critical-path or high-fan-out work when choosing the next batch.
+4. **Engine delegation**
+   - Hand independent work to the current engine layer (`$ultrawork`, subagents, or equivalent runtime-native parallel lanes).
+   - Do not promise a fixed active-agent count across runtimes.
+5. **Verification discipline**
+   - Require repo verification before marking blueprint tasks complete.
+6. **Shared execution model**
+   - Treat `/pll` as the interactive/manual front door for the same control-plane contract that `wp blueprint exec` uses.
+   - Reuse the same backend names, progress bridge semantics, and truthfulness rules.
+
+
+## Roadmap-Aware Lane Picking
+
+When no explicit task list is supplied, ground lane selection in `wp blueprint list` before inventing work:
+
+1. Prefer active `ROADMAP` rows and pick the next `planned` `CHILD` row whose `depends_on:` chain is satisfied.
+2. Treat `ORPHANS` as fallback work only when no roadmap child is actionable.
+3. Keep the heuristic discoverable and auditable: `wp audit roadmap-links` checks bidirectional roadmap/child links, while `wp audit blueprint-lifecycle` checks lifecycle placement.
+4. If command output changes, update `/pll` guidance and the shared blueprint output contract together.
+
+## Concurrency Limits
+
+| Scope | Guidance |
+| --- | --- |
+| Default batches | Use the smallest parallelism that still keeps safe independent lanes busy |
+| Test-heavy tasks | Keep concurrency conservative |
+| Build/deploy tasks | Keep concurrency conservative |
+
+## Deadlock and Failure Handling
+
+- If no tasks remain ready but some are blocked, report the blocking tasks and their dependencies.
+- Failed tasks stay blocked with reasons; downstream work remains blocked unless explicitly safe to continue.
+- If lifecycle mutation fails, stop instead of continuing with stale plan state.
+
+## When **NOT** to use
+
+- Small, strictly serial work where `/plan` or direct execution is simpler.
+- Situations where you only need generic parallel fan-out and do not need Blueprint lifecycle/state awareness; use `$ultrawork` directly there.
+
+## Quick Start Examples
+
+```bash
+/pll "lint auth, lint utils, typecheck api [depends: lint auth], test api [depends: typecheck api]"
+/pll tasks.md --max=6
+/pll blueprints/in-progress/new-launch/_overview.md
+```

package/skills/react-doctor/SKILL.md

@@ -0,0 +1,54 @@
+---
+type: skill
+slug: react-doctor
+title: React Doctor
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: '2026-05-07'
+last_reviewed: '2026-05-07'
+name: react-doctor
+description: Diagnose and fix React codebase health issues. Use when reviewing React code, fixing performance problems, auditing security, or improving code quality.
+version: 1.0.0
+license: MIT
+upstream: 
+  source: https://github.com/millionco/react-doctor/tree/main/packages/react-doctor
+  last_synced: "2026-05-28"
+---
+
+# React Doctor
+
+Scans your React codebase for security, performance, correctness, and architecture issues. Outputs a 0-100 score with actionable diagnostics.
+
+## Usage
+
+```bash
+vp dlx react-doctor@latest . --verbose
+```
+
+## Workflow
+
+1. Run the command above at the project root
+2. Read every diagnostic with file paths and line numbers
+3. Fix issues starting with errors (highest severity)
+4. Re-run to verify the score improved
+
+## Rules (47+)
+
+- **Security**: hardcoded secrets in client bundle, eval()
+- **State & Effects**: derived state in useEffect, missing cleanup, useState from props, cascading setState
+- **Architecture**: components inside components, giant components, inline render functions
+- **Performance**: layout property animations, transition-all, large blur values
+- **Correctness**: array index as key, conditional rendering bugs
+- **Next.js**: missing metadata, client-side fetching for server data, async client components
+- **Bundle Size**: barrel imports, full lodash, moment.js, missing code splitting
+- **Server**: missing auth in server actions, blocking without after()
+- **Accessibility**: missing prefers-reduced-motion
+- **Dead Code**: unused files, exports, types
+
+## Score
+
+- **75+**: Great
+- **50-74**: Needs work
+- **0-49**: Critical

package/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,322 @@
+---
+type: skill
+slug: systematic-debugging
+title: Systematic Debugging
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: '2026-05-07'
+last_reviewed: '2026-05-07'
+name: systematic-debugging
+description: Provides systematic debugging methodology for bugs, test failures, and unexpected behavior. Emphasizes root cause investigation before proposing fixes
+---
+
+# Systematic Debugging
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+If your repo has a rule on deterministic external boundaries (e.g. `.agent/rules/agent-guide.md`), follow it for timeout, polling, and async-boundary fixes.
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes.
+
+## When to Use
+
+Use for ANY technical issue:
+
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+**Use this ESPECIALLY when:**
+
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+- You don't fully understand the issue
+
+**Don't skip when:**
+
+- Issue seems simple (simple bugs have root causes too)
+- You're in a hurry (rushing guarantees rework)
+- Manager wants it fixed NOW (systematic is faster than thrashing)
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings
+   - They often contain the exact solution
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+   - Prefer lightweight evidence gathering first (`rg -n` for search, `sed -n` for exact ranges) before reaching for heavier ad hoc scripts
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - Does it happen every time?
+   - If not reproducible → gather more data, don't guess
+
+3. **Check Recent Changes**
+   - What changed that could cause this?
+   - Git diff, recent commits
+   - New dependencies, config changes
+   - Environmental differences
+
+4. **Gather Evidence in Multi-Component Systems**
+
+   **WHEN system has multiple components (CI → build → signing, API → service → database):**
+
+   **BEFORE proposing fixes, add diagnostic instrumentation:**
+
+   ```
+   For EACH component boundary:
+     - Log what data enters component
+     - Log what data exits component
+     - Verify environment/config propagation
+     - Check state at each layer
+
+   Run once to gather evidence showing WHERE it breaks
+   THEN analyze evidence to identify failing component
+   THEN investigate that specific component
+   ```
+
+   **Example (multi-layer system):**
+
+   ```bash
+   # Layer 1: Workflow
+   echo "=== Secrets available in workflow: ==="
+   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
+
+   # Layer 2: Build script
+   echo "=== Env vars in build script: ==="
+   env | grep IDENTITY || echo "IDENTITY not in environment"
+
+   # Layer 3: Signing script
+   echo "=== Keychain state: ==="
+   security list-keychains
+   security find-identity -v
+
+   # Layer 4: Actual signing
+   codesign --sign "$IDENTITY" --verbose=4 "$APP"
+   ```
+
+   **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
+
+5. **Trace Data Flow**
+
+   **WHEN error is deep in call stack:**
+
+   See `root-cause-tracing.md` in this directory for the complete backward tracing technique.
+
+   **Quick version:**
+   - Where does bad value originate?
+   - What called this with bad value?
+   - Keep tracing up until you find the source
+   - Fix at source, not at symptom
+
+### Phase 2: Pattern Analysis
+
+**Find the pattern before fixing:**
+
+1. **Find Working Examples**
+   - Locate similar working code in same codebase
+   - What works that's similar to what's broken?
+
+2. **Compare Against References**
+   - If implementing pattern, read reference implementation COMPLETELY
+   - Don't skim - read every line
+   - Understand the pattern fully before applying
+   - For framework or tool behavior, prefer official docs over secondary summaries
+
+3. **Identify Differences**
+   - What's different between working and broken?
+   - List every difference, however small
+   - Don't assume "that can't matter"
+
+4. **Understand Dependencies**
+   - What other components does this need?
+   - What settings, config, environment?
+   - What assumptions does it make?
+
+### Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis**
+   - State clearly: "I think X is the root cause because Y"
+   - Write it down
+   - Be specific, not vague
+
+2. **Test Minimally**
+   - Make the SMALLEST possible change to test hypothesis
+   - One variable at a time
+   - Don't fix multiple things at once
+
+3. **Verify Before Continuing**
+   - Did it work? Yes → Phase 4
+   - Didn't work? Form NEW hypothesis
+   - DON'T add more fixes on top
+
+4. **When You Don't Know**
+   - Say "I don't understand X"
+   - Don't pretend to know
+   - Ask for help
+   - Research more
+
+### Phase 4: Implementation
+
+**Fix the root cause, not the symptom:**
+
+1. **Create Failing Test Case**
+   - Simplest possible reproduction
+   - Automated test if possible
+   - One-off test script if no framework
+   - MUST have before fixing
+   - Use the `webpresso:test-driven-development` skill for writing proper failing tests
+
+2. **Implement Single Fix**
+   - Address the root cause identified
+   - ONE change at a time
+   - No "while I'm here" improvements
+   - No bundled refactoring
+
+3. **Verify Fix**
+   - Test passes now?
+   - No other tests broken?
+   - Issue actually resolved?
+
+4. **If Fix Doesn't Work**
+   - STOP
+   - Count: How many fixes have you tried?
+   - If < 3: Return to Phase 1, re-analyze with new information
+   - **If ≥ 3: STOP and question the architecture (step 5 below)**
+   - DON'T attempt Fix #4 without architectural discussion
+
+5. **If 3+ Fixes Failed: Question Architecture**
+
+   **Pattern indicating architectural problem:**
+   - Each fix reveals new shared state/coupling/problem in different place
+   - Fixes require "massive refactoring" to implement
+   - Each fix creates new symptoms elsewhere
+
+   **STOP and question fundamentals:**
+   - Is this pattern fundamentally sound?
+   - Are we "sticking with it through sheer inertia"?
+   - Should we refactor architecture vs. continue fixing symptoms?
+
+   **Discuss with your human partner before attempting more fixes**
+
+   This is NOT a failed hypothesis - this is a wrong architecture.
+
+## Red Flags - STOP and Follow Process
+
+If you catch yourself thinking:
+
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "Pattern says X but I'll adapt it differently"
+- "Here are the main problems: [lists fixes without investigation]"
+- Proposing solutions before tracing data flow
+- **"One more fix attempt" (when already tried 2+)**
+- **Each fix reveals new problem in different place**
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+**If 3+ fixes failed:** Question the architecture (see Phase 4.5)
+
+## your human partner's Signals You're Doing It Wrong
+
+**Watch for these redirections:**
+
+- "Is that not happening?" - You assumed without verifying
+- "Will it show us...?" - You should have added evidence gathering
+- "Stop guessing" - You're proposing fixes without understanding
+- "Ultrathink this" - Question fundamentals, not just symptoms
+- "We're stuck?" (frustrated) - Your approach isn't working
+
+**When you see these:** STOP. Return to Phase 1.
+
+## Common Rationalizations
+
+| Excuse                                       | Reality                                                                 |
+| -------------------------------------------- | ----------------------------------------------------------------------- |
+| "Issue is simple, don't need process"        | Simple issues have root causes too. Process is fast for simple bugs.    |
+| "Emergency, no time for process"             | Systematic debugging is FASTER than guess-and-check thrashing.          |
+| "Just try this first, then investigate"      | First fix sets the pattern. Do it right from the start.                 |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it.                       |
+| "Multiple fixes at once saves time"          | Can't isolate what worked. Causes new bugs.                             |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely.              |
+| "I see the problem, let me fix it"           | Seeing symptoms ≠ understanding root cause.                             |
+| "One more fix attempt" (after 2+ failures)   | 3+ failures = architectural problem. Question pattern, don't fix again. |
+
+## Quick Reference
+
+| Phase                 | Key Activities                                         | Success Criteria            |
+| --------------------- | ------------------------------------------------------ | --------------------------- |
+| **1. Root Cause**     | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY     |
+| **2. Pattern**        | Find working examples, compare                         | Identify differences        |
+| **3. Hypothesis**     | Form theory, test minimally                            | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify                               | Bug resolved, tests pass    |
+
+## When Process Reveals "No Root Cause"
+
+If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
+
+1. You've completed the process
+2. Document what you investigated
+3. Implement appropriate handling (retry, timeout, error message)
+4. Add monitoring/logging for future investigation
+
+**But:** 95% of "no root cause" cases are incomplete investigation.
+
+## Supporting Techniques
+
+These techniques are part of systematic debugging and available in this directory:
+
+- **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
+- **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
+- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
+
+**Related skills:**
+
+- **webpresso:test-driven-development** - For creating failing test case (Phase 4, Step 1)
+- **webpresso:verify** - Verify fix worked before claiming success
+
+## Real-World Impact
+
+From debugging sessions:
+
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common
+
+## See also
+
+- `/investigate` (gstack) — interactive variant with live browser controls, freeze hooks, and human-in-the-loop debugging. Choose `/investigate` when you need to interact with a running UI. Use this skill for headless agent runs without a human in the loop.

package/skills/tanstack-query/SKILL.md

@@ -0,0 +1,175 @@
+---
+type: skill
+slug: tanstack-query
+title: TanStack Query hard-cut contract
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: '2026-05-07'
+last_reviewed: '2026-05-07'
+name: tanstack-query
+description: |
+  Apply a canonical TanStack Query v5 contract: SDK-first query and mutation factories, suspense-first route data, QueryClient defaults with throwOnError, prefetch-aware loaders, infinite-query primitives, and generator-first CRUD guidance.
+user-invocable: true
+upstream: 
+  source: null
+  last_synced: "2026-04-22"
+---
+
+# TanStack Query hard-cut contract
+
+Primary contract guide: `.agent/guides/tanstack-query-contract.md` (if present in your repo).
+
+## What this skill is for
+
+Use this skill when you need to:
+
+- add or refactor TanStack Query usage in a React app
+- replace ad-hoc query/mutation code with reusable factories
+- wire route-critical data through RR7 `clientLoader` + suspense
+- standardize optimistic updates, paginated feeds, or pending-state UX
+- decide whether a new hand-written query layer is allowed at all
+
+This skill is **not** the generic place for TanStack Query trivia. It encodes
+one repository contract derived from a `tanstack-query-hardcut` blueprint.
+
+## Canonical contract
+
+### 1) Generated contracts own CRUD first
+
+If the surface is YAML-backed or already expressible through generated CRUD
+outputs, prefer generated frontend hooks/factories first.
+
+Only add a hand-written query module when it is clearly one of these:
+
+- custom non-CRUD business flow
+- composition across multiple generated operations
+- temporary bridge until generator support lands
+
+If you still need a new hand-written YAML-backed module, document the D23
+exception explicitly:
+
+1. why generator expansion cannot own it yet
+2. why the remaining layer is composition-only
+3. how it will collapse later
+
+### 2) Export factories, not reusable inline objects
+
+Canonical shapes:
+
+- `queryOptions(...)` for standard queries
+- `mutationOptions(...)` for reusable mutations
+- `infiniteQueryOptions(...)` for paginated / load-more feeds
+
+Put the factory in a stable home such as `app/hooks/queries/<domain>.ts`, then
+consume it from hooks, route loaders, prefetch helpers, and tests.
+
+### 3) SDK-only GraphQL
+
+App code talks to GraphQL through a generated SDK (e.g., `~/generated/graphql/graphql-sdk`).
+If an operation is missing, add it to the codegen lane. Do not write inline
+GraphQL strings in app code or skill examples.
+
+### 4) Suspense-first route data
+
+Route-critical data flow:
+
+1. `queryClient.ensureQueryData(factory(...))` inside RR7 `clientLoader`
+2. `useSuspenseQuery(factory(...))` inside the route/domain component
+3. route-level `ErrorBoundary` export uses `RouteQueryErrorBoundary`
+
+Do not branch on `data === undefined` or `isPending` for data that is required
+before render.
+
+### 5) Errors are boundary-owned by default
+
+`createQueryClient()` should default to:
+
+- queries: `throwOnError: true`, `staleTime: 30_000`, `gcTime: 5 * 60_000`, `retry: 1`
+- mutations: `throwOnError: true`, `retry: 0`
+
+Use RR7-native route error boundaries plus `QueryErrorResetBoundary` to expose
+retry/reset UX.
+
+### 6) Pending work is observable through TanStack primitives
+
+For cross-component pending UI, prefer:
+
+- `useMutationState(...)`
+- `useIsMutating(...)`
+
+Key these off a stable `mutationKey` exported by the mutation-options factory or
+derived by the shared optimistic helper.
+
+### 7) Infinite-query primitives own pagination
+
+For load-more or cursor feeds, prefer:
+
+- `infiniteQueryOptions(...)`
+- `useSuspenseInfiniteQuery(...)`
+- `usePrefetchInfiniteQuery(...)` for secondary panes before a suspense boundary
+
+Do not hand-roll page accumulation when the TanStack primitive fits.
+
+## Standard workflow
+
+### Query workflow
+
+1. Decide whether generation should own the surface.
+2. Export a query-options factory backed by the generated SDK.
+3. Prefetch route-critical data with `queryClient.ensureQueryData(...)`.
+4. Render with `useSuspenseQuery(...)`.
+5. Use `usePrefetchQuery(...)` only for secondary boundaries that benefit from render-time warming.
+
+### Mutation workflow
+
+1. Export `mutationOptions(...)` with a stable `mutationKey`.
+2. Use `useMutation({ ...factory(), onSuccess, onSettled })` in the consuming component.
+3. Invalidate or update the affected query factories.
+4. Expose sibling pending state via `useMutationState(...)` / `useIsMutating(...)`.
+5. For optimistic flows, use `createOptimisticMutation(...)` instead of open-coded cache choreography.
+
+### Pagination workflow
+
+1. Export `infiniteQueryOptions(...)` with `initialPageParam` and `getNextPageParam`.
+2. Prefetch the first page in `clientLoader` when the feed is route-critical.
+3. Render with `useSuspenseInfiniteQuery(...)`.
+4. Warm secondary feeds with `usePrefetchInfiniteQuery(...)` when it shortens the waterfall.
+
+## Hard bans
+
+- No inline GraphQL strings in app code
+- No new reusable inline `useQuery({ queryKey, queryFn })` contracts
+- No `isLoading`-driven query examples in new code
+- No second provider abstraction when the existing root/preset can own the shared client
+- No bespoke mutation-loading stores when TanStack mutation-state hooks fit
+- No medium-sized custom hooks that re-own generated CRUD semantics
+
+## Escape hatches
+
+Allowed only when justified in code comments / implementation notes:
+
+- `useQuery(...)` instead of suspense for polling, optimistic local reconciliation, or truly optional background data
+- per-mutation `throwOnError: false` for intentional inline form validation UX (see opt-out policy below)
+- a hand-written query module over a YAML-backed surface only with a D23 exception note
+
+### `throwOnError: false` opt-out policy
+
+Opting out per-call is allowed only for **inline-error UX** — surfaces that render their own toast / inline message and must not bubble to the route boundary (e.g. action buttons, optimistic mutations, form validation).
+
+When opting out:
+
+- Add a one-line `// inline-error UX: ...` comment explaining the local error path (toast, inline banner, status field)
+- Provide a local `onError` handler — silent failure is never acceptable
+- For **queries** (vs mutations), prefer `meta: { skipGlobalError: true }` over `throwOnError: false` so the global `QueryCache.onError` can still log / report
+
+Bare `throwOnError: false` without the comment + local handler is a code-review red flag.
+
+## File guide
+
+- Start with `templates/query-client-config.ts`
+- Then use `templates/use-query-basic.tsx`, `templates/use-mutation-basic.tsx`, and `templates/use-infinite-query.tsx`
+- Use `templates/custom-hooks-pattern.tsx` only for thin composition
+- Use `templates/error-boundary.tsx` for the route fallback contract
+- Use the reference docs for testing, errors, and typing details