kodelyth-ecc 1.2.0

package/.agent/rules/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/.agent/rules/agents.md

@@ -0,0 +1,94 @@
+# Kodelyth ECC — Agent Roster
+
+This project has 53 specialist agents installed in `.agent/skills/`.
+Invoke them proactively — do not wait to be asked.
+
+## When to Invoke Without Being Asked
+
+| Situation | Agent to invoke |
+|---|---|
+| User asks for a new feature | `planner` |
+| User is unsure what to do | `kodelyth-advisor` |
+| Code was just written or modified | `code-reviewer` |
+| A bug is reported | `debug-detective` |
+| Frontend or UI work was done | `ux-reviewer` |
+| An API route was changed | `api-guardian` |
+| Security-sensitive code touched | `security-reviewer` |
+| Build is failing | `build-error-resolver` |
+| User is about to start coding | `pair-programmer` |
+| Framework or dependency upgrade | `migration-guide` |
+| Something is slow | `performance-optimizer` |
+
+## Full Agent Roster
+
+### Guidance
+- `kodelyth-advisor` — reads situation, recommends exact tool — start here when unsure
+- `pair-programmer` — thinking partner before coding; catches wrong approach early
+- `planner` — implementation planning for complex features
+- `architect` — system design and scalability decisions
+- `code-architect` — feature architecture blueprints with concrete files and interfaces
+
+### Code Review
+- `code-reviewer` — general quality, patterns, best practices
+- `typescript-reviewer` — TypeScript and JavaScript specific
+- `python-reviewer` — Python specific
+- `go-reviewer` — Go specific
+- `rust-reviewer` — Rust specific
+- `java-reviewer` — Java and Spring Boot specific
+- `kotlin-reviewer` — Kotlin, Android, KMP specific
+- `cpp-reviewer` — C++ specific
+- `csharp-reviewer` — C# and .NET specific
+- `flutter-reviewer` — Flutter and Dart specific
+- `database-reviewer` — PostgreSQL, schema design, query optimization
+- `healthcare-reviewer` — clinical safety, PHI compliance
+
+### Build Error Resolution
+- `build-error-resolver` — general build errors
+- `go-build-resolver` — Go specific
+- `rust-build-resolver` — Rust and Cargo specific
+- `java-build-resolver` — Java, Maven, Gradle specific
+- `kotlin-build-resolver` — Kotlin and Gradle specific
+- `cpp-build-resolver` — C++ and CMake specific
+- `dart-build-resolver` — Dart and Flutter specific
+- `pytorch-build-resolver` — PyTorch, CUDA, training errors
+
+### Debugging
+- `debug-detective` — traces every bug to root cause; never guesses
+- `silent-failure-hunter` — finds swallowed errors and bad fallbacks
+
+### Security
+- `security-reviewer` — OWASP Top 10, injection, auth, secrets, SSRF
+
+### UX and Accessibility
+- `ux-reviewer` — usability, interaction logic, WCAG 2.1 AA; never touches visual design
+
+### Kodelyth Exclusive
+- `api-guardian` — detects breaking API changes before they ship
+- `migration-guide` — framework and language migration playbooks
+
+### Code Quality
+- `refactor-cleaner` — dead code removal, consolidation
+- `code-simplifier` — simplify for clarity after complex changes
+- `performance-optimizer` — bottleneck analysis and optimization
+- `type-design-analyzer` — type safety improvements
+- `comment-analyzer` — documentation hygiene
+- `code-explorer` — understanding unfamiliar codebases
+
+### Testing
+- `tdd-guide` — write tests first, enforces red-green-refactor
+- `e2e-runner` — end-to-end Playwright tests for critical user flows
+- `pr-test-analyzer` — PR test coverage review
+
+### Documentation
+- `doc-updater` — READMEs, codemaps, documentation updates
+- `docs-lookup` — library and API documentation
+- `seo-specialist` — technical SEO, structured data, Core Web Vitals
+
+### Open Source
+- `opensource-forker` — strip secrets, clean history
+- `opensource-packager` — README, setup, license for public release
+- `opensource-sanitizer` — verify sanitization before public release
+
+## Parallel Execution Rule
+
+For independent tasks, always run agents in parallel — never sequentially when tasks do not depend on each other.

package/.agent/rules/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/.agent/rules/coding-style.md

@@ -0,0 +1,122 @@
+# Coding Style
+
+## Immutability (CRITICAL)
+
+ALWAYS create new objects, NEVER mutate existing ones:
+
+```
+// Pseudocode
+WRONG:  modify(original, field, value) → changes original in-place
+CORRECT: update(original, field, value) → returns new copy with change
+```
+
+Rationale: Immutable data prevents hidden side effects, makes debugging easier, and enables safe concurrency.
+
+## Core Principles
+
+### KISS (Keep It Simple)
+
+- Prefer the simplest solution that actually works
+- Avoid premature optimization
+- Optimize for clarity over cleverness
+
+### DRY (Don't Repeat Yourself)
+
+- Extract repeated logic into shared functions or utilities
+- Avoid copy-paste implementation drift
+- Introduce abstractions when repetition is real, not speculative
+
+### YAGNI (You Aren't Gonna Need It)
+
+- Do not build features or abstractions before they are needed
+- Avoid speculative generality
+- Start simple, then refactor when the pressure is real
+
+## File Organization
+
+MANY SMALL FILES > FEW LARGE FILES:
+- High cohesion, low coupling
+- 200-400 lines typical, 800 max
+- Extract utilities from large modules
+- Organize by feature/domain, not by type
+
+## Error Handling
+
+ALWAYS handle errors comprehensively:
+- Handle errors explicitly at every level
+- Provide user-friendly error messages in UI-facing code
+- Log detailed error context on the server side
+- Never silently swallow errors
+
+## Input Validation
+
+ALWAYS validate at system boundaries:
+- Validate all user input before processing
+- Use schema-based validation where available
+- Fail fast with clear error messages
+- Never trust external data (API responses, user input, file content)
+
+## Naming Conventions
+
+- Variables and functions: `camelCase` with descriptive names
+- Booleans: prefer `is`, `has`, `should`, or `can` prefixes
+- Interfaces, types, and components: `PascalCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Custom hooks: `camelCase` with a `use` prefix
+
+## Code Smells to Avoid
+
+### Deep Nesting
+
+Prefer early returns over nested conditionals once the logic starts stacking.
+
+### Magic Numbers
+
+Use named constants for meaningful thresholds, delays, and limits.
+
+### Long Functions
+
+Split large functions into focused pieces with clear responsibilities.
+
+## Visual Output & Documentation Style
+
+### No Emoji (STRICT)
+
+**Never** use decorative emoji in documentation, agent responses, README files, skill files, or UI output.
+
+Emoji signals low craft. Use professional alternatives instead:
+
+| Context | Wrong | Right |
+|---|---|---|
+| GitHub Markdown badges | ✅ Feature complete | `![Status](https://img.shields.io/badge/status-complete-brightgreen.svg)` |
+| Inline doc icons | 🔍 Search | `<img src="icons/search.svg" width="16" alt="Search">` |
+| Status indicators | ✅ Passing / ❌ Failing | `PASS` / `FAIL` or ✓ / ✗ (Unicode, not emoji) |
+| Section headers | 🎯 Goals | `## Goals` — plain heading, no decoration |
+| Terminal output | 🚀 Installing... | `Installing...` or `[INFO] Installing...` |
+| Checklists | ✅ Done | `- [x] Done` (Markdown checkbox) |
+
+**Allowed in terminal scripts only:** Unicode symbols `✓` (U+2713), `✗` (U+2717), `→` (U+2192) — these are text characters, not emoji, and render cleanly in all terminals.
+
+**In rendered Markdown (README, docs, skills):**
+```html
+<!-- Use shields.io SVG badges for status -->
+![Build](https://img.shields.io/badge/build-passing-brightgreen.svg)
+![Coverage](https://img.shields.io/badge/coverage-94%25-brightgreen.svg)
+
+<!-- Use <img> for inline icons -->
+<img src="https://cdn.simpleicons.org/typescript" width="16" height="16" alt="TypeScript">
+```
+
+**In agent responses:** no decoration whatsoever — structured prose, code blocks, and tables only.
+
+## Code Quality Checklist
+
+Before marking work complete:
+- [ ] Code is readable and well-named
+- [ ] Functions are small (<50 lines)
+- [ ] Files are focused (<800 lines)
+- [ ] No deep nesting (>4 levels)
+- [ ] Proper error handling
+- [ ] No hardcoded values (use constants or config)
+- [ ] No mutation (immutable patterns used)
+- [ ] No emoji — SVG badges or plain text only

package/.agent/rules/design-quality.md

@@ -0,0 +1,63 @@
+> This file extends [common/patterns.md](../common/patterns.md) with web-specific design-quality guidance.
+
+# Web Design Quality Standards
+
+## Anti-Template Policy
+
+Do not ship generic template-looking UI. Frontend output should look intentional, opinionated, and specific to the product.
+
+### Banned Patterns
+
+- Default card grids with uniform spacing and no hierarchy
+- Stock hero section with centered headline, gradient blob, and generic CTA
+- Unmodified library defaults passed off as finished design
+- Flat layouts with no layering, depth, or motion
+- Uniform radius, spacing, and shadows across every component
+- Safe gray-on-white styling with one decorative accent color
+- Dashboard-by-numbers layouts with sidebar + cards + charts and no point of view
+- Default font stacks used without a deliberate reason
+
+### Required Qualities
+
+Every meaningful frontend surface should demonstrate at least four of these:
+
+1. Clear hierarchy through scale contrast
+2. Intentional rhythm in spacing, not uniform padding everywhere
+3. Depth or layering through overlap, shadows, surfaces, or motion
+4. Typography with character and a real pairing strategy
+5. Color used semantically, not just decoratively
+6. Hover, focus, and active states that feel designed
+7. Grid-breaking editorial or bento composition where appropriate
+8. Texture, grain, or atmosphere when it fits the visual direction
+9. Motion that clarifies flow instead of distracting from it
+10. Data visualization treated as part of the design system, not an afterthought
+
+## Before Writing Frontend Code
+
+1. Pick a specific style direction. Avoid vague defaults like "clean minimal".
+2. Define a palette intentionally.
+3. Choose typography deliberately.
+4. Gather at least a small set of real references.
+5. Use ECC design/frontend skills where relevant.
+
+## Worthwhile Style Directions
+
+- Editorial / magazine
+- Neo-brutalism
+- Glassmorphism with real depth
+- Dark luxury or light luxury with disciplined contrast
+- Bento layouts
+- Scrollytelling
+- 3D integration
+- Swiss / International
+- Retro-futurism
+
+Do not default to dark mode automatically. Choose the visual direction the product actually wants.
+
+## Component Checklist
+
+- [ ] Does it avoid looking like a default Tailwind or shadcn template?
+- [ ] Does it have intentional hover/focus/active states?
+- [ ] Does it use hierarchy rather than uniform emphasis?
+- [ ] Would this look believable in a real product screenshot?
+- [ ] If it supports both themes, do both light and dark feel intentional?

package/.agent/rules/development-workflow.md

@@ -0,0 +1,44 @@
+# 开发工作流
+
+> 此文件扩展 [common/git-workflow.md](./git-workflow.md)，包含 git 操作之前的完整功能开发流程。
+
+功能实现工作流描述了开发管道：研究、规划、TDD、代码审查，然后提交到 git。
+
+## 功能实现工作流
+
+0. **研究与重用** _(任何新实现前必需)_
+   - **GitHub 代码搜索优先：** 在编写任何新代码之前，运行 `gh search repos` 和 `gh search code` 查找现有实现、模板和模式。
+   - **库文档其次：** 使用 Context7 或主要供应商文档确认 API 行为、包使用和版本特定细节。
+   - **仅当前两者不足时使用 Exa：** 在 GitHub 搜索和主要文档之后，使用 Exa 进行更广泛的网络研究或发现。
+   - **检查包注册表：** 在编写工具代码之前搜索 npm、PyPI、crates.io 和其他注册表。首选久经考验的库而非手工编写的解决方案。
+   - **搜索可适配的实现：** 寻找解决问题 80%+ 且可以分支、移植或包装的开源项目。
+   - 当满足需求时，优先采用或移植经验证的方法而非从头编写新代码。
+
+1. **先规划**
+   - 使用 **planner** 代理创建实现计划
+   - 编码前生成规划文档：PRD、架构、系统设计、技术文档、任务列表
+   - 识别依赖和风险
+   - 分解为阶段
+
+2. **TDD 方法**
+   - 使用 **tdd-guide** 代理
+   - 先写测试（RED）
+   - 实现以通过测试（GREEN）
+   - 重构（IMPROVE）
+   - 验证 80%+ 覆盖率
+
+3. **代码审查**
+   - 编写代码后立即使用 **code-reviewer** 代理
+   - 解决关键和高优先级问题
+   - 尽可能修复中优先级问题
+
+4. **提交与推送**
+   - 详细的提交消息
+   - 遵循约定式提交格式
+   - 参见 [git-workflow.md](./git-workflow.md) 了解提交消息格式和 PR 流程
+
+5. **审查前检查**
+   - 验证所有自动化检查（CI/CD）已通过
+   - 解决任何合并冲突
+   - 确保分支已与目标分支同步
+   - 仅在这些检查通过后请求审查