@zmice/zc 0.1.0 → 0.2.0

package/vendor/packages/toolkit/src/content/skills/performance-optimization/body.md

@@ -0,0 +1,345 @@
+# Performance Optimization
+
+## Overview
+
+Measure before optimizing. Performance work without measurement is guessing — and guessing leads to premature optimization that adds complexity without improving what matters. Profile first, identify the actual bottleneck, fix it, measure again. Optimize only what measurements prove matters.
+
+## When to Use
+
+- Performance requirements exist in the spec (load time budgets, response time SLAs)
+- Users or monitoring report slow behavior
+- Core Web Vitals scores are below thresholds
+- You suspect a change introduced a regression
+- Building features that handle large datasets or high traffic
+
+**When NOT to use:** Don't optimize before you have evidence of a problem. Premature optimization adds complexity that costs more than the performance it gains.
+
+## Core Web Vitals Targets
+
+| Metric | Good | Needs Improvement | Poor |
+|--------|------|-------------------|------|
+| **LCP** (Largest Contentful Paint) | ≤ 2.5s | ≤ 4.0s | > 4.0s |
+| **INP** (Interaction to Next Paint) | ≤ 200ms | ≤ 500ms | > 500ms |
+| **CLS** (Cumulative Layout Shift) | ≤ 0.1 | ≤ 0.25 | > 0.25 |
+
+## The Optimization Workflow
+
+```
+1. MEASURE  → Establish baseline with real data
+2. IDENTIFY → Find the actual bottleneck (not assumed)
+3. FIX      → Address the specific bottleneck
+4. VERIFY   → Measure again, confirm improvement
+5. GUARD    → Add monitoring or tests to prevent regression
+```
+
+### Step 1: Measure
+
+Two complementary approaches — use both:
+
+- **Synthetic (Lighthouse, DevTools Performance tab):** Controlled conditions, reproducible. Best for CI regression detection and isolating specific issues.
+- **RUM (web-vitals library, CrUX):** Real user data in real conditions. Required to validate that a fix actually improved user experience.
+
+**Frontend:**
+```bash
+# Synthetic: Lighthouse in Chrome DevTools (or CI)
+# Chrome DevTools → Performance tab → Record
+# Chrome DevTools MCP → Performance trace
+
+# RUM: Web Vitals library in code
+import { onLCP, onINP, onCLS } from 'web-vitals';
+
+onLCP(console.log);
+onINP(console.log);
+onCLS(console.log);
+```
+
+**Backend:**
+```bash
+# Response time logging
+# Application Performance Monitoring (APM)
+# Database query logging with timing
+
+# Simple timing
+console.time('db-query');
+const result = await db.query(...);
+console.timeEnd('db-query');
+```
+
+### Where to Start Measuring
+
+Use the symptom to decide what to measure first:
+
+```
+What is slow?
+├── First page load
+│   ├── Large bundle? --> Measure bundle size, check code splitting
+│   ├── Slow server response? --> Measure TTFB in DevTools Network waterfall
+│   │   ├── DNS long? --> Add dns-prefetch / preconnect for known origins
+│   │   ├── TCP/TLS long? --> Enable HTTP/2, check edge deployment, keep-alive
+│   │   └── Waiting (server) long? --> Profile backend, check queries and caching
+│   └── Render-blocking resources? --> Check network waterfall for CSS/JS blocking
+├── Interaction feels sluggish
+│   ├── UI freezes on click? --> Profile main thread, look for long tasks (>50ms)
+│   ├── Form input lag? --> Check re-renders, controlled component overhead
+│   └── Animation jank? --> Check layout thrashing, forced reflows
+├── Page after navigation
+│   ├── Data loading? --> Measure API response times, check for waterfalls
+│   └── Client rendering? --> Profile component render time, check for N+1 fetches
+└── Backend / API
+    ├── Single endpoint slow? --> Profile database queries, check indexes
+    ├── All endpoints slow? --> Check connection pool, memory, CPU
+    └── Intermittent slowness? --> Check for lock contention, GC pauses, external deps
+```
+
+### Step 2: Identify the Bottleneck
+
+Common bottlenecks by category:
+
+**Frontend:**
+
+| Symptom | Likely Cause | Investigation |
+|---------|-------------|---------------|
+| Slow LCP | Large images, render-blocking resources, slow server | Check network waterfall, image sizes |
+| High CLS | Images without dimensions, late-loading content, font shifts | Check layout shift attribution |
+| Poor INP | Heavy JavaScript on main thread, large DOM updates | Check long tasks in Performance trace |
+| Slow initial load | Large bundle, many network requests | Check bundle size, code splitting |
+
+**Backend:**
+
+| Symptom | Likely Cause | Investigation |
+|---------|-------------|---------------|
+| Slow API responses | N+1 queries, missing indexes, unoptimized queries | Check database query log |
+| Memory growth | Leaked references, unbounded caches, large payloads | Heap snapshot analysis |
+| CPU spikes | Synchronous heavy computation, regex backtracking | CPU profiling |
+| High latency | Missing caching, redundant computation, network hops | Trace requests through the stack |
+
+### Step 3: Fix Common Anti-Patterns
+
+#### N+1 Queries (Backend)
+
+```typescript
+// BAD: N+1 — one query per task for the owner
+const tasks = await db.tasks.findMany();
+for (const task of tasks) {
+  task.owner = await db.users.findUnique({ where: { id: task.ownerId } });
+}
+
+// GOOD: Single query with join/include
+const tasks = await db.tasks.findMany({
+  include: { owner: true },
+});
+```
+
+#### Unbounded Data Fetching
+
+```typescript
+// BAD: Fetching all records
+const allTasks = await db.tasks.findMany();
+
+// GOOD: Paginated with limits
+const tasks = await db.tasks.findMany({
+  take: 20,
+  skip: (page - 1) * 20,
+  orderBy: { createdAt: 'desc' },
+});
+```
+
+#### Missing Image Optimization (Frontend)
+
+```html
+<!-- BAD: No dimensions, no format optimization -->
+<img src="/hero.jpg" />
+
+<!-- GOOD: Hero / LCP image — art direction + resolution switching, high priority -->
+<!--
+  Two techniques combined:
+  - Art direction (media): different crop/composition per breakpoint
+  - Resolution switching (srcset + sizes): right file size per screen density
+-->
+<picture>
+  <!-- Mobile: portrait crop (8:10) -->
+  <source
+    media="(max-width: 767px)"
+    srcset="/hero-mobile-400.avif 400w, /hero-mobile-800.avif 800w"
+    sizes="100vw"
+    width="800"
+    height="1000"
+    type="image/avif"
+  />
+  <source
+    media="(max-width: 767px)"
+    srcset="/hero-mobile-400.webp 400w, /hero-mobile-800.webp 800w"
+    sizes="100vw"
+    width="800"
+    height="1000"
+    type="image/webp"
+  />
+  <!-- Desktop: landscape crop (2:1) -->
+  <source
+    srcset="/hero-800.avif 800w, /hero-1200.avif 1200w, /hero-1600.avif 1600w"
+    sizes="(max-width: 1200px) 100vw, 1200px"
+    width="1200"
+    height="600"
+    type="image/avif"
+  />
+  <source
+    srcset="/hero-800.webp 800w, /hero-1200.webp 1200w, /hero-1600.webp 1600w"
+    sizes="(max-width: 1200px) 100vw, 1200px"
+    width="1200"
+    height="600"
+    type="image/webp"
+  />
+  <img
+    src="/hero-desktop.jpg"
+    width="1200"
+    height="600"
+    fetchpriority="high"
+    alt="Hero image description"
+  />
+</picture>
+
+<!-- GOOD: Below-the-fold image — lazy loaded + async decoding -->
+<img
+  src="/content.webp"
+  width="800"
+  height="400"
+  loading="lazy"
+  decoding="async"
+  alt="Content image description"
+/>
+```
+
+#### Unnecessary Re-renders (React)
+
+```tsx
+// BAD: Creates new object on every render, causing children to re-render
+function TaskList() {
+  return <TaskFilters options={{ sortBy: 'date', order: 'desc' }} />;
+}
+
+// GOOD: Stable reference
+const DEFAULT_OPTIONS = { sortBy: 'date', order: 'desc' } as const;
+function TaskList() {
+  return <TaskFilters options={DEFAULT_OPTIONS} />;
+}
+
+// Use React.memo for expensive components
+const TaskItem = React.memo(function TaskItem({ task }: Props) {
+  return <div>{/* expensive render */}</div>;
+});
+
+// Use useMemo for expensive computations
+function TaskStats({ tasks }: Props) {
+  const stats = useMemo(() => calculateStats(tasks), [tasks]);
+  return <div>{stats.completed} / {stats.total}</div>;
+}
+```
+
+#### Large Bundle Size
+
+```typescript
+// Modern bundlers (Vite, webpack 5+) handle named imports with tree-shaking automatically,
+// provided the dependency ships ESM and is marked `sideEffects: false` in package.json.
+// Profile before changing import styles — the real gains come from splitting and lazy loading.
+
+// GOOD: Dynamic import for heavy, rarely-used features
+const ChartLibrary = lazy(() => import('./ChartLibrary'));
+
+// GOOD: Route-level code splitting wrapped in Suspense
+const SettingsPage = lazy(() => import('./pages/Settings'));
+
+function App() {
+  return (
+    <Suspense fallback={<Spinner />}>
+      <SettingsPage />
+    </Suspense>
+  );
+}
+```
+
+#### Missing Caching (Backend)
+
+```typescript
+// Cache frequently-read, rarely-changed data
+const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+let cachedConfig: AppConfig | null = null;
+let cacheExpiry = 0;
+
+async function getAppConfig(): Promise<AppConfig> {
+  if (cachedConfig && Date.now() < cacheExpiry) {
+    return cachedConfig;
+  }
+  cachedConfig = await db.config.findFirst();
+  cacheExpiry = Date.now() + CACHE_TTL;
+  return cachedConfig;
+}
+
+// HTTP caching headers for static assets
+app.use('/static', express.static('public', {
+  maxAge: '1y',           // Cache for 1 year
+  immutable: true,        // Never revalidate (use content hashing in filenames)
+}));
+
+// Cache-Control for API responses
+res.set('Cache-Control', 'public, max-age=300'); // 5 minutes
+```
+
+## Performance Budget
+
+Set budgets and enforce them:
+
+```
+JavaScript bundle: < 200KB gzipped (initial load)
+CSS: < 50KB gzipped
+Images: < 200KB per image (above the fold)
+Fonts: < 100KB total
+API response time: < 200ms (p95)
+Time to Interactive: < 3.5s on 4G
+Lighthouse Performance score: ≥ 90
+```
+
+**Enforce in CI:**
+```bash
+# Bundle size check
+npx bundlesize --config bundlesize.config.json
+
+# Lighthouse CI
+npx lhci autorun
+```
+
+## See Also
+
+For detailed performance checklists, optimization commands, and anti-pattern reference, see `references/performance-checklist.md`.
+
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "We'll optimize later" | Performance debt compounds. Fix obvious anti-patterns now, defer micro-optimizations. |
+| "It's fast on my machine" | Your machine isn't the user's. Profile on representative hardware and networks. |
+| "This optimization is obvious" | If you didn't measure, you don't know. Profile first. |
+| "Users won't notice 100ms" | Research shows 100ms delays impact conversion rates. Users notice more than you think. |
+| "The framework handles performance" | Frameworks prevent some issues but can't fix N+1 queries or oversized bundles. |
+
+## Red Flags
+
+- Optimization without profiling data to justify it
+- N+1 query patterns in data fetching
+- List endpoints without pagination
+- Images without dimensions, lazy loading, or responsive sizes
+- Bundle size growing without review
+- No performance monitoring in production
+- `React.memo` and `useMemo` everywhere (overusing is as bad as underusing)
+
+## Verification
+
+After any performance-related change:
+
+- [ ] Before and after measurements exist (specific numbers)
+- [ ] The specific bottleneck is identified and addressed
+- [ ] Core Web Vitals are within "Good" thresholds
+- [ ] Bundle size hasn't increased significantly
+- [ ] No N+1 queries in new data fetching code
+- [ ] Performance budget passes in CI (if configured)
+- [ ] Existing tests still pass (optimization didn't break behavior)

package/vendor/packages/toolkit/src/content/skills/performance-optimization/meta.yaml

@@ -0,0 +1,20 @@
+kind: skill
+name: performance-optimization
+title: 性能优化
+description: 优化应用性能。适用于存在性能要求、怀疑出现回归，或需要改善 Core Web Vitals 与加载时间时；也适用于已经通过 profiling 找到瓶颈并需要定向修复的场景。
+tier: recommended
+audience: advanced
+stability: stable
+suggests:
+  - skill:verification-before-completion
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: agent-skills
+  strategy: adapted
+  origin_name: performance-optimization
+  origin_path: skills/performance-optimization/SKILL.md
+  origin_id: skill:performance-optimization
+  notes: 基于上游性能优化能力中文化整理。

package/vendor/packages/toolkit/src/content/skills/planning-and-task-breakdown/body.md

@@ -0,0 +1,48 @@
+# 规划与任务拆解
+
+## 何时使用
+
+- 已有规格，需要拆成可执行单元
+- 任务太大、太模糊或依赖顺序不明显
+- 需要并行推进多个切片
+- 需要向人类清楚表达范围、风险和检查点
+
+不适用于单文件且边界显而易见的小改动。
+
+## 输入前提
+
+- 已有规格，或至少有清楚的问题定义
+- 已读相关代码并识别主要约束
+- 愿意在规划阶段保持只读，不边做边改
+
+## 执行步骤
+
+1. 进入只读分析模式，先看规格和现有代码
+2. 识别依赖图，确定哪些必须先做
+3. 优先做纵向切片，而不是按数据库、API、UI 横向分层
+4. 为每个任务写清：
+   - 描述
+   - Acceptance criteria
+   - Verification
+   - Dependencies
+   - Files likely touched
+5. 排出顺序，并设置阶段性检查点
+
+## 成功标准
+
+- 每个任务都能独立实现、测试和验证
+- 任务粒度足够小，不会一次触碰过多文件
+- 依赖顺序和可并行项是显式的
+- 人类看完计划后能明确判断“方案对不对”
+
+## 相关原则
+
+- 计划服务实现，不是形式化文档
+- 先控制复杂度，再讨论并行度
+- 任务必须能验证，不能只写动作名
+
+## 与其他技能的衔接
+
+- 接在 `spec-driven-development` 之后
+- 计划确认后交给 `incremental-implementation`
+- 涉及方案争议时，可搭配 `multi-perspective-review`

package/vendor/packages/toolkit/src/content/skills/planning-and-task-breakdown/meta.yaml

@@ -0,0 +1,20 @@
+kind: skill
+name: planning-and-task-breakdown
+title: 任务拆解
+description: 将工作拆解为有序任务。适用于已经有规格或清晰需求、需要拆成可实现任务的场景；也适用于任务过大难以下手、需要估算范围或可以并行推进的情况。
+tier: core
+audience: default
+stability: stable
+suggests:
+  - skill:engineering-principles
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: agent-skills
+  strategy: adapted
+  origin_name: planning-and-task-breakdown
+  origin_path: skills/planning-and-task-breakdown/SKILL.md
+  origin_id: skill:planning-and-task-breakdown
+  notes: 基于上游 planning workflow，并增加上下文窗口与并行拆解约束

package/vendor/packages/toolkit/src/content/skills/release-documentation-sync/body.md

@@ -0,0 +1,54 @@
+# 发布后文档同步
+
+## 何时使用
+
+- 版本、功能或配置已经发布，需要确认长期文档没有落后于真实状态时
+- 发布说明已经写完，但还需要逐项核对 README、安装说明和行为变更记录时
+- 发布后发现用户或内部同事仍按旧路径操作，需要做 drift closure 时
+
+## 输入前提
+
+- 代码和发布动作已经完成，当前重点是收尾而不是重新设计方案
+- 已知本次发布影响了哪些入口、配置、默认行为或升级路径
+- 相关 owner 能立即修正文档，而不是把问题留到下个版本
+
+## 执行步骤
+
+1. 列出本次发布影响的同步对象，只保留长期会被消费的文档：
+   - README、quick start、首次成功路径
+   - 安装、升级、回滚或迁移说明
+   - 公共 API、CLI、配置项、默认值说明
+   - 用户可见行为变更、兼容性边界、已知限制
+2. 逐项核对这些文档是否反映真实发布状态，而不是反映开发中间态
+3. 对缺失项立即补齐，或明确记录 owner、截止时间和阻断原因
+4. 用最小验收确认收尾完成：
+   - 新用户能按文档走通最小成功路径
+   - 旧用户知道是否需要升级、迁移或回滚动作
+   - 支持、运维和后续开发不会因为旧文档误判
+5. 记录仍然存在的差异；如果差异会误导用户或运维，就把它视为未完成收尾
+
+## 成功标准
+
+- 发布后的长期文档与真实状态一致
+- 文档同步对象清晰，没有把临时说明误当成长期文档
+- 影响安装、升级、回滚或默认行为的变化都有明确说明
+- drift 没有带入下一个版本
+
+## 边界
+
+- 本 skill 只负责发布后的文档同步和 drift closure
+- 不替代 `documentation-and-adrs` 的决策记录、ADR 和长期知识沉淀
+- 不替代 `shipping-and-launch` 的发布 gate、灰度、监控和回滚策略
+- 不扩展成通用文档大全；只处理本次发布真正受影响的长期文档
+
+## 最小清单
+
+- README / quick start 已同步
+- 安装、升级、回滚说明已同步
+- 行为变更、默认值变化、兼容性边界已同步
+- 如有剩余差异，已明确 owner 和关闭时间
+
+## 与其他技能的衔接
+
+- 发布前通常先用 `shipping-and-launch`
+- 需要判断应该记录什么、哪些文档已 drift 时，回到 `documentation-and-adrs`

package/vendor/packages/toolkit/src/content/skills/release-documentation-sync/meta.yaml

@@ -0,0 +1,15 @@
+kind: skill
+name: release-documentation-sync
+title: 发布后文档同步
+description: 在发布完成后核对 README、安装升级说明、行为变更记录等长期文档是否与真实发布状态一致，避免 release 之后继续发生文档 drift。
+tier: recommended
+audience: advanced
+stability: stable
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: gstack
+  strategy: inspired
+  notes: 吸收 document-release 的发布后文档同步思路，只保留轻量收尾清单与 drift closure，不复制完整文档体系或发布 gate。

package/vendor/packages/toolkit/src/content/skills/review-response-and-resolution/body.md

@@ -0,0 +1,61 @@
+# 审查响应与问题收敛
+
+## 何时使用
+
+- 已收到 reviewer、同事或代理给出的审查意见之后
+- 一轮 review 结束，需要把问题分类并安排修复顺序时
+- 修复完成后，需要补充回归验证并回复 reviewer 时
+- 需要判断哪些意见必须立即处理，哪些可以延后时
+
+## 输入前提
+
+- 已有明确的 review 结论或问题清单
+- 已知道这次变更的规格、计划或原始目标
+- 愿意对每条反馈给出处理结果，而不是只回一句“已看”
+
+## 执行步骤
+
+1. 先把反馈分类：
+   - 阻塞合并的问题
+   - 应在本轮修复的重要问题
+   - 可延后的建议项
+   - 需要澄清或不同意的点
+2. 回到原始规格或任务，确认每条反馈是否真会影响需求、正确性、可维护性或风险边界
+3. 按顺序处理：
+   - 先修 `Critical`
+   - 再处理会影响当前发布质量的 `Important`
+   - 对 `Suggestion` 明确采纳、暂缓或拒绝，并说明原因
+4. 每完成一类修复，都补最小必要的回归验证：
+   - 受影响测试
+   - 构建或 lint
+   - 需要时补充人工验证
+5. 回复 reviewer 时逐条说明：
+   - 已修复什么
+   - 用什么验证证明成立
+   - 哪些未采纳以及理由
+6. 重新提交前确认：
+   - 没有遗留未回应的阻塞问题
+   - 新改动没有引入额外漂移
+   - 反馈闭环对外可读、可核验
+
+## 成功标准
+
+- 每条 review 意见都有明确处理状态
+- 修复顺序由风险和合并门槛驱动，而不是按回复方便程度排列
+- 回复 reviewer 时包含具体改动和验证依据
+- 延后项被显式记录，不伪装成“已处理”
+- 重新提交后，reviewer 能快速判断这一轮是否真正收敛
+
+## 相关原则
+
+- 先消除阻塞，再处理优化项
+- 不把“不同意”写成情绪表达，要写成技术理由
+- 回复必须附验证证据，不能只有态度
+- review 响应是收敛过程，不是辩论过程
+
+## 与其他技能的衔接
+
+- 通常接在 `code-review-and-quality` 之后
+- 回归验证依赖 `verification-before-completion`
+- 如果反馈暴露出规格缺口，可回到 `spec-driven-development` 或 `planning-and-task-breakdown`
+- 如果反馈聚焦安全或性能，可转给对应专项 skill 深挖

package/vendor/packages/toolkit/src/content/skills/review-response-and-resolution/meta.yaml

@@ -0,0 +1,18 @@
+kind: skill
+name: review-response-and-resolution
+title: 审查响应与问题收敛
+description: 在收到代码审查反馈后使用。负责分类意见、安排修复顺序、补充回归验证，并以可核验的方式回复 reviewer，直到问题收敛。
+tier: recommended
+audience: advanced
+stability: stable
+suggests:
+  - skill:verification-before-completion
+  - skill:engineering-principles
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: superpowers
+  strategy: inspired
+  notes: 吸收 receiving-code-review 一类方法，整理为本仓库的 review 后处理闭环；只覆盖响应、修复、回归验证和回复，不承担审查本身或分支收尾职责。

package/vendor/packages/toolkit/src/content/skills/safety-guardrails/body.md

@@ -0,0 +1,43 @@
+# 安全护栏
+
+## 何时使用
+
+- 即将执行可能破坏文件、数据库、Git 历史或配置的操作时
+- 接近生产环境、敏感数据或关键基础设施时
+- 多个代理同时改同一仓库时
+- 你不完全理解某条命令的影响时
+
+## 输入前提
+
+- 已识别当前操作的风险等级
+- 接受对高风险操作增加确认、冻结或限制
+- 目标是降低误操作，而不是完全阻塞正常开发
+
+## 执行步骤
+
+1. 先判断当前需要哪种保护模式：
+   - `Careful`：危险操作前预警
+   - `Freeze`：冻结关键文件或目录
+   - `Guard`：最高级防护，叠加更多限制
+2. 对危险命令做风险识别和替代方案提示
+3. 对关键路径加冻结规则，阻止越界修改
+4. 高风险环境开启 Guard，限制更大范围写入和执行
+5. 整个操作过程保留审计痕迹和确认记录
+
+## 成功标准
+
+- 高风险操作不会在无确认的情况下执行
+- 关键文件或目录不会被误改
+- 生产或敏感环境下的改动范围被显式限制
+- 安全模式不会妨碍普通低风险开发
+
+## 相关原则
+
+- 在真正危险的地方增加摩擦
+- 不确定时宁可先警告、先冻结
+- 可逆操作和不可逆操作应区别对待
+
+## 与其他技能的衔接
+
+- 与 `security-and-hardening` 互补：一个防漏洞，一个防误操作
+- 在 `shipping-and-launch`、迁移、数据库操作和批量改动前特别重要

package/vendor/packages/toolkit/src/content/skills/safety-guardrails/meta.yaml

@@ -0,0 +1,17 @@
+kind: skill
+name: safety-guardrails
+title: 安全护栏
+description: 在 AI 执行潜在破坏性操作时施加安全护栏。适用于生产环境、关键基础设施或敏感文件附近的工作，通过 Careful、Freeze、Guard 三种模式减少误删、危险命令和越权修改风险。
+tier: recommended
+audience: default
+stability: stable
+suggests:
+  - skill:verification-before-completion
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: toolkit-original
+  strategy: curated
+  notes: 本仓库围绕高风险操作防护整理的安全执行能力。