cc-devflow 4.2.0 → 4.4.1

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/cc-devflow-orchestrator/SKILL.md

@@ -1,169 +0,0 @@
----
-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 command/skill without duplicating detailed implementation standards.
-
-## Workflow Map
-
-### Project-Level (run once per project)
-
-```text
-/core:roadmap      → ROADMAP.md + BACKLOG.md
-/core:architecture → ARCHITECTURE.md
-/core:guidelines   → frontend/backend guidelines
-/core:style        → STYLE.md
-```
-
-## Project-Level Harness Protocol (Long-running)
-
-For `/core:*` commands, enforce a two-session model before declaring completion:
-
-1. Initializer session
-   - establish/update `devflow/.core-harness/<command>/checklist.json`, `progress.md`, `session-handoff.md`
-   - convert high-level goal into structured acceptance checks (default all failing)
-2. Worker session(s)
-   - resume from `session-handoff.md` + `progress.md`
-   - execute one smallest deliverable per session
-   - update checklist status only after command-specific validation
-3. Completion gate
-   - completion is allowed only when checklist is fully passing and command validation gates pass
-   - never declare success from “looks complete”; require artifact evidence
-
-### Core Route Defaults
-
-- no `devflow/ROADMAP.md` → route to `/core:roadmap` (initializer first)
-- roadmap exists but architecture missing/stale → route to `/core:architecture`
-- architecture exists but guidelines missing/stale → route to `/core:guidelines`
-- style missing/stale → route to `/core:style`
-- interrupted core command → rerun same command from handoff (`/core:roadmap --resume` if supported; otherwise run command again and continue from `session-handoff.md`)
-
-### Requirement-Level Canonical Mainline (v6)
-
-```text
-/flow:init    → harness:init + harness:pack
-             → context-package.md + harness-state.json
-     ↓
-/flow:spec    → harness:plan
-             → task-manifest.json
-     ↓
-/flow:dev     → harness:dispatch / harness:resume
-             → runtime events + checkpoints + manifest status
-     ↓
-/flow:verify  → harness:verify
-             → report-card.json (quick/strict gates)
-     ↓
-/flow:release → harness:release + harness:janitor
-             → RELEASE_NOTE.md + released state
-```
-
-### Bug Workflow
-
-```text
-/flow:fix "BUG-123|描述" → 系统化调试与修复
-```
-
-### Deprecated Migrations (keep for compatibility)
-
-```text
-/flow:new       → /flow:init → /flow:spec → /flow:dev → /flow:verify → /flow:release
-/flow:clarify   → merged into /flow:spec
-/flow:checklist → merged into /flow:verify --strict
-/flow:quality   → merged into /flow:verify
-```
-
-## Routing Guide
-
-### Requirement kickoff
-- Recommend: `/flow:init "REQ-123|Title|URLs?"`
-- Then: `/flow:spec "REQ-123"`
-
-### Planning/specification questions
-- Recommend: `/flow:spec`
-- Notes: this is the unified planning stage for executable task-manifest generation.
-
-### Development execution / interrupted execution
-- Recommend: `/flow:dev "REQ-123"`
-- If interrupted/failed: `/flow:dev "REQ-123" --resume`
-
-### QA/security/release readiness
-- Recommend: `/flow:verify "REQ-123"`
-- Strict gate: `/flow:verify "REQ-123" --strict`
-
-### Release
-- Recommend: `/flow:release "REQ-123"`
-- Release is blocked when report-card overall is fail.
-
-### Code review requests
-- Recommend: `/flow:verify "REQ-123" --strict`
-- Optional deep review: `/util:code-review "<diff>"`
-
-## Phase Gates (Quick Reference)
-
-### Entry Gates
-- `flow:init`: repository and requirement id are valid.
-- `flow:spec`: `context-package.md` and `harness-state.json` exist.
-- `flow:dev`: `task-manifest.json` exists and is schema-valid.
-- `flow:verify`: task dispatch completed or at least one dispatch/resume run exists.
-- `flow:release`: `report-card.json.overall == pass`.
-
-### Exit Gates
-- `flow:init`: requirement context packaged.
-- `flow:spec`: task-manifest generated.
-- `flow:dev`: task statuses updated with runtime checkpoints/events.
-- `flow:verify`: report-card emitted (quick/strict/review sections).
-- `flow:release`: release note generated and harness state marked released.
-
-## State → Recommended Command
-
-```yaml
-no_requirement_context:
-  recommend: /flow:init
-
-initialized_or_context_packed:
-  recommend: /flow:spec
-
-manifest_exists_with_pending_or_failed:
-  recommend: /flow:dev
-  alternative: /flow:dev --resume
-
-manifest_all_passed_without_report_card:
-  recommend: /flow:verify --strict
-
-report_card_fail:
-  recommend: /flow:dev --resume
-  then: /flow:verify --strict
-
-report_card_pass:
-  recommend: /flow:release
-
-released:
-  recommend: /flow:archive (optional)
-```
-
-## Auxiliary Commands
-
-### Progress and recovery
-- `/flow:status` - query requirement progress
-- `/flow:update "REQ-123" "T012"` - update task progress
-- `/flow:restart "REQ-123" --from=dev` - recover interrupted workflow state
-
-### Upgrade and governance
-- `/flow:upgrade "REQ-123" --analyze` - PRD version impact analysis
-- `/flow:constitution` - constitution governance
-- `/flow:verify "REQ-123"` - consistency and quality verification
-
-## Design Principle
-
-This skill only does routing:
-- Which command to run next
-- Which gate blocks progress
-- Which migration path applies for deprecated commands
-- Prefer incremental convergence over one-shot generation
-- Require artifact-backed completion for long-running sessions
-
-Detailed quality standards stay in command files and workflow skills.