@geraldmaron/construct 1.0.0

package/rules/zh/code-review.md

@@ -0,0 +1,129 @@
+<!--
+rules/zh/code-review.md — <one-line purpose>
+
+<2–6 line summary.>
+-->
+# 代码审查标准
+
+## 目的
+
+代码审查确保代码合并前的质量、安全性和可维护性。此规则定义何时以及如何进行代码审查。
+
+## 何时审查
+
+**强制审查触发条件：**
+
+- 编写或修改代码后
+- 提交到共享分支之前
+- 更改安全敏感代码时（认证、支付、用户数据）
+- 进行架构更改时
+- 合并 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,53 @@
+<!--
+rules/zh/coding-style.md — <one-line purpose>
+
+<2–6 line summary.>
+-->
+# 编码风格
+
+## 不可变性（关键）
+
+始终创建新对象，永远不要修改现有对象：
+
+```
+// 伪代码
+错误:  modify(original, field, value) → 就地修改 original
+正确: update(original, field, value) → 返回带有更改的新副本
+```
+
+原理：不可变数据防止隐藏的副作用，使调试更容易，并启用安全的并发。
+
+## 文件组织
+
+多个小文件 > 少量大文件：
+- 高内聚，低耦合
+- 典型 200-400 行，最多 800 行
+- 从大模块中提取工具函数
+- 按功能/领域组织，而非按类型
+
+## 错误处理
+
+始终全面处理错误：
+- 在每一层显式处理错误
+- 在面向 UI 的代码中提供用户友好的错误消息
+- 在服务器端记录详细的错误上下文
+- 永远不要静默吞掉错误
+
+## 输入验证
+
+始终在系统边界验证：
+- 处理前验证所有用户输入
+- 在可用的情况下使用基于模式的验证
+- 快速失败并给出清晰的错误消息
+- 永远不要信任外部数据（API 响应、用户输入、文件内容）
+
+## 代码质量检查清单
+
+在标记工作完成前：
+- [ ] 代码可读且命名良好
+- [ ] 函数很小（<50 行）
+- [ ] 文件聚焦（<800 行）
+- [ ] 没有深层嵌套（>4 层）
+- [ ] 正确的错误处理
+- [ ] 没有硬编码值（使用常量或配置）
+- [ ] 没有变更（使用不可变模式）

package/rules/zh/development-workflow.md

@@ -0,0 +1,49 @@
+<!--
+rules/zh/development-workflow.md — <one-line purpose>
+
+<2–6 line summary.>
+-->
+# 开发工作流
+
+> 此文件扩展 [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/rules/zh/git-workflow.md

@@ -0,0 +1,29 @@
+<!--
+rules/zh/git-workflow.md — <one-line purpose>
+
+<2–6 line summary.>
+-->
+# 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/rules/zh/hooks.md

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

package/rules/zh/patterns.md

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

package/rules/zh/performance.md

@@ -0,0 +1,60 @@
+<!--
+rules/zh/performance.md — <one-line purpose>
+
+<2–6 line summary.>
+-->
+# 性能优化
+
+## 模型选择策略
+
+**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/rules/zh/security.md

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

package/rules/zh/testing.md

@@ -0,0 +1,34 @@
+<!--
+rules/zh/testing.md — <one-line purpose>
+
+<2–6 line summary.>
+-->
+# 测试要求
+
+## 最低测试覆盖率：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/skills/ai/agent-dev.md

@@ -0,0 +1,102 @@
+<!--
+skills/ai/agent-dev.md — AI Agent Development — Use this skill when building AI agents, tool-use systems, or multi-agent workflo
+
+Use this skill when building AI agents, tool-use systems, or multi-agent workflows. ## Agent Architecture
+-->
+# AI Agent Development
+
+Use this skill when building AI agents, tool-use systems, or multi-agent workflows.
+
+## Agent Architecture
+
+### Core Loop
+1. Receive user input or system event
+2. Plan: decide what action to take (tool call, response, delegation)
+3. Act: execute the chosen action
+4. Observe: process the result
+5. Repeat until the task is complete or a stop condition is met
+
+### Planning Strategies
+- ReAct: interleave reasoning and acting in a single prompt
+- Plan-then-execute: generate a full plan, execute steps sequentially
+- Tree of thought: explore multiple approaches, select the best
+- Choose based on task complexity; ReAct for simple, plan-first for multi-step
+
+## Tool Design
+
+### Principles
+- Each tool does one thing well
+- Tool names and descriptions are clear enough for the LLM to select correctly
+- Parameters have strict types and validation
+- Return structured results the LLM can parse
+- Include error states the agent can reason about
+
+### Tool Schema
+- Use JSON Schema or equivalent for parameter definitions
+- Required vs optional parameters clearly marked
+- Enum values for constrained choices
+- Description field explains when and why to use the tool
+- Examples in the description improve selection accuracy
+
+### Common Tool Categories
+- Information retrieval: search, database query, API call
+- Computation: calculator, code execution, data transformation
+- Communication: email, messaging, notifications
+- File operations: read, write, list
+- System control: deploy, configure, monitor
+
+## Function Calling
+
+- Validate all tool arguments before execution
+- Sanitize user-influenced inputs passed to tools
+- Set timeouts on all external tool calls
+- Handle tool failures gracefully; allow the agent to retry or choose alternatives
+- Log every tool call with inputs, outputs, latency, and success/failure
+
+## Multi-Agent Systems
+
+### Patterns
+- **Orchestrator-worker**: one agent delegates subtasks to specialists
+- **Pipeline**: agents process sequentially, each adding to the context
+- **Debate**: multiple agents propose solutions, a judge selects the best
+- **Swarm**: agents claim tasks from a shared queue
+
+### Coordination
+- Define clear responsibilities per agent role
+- One writer per resource at any time to avoid conflicts
+- Shared context via message passing, not shared mutable state
+- Supervisor agent monitors progress and handles failures
+- Set maximum iterations to prevent infinite loops
+
+## Prompt Engineering for Agents
+
+- System prompt: role, capabilities, constraints, output format
+- Include examples of correct tool selection and usage
+- Specify when to ask for clarification vs proceed with assumptions
+- Define stop conditions: task complete, max iterations, confidence threshold
+- Separate instructions from context; keep instructions stable
+
+## Error Handling
+
+- Retry transient failures with backoff
+- Escalate persistent failures to the user or supervisor
+- Maintain a fallback path when tools are unavailable
+- Log enough context to debug failures post-hoc
+- Prevent cascading failures in multi-agent systems
+
+## Safety and Guardrails
+
+- Validate agent outputs before executing side effects
+- Require human approval for high-impact actions (delete, deploy, send)
+- Rate limit tool calls to prevent runaway loops
+- Monitor token usage and cost per agent session
+- Content filtering on both inputs and outputs
+
+## Evaluation
+
+- Task completion rate on a benchmark set
+- Tool selection accuracy: did the agent pick the right tool?
+- Step efficiency: how many steps to complete vs optimal?
+- Error recovery rate: does the agent recover from tool failures?
+- Cost per task: tokens consumed, API calls made, latency
+- Run evals on every prompt or tool change

package/skills/ai/llm-security.md

@@ -0,0 +1,105 @@
+<!--
+skills/ai/llm-security.md — LLM Security — Use this skill when securing LLM-powered applications against prompt injection,
+
+Use this skill when securing LLM-powered applications against prompt injection, data leakage, and misuse. ## Prompt Injection
+-->
+# LLM Security
+
+Use this skill when securing LLM-powered applications against prompt injection, data leakage, and misuse.
+
+## Prompt Injection
+
+### Direct Injection
+- User input overrides system instructions ("ignore previous instructions and...")
+- Instruction delimiters in user content confuse the model
+- Encoded payloads: base64, ROT13, unicode tricks bypass naive filters
+
+### Indirect Injection
+- Malicious instructions embedded in retrieved documents, emails, or web pages
+- Tool outputs containing adversarial prompts
+- Injected content in database records, file metadata, or API responses
+
+### Mitigations
+- Separate system instructions from user input with clear structural delimiters
+- Use structured tool calling instead of free-text tool invocation
+- Validate and sanitize all external content before including in prompts
+- Monitor for instruction-following anomalies in outputs
+- Defense in depth: no single mitigation is sufficient
+
+## Data Leakage
+
+### System Prompt Extraction
+- Adversarial queries designed to make the model reveal its instructions
+- Avoid placing secrets, API keys, or sensitive logic in prompts
+- Test with extraction attempts before deployment
+
+### Training Data Leakage
+- Model may memorize and reproduce sensitive training data
+- Use output filtering for PII, credentials, and proprietary content
+- Fine-tuned models have higher memorization risk
+
+### Context Window Leakage
+- Multi-turn conversations may expose prior context to subsequent users
+- Isolate sessions; do not share context across users
+- Clear context between logically separate interactions
+
+## Output Validation
+
+- Classify outputs for harmful content before delivering to users
+- Filter PII from generated responses
+- Validate structured outputs against expected schema
+- Block responses that reference system prompt content
+- Rate limit generation to prevent abuse
+
+## Guardrails Architecture
+
+### Input Layer
+1. Input validation: length, format, character set
+2. Content classification: detect adversarial, toxic, or off-topic input
+3. Rate limiting per user, per IP, per session
+4. Blocklist for known attack patterns (with awareness that blocklists are bypassable)
+
+### Processing Layer
+1. Separate system context from user context structurally
+2. Minimize sensitive information in prompts
+3. Use tool-level permissions: agent cannot access tools beyond its scope
+4. Constrain generation parameters: temperature, max tokens, stop sequences
+
+### Output Layer
+1. Content classification on generated text
+2. PII detection and redaction
+3. Schema validation for structured outputs
+4. Citation verification against source material
+5. Human review queue for high-risk outputs
+
+## Tool Use Security
+
+- Principle of least privilege: each tool call should require minimum permissions
+- Validate all tool arguments; do not pass user input directly to tools
+- Sandbox code execution environments
+- Log all tool invocations for audit
+- Require confirmation for destructive operations
+
+## Jailbreak Resistance
+
+- No single defense stops all jailbreaks; layer mitigations
+- Regularly test with known jailbreak techniques
+- Monitor for novel attack patterns in production logs
+- Update defenses as new techniques emerge
+- Accept that sufficiently motivated attackers will find bypasses; limit blast radius
+
+## Monitoring and Incident Response
+
+- Log all prompts, responses, and tool calls (with PII redaction)
+- Alert on: unusual token patterns, repeated injection attempts, output policy violations
+- Maintain an incident response playbook for LLM-specific failures
+- Track and categorize bypass attempts to improve defenses
+- Measure: injection detection rate, false positive rate, policy violation rate
+
+## Compliance
+
+- Document AI usage and limitations for users
+- Maintain audit trail of model inputs, outputs, and decisions
+- Disclose AI-generated content where required by policy or regulation
+- Ensure data processing complies with privacy regulations (GDPR, CCPA)
+- Review and update security controls with each model or prompt change