@heyai-rules/pilo-masterkit 1.2.2 → 3.1.0

package/.agent/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 层）
+- [ ] 正确的错误处理
+- [ ] 没有硬编码值（使用常量或配置）
+- [ ] 没有变更（使用不可变模式）

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

package/.agent/rules/zh/git-workflow.md

@@ -0,0 +1,24 @@
+# Git 工作流
+
+## 提交消息格式
+```
+<类型>: <描述>
+
+<可选正文>
+```
+
+类型：feat, fix, refactor, docs, test, chore, perf, ci
+
+注意：通过 ~/.claude/settings.json 全局禁用归属。
+
+## Pull Request 工作流
+
+创建 PR 时：
+1. 分析完整提交历史（不仅是最新提交）
+2. 使用 `git diff [base-branch]...HEAD` 查看所有更改
+3. 起草全面的 PR 摘要
+4. 包含带有 TODO 的测试计划
+5. 如果是新分支，使用 `-u` 标志推送
+
+> 对于 git 操作之前的完整开发流程（规划、TDD、代码审查），
+> 参见 [development-workflow.md](./development-workflow.md)。

package/.agent/rules/zh/hooks.md

@@ -0,0 +1,30 @@
+# 钩子系统
+
+## 钩子类型
+
+- **PreToolUse**：工具执行前（验证、参数修改）
+- **PostToolUse**：工具执行后（自动格式化、检查）
+- **Stop**：会话结束时（最终验证）
+
+## 自动接受权限
+
+谨慎使用：
+- 为可信、定义明确的计划启用
+- 探索性工作时禁用
+- 永远不要使用 dangerously-skip-permissions 标志
+- 改为在 `~/.claude.json` 中配置 `allowedTools`
+
+## TodoWrite 最佳实践
+
+使用 TodoWrite 工具：
+- 跟踪多步骤任务的进度
+- 验证对指令的理解
+- 启用实时引导
+- 显示细粒度的实现步骤
+
+待办列表揭示：
+- 顺序错误的步骤
+- 缺失的项目
+- 多余的不必要项目
+- 错误的粒度
+- 误解的需求

package/.agent/rules/zh/patterns.md

@@ -0,0 +1,31 @@
+# 常用模式
+
+## 骨架项目
+
+实现新功能时：
+1. 搜索久经考验的骨架项目
+2. 使用并行代理评估选项：
+   - 安全性评估
+   - 可扩展性分析
+   - 相关性评分
+   - 实现规划
+3. 克隆最佳匹配作为基础
+4. 在经验证的结构内迭代
+
+## 设计模式
+
+### 仓储模式
+
+将数据访问封装在一致的接口后面：
+- 定义标准操作：findAll、findById、create、update、delete
+- 具体实现处理存储细节（数据库、API、文件等）
+- 业务逻辑依赖抽象接口，而非存储机制
+- 便于轻松切换数据源，并简化使用模拟的测试
+
+### API 响应格式
+
+对所有 API 响应使用一致的信封：
+- 包含成功/状态指示器
+- 包含数据负载（错误时可为空）
+- 包含错误消息字段（成功时可为空）
+- 包含分页响应的元数据（total、page、limit）

package/.agent/rules/zh/performance.md

@@ -0,0 +1,55 @@
+# 性能优化
+
+## 模型选择策略
+
+**Haiku 4.5**（Sonnet 90% 的能力，3 倍成本节省）：
+- 频繁调用的轻量级代理
+- 结对编程和代码生成
+- 多代理系统中的工作者代理
+
+**Sonnet 4.6**（最佳编码模型）：
+- 主要开发工作
+- 编排多代理工作流
+- 复杂编码任务
+
+**Opus 4.5**（最深度推理）：
+- 复杂架构决策
+- 最大推理需求
+- 研究和分析任务
+
+## 上下文窗口管理
+
+避免在上下文窗口的最后 20% 进行以下操作：
+- 大规模重构
+- 跨多个文件的功能实现
+- 调试复杂交互
+
+上下文敏感度较低的任务：
+- 单文件编辑
+- 独立工具创建
+- 文档更新
+- 简单 bug 修复
+
+## 扩展思考 + 规划模式
+
+扩展思考默认启用，为内部推理保留最多 31,999 个 token。
+
+通过以下方式控制扩展思考：
+- **切换**：Option+T（macOS）/ Alt+T（Windows/Linux）
+- **配置**：在 `~/.claude/settings.json` 中设置 `alwaysThinkingEnabled`
+- **预算上限**：`export MAX_THINKING_TOKENS=10000`
+- **详细模式**：Ctrl+O 查看思考输出
+
+对于需要深度推理的复杂任务：
+1. 确保扩展思考已启用（默认开启）
+2. 启用**规划模式**进行结构化方法
+3. 使用多轮审查进行彻底分析
+4. 使用分角色子代理获得多样化视角
+
+## 构建排查
+
+如果构建失败：
+1. 使用 **build-error-resolver** 代理
+2. 分析错误消息
+3. 增量修复
+4. 每次修复后验证

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

@@ -0,0 +1,29 @@
+# 安全指南
+
+## 强制安全检查
+
+在任何提交之前：
+- [ ] 无硬编码密钥（API 密钥、密码、令牌）
+- [ ] 所有用户输入已验证
+- [ ] SQL 注入防护（参数化查询）
+- [ ] XSS 防护（净化 HTML）
+- [ ] CSRF 保护已启用
+- [ ] 认证/授权已验证
+- [ ] 所有端点启用速率限制
+- [ ] 错误消息不泄露敏感数据
+
+## 密钥管理
+
+- 永远不要在源代码中硬编码密钥
+- 始终使用环境变量或密钥管理器
+- 启动时验证所需的密钥是否存在
+- 轮换任何可能已暴露的密钥
+
+## 安全响应协议
+
+如果发现安全问题：
+1. 立即停止
+2. 使用 **security-reviewer** 代理
+3. 在继续之前修复关键问题
+4. 轮换任何已暴露的密钥
+5. 审查整个代码库中的类似问题

package/.agent/rules/zh/testing.md

@@ -0,0 +1,29 @@
+# 测试要求
+
+## 最低测试覆盖率：80%
+
+测试类型（全部必需）：
+1. **单元测试** - 单个函数、工具、组件
+2. **集成测试** - API 端点、数据库操作
+3. **E2E 测试** - 关键用户流程（框架根据语言选择）
+
+## 测试驱动开发
+
+强制工作流：
+1. 先写测试（RED）
+2. 运行测试 - 应该失败
+3. 编写最小实现（GREEN）
+4. 运行测试 - 应该通过
+5. 重构（IMPROVE）
+6. 验证覆盖率（80%+）
+
+## 测试失败排查
+
+1. 使用 **tdd-guide** 代理
+2. 检查测试隔离
+3. 验证模拟是否正确
+4. 修复实现，而非测试（除非测试有误）
+
+## 代理支持
+
+- **tdd-guide** - 主动用于新功能，强制先写测试

package/.agent/skills/agent-eval/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: agent-eval
+description: Head-to-head comparison of coding agents (Claude Code, Aider, Codex, etc.) on custom tasks with pass rate, cost, time, and consistency metrics
+origin: ECC
+tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Agent Eval Skill
+
+A lightweight CLI tool for comparing coding agents head-to-head on reproducible tasks. Every "which coding agent is best?" comparison runs on vibes — this tool systematizes it.
+
+## When to Activate
+
+- Comparing coding agents (Claude Code, Aider, Codex, etc.) on your own codebase
+- Measuring agent performance before adopting a new tool or model
+- Running regression checks when an agent updates its model or tooling
+- Producing data-backed agent selection decisions for a team
+
+## Installation
+
+> **Note:** Install agent-eval from its repository after reviewing the source.
+
+## Core Concepts
+
+### YAML Task Definitions
+
+Define tasks declaratively. Each task specifies what to do, which files to touch, and how to judge success:
+
+```yaml
+name: add-retry-logic
+description: Add exponential backoff retry to the HTTP client
+repo: ./my-project
+files:
+  - src/http_client.py
+prompt: |
+  Add retry logic with exponential backoff to all HTTP requests.
+  Max 3 retries. Initial delay 1s, max delay 30s.
+judge:
+  - type: pytest
+    command: pytest tests/test_http_client.py -v
+  - type: grep
+    pattern: "exponential_backoff|retry"
+    files: src/http_client.py
+commit: "abc1234"  # pin to specific commit for reproducibility
+```
+
+### Git Worktree Isolation
+
+Each agent run gets its own git worktree — no Docker required. This provides reproducibility isolation so agents cannot interfere with each other or corrupt the base repo.
+
+### Metrics Collected
+
+| Metric | What It Measures |
+|--------|-----------------|
+| Pass rate | Did the agent produce code that passes the judge? |
+| Cost | API spend per task (when available) |
+| Time | Wall-clock seconds to completion |
+| Consistency | Pass rate across repeated runs (e.g., 3/3 = 100%) |
+
+## Workflow
+
+### 1. Define Tasks
+
+Create a `tasks/` directory with YAML files, one per task:
+
+```bash
+mkdir tasks
+# Write task definitions (see template above)
+```
+
+### 2. Run Agents
+
+Execute agents against your tasks:
+
+```bash
+agent-eval run --task tasks/add-retry-logic.yaml --agent claude-code --agent aider --runs 3
+```
+
+Each run:
+1. Creates a fresh git worktree from the specified commit
+2. Hands the prompt to the agent
+3. Runs the judge criteria
+4. Records pass/fail, cost, and time
+
+### 3. Compare Results
+
+Generate a comparison report:
+
+```bash
+agent-eval report --format table
+```
+
+```
+Task: add-retry-logic (3 runs each)
+┌──────────────┬───────────┬────────┬────────┬─────────────┐
+│ Agent        │ Pass Rate │ Cost   │ Time   │ Consistency │
+├──────────────┼───────────┼────────┼────────┼─────────────┤
+│ claude-code  │ 3/3       │ $0.12  │ 45s    │ 100%        │
+│ aider        │ 2/3       │ $0.08  │ 38s    │  67%        │
+└──────────────┴───────────┴────────┴────────┴─────────────┘
+```
+
+## Judge Types
+
+### Code-Based (deterministic)
+
+```yaml
+judge:
+  - type: pytest
+    command: pytest tests/ -v
+  - type: command
+    command: npm run build
+```
+
+### Pattern-Based
+
+```yaml
+judge:
+  - type: grep
+    pattern: "class.*Retry"
+    files: src/**/*.py
+```
+
+### Model-Based (LLM-as-judge)
+
+```yaml
+judge:
+  - type: llm
+    prompt: |
+      Does this implementation correctly handle exponential backoff?
+      Check for: max retries, increasing delays, jitter.
+```
+
+## Best Practices
+
+- **Start with 3-5 tasks** that represent your real workload, not toy examples
+- **Run at least 3 trials** per agent to capture variance — agents are non-deterministic
+- **Pin the commit** in your task YAML so results are reproducible across days/weeks
+- **Include at least one deterministic judge** (tests, build) per task — LLM judges add noise
+- **Track cost alongside pass rate** — a 95% agent at 10x the cost may not be the right choice
+- **Version your task definitions** — they are test fixtures, treat them as code
+
+## Links
+
+- Repository: [github.com/joaquinhuigomez/agent-eval](https://github.com/joaquinhuigomez/agent-eval)

package/.agent/skills/agent-harness-construction/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: agent-harness-construction
+description: Design and optimize AI agent action spaces, tool definitions, and observation formatting for higher completion rates.
+origin: ECC
+---
+
+# Agent Harness Construction
+
+Use this skill when you are improving how an agent plans, calls tools, recovers from errors, and converges on completion.
+
+## Core Model
+
+Agent output quality is constrained by:
+1. Action space quality
+2. Observation quality
+3. Recovery quality
+4. Context budget quality
+
+## Action Space Design
+
+1. Use stable, explicit tool names.
+2. Keep inputs schema-first and narrow.
+3. Return deterministic output shapes.
+4. Avoid catch-all tools unless isolation is impossible.
+
+## Granularity Rules
+
+- Use micro-tools for high-risk operations (deploy, migration, permissions).
+- Use medium tools for common edit/read/search loops.
+- Use macro-tools only when round-trip overhead is the dominant cost.
+
+## Observation Design
+
+Every tool response should include:
+- `status`: success|warning|error
+- `summary`: one-line result
+- `next_actions`: actionable follow-ups
+- `artifacts`: file paths / IDs
+
+## Error Recovery Contract
+
+For every error path, include:
+- root cause hint
+- safe retry instruction
+- explicit stop condition
+
+## Context Budgeting
+
+1. Keep system prompt minimal and invariant.
+2. Move large guidance into skills loaded on demand.
+3. Prefer references to files over inlining long documents.
+4. Compact at phase boundaries, not arbitrary token thresholds.
+
+## Architecture Pattern Guidance
+
+- ReAct: best for exploratory tasks with uncertain path.
+- Function-calling: best for structured deterministic flows.
+- Hybrid (recommended): ReAct planning + typed tool execution.
+
+## Benchmarking
+
+Track:
+- completion rate
+- retries per task
+- pass@1 and pass@3
+- cost per successful task
+
+## Anti-Patterns
+
+- Too many tools with overlapping semantics.
+- Opaque tool output with no recovery hints.
+- Error-only output without next steps.
+- Context overloading with irrelevant references.