cc-devflow 4.3.0 → 4.5.0

package/.claude/skills/_reference-implementations/frontend-react-mui/resources/typescript-standards.md

@@ -1,418 +0,0 @@
-# TypeScript Standards
-
-TypeScript best practices for type safety and maintainability in React frontend code.
-
----
-
-## Strict Mode
-
-### Configuration
-
-TypeScript strict mode is **enabled** in the project:
-
-```json
-// tsconfig.json
-{
-    "compilerOptions": {
-        "strict": true,
-        "noImplicitAny": true,
-        "strictNullChecks": true
-    }
-}
-```
-
-**This means:**
-- No implicit `any` types
-- Null/undefined must be handled explicitly
-- Type safety enforced
-
----
-
-## No `any` Type
-
-### The Rule
-
-```typescript
-// ❌ NEVER use any
-function handleData(data: any) {
-    return data.something;
-}
-
-// ✅ Use specific types
-interface MyData {
-    something: string;
-}
-
-function handleData(data: MyData) {
-    return data.something;
-}
-
-// ✅ Or use unknown for truly unknown data
-function handleUnknown(data: unknown) {
-    if (typeof data === 'object' && data !== null && 'something' in data) {
-        return (data as MyData).something;
-    }
-}
-```
-
-**If you truly don't know the type:**
-- Use `unknown` (forces type checking)
-- Use type guards to narrow
-- Document why type is unknown
-
----
-
-## Explicit Return Types
-
-### Function Return Types
-
-```typescript
-// ✅ CORRECT - Explicit return type
-function getUser(id: number): Promise<User> {
-    return apiClient.get(`/users/${id}`);
-}
-
-function calculateTotal(items: Item[]): number {
-    return items.reduce((sum, item) => sum + item.price, 0);
-}
-
-// ❌ AVOID - Implicit return type (less clear)
-function getUser(id: number) {
-    return apiClient.get(`/users/${id}`);
-}
-```
-
-### Component Return Types
-
-```typescript
-// React.FC already provides return type (ReactElement)
-export const MyComponent: React.FC<Props> = ({ prop }) => {
-    return <div>{prop}</div>;
-};
-
-// For custom hooks
-function useMyData(id: number): { data: Data; isLoading: boolean } {
-    const [data, setData] = useState<Data | null>(null);
-    const [isLoading, setIsLoading] = useState(true);
-
-    return { data: data!, isLoading };
-}
-```
-
----
-
-## Type Imports
-
-### Use 'type' Keyword
-
-```typescript
-// ✅ CORRECT - Explicitly mark as type import
-import type { User } from '~types/user';
-import type { Post } from '~types/post';
-import type { SxProps, Theme } from '@mui/material';
-
-// ❌ AVOID - Mixed value and type imports
-import { User } from '~types/user';  // Unclear if type or value
-```
-
-**Benefits:**
-- Clearly separates types from values
-- Better tree-shaking
-- Prevents circular dependencies
-- TypeScript compiler optimization
-
----
-
-## Component Prop Interfaces
-
-### Interface Pattern
-
-```typescript
-/**
- * Props for MyComponent
- */
-interface MyComponentProps {
-    /** The user ID to display */
-    userId: number;
-
-    /** Optional callback when action completes */
-    onComplete?: () => void;
-
-    /** Display mode for the component */
-    mode?: 'view' | 'edit';
-
-    /** Additional CSS classes */
-    className?: string;
-}
-
-export const MyComponent: React.FC<MyComponentProps> = ({
-    userId,
-    onComplete,
-    mode = 'view',  // Default value
-    className,
-}) => {
-    return <div>...</div>;
-};
-```
-
-**Key Points:**
-- Separate interface for props
-- JSDoc comments for each prop
-- Optional props use `?`
-- Provide defaults in destructuring
-
-### Props with Children
-
-```typescript
-interface ContainerProps {
-    children: React.ReactNode;
-    title: string;
-}
-
-// React.FC automatically includes children type, but be explicit
-export const Container: React.FC<ContainerProps> = ({ children, title }) => {
-    return (
-        <div>
-            <h2>{title}</h2>
-            {children}
-        </div>
-    );
-};
-```
-
----
-
-## Utility Types
-
-### Partial<T>
-
-```typescript
-// Make all properties optional
-type UserUpdate = Partial<User>;
-
-function updateUser(id: number, updates: Partial<User>) {
-    // updates can have any subset of User properties
-}
-```
-
-### Pick<T, K>
-
-```typescript
-// Select specific properties
-type UserPreview = Pick<User, 'id' | 'name' | 'email'>;
-
-const preview: UserPreview = {
-    id: 1,
-    name: 'John',
-    email: 'john@example.com',
-    // Other User properties not allowed
-};
-```
-
-### Omit<T, K>
-
-```typescript
-// Exclude specific properties
-type UserWithoutPassword = Omit<User, 'password' | 'passwordHash'>;
-
-const publicUser: UserWithoutPassword = {
-    id: 1,
-    name: 'John',
-    email: 'john@example.com',
-    // password and passwordHash not allowed
-};
-```
-
-### Required<T>
-
-```typescript
-// Make all properties required
-type RequiredConfig = Required<Config>;  // All optional props become required
-```
-
-### Record<K, V>
-
-```typescript
-// Type-safe object/map
-const userMap: Record<string, User> = {
-    'user1': { id: 1, name: 'John' },
-    'user2': { id: 2, name: 'Jane' },
-};
-
-// For styles
-import type { SxProps, Theme } from '@mui/material';
-
-const styles: Record<string, SxProps<Theme>> = {
-    container: { p: 2 },
-    header: { mb: 1 },
-};
-```
-
----
-
-## Type Guards
-
-### Basic Type Guards
-
-```typescript
-function isUser(data: unknown): data is User {
-    return (
-        typeof data === 'object' &&
-        data !== null &&
-        'id' in data &&
-        'name' in data
-    );
-}
-
-// Usage
-if (isUser(response)) {
-    console.log(response.name);  // TypeScript knows it's User
-}
-```
-
-### Discriminated Unions
-
-```typescript
-type LoadingState =
-    | { status: 'idle' }
-    | { status: 'loading' }
-    | { status: 'success'; data: Data }
-    | { status: 'error'; error: Error };
-
-function Component({ state }: { state: LoadingState }) {
-    // TypeScript narrows type based on status
-    if (state.status === 'success') {
-        return <Display data={state.data} />;  // data available here
-    }
-
-    if (state.status === 'error') {
-        return <Error error={state.error} />;  // error available here
-    }
-
-    return <Loading />;
-}
-```
-
----
-
-## Generic Types
-
-### Generic Functions
-
-```typescript
-function getById<T>(items: T[], id: number): T | undefined {
-    return items.find(item => (item as any).id === id);
-}
-
-// Usage with type inference
-const users: User[] = [...];
-const user = getById(users, 123);  // Type: User | undefined
-```
-
-### Generic Components
-
-```typescript
-interface ListProps<T> {
-    items: T[];
-    renderItem: (item: T) => React.ReactNode;
-}
-
-export function List<T>({ items, renderItem }: ListProps<T>): React.ReactElement {
-    return (
-        <div>
-            {items.map((item, index) => (
-                <div key={index}>{renderItem(item)}</div>
-            ))}
-        </div>
-    );
-}
-
-// Usage
-<List<User>
-    items={users}
-    renderItem={(user) => <UserCard user={user} />}
-/>
-```
-
----
-
-## Type Assertions (Use Sparingly)
-
-### When to Use
-
-```typescript
-// ✅ OK - When you know more than TypeScript
-const element = document.getElementById('my-element') as HTMLInputElement;
-const value = element.value;
-
-// ✅ OK - API response that you've validated
-const response = await api.getData();
-const user = response.data as User;  // You know the shape
-```
-
-### When NOT to Use
-
-```typescript
-// ❌ AVOID - Circumventing type safety
-const data = getData() as any;  // WRONG - defeats TypeScript
-
-// ❌ AVOID - Unsafe assertion
-const value = unknownValue as string;  // Might not actually be string
-```
-
----
-
-## Null/Undefined Handling
-
-### Optional Chaining
-
-```typescript
-// ✅ CORRECT
-const name = user?.profile?.name;
-
-// Equivalent to:
-const name = user && user.profile && user.profile.name;
-```
-
-### Nullish Coalescing
-
-```typescript
-// ✅ CORRECT
-const displayName = user?.name ?? 'Anonymous';
-
-// Only uses default if null or undefined
-// (Different from || which triggers on '', 0, false)
-```
-
-### Non-Null Assertion (Use Carefully)
-
-```typescript
-// ✅ OK - When you're certain value exists
-const data = queryClient.getQueryData<Data>(['data'])!;
-
-// ⚠️ CAREFUL - Only use when you KNOW it's not null
-// Better to check explicitly:
-const data = queryClient.getQueryData<Data>(['data']);
-if (data) {
-    // Use data
-}
-```
-
----
-
-## Summary
-
-**TypeScript Checklist:**
-- ✅ Strict mode enabled
-- ✅ No `any` type (use `unknown` if needed)
-- ✅ Explicit return types on functions
-- ✅ Use `import type` for type imports
-- ✅ JSDoc comments on prop interfaces
-- ✅ Utility types (Partial, Pick, Omit, Required, Record)
-- ✅ Type guards for narrowing
-- ✅ Optional chaining and nullish coalescing
-- ❌ Avoid type assertions unless necessary
-
-**See Also:**
-- [component-patterns.md](component-patterns.md) - Component typing
-- [data-fetching.md](data-fetching.md) - API typing

package/.claude/skills/attention-refresh/SKILL.md

@@ -1,170 +0,0 @@
----
-name: flow-attention-refresh
-description: "注意力刷新协议。在关键时刻强制读取核心文档，防止目标遗忘。被 flow-dev, flow-ralph 等命令引用。"
----
-
-# Flow Attention Refresh - 注意力刷新协议
-
-## Overview
-
-解决 "Lost in the Middle" 效应：当上下文过长时，原始目标被"推出"注意力窗口。
-
-```
-问题:
-上下文开始: [原始目标 - 距离很远，被"遗忘"]
-     ↓
-... 50+ 工具调用 ...
-     ↓
-上下文末尾: [最近的工具输出 - 在注意力窗口]
-
-解决:
-在关键时刻强制读取目标文档 → 将目标"拉回"注意力窗口
-```
-
-## The Iron Law
-
-```
-BEFORE MAJOR DECISION → READ GOAL FILES → THEN ACT
-```
-
-## Refresh Protocols
-
-### Protocol 1: Flow Entry (每个 flow-* 命令开始)
-
-**触发点**: 任何 `/flow-*` 命令的 Entry Gate
-
-**动作**:
-```yaml
-read:
-  - BRAINSTORM.md "成功标准" 章节
-  - TASKS.md 当前阶段任务列表
-focus: 本次命令要达成什么？
-```
-
-**实现**: 已由现有 Brainstorm Alignment Check 覆盖
-
----
-
-### Protocol 2: Task Start (flow-dev 每个任务开始)
-
-**触发点**: `flow-dev` TDD 循环中，每个任务执行前
-
-**动作**:
-```yaml
-read:
-  - TASKS.md 当前任务 T### 段落 + DoD
-  - quickstart.md 相关命令
-focus: 这个任务的验收标准是什么？
-```
-
-**实现位置**: flow-dev.md 阶段 3 TDD 循环
-
-**代码片段**:
-```markdown
-**注意力刷新** (Protocol 2):
-→ Read: TASKS.md 当前任务 T### 段落
-→ Focus: 任务目标和 DoD
-→ Then: 开始执行任务
-```
-
----
-
-### Protocol 3: Ralph Iteration (Ralph 循环每次迭代)
-
-**触发点**: `/flow-ralph` 每次迭代开始
-
-**动作**:
-```yaml
-read:
-  - TASKS.md 第一个未完成任务
-  - ERROR_LOG.md 最近 5 条记录
-focus: 下一步行动 + 避免重复错误
-```
-
-**实现位置**: flow-ralph.md Ralph Loop 开始处
-
-**代码片段**:
-```markdown
-**注意力刷新** (Protocol 3):
-→ Read: TASKS.md 找到第一个 `- [ ]` 任务
-→ Read: ERROR_LOG.md 最近 5 条（如存在）
-→ Focus: 下一步行动是什么？有什么错误需要避免？
-→ Then: 执行任务
-```
-
----
-
-### Protocol 4: Error Recovery (遇到错误后)
-
-**触发点**: 测试失败、构建错误、运行时异常后
-
-**动作**:
-```yaml
-read:
-  - ERROR_LOG.md 当前错误记录
-  - TASKS.md 当前任务定义
-focus: 错误根因 + 解决方案
-```
-
-**实现位置**: flow-tdd skill 错误处理部分
-
-**代码片段**:
-```markdown
-**错误恢复刷新** (Protocol 4):
-→ Record: 将错误追加到 ERROR_LOG.md
-→ Read: ERROR_LOG.md 当前错误 + 历史相似错误
-→ Read: TASKS.md 当前任务
-→ Focus: 根因分析，避免盲目修复
-→ Then: 有针对性地修复
-```
-
----
-
-## Integration Map
-
-```
-现有机制:
-┌──────────────────────────────────────┐
-│ flow-brainstorming skill             │
-│ ↓ 触发于 /flow-init                  │
-│ ↓ 输出 BRAINSTORM.md                 │
-└──────────────────────────────────────┘
-              ↓
-┌──────────────────────────────────────┐
-│ Brainstorm Alignment Check           │
-│ ↓ 在每个 flow-* Entry Gate           │
-│ ↓ 读取 BRAINSTORM.md 验证对齐        │
-│ ↓ = Protocol 1                       │
-└──────────────────────────────────────┘
-
-新增机制:
-┌──────────────────────────────────────┐
-│ flow-attention-refresh skill (本文件) │
-│ ↓ 被 flow-dev, flow-ralph 引用       │
-│ ↓ 在更细粒度的时刻刷新注意力          │
-│ ↓ Protocol 2, 3, 4                   │
-└──────────────────────────────────────┘
-```
-
-## Rationalization Prevention
-
-| Excuse | Reality |
-|--------|---------|
-| "我记得目标是什么" | 上下文 50+ 工具调用后，你真的不记得了 |
-| "读文件浪费时间" | 读文件 < 1秒，返工 > 10分钟 |
-| "这个任务很简单" | 简单任务也会偏离目标 |
-| "刚刚读过了" | 每次迭代都要读，这是协议 |
-
-## Red Flags - STOP
-
-如果你发现自己：
-- 开始任务前没有读取 TASKS.md
-- 遇到错误后没有先记录 ERROR_LOG.md
-- Ralph 循环中忘记读取上次错误
-- 做决策时没有参考 BRAINSTORM.md
-
-**STOP。执行对应的 Protocol。**
-
----
-
-**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md