kodelyth-ecc 2.18.0 → 2.19.0

package/.agent/rules/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/.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,41 @@
+---
+paths:
+  - "**/*.rb"
+  - "**/*.rake"
+  - "**/Gemfile"
+  - "**/Rakefile"
+---
+# Ruby Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with Ruby specific content.
+
+## Standards
+
+- Follow the **Ruby Style Guide** (rubocop default)
+- Use **frozen_string_literal: true** at the top of every file
+- Prefer `do...end` for multi-line blocks, `{ }` for single-line
+
+## Immutability
+
+```ruby
+# frozen_string_literal: true
+
+User = Data.define(:name, :email)  # Ruby 3.2+ immutable value object
+```
+
+## Formatting
+
+- **RuboCop** for linting and style enforcement
+- **StandardRB** as a zero-config RuboCop config alternative
+- Line length: 120 characters max
+
+## Naming
+
+- `snake_case` for methods and variables
+- `CamelCase` for classes and modules
+- `SCREAMING_SNAKE_CASE` for constants
+- Predicate methods end with `?`, destructive methods end with `!`
+
+## Reference
+
+See skill: `ruby-patterns` for comprehensive Ruby idioms, Rails patterns, and concurrency.

package/.agent/rules/cost-aware-model-routing.md

@@ -0,0 +1,152 @@
+# Cost-Aware Model Routing — Auto-Pick the Right Model Tier per Task
+
+This rule teaches the AI to **classify the current task and recommend the right model tier** instead of defaulting to one expensive model for everything. Pairs with the `agent-intent-routing` rule (agent selection) and the `token-budget` safety hook (spend control) to keep ECC sessions both effective AND affordable.
+
+> **The 80/20 of cost in agent workflows:** 80% of turns are trivial (rename, format, doc, summary, list-files) and burn frontier-model tokens for no benefit. Routing them to a fast/cheap tier saves 60–80% of monthly spend with no measurable quality loss.
+
+---
+
+## The Rule
+
+Before composing your response, classify the task by **scope, ambiguity, and risk**, then either:
+
+1. **Route silently** — the user already picked a model that matches the tier (do nothing).
+2. **Suggest a tier change** — emit a one-line recommendation when the active model is wildly mismatched (frontier model on a doc-typo fix, or a tiny model on a security audit).
+
+Always be transparent. Never silently switch models. Always teach the user how to make the decision next time.
+
+---
+
+## Tier definitions
+
+| Tier | Examples | Default models (provider-agnostic) |
+|---|---|---|
+| **trivial** | Single-line rename, format-only, fix typo, add JSDoc, generate plain summary, list files, regex tweak, version bump, capitalisation. Output usually < 50 lines. | Claude Haiku · Gemini Flash · GPT-4.1-mini · Qwen 2.5 Coder 7B (local) · Ollama (Llama 3.1 8B). |
+| **standard** | Code review of a single PR, write a small unit test, refactor one file, fix a non-critical bug, write a focused doc section, design a small data model. | Claude Sonnet · GPT-4.1 · Gemini Pro · Qwen 2.5 Coder 32B. |
+| **hard** | Architecture decision, debug-blitz of intermittent prod bug, security audit, multi-file refactor (3+ files), incident postmortem, design review, devil-mode adversarial sweep, agent harness changes, anything `code-architect`/`incident-commander`/`debug-detective` would own. | Claude Opus · GPT-5 · Gemini Ultra · best-available frontier model. |
+
+**The names are reference points** — pick the equivalent tier in whatever provider stack the user has configured. The classification is what matters, not the brand.
+
+---
+
+## Classification heuristics (signals to weigh)
+
+Use these signals together — single signals are noisy, three or four together are reliable:
+
+### Trivial signals
+- One file, < 50 lines of context
+- Pure formatting / renaming / documentation work
+- No tests need updating
+- The user's question fits in a single sentence
+- No ambiguity ("rename `getUserName` to `getUserDisplayName`")
+- Verbs: format, rename, capitalize, fix typo, add comment, list, count, summarize
+
+### Standard signals
+- 1–3 files in scope
+- Behavior change + tests required
+- One subsystem
+- Verbs: refactor, review, fix bug, write test, optimize, document, migrate (small)
+- The user pasted a stack trace from one place
+
+### Hard signals
+- Cross-cutting concern (auth, payments, telemetry, retries, concurrency)
+- Multiple subsystems / 4+ files
+- Security implications (PII, secrets, authz, supply chain)
+- Production / incident framing ("urgent", "down", "leaking", "live")
+- Architectural framing ("decide", "design", "should we", "trade-off")
+- The user invoked `code-architect`, `incident-commander`, `debug-detective`, `security-reviewer`, `chaos-engineer`, `backdoor-hunter`, `prompt-injection-hunter`
+- Devil-mode parallel commands
+- The session has already burned > 30k tokens (compounding context)
+- Agent handoff chains involving 3+ specialists
+
+If signals are **mixed or contradictory**, default to **standard** and surface the ambiguity to the user.
+
+---
+
+## Output format when suggesting a tier change
+
+Emit exactly one block, then proceed normally:
+
+```
+[model-router] task=<trivial|standard|hard> · suggested=<tier> · current=<active model or "unknown">
+  why: <one short sentence on the dominant signals>
+  next: <how to switch — provider-specific, e.g. "use --model claude-haiku" or "switch to /model haiku">
+```
+
+**Only emit this block when the active model is mismatched.** If the user is already on the right tier, route silently.
+
+---
+
+## Per-team configurability
+
+Teams override the defaults via env vars or `.kodelythecc/router.json`:
+
+### Env vars
+
+| Variable | Effect |
+|---|---|
+| `KODELYTH_ROUTER=off` | Disable the rule entirely. The AI never suggests model changes. |
+| `KODELYTH_ROUTER_TRIVIAL=<model-id>` | Override trivial tier. |
+| `KODELYTH_ROUTER_STANDARD=<model-id>` | Override standard tier. |
+| `KODELYTH_ROUTER_HARD=<model-id>` | Override hard tier. |
+| `KODELYTH_ROUTER_DEFAULT=<trivial\|standard\|hard>` | Default tier for ambiguous tasks (default `standard`). |
+
+### Project file: `.kodelythecc/router.json`
+
+```json
+{
+  "trivial":  "claude-haiku-4-5-20251001",
+  "standard": "claude-sonnet-4-6",
+  "hard":     "claude-opus-4-1",
+  "default":  "standard",
+  "notes":    "Set by infra team. Bump trivial→sonnet for any task that touches /payments."
+}
+```
+
+A `notes` field is purely human — the AI surfaces it when emitting a recommendation so the team's reasoning rides along.
+
+---
+
+## Hard rules (never break these)
+
+1. **Security audits, incident triage, and devil-mode never downgrade.** If the active task involves `security-reviewer`, `incident-commander`, `debug-detective`, `prompt-injection-hunter`, `supply-chain-auditor`, `secret-hunter`, `backdoor-hunter`, `chaos-engineer`, `jailbreak-tester`, `code-stealer-detector`, or `license-violation-finder` — recommend **hard** tier even if other signals look trivial.
+2. **Production framing wins.** "Down", "leaking", "broken in prod", "incident", "outage" → hard.
+3. **No silent demotion of multi-file refactors** — if 3+ files are in scope, never recommend trivial.
+4. **Respect explicit user choice.** If the user said "use haiku" or "stay on sonnet", do not override. Surface only if a new turn introduces signals that conflict.
+5. **Budget-aware:** if the `token-budget` safety hook reports usage > 70% of budget, bias one tier downward when ambiguous to extend the session.
+
+---
+
+## Examples
+
+```
+User: "rename getUserName to getUserDisplayName everywhere"
+[model-router] task=trivial · suggested=trivial · current=opus
+  why: single rename, mechanical, no behavior change.
+  next: switch to /model claude-haiku to save ~80% on this turn.
+```
+
+```
+User: "production is down and the auth service is throwing 502s, help"
+[model-router] task=hard · suggested=hard · current=haiku
+  why: production incident with security-relevant subsystem.
+  next: switch to /model claude-opus before continuing — this is incident-commander territory.
+```
+
+```
+User: "review this 40-line PR"
+(active model: sonnet — silent route, no block emitted)
+```
+
+---
+
+## Why this rule exists
+
+LLM cost is the #1 reason teams stop using agent toolkits. Two complementary primitives:
+
+- The **token-budget safety hook** prevents catastrophic blow-ups (hard cap per session).
+- This **routing rule** prevents the slow leak (frontier-model overuse on trivial work).
+
+Together they typically cut LLM bills by 50–70% with no measurable quality drop on standard work.
+
+For implementation patterns inside user code (your own pipelines that call LLMs), see the [`cost-aware-llm-pipeline`](../../skills/cost-aware-llm-pipeline/SKILL.md) skill.

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）已通过
+   - 解决任何合并冲突
+   - 确保分支已与目标分支同步
+   - 仅在这些检查通过后请求审查