kodelyth-ecc 1.2.0

package/rules/web/hooks.md

@@ -0,0 +1,120 @@
+> This file extends [common/hooks.md](../common/hooks.md) with web-specific hook recommendations.
+
+# Web Hooks
+
+## Recommended PostToolUse Hooks
+
+Prefer project-local tooling. Do not wire hooks to remote one-off package execution.
+
+### Format on Save
+
+Use the project's existing formatter entrypoint after edits:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "command": "pnpm prettier --write \"$FILE_PATH\"",
+        "description": "Format edited frontend files"
+      }
+    ]
+  }
+}
+```
+
+Equivalent local commands via `yarn prettier` or `npm exec prettier --` are fine when they use repo-owned dependencies.
+
+### Lint Check
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "command": "pnpm eslint --fix \"$FILE_PATH\"",
+        "description": "Run ESLint on edited frontend files"
+      }
+    ]
+  }
+}
+```
+
+### Type Check
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "command": "pnpm tsc --noEmit --pretty false",
+        "description": "Type-check after frontend edits"
+      }
+    ]
+  }
+}
+```
+
+### CSS Lint
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "command": "pnpm stylelint --fix \"$FILE_PATH\"",
+        "description": "Lint edited stylesheets"
+      }
+    ]
+  }
+}
+```
+
+## PreToolUse Hooks
+
+### Guard File Size
+
+Block oversized writes from tool input content, not from a file that may not exist yet:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write",
+        "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const c=i.tool_input?.content||'';const lines=c.split('\\n').length;if(lines>800){console.error('[Hook] BLOCKED: File exceeds 800 lines ('+lines+' lines)');console.error('[Hook] Split into smaller modules');process.exit(2)}console.log(d)})\"",
+        "description": "Block writes that exceed 800 lines"
+      }
+    ]
+  }
+}
+```
+
+## Stop Hooks
+
+### Final Build Verification
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "command": "pnpm build",
+        "description": "Verify the production build at session end"
+      }
+    ]
+  }
+}
+```
+
+## Ordering
+
+Recommended order:
+1. format
+2. lint
+3. type check
+4. build verification

package/rules/web/patterns.md

@@ -0,0 +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

package/rules/web/performance.md

@@ -0,0 +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

package/rules/web/security.md

@@ -0,0 +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

package/rules/web/testing.md

@@ -0,0 +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

package/rules/zh/README.md

@@ -0,0 +1,108 @@
+# 规则
+
+## 结构
+
+规则按**通用**层和**语言特定**目录组织：
+
+```
+rules/
+├── common/          # 语言无关的原则（始终安装）
+│   ├── coding-style.md
+│   ├── git-workflow.md
+│   ├── testing.md
+│   ├── performance.md
+│   ├── patterns.md
+│   ├── hooks.md
+│   ├── agents.md
+│   ├── security.md
+│   ├── code-review.md
+│   └── development-workflow.md
+├── zh/              # 中文翻译版本
+│   ├── coding-style.md
+│   ├── git-workflow.md
+│   ├── testing.md
+│   ├── performance.md
+│   ├── patterns.md
+│   ├── hooks.md
+│   ├── agents.md
+│   ├── security.md
+│   ├── code-review.md
+│   └── development-workflow.md
+├── typescript/      # TypeScript/JavaScript 特定
+├── python/          # Python 特定
+├── golang/          # Go 特定
+├── swift/           # Swift 特定
+└── php/             # PHP 特定
+```
+
+- **common/** 包含通用原则 — 无语言特定的代码示例。
+- **zh/** 包含 common 目录的中文翻译版本。
+- **语言目录** 扩展通用规则，包含框架特定的模式、工具和代码示例。每个文件引用其对应的通用版本。
+
+## 安装
+
+### 选项 1：安装脚本（推荐）
+
+```bash
+# 安装通用 + 一个或多个语言特定的规则集
+./install.sh typescript
+./install.sh python
+./install.sh golang
+./install.sh swift
+./install.sh php
+
+# 同时安装多种语言
+./install.sh typescript python
+```
+
+### 选项 2：手动安装
+
+> **重要提示：** 复制整个目录 — 不要使用 `/*` 展开。
+> 通用和语言特定目录包含同名文件。
+> 将它们展开到一个目录会导致语言特定文件覆盖通用规则，
+> 并破坏语言特定文件使用的 `../common/` 相对引用。
+
+```bash
+# 创建目标目录
+mkdir -p ~/.claude/rules
+
+# 安装通用规则（所有项目必需）
+cp -r rules/common ~/.claude/rules/common
+
+# 安装中文翻译版本（可选）
+cp -r rules/zh ~/.claude/rules/zh
+
+# 根据项目技术栈安装语言特定规则
+cp -r rules/typescript ~/.claude/rules/typescript
+cp -r rules/python ~/.claude/rules/python
+cp -r rules/golang ~/.claude/rules/golang
+cp -r rules/swift ~/.claude/rules/swift
+cp -r rules/php ~/.claude/rules/php
+```
+
+## 规则 vs 技能
+
+- **规则** 定义广泛适用的标准、约定和检查清单（如"80% 测试覆盖率"、"禁止硬编码密钥"）。
+- **技能**（`skills/` 目录）为特定任务提供深入、可操作的参考材料（如 `python-patterns`、`golang-testing`）。
+
+语言特定的规则文件在适当的地方引用相关技能。规则告诉你*做什么*；技能告诉你*怎么做*。
+
+## 规则优先级
+
+当语言特定规则与通用规则冲突时，**语言特定规则优先**（特定覆盖通用）。这遵循标准的分层配置模式（类似于 CSS 特异性或 `.gitignore` 优先级）。
+
+- `rules/common/` 定义适用于所有项目的通用默认值。
+- `rules/golang/`、`rules/python/`、`rules/swift/`、`rules/php/`、`rules/typescript/` 等在语言习惯不同时覆盖这些默认值。
+- `rules/zh/` 是通用规则的中文翻译，与英文版本内容一致。
+
+### 示例
+
+`common/coding-style.md` 推荐不可变性作为默认原则。语言特定的 `golang/coding-style.md` 可以覆盖这一点：
+
+> 惯用的 Go 使用指针接收器进行结构体变更 — 参见 [common/coding-style.md](../common/coding-style.md) 了解通用原则，但这里首选符合 Go 习惯的变更方式。
+
+### 带覆盖说明的通用规则
+
+`rules/common/` 中可能被语言特定文件覆盖的规则会被标记：
+
+> **语言说明**：此规则可能会被语言特定规则覆盖；对于某些语言，该模式可能并不符合惯用写法。

package/rules/zh/agents.md

@@ -0,0 +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
+```
+
+## 多视角分析
+
+对于复杂问题，使用分角色子代理：
+- 事实审查者
+- 高级工程师
+- 安全专家
+- 一致性审查者
+- 冗余检查者

package/rules/zh/code-review.md

@@ -0,0 +1,124 @@
+# 代码审查标准
+
+## 目的
+
+代码审查确保代码合并前的质量、安全性和可维护性。此规则定义何时以及如何进行代码审查。
+
+## 何时审查
+
+**强制审查触发条件：**
+
+- 编写或修改代码后
+- 提交到共享分支之前
+- 更改安全敏感代码时（认证、支付、用户数据）
+- 进行架构更改时
+- 合并 pull request 之前
+
+**审查前要求：**
+
+在请求审查之前，确保：
+
+- 所有自动化检查（CI/CD）已通过
+- 合并冲突已解决
+- 分支已与目标分支同步
+
+## 审查检查清单
+
+在标记代码完成之前：
+
+- [ ] 代码可读且命名良好
+- [ ] 函数聚焦（<50 行）
+- [ ] 文件内聚（<800 行）
+- [ ] 无深层嵌套（>4 层）
+- [ ] 错误显式处理
+- [ ] 无硬编码密钥或凭据
+- [ ] 无 console.log 或调试语句
+- [ ] 新功能有测试
+- [ ] 测试覆盖率满足 80% 最低要求
+
+## 安全审查触发条件
+
+**停止并使用 security-reviewer 代理当：**
+
+- 认证或授权代码
+- 用户输入处理
+- 数据库查询
+- 文件系统操作
+- 外部 API 调用
+- 加密操作
+- 支付或金融代码
+
+## 审查严重级别
+
+| 级别 | 含义 | 行动 |
+|-------|---------|--------|
+| CRITICAL（关键） | 安全漏洞或数据丢失风险 | **阻止** - 合并前必须修复 |
+| HIGH（高） | Bug 或重大质量问题 | **警告** - 合并前应修复 |
+| MEDIUM（中） | 可维护性问题 | **信息** - 考虑修复 |
+| LOW（低） | 风格或次要建议 | **注意** - 可选 |
+
+## 代理使用
+
+使用这些代理进行代码审查：
+
+| 代理 | 用途 |
+|-------|--------|
+| **code-reviewer** | 通用代码质量、模式、最佳实践 |
+| **security-reviewer** | 安全漏洞、OWASP Top 10 |
+| **typescript-reviewer** | TypeScript/JavaScript 特定问题 |
+| **python-reviewer** | Python 特定问题 |
+| **go-reviewer** | Go 特定问题 |
+| **rust-reviewer** | Rust 特定问题 |
+
+## 审查工作流
+
+```
+1. 运行 git diff 了解更改
+2. 先检查安全检查清单
+3. 审查代码质量检查清单
+4. 运行相关测试
+5. 验证覆盖率 >= 80%
+6. 使用适当的代理进行详细审查
+```
+
+## 常见问题捕获
+
+### 安全
+
+- 硬编码凭据（API 密钥、密码、令牌）
+- SQL 注入（查询中的字符串拼接）
+- XSS 漏洞（未转义的用户输入）
+- 路径遍历（未净化的文件路径）
+- CSRF 保护缺失
+- 认证绕过
+
+### 代码质量
+
+- 大函数（>50 行）- 拆分为更小的
+- 大文件（>800 行）- 提取模块
+- 深层嵌套（>4 层）- 使用提前返回
+- 缺少错误处理 - 显式处理
+- 变更模式 - 优先使用不可变操作
+- 缺少测试 - 添加测试覆盖
+
+### 性能
+
+- N+1 查询 - 使用 JOIN 或批处理
+- 缺少分页 - 给查询添加 LIMIT
+- 无界查询 - 添加约束
+- 缺少缓存 - 缓存昂贵操作
+
+## 批准标准
+
+- **批准**：无关键或高优先级问题
+- **警告**：仅有高优先级问题（谨慎合并）
+- **阻止**：发现关键问题
+
+## 与其他规则的集成
+
+此规则与以下规则配合：
+
+- [testing.md](testing.md) - 测试覆盖率要求
+- [security.md](security.md) - 安全检查清单
+- [git-workflow.md](git-workflow.md) - 提交标准
+- [agents.md](agents.md) - 代理委托

package/rules/zh/coding-style.md

@@ -0,0 +1,48 @@
+# 编码风格
+
+## 不可变性（关键）
+
+始终创建新对象，永远不要修改现有对象：
+
+```
+// 伪代码
+错误:  modify(original, field, value) → 就地修改 original
+正确: update(original, field, value) → 返回带有更改的新副本
+```
+
+原理：不可变数据防止隐藏的副作用，使调试更容易，并启用安全的并发。
+
+## 文件组织
+
+多个小文件 > 少量大文件：
+- 高内聚，低耦合
+- 典型 200-400 行，最多 800 行
+- 从大模块中提取工具函数
+- 按功能/领域组织，而非按类型
+
+## 错误处理
+
+始终全面处理错误：
+- 在每一层显式处理错误
+- 在面向 UI 的代码中提供用户友好的错误消息
+- 在服务器端记录详细的错误上下文
+- 永远不要静默吞掉错误
+
+## 输入验证
+
+始终在系统边界验证：
+- 处理前验证所有用户输入
+- 在可用的情况下使用基于模式的验证
+- 快速失败并给出清晰的错误消息
+- 永远不要信任外部数据（API 响应、用户输入、文件内容）
+
+## 代码质量检查清单
+
+在标记工作完成前：
+- [ ] 代码可读且命名良好
+- [ ] 函数很小（<50 行）
+- [ ] 文件聚焦（<800 行）
+- [ ] 没有深层嵌套（>4 层）
+- [ ] 正确的错误处理
+- [ ] 没有硬编码值（使用常量或配置）
+- [ ] 没有变更（使用不可变模式）