@zmice/zc 0.1.0 → 0.2.0

package/vendor/packages/toolkit/src/content/skills/code-simplification/body.md

@@ -0,0 +1,326 @@
+# Code Simplification
+
+> Inspired by the [Claude Code Simplifier plugin](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/code-simplifier/agents/code-simplifier.md). Adapted here as a model-agnostic, process-driven skill for any AI coding agent.
+
+## Overview
+
+Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines — it's code that is easier to read, understand, modify, and debug. Every simplification must pass a simple test: "Would a new team member understand this faster than the original?"
+
+## When to Use
+
+- After a feature is working and tests pass, but the implementation feels heavier than it needs to be
+- During code review when readability or complexity issues are flagged
+- When you encounter deeply nested logic, long functions, or unclear names
+- When refactoring code written under time pressure
+- When consolidating related logic scattered across files
+- After merging changes that introduced duplication or inconsistency
+
+**When NOT to use:**
+
+- Code is already clean and readable — don't simplify for the sake of it
+- You don't understand what the code does yet — comprehend before you simplify
+- The code is performance-critical and the "simpler" version would be measurably slower
+- You're about to rewrite the module entirely — simplifying throwaway code wastes effort
+
+## The Five Principles
+
+### 1. Preserve Behavior Exactly
+
+Don't change what the code does — only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it.
+
+```
+ASK BEFORE EVERY CHANGE:
+→ Does this produce the same output for every input?
+→ Does this maintain the same error behavior?
+→ Does this preserve the same side effects and ordering?
+→ Do all existing tests still pass without modification?
+```
+
+### 2. Follow Project Conventions
+
+Simplification means making code more consistent with the codebase, not imposing external preferences. Before simplifying:
+
+```
+1. Read CLAUDE.md / project conventions
+2. Study how neighboring code handles similar patterns
+3. Match the project's style for:
+   - Import ordering and module system
+   - Function declaration style
+   - Naming conventions
+   - Error handling patterns
+   - Type annotation depth
+```
+
+Simplification that breaks project consistency is not simplification — it's churn.
+
+### 3. Prefer Clarity Over Cleverness
+
+Explicit code is better than compact code when the compact version requires a mental pause to parse.
+
+```typescript
+// UNCLEAR: Dense ternary chain
+const label = isNew ? 'New' : isUpdated ? 'Updated' : isArchived ? 'Archived' : 'Active';
+
+// CLEAR: Readable mapping
+function getStatusLabel(item: Item): string {
+  if (item.isNew) return 'New';
+  if (item.isUpdated) return 'Updated';
+  if (item.isArchived) return 'Archived';
+  return 'Active';
+}
+```
+
+```typescript
+// UNCLEAR: Chained reduces with inline logic
+const result = items.reduce((acc, item) => ({
+  ...acc,
+  [item.id]: { ...acc[item.id], count: (acc[item.id]?.count ?? 0) + 1 }
+}), {});
+
+// CLEAR: Named intermediate step
+const countById = new Map<string, number>();
+for (const item of items) {
+  countById.set(item.id, (countById.get(item.id) ?? 0) + 1);
+}
+```
+
+### 4. Maintain Balance
+
+Simplification has a failure mode: over-simplification. Watch for these traps:
+
+- **Inlining too aggressively** — removing a helper that gave a concept a name makes the call site harder to read
+- **Combining unrelated logic** — two simple functions merged into one complex function is not simpler
+- **Removing "unnecessary" abstraction** — some abstractions exist for extensibility or testability, not complexity
+- **Optimizing for line count** — fewer lines is not the goal; easier comprehension is
+
+### 5. Scope to What Changed
+
+Default to simplifying recently modified code. Avoid drive-by refactors of unrelated code unless explicitly asked to broaden scope. Unscoped simplification creates noise in diffs and risks unintended regressions.
+
+## The Simplification Process
+
+### Step 1: Understand Before Touching (Chesterton's Fence)
+
+Before changing or removing anything, understand why it exists. This is Chesterton's Fence: if you see a fence across a road and don't understand why it's there, don't tear it down. First understand the reason, then decide if the reason still applies.
+
+```
+BEFORE SIMPLIFYING, ANSWER:
+- What is this code's responsibility?
+- What calls it? What does it call?
+- What are the edge cases and error paths?
+- Are there tests that define the expected behavior?
+- Why might it have been written this way? (Performance? Platform constraint? Historical reason?)
+- Check git blame: what was the original context for this code?
+```
+
+If you can't answer these, you're not ready to simplify. Read more context first.
+
+### Step 2: Identify Simplification Opportunities
+
+Scan for these patterns — each one is a concrete signal, not a vague smell:
+
+**Structural complexity:**
+
+| Pattern | Signal | Simplification |
+|---------|--------|----------------|
+| Deep nesting (3+ levels) | Hard to follow control flow | Extract conditions into guard clauses or helper functions |
+| Long functions (50+ lines) | Multiple responsibilities | Split into focused functions with descriptive names |
+| Nested ternaries | Requires mental stack to parse | Replace with if/else chains, switch, or lookup objects |
+| Boolean parameter flags | `doThing(true, false, true)` | Replace with options objects or separate functions |
+| Repeated conditionals | Same `if` check in multiple places | Extract to a well-named predicate function |
+
+**Naming and readability:**
+
+| Pattern | Signal | Simplification |
+|---------|--------|----------------|
+| Generic names | `data`, `result`, `temp`, `val`, `item` | Rename to describe the content: `userProfile`, `validationErrors` |
+| Abbreviated names | `usr`, `cfg`, `btn`, `evt` | Use full words unless the abbreviation is universal (`id`, `url`, `api`) |
+| Misleading names | Function named `get` that also mutates state | Rename to reflect actual behavior |
+| Comments explaining "what" | `// increment counter` above `count++` | Delete the comment — the code is clear enough |
+| Comments explaining "why" | `// Retry because the API is flaky under load` | Keep these — they carry intent the code can't express |
+
+**Redundancy:**
+
+| Pattern | Signal | Simplification |
+|---------|--------|----------------|
+| Duplicated logic | Same 5+ lines in multiple places | Extract to a shared function |
+| Dead code | Unreachable branches, unused variables, commented-out blocks | Remove (after confirming it's truly dead) |
+| Unnecessary abstractions | Wrapper that adds no value | Inline the wrapper, call the underlying function directly |
+| Over-engineered patterns | Factory-for-a-factory, strategy-with-one-strategy | Replace with the simple direct approach |
+| Redundant type assertions | Casting to a type that's already inferred | Remove the assertion |
+
+### Step 3: Apply Changes Incrementally
+
+Make one simplification at a time. Run tests after each change. **Submit refactoring changes separately from feature or bug fix changes.** A PR that refactors and adds a feature is two PRs — split them.
+
+```
+FOR EACH SIMPLIFICATION:
+1. Make the change
+2. Run the test suite
+3. If tests pass → commit (or continue to next simplification)
+4. If tests fail → revert and reconsider
+```
+
+Avoid batching multiple simplifications into a single untested change. If something breaks, you need to know which simplification caused it.
+
+**The Rule of 500:** If a refactoring would touch more than 500 lines, invest in automation (codemods, sed scripts, AST transforms) rather than making the changes by hand. Manual edits at that scale are error-prone and exhausting to review.
+
+### Step 4: Verify the Result
+
+After all simplifications, step back and evaluate the whole:
+
+```
+COMPARE BEFORE AND AFTER:
+- Is the simplified version genuinely easier to understand?
+- Did you introduce any new patterns inconsistent with the codebase?
+- Is the diff clean and reviewable?
+- Would a teammate approve this change?
+```
+
+If the "simplified" version is harder to understand or review, revert. Not every simplification attempt succeeds.
+
+## Language-Specific Guidance
+
+### TypeScript / JavaScript
+
+```typescript
+// SIMPLIFY: Unnecessary async wrapper
+// Before
+async function getUser(id: string): Promise<User> {
+  return await userService.findById(id);
+}
+// After
+function getUser(id: string): Promise<User> {
+  return userService.findById(id);
+}
+
+// SIMPLIFY: Verbose conditional assignment
+// Before
+let displayName: string;
+if (user.nickname) {
+  displayName = user.nickname;
+} else {
+  displayName = user.fullName;
+}
+// After
+const displayName = user.nickname || user.fullName;
+
+// SIMPLIFY: Manual array building
+// Before
+const activeUsers: User[] = [];
+for (const user of users) {
+  if (user.isActive) {
+    activeUsers.push(user);
+  }
+}
+// After
+const activeUsers = users.filter((user) => user.isActive);
+
+// SIMPLIFY: Redundant boolean return
+// Before
+function isValid(input: string): boolean {
+  if (input.length > 0 && input.length < 100) {
+    return true;
+  }
+  return false;
+}
+// After
+function isValid(input: string): boolean {
+  return input.length > 0 && input.length < 100;
+}
+```
+
+### Python
+
+```python
+# SIMPLIFY: Verbose dictionary building
+# Before
+result = {}
+for item in items:
+    result[item.id] = item.name
+# After
+result = {item.id: item.name for item in items}
+
+# SIMPLIFY: Nested conditionals with early return
+# Before
+def process(data):
+    if data is not None:
+        if data.is_valid():
+            if data.has_permission():
+                return do_work(data)
+            else:
+                raise PermissionError("No permission")
+        else:
+            raise ValueError("Invalid data")
+    else:
+        raise TypeError("Data is None")
+# After
+def process(data):
+    if data is None:
+        raise TypeError("Data is None")
+    if not data.is_valid():
+        raise ValueError("Invalid data")
+    if not data.has_permission():
+        raise PermissionError("No permission")
+    return do_work(data)
+```
+
+### React / JSX
+
+```tsx
+// SIMPLIFY: Verbose conditional rendering
+// Before
+function UserBadge({ user }: Props) {
+  if (user.isAdmin) {
+    return <Badge variant="admin">Admin</Badge>;
+  } else {
+    return <Badge variant="default">User</Badge>;
+  }
+}
+// After
+function UserBadge({ user }: Props) {
+  const variant = user.isAdmin ? 'admin' : 'default';
+  const label = user.isAdmin ? 'Admin' : 'User';
+  return <Badge variant={variant}>{label}</Badge>;
+}
+
+// SIMPLIFY: Prop drilling through intermediate components
+// Before — consider whether context or composition solves this better.
+// This is a judgment call — flag it, don't auto-refactor.
+```
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "It's working, no need to touch it" | Working code that's hard to read will be hard to fix when it breaks. Simplifying now saves time on every future change. |
+| "Fewer lines is always simpler" | A 1-line nested ternary is not simpler than a 5-line if/else. Simplicity is about comprehension speed, not line count. |
+| "I'll just quickly simplify this unrelated code too" | Unscoped simplification creates noisy diffs and risks regressions in code you didn't intend to change. Stay focused. |
+| "The types make it self-documenting" | Types document structure, not intent. A well-named function explains *why* better than a type signature explains *what*. |
+| "This abstraction might be useful later" | Don't preserve speculative abstractions. If it's not used now, it's complexity without value. Remove it and re-add when needed. |
+| "The original author must have had a reason" | Maybe. Check git blame — apply Chesterton's Fence. But accumulated complexity often has no reason; it's just the residue of iteration under pressure. |
+| "I'll refactor while adding this feature" | Separate refactoring from feature work. Mixed changes are harder to review, revert, and understand in history. |
+
+## Red Flags
+
+- Simplification that requires modifying tests to pass (you likely changed behavior)
+- "Simplified" code that is longer and harder to follow than the original
+- Renaming things to match your preferences rather than project conventions
+- Removing error handling because "it makes the code cleaner"
+- Simplifying code you don't fully understand
+- Batching many simplifications into one large, hard-to-review commit
+- Refactoring code outside the scope of the current task without being asked
+
+## Verification
+
+After completing a simplification pass:
+
+- [ ] All existing tests pass without modification
+- [ ] Build succeeds with no new warnings
+- [ ] Linter/formatter passes (no style regressions)
+- [ ] Each simplification is a reviewable, incremental change
+- [ ] The diff is clean — no unrelated changes mixed in
+- [ ] Simplified code follows project conventions (checked against CLAUDE.md or equivalent)
+- [ ] No error handling was removed or weakened
+- [ ] No dead code was left behind (unused imports, unreachable branches)
+- [ ] A teammate or review agent would approve the change as a net improvement

package/vendor/packages/toolkit/src/content/skills/code-simplification/meta.yaml

@@ -0,0 +1,21 @@
+kind: skill
+name: code-simplification
+title: 代码简化
+description: 以澄清代码为目标进行简化重构。适用于在不改变行为的前提下提升可读性和可维护性，也适用于处理已经积累了不必要复杂度的代码。
+tier: recommended
+audience: default
+stability: stable
+suggests:
+  - skill:engineering-principles
+  - skill:code-review-and-quality
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: agent-skills
+  strategy: adapted
+  origin_name: code-simplification
+  origin_path: skills/code-simplification/SKILL.md
+  origin_id: skill:code-simplification
+  notes: 基于上游代码简化能力中文化整理。

package/vendor/packages/toolkit/src/content/skills/codebase-onboarding/body.md

@@ -0,0 +1,40 @@
+# 代码库导览
+
+## 何时使用
+
+- 第一次接触一个代码库
+- 要在陌生项目上开始实现、调试或重构
+- 需要快速建立项目全局认知
+- 需要生成后续任务可复用的项目概览
+
+## 输入前提
+
+- 已确定要探索的仓库或子系统
+- 愿意先理解结构，再进入实现
+- 目标是产出概览，而不是理解一切细节
+
+## 执行步骤
+
+1. 扫描目录结构和关键配置文件
+2. 定位入口点、路由、模型和主流程
+3. 梳理依赖关系、核心模块和数据流
+4. 识别架构模式、测试策略和项目约定
+5. 输出一份后续开发可复用的项目概览
+
+## 成功标准
+
+- 能清楚说明项目类型、技术栈、入口点和关键目录
+- 核心模块职责和数据流向是明确的
+- 已记录当前任务相关的关键约定和陷阱
+- 输出足够短，能被后续任务直接消费
+
+## 相关原则
+
+- 先读 README 和测试，再深挖源码
+- 聚焦当前任务相关区域，不求一次理解全仓库
+- 概览是压缩上下文，不是转述源码
+
+## 与其他技能的衔接
+
+- 产出的概览可直接供 `context-engineering` 使用
+- 在陌生项目上做需求或实现前，可先接 `brainstorming-and-design` / `spec-driven-development`

package/vendor/packages/toolkit/src/content/skills/codebase-onboarding/meta.yaml

@@ -0,0 +1,20 @@
+kind: skill
+name: codebase-onboarding
+title: 代码库导览
+description: 进入陌生代码库或启动新项目时使用。通过目录扫描、入口定位、依赖梳理与模式识别快速建立全局认知，并输出后续开发可复用的精炼上下文。
+tier: recommended
+audience: default
+stability: stable
+suggests:
+  - skill:context-engineering
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: agent-skills
+  strategy: adapted
+  origin_name: codebase-onboarding
+  origin_path: skills/codebase-onboarding/SKILL.md
+  origin_id: skill:codebase-onboarding
+  notes: 延续上游 onboarding 方法，并对齐本仓库上下文压缩习惯。

package/vendor/packages/toolkit/src/content/skills/context-budget-audit/body.md

@@ -0,0 +1,38 @@
+# 上下文审计
+
+## 何时使用
+
+- 会话表现变慢或质量下降，但原因不明时
+- 最近增加了新的 skills、agents、rules 或 MCP 工具时
+- 想知道上下文预算到底被哪些组件占掉时
+- `ctx-health` 提示需要进一步审计时
+
+## 输入前提
+
+- 已有需要审计的上下文组件集合
+- 目标是量化膨胀来源，而不是泛泛觉得“上下文太长”
+- 接受这是一项治理动作，不是日常每次都要做
+
+## 执行步骤
+
+1. 盘点各类组件的 token 开销
+2. 按始终需要、按需需要、很少需要进行分类
+3. 识别臃肿、重复和低收益组件
+4. 输出按收益排序的压缩建议
+
+## 成功标准
+
+- 能明确指出主要 token 消耗点
+- 有可执行的缩减建议，而不是只给感受判断
+- 可估算压缩前后的上下文开销差异
+
+## 相关原则
+
+- 量化优先于感觉
+- 上下文不是越多越好，而是越准越好
+- 审计的目标是提升有效信号密度
+
+## 与其他技能的衔接
+
+- 是 `ctx-health` 的深度版本
+- 与 `context-engineering` 配合，用于长期治理

package/vendor/packages/toolkit/src/content/skills/context-budget-audit/meta.yaml

@@ -0,0 +1,17 @@
+kind: skill
+name: context-budget-audit
+title: 上下文审计
+description: 审计代理、skills、rules 与说明文档对上下文窗口的占用，识别膨胀和冗余项，并产出按优先级排序的 token 节省建议。适用于会话质量下降、组件持续增长或需要核查上下文余量时。
+tier: optional
+audience: advanced
+stability: evolving
+requires:
+  - skill:context-engineering
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: toolkit-original
+  strategy: curated
+  notes: 本仓库针对长会话治理补充的内容运维能力。

package/vendor/packages/toolkit/src/content/skills/context-engineering/body.md

@@ -0,0 +1,55 @@
+# 上下文工程
+
+## 何时使用
+
+- 开始新的编码会话或新子任务时
+- 输出质量下降，开始出现幻觉、忽略约定或跑偏
+- 任务切换导致上下文混杂时
+- 需要为代理准备最小但足够的输入材料时
+
+## 方法原则
+
+- 复杂任务先校准目标、边界和验证方式，再装载上下文
+- 最小充分上下文优先于“大而全”材料堆叠
+- 上下文装载要服务当前任务，不为可能发生的旁支需求提前铺料
+- 一旦任务阶段变化，就主动压缩和重建上下文，避免 drift
+
+## 输入前提
+
+- 已知道当前任务真正需要哪些信息
+- 愿意主动裁剪无关上下文
+- 接受规则文件、规格、源码、错误输出有不同优先级
+
+## 执行步骤
+
+1. 先校准：明确目标、非目标、风险点和需要的验证证据
+2. 先装载稳定规则：规则文件、长期约定、关键边界
+3. 再装载任务级上下文：规格片段、相关源码、测试、错误输出
+4. 控制上下文体积，只保留当前任务需要的信息
+5. 任务切换或阶段推进时主动压缩总结，清理旧上下文
+6. 发现上下文冲突、缺口或陈旧信息时，显式暴露而不是猜测
+
+## 成功标准
+
+- 开始执行前，代理已经知道目标、边界和验证方式
+- 代理看到的是当前任务需要的最小充分上下文
+- 规则、规格、源码和错误信息的层级清晰
+- 上下文切换不会把旧问题带入新任务
+- 遇到冲突时能清楚指出需要人类决策的点
+- 不会因为上下文膨胀而偏离当前任务
+
+## 相关原则
+
+- 复杂任务谨慎优先于求快
+- 少而准，比多而杂更有效
+- 目标导向决定装载顺序
+- 外科式修改也适用于上下文，只带入要改的那一小块
+- 规格和规则优先于猜测
+- 压缩上下文是持续动作，不是最后补救
+
+## 与其他技能的衔接
+
+- 与 `engineering-principles` 配合，在进入实现前先校准工作方式
+- 与 `codebase-onboarding` 配合，先建立地图再装载局部上下文
+- 与 `context-budget-audit` 配合，检查上下文是否膨胀
+- 为几乎所有实现和审查技能提供前置支持

package/vendor/packages/toolkit/src/content/skills/context-engineering/meta.yaml

@@ -0,0 +1,17 @@
+kind: skill
+name: context-engineering
+title: 上下文工程
+description: 优化代理的上下文配置。适用于新会话启动、输出质量下降、任务切换，或需要为项目整理规则文件与上下文装配方式时。
+tier: recommended
+audience: advanced
+stability: stable
+suggests:
+  - skill:using-agent-skills
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: superpowers
+  strategy: inspired
+  notes: 吸收上游对上下文组织的经验，并结合本仓库上下文管理原则整理。