plan-flow-skill 1.0.0

package/rules/core/complexity-scoring.mdc

@@ -0,0 +1,235 @@
+---
+description: "Core pattern for calculating task complexity scores for implementation planning and code review"
+alwaysApply: false
+---
+
+# Complexity Scoring
+
+This document defines the scoring system for plan phases. These scores determine execution strategy and help estimate implementation effort.
+
+---
+
+## Complexity Scale
+
+| Score | Level     | Description                                | Examples                                                               |
+| ----- | --------- | ------------------------------------------ | ---------------------------------------------------------------------- |
+| 0-2   | Trivial   | Simple, mechanical changes                 | Adding a type alias, renaming a variable, adding an import             |
+| 3-4   | Low       | Straightforward implementation             | Creating a simple Zod schema, adding a basic utility function          |
+| 5-6   | Medium    | Moderate complexity, some decisions        | Creating a new component with logic hook, adding a store action        |
+| 7-8   | High      | Complex implementation, multiple concerns  | API route with command pattern, complex state management               |
+| 9-10  | Very High | Highly complex, requires careful attention | Streaming implementation, complex algorithms, multi-system integration |
+
+---
+
+## Scoring Criteria
+
+Use these modifiers to calculate the complexity score for each phase:
+
+### Positive Modifiers (Add Points)
+
+| Modifier                             | Points |
+| ------------------------------------ | ------ |
+| Each new file to create              | +1     |
+| External API integration             | +1     |
+| Database operations                  | +1     |
+| Complex state management             | +1     |
+| View/logic separation pattern        | +1     |
+| Streaming or real-time features      | +2     |
+| Complex business logic or algorithms | +2     |
+| Multi-system integration             | +2     |
+| Authentication/authorization logic   | +1     |
+| Error handling with recovery         | +1     |
+
+### Negative Modifiers (Subtract Points)
+
+| Modifier                             | Points |
+| ------------------------------------ | ------ |
+| Purely mechanical/repetitive tasks   | -1     |
+| Small modifications to existing code | -1     |
+| Following existing patterns exactly  | -1     |
+| Copy/paste with minor changes        | -1     |
+
+---
+
+## Execution Strategy Based on Scores
+
+| Total Adjacent Score | Execution Strategy                                                 |
+| -------------------- | ------------------------------------------------------------------ |
+| ≤ 6                  | **Aggregate**: Execute multiple phases together in one pass        |
+| 7-10                 | **Cautious**: Execute 1-2 phases, then verify                      |
+| > 10                 | **Sequential**: Execute one phase at a time with full verification |
+
+---
+
+## Aggregation Rules
+
+1. **Can aggregate** phases when their combined complexity ≤ 6
+2. **Never aggregate** across a phase with complexity ≥ 8
+3. **Always execute separately**: Tests phase (regardless of score)
+4. **Prefer aggregation** for trivial consecutive phases (0-2 each)
+
+---
+
+## Examples
+
+### Example 1: Aggregatable Phases (Combined ≤ 6)
+
+```markdown
+### Phase 1: Types and Schemas
+
+**Complexity**: 3/10
+
+- [ ] Create WorkflowStep type
+- [ ] Create Zod schema
+
+### Phase 2: Utility Functions
+
+**Complexity**: 2/10
+
+- [ ] Create transformation helper
+
+<!-- Combined complexity: 5 → Execute together -->
+```
+
+### Example 2: Must Execute Separately (Phase ≥ 8)
+
+```markdown
+### Phase 3: API Route with Streaming
+
+**Complexity**: 9/10
+
+- [ ] Create streaming endpoint
+- [ ] Handle SSE events
+- [ ] Implement error recovery
+
+### Phase 4: UI Components
+
+**Complexity**: 6/10
+
+- [ ] Create component with view/logic separation
+- [ ] Integrate with store
+
+<!-- Phase 3 is ≥ 8, execute separately. Phase 4 starts fresh. -->
+```
+
+### Example 3: Sequential Execution (Total > 10)
+
+```markdown
+### Phase 1: Database Schema
+
+**Complexity**: 5/10
+
+### Phase 2: Backend API
+
+**Complexity**: 7/10
+
+### Phase 3: Frontend Components
+
+**Complexity**: 6/10
+
+<!-- Adjacent totals exceed 10, execute one at a time -->
+```
+
+---
+
+## Phase Format with Complexity
+
+Every phase in a plan must include a complexity score:
+
+```markdown
+### Phase 1: [Phase Name]
+
+**Scope**: [What this phase covers]
+**Complexity**: X/10
+
+- [ ] Task 1
+- [ ] Task 2
+
+**Build Verification**: Run `npm run build`
+```
+
+---
+
+## Scoring Guidelines
+
+### When in Doubt, Score Higher
+
+If uncertain about complexity, err on the side of a higher score. It's better to execute cautiously than to rush through a complex phase.
+
+### Re-evaluate During Execution
+
+If a phase turns out to be more complex than estimated:
+
+1. Stop execution
+2. Update the complexity score in the plan
+3. Adjust execution strategy accordingly
+
+### Common Complexity Patterns
+
+| Task Type                       | Typical Score |
+| ------------------------------- | ------------- |
+| Type definitions only           | 2-3           |
+| Simple utility function         | 2-3           |
+| Zod schema creation             | 3-4           |
+| Basic React component           | 4-5           |
+| Component with view/logic split | 5-6           |
+| Zustand store actions           | 4-5           |
+| REST API route                  | 5-6           |
+| API route with command pattern  | 6-7           |
+| Database operations             | 5-7           |
+| Streaming/SSE implementation    | 8-9           |
+| Complex algorithm               | 7-9           |
+| Multi-service integration       | 8-10          |
+| Unit tests                      | 3-5           |
+| Integration tests               | 5-6           |
+
+---
+
+## Real-World Scoring Examples
+
+### Example A: Add a New Form Field
+
+**Scenario**: Add an email field to the user registration form.
+
+| Modifier | Points | Reason |
+|----------|--------|--------|
+| Modify existing component | -1 | Small modification |
+| Following existing patterns | -1 | Other fields already exist |
+| Add Zod validation | +1 | Schema update |
+| **Total** | **2/10** | Trivial |
+
+**Execution**: Can be aggregated with other trivial phases.
+
+---
+
+### Example B: Create User Dashboard API
+
+**Scenario**: Create an API endpoint that fetches user data with analytics.
+
+| Modifier | Points | Reason |
+|----------|--------|--------|
+| New file (route.ts) | +1 | Creating API route |
+| Database operations | +1 | Fetch user data |
+| External API integration | +1 | Analytics service |
+| Error handling with recovery | +1 | Handle service failures |
+| Complex business logic | +2 | Aggregate multiple data sources |
+| **Total** | **6/10** | Medium |
+
+**Execution**: Can be aggregated if adjacent phase is ≤ 0.
+
+---
+
+### Example C: Implement Real-time Chat Feature
+
+**Scenario**: Add WebSocket-based chat with message persistence.
+
+| Modifier | Points | Reason |
+|----------|--------|--------|
+| New files (3 files) | +3 | Route, hook, component |
+| Streaming/real-time | +2 | WebSocket handling |
+| Database operations | +1 | Message persistence |
+| Complex state management | +1 | Chat state with optimistic updates |
+| Multi-system integration | +2 | WebSocket + DB + Auth |
+| **Total** | **9/10** | Very High |
+
+**Execution**: Must execute separately. Never aggregate with other phases.

package/rules/core/forbidden-patterns.mdc

@@ -0,0 +1,263 @@
+---
+description: "Anti-patterns and practices to avoid in all code"
+alwaysApply: true
+---
+
+# Forbidden Patterns
+
+This file defines **anti-patterns and practices to avoid** in your project. Add patterns that your team has identified as problematic and wants the AI to avoid during code generation.
+
+---
+
+## How to Use This File
+
+1. **Add anti-patterns** that cause problems in your codebase
+2. **Show examples** of the problematic code
+3. **Explain why** each pattern is harmful
+4. **Reference the fix** in `.cursor/rules/core/allowed-patterns.mdc` when applicable
+
+---
+
+## Example Pattern Structure
+
+### DON'T: Pattern Name
+
+**Problem**: Brief description of why this is problematic.
+
+```typescript
+// BAD - Example of the anti-pattern
+const badExample = doThingWrong()
+```
+
+**Why This is Wrong**:
+
+- Reason 1
+- Reason 2
+
+**Fix**: Description of the correct approach or link to `.cursor/rules/core/allowed-patterns.mdc`.
+
+---
+
+## Example Anti-Patterns
+
+### 1. DON'T Use Magic Numbers
+
+**Problem**: Hardcoded numbers without context make code hard to understand and maintain.
+
+```typescript
+// BAD - What does 86400000 mean?
+setTimeout(cleanup, 86400000)
+
+// BAD - Why 5? What if it needs to change?
+if (retryCount > 5) {
+  throw new Error('Too many retries')
+}
+```
+
+**Why This is Wrong**:
+
+- No context for what the number represents
+- Hard to find and update when requirements change
+- Easy to introduce bugs with typos
+
+**Fix**: Use named constants with descriptive names.
+
+```typescript
+// GOOD
+const ONE_DAY_MS = 24 * 60 * 60 * 1000
+setTimeout(cleanup, ONE_DAY_MS)
+
+const MAX_RETRY_ATTEMPTS = 5
+if (retryCount > MAX_RETRY_ATTEMPTS) {
+  throw new Error('Too many retries')
+}
+```
+
+---
+
+### 2. DON'T Swallow Errors Silently
+
+**Problem**: Catching errors without handling them hides bugs and makes debugging impossible.
+
+```typescript
+// BAD - Error is completely ignored
+try {
+  await saveData(data)
+} catch (error) {
+  // Silent failure - no one knows something went wrong
+}
+
+// BAD - Generic catch that hides the real issue
+try {
+  await complexOperation()
+} catch {
+  return null
+}
+```
+
+**Why This is Wrong**:
+
+- Bugs go unnoticed until they cause bigger problems
+- Impossible to debug issues in production
+- Users don't know their action failed
+
+**Fix**: Always log errors and provide appropriate user feedback.
+
+```typescript
+// GOOD
+try {
+  await saveData(data)
+} catch (error) {
+  logger.error('Failed to save data', { error, data })
+  throw new UserFacingError('Unable to save. Please try again.')
+}
+```
+
+---
+
+### 3. DON'T Use Nested Ternaries
+
+**Problem**: Deeply nested ternary operators are hard to read and maintain.
+
+```typescript
+// BAD - Unreadable nested ternaries
+const status = isLoading ? 'loading' : hasError ? 'error' : isComplete ? 'complete' : 'idle'
+
+// BAD - Even worse with more nesting
+const message = !user ? 'Not logged in' : !user.verified ? 'Please verify' : user.isPremium ? 'Welcome back, premium user!' : 'Welcome back!'
+```
+
+**Why This is Wrong**:
+
+- Extremely hard to read and understand
+- Easy to introduce bugs when modifying
+- Difficult to add new conditions
+
+**Fix**: Use if/else statements, switch statements, or lookup objects.
+
+```typescript
+// GOOD - Clear and maintainable
+function getStatus(isLoading: boolean, hasError: boolean, isComplete: boolean) {
+  if (isLoading) return 'loading'
+  if (hasError) return 'error'
+  if (isComplete) return 'complete'
+  return 'idle'
+}
+```
+
+---
+
+### 4. DON'T Mutate Function Parameters
+
+**Problem**: Mutating parameters causes unexpected side effects and makes code unpredictable.
+
+```typescript
+// BAD - Mutating the input array
+function addItem(items: string[], newItem: string) {
+  items.push(newItem) // Modifies the original array!
+  return items
+}
+
+// BAD - Mutating object properties
+function updateUser(user: User) {
+  user.lastUpdated = new Date() // Modifies the original object!
+  return user
+}
+```
+
+**Why This is Wrong**:
+
+- Caller doesn't expect their data to change
+- Causes bugs that are hard to track down
+- Breaks immutability expectations in React/Redux
+
+**Fix**: Return new objects/arrays instead of mutating.
+
+```typescript
+// GOOD - Returns new array
+function addItem(items: string[], newItem: string) {
+  return [...items, newItem]
+}
+
+// GOOD - Returns new object
+function updateUser(user: User) {
+  return { ...user, lastUpdated: new Date() }
+}
+```
+
+---
+
+### 5. DON'T Mix Async Patterns
+
+**Problem**: Mixing callbacks, promises, and async/await makes code confusing and error-prone.
+
+```typescript
+// BAD - Mixing callbacks and promises
+function fetchData(callback) {
+  fetch('/api/data')
+    .then(res => res.json())
+    .then(data => callback(null, data))
+    .catch(err => callback(err))
+}
+
+// BAD - Mixing .then() with async/await
+async function processData() {
+  const result = await fetchData()
+  return result.then(data => transform(data)) // Mixing patterns!
+}
+```
+
+**Why This is Wrong**:
+
+- Confusing control flow
+- Error handling becomes inconsistent
+- Harder to debug and maintain
+
+**Fix**: Use async/await consistently throughout.
+
+```typescript
+// GOOD - Consistent async/await
+async function fetchData() {
+  const response = await fetch('/api/data')
+  return response.json()
+}
+
+async function processData() {
+  const data = await fetchData()
+  return transform(data)
+}
+```
+
+---
+
+## Adding Your Anti-Patterns
+
+When adding new anti-patterns to this file:
+
+1. **Start with "DON'T"** followed by the pattern name
+2. **Describe the problem** briefly
+3. **Provide BAD examples** showing the anti-pattern
+4. **Explain why it's wrong** with a bullet list
+5. **Show the fix** or reference `.cursor/rules/core/allowed-patterns.mdc`
+
+---
+
+## Template for New Anti-Patterns
+
+```markdown
+### DON'T: Pattern Name
+
+**Problem**: Brief description of why this is problematic.
+
+\`\`\`typescript
+// BAD - Example of the anti-pattern
+const badExample = problematicCode()
+\`\`\`
+
+**Why This is Wrong**:
+
+- Reason 1
+- Reason 2
+
+**Fix**: Description or link to `.cursor/rules/core/allowed-patterns.mdc`.
+```

package/rules/languages/_index.mdc

@@ -0,0 +1,80 @@
+---
+description: "Summary index for language patterns - load this to see available references"
+alwaysApply: false
+---
+
+# Languages Index
+
+## Overview
+
+Language-specific patterns and best practices. These rules apply when working with TypeScript/JavaScript or Python files respectively.
+
+**Total Files**: 2 files, ~316 lines
+**Reference Codes**: LNG-TS-1 through LNG-PY-5
+
+---
+
+## Reference Codes
+
+### TypeScript Patterns (`typescript-patterns.mdc`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| LNG-TS-1 | Type definitions (interfaces, unions, generics) | typescript-patterns.mdc | 9-50 |
+| LNG-TS-2 | Error handling and custom error types | typescript-patterns.mdc | 51-65 |
+| LNG-TS-3 | Type safety (utility types, avoid any, null safety) | typescript-patterns.mdc | 66-86 |
+| LNG-TS-4 | Advanced patterns (const assertions, type guards, immutability, satisfies) | typescript-patterns.mdc | 87-129 |
+
+### Python Patterns (`python-patterns.mdc`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| LNG-PY-1 | Style and typing (PEP 8, type hints, dataclasses) | python-patterns.mdc | 9-52 |
+| LNG-PY-2 | Code organization (modular functions, enums, context managers) | python-patterns.mdc | 53-97 |
+| LNG-PY-3 | Error handling and custom exceptions | python-patterns.mdc | 98-110 |
+| LNG-PY-4 | Async and I/O patterns | python-patterns.mdc | 111-125 |
+| LNG-PY-5 | Best practices (DI, logging, Pydantic, Pathlib) | python-patterns.mdc | 126-189 |
+
+---
+
+## When to Expand
+
+| Code | Expand When |
+|------|-------------|
+| LNG-TS-1 | Defining TypeScript interfaces or unions |
+| LNG-TS-2 | Implementing custom error classes in TS |
+| LNG-TS-3 | Need examples of utility types or null safety |
+| LNG-TS-4 | Using advanced TS features like satisfies or type guards |
+| LNG-PY-1 | Setting up Python project structure or typing |
+| LNG-PY-2 | Organizing Python modules and using enums |
+| LNG-PY-3 | Creating custom Python exceptions |
+| LNG-PY-4 | Implementing async/await in Python |
+| LNG-PY-5 | Using Pydantic, logging, or dependency injection |
+
+---
+
+## Quick Reference
+
+### TypeScript Key Points
+- **Strict mode**: Always enable `strict: true`
+- **Interfaces**: Prefer for object shapes
+- **Discriminated unions**: Model exclusive states
+- **Generics**: Reusable, type-safe components
+- **Avoid any**: Use `unknown` with type guards
+- **Immutability**: Use `readonly` and `ReadonlyArray`
+
+### Python Key Points
+- **PEP 8**: Follow naming conventions
+- **Type hints**: Add annotations for clarity
+- **Dataclasses**: Use for structured data
+- **Enums**: Replace magic strings/numbers
+- **Context managers**: Resource management
+- **Logging**: Use logger, not print
+
+---
+
+## Notes
+
+- Both files have `alwaysApply: false` - loaded based on file glob patterns
+- TypeScript patterns apply to `**/*.ts` and `**/*.tsx` files
+- Python patterns apply to `**/*.py` files