cc-devflow 1.0.1

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

@@ -0,0 +1,418 @@
+# 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/cc-devflow-orchestrator/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: cc-devflow-orchestrator
+description: CC-DevFlow workflow router and agent recommender. Use when starting requirements, running flow commands, or asking about devflow processes.
+---
+
+# CC-DevFlow Orchestrator
+
+## Purpose
+Guide users to the correct agent/command WITHOUT duplicating their detailed standards.
+
+## Workflow Map
+
+### 🏢 项目级工作流（Project-Level, 项目初期执行一次）
+
+```
+/core-roadmap → ROADMAP.md + BACKLOG.md (产品路线图)
+/core-architecture → ARCHITECTURE.md (系统架构设计)
+/core-guidelines → frontend-guidelines.md / backend-guidelines.md (项目规范)
+/core-style → STYLE.md (设计风格指南) ⭐ 新增
+```
+
+### 📦 需求级工作流（Requirement-Level, 每个需求执行一次）
+
+```
+/flow-init → research.md + tasks.json (研究初始化)
+     ↓
+/flow-clarify → clarifications/*.md (11 维度歧义扫描, 可选) ⭐ 新增
+     ↓
+/flow-prd → PRD.md (invoke prd-writer agent)
+     ↓
+/flow-checklist → checklists/*.md (需求质量检查, 可选) ⭐ 新增
+     ↓
+/flow-tech → TECH_DESIGN.md + data-model + contracts (invoke tech-architect agent)
+     ↓
+/flow-ui → UI_PROTOTYPE.html (invoke ui-designer agent, 可选, 引用 STYLE.md) ⭐ 变更
+     ↓
+/flow-epic → EPIC.md + TASKS.md (invoke planner agent with PRD+TECH+UI)
+     ↓
+/flow-dev → TASKS.md execution (TDD order enforced, 引用 STYLE.md) ⭐ 变更
+     ↓
+/flow-qa → QA reports (invoke qa-tester + security-reviewer agents)
+     ↓
+/flow-release → PR creation + deployment
+     ↓
+/flow-verify → consistency check (invoke consistency-checker agent, 任意阶段可调用)
+```
+
+**说明**:
+- 项目级命令建立全局标准（SSOT），需求级命令引用这些标准
+- `/flow-clarify` 在 PRD 前可选执行，消除 research.md 中的歧义
+- `/flow-ui` 和 `/flow-dev` 自动加载 `devflow/STYLE.md`（如存在）
+- 项目级命令可按需执行，无严格顺序要求
+
+## Agent Delegation Guide
+
+### When User Asks About Requirements Clarification
+- **DO**: Recommend `/flow-clarify` command → invokes clarify-analyst agent
+- **DON'T**: Duplicate clarification logic (flow-clarify.md has ~128 lines)
+- **Link**: See [.claude/commands/flow-clarify.md](.claude/commands/flow-clarify.md) for details
+- **Outputs**: clarifications/[timestamp]-flow-clarify.md (澄清报告)
+- **Features**: 11-dimension scan, ≤5 prioritized questions, session recovery
+
+### When User Asks About PRD
+- **DO**: Recommend `/flow-prd` command → invokes prd-writer agent
+- **DON'T**: Duplicate PRD standards (prd-writer agent has ~300 lines)
+- **Link**: See [.claude/agents/prd-writer.md](.claude/agents/prd-writer.md) for PRD details
+- **Standards**: INVEST principles, Anti-Expansion mandate, Given-When-Then criteria
+
+### When User Asks About Requirement Quality Checklist
+- **DO**: Recommend `/flow-checklist` command → invokes checklist-agent
+- **DON'T**: Duplicate checklist standards (checklist-agent has ~180 lines)
+- **Link**: See [.claude/commands/flow-checklist.md](.claude/commands/flow-checklist.md) for details
+- **Outputs**: checklists/*.md (ux, api, security, performance, data, general)
+- **Features**: 5 quality dimensions, Anti-Example rules, 80% gate threshold
+- **Level**: Requirement-level (optional, before /flow-epic)
+
+### When User Asks About Tech Design
+- **DO**: Recommend `/flow-tech` command → invokes tech-architect agent
+- **DON'T**: Duplicate tech standards (tech-architect agent has ~516 lines)
+- **Link**: See [.claude/agents/tech-architect.md](.claude/agents/tech-architect.md) for design details
+- **Outputs**: TECH_DESIGN.md, data-model.md, contracts/, quickstart.md
+
+### When User Asks About Design Style Guide
+- **DO**: Recommend `/core-style` command → invokes style-guide-generator agent
+- **DON'T**: Duplicate style guide standards (style-guide-generator agent has ~400 lines)
+- **Link**: See [.claude/agents/style-guide-generator.md](.claude/agents/style-guide-generator.md) for details
+- **Outputs**: STYLE.md (project-level SSOT for visual consistency)
+- **Level**: Project-level (execute once per project)
+
+### When User Asks About UI Prototype
+- **DO**: Recommend `/flow-ui` command → invokes ui-designer agent
+- **DON'T**: Duplicate UI standards (ui-designer agent has ~485 lines)
+- **Link**: See [.claude/agents/ui-designer.md](.claude/agents/ui-designer.md) for UI details
+- **Features**: 80+ design masters sampling, responsive design, NO PLACEHOLDER, references STYLE.md
+
+### When User Asks About Task Planning
+- **DO**: Recommend `/flow-epic` command → invokes planner agent
+- **DON'T**: Duplicate planning logic (planner agent has ~400 lines)
+- **Link**: See [.claude/agents/planner.md](.claude/agents/planner.md) for task breakdown rules
+- **Enforces**: Phase -1 Gates (Articles VII, VIII, IX), TDD sequence
+
+### When User Asks About QA/Security
+- **DO**: Recommend `/flow-qa` command → invokes qa-tester + security-reviewer agents
+- **DON'T**: Duplicate QA standards (qa-tester agent has ~300 lines)
+- **Link**: See [.claude/agents/qa-tester.md](.claude/agents/qa-tester.md) for QA details
+
+## Phase Gates (Quick Reference Only)
+
+### Entry Gates
+- **flow-clarify Entry**: research.md 存在, phase0_complete == true
+- **flow-prd Entry**: research.md 无 TODO placeholder, phase0_complete == true (clarify 可选)
+- **flow-checklist Entry**: PRD.md 必须完成 (prd_complete == true)
+- **flow-tech Entry**: PRD.md 必须完成
+- **flow-ui Entry**: PRD.md 必须完成（可与 tech 并行）
+- **flow-epic Entry**: PRD 完成，tech/ui 推荐但可选，Checklist Gate (如存在 checklists/)
+- **flow-dev Entry**: EPIC.md + TASKS.md 存在
+- **flow-qa Entry**: development_complete == true
+
+### Exit Gates
+- **flow-init Exit**: research.md 5-level quality check
+- **flow-clarify Exit**: clarification report 完整, orchestration_status.clarify_complete == true
+- **flow-prd Exit**: PRD.md 无 placeholder, Constitution 合规
+- **flow-tech Exit**: TECH_DESIGN.md + data-model + contracts 完整
+- **flow-epic Exit**: TASKS.md TDD 顺序正确, Phase -1 Gates 通过
+- **flow-dev Exit**: 所有 TASKS 完成, 测试通过
+- **flow-qa Exit**: 无 high-severity 漏洞
+
+**For Details**: See [orchestration_status.json](devflow/requirements/REQ-XXX/orchestration_status.json) and [EXECUTION_LOG.md](devflow/requirements/REQ-XXX/EXECUTION_LOG.md)
+
+## State Machine: Status → Recommended Command
+
+Read `orchestration_status.json` to determine current phase:
+
+```yaml
+status: "initialized"
+  → Recommend: /flow-clarify (optional, clarify ambiguities)
+  → Alternative: /flow-prd (skip clarification, generate PRD directly)
+
+status: "clarify_complete" OR "clarify_skipped"
+  → Recommend: /flow-prd (generate PRD)
+
+status: "prd_complete"
+  → Recommend: /flow-tech (generate technical design)
+  → Alternative: /flow-ui (generate UI prototype, optional)
+
+status: "tech_design_complete"
+  → If UI not done: /flow-ui (optional)
+  → Else: /flow-epic (generate EPIC and TASKS)
+
+status: "epic_complete"
+  → Recommend: /flow-dev (start TDD development)
+
+status: "development_complete"
+  → Recommend: /flow-qa (quality assurance and security review)
+
+status: "qa_complete"
+  → Recommend: /flow-release (create PR and release)
+
+status: "released"
+  → Recommend: /flow-verify (final consistency check)
+```
+
+## Troubleshooting Quick Routing
+
+### Phase gate blocked?
+- **Action**: Check `orchestration_status.json` for current status
+- **Script**: Run `.claude/scripts/check-prerequisites.sh --json`
+
+### Document missing?
+- **Action**: Check which phase is incomplete
+- **Script**: Run `.claude/scripts/generate-status-report.sh`
+
+### Need detailed standards?
+- **Clarify**: See flow-clarify.md command + clarify-analyst agent
+- **PRD**: Consult prd-writer agent
+- **Tech**: Consult tech-architect agent
+- **UI**: Consult ui-designer agent
+- **Tasks**: Consult planner agent
+- **QA**: Consult qa-tester agent
+
+### Constitution violation?
+- **Real-time check**: constitution-guardian guardrail (PreToolUse hook)
+- **Batch validation**: Run `.claude/scripts/validate-constitution.sh`
+- **Reference**: See [.claude/constitution/project-constitution.md](.claude/constitution/project-constitution.md) v2.0.0
+
+### TDD order violated?
+- **Real-time check**: devflow-tdd-enforcer guardrail (PreToolUse hook)
+- **Manual check**: See TASKS.md, tests MUST be marked [x] before implementation
+
+## Auxiliary Commands
+
+### Status and Progress
+- `/flow-status` - Query requirement progress
+- `/flow-update "REQ-123" "T012"` - Update task completion
+- `/flow-restart "REQ-123" --from=epic` - Resume interrupted workflow
+
+### Upgrade and Analysis
+- `/flow-upgrade "REQ-123" --analyze` - PRD version upgrade impact analysis
+- `/flow-constitution` - Constitution management
+- `/flow-verify "REQ-123"` - Comprehensive consistency verification
+
+### Bug Fix
+- `/flow-fix "BUG-123|登录超时"` - One-shot BUG fix workflow
+- `/problem-analyzer "<issue>"` - Problem diagnosis
+
+### Code Review
+- `/code-review-high "<diff>"` - High-rigor code review
+
+## Integration with Other Skills
+
+- **devflow-tdd-enforcer**: Enforces TDD order in TASKS.md (Guardrail, blocks)
+- **constitution-guardian**: Enforces Constitution compliance (Guardrail, blocks)
+- **devflow-file-standards**: File naming and directory structure reference
+- **devflow-constitution-quick-ref**: Constitution quick reference
+
+## Design Principle
+
+**This skill does NOT contain**:
+- ❌ Detailed agent execution standards (those are in agent files)
+- ❌ Full Phase Gate validation logic (those are in flow command files)
+- ❌ Complete Constitution articles (those are in project-constitution.md)
+
+**This skill ONLY contains**:
+- ✅ Workflow routing (which command to run next)
+- ✅ Agent delegation (which agent handles what)
+- ✅ Quick reference (Phase Gates summary, not full details)
+- ✅ Links to detailed documentation
+
+**Rationale**: Avoid duplication ("不重不漏" principle). Agents and Commands own detailed standards.