@heyai-rules/pilo-masterkit 2.1.0 → 3.1.0

package/.agent/rules/web/patterns.md

@@ -1,79 +1,79 @@
-> This file extends [common/patterns.md](../common/patterns.md) with web-specific patterns.
-
-# Web Patterns
-
-## Component Composition
-
-### Compound Components
-
-Use compound components when related UI shares state and interaction semantics:
-
-```tsx
-<Tabs defaultValue="overview">
-  <Tabs.List>
-    <Tabs.Trigger value="overview">Overview</Tabs.Trigger>
-    <Tabs.Trigger value="settings">Settings</Tabs.Trigger>
-  </Tabs.List>
-  <Tabs.Content value="overview">...</Tabs.Content>
-  <Tabs.Content value="settings">...</Tabs.Content>
-</Tabs>
-```
-
-- Parent owns state
-- Children consume via context
-- Prefer this over prop drilling for complex widgets
-
-### Render Props / Slots
-
-- Use render props or slot patterns when behavior is shared but markup must vary
-- Keep keyboard handling, ARIA, and focus logic in the headless layer
-
-### Container / Presentational Split
-
-- Container components own data loading and side effects
-- Presentational components receive props and render UI
-- Presentational components should stay pure
-
-## State Management
-
-Treat these separately:
-
-| Concern | Tooling |
-|---------|---------|
-| Server state | TanStack Query, SWR, tRPC |
-| Client state | Zustand, Jotai, signals |
-| URL state | search params, route segments |
-| Form state | React Hook Form or equivalent |
-
-- Do not duplicate server state into client stores
-- Derive values instead of storing redundant computed state
-
-## URL As State
-
-Persist shareable state in the URL:
-- filters
-- sort order
-- pagination
-- active tab
-- search query
-
-## Data Fetching
-
-### Stale-While-Revalidate
-
-- Return cached data immediately
-- Revalidate in the background
-- Prefer existing libraries instead of rolling this by hand
-
-### Optimistic Updates
-
-- Snapshot current state
-- Apply optimistic update
-- Roll back on failure
-- Emit visible error feedback when rolling back
-
-### Parallel Loading
-
-- Fetch independent data in parallel
-- Avoid parent-child request waterfalls
-- Prefetch likely next routes or states when justified
+> This file extends [common/patterns.md](../common/patterns.md) with web-specific patterns.
+
+# Web Patterns
+
+## Component Composition
+
+### Compound Components
+
+Use compound components when related UI shares state and interaction semantics:
+
+```tsx
+<Tabs defaultValue="overview">
+  <Tabs.List>
+    <Tabs.Trigger value="overview">Overview</Tabs.Trigger>
+    <Tabs.Trigger value="settings">Settings</Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="overview">...</Tabs.Content>
+  <Tabs.Content value="settings">...</Tabs.Content>
+</Tabs>
+```
+
+- Parent owns state
+- Children consume via context
+- Prefer this over prop drilling for complex widgets
+
+### Render Props / Slots
+
+- Use render props or slot patterns when behavior is shared but markup must vary
+- Keep keyboard handling, ARIA, and focus logic in the headless layer
+
+### Container / Presentational Split
+
+- Container components own data loading and side effects
+- Presentational components receive props and render UI
+- Presentational components should stay pure
+
+## State Management
+
+Treat these separately:
+
+| Concern | Tooling |
+|---------|---------|
+| Server state | TanStack Query, SWR, tRPC |
+| Client state | Zustand, Jotai, signals |
+| URL state | search params, route segments |
+| Form state | React Hook Form or equivalent |
+
+- Do not duplicate server state into client stores
+- Derive values instead of storing redundant computed state
+
+## URL As State
+
+Persist shareable state in the URL:
+- filters
+- sort order
+- pagination
+- active tab
+- search query
+
+## Data Fetching
+
+### Stale-While-Revalidate
+
+- Return cached data immediately
+- Revalidate in the background
+- Prefer existing libraries instead of rolling this by hand
+
+### Optimistic Updates
+
+- Snapshot current state
+- Apply optimistic update
+- Roll back on failure
+- Emit visible error feedback when rolling back
+
+### Parallel Loading
+
+- Fetch independent data in parallel
+- Avoid parent-child request waterfalls
+- Prefetch likely next routes or states when justified

package/.agent/rules/web/performance.md

@@ -1,64 +1,64 @@
-> This file extends [common/performance.md](../common/performance.md) with web-specific performance content.
-
-# Web Performance Rules
-
-## Core Web Vitals Targets
-
-| Metric | Target |
-|--------|--------|
-| LCP | < 2.5s |
-| INP | < 200ms |
-| CLS | < 0.1 |
-| FCP | < 1.5s |
-| TBT | < 200ms |
-
-## Bundle Budget
-
-| Page Type | JS Budget (gzipped) | CSS Budget |
-|-----------|---------------------|------------|
-| Landing page | < 150kb | < 30kb |
-| App page | < 300kb | < 50kb |
-| Microsite | < 80kb | < 15kb |
-
-## Loading Strategy
-
-1. Inline critical above-the-fold CSS where justified
-2. Preload the hero image and primary font only
-3. Defer non-critical CSS or JS
-4. Dynamically import heavy libraries
-
-```js
-const gsapModule = await import('gsap');
-const { ScrollTrigger } = await import('gsap/ScrollTrigger');
-```
-
-## Image Optimization
-
-- Explicit `width` and `height`
-- `loading="eager"` plus `fetchpriority="high"` for hero media only
-- `loading="lazy"` for below-the-fold assets
-- Prefer AVIF or WebP with fallbacks
-- Never ship source images far beyond rendered size
-
-## Font Loading
-
-- Max two font families unless there is a clear exception
-- `font-display: swap`
-- Subset where possible
-- Preload only the truly critical weight/style
-
-## Animation Performance
-
-- Animate compositor-friendly properties only
-- Use `will-change` narrowly and remove it when done
-- Prefer CSS for simple transitions
-- Use `requestAnimationFrame` or established animation libraries for JS motion
-- Avoid scroll handler churn; use IntersectionObserver or well-behaved libraries
-
-## Performance Checklist
-
-- [ ] All images have explicit dimensions
-- [ ] No accidental render-blocking resources
-- [ ] No layout shifts from dynamic content
-- [ ] Motion stays on compositor-friendly properties
-- [ ] Third-party scripts load async/defer and only when needed
+> This file extends [common/performance.md](../common/performance.md) with web-specific performance content.
+
+# Web Performance Rules
+
+## Core Web Vitals Targets
+
+| Metric | Target |
+|--------|--------|
+| LCP | < 2.5s |
+| INP | < 200ms |
+| CLS | < 0.1 |
+| FCP | < 1.5s |
+| TBT | < 200ms |
+
+## Bundle Budget
+
+| Page Type | JS Budget (gzipped) | CSS Budget |
+|-----------|---------------------|------------|
+| Landing page | < 150kb | < 30kb |
+| App page | < 300kb | < 50kb |
+| Microsite | < 80kb | < 15kb |
+
+## Loading Strategy
+
+1. Inline critical above-the-fold CSS where justified
+2. Preload the hero image and primary font only
+3. Defer non-critical CSS or JS
+4. Dynamically import heavy libraries
+
+```js
+const gsapModule = await import('gsap');
+const { ScrollTrigger } = await import('gsap/ScrollTrigger');
+```
+
+## Image Optimization
+
+- Explicit `width` and `height`
+- `loading="eager"` plus `fetchpriority="high"` for hero media only
+- `loading="lazy"` for below-the-fold assets
+- Prefer AVIF or WebP with fallbacks
+- Never ship source images far beyond rendered size
+
+## Font Loading
+
+- Max two font families unless there is a clear exception
+- `font-display: swap`
+- Subset where possible
+- Preload only the truly critical weight/style
+
+## Animation Performance
+
+- Animate compositor-friendly properties only
+- Use `will-change` narrowly and remove it when done
+- Prefer CSS for simple transitions
+- Use `requestAnimationFrame` or established animation libraries for JS motion
+- Avoid scroll handler churn; use IntersectionObserver or well-behaved libraries
+
+## Performance Checklist
+
+- [ ] All images have explicit dimensions
+- [ ] No accidental render-blocking resources
+- [ ] No layout shifts from dynamic content
+- [ ] Motion stays on compositor-friendly properties
+- [ ] Third-party scripts load async/defer and only when needed

package/.agent/rules/web/security.md

@@ -1,57 +1,57 @@
-> This file extends [common/security.md](../common/security.md) with web-specific security content.
-
-# Web Security Rules
-
-## Content Security Policy
-
-Always configure a production CSP.
-
-### Nonce-Based CSP
-
-Use a per-request nonce for scripts instead of `'unsafe-inline'`.
-
-```text
-Content-Security-Policy:
-  default-src 'self';
-  script-src 'self' 'nonce-{RANDOM}' https://cdn.jsdelivr.net;
-  style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;
-  img-src 'self' data: https:;
-  font-src 'self' https://fonts.gstatic.com;
-  connect-src 'self' https://*.example.com;
-  frame-src 'none';
-  object-src 'none';
-  base-uri 'self';
-```
-
-Adjust origins to the project. Do not cargo-cult this block unchanged.
-
-## XSS Prevention
-
-- Never inject unsanitized HTML
-- Avoid `innerHTML` / `dangerouslySetInnerHTML` unless sanitized first
-- Escape dynamic template values
-- Sanitize user HTML with a vetted local sanitizer when absolutely necessary
-
-## Third-Party Scripts
-
-- Load asynchronously
-- Use SRI when serving from a CDN
-- Audit quarterly
-- Prefer self-hosting for critical dependencies when practical
-
-## HTTPS and Headers
-
-```text
-Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
-X-Content-Type-Options: nosniff
-X-Frame-Options: DENY
-Referrer-Policy: strict-origin-when-cross-origin
-Permissions-Policy: camera=(), microphone=(), geolocation=()
-```
-
-## Forms
-
-- CSRF protection on state-changing forms
-- Rate limiting on submission endpoints
-- Validate client and server side
-- Prefer honeypots or light anti-abuse controls over heavy-handed CAPTCHA defaults
+> This file extends [common/security.md](../common/security.md) with web-specific security content.
+
+# Web Security Rules
+
+## Content Security Policy
+
+Always configure a production CSP.
+
+### Nonce-Based CSP
+
+Use a per-request nonce for scripts instead of `'unsafe-inline'`.
+
+```text
+Content-Security-Policy:
+  default-src 'self';
+  script-src 'self' 'nonce-{RANDOM}' https://cdn.jsdelivr.net;
+  style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;
+  img-src 'self' data: https:;
+  font-src 'self' https://fonts.gstatic.com;
+  connect-src 'self' https://*.example.com;
+  frame-src 'none';
+  object-src 'none';
+  base-uri 'self';
+```
+
+Adjust origins to the project. Do not cargo-cult this block unchanged.
+
+## XSS Prevention
+
+- Never inject unsanitized HTML
+- Avoid `innerHTML` / `dangerouslySetInnerHTML` unless sanitized first
+- Escape dynamic template values
+- Sanitize user HTML with a vetted local sanitizer when absolutely necessary
+
+## Third-Party Scripts
+
+- Load asynchronously
+- Use SRI when serving from a CDN
+- Audit quarterly
+- Prefer self-hosting for critical dependencies when practical
+
+## HTTPS and Headers
+
+```text
+Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+Referrer-Policy: strict-origin-when-cross-origin
+Permissions-Policy: camera=(), microphone=(), geolocation=()
+```
+
+## Forms
+
+- CSRF protection on state-changing forms
+- Rate limiting on submission endpoints
+- Validate client and server side
+- Prefer honeypots or light anti-abuse controls over heavy-handed CAPTCHA defaults

package/.agent/rules/web/testing.md

@@ -1,55 +1,55 @@
-> This file extends [common/testing.md](../common/testing.md) with web-specific testing content.
-
-# Web Testing Rules
-
-## Priority Order
-
-### 1. Visual Regression
-
-- Screenshot key breakpoints: 320, 768, 1024, 1440
-- Test hero sections, scrollytelling sections, and meaningful states
-- Use Playwright screenshots for visual-heavy work
-- If both themes exist, test both
-
-### 2. Accessibility
-
-- Run automated accessibility checks
-- Test keyboard navigation
-- Verify reduced-motion behavior
-- Verify color contrast
-
-### 3. Performance
-
-- Run Lighthouse or equivalent against meaningful pages
-- Keep CWV targets from [performance.md](performance.md)
-
-### 4. Cross-Browser
-
-- Minimum: Chrome, Firefox, Safari
-- Test scrolling, motion, and fallback behavior
-
-### 5. Responsive
-
-- Test 320, 375, 768, 1024, 1440, 1920
-- Verify no overflow
-- Verify touch interactions
-
-## E2E Shape
-
-```ts
-import { test, expect } from '@playwright/test';
-
-test('landing hero loads', async ({ page }) => {
-  await page.goto('/');
-  await expect(page.locator('h1')).toBeVisible();
-});
-```
-
-- Avoid flaky timeout-based assertions
-- Prefer deterministic waits
-
-## Unit Tests
-
-- Test utilities, data transforms, and custom hooks
-- For highly visual components, visual regression often carries more signal than brittle markup assertions
-- Visual regression supplements coverage targets; it does not replace them
+> This file extends [common/testing.md](../common/testing.md) with web-specific testing content.
+
+# Web Testing Rules
+
+## Priority Order
+
+### 1. Visual Regression
+
+- Screenshot key breakpoints: 320, 768, 1024, 1440
+- Test hero sections, scrollytelling sections, and meaningful states
+- Use Playwright screenshots for visual-heavy work
+- If both themes exist, test both
+
+### 2. Accessibility
+
+- Run automated accessibility checks
+- Test keyboard navigation
+- Verify reduced-motion behavior
+- Verify color contrast
+
+### 3. Performance
+
+- Run Lighthouse or equivalent against meaningful pages
+- Keep CWV targets from [performance.md](performance.md)
+
+### 4. Cross-Browser
+
+- Minimum: Chrome, Firefox, Safari
+- Test scrolling, motion, and fallback behavior
+
+### 5. Responsive
+
+- Test 320, 375, 768, 1024, 1440, 1920
+- Verify no overflow
+- Verify touch interactions
+
+## E2E Shape
+
+```ts
+import { test, expect } from '@playwright/test';
+
+test('landing hero loads', async ({ page }) => {
+  await page.goto('/');
+  await expect(page.locator('h1')).toBeVisible();
+});
+```
+
+- Avoid flaky timeout-based assertions
+- Prefer deterministic waits
+
+## Unit Tests
+
+- Test utilities, data transforms, and custom hooks
+- For highly visual components, visual regression often carries more signal than brittle markup assertions
+- Visual regression supplements coverage targets; it does not replace them

package/.agent/rules/zh/agents.md

@@ -1,50 +1,50 @@
-# 代理编排
-
-## 可用代理
-
-位于 `~/.claude/agents/`：
-
-| 代理 | 用途 | 何时使用 |
-|-------|---------|------------|
-| planner | 实现规划 | 复杂功能、重构 |
-| architect | 系统设计 | 架构决策 |
-| tdd-guide | 测试驱动开发 | 新功能、bug 修复 |
-| code-reviewer | 代码审查 | 编写代码后 |
-| security-reviewer | 安全分析 | 提交前 |
-| build-error-resolver | 修复构建错误 | 构建失败时 |
-| e2e-runner | E2E 测试 | 关键用户流程 |
-| refactor-cleaner | 死代码清理 | 代码维护 |
-| doc-updater | 文档 | 更新文档 |
-| rust-reviewer | Rust 代码审查 | Rust 项目 |
-
-## 立即使用代理
-
-无需用户提示：
-1. 复杂功能请求 - 使用 **planner** 代理
-2. 刚编写/修改的代码 - 使用 **code-reviewer** 代理
-3. Bug 修复或新功能 - 使用 **tdd-guide** 代理
-4. 架构决策 - 使用 **architect** 代理
-
-## 并行任务执行
-
-对独立操作始终使用并行 Task 执行：
-
-```markdown
-# 好：并行执行
-同时启动 3 个代理：
-1. 代理 1：认证模块安全分析
-2. 代理 2：缓存系统性能审查
-3. 代理 3：工具类型检查
-
-# 坏：不必要的顺序
-先代理 1，然后代理 2，然后代理 3
-```
-
-## 多视角分析
-
-对于复杂问题，使用分角色子代理：
-- 事实审查者
-- 高级工程师
-- 安全专家
-- 一致性审查者
-- 冗余检查者
+# 代理编排
+
+## 可用代理
+
+位于 `~/.claude/agents/`：
+
+| 代理 | 用途 | 何时使用 |
+|-------|---------|------------|
+| planner | 实现规划 | 复杂功能、重构 |
+| architect | 系统设计 | 架构决策 |
+| tdd-guide | 测试驱动开发 | 新功能、bug 修复 |
+| code-reviewer | 代码审查 | 编写代码后 |
+| security-reviewer | 安全分析 | 提交前 |
+| build-error-resolver | 修复构建错误 | 构建失败时 |
+| e2e-runner | E2E 测试 | 关键用户流程 |
+| refactor-cleaner | 死代码清理 | 代码维护 |
+| doc-updater | 文档 | 更新文档 |
+| rust-reviewer | Rust 代码审查 | Rust 项目 |
+
+## 立即使用代理
+
+无需用户提示：
+1. 复杂功能请求 - 使用 **planner** 代理
+2. 刚编写/修改的代码 - 使用 **code-reviewer** 代理
+3. Bug 修复或新功能 - 使用 **tdd-guide** 代理
+4. 架构决策 - 使用 **architect** 代理
+
+## 并行任务执行
+
+对独立操作始终使用并行 Task 执行：
+
+```markdown
+# 好：并行执行
+同时启动 3 个代理：
+1. 代理 1：认证模块安全分析
+2. 代理 2：缓存系统性能审查
+3. 代理 3：工具类型检查
+
+# 坏：不必要的顺序
+先代理 1，然后代理 2，然后代理 3
+```
+
+## 多视角分析
+
+对于复杂问题，使用分角色子代理：
+- 事实审查者
+- 高级工程师
+- 安全专家
+- 一致性审查者
+- 冗余检查者