cursor-kit-cli 1.2.0-beta → 1.2.0-beta.3

package/templates/skills/frontend-development/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/templates/skills/problem-solving/SKILL.mdc

@@ -0,0 +1,96 @@
+---
+name: Problem-Solving Techniques
+description: Apply systematic problem-solving techniques for complexity spirals (simplification cascades), innovation blocks (collision-zone thinking), recurring patterns (meta-pattern recognition), assumption constraints (inversion exercise), scale uncertainty (scale game), and dispatch when stuck. Techniques derived from Microsoft Amplifier project patterns adapted for immediate application.
+version: 2.0.0
+---
+
+# Problem-Solving Techniques
+
+Systematic approaches for different types of stuck-ness. Each technique targets specific problem patterns.
+
+## When to Use
+
+Apply when encountering:
+- **Complexity spiraling** - Multiple implementations, growing special cases, excessive branching
+- **Innovation blocks** - Conventional solutions inadequate, need breakthrough thinking
+- **Recurring patterns** - Same issue across domains, reinventing solutions
+- **Assumption constraints** - Forced into "only way", can't question premise
+- **Scale uncertainty** - Production readiness unclear, edge cases unknown
+- **General stuck-ness** - Unsure which technique applies
+
+## Quick Dispatch
+
+**Match symptom to technique:**
+
+| Stuck Symptom | Technique | Reference |
+|---------------|-----------|-----------|
+| Same thing implemented 5+ ways, growing special cases | **Simplification Cascades** | `references/simplification-cascades.md` |
+| Conventional solutions inadequate, need breakthrough | **Collision-Zone Thinking** | `references/collision-zone-thinking.md` |
+| Same issue in different places, reinventing wheels | **Meta-Pattern Recognition** | `references/meta-pattern-recognition.md` |
+| Solution feels forced, "must be done this way" | **Inversion Exercise** | `references/inversion-exercise.md` |
+| Will this work at production? Edge cases unclear? | **Scale Game** | `references/scale-game.md` |
+| Unsure which technique to use | **When Stuck** | `references/when-stuck.md` |
+
+## Core Techniques
+
+### 1. Simplification Cascades
+Find one insight eliminating multiple components. "If this is true, we don't need X, Y, Z."
+
+**Key insight:** Everything is a special case of one general pattern.
+
+**Red flag:** "Just need to add one more case..." (repeating forever)
+
+### 2. Collision-Zone Thinking
+Force unrelated concepts together to discover emergent properties. "What if we treated X like Y?"
+
+**Key insight:** Revolutionary ideas from deliberate metaphor-mixing.
+
+**Red flag:** "I've tried everything in this domain"
+
+### 3. Meta-Pattern Recognition
+Spot patterns appearing in 3+ domains to find universal principles.
+
+**Key insight:** Patterns in how patterns emerge reveal reusable abstractions.
+
+**Red flag:** "This problem is unique" (probably not)
+
+### 4. Inversion Exercise
+Flip core assumptions to reveal hidden constraints. "What if the opposite were true?"
+
+**Key insight:** Valid inversions reveal context-dependence of "rules."
+
+**Red flag:** "There's only one way to do this"
+
+### 5. Scale Game
+Test at extremes (1000x bigger/smaller, instant/year-long) to expose fundamental truths.
+
+**Key insight:** What works at one scale fails at another.
+
+**Red flag:** "Should scale fine" (without testing)
+
+## Application Process
+
+1. **Identify stuck-type** - Match symptom to technique above
+2. **Load detailed reference** - Read specific technique from `references/`
+3. **Apply systematically** - Follow technique's process
+4. **Document insights** - Record what worked/failed
+5. **Combine if needed** - Some problems need multiple techniques
+
+## Combining Techniques
+
+Powerful combinations:
+- **Simplification + Meta-pattern** - Find pattern, then simplify all instances
+- **Collision + Inversion** - Force metaphor, then invert its assumptions
+- **Scale + Simplification** - Extremes reveal what to eliminate
+- **Meta-pattern + Scale** - Universal patterns tested at extremes
+
+## References
+
+Load detailed guides as needed:
+- `references/when-stuck.md` - Dispatch flowchart and decision tree
+- `references/simplification-cascades.md` - Cascade detection and extraction
+- `references/collision-zone-thinking.md` - Metaphor collision process
+- `references/meta-pattern-recognition.md` - Pattern abstraction techniques
+- `references/inversion-exercise.md` - Assumption flipping methodology
+- `references/scale-game.md` - Extreme testing procedures
+- `references/attribution.md` - Source and adaptation notes

package/templates/skills/problem-solving/references/attribution.md

@@ -0,0 +1,69 @@
+# Problem-Solving Skills - Attribution
+
+These skills were derived from agent patterns in the Microsoft Amplifier project.
+
+## Source Repository
+
+- **Name:** Amplifier
+- **URL:** https://github.com/microsoft/amplifier
+- **Commit:** 2adb63f858e7d760e188197c8e8d4c1ef721e2a6
+- **Date:** 2025-10-10
+
+## Skills Derived from Amplifier Agents
+
+### From insight-synthesizer agent:
+- **simplification-cascades** - Finding insights that eliminate multiple components
+- **collision-zone-thinking** - Forcing unrelated concepts together for breakthroughs
+- **meta-pattern-recognition** - Spotting patterns across 3+ domains
+- **inversion-exercise** - Flipping assumptions to reveal alternatives
+- **scale-game** - Testing at extremes to expose fundamental truths
+
+### From ambiguity-guardian agent:
+- **preserving-productive-tensions** - Preserving multiple valid approaches (in architecture skill)
+
+### From knowledge-archaeologist agent:
+- **tracing-knowledge-lineages** - Understanding how ideas evolved (in research skill)
+
+### Dispatch pattern:
+- **when-stuck** - Maps stuck-symptoms to appropriate technique
+
+## What Was Adapted
+
+The Amplifier agents are specialized long-lived agents with structured JSON output. These skills extract the core problem-solving techniques and adapt them as:
+
+- **Scannable quick-reference guides** (~60-80 lines each)
+- **Symptom-based discovery** via when_to_use descriptions
+- **Immediate application** without special tooling
+- **Composable patterns** through dispatch system
+- **Progressive disclosure** via SKILL.md + references structure
+
+## Core Insight
+
+Agent capabilities are domain-agnostic patterns. Whether packaged as "amplifier agent" or "problem-solving skill", the underlying technique is the same.
+
+We extracted the techniques and made them:
+- Portable across contexts
+- Immediately applicable
+- Token-efficient through progressive disclosure
+- Discoverable through symptom-matching
+- Combinable for complex problems
+
+## License
+
+Original Amplifier project uses MIT License. These adapted skills maintain attribution and follow the same open spirit.
+
+## Adaptation Notes
+
+**Changes from original:**
+- Converted from long-lived agent to scannable reference
+- Added symptom-based dispatch system
+- Removed JSON output requirements
+- Focused on immediate application
+- Added concrete examples
+- Structured for progressive disclosure
+
+**Preserved from original:**
+- Core problem-solving techniques
+- Recognition patterns
+- Application processes
+- Fundamental insights

package/templates/skills/problem-solving/references/collision-zone-thinking.md

@@ -0,0 +1,79 @@
+# Collision-Zone Thinking
+
+Force unrelated concepts together to discover emergent properties. "What if we treated X like Y?"
+
+## Core Principle
+
+Revolutionary insights from deliberate metaphor-mixing. Treat X like Y and see what emerges.
+
+## When to Use
+
+| Symptom | Action |
+|---------|--------|
+| Stuck in conventional thinking | Force wild domain collision |
+| Solutions feel incremental | Need breakthrough, not optimization |
+| "Tried everything in this domain" | Import concepts from elsewhere |
+| Need innovation, not iteration | Deliberately mix unrelated ideas |
+
+## Quick Reference Collisions
+
+| Treat This | Like This | Discovers |
+|------------|-----------|-----------|
+| Code organization | DNA/genetics | Mutation testing, evolutionary algorithms |
+| Service architecture | Lego bricks | Composable microservices, plug-and-play |
+| Data management | Water flow | Streaming, data lakes, flow-based systems |
+| Request handling | Postal mail | Message queues, async processing |
+| Error handling | Circuit breakers | Fault isolation, graceful degradation |
+
+## Process
+
+1. **Pick two unrelated concepts** from different domains
+2. **Force combination** - "What if we treated [A] like [B]?"
+3. **Explore emergent properties** - What new capabilities appear?
+4. **Test boundaries** - Where does the metaphor break?
+5. **Extract insight** - What did we learn?
+
+## Detailed Example
+
+**Problem:** Complex distributed system with cascading failures
+
+**Collision:** "What if we treated services like electrical circuits?"
+
+**Emergent properties:**
+- Circuit breakers (disconnect on overload)
+- Fuses (one-time failure protection)
+- Ground faults (error isolation)
+- Load balancing (current distribution)
+- Voltage regulation (rate limiting)
+
+**Where it works:** Preventing cascade failures, fault isolation
+
+**Where it breaks:** Circuits don't have retry logic, healing mechanisms
+
+**Insight gained:** Failure isolation patterns from electrical engineering
+
+## Best Source Domains
+
+Rich domains for concept mining:
+- **Physics** - Forces, thermodynamics, relativity
+- **Biology** - Evolution, ecosystems, immune systems
+- **Economics** - Markets, incentives, game theory
+- **Psychology** - Cognition, behavior, motivation
+- **Architecture** - Structure, flow, space utilization
+
+## Red Flags
+
+You need collision-zone thinking when:
+- "I've tried everything in this domain"
+- Solutions feel incremental, not breakthrough
+- Stuck in conventional thinking
+- Need innovation, not optimization
+- "Standard approach isn't working"
+
+## Remember
+
+- Wild combinations often yield best insights
+- Test metaphor boundaries rigorously
+- Document even failed collisions (they teach)
+- Breakthrough > incremental improvement
+- Question: "What would [domain expert] do?"