@zmice/zc 0.1.1 → 0.2.0

package/vendor/packages/toolkit/src/content/skills/developer-experience-audit/body.md

@@ -0,0 +1,49 @@
+# 开发者体验审计
+
+## 何时使用
+
+- 功能、CLI 或文档已经实现，需要从真实开发者视角做一次走查时
+- 发布前、合并前，确认 getting started 和安装链真的能支撑最小成功路径时
+- `multi-perspective-review` 已完成，但需要验证当时的 DevEx 假设是否在实做后仍成立时
+- onboarding、安装、配置、首次运行或错误恢复链路刚发生变更时
+
+## 输入前提
+
+- 待审计的实现已经可运行，而不是只停留在计划或伪代码
+- 已明确目标开发者是谁，以及最小成功路径是什么
+- 已有开发者会实际依赖的入口材料，例如 README、安装说明、CLI 帮助或示例命令
+
+## 执行步骤
+
+1. 先定义审计场景：目标开发者画像、运行环境、起点文档和期望的首次成功结果
+2. 按 getting started 和安装链从头执行，不跳过任何“大家都知道”的隐含前置条件
+3. 验证首次成功路径是否清晰可达，包括安装、配置、运行第一条命令以及看到预期结果
+4. 检查失败回流：当命令失败、配置缺失或依赖不满足时，错误信息和文档是否告诉开发者下一步怎么做
+5. 记录所有问题，并区分 `blocker`、`major friction`、`minor friction`，明确问题落点在代码、CLI、文档还是环境假设
+6. 输出结论和修复建议，决定是放行、修后重审，还是阻断发布/合并
+
+## 通过标准
+
+- 新开发者能靠现有入口材料完成最小成功路径
+- 安装链、配置链和首次运行链没有隐形步骤
+- 错误信息与文档足以支持失败后的回流，而不是让人猜
+- 审计结论能落成具体修复项，而不是停留在“体验一般”
+
+## 阻断标准
+
+- getting started 无法独立支撑起步，必须依赖口头知识或仓库历史
+- 安装链、配置链或首次成功路径存在实际断点
+- 失败后没有可执行的回流路径，错误信息或文档不足以指导恢复
+- 关键路径需要额外试错才能完成，且试错成本会显著拖慢新开发者
+
+## 相关原则
+
+- DevEx 不能只在计划里看起来合理，必须在实现后真实走一遍
+- 首次成功路径是最重要的开发者体验信号
+- 审计结果必须能回流成具体修复动作
+
+## 与其他技能的衔接
+
+- `multi-perspective-review` 负责实现前评审，这里负责实现后的真实实测
+- 常与 `verification-before-completion` 配合，把体验结论建立在实际运行证据上
+- 如问题落在长期说明与使用材料上，可回流到 `documentation-and-adrs`

package/vendor/packages/toolkit/src/content/skills/developer-experience-audit/meta.yaml

@@ -0,0 +1,17 @@
+kind: skill
+name: developer-experience-audit
+title: 开发者体验审计
+description: 在实现完成后，从 onboarding、安装链、首次成功路径和失败回流出发，对真实开发者体验做实测审计。适用于发布前、合并前，或怀疑 getting started 与文档不足以支撑最小成功路径时。
+tier: recommended
+audience: advanced
+stability: stable
+suggests:
+  - skill:verification-before-completion
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: gstack
+  strategy: inspired
+  notes: 吸收 gstack 中 plan-devex-review 与 devex-review 的实现后实测思路，转译为本仓库的轻量 DevEx 审计技能；不镜像其角色、目录或提示词结构。

package/vendor/packages/toolkit/src/content/skills/documentation-and-adrs/body.md

@@ -0,0 +1,61 @@
+# 文档与 ADR
+
+## 何时使用
+
+- 做了重要架构或公共接口决策时
+- 发布会影响用户行为的新功能时
+- 需要把“为什么这样做”留下来时
+- 反复出现同一类解释，适合沉淀成长期文档时
+- 实现或发布已经完成，需要判断长期文档是否发生 drift 时
+
+## 输入前提
+
+- 已有值得记录的决策、约束或经验
+- 目标是说明为什么，而不是复述代码
+- 愿意把文档当作工程产物持续维护
+
+## 执行步骤
+
+1. 判断是否需要 ADR、README 更新、接口文档或注释
+2. 记录背景、约束、候选方案、决策和后果
+3. 对公共 API 或关键流程补充可消费文档
+4. 对源码中的非显而易见陷阱补充“为什么”类注释
+5. 检查发布或实现是否让以下长期文档产生 drift：
+   - README 和 quick start
+   - 架构说明、ADR、迁移或兼容性说明
+   - 公共 API、CLI、配置项、安装说明
+   - 关键行为变更、默认值变化、已知限制
+6. 满足以下任一触发条件时，把文档同步视为显式收尾项，而不是可选备注：
+   - 用户首条成功路径变了
+   - 安装、升级、回滚步骤变了
+   - 默认行为、配置语义或兼容性边界变了
+   - 运维、支持或后续开发会因为旧文档而误判
+7. 把文档与代码一起进入版本控制；如果代码已发布，再补一次发布后同步核对
+
+## 成功标准
+
+- 重要决策有书面理由，不依赖口头记忆
+- 文档说明的是“为什么”和“怎么验证”，不是重复代码
+- 后续工程师或代理能直接消费这些记录
+- 文档与当前实现保持同步
+- 文档 drift 被显式识别，而不是在发布后被动暴露
+
+## 相关原则
+
+- 文档记录决策，不记录显而易见的代码
+- ADR 解决的是可逆成本高的长期决策
+- 最有价值的文档是帮助后人少走弯路
+- “代码完成”不等于“知识完成”，发布后 drift 也算未收尾
+
+## 与发布后文档同步的边界
+
+- 本 skill 负责判断要记录什么、为什么要更新，以及哪些长期文档已经失真
+- `release-documentation-sync` 负责发布后的同步清单、最小验收和收尾核对
+- `shipping-and-launch` 负责发布 gate，不替代长期文档沉淀和 ADR 记录
+
+## 与其他技能的衔接
+
+- 架构决策后常接 `architect`
+- 发布前常接 `shipping-and-launch`
+- 发布完成后如需做同步收尾，接 `release-documentation-sync`
+- 规格、计划和实现完成后可补最终沉淀

package/vendor/packages/toolkit/src/content/skills/documentation-and-adrs/meta.yaml

@@ -0,0 +1,21 @@
+kind: skill
+name: documentation-and-adrs
+title: 文档与 ADR
+description: 记录关键决策与长期文档。适用于架构决策、公共 API 变更、功能交付或任何未来工程师和代理需要理解的上下文沉淀。
+tier: recommended
+audience: default
+stability: stable
+suggests:
+  - skill:release-documentation-sync
+  - skill:verification-before-completion
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: agent-skills
+  strategy: adapted
+  origin_name: documentation-and-adrs
+  origin_path: skills/documentation-and-adrs/SKILL.md
+  origin_id: skill:documentation-and-adrs
+  notes: 沿用上游文档与 ADR 思路，并补充发布后文档 drift 的触发与收尾边界，对齐本仓库的长期文档结构。

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

@@ -0,0 +1,54 @@
+在进入规格、实现、审查和验证前，先用这组原则校准工作方式。它不替代具体 skill，而是作为轻量原则层，约束这些 skill 的执行风格和判断边界。
+
+## 何时使用
+
+- 任务开始时，需要先统一执行方式
+- 实现复杂度开始膨胀，出现过度设计倾向
+- 调试或重构过程中，开始偏离最初目标
+- 准备宣称完成，但缺少可验证证据
+
+## 核心原则
+
+1. 先澄清假设
+   把输入、约束、风险和未知项说清楚，再进入实现。
+
+2. 简单优先
+   先选最直接、最容易验证、最少抽象的方案。
+
+3. 外科式修改
+   只改完成目标所需的最小范围，不顺手扩散、不借题发挥。
+
+4. 目标导向
+   每一步都要能回答“这一步为什么必要，它离目标更近了什么”。
+
+5. 证据先于断言
+   结论必须建立在测试、构建、检查或运行结果上，而不是感觉。
+
+6. 发布后不允许失控漂移
+   已发布行为、文档、门禁和回归基线发生变化时，必须有明确校验与同步动作，不能默认“上线后自然会对齐”。
+
+## 原则落点
+
+| 原则 | 主要落点 |
+| --- | --- |
+| 证据先于断言 | `verification-before-completion`、`ci-cd-and-automation`、`browser-qa-testing` |
+| 复杂任务谨慎优先于求快 | `verification-before-completion`、`context-engineering` |
+| 简单优先 | `ci-cd-and-automation`、`browser-qa-testing`、`context-engineering` |
+| 外科式修改 | `ci-cd-and-automation`、`context-engineering` |
+| 目标导向 | `verification-before-completion`、`context-engineering` |
+| 发布后不允许失控漂移 | `ci-cd-and-automation` |
+
+## 执行检查清单
+
+- 我是否明确了当前目标和不做什么
+- 这次改动是否是当前问题的最小可行解
+- 是否引入了与目标无关的抽象、重命名或结构变动
+- 是否保留了足够的验证证据来支撑最终结论
+- 如果变更已发布，是否明确了发布后需要持续校验的门禁、基线或文档同步点
+
+## 与其他技能的衔接
+
+- 在 `spec-driven-development` 前使用，用来约束需求澄清方式
+- 在 `incremental-implementation` 和 `test-driven-development` 中使用，用来限制改动半径和复杂度
+- 在 `verification-before-completion` 中使用，用来提醒结论必须落到证据
+- 在 `ci-cd-and-automation`、`browser-qa-testing`、`context-engineering` 中使用，用来把原则变成可执行门禁

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

@@ -0,0 +1,18 @@
+kind: skill
+name: engineering-principles
+title: 工程原则
+description: 在进入规格、实现、审查和验证之前先校准工程行为原则，强调澄清假设、简单优先、外科式修改、目标导向和证据先于断言。
+tier: recommended
+audience: default
+stability: stable
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: andrej-karpathy-skills
+  strategy: inspired
+  origin_name: karpathy-guidelines
+  origin_path: skills/karpathy-guidelines/
+  origin_id: skill:karpathy-guidelines
+  notes: 提炼为跨技能共享的工程原则层，不直接镜像上游正文

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

@@ -0,0 +1,324 @@
+# Frontend UI Engineering
+
+## Overview
+
+Build production-quality user interfaces that are accessible, performant, and visually polished. The goal is UI that looks like it was built by a design-aware engineer at a top company — not like it was generated by an AI. This means real design system adherence, proper accessibility, thoughtful interaction patterns, and no generic "AI aesthetic."
+
+## When to Use
+
+- Building new UI components or pages
+- Modifying existing user-facing interfaces
+- Implementing responsive layouts
+- Adding interactivity or state management
+- Fixing visual or UX issues
+
+## Component Architecture
+
+### File Structure
+
+Colocate everything related to a component:
+
+```
+src/components/
+  TaskList/
+    TaskList.tsx          # Component implementation
+    TaskList.test.tsx     # Tests
+    TaskList.stories.tsx  # Storybook stories (if using)
+    use-task-list.ts      # Custom hook (if complex state)
+    types.ts              # Component-specific types (if needed)
+```
+
+### Component Patterns
+
+**Prefer composition over configuration:**
+
+```tsx
+// Good: Composable
+<Card>
+  <CardHeader>
+    <CardTitle>Tasks</CardTitle>
+  </CardHeader>
+  <CardBody>
+    <TaskList tasks={tasks} />
+  </CardBody>
+</Card>
+
+// Avoid: Over-configured
+<Card
+  title="Tasks"
+  headerVariant="large"
+  bodyPadding="md"
+  content={<TaskList tasks={tasks} />}
+/>
+```
+
+**Keep components focused:**
+
+```tsx
+// Good: Does one thing
+export function TaskItem({ task, onToggle, onDelete }: TaskItemProps) {
+  return (
+    <li className="flex items-center gap-3 p-3">
+      <Checkbox checked={task.done} onChange={() => onToggle(task.id)} />
+      <span className={task.done ? 'line-through text-muted' : ''}>{task.title}</span>
+      <Button variant="ghost" size="sm" onClick={() => onDelete(task.id)}>
+        <TrashIcon />
+      </Button>
+    </li>
+  );
+}
+```
+
+**Separate data fetching from presentation:**
+
+```tsx
+// Container: handles data
+export function TaskListContainer() {
+  const { tasks, isLoading, error } = useTasks();
+
+  if (isLoading) return <TaskListSkeleton />;
+  if (error) return <ErrorState message="Failed to load tasks" retry={refetch} />;
+  if (tasks.length === 0) return <EmptyState message="No tasks yet" />;
+
+  return <TaskList tasks={tasks} />;
+}
+
+// Presentation: handles rendering
+export function TaskList({ tasks }: { tasks: Task[] }) {
+  return (
+    <ul role="list" className="divide-y">
+      {tasks.map(task => <TaskItem key={task.id} task={task} />)}
+    </ul>
+  );
+}
+```
+
+## State Management
+
+**Choose the simplest approach that works:**
+
+```
+Local state (useState)           → Component-specific UI state
+Lifted state                     → Shared between 2-3 sibling components
+Context                          → Theme, auth, locale (read-heavy, write-rare)
+URL state (searchParams)         → Filters, pagination, shareable UI state
+Server state (React Query, SWR)  → Remote data with caching
+Global store (Zustand, Redux)    → Complex client state shared app-wide
+```
+
+**Avoid prop drilling deeper than 3 levels.** If you're passing props through components that don't use them, introduce context or restructure the component tree.
+
+## Design System Adherence
+
+### Avoid the AI Aesthetic
+
+AI-generated UI has recognizable patterns. Avoid all of them:
+
+| AI Default | Why It Is a Problem | Production Quality |
+|---|---|---|
+| Purple/indigo everything | Models default to visually "safe" palettes, making every app look identical | Use the project's actual color palette |
+| Excessive gradients | Gradients add visual noise and clash with most design systems | Flat or subtle gradients matching the design system |
+| Rounded everything (rounded-2xl) | Maximum rounding signals "friendly" but ignores the hierarchy of corner radii in real designs | Consistent border-radius from the design system |
+| Generic hero sections | Template-driven layout with no connection to the actual content or user need | Content-first layouts |
+| Lorem ipsum-style copy | Placeholder text hides layout problems that real content reveals (length, wrapping, overflow) | Realistic placeholder content |
+| Oversized padding everywhere | Equal generous padding destroys visual hierarchy and wastes screen space | Consistent spacing scale |
+| Stock card grids | Uniform grids are a layout shortcut that ignores information priority and scanning patterns | Purpose-driven layouts |
+| Shadow-heavy design | Layered shadows add depth that competes with content and slows rendering on low-end devices | Subtle or no shadows unless the design system specifies |
+
+### Spacing and Layout
+
+Use a consistent spacing scale. Don't invent values:
+
+```css
+/* Use the scale: 0.25rem increments (or whatever the project uses) */
+/* Good */  padding: 1rem;      /* 16px */
+/* Good */  gap: 0.75rem;       /* 12px */
+/* Bad */   padding: 13px;      /* Not on any scale */
+/* Bad */   margin-top: 2.3rem; /* Not on any scale */
+```
+
+### Typography
+
+Respect the type hierarchy:
+
+```
+h1 → Page title (one per page)
+h2 → Section title
+h3 → Subsection title
+body → Default text
+small → Secondary/helper text
+```
+
+Don't skip heading levels. Don't use heading styles for non-heading content.
+
+### Color
+
+- Use semantic color tokens: `text-primary`, `bg-surface`, `border-default` — not raw hex values
+- Ensure sufficient contrast (4.5:1 for normal text, 3:1 for large text)
+- Don't rely solely on color to convey information (use icons, text, or patterns too)
+
+## Accessibility (WCAG 2.1 AA)
+
+Every component must meet these standards:
+
+### Keyboard Navigation
+
+```tsx
+// Every interactive element must be keyboard accessible
+<button onClick={handleClick}>Click me</button>        // ✓ Focusable by default
+<div onClick={handleClick}>Click me</div>               // ✗ Not focusable
+<div role="button" tabIndex={0} onClick={handleClick}    // ✓ But prefer <button>
+     onKeyDown={e => (e.key === 'Enter' || e.key === ' ') && handleClick()}>
+  Click me
+</div>
+```
+
+### ARIA Labels
+
+```tsx
+// Label interactive elements that lack visible text
+<button aria-label="Close dialog"><XIcon /></button>
+
+// Label form inputs
+<label htmlFor="email">Email</label>
+<input id="email" type="email" />
+
+// Or use aria-label when no visible label exists
+<input aria-label="Search tasks" type="search" />
+```
+
+### Focus Management
+
+```tsx
+// Move focus when content changes
+function Dialog({ isOpen, onClose }: DialogProps) {
+  const closeRef = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    if (isOpen) closeRef.current?.focus();
+  }, [isOpen]);
+
+  // Trap focus inside dialog when open
+  return (
+    <dialog open={isOpen}>
+      <button ref={closeRef} onClick={onClose}>Close</button>
+      {/* dialog content */}
+    </dialog>
+  );
+}
+```
+
+### Meaningful Empty and Error States
+
+```tsx
+// Don't show blank screens
+function TaskList({ tasks }: { tasks: Task[] }) {
+  if (tasks.length === 0) {
+    return (
+      <div role="status" className="text-center py-12">
+        <TasksEmptyIcon className="mx-auto h-12 w-12 text-muted" />
+        <h3 className="mt-2 text-sm font-medium">No tasks</h3>
+        <p className="mt-1 text-sm text-muted">Get started by creating a new task.</p>
+        <Button className="mt-4" onClick={onCreateTask}>Create Task</Button>
+      </div>
+    );
+  }
+
+  return <ul role="list">...</ul>;
+}
+```
+
+## Responsive Design
+
+Design for mobile first, then expand:
+
+```tsx
+// Tailwind: mobile-first responsive
+<div className="
+  grid grid-cols-1      /* Mobile: single column */
+  sm:grid-cols-2        /* Small: 2 columns */
+  lg:grid-cols-3        /* Large: 3 columns */
+  gap-4
+">
+```
+
+Test at these breakpoints: 320px, 768px, 1024px, 1440px.
+
+## Loading and Transitions
+
+```tsx
+// Skeleton loading (not spinners for content)
+function TaskListSkeleton() {
+  return (
+    <div className="space-y-3" aria-busy="true" aria-label="Loading tasks">
+      {Array.from({ length: 3 }).map((_, i) => (
+        <div key={i} className="h-12 bg-muted animate-pulse rounded" />
+      ))}
+    </div>
+  );
+}
+
+// Optimistic updates for perceived speed
+function useToggleTask() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: toggleTask,
+    onMutate: async (taskId) => {
+      await queryClient.cancelQueries({ queryKey: ['tasks'] });
+      const previous = queryClient.getQueryData(['tasks']);
+
+      queryClient.setQueryData(['tasks'], (old: Task[]) =>
+        old.map(t => t.id === taskId ? { ...t, done: !t.done } : t)
+      );
+
+      return { previous };
+    },
+    onError: (_err, _taskId, context) => {
+      queryClient.setQueryData(['tasks'], context?.previous);
+    },
+  });
+}
+```
+
+## See Also
+
+For detailed accessibility requirements and testing tools, see `references/accessibility-checklist.md`.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "Accessibility is a nice-to-have" | It's a legal requirement in many jurisdictions and an engineering quality standard. |
+| "We'll make it responsive later" | Retrofitting responsive design is 3x harder than building it from the start. |
+| "The design isn't final, so I'll skip styling" | Use the design system defaults. Unstyled UI creates a broken first impression for reviewers. |
+| "This is just a prototype" | Prototypes become production code. Build the foundation right. |
+| "The AI aesthetic is fine for now" | It signals low quality. Use the project's actual design system from the start. |
+
+## Red Flags
+
+- Components with more than 200 lines (split them)
+- Inline styles or arbitrary pixel values
+- Missing error states, loading states, or empty states
+- No keyboard navigation testing
+- Color as the sole indicator of state (red/green without text or icons)
+- Generic "AI look" (purple gradients, oversized cards, stock layouts)
+
+## Verification
+
+After building UI:
+
+### 工程质量
+- [ ] Component renders without console errors
+- [ ] All interactive elements are keyboard accessible (Tab through the page)
+- [ ] Screen reader can convey the page’s content and structure
+- [ ] Responsive: works at 320px, 768px, 1024px, 1440px
+- [ ] Loading, error, and empty states all handled
+- [ ] Follows the project’s design system (spacing, colors, typography)
+- [ ] No accessibility warnings in dev tools or axe-core
+
+### UX 可用性自检（参考 Steve Krug "Don't Make Me Think"）
+- [ ] **Trunk Test** — 用户能否立即识别：这是什么网站？我在哪个页面？如何搜索/导航？
+- [ ] **3秒扫描** — 用户打开页面 3 秒内能否找到主要操作入口？视觉焦点是否引导到正确位置？
+- [ ] **无脑选择** — 每个点击操作是否感觉显而易见？用户是否需要思考"这个能点吗？"
+- [ ] **废话检测** — 页面上是否有大段无人阅读的文字？能否精简或移除？

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

@@ -0,0 +1,21 @@
+kind: skill
+name: frontend-ui-engineering
+title: 前端界面工程
+description: 构建生产级前端界面。适用于开发或修改用户可见界面、创建组件、实现布局、管理状态，或需要让输出具备真实产品质感而不是模板化 AI 味道时。
+tier: recommended
+audience: advanced
+stability: stable
+suggests:
+  - skill:browser-qa-testing
+  - skill:verification-before-completion
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: agent-skills
+  strategy: adapted
+  origin_name: frontend-ui-engineering
+  origin_path: skills/frontend-ui-engineering/SKILL.md
+  origin_id: skill:frontend-ui-engineering
+  notes: 基于上游前端工程能力整理，并结合本仓库的界面设计偏好。